arcadia_cli.py

#!/usr/bin/env python3
"""
Arcadia CLI — Phase 1 POC (merged)
- pack:   build .arcpack (zip), .torrent (libtorrent), .arcmanifest
- seed:   seed a .torrent (DHT+LSD enabled) until Ctrl+C
- get:    fetch manifest (file/URL), download via torrent, verify, install, update library
- list:   show installed titles
- launch: run installed title (reads launch_rel from library, decrypt-on-launch if encrypted)
- inspect: list files inside an installed title (decrypts temporarily if encrypted)
- sign/verify: detached signatures for provenance (RSA-PSS/SHA-256)
- verify-license: verify dev-signed license (RSA-PSS/SHA-256)

New in this merge:
- Always-on local SQLite metrics:
  • Client:  ~/.arcadia/library.db  (transfer_session, transfer_progress, launch_session)
  • Dev/seeder: ~/.arcadia/dev.db   (same schema for seeding sessions)
- Progress callback writes rows during download/seed loops
- Plain logging remains unchanged (you’ll still see console progress)

Notes:
- Pure libtorrent (no external mktorrent). LSD + DHT enabled.
- Optional AES-256-GCM encryption with per-client RSA-wrapped content keys.
"""

from __future__ import annotations

import argparse
import base64
import hashlib
import json
import logging
import os
import re
import shutil
import socket
import sqlite3
import subprocess
import sys
import tempfile
import time
import urllib.request
import zipfile
from pathlib import Path
from typing import Optional, List, Tuple

from security.iam import (
    ArcadiaSecurityError,
    LicenseManager,
    ManifestSigner,
    SecurityContext,
    license_doc_from_dict,
    license_doc_to_dict,
    manifest_core_from_dict,
    manifest_signature_from_dict,
    manifest_signature_to_dict,
)
from db.library import (
    export_library_json,
    init_library_db,
    load_game as load_library_game,
    load_library as load_library_state,
    migrate_json_to_db,
    upsert_installed_title,
)

try:
    import libtorrent as lt
except Exception:
    lt = None  # type: ignore

# ------------------------------
# Logging
# ------------------------------

LOGGER = logging.getLogger("arcadia")

def setup_logging(verbosity: int) -> None:
    level = logging.INFO
    if verbosity <= -1:
        level = logging.ERROR
    elif verbosity >= 2:
        level = logging.DEBUG
    elif verbosity == 1:
        level = logging.INFO
    logging.basicConfig(
        level=level,
        format="%(asctime)s │ %(levelname)-8s │ %(name)s │ %(message)s",
        datefmt="%H:%M:%S",
    )

# ------------------------------
# Crypto helpers (AES-GCM + RSA)
# ------------------------------

from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding, rsa
from cryptography.hazmat.primitives.asymmetric import utils as asym_utils
import secrets

def _rsa_load_private(path: Path):
    return serialization.load_pem_private_key(path.read_bytes(), password=None)

def _rsa_load_public(path: Path):
    return serialization.load_pem_public_key(path.read_bytes())

def _encrypt_file_aesgcm(src: Path, dst: Path, key: bytes) -> dict:
    """Encrypt src → dst (AES-256-GCM). Returns {'nonce_b64', 'ciphertext_sha256'}."""
    nonce = secrets.token_bytes(12)
    aes = AESGCM(key)
    pt = src.read_bytes()  # P1: OK; P2: stream/chunk
    ct = aes.encrypt(nonce, pt, b"")  # includes auth tag
    dst.write_bytes(ct)
    sha = hashlib.sha256(ct).hexdigest()
    return {"nonce_b64": base64.b64encode(nonce).decode(), "ciphertext_sha256": sha}

def _decrypt_arcpack(enc_path: Path, out_zip: Path, nonce_b64: str, key: bytes) -> None:
    aes = AESGCM(key)
    nonce = base64.b64decode(nonce_b64)
    ct = enc_path.read_bytes()
    pt = aes.decrypt(nonce, ct, b"")
    out_zip.write_bytes(pt)

def _make_license(game_id: str, version: str, content_key: bytes,
                  dev_priv_pem: Path, client_pub_pem: Path) -> dict:
    """License format:
      enc_key_b64 : content_key encrypted to client (RSA-OAEP-256)
      sig_b64     : RSA-PSS over SHA256(game_id|version|enc_key)
    """
    dev_priv = _rsa_load_private(dev_priv_pem)
    cli_pub = _rsa_load_public(client_pub_pem)

    enc_key = cli_pub.encrypt(
        content_key,
        padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
                     algorithm=hashes.SHA256(), label=None)
    )
    sep = b"|"
    h = hashlib.sha256()
    h.update(game_id.encode()); h.update(sep); h.update(version.encode()); h.update(sep); h.update(enc_key)
    digest = h.digest()
    sig = dev_priv.sign(
        digest,
        padding.PSS(mgf=padding.MGF1(hashes.SHA256()),
                    salt_length=padding.PSS.MAX_LENGTH),
        asym_utils.Prehashed(hashes.SHA256())
    )
    return {
        "schema_version": "1",
        "alg": "RSA-OAEP-256+AES-256-GCM",
        "game_id": game_id,
        "version": version,
        "enc_key_b64": base64.b64encode(enc_key).decode(),
        "sig_b64": base64.b64encode(sig).decode(),
    }

def _decrypt_content_key(license_path: Path, dev_pubkey: Optional[Path], player_privkey: Path) -> bytes:
    """Verify (optional) dev signature, then unwrap content key with player's private key."""
    lic = json.loads(license_path.read_text())
    enc_key = base64.b64decode(lic["enc_key_b64"])
    sig = base64.b64decode(lic["sig_b64"])
    game_id, version = lic["game_id"], lic["version"]

    if dev_pubkey:
        pub = _rsa_load_public(dev_pubkey)
        sep = b"|"
        h = hashlib.sha256()
        h.update(game_id.encode()); h.update(sep); h.update(version.encode()); h.update(sep); h.update(enc_key)
        pub.verify(
            sig, h.digest(),
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()),
                        salt_length=padding.PSS.MAX_LENGTH),
            asym_utils.Prehashed(hashes.SHA256())
        )

    priv = _rsa_load_private(player_privkey)
    key = priv.decrypt(
        enc_key,
        padding.OAEP(mgf=padding.MGF1(algorithm=hashes.SHA256()),
                     algorithm=hashes.SHA256(),
                     label=None)
    )
    return key

def _is_modern_license_doc(lic: dict) -> bool:
    return "enc_key_wrapped_b64" in lic and "dev_pub_b64" in lic

def _verify_modern_manifest_license(manifest: dict, lic: dict) -> None:
    core = manifest_core_from_dict(manifest)
    sig = manifest_signature_from_dict(manifest)
    ManifestSigner.verify_manifest(core, sig)
    LicenseManager.verify_license(license_doc_from_dict(lic), sig, core=core)

def _unwrap_content_key_for_manifest(
    manifest: dict,
    license_path: Path,
    player_privkey: Path,
    legacy_dev_pubkey: Optional[Path] = None,
) -> bytes:
    lic = json.loads(license_path.read_text())
    if _is_modern_license_doc(lic):
        core = manifest_core_from_dict(manifest)
        sig = manifest_signature_from_dict(manifest)
        ManifestSigner.verify_manifest(core, sig)
        return LicenseManager.verify_and_unwrap(
            license_doc_from_dict(lic),
            sig,
            player_privkey.read_bytes(),
            core=core,
        )
    return _decrypt_content_key(license_path, legacy_dev_pubkey, player_privkey)

# ------------------------------
# General helpers (hashing, IO, URLs)
# ------------------------------

def _round_piece_len(n: int) -> int:
    # Keep it power-of-two-ish later; for now clamp
    return max(16 * 1024, min(4 * 1024 * 1024, int(n)))

def _compute_sha256(path: Path) -> Tuple[str, int]:
    h = hashlib.sha256()
    size = 0
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(1024 * 1024), b""):
            size += len(chunk)
            h.update(chunk)
    return h.hexdigest(), size

def _sha1_to_hex(h) -> str:
    try:
        return h.to_bytes().hex()
    except Exception:
        pass
    try:
        s = h.to_string()
        if isinstance(s, (bytes, bytearray)):
            return bytes(s).hex()
        if isinstance(s, str) and len(s) == 40 and all(c in "0123456789abcdefABCDEF" for c in s):
            return s.lower()
    except Exception:
        pass
    return ""

def _is_url(s: str) -> bool:
    return s.startswith("http://") or s.startswith("https://")

def _read_text_from_uri(uri: str) -> str:
    if _is_url(uri):
        with urllib.request.urlopen(uri) as r:
            return r.read().decode("utf-8")
    return Path(uri).read_text()

def create_arcpack(input_path: Path, out_dir: Path, pack_basename: str) -> Tuple[Path, Optional[str]]:
    """Build an .arcpack ZIP. If input_path is a file, return (path, arcname)."""
    out_dir.mkdir(parents=True, exist_ok=True)
    arcpack_path = out_dir / f"{pack_basename}.arcpack"

    if input_path.is_file():
        arcname = input_path.name
        with zipfile.ZipFile(arcpack_path, "w", zipfile.ZIP_DEFLATED) as z:
            z.write(input_path, arcname)
        return arcpack_path, arcname

    with zipfile.ZipFile(arcpack_path, "w", zipfile.ZIP_DEFLATED) as z:
        for root, _, files in os.walk(input_path):
            files.sort()
            for fn in files:
                p = Path(root) / fn
                z.write(p, p.relative_to(input_path).as_posix())
    return arcpack_path, None

# ------------------------------
# DB (always-on, local SQLite)
# ------------------------------

def _db_path(role: str) -> Path:
    """
    role: 'dev' for seeder-side metrics, 'client' for player-side metrics.
    Env overrides:
      ARCADIA_DEV_DB     (defaults: ~/.arcadia/dev.db)
      ARCADIA_CLIENT_DB  (defaults: ~/.arcadia/library.db)
    """
    if role == "dev":
        return Path(os.environ.get("ARCADIA_DEV_DB", str(Path.home()/".arcadia"/"dev.db"))).expanduser()
    return Path(os.environ.get("ARCADIA_CLIENT_DB", str(Path.home()/".arcadia"/"library.db"))).expanduser()

_DDL = """
PRAGMA journal_mode=WAL;
PRAGMA foreign_keys=ON;

CREATE TABLE IF NOT EXISTS transfer_session (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  role          TEXT NOT NULL,             -- 'client' | 'seeder'
  game_id       TEXT NOT NULL,
  version       TEXT NOT NULL,
  infohash      TEXT,
  size_bytes    INTEGER,
  started_utc   TEXT NOT NULL,
  completed_utc TEXT,
  result        TEXT,                      -- 'ok' | 'timeout' | 'error' | 'cancel'
  error_msg     TEXT
);

CREATE TABLE IF NOT EXISTS transfer_progress (
  sess_id       INTEGER NOT NULL REFERENCES transfer_session(id) ON DELETE CASCADE,
  ts_utc        TEXT NOT NULL,
  peers         INTEGER,
  down_bps      INTEGER,
  up_bps        INTEGER,
  progress_pct  REAL
);

CREATE INDEX IF NOT EXISTS idx_tp_sess ON transfer_progress(sess_id, ts_utc);

CREATE TABLE IF NOT EXISTS launch_session (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  game_id       TEXT NOT NULL,
  version       TEXT NOT NULL,
  encrypted     INTEGER NOT NULL,
  started_utc   TEXT NOT NULL,
  completed_utc TEXT,
  exit_code     INTEGER,
  result        TEXT,                      -- 'ok' | 'verify-fail' | 'spawn-fail' | 'error'
  error_msg     TEXT
);
"""

def _db_init(dbp: Path) -> None:
    dbp.parent.mkdir(parents=True, exist_ok=True)
    with sqlite3.connect(dbp) as cx:
        cx.executescript(_DDL)
        cx.commit()

def _utc() -> str:
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

def _tx(dbp: Path):
    """Autocommit connection for quick inserts/updates."""
    return sqlite3.connect(dbp, isolation_level=None)

def _infer_id_ver_from_name(name: str) -> tuple[str, str]:
    """
    Best-effort: 'game42-1.0.0.arcpack' or 'game42-1.0.0.arcpack.enc' -> ('game42','1.0.0')
    """
    stem = name
    for suf in (".arcpack.enc", ".arcpack", ".zip", ".bin"):
        if stem.endswith(suf):
            stem = stem[: -len(suf)]
            break
    i = stem.rfind("-")
    if i <= 0:
        return stem, "0"
    return stem[:i], stem[i+1:]

# ------------------------------
# Libtorrent helpers (create & download)
# ------------------------------

from urllib.parse import quote as _urlquote

def create_torrent_with_libtorrent(
    payload: Path, trackers: List[str], piece_len_bytes: int, private: bool
) -> Tuple[bytes, str, str]:
    """Return (bencoded .torrent bytes, infohash_hex_v1, magnet_uri)."""
    if lt is None:
        raise RuntimeError("libtorrent not available")

    fs = lt.file_storage()
    fs.add_file(payload.name, payload.stat().st_size)

    try:
        flags = lt.create_torrent_flags.v1_only
    except Exception:
        flags = 0

    try:
        ct = lt.create_torrent(fs, piece_size=piece_len_bytes, flags=flags)
    except TypeError:
        ct = lt.create_torrent(fs, piece_len_bytes)

    for tr in trackers or []:
        try:
            ct.add_tracker(tr)
        except Exception:
            LOGGER.debug("[pack] failed to add tracker %s", tr)

    if private:
        try:
            ct.set_priv(True)
        except Exception:
            pass

    lt.set_piece_hashes(ct, str(payload.parent))
    tor = ct.generate()
    data = lt.bencode(tor)

    ti = lt.torrent_info(tor)
    ih_hex = ""
    try:
        ih_hex = _sha1_to_hex(ti.info_hashes().v1)  # libtorrent 2.x
    except Exception:
        try:
            ih_hex = _sha1_to_hex(ti.info_hash())    # libtorrent 1.2.x
        except Exception:
            ih_hex = ""

    try:
        magnet = lt.make_magnet_uri(ti)
    except Exception:
        magnet = f"magnet:?xt=urn:btih:{ih_hex}&dn={_urlquote(payload.name)}"
        for tr in trackers or []:
            magnet += f"&tr={_urlquote(tr)}"

    return data, ih_hex, magnet

class DownloadResult:
    def __init__(self, path: Path, bytes_written: int, elapsed_s: float):
        self.path = path
        self.bytes_written = bytes_written
        self.elapsed_s = elapsed_s

class TransportTimeoutError(TimeoutError):
    def __init__(self, reason: str):
        super().__init__(f"download timeout: {reason}")
        self.reason = reason

class TransportDiagnostics:
    def __init__(
        self,
        source: str,
        save_dir: Path,
        listen_port: int,
        timeout_s: int,
        peers: Optional[List[Tuple[str, int]]] = None,
    ):
        self.started_utc = _utc()
        self.completed_utc = ""
        self.source = source
        self.source_kind = "magnet" if source.startswith("magnet:") else "infohash"
        self.save_dir = str(save_dir)
        self.listen_port = int(listen_port)
        self.timeout_s = int(timeout_s or 0)
        self.direct_peers = [f"{ip}:{port}" for ip, port in (peers or [])]
        self.session = {
            "dht": True,
            "lsd": True,
            "upnp": False,
            "natpmp": False,
            "dht_routers": [],
        }
        self.events: list[dict] = []
        self.alerts: list[str] = []
        self.samples: list[dict] = []
        self.max_peers = 0
        self.max_progress_pct = 0.0
        self.max_total_done = 0
        self.first_peer_elapsed_s: Optional[float] = None
        self.first_progress_elapsed_s: Optional[float] = None
        self.last_progress_elapsed_s: Optional[float] = None
        self.result = "running"
        self.failure_reason = ""
        self.error_msg = ""
        self.output_path = ""
        self.bytes_written = 0
        self.elapsed_s = 0.0

    def event(self, kind: str, message: str, **fields) -> None:
        item = {"ts_utc": _utc(), "kind": kind, "message": message}
        if fields:
            item.update(fields)
        self.events.append(item)

    def add_alert(self, message: str) -> None:
        if len(self.alerts) < 80:
            self.alerts.append(message)

    def observe(self, status, elapsed_s: float) -> None:
        sample = _transport_status_snapshot(status, elapsed_s)
        self.samples.append(sample)
        if len(self.samples) > 240:
            self.samples = self.samples[-240:]

        peers = int(sample.get("peers") or 0)
        progress_pct = float(sample.get("progress_pct") or 0.0)
        total_done = int(sample.get("total_done") or 0)
        old_max_progress = self.max_progress_pct
        old_max_total_done = self.max_total_done
        self.max_peers = max(self.max_peers, peers)
        self.max_progress_pct = max(self.max_progress_pct, progress_pct)
        self.max_total_done = max(self.max_total_done, total_done)

        if peers > 0 and self.first_peer_elapsed_s is None:
            self.first_peer_elapsed_s = round(elapsed_s, 2)
        if progress_pct > 0 and self.first_progress_elapsed_s is None:
            self.first_progress_elapsed_s = round(elapsed_s, 2)
        if progress_pct > old_max_progress or total_done > old_max_total_done:
            self.last_progress_elapsed_s = round(elapsed_s, 2)

    def finish(
        self,
        result: str,
        elapsed_s: float,
        failure_reason: str = "",
        error_msg: str = "",
        output_path: str = "",
        bytes_written: int = 0,
    ) -> None:
        self.completed_utc = _utc()
        self.result = result
        self.elapsed_s = round(float(elapsed_s), 3)
        self.failure_reason = failure_reason
        self.error_msg = error_msg
        self.output_path = output_path
        self.bytes_written = int(bytes_written or 0)

    def to_dict(self) -> dict:
        return {
            "started_utc": self.started_utc,
            "completed_utc": self.completed_utc,
            "result": self.result,
            "failure_reason": self.failure_reason,
            "error_msg": self.error_msg,
            "elapsed_s": self.elapsed_s,
            "source_kind": self.source_kind,
            "source": self.source,
            "save_dir": self.save_dir,
            "listen_port": self.listen_port,
            "timeout_s": self.timeout_s,
            "direct_peers": self.direct_peers,
            "session": self.session,
            "summary": {
                "max_peers": self.max_peers,
                "max_progress_pct": round(self.max_progress_pct, 3),
                "max_total_done": self.max_total_done,
                "first_peer_elapsed_s": self.first_peer_elapsed_s,
                "first_progress_elapsed_s": self.first_progress_elapsed_s,
                "last_progress_elapsed_s": self.last_progress_elapsed_s,
                "sample_count": len(self.samples),
                "alert_count": len(self.alerts),
            },
            "output_path": self.output_path,
            "bytes_written": self.bytes_written,
            "events": self.events,
            "alerts": self.alerts,
            "samples": self.samples,
        }

def _safe_status_value(status, name: str, default=None):
    try:
        value = getattr(status, name)
        if callable(value):
            return value()
        return value
    except Exception:
        return default

def _transport_status_snapshot(status, elapsed_s: float) -> dict:
    progress = float(_safe_status_value(status, "progress", 0.0) or 0.0)
    state = _safe_status_value(status, "state", "")
    return {
        "elapsed_s": round(float(elapsed_s), 2),
        "peers": int(_safe_status_value(status, "num_peers", 0) or 0),
        "down_bps": int(_safe_status_value(status, "download_rate", 0) or 0),
        "up_bps": int(_safe_status_value(status, "upload_rate", 0) or 0),
        "progress_pct": round(progress * 100.0, 3),
        "total_done": int(_safe_status_value(status, "total_done", 0) or 0),
        "is_seeding": bool(_safe_status_value(status, "is_seeding", False)),
        "has_metadata": bool(_safe_status_value(status, "has_metadata", False)),
        "state": str(state),
    }

def _collect_libtorrent_alerts(session, diagnostics: Optional[TransportDiagnostics]) -> None:
    if diagnostics is None or not hasattr(session, "pop_alerts"):
        return
    try:
        for alert in session.pop_alerts():
            diagnostics.add_alert(str(alert))
    except Exception:
        pass

def _classify_transport_timeout(diagnostics: Optional[TransportDiagnostics]) -> str:
    if diagnostics is None:
        return "timeout"
    if not diagnostics.samples:
        return "no-status-samples"
    if diagnostics.source_kind == "magnet" and not any(s.get("has_metadata") for s in diagnostics.samples):
        return "metadata-timeout"
    if diagnostics.max_peers <= 0:
        return "no-peers"
    if diagnostics.max_total_done <= 0 and diagnostics.max_progress_pct <= 0:
        return "connected-no-progress"
    return "stalled"

def _write_transport_diagnostics(path: Optional[str], diagnostics: Optional[TransportDiagnostics]) -> None:
    if not path or diagnostics is None:
        return
    out = Path(path).expanduser()
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text(json.dumps(diagnostics.to_dict(), indent=2), encoding="utf-8")

def _last_transport_elapsed(diagnostics: Optional[TransportDiagnostics]) -> float:
    if diagnostics and diagnostics.samples:
        return float(diagnostics.samples[-1].get("elapsed_s") or 0.0)
    return 0.0

def _download_with_libtorrent(
    magnet_or_info: str,
    save_dir: Path,
    listen_port: int,
    timeout_s: int = 0,
    peers: Optional[List[Tuple[str, int]]] = None,
    progress_cb=None,   # NEW: DB progress hook
    diagnostics: Optional[TransportDiagnostics] = None,
) -> DownloadResult:
    if lt is None:
        raise RuntimeError("libtorrent not available")
    save_dir.mkdir(parents=True, exist_ok=True)

    # Session: DHT + LSD, no UPnP/NAT-PMP for simplicity
    try:
        sp = lt.settings_pack()
        sp.set_str(lt.settings_pack.listen_interfaces, f"0.0.0.0:{listen_port}")
        sp.set_bool(lt.settings_pack.enable_upnp, False)
        sp.set_bool(lt.settings_pack.enable_natpmp, False)
        sp.set_bool(lt.settings_pack.enable_lsd, True)
        sp.set_bool(lt.settings_pack.enable_dht, True)
        ses = lt.session(sp)
        if diagnostics:
            diagnostics.event("session", "created settings_pack session", listen_port=listen_port)
        try:
            for router in ("router.bittorrent.com", "router.utorrent.com", "dht.transmissionbt.com"):
                ses.add_dht_router(router, 6881)
                if diagnostics:
                    diagnostics.session["dht_routers"].append(f"{router}:6881")
            ses.start_dht()
            if diagnostics:
                diagnostics.event("dht", "started DHT")
        except Exception as e:
            if diagnostics:
                diagnostics.event("dht", "failed to start DHT", error=str(e))
    except Exception:
        ses = lt.session()
        if diagnostics:
            diagnostics.event("session", "created fallback session", listen_port=listen_port)
        try:
            ses.listen_on(listen_port, listen_port)
            if diagnostics:
                diagnostics.event("listen", "bound fallback listen port", listen_port=listen_port)
        except Exception as e:
            if diagnostics:
                diagnostics.event("listen", "failed to bind fallback listen port", listen_port=listen_port, error=str(e))

    params = lt.add_torrent_params()
    if magnet_or_info.startswith("magnet:"):
        params = lt.parse_magnet_uri(magnet_or_info)
        if diagnostics:
            diagnostics.event("torrent", "parsed magnet URI")
    else:
        params.info_hash = magnet_or_info  # expecting 40-hex btih
        if diagnostics:
            diagnostics.event("torrent", "using infohash", infohash=magnet_or_info)
    params.save_path = str(save_dir)

    if peers:
        try:
            params.peers = [(ip, int(port)) for (ip, port) in peers]
            if diagnostics:
                diagnostics.event("peers", "added direct peers", peers=[f"{ip}:{port}" for ip, port in peers])
        except Exception as e:
            if diagnostics:
                diagnostics.event("peers", "failed to add direct peers", error=str(e))

    h = ses.add_torrent(params)
    if diagnostics:
        diagnostics.event("torrent", "added torrent to session")

    start = time.time()
    last_log = 0.0
    while True:
        s = h.status()
        elapsed = time.time() - start
        if diagnostics:
            diagnostics.observe(s, elapsed)
            try:
                if hasattr(h, "has_metadata") and h.has_metadata():
                    diagnostics.samples[-1]["has_metadata"] = True
            except Exception:
                pass
            _collect_libtorrent_alerts(ses, diagnostics)
        if s.is_seeding:
            break
        if timeout_s and elapsed > timeout_s:
            reason = _classify_transport_timeout(diagnostics)
            if diagnostics:
                diagnostics.finish("timeout", elapsed, failure_reason=reason, error_msg=f"download timeout: {reason}")
            raise TransportTimeoutError(reason)
        now = time.time()
        if now - last_log > 1.0:
            last_log = now
            LOGGER.info("[get] peers=%d down=%.1f kB/s prog=%.1f%%",
                        s.num_peers, s.download_rate/1024.0, s.progress*100)
            if progress_cb:
                try:
                    progress_cb(s)
                except Exception:
                    pass
        time.sleep(0.25)

    ti = h.get_torrent_info()
    if ti.num_files() == 1:
        out_path = save_dir / ti.files().file_path(0)
    else:
        out_path = save_dir / ti.name()
    result = DownloadResult(out_path, h.status().total_done, time.time() - start)
    if diagnostics:
        diagnostics.finish("ok", result.elapsed_s, output_path=str(out_path), bytes_written=result.bytes_written)
    return result

# ------------------------------
# Executable discovery helpers
# ------------------------------

def _is_probably_executable(p: Path) -> bool:
    if not p.is_file():
        return False
    if os.name == "nt":
        return p.suffix.lower() in (".exe", ".bat", ".cmd")
    try:
        st = p.stat().st_mode
        if st & 0o111:
            return True
        with p.open("rb") as f:
            head = f.read(4)
        return head.startswith(b"#!") or head.startswith(b"\x7fELF")
    except Exception:
        return False

def _discover_executable(run_dir: Path, preferred_names: list[str]) -> Optional[Path]:
    candidates: list[Path] = []
    try:
        for root, _, files in os.walk(run_dir):
            files.sort()
            for fn in files:
                p = Path(root) / fn
                if _is_probably_executable(p):
                    candidates.append(p)
    except Exception:
        return None

    if not candidates:
        return None

    lowers = [n.lower() for n in preferred_names if n]
    for p in candidates:
        if p.name.lower() in lowers:
            return p
    for p in candidates:
        if any(n in p.name.lower() for n in lowers):
            return p
    return candidates[0]

# ------------------------------
# Handlers: pack & seed
# ------------------------------

def handle_pack(args: argparse.Namespace) -> int:
    LOGGER.info("[pack] name=%s id=%s ver=%s platform=%s", args.name, args.id, args.version, args.platform)
    input_path = Path(args.input_dir).expanduser().resolve()
    out_dir = Path(args.out_dir).expanduser().resolve()
    if not input_path.exists():
        LOGGER.error("[pack] input path not found: %s", input_path)
        return 2

    pack_basename = f"{args.id}-{args.version}"
    LOGGER.info("[pack] creating arcpack → %s", out_dir / f"{pack_basename}.arcpack")
    arcpack_path, single_arcname = create_arcpack(input_path, out_dir, pack_basename)

    with zipfile.ZipFile(arcpack_path, "r") as z:
        if len(z.namelist()) == 0:
            LOGGER.error("[pack] empty archive; aborting.")
            try: arcpack_path.unlink()
            except Exception: pass
            return 2

    plaintext_sha256, _ = _compute_sha256(arcpack_path)

    # Choose payload (plain vs encrypted)
    if args.encrypt:
        content_key = secrets.token_bytes(32)
        enc_path = arcpack_path.with_suffix(".arcpack.enc")
        enc_meta = _encrypt_file_aesgcm(arcpack_path, enc_path, content_key)
        torrent_payload = enc_path
        content_sha256 = enc_meta["ciphertext_sha256"]
        nonce_b64 = enc_meta["nonce_b64"]
    else:
        torrent_payload = arcpack_path
        content_sha256 = plaintext_sha256
        nonce_b64 = ""

    size_bytes = torrent_payload.stat().st_size

    # Create torrent
    magnet = ""
    infohash = ""
    if not args.no_torrent:
        if lt is None:
            LOGGER.error("[pack] libtorrent not available; cannot create torrent")
            return 3
        data, ih_hex, magnet = create_torrent_with_libtorrent(
            torrent_payload, args.tracker or [], _round_piece_len(512 * 1024), args.private
        )
        infohash = ih_hex
        (out_dir / f"{pack_basename}.torrent").write_bytes(data)
        LOGGER.info("[pack] wrote torrent → %s", out_dir / f"{pack_basename}.torrent")
        LOGGER.debug("[pack] infohash=%s magnet=%s", ih_hex, magnet)

    # Infer launch_rel if not provided
    inferred_launch = args.launch_rel or args.id
    if not args.launch_rel:
        if single_arcname is not None:
            inferred_launch = single_arcname
        else:
            try:
                execs = []
                for root, _, files in os.walk(input_path):
                    for fn in files:
                        p = Path(root) / fn
                        if _is_probably_executable(p):
                            execs.append(p.relative_to(input_path).as_posix())
                execs.sort()
                if execs:
                    inferred_launch = execs[0]
                    LOGGER.info("[pack] inferred launch_rel: %s", inferred_launch)
            except Exception:
                pass

    # Write manifest
    manifest = {
        "schema_version": "2",
        "game_id": args.id,
        "name": args.name,
        "version": args.version,
        "platforms": [args.platform],
        "size_bytes": size_bytes,
        "content_sha256": content_sha256,
        "payload_sha256": content_sha256,
        "plaintext_sha256": plaintext_sha256,
        "torrent": ({"magnet": magnet, "infohash": infohash} if magnet else {}),
        "launch": inferred_launch,
        "encryption": {
            "enabled": bool(args.encrypt),
            "alg": "AES-256-GCM" if args.encrypt else "",
            "nonce_b64": nonce_b64,
        },
        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
    }
    if getattr(args, "dev_ed25519", None):
        sig = SecurityContext().sign_manifest(
            manifest_core_from_dict(manifest),
            Path(args.dev_ed25519).expanduser().read_bytes(),
        )
        manifest["signature"] = manifest_signature_to_dict(sig)
        manifest["developer"] = {
            "key_alg": "ed25519",
            "dev_pub_b64": sig.dev_pub_b64,
        }
    manifest_path = out_dir / f"{pack_basename}.arcmanifest"
    manifest_path.write_text(json.dumps(manifest, indent=2))
    LOGGER.info("[pack] wrote manifest → %s", manifest_path)

    # Optional per-client license
    if args.encrypt and getattr(args, "dev_ed25519", None) and args.client_pubkey:
        lic_doc = SecurityContext().issue_license(
            args.id,
            args.version,
            content_key,
            Path(args.dev_ed25519).expanduser().read_bytes(),
            Path(args.client_pubkey).expanduser().read_bytes(),
        )
        lic = license_doc_to_dict(lic_doc)
        lic_path = out_dir / f"{pack_basename}.license.json"
        lic_path.write_text(json.dumps(lic, indent=2))
        LOGGER.info("[pack] wrote license → %s", lic_path)
    elif args.encrypt and args.dev_privkey and args.client_pubkey:
        lic = _make_license(args.id, args.version, content_key, Path(args.dev_privkey), Path(args.client_pubkey))
        lic_path = out_dir / f"{pack_basename}.license.json"
        lic_path.write_text(json.dumps(lic, indent=2))
        LOGGER.info("[pack] wrote license → %s", lic_path)

    if args.print_magnet and magnet:
        print(magnet)
    return 0

def handle_seed(args: argparse.Namespace) -> int:
    if lt is None:
        LOGGER.error("libtorrent is required for `seed`.")
        return 2

    torrent_path = Path(args.torrent).expanduser().resolve()
    content_dir = Path(args.content_dir).expanduser().resolve()
    if not torrent_path.exists():
        LOGGER.error("[seed] .torrent not found: %s", torrent_path)
        return 2
    if not content_dir.exists():
        LOGGER.error("[seed] content dir not found: %s", content_dir)
        return 2

    # Session: DHT + LSD, no UPnP/NAT-PMP
    try:
        sp = lt.settings_pack()
        sp.set_str(lt.settings_pack.listen_interfaces, f"0.0.0.0:{args.listen_port}")
        sp.set_bool(lt.settings_pack.enable_upnp, False)
        sp.set_bool(lt.settings_pack.enable_natpmp, False)
        sp.set_bool(lt.settings_pack.enable_lsd, True)
        sp.set_bool(lt.settings_pack.enable_dht, True)
        ses = lt.session(sp)
        try:
            ses.add_dht_router("router.bittorrent.com", 6881)
            ses.add_dht_router("router.utorrent.com", 6881)
            ses.add_dht_router("dht.transmissionbt.com", 6881)
            ses.start_dht()
        except Exception:
            pass
    except Exception:
        ses = lt.session()
        try:
            ses.listen_on(args.listen_port, args.listen_port)
        except Exception:
            pass

    ti = lt.torrent_info(str(torrent_path))
    params = lt.add_torrent_params()
    params.ti = ti
    params.save_path = str(content_dir)
    try:
        params.flags |= lt.torrent_flags.seed_mode
    except Exception:
        pass

    # --- DB: open dev/seeder session ---
    name_inside = ti.name()
    _seed_game_id, _seed_version = _infer_id_ver_from_name(name_inside)
    _dev_db = _db_path("dev")
    _db_init(_dev_db)
    with _tx(_dev_db) as cx:
        cur = cx.execute(
            "INSERT INTO transfer_session(role,game_id,version,infohash,size_bytes,started_utc) VALUES(?,?,?,?,?,?)",
            ("seeder", _seed_game_id, _seed_version,
             getattr(ti, "info_hash", lambda: "")() if hasattr(ti, "info_hash") else "",
             int(getattr(ti, "total_size", lambda: 0)()), _utc())
        )
        _seed_sess_id = cur.lastrowid

    h = ses.add_torrent(params)
    LOGGER.info("[seed] Seeding %s on %s (Ctrl+C to stop)", ti.name(), args.listen_port)

    last = 0.0
    try:
        while True:
            s = h.status()
            now = time.time()
            if now - last > 1.0:
                last = now
                LOGGER.info("[seed] peers=%d up=%.1f kB/s", s.num_peers, s.upload_rate/1024.0)
                # DB progress row
                try:
                    with _tx(_dev_db) as cx:
                        cx.execute(
                            "INSERT INTO transfer_progress(sess_id,ts_utc,peers,down_bps,up_bps,progress_pct) VALUES(?,?,?,?,?,?)",
                            (_seed_sess_id, _utc(), int(s.num_peers), 0, int(s.upload_rate), 100.0 if s.is_seeding else None)
                        )
                except Exception:
                    pass
            time.sleep(0.25)
    except KeyboardInterrupt:
        LOGGER.info("[seed] stopping…")
    finally:
        try:
            with _tx(_dev_db) as cx:
                cx.execute("UPDATE transfer_session SET completed_utc=?, result='ok' WHERE id=?",
                           (_utc(), _seed_sess_id))
        except Exception:
            pass
    return 0

# ------------------------------
# Handlers: get, list, launch, inspect
# ------------------------------

def handle_get(args: argparse.Namespace) -> int:
    if lt is None:
        LOGGER.error("libtorrent not available — install python bindings")
        return 2

    LOGGER.info("[get] manifest=%s install_root=%s", args.manifest, args.install_root)

    # 1) Load manifest
    try:
        raw = _read_text_from_uri(args.manifest)
        manifest = json.loads(raw)
    except Exception as e:
        LOGGER.error("[get] failed to load manifest: %s", e)
        return 2

    game_id = manifest.get("game_id") or "unknown"
    version = manifest.get("version") or "0"
    launch_rel = manifest.get("launch", game_id)
    expected_sha = (manifest.get("content_sha256") or "").lower()
    platform = (manifest.get("platforms") or ["unknown"])[0]
    enc_cfg = (manifest.get("encryption") or {})
    enc_enabled = bool(enc_cfg.get("enabled"))
    nonce_b64 = enc_cfg.get("nonce_b64") or ""

    tor = manifest.get("torrent", {})
    magnet = tor.get("magnet") or tor.get("uri") or ""
    infohash = tor.get("infohash") or ""
    if not magnet and not infohash:
        LOGGER.error("[get] manifest missing torrent magnet/infohash")
        return 2

    # --- DB: open client transfer session ---
    _client_db = _db_path("client")
    _db_init(_client_db)
    with _tx(_client_db) as cx:
        cur = cx.execute(
            "INSERT INTO transfer_session(role,game_id,version,infohash,size_bytes,started_utc) VALUES(?,?,?,?,?,?)",
            ("client", game_id, version, infohash, int(manifest.get("size_bytes") or 0), _utc())
        )
        _sess_id = cur.lastrowid

    # 2) Download via torrent
    tmp_dir = Path(args.tmp_dir).expanduser().resolve()
    tmp_dir.mkdir(parents=True, exist_ok=True)

    peer_list: Optional[List[Tuple[str, int]]] = None
    if getattr(args, "peer", None):
        peer_list = []
        for item in args.peer:
            try:
                ip, port = item.rsplit(":", 1)
                peer_list.append((ip, int(port)))
            except Exception:
                LOGGER.warning("[get] bad --peer value: %s", item)

    def _client_progress_cb(status):
        try:
            with _tx(_client_db) as cx:
                cx.execute(
                    "INSERT INTO transfer_progress(sess_id,ts_utc,peers,down_bps,up_bps,progress_pct) VALUES(?,?,?,?,?,?)",
                    (_sess_id, _utc(), int(status.num_peers), int(status.download_rate),
                     int(status.upload_rate), round(status.progress*100, 2))
                )
        except Exception:
            pass

    transport_diag = TransportDiagnostics(magnet or infohash, tmp_dir, args.listen_port, args.timeout, peer_list)

    try:
        res = _download_with_libtorrent(magnet or infohash, tmp_dir, args.listen_port, args.timeout,
                                        peers=peer_list, progress_cb=_client_progress_cb,
                                        diagnostics=transport_diag)
        _write_transport_diagnostics(getattr(args, "diagnostics_json", None), transport_diag)
    except TransportTimeoutError as e:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "timeout", f"{e.reason}: {e}", _sess_id))
        _write_transport_diagnostics(getattr(args, "diagnostics_json", None), transport_diag)
        LOGGER.error("[get] download timeout: %s", e.reason)
        return 3
    except TimeoutError as e:
        reason = _classify_transport_timeout(transport_diag)
        transport_diag.finish("timeout", _last_transport_elapsed(transport_diag), failure_reason=reason, error_msg=str(e))
        with _tx(_client_db) as cx:
            cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "timeout", f"{reason}: {e}", _sess_id))
        _write_transport_diagnostics(getattr(args, "diagnostics_json", None), transport_diag)
        LOGGER.error("[get] download timeout: %s", reason)
        return 3
    except Exception as e:
        transport_diag.finish("error", _last_transport_elapsed(transport_diag), failure_reason="transport-error", error_msg=str(e))
        with _tx(_client_db) as cx:
            cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", str(e), _sess_id))
        _write_transport_diagnostics(getattr(args, "diagnostics_json", None), transport_diag)
        LOGGER.error("[get] download failed: %s", e)
        return 3

    downloaded_path = res.path
    LOGGER.info("[get] downloaded → %s (%.2f MB in %.1fs)", downloaded_path, res.bytes_written/1e6, res.elapsed_s)

    # 3) Verify SHA-256 (fail-closed)
    if not args.no_verify and expected_sha:
        actual_sha, _ = _compute_sha256(downloaded_path)
        if actual_sha.lower() != expected_sha:
            with _tx(_client_db) as cx:
                cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                           (_utc(), "error", "SHA-256 mismatch", _sess_id))
            LOGGER.error("[get] SHA-256 mismatch: expected %s got %s", expected_sha, actual_sha)
            transport_diag.event("verify", "payload SHA-256 mismatch", expected=expected_sha, actual=actual_sha)
            transport_diag.finish("hash-mismatch", res.elapsed_s, failure_reason="payload-hash-mismatch",
                                  error_msg=f"expected {expected_sha} got {actual_sha}",
                                  output_path=str(downloaded_path), bytes_written=res.bytes_written)
            _write_transport_diagnostics(getattr(args, "diagnostics_json", None), transport_diag)
            try: downloaded_path.unlink()
            except Exception: pass
            return 4

    # 4) Install
    install_root = Path(args.install_root).expanduser().resolve()
    dest = install_root / f"{game_id}-{version}"
    if dest.exists() and not args.force:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", "install path exists", _sess_id))
        LOGGER.error("[get] install path exists (use --force): %s", dest)
        return 5
    if dest.exists():
        shutil.rmtree(dest)
    dest.mkdir(parents=True, exist_ok=True)

    stored_license_path = ""
    if enc_enabled:
        # Keep ciphertext & manifest; license may be provided now or later.
        final_cipher = dest / f"{game_id}-{version}.arcpack.enc"
        shutil.move(str(downloaded_path), str(final_cipher))
        (dest / "manifest.json").write_text(json.dumps(manifest, indent=2))

        if getattr(args, "license", None):
            lic_src = Path(args.license).expanduser()
            if lic_src.exists():
                lic_dst = dest / f"{game_id}-{version}.license.json"
                shutil.copy2(str(lic_src), str(lic_dst))
                stored_license_path = str(lic_dst)
                LOGGER.info("[get] stored license → %s", lic_dst)

        LOGGER.info("[get] encrypted install complete → %s", dest)
    else:
        try:
            with zipfile.ZipFile(downloaded_path, "r") as z:
                z.extractall(dest)
        except Exception as e:
            with _tx(_client_db) as cx:
                cx.execute("UPDATE transfer_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                           (_utc(), "error", f"extract failed: {e}", _sess_id))
            LOGGER.error("[get] extract failed: %s", e)
            return 6
        LOGGER.info("[get] extracted → %s", dest)

    # 5) Update library (JSON)
    library_path = Path(args.library).expanduser()
    library_path.parent.mkdir(parents=True, exist_ok=True)
    lib = {"games": {}}
    if library_path.exists():
        try:
            lib = json.loads(library_path.read_text()) or lib
        except Exception:
            pass

    game_meta = {
        "name": manifest.get("name", game_id),
        "version": version,
        "install_path": str(dest),
        "manifest_sha256": hashlib.sha256(raw.encode()).hexdigest(),
        "content_sha256": expected_sha,
        "payload_sha256": manifest.get("payload_sha256", expected_sha),
        "plaintext_sha256": manifest.get("plaintext_sha256", ""),
        "platform": platform,
        "added_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
        "launch_rel": launch_rel,
        "encryption": {
            "enabled": enc_enabled,
            "nonce_b64": nonce_b64 if enc_enabled else "",
            "cipher_path": str(dest / f"{game_id}-{version}.arcpack.enc") if enc_enabled else "",
            "license_basename": f"{game_id}-{version}.license.json" if enc_enabled else "",
        },
    }
    lib.setdefault("games", {})[game_id] = game_meta
    library_path.write_text(json.dumps(lib, indent=2))
    try:
        upsert_installed_title(
            _client_db,
            game_id,
            game_meta,
            manifest=manifest,
            raw_manifest=raw,
            source_manifest_uri=args.manifest,
            license_path=stored_license_path,
        )
        export_library_json(_client_db, library_path)
    except Exception as e:
        LOGGER.debug("[get] SQLite library update skipped: %s", e)

    with _tx(_client_db) as cx:
        cx.execute("UPDATE transfer_session SET completed_utc=?, result='ok' WHERE id=?",
                   (_utc(), _sess_id))

    LOGGER.info("[get] installed %s %s → %s", game_id, version, dest)
    return 0

def handle_list(args: argparse.Namespace) -> int:
    lib_path = Path(args.library).expanduser()
    try:
        data = load_library_state(_db_path("client"), lib_path)
    except Exception as e:
        LOGGER.error("[list] failed to read library: %s", e)
        return 2

    games = data.get("games", {})
    if args.json:
        print(json.dumps(games, indent=2))
        return 0
    if not games:
        print("(no titles installed)")
        return 0

    print(f"{'ID':20} {'Version':10} {'Platform':12} Install Path")
    print("-" * 80)
    for gid, meta in games.items():
        print(f"{gid:20} {meta.get('version',''):10} {meta.get('platform',''):12} {meta.get('install_path','')}")
    return 0

def handle_migrate_library(args: argparse.Namespace) -> int:
    library_path = Path(args.library).expanduser()
    db_path = Path(args.db).expanduser() if getattr(args, "db", None) else _db_path("client")
    try:
        count = migrate_json_to_db(library_path, db_path)
        export_library_json(db_path, library_path)
    except Exception as e:
        LOGGER.error("[migrate-library] failed: %s", e)
        return 1
    print(f"Migrated {count} title(s) to {db_path}")
    return 0

def _ensure_executable(path: Path) -> None:
    if os.name != "nt" and path.exists():
        try:
            path.chmod(path.stat().st_mode | 0o111)
        except Exception:
            pass

def handle_launch(args: argparse.Namespace) -> int:
    """Launch installed title; if encrypted, decrypt-on-launch into a temp '.run' dir."""
    lib_path = Path(args.library).expanduser()
    try:
        meta = load_library_game(_db_path("client"), args.game_id, lib_path)
    except Exception as e:
        LOGGER.error("[launch] failed to read library: %s", e)
        return 2

    if not meta:
        LOGGER.error("[launch] game id not found in library: %s", args.game_id)
        return 2

    install_path = Path(meta["install_path"])
    launch_rel = meta.get("launch_rel") or args.game_id
    enc_meta = (meta.get("encryption") or {})
    is_encrypted = bool(enc_meta.get("enabled"))

    # --- DB: open launch session (client db) ---
    _client_db = _db_path("client")
    _db_init(_client_db)
    with _tx(_client_db) as cx:
        cur = cx.execute(
            "INSERT INTO launch_session(game_id,version,encrypted,started_utc) VALUES(?,?,?,?)",
            (args.game_id, meta.get("version","0"), 1 if is_encrypted else 0, _utc())
        )
        _launch_id = cur.lastrowid

    # Plain: just run
    if not is_encrypted:
        exe_path = (install_path / launch_rel).resolve()
        if not exe_path.exists():
            with _tx(_client_db) as cx:
                cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                           (_utc(), "error", f"exe missing: {exe_path}", _launch_id))
            LOGGER.error("[launch] executable not found: %s", exe_path)
            return 2
        _ensure_executable(exe_path)
        cmd = [str(exe_path)] + (args.game_args or [])
        LOGGER.info("[launch] exec: %s", " ".join(cmd))
        try:
            proc = subprocess.Popen(cmd, cwd=str(install_path))
            proc.wait()
            rc = proc.returncode or 0
            with _tx(_client_db) as cx:
                cx.execute("UPDATE launch_session SET completed_utc=?, exit_code=?, result='ok' WHERE id=?",
                           (_utc(), rc, _launch_id))
            return rc
        except Exception as e:
            with _tx(_client_db) as cx:
                cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                           (_utc(), "spawn-fail", str(e), _launch_id))
            LOGGER.error("[launch] failed to spawn: %s", e)
            return 1

    # Encrypted flow
    cipher_path = Path(enc_meta.get("cipher_path") or "")
    nonce_b64 = enc_meta.get("nonce_b64") or ""
    lic_basename = enc_meta.get("license_basename") or ""
    man_path = install_path / "manifest.json"

    if not cipher_path.exists():
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", f"cipher missing: {cipher_path}", _launch_id))
        LOGGER.error("[launch] encrypted title: cipher file missing at %s", cipher_path)
        return 2
    if not man_path.exists():
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", f"manifest missing: {man_path}", _launch_id))
        LOGGER.error("[launch] encrypted title: manifest.json missing at %s", man_path)
        return 2
    try:
        manifest = json.loads(man_path.read_text())
    except Exception as e:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", f"manifest unreadable: {e}", _launch_id))
        LOGGER.error("[launch] encrypted title: manifest.json unreadable: %s", e)
        return 2

    # resolve license file
    lic_path = Path(args.license).expanduser() if getattr(args, "license", None) else (install_path / lic_basename)
    if not lic_path.exists():
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", "license not found", _launch_id))
        LOGGER.error("[launch] encrypted title: license not found (use --license)")
        return 2
    if not getattr(args, "key", None):
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", "player --key not provided", _launch_id))
        LOGGER.error("[launch] encrypted title: provide --key <player_private.pem>")
        return 2

    try:
        content_key = _unwrap_content_key_for_manifest(
            manifest,
            lic_path,
            Path(args.key).expanduser(),
            Path(args.dev_pubkey).expanduser() if getattr(args, "dev_pubkey", None) else None,
        )
    except Exception as e:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "verify-fail", str(e), _launch_id))
        LOGGER.error("[launch] license/unwrap verification failed: %s", e)
        return 2

    # decrypt into .run and launch
    run_dir = install_path / ".run"
    if run_dir.exists():
        shutil.rmtree(run_dir)
    run_dir.mkdir(parents=True, exist_ok=True)

    tmp_zip = run_dir / ".decrypted.arcpack"
    try:
        _decrypt_arcpack(cipher_path, tmp_zip, nonce_b64, content_key)
        plaintext_sha = (manifest.get("plaintext_sha256") or "").lower()
        if plaintext_sha:
            actual_plain_sha, _ = _compute_sha256(tmp_zip)
            if actual_plain_sha.lower() != plaintext_sha:
                raise ValueError(f"plaintext hash mismatch: expected {plaintext_sha} got {actual_plain_sha}")
        with zipfile.ZipFile(tmp_zip, "r") as z:
            z.extractall(run_dir)
    except Exception as e:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "error", f"decrypt/extract failed: {e}", _launch_id))
        LOGGER.error("[launch] decrypt/extract failed: %s", e)
        return 2
    finally:
        if not getattr(args, "keep_decrypted", False):
            try: tmp_zip.unlink()
            except Exception: pass

    exe_path = (run_dir / launch_rel).resolve()
    if not exe_path.exists():
        if not getattr(args, "no_auto_discover", False):
            preferred = [os.path.basename(launch_rel or ""), args.game_id]
            guess = _discover_executable(run_dir, preferred)
            if guess and guess.exists():
                LOGGER.info("[launch] auto-discovered executable: %s", guess)
                exe_path = guess
            else:
                LOGGER.error("[launch] executable not found at %s", exe_path)
                with _tx(_client_db) as cx:
                    cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                               (_utc(), "error", "exe not found after decrypt", _launch_id))
                return 2
        else:
            with _tx(_client_db) as cx:
                cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                           (_utc(), "error", "exe not found (no auto-discover)", _launch_id))
            LOGGER.error("[launch] executable not found after decrypt: %s", exe_path)
            return 2

    _ensure_executable(exe_path)
    cmd = [str(exe_path)] + (args.game_args or [])
    LOGGER.info("[launch] exec (decrypted sandbox): %s", " ".join(cmd))
    try:
        proc = subprocess.Popen(cmd, cwd=str(run_dir))
        proc.wait()
        rc = proc.returncode or 0
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, exit_code=?, result='ok' WHERE id=?",
                       (_utc(), rc, _launch_id))
    except Exception as e:
        with _tx(_client_db) as cx:
            cx.execute("UPDATE launch_session SET completed_utc=?, result=?, error_msg=? WHERE id=?",
                       (_utc(), "spawn-fail", str(e), _launch_id))
        LOGGER.error("[launch] failed to spawn: %s", e)
        return 1
    finally:
        if not getattr(args, "keep_decrypted", False):
            try: shutil.rmtree(run_dir)
            except Exception: pass

    return rc

def handle_inspect(args: argparse.Namespace) -> int:
    lib_path = Path(args.library).expanduser()
    meta = load_library_game(_db_path("client"), args.game_id, lib_path)
    if not meta:
        LOGGER.error("[inspect] game id not in library: %s", args.game_id)
        return 2
    enc = (meta.get("encryption") or {})
    if not enc.get("enabled"):
        base = Path(meta["install_path"])
        for p in sorted(base.rglob("*")):
            if p.is_file():
                print(p.relative_to(base).as_posix())
        return 0

    if not args.key:
        LOGGER.error("[inspect] encrypted title requires --key to list contents")
        return 2

    install = Path(meta["install_path"])
    cipher = Path(enc.get("cipher_path") or "")
    nonce_b64 = enc.get("nonce_b64") or ""
    man_path = install / "manifest.json"
    lic_path = install / (enc.get("license_basename") or "")
    if not (cipher.exists() and man_path.exists() and lic_path.exists()):
        LOGGER.error("[inspect] missing cipher/manifest/license")
        return 2
    try:
        manifest = json.loads(man_path.read_text())
    except Exception as e:
        LOGGER.error("[inspect] manifest unreadable: %s", e)
        return 2

    # unwrap key
    try:
        content_key = _unwrap_content_key_for_manifest(manifest, lic_path, Path(args.key).expanduser())
    except Exception as e:
        LOGGER.error("[inspect] unwrap failed: %s", e)
        return 2

    tmp_zip = Path(tempfile.mkstemp(prefix="arcadia_inspect_", suffix=".zip")[1])
    try:
        _decrypt_arcpack(cipher, tmp_zip, nonce_b64, content_key)
        plaintext_sha = (manifest.get("plaintext_sha256") or "").lower()
        if plaintext_sha:
            actual_plain_sha, _ = _compute_sha256(tmp_zip)
            if actual_plain_sha.lower() != plaintext_sha:
                raise ValueError(f"plaintext hash mismatch: expected {plaintext_sha} got {actual_plain_sha}")
        with zipfile.ZipFile(tmp_zip, "r") as z:
            for n in z.namelist():
                print(n)
    finally:
        try: tmp_zip.unlink()
        except Exception: pass
    return 0

# ------------------------------
# Detached signature helpers (optional tooling)
# ------------------------------

def _rsa_sign_bytes(priv_pem: Path, data: bytes) -> bytes:
    priv = serialization.load_pem_private_key(priv_pem.read_bytes(), password=None)
    h = hashes.Hash(hashes.SHA256()); h.update(data); digest = h.finalize()
    sig = priv.sign(
        digest,
        padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
        asym_utils.Prehashed(hashes.SHA256()),
    )
    return sig

def _rsa_verify_bytes(pub_pem: Path, data: bytes, sig: bytes) -> bool:
    pub = serialization.load_pem_public_key(pub_pem.read_bytes())
    h = hashes.Hash(hashes.SHA256()); h.update(data); digest = h.finalize()
    try:
        pub.verify(
            sig, digest,
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
            asym_utils.Prehashed(hashes.SHA256()),
        )
        return True
    except Exception:
        return False

def _read_file_bytes(p: Path) -> bytes:
    return p.read_bytes()

def handle_sign(args: argparse.Namespace) -> int:
    data = _read_file_bytes(Path(args.file).expanduser())
    sig = _rsa_sign_bytes(Path(args.key).expanduser(), data)
    if args.armor:
        out = base64.b64encode(sig).decode()
        if args.out:
            Path(args.out).write_text(out)
        else:
            print(out)
    else:
        out_path = Path(args.out) if args.out else Path(args.file + ".sig")
        out_path.write_bytes(sig)
        print(str(out_path))
    return 0

def handle_verify(args: argparse.Namespace) -> int:
    data = _read_file_bytes(Path(args.file).expanduser())
    sig_path = Path(args.signature).expanduser()
    sig = base64.b64decode(sig_path.read_text()) if args.armor else sig_path.read_bytes()
    ok = _rsa_verify_bytes(Path(args.pubkey).expanduser(), data, sig)
    print("OK" if ok else "FAIL")
    return 0 if ok else 1

def handle_verify_license(args: argparse.Namespace) -> int:
    lic = json.loads(Path(args.file).read_text())
    enc_key = base64.b64decode(lic["enc_key_b64"])
    sig = base64.b64decode(lic["sig_b64"])
    game_id, version = lic["game_id"], lic["version"]

    sep = b"|"
    h = hashlib.sha256()
    h.update(game_id.encode()); h.update(sep); h.update(version.encode()); h.update(sep); h.update(enc_key)
    digest = h.digest()

    pub = serialization.load_pem_public_key(Path(args.pubkey).read_bytes())
    try:
        pub.verify(
            sig, digest,
            padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
            asym_utils.Prehashed(hashes.SHA256()),
        )
        print("OK"); return 0
    except Exception as e:
        print(f"FAIL: {e}"); return 1

def handle_verify_chain(args: argparse.Namespace) -> int:
    try:
        manifest = json.loads(Path(args.manifest).expanduser().read_text())
        lic = json.loads(Path(args.license).expanduser().read_text())
    except Exception as e:
        LOGGER.error("[verify-chain] failed to load manifest/license: %s", e)
        return 2

    if not _is_modern_license_doc(lic):
        LOGGER.error("[verify-chain] legacy RSA license detected; use verify-license for this artifact")
        return 2

    try:
        _verify_modern_manifest_license(manifest, lic)

        payload_path = Path(args.payload).expanduser() if getattr(args, "payload", None) else None
        if payload_path:
            expected_payload_sha = (manifest.get("content_sha256") or "").lower()
            if expected_payload_sha:
                actual_payload_sha, _ = _compute_sha256(payload_path)
                if actual_payload_sha.lower() != expected_payload_sha:
                    raise ValueError(f"payload hash mismatch: expected {expected_payload_sha} got {actual_payload_sha}")

        if getattr(args, "player_key", None):
            content_key = _unwrap_content_key_for_manifest(
                manifest,
                Path(args.license).expanduser(),
                Path(args.player_key).expanduser(),
                Path(args.dev_pubkey).expanduser() if getattr(args, "dev_pubkey", None) else None,
            )
            if payload_path and (manifest.get("encryption") or {}).get("enabled"):
                plaintext_sha = (manifest.get("plaintext_sha256") or "").lower()
                if plaintext_sha:
                    tmp_zip = Path(tempfile.mkstemp(prefix="arcadia_verify_", suffix=".arcpack")[1])
                    try:
                        _decrypt_arcpack(
                            payload_path,
                            tmp_zip,
                            (manifest.get("encryption") or {}).get("nonce_b64") or "",
                            content_key,
                        )
                        actual_plain_sha, _ = _compute_sha256(tmp_zip)
                        if actual_plain_sha.lower() != plaintext_sha:
                            raise ValueError(f"plaintext hash mismatch: expected {plaintext_sha} got {actual_plain_sha}")
                    finally:
                        try: tmp_zip.unlink()
                        except Exception: pass

    except Exception as e:
        LOGGER.error("[verify-chain] FAIL: %s", e)
        return 1

    print("OK")
    return 0

# ------------------------------
# doctor (local diagnostics)
# ------------------------------

def _doctor_result(name: str, status: str, message: str, **details) -> dict:
    out = {"name": name, "status": status, "message": message}
    if details:
        out["details"] = details
    return out

def _check_writable_dir(path: Path, create: bool = True) -> tuple[bool, str]:
    try:
        if create:
            path.mkdir(parents=True, exist_ok=True)
        elif not path.exists():
            return False, "path does not exist"
        probe = path / ".arcadia_doctor_write_test"
        probe.write_text("ok", encoding="utf-8")
        probe.unlink(missing_ok=True)
        return True, "writable"
    except Exception as e:
        return False, str(e)

def _check_port_available(port: int) -> tuple[bool, str]:
    if port <= 0:
        return True, "port check skipped"
    try:
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            sock.bind(("127.0.0.1", int(port)))
        return True, "available on 127.0.0.1"
    except Exception as e:
        return False, str(e)

def handle_doctor(args: argparse.Namespace) -> int:
    results: list[dict] = []

    py_ok = sys.version_info >= (3, 9)
    results.append(_doctor_result(
        "python",
        "ok" if py_ok else "fail",
        f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
        executable=sys.executable,
    ))

    if lt is None:
        results.append(_doctor_result("libtorrent", "fail", "not importable"))
    else:
        results.append(_doctor_result("libtorrent", "ok", "importable", version=str(getattr(lt, "__version__", "unknown"))))

    install_root = Path(args.install_root).expanduser()
    ok, msg = _check_writable_dir(install_root, create=not args.no_create)
    results.append(_doctor_result("install_root", "ok" if ok else "fail", msg, path=str(install_root)))

    tmp_dir = Path(args.tmp_dir).expanduser()
    ok, msg = _check_writable_dir(tmp_dir, create=not args.no_create)
    results.append(_doctor_result("tmp_dir", "ok" if ok else "fail", msg, path=str(tmp_dir)))

    library_path = Path(args.library).expanduser()
    ok, msg = _check_writable_dir(library_path.parent, create=not args.no_create)
    results.append(_doctor_result("library_json_parent", "ok" if ok else "fail", msg, path=str(library_path.parent)))

    db_path = Path(args.db).expanduser() if getattr(args, "db", None) else _db_path("client")
    try:
        _db_init(db_path)
        init_library_db(db_path)
        with sqlite3.connect(db_path) as cx:
            tables = sorted(r[0] for r in cx.execute("SELECT name FROM sqlite_master WHERE type='table'"))
        required = {"transfer_session", "transfer_progress", "launch_session", "installed_title", "title_provenance"}
        missing = sorted(required - set(tables))
        if missing:
            results.append(_doctor_result("client_db", "fail", "missing required tables", path=str(db_path), missing=missing))
        else:
            results.append(_doctor_result("client_db", "ok", "schema initialized", path=str(db_path), tables=tables))
    except Exception as e:
        results.append(_doctor_result("client_db", "fail", str(e), path=str(db_path)))

    if not args.skip_port_check:
        ok, msg = _check_port_available(args.listen_port)
        results.append(_doctor_result("listen_port", "ok" if ok else "warn", msg, port=args.listen_port))

    failed = [r for r in results if r["status"] == "fail"]
    output = {
        "ok": not failed,
        "failed": len(failed),
        "results": results,
    }

    if args.json:
        print(json.dumps(output, indent=2))
    else:
        for r in results:
            label = r["status"].upper()
            detail = ""
            if "details" in r:
                detail = " " + json.dumps(r["details"], sort_keys=True)
            print(f"[{label}] {r['name']}: {r['message']}{detail}")
        if not failed:
            print("Environment looks sane.")
    return 0 if not failed else 1

# ------------------------------
# Argparse
# ------------------------------

def build_parser() -> argparse.ArgumentParser:
    epilog = (
        "Examples:\n"
        "  arcadia pack ./examples/game42 --name 'Game42' --id game42 \\\n"
        "         --version 1.0.0 --platform linux-x64 --launch-rel game42 \\\n"
        "         --out-dir ./seeds --tracker udp://tracker.opentrackr.org:1337/announce\n"
        "  arcadia seed ./seeds/game42-1.0.0.torrent --content-dir ./seeds --listen-port 51413\n"
        "  arcadia get http://HOST:8080/game42-1.0.0.arcmanifest\n"
        "  arcadia launch game42 --key ~/client_priv.pem --dev-pubkey ./dev_pub.pem\n"
    )

    parser = argparse.ArgumentParser(
        prog="arcadia",
        description="Arcadia P1 CLI — pack, fetch, install, seed, launch; BitTorrent-powered with optional encryption.",
        epilog=epilog,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )

    # Global flags
    parser.add_argument("-v", "--verbose", action="count", default=1, help="Increase verbosity (-vv for DEBUG)")
    parser.add_argument("-q", "--quiet", action="count", default=0, help="Reduce verbosity (-q for ERROR)")

    sub = parser.add_subparsers(dest="cmd", metavar="{pack,get,list,launch,inspect,doctor,seed,sign,verify,verify-license,verify-chain,migrate-library}")

    # pack
    p_pack = sub.add_parser("pack", help="Create .arcpack, .torrent, and .arcmanifest")
    p_pack.add_argument("input_dir", help="Path to built game directory (or single file)")
    p_pack.add_argument("--name", required=True)
    p_pack.add_argument("--id", required=True)
    p_pack.add_argument("--version", required=True)
    p_pack.add_argument("--platform", required=True, choices=[
        "linux-x64", "linux-arm64", "win-x64", "macos-arm64", "macos-x64"
    ])
    p_pack.add_argument("--launch-rel", default="", help="Relative path to executable inside the pack")
    p_pack.add_argument("--out-dir", default="./seeds")
    p_pack.add_argument("--tracker", action="append", default=[], help="Announce URL (repeatable)")
    p_pack.add_argument("--private", action="store_true", help="Mark torrent as private")
    p_pack.add_argument("--no-torrent", action="store_true")
    p_pack.add_argument("--print-magnet", action="store_true")
    # encryption & licensing
    p_pack.add_argument("--encrypt", action="store_true", help="Encrypt arcpack (AES-256-GCM); torrent ciphertext")
    p_pack.add_argument("--dev-ed25519", help="Developer Ed25519 private key (PEM) to sign manifest and license")
    p_pack.add_argument("--dev-privkey", help="Legacy developer RSA private key (PEM) to sign license")
    p_pack.add_argument("--client-pubkey", help="Client RSA public key (PEM) to wrap content key")
    p_pack.set_defaults(func=handle_pack)

    # seed
    p_seed = sub.add_parser("seed", help="Seed a .torrent for a built .arcpack (blocks until Ctrl+C)")
    p_seed.add_argument("torrent")
    p_seed.add_argument("--content-dir", default="./seeds")
    p_seed.add_argument("--listen-port", type=int, default=51413)
    p_seed.set_defaults(func=handle_seed)

    # get
    p_get = sub.add_parser("get", help="Fetch manifest, download pack, verify, install")
    p_get.add_argument("manifest", help="Path or URL to .arcmanifest")
    p_get.add_argument("--install-root", default=str(Path.home() / ".arcadia" / "games"))
    p_get.add_argument("--tmp-dir", default=str(Path.home() / ".arcadia" / "tmp"))
    p_get.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_get.add_argument("--listen-port", type=int, default=51413)
    p_get.add_argument("--timeout", type=int, default=0)
    p_get.add_argument("--force", action="store_true")
    p_get.add_argument("--no-verify", action="store_true")
    p_get.add_argument("--peer", action="append", help="Direct seed peer ip:port (repeatable)")
    p_get.add_argument("--license", help="Path to a license.json to store with an encrypted title")
    p_get.add_argument("--diagnostics-json", help="Write BitTorrent transport diagnostics to this JSON file")
    p_get.set_defaults(func=handle_get)

    # list
    p_list = sub.add_parser("list", help="Show installed titles")
    p_list.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_list.add_argument("--json", action="store_true")
    p_list.set_defaults(func=handle_list)

    p_migrate = sub.add_parser("migrate-library", help="Import library.json into the local SQLite library DB")
    p_migrate.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_migrate.add_argument("--db", help="SQLite DB path (default: ARCADIA_CLIENT_DB or ~/.arcadia/library.db)")
    p_migrate.set_defaults(func=handle_migrate_library)

    # launch
    p_launch = sub.add_parser("launch", help="Launch an installed game by id")
    p_launch.add_argument("game_id")
    p_launch.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_launch.add_argument("--install-root", default=str(Path.home() / ".arcadia" / "games"))
    p_launch.add_argument("--license", help="Path to license.json (if not already stored)")
    p_launch.add_argument("--key", help="Player RSA private key (PEM) to unwrap the content key")
    p_launch.add_argument("--dev-pubkey", help="Developer public key (PEM) to verify license signature")
    p_launch.add_argument("--keep-decrypted", action="store_true", help="Keep decrypted files after run (debug)")
    p_launch.add_argument("--no-auto-discover", action="store_true",
                          help="Disable automatic search for an executable inside .run/")
    p_launch.add_argument("game_args", nargs=argparse.ZERO_OR_MORE,
                          help="Args passed to the game; if they start with '-' put them after a double-dash '--'")
    p_launch.set_defaults(func=handle_launch)

    # inspect
    p_inspect = sub.add_parser("inspect", help="List contents of an installed title")
    p_inspect.add_argument("game_id")
    p_inspect.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_inspect.add_argument("--key", help="Player RSA private key (required for encrypted titles)")
    p_inspect.set_defaults(func=handle_inspect)

    # doctor
    p_doc = sub.add_parser("doctor", help="Check environment and permissions")
    p_doc.add_argument("--install-root", "--install_root", dest="install_root", default=str(Path.home() / ".arcadia" / "games"))
    p_doc.add_argument("--tmp-dir", default=str(Path.home() / ".arcadia" / "tmp"))
    p_doc.add_argument("--library", default=str(Path.home() / ".arcadia" / "library.json"))
    p_doc.add_argument("--db", help="SQLite DB path (default: ARCADIA_CLIENT_DB or ~/.arcadia/library.db)")
    p_doc.add_argument("--listen-port", type=int, default=51413)
    p_doc.add_argument("--skip-port-check", action="store_true")
    p_doc.add_argument("--no-create", action="store_true", help="Do not create missing local state directories during checks")
    p_doc.add_argument("--json", action="store_true", help="Emit machine-readable diagnostics")
    p_doc.set_defaults(func=handle_doctor)

    # sign/verify
    p_sign = sub.add_parser("sign", help="Detached sign a file with RSA-PSS(SHA-256)")
    p_sign.add_argument("file")
    p_sign.add_argument("--key", required=True, help="Developer private key (PEM)")
    p_sign.add_argument("--armor", action="store_true", help="Base64-armor signature to stdout or --out")
    p_sign.add_argument("--out", help="Output path for signature (default: <file>.sig or stdout if --armor)")
    p_sign.set_defaults(func=handle_sign)

    p_verify = sub.add_parser("verify", help="Verify a detached signature against a file")
    p_verify.add_argument("file")
    p_verify.add_argument("--signature", required=True, help="Path to signature (raw or base64 if --armor)")
    p_verify.add_argument("--pubkey", required=True, help="Developer public key (PEM)")
    p_verify.add_argument("--armor", action="store_true", help="Treat signature file as base64-encoded")
    p_verify.set_defaults(func=handle_verify)

    p_vlic = sub.add_parser("verify-license", help="Verify license JSON signature (RSA-PSS)")
    p_vlic.add_argument("--file", required=True, help="Path to license.json")
    p_vlic.add_argument("--pubkey", required=True, help="Developer public key (PEM)")
    p_vlic.set_defaults(func=handle_verify_license)

    p_vchain = sub.add_parser("verify-chain", help="Verify modern manifest/license/payload trust chain")
    p_vchain.add_argument("--manifest", required=True, help="Path to .arcmanifest")
    p_vchain.add_argument("--license", required=True, help="Path to license.json")
    p_vchain.add_argument("--payload", help="Optional payload path for full hash verification")
    p_vchain.add_argument("--key", "--player-key", dest="player_key", help="Optional player private key for unwrap/decrypt checks")
    p_vchain.add_argument("--dev-pubkey", help="Optional developer public key for legacy checks")
    p_vchain.set_defaults(func=handle_verify_chain)

    return parser

# ------------------------------
# main
# ------------------------------

def main(argv: Optional[List[str]] = None) -> int:
    argv = argv or sys.argv[1:]
    # Prep logging
    partial = argparse.ArgumentParser(add_help=False)
    partial.add_argument("-v", "--verbose", action="count", default=1)
    partial.add_argument("-q", "--quiet", action="count", default=0)
    known, _ = partial.parse_known_args(argv)
    setup_logging((known.verbose or 1) - (known.quiet or 0))

    parser = build_parser()
    args = parser.parse_args(argv)
    if not getattr(args, "cmd", None):
        parser.print_help()
        return 1
    try:
        return int(args.func(args))
    except KeyboardInterrupt:
        LOGGER.error("Interrupted")
        return 130
    except Exception as exc:
        LOGGER.exception("Unhandled error: %s", exc)
        return 1

if __name__ == "__main__":
    sys.exit(main())