model-mirror-cli 0.2.0__py3-none-any.whl

model_mirror/cli.py

@@ -0,0 +1,2436 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from . import __version__
+from .audit import audit_model
+from .checksums import MANIFEST, iter_payload_files, load_manifest, write_checksums, verify_checksums
+from .config import (
+    Config,
+    REPO_TYPE_DIRS,
+    archive_path,
+    archive_runtime_cache_path,
+    archive_runtime_tmp_path,
+    load_config,
+    parse_bool,
+    parse_nonnegative_int,
+    parse_positive_int,
+    save_config,
+)
+from .hub import HuggingFaceHub, get_snapshot, read_snapshot_plan
+from .lock import ModelBusyError, ModelLock, lock_label, read_active_lock
+from .mirror import mirror
+from .progress import ProgressEntry, ProgressSnapshot, progress_snapshot
+from .repair import repair
+from .removal import (
+    REMOVALS_DIR,
+    RemovalRecord,
+    complete_removal,
+    prune_empty_removal_parents,
+    read_removal_record,
+    removal_path,
+    removal_record_path,
+    stage_removal,
+    write_removal_record,
+)
+from .state import (
+    VerificationState,
+    read_verification_state,
+    state_from_results,
+    verification_state_path,
+    write_verification_state,
+)
+from .verify import RemoteVerifyResult, merge_checksum_result, verify_remote
+
+
+TORRENT_EXPERIMENTAL_NOTICE = (
+    "EXPERIMENTAL: torrent interfaces and metadata formats may change before stabilization."
+)
+
+
+CONFIG_OPTIONS = [
+    (
+        "directory",
+        "MODEL_MIRROR_DIRECTORY",
+        "Archive root. Repos are stored below models/, datasets/, or spaces/ under this directory.",
+    ),
+    ("repo_type", "MODEL_MIRROR_REPO_TYPE", "Default Hugging Face repo type: model, dataset, or space."),
+    ("revision", "MODEL_MIRROR_REVISION", "Default revision to mirror or verify, usually main."),
+    ("checksum", None, "Whether mirror/repair writes local hash manifest records."),
+    (
+        "checksum_workers",
+        "MODEL_MIRROR_CHECKSUM_WORKERS",
+        "Number of files to hash concurrently. Use 1 for HDD-friendly sequential reads.",
+    ),
+    (
+        "download_workers",
+        "MODEL_MIRROR_DOWNLOAD_WORKERS",
+        "Number of files to download concurrently. Default 1 is HDD-friendly; increase for SSD/NVMe.",
+    ),
+    (
+        "stall_timeout_seconds",
+        "MODEL_MIRROR_STALL_TIMEOUT",
+        "Abort and retry a file when no local byte progress occurs for this many seconds. "
+        "Default 600; set 0 to disable.",
+    ),
+    (
+        "stall_retries",
+        "MODEL_MIRROR_STALL_RETRIES",
+        "Number of stall-triggered resume retries per file before failing the mirror.",
+    ),
+    ("verify_after_mirror", None, "Whether mirror runs verification after download unless --no-verify is passed."),
+    (
+        "hf_xet_high_performance",
+        "MODEL_MIRROR_HF_XET_HIGH_PERFORMANCE",
+        "Sets HF_XET_HIGH_PERFORMANCE=1. Off by default; use only on high-bandwidth machines "
+        "with fast disks and ample memory, typically 64 GB RAM or more.",
+    ),
+    (
+        "hf_xet_reconstruct_write_sequentially",
+        "MODEL_MIRROR_HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY",
+        "Uses HDD-friendly Xet reconstruction writes by disabling vectored reconstruction writes where supported.",
+    ),
+    (
+        "hf_xet_num_concurrent_range_gets",
+        "MODEL_MIRROR_HF_XET_NUM_CONCURRENT_RANGE_GETS",
+        "Limits Xet internal download concurrency. Default 1 is HDD-friendly; increase for SSD/NVMe.",
+    ),
+    (
+        "token_path",
+        "MODEL_MIRROR_TOKEN_PATH",
+        "Path to a Hugging Face token file. If unset, model-mirror checks HF_TOKEN_PATH, "
+        "HF_HOME/token, ~/.cache/huggingface/token, and ~/.huggingface/token. Token contents are never printed.",
+    ),
+    (
+        "cache_dir",
+        None,
+        "Overrides the Hugging Face cache root; defaults to DIRECTORY/.model-mirror/cache.",
+    ),
+    (
+        "tmp_dir",
+        None,
+        "Overrides temporary file directory; defaults to DIRECTORY/.model-mirror/tmp.",
+    ),
+]
+
+
+@dataclass(slots=True)
+class CacheUsage:
+    archive_cache: int
+    archive_tmp: int
+    mirror_cache: int
+
+    @property
+    def total(self) -> int:
+        return self.archive_cache + self.archive_tmp + self.mirror_cache
+
+
+@dataclass(slots=True)
+class MirrorStatusEntry:
+    root: Path
+    repo_id: str
+    repo_type: str
+    state: VerificationState | None
+    active_lock: dict | None
+    payload_files: int | None
+    payload_size: int | None
+    payload_source: str
+    expected_files: int | None
+    snapshot_commit: str
+    snapshot_requested_revision: str
+    progress: ProgressSnapshot
+    torrent_status: str | None
+    upstream_observation: UpstreamObservation | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamObservation:
+    status: str
+    commit: str | None
+    observed_at_utc: str
+    error: str | None = None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="model-mirror",
+        description="Mirror Hugging Face repositories into local bulk storage and verify their integrity.",
+        epilog="Run 'model-mirror COMMAND --help' for command-specific options.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--config", help="path to config file; defaults to ~/.model-mirror.yaml")
+    subparsers = parser.add_subparsers(dest="command")
+    command_parsers: dict[str, argparse.ArgumentParser] = {}
+
+    def add_command_parser(name: str, **kwargs) -> argparse.ArgumentParser:
+        command_parser = subparsers.add_parser(name, **kwargs)
+        command_parsers[name] = command_parser
+        return command_parser
+
+    mirror_parser = add_command_parser(
+        "mirror",
+        help="mirror a Hugging Face repo",
+        description="Download a repo at a resolved Hub commit and verify it unless --no-verify is used.",
+        epilog="Exit status: 0 when complete or downloaded cleanly; 1 when final verification is not clean.",
+    )
+    mirror_parser.add_argument("model", metavar="repo", help="Hugging Face repo id, e.g. org/model")
+    mirror_parser.add_argument("--repo-type", choices=["model", "dataset", "space"], help="repo kind to mirror")
+    add_revision_options(mirror_parser)
+    mirror_parser.add_argument("--force", action="store_true", help="download even if the local copy looks complete")
+    mirror_parser.add_argument("--no-verify", action="store_true", help="skip verification after download")
+    mirror_parser.add_argument(
+        "--stall-timeout",
+        type=parse_nonnegative_int_arg,
+        metavar="SECONDS",
+        help="override stall timeout for this mirror; default 600 seconds, 0 disables timeout",
+    )
+
+    remove_parser = add_command_parser(
+        "remove",
+        help="permanently remove a mirror",
+        description=(
+            "Show the selected mirror's identity, commit, verification age, file count, and size, "
+            "then require confirmation before permanent removal. Interrupted removals are resumable."
+        ),
+        epilog=(
+            "Exit status: 0 when removed or cancelled; 1 when the mirror is missing, busy, unsafe, "
+            "has an active torrent publication, or removal is interrupted."
+        ),
+    )
+    remove_parser.add_argument("model", metavar="repo", help="repo id to remove, e.g. org/model")
+    remove_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to remove"
+    )
+    remove_parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="skip the interactive repository-name confirmation",
+    )
+
+    verify_parser = add_command_parser(
+        "verify",
+        help="verify mirrored archives",
+        description="Check local files against Hub metadata, local checksums, and model metadata.",
+        epilog=(
+            "Exit status: 0 when verification is clean; 1 when files are missing, corrupt, extra, busy, "
+            "the upstream repository is unavailable, or cached verification data is missing/stale; "
+            "2 for command-line errors."
+        ),
+    )
+    verify_parser.add_argument("model", metavar="repo", nargs="?", help="repo id to verify unless --all is used")
+    verify_parser.add_argument("--cached", action="store_true", help="verify Hub hashes from cached .manifest rows")
+    verify_parser.add_argument("--all", action="store_true", help="verify every mirrored model")
+    verify_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to verify"
+    )
+    add_revision_options(verify_parser)
+    verify_parser.add_argument("--strict", action="store_true", help="fail on extra local files")
+    verify_parser.add_argument("--max-age", help="with --all, skip clean archives verified within this age, e.g. 7d")
+    verify_parser.add_argument("--offline", action="store_true", help="verify only against local checksum state")
+
+    repair_parser = add_command_parser(
+        "repair",
+        help="repair a mirrored archive",
+        description=(
+            "Redownload files listed in existing .verification repair paths, "
+            "reconcile a stale pinned snapshot plan, then run a final verification. Run verify first."
+        ),
+        epilog=(
+            "Exit status: 0 when complete, repaired, or updated cleanly; 1 when verification state is missing, "
+            "repair is incomplete, cached verification data is incomplete, or a model is busy; "
+            "2 for command-line errors."
+        ),
+    )
+    repair_parser.add_argument("model", metavar="repo", nargs="?", help="repo id to repair unless --all is used")
+    repair_parser.add_argument("--all", action="store_true", help="repair every mirrored model with verification state")
+    repair_parser.add_argument(
+        "--update",
+        action="store_true",
+        help="apply upstream commit changes recorded by verify before repairing",
+    )
+    repair_parser.add_argument(
+        "--force-partial",
+        action="store_true",
+        help=(
+            "attempt repair even when cached verification data for untouched files is incomplete; "
+            "may leave the repository inconsistent"
+        ),
+    )
+    repair_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to repair"
+    )
+
+    upgrade_parser = add_command_parser(
+        "upgrade",
+        help="EXPERIMENTAL: add complete torrent hash coverage to existing archives",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Read only payload files missing reusable torrent hash coverage. "
+            "Payload bytes and the pinned resolved commit are not changed."
+        ),
+        epilog="Exit status: 0 when coverage is complete or the dry-run succeeds; 1 on an unreadable archive or busy model.",
+    )
+    upgrade_parser.add_argument("model", metavar="repo", nargs="?", help="repo id to upgrade unless --all is used")
+    upgrade_parser.add_argument("--all", action="store_true", help="upgrade every mirrored repository of this type")
+    upgrade_parser.add_argument("--dry-run", action="store_true", help="report required reads without changing metadata")
+    upgrade_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to upgrade"
+    )
+
+    torrent_parser = add_command_parser(
+        "torrent",
+        help="EXPERIMENTAL: publish, seed, inspect, or retire commit-pinned torrents",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Manage client-independent torrent artifacts and model-mirror's durable seed intent."
+        ),
+    )
+    torrent_subparsers = torrent_parser.add_subparsers(dest="torrent_command")
+
+    def add_torrent_repo_command(name: str, help_text: str) -> argparse.ArgumentParser:
+        command = torrent_subparsers.add_parser(
+            name,
+            help=help_text,
+            description=f"{TORRENT_EXPERIMENTAL_NOTICE} {help_text.capitalize()}.",
+        )
+        command.add_argument("model", metavar="repo", help="repo id, e.g. org/model")
+        command.add_argument(
+            "--repo-type",
+            choices=["model", "dataset", "space"],
+            default="model",
+            help="repo kind",
+        )
+        return command
+
+    create_torrent_parser = add_torrent_repo_command(
+        "create",
+        "create an ordinary .torrent and recovery record without requesting managed seeding",
+    )
+    create_torrent_parser.add_argument(
+        "--external",
+        action="store_true",
+        help="record that runtime seeding is owned by an external client",
+    )
+    publish_torrent_parser = add_torrent_repo_command(
+        "publish",
+        "create or reuse a publication and request durable seeding",
+    )
+    publish_torrent_parser.add_argument(
+        "--external",
+        action="store_true",
+        help="emit external-client handoff instead of managed seed intent",
+    )
+    add_torrent_repo_command("show", "show publication, trust, fence, and backend state")
+    add_torrent_repo_command("stop", "stop desired managed seeding without releasing the update fence")
+    add_torrent_repo_command("retire", "remove desired seeding and release the update fence")
+    handoff_torrent_parser = torrent_subparsers.add_parser(
+        "handoff",
+        help="print a standard-client download destination and exact import command",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Print a standard-client download destination and exact import command."
+        ),
+    )
+    handoff_torrent_parser.add_argument("torrent_file", type=Path, help="model-mirror .torrent file")
+    import_torrent_parser = torrent_subparsers.add_parser(
+        "import",
+        help="validate and atomically finalize payload downloaded by an external client",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Validate and atomically finalize payload downloaded by an external client."
+        ),
+    )
+    import_torrent_parser.add_argument("torrent_file", type=Path, help="model-mirror .torrent file")
+    import_torrent_parser.add_argument("payload_root", type=Path, help="downloaded torrent root directory")
+    import_torrent_parser.add_argument(
+        "--seed",
+        action="store_true",
+        help="request managed seeding after successful import",
+    )
+    join_torrent_parser = torrent_subparsers.add_parser(
+        "join",
+        help="download a model-mirror torrent or magnet and finalize it as a local archive",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Download a model-mirror torrent or magnet and finalize it as a local archive."
+        ),
+    )
+    join_torrent_parser.add_argument("source", help="path to a .torrent file or a magnet URI")
+    join_torrent_parser.add_argument(
+        "--seed",
+        action="store_true",
+        help="request managed seeding after successful join",
+    )
+    join_torrent_parser.add_argument(
+        "--metadata-timeout",
+        type=float,
+        default=120.0,
+        help="seconds to wait for magnet metadata; default 120",
+    )
+    serve_torrent_parser = torrent_subparsers.add_parser(
+        "serve",
+        help="run the managed libtorrent backend and reconcile durable seed intent",
+        description=(
+            f"{TORRENT_EXPERIMENTAL_NOTICE} "
+            "Run the managed libtorrent backend and reconcile durable seed intent."
+        ),
+    )
+    serve_torrent_parser.add_argument(
+        "--poll-seconds",
+        type=float,
+        default=2.0,
+        help="desired-state reconciliation interval; default 2 seconds",
+    )
+    serve_torrent_parser.add_argument(
+        "--once",
+        action="store_true",
+        help="perform one reconciliation pass and stop (diagnostic)",
+    )
+
+    offline_parser = add_command_parser(
+        "offline",
+        help="mark a mirror offline-only",
+        description=(
+            "Disable Hub checks for one mirrored repo. Use this when the upstream repo is gone "
+            "and you want verification to use local state only."
+        ),
+        epilog="Exit status: 0 when the mirror is marked offline-only; 1 when local verification state is missing or busy.",
+    )
+    offline_parser.add_argument("model", metavar="repo", help="repo id to mark offline-only")
+    offline_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to update"
+    )
+
+    online_parser = add_command_parser(
+        "online",
+        help="re-enable Hub checks for a mirror",
+        description="Clear offline-only mode so verify and repair contact the Hub again.",
+        epilog="Exit status: 0 when the mirror is marked online; 1 when local verification state is missing or busy.",
+    )
+    online_parser.add_argument("model", metavar="repo", help="repo id to mark online")
+    online_parser.add_argument(
+        "--repo-type", choices=["model", "dataset", "space"], default="model", help="repo kind to update"
+    )
+
+    list_parser = add_command_parser(
+        "list",
+        help="list mirrors in columns or show one mirror in detail",
+        description=(
+            "Show a compact archive-wide table, or detailed last-known local state when REPO is supplied. "
+            "This command is metadata-only and does not contact upstream unless --check-upstream is supplied."
+        ),
+    )
+    status_parser = add_command_parser(
+        "status",
+        help="show archive status or detailed local state for one mirror",
+        description=(
+            "Show a compact archive-wide table, or detailed last-known local state when REPO is supplied. "
+            "This command is metadata-only and does not contact upstream unless --check-upstream is supplied."
+        ),
+    )
+    for status_like_parser in (list_parser, status_parser):
+        status_like_parser.add_argument("model", metavar="repo", nargs="?", help="optional repo id, e.g. org/model")
+        status_like_parser.add_argument(
+            "--repo-type",
+            choices=["model", "dataset", "space"],
+            help="repo kind; filters the table or selects the detailed repo",
+        )
+        status_like_parser.add_argument(
+            "--check-upstream",
+            action="store_true",
+            help="advisory live comparison with upstream; does not update local metadata",
+        )
+        status_like_parser.add_argument(
+            "--verbose",
+            action="store_true",
+            help="show all recorded metadata fields in the human-readable detail view",
+        )
+        status_like_parser.add_argument(
+            "--json",
+            action="store_true",
+            dest="json_output",
+            help="emit stable structured JSON; --verbose has no effect",
+        )
+
+    clean_cache_parser = add_command_parser(
+        "clean-cache",
+        help="remove Hugging Face cache and temporary files",
+        description=(
+            "Remove archive cache, temporary files, and per-mirror Hugging Face metadata caches "
+            "without touching mirrored payload files. Without --force, only reports reclaimable space."
+        ),
+        epilog="Exit status: 0 when cleanup succeeds; 1 when a configured cleanup target is unsafe.",
+    )
+    clean_cache_parser.add_argument("--force", action="store_true", help="delete cache and temporary files")
+
+    config_parser = add_command_parser(
+        "config",
+        help="show or change configuration",
+        description="Print configuration, describe supported keys, or persist configuration changes.",
+    )
+    config_subparsers = config_parser.add_subparsers(dest="config_command")
+    config_subparsers.add_parser("show", help="print the resolved configuration")
+    config_subparsers.add_parser("options", help="print supported configuration keys with descriptions")
+    directory_parser = config_subparsers.add_parser("directory", help="get or set archive directory")
+    directory_parser.add_argument("path", nargs="?", help="new archive directory; omit to print current value")
+    set_parser = config_subparsers.add_parser("set", help="set a supported configuration key")
+    set_parser.add_argument("key", help="configuration key; see 'model-mirror config options'")
+    set_parser.add_argument("value", help="new value")
+
+    help_parser = add_command_parser(
+        "help",
+        help="show help",
+        description="Show full help or command-specific help.",
+    )
+    help_parser.add_argument("topic", nargs="?", help="optional command to show help for")
+    parser.command_parsers = command_parsers
+
+    return parser
+
+
+def add_revision_options(parser: argparse.ArgumentParser) -> None:
+    revision_group = parser.add_mutually_exclusive_group()
+    revision_group.add_argument("--revision", help="branch, tag, or commit to use; defaults to config revision")
+    revision_group.add_argument("--commit", help="commit SHA to use")
+
+
+def parse_nonnegative_int_arg(value: str) -> int:
+    try:
+        return parse_nonnegative_int(value, default=0)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def selected_revision_arg(args) -> str | None:
+    return args.commit or args.revision
+
+
+def main(argv: list[str] | None = None, *, hub=None) -> int:
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    args = parser.parse_args(raw_argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    if args.command == "help":
+        return handle_help(parser, args.topic)
+    config_path = Path(args.config).expanduser() if args.config else None
+    config = load_config(config_path)
+
+    if should_supervise_mirror(args, config, hub):
+        return run_supervised_mirror(raw_argv, args, config)
+
+    try:
+        if args.command == "config":
+            return handle_config(args, config, config_path)
+        if args.command in {"list", "status"}:
+            return handle_list(
+                config,
+                repo_id=args.model,
+                repo_type=args.repo_type,
+                check_upstream=args.check_upstream,
+                verbose=args.verbose,
+                json_output=args.json_output,
+                hub=hub,
+            )
+        if args.command == "clean-cache":
+            return handle_clean_cache(config, force=args.force)
+        if args.command == "mirror":
+            selected_hub = hub or HuggingFaceHub(config)
+            result = mirror(
+                config,
+                args.model,
+                hub=selected_hub,
+                repo_type=args.repo_type,
+                revision=selected_revision_arg(args),
+                force=args.force,
+                verify_after=config.verify_after_mirror and not args.no_verify,
+                stall_timeout_seconds=args.stall_timeout,
+            )
+            print(f"{result.status}: {args.model} -> {result.path}")
+            return mirror_exit_code(result.status)
+        if args.command == "remove":
+            return handle_remove(args, config)
+        if args.command == "verify":
+            return handle_verify(args, config, hub=hub)
+        if args.command == "repair":
+            return handle_repair(args, config, hub=hub)
+        if args.command == "upgrade":
+            return handle_upgrade(args, config)
+        if args.command == "torrent":
+            return handle_torrent(args, config)
+        if args.command == "offline":
+            return handle_offline_mode(args, config, offline_only=True)
+        if args.command == "online":
+            return handle_offline_mode(args, config, offline_only=False)
+    except ModelBusyError as exc:
+        print(str(exc))
+        return 1
+
+    parser.error(f"Unhandled command: {args.command}")
+    return 2
+
+
+def should_supervise_mirror(args, config: Config, hub) -> bool:
+    if args.command != "mirror":
+        return False
+    if hub is not None:
+        return False
+    if os.environ.get("MODEL_MIRROR_SUPERVISED_CHILD") == "1":
+        return False
+    return effective_stall_timeout(args, config) > 0
+
+
+def effective_stall_timeout(args, config: Config) -> int:
+    selected = getattr(args, "stall_timeout", None)
+    return config.stall_timeout_seconds if selected is None else selected
+
+
+def run_supervised_mirror(raw_argv: list[str], args, config: Config) -> int:
+    repo_type = args.repo_type or config.repo_type
+    root = archive_path(config, args.model, repo_type)
+    timeout = effective_stall_timeout(args, config)
+    retry_limit = config.stall_retries
+    retry_counts: dict[str, int] = {}
+    command = [sys.executable, "-m", "model_mirror.cli", *raw_argv]
+    env = dict(os.environ)
+    env["MODEL_MIRROR_SUPERVISED_CHILD"] = "1"
+
+    while True:
+        child = subprocess.Popen(command, env=env)
+        restart, returncode = supervise_child(child, root, timeout, retry_limit, retry_counts)
+        if restart:
+            continue
+        return returncode
+
+
+def supervise_child(
+    child,
+    root: Path,
+    timeout: int,
+    retry_limit: int,
+    retry_counts: dict[str, int],
+) -> tuple[bool, int]:
+    started = time.monotonic()
+    started_at_utc = datetime.now(timezone.utc)
+    poll_interval = min(30.0, max(1.0, timeout / 10))
+    while True:
+        returncode = child.poll()
+        if returncode is not None:
+            return False, returncode
+
+        snapshot = progress_snapshot(root, stall_timeout_seconds=timeout)
+        fresh_entries = fresh_progress_entries(snapshot.entries, started_at_utc)
+        stalled_entries = [entry for entry in fresh_entries if entry.stalled]
+        if stalled_entries:
+            entry = selected_progress_entry(stalled_entries)
+            path = entry.path
+            retry_counts[path] = retry_counts.get(path, 0) + 1
+            if retry_counts[path] > retry_limit:
+                print(
+                    f"stall retry limit exceeded for {path}: "
+                    f"{retry_counts[path] - 1}/{retry_limit}; terminating mirror child"
+                )
+                terminate_child(child)
+                return False, 1
+            print(
+                f"stall detected for {path}: idle={format_age_seconds(entry.idle_seconds)}; "
+                f"restarting mirror child ({retry_counts[path]}/{retry_limit})"
+            )
+            terminate_child(child)
+            return True, 0
+
+        if not fresh_entries and time.monotonic() - started >= timeout:
+            retry_counts["<no-progress>"] = retry_counts.get("<no-progress>", 0) + 1
+            if retry_counts["<no-progress>"] > retry_limit:
+                print("stall retry limit exceeded before progress was reported; terminating mirror child")
+                terminate_child(child)
+                return False, 1
+            print(
+                "stall detected before progress was reported; "
+                f"restarting mirror child ({retry_counts['<no-progress>']}/{retry_limit})"
+            )
+            terminate_child(child)
+            return True, 0
+
+        time.sleep(poll_interval)
+
+
+def fresh_progress_entries(entries: list[ProgressEntry], started_at_utc: datetime) -> list[ProgressEntry]:
+    return [entry for entry in entries if progress_entry_updated_after(entry, started_at_utc)]
+
+
+def progress_entry_updated_after(entry: ProgressEntry, cutoff: datetime) -> bool:
+    try:
+        updated = datetime.fromisoformat(entry.updated_at_utc)
+    except ValueError:
+        return False
+    if updated.tzinfo is None:
+        updated = updated.replace(tzinfo=timezone.utc)
+    return updated >= cutoff
+
+
+def terminate_child(child) -> None:
+    child.terminate()
+    try:
+        child.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        child.kill()
+        child.wait(timeout=30)
+
+
+def handle_help(parser: argparse.ArgumentParser, topic: str | None) -> int:
+    if topic is None:
+        parser.print_help()
+        return 0
+    command_parser = parser.command_parsers.get(topic)
+    if command_parser is None:
+        parser.error(f"Unknown help topic: {topic}")
+    command_parser.print_help()
+    return 0
+
+
+def mirror_exit_code(status: str) -> int:
+    return 0 if status in {"complete", "downloaded"} else 1
+
+
+def handle_config(args, config: Config, config_path: Path | None) -> int:
+    if args.config_command in {None, "options"}:
+        return handle_config_options(config)
+
+    if args.config_command == "show":
+        print(f"directory: {config.directory}")
+        print(f"repo_type: {config.repo_type}")
+        print(f"revision: {config.revision}")
+        print(f"checksum: {config.checksum}")
+        print(f"checksum_workers: {config.checksum_workers}")
+        print(f"download_workers: {config.download_workers}")
+        print(f"stall_timeout_seconds: {config.stall_timeout_seconds}")
+        print(f"stall_retries: {config.stall_retries}")
+        print(f"verify_after_mirror: {config.verify_after_mirror}")
+        print(f"hf_xet_high_performance: {config.hf_xet_high_performance}")
+        print(f"hf_xet_reconstruct_write_sequentially: {config.hf_xet_reconstruct_write_sequentially}")
+        if config.hf_xet_num_concurrent_range_gets is not None:
+            print(f"hf_xet_num_concurrent_range_gets: {config.hf_xet_num_concurrent_range_gets}")
+        if config.token_path:
+            print(f"token_path: {config.token_path}")
+        return 0
+
+    if args.config_command == "directory":
+        if args.path is None:
+            print(config.directory)
+            return 0
+        config.directory = Path(args.path).expanduser()
+        config.directory.mkdir(parents=True, exist_ok=True)
+        save_config(config, config_path)
+        print(f"directory: {config.directory}")
+        return 0
+
+    if args.config_command == "set":
+        set_config_value(config, args.key, args.value)
+        save_config(config, config_path)
+        print(f"{args.key}: {args.value}")
+        return 0
+
+    return 2
+
+
+def handle_config_options(config: Config) -> int:
+    values = {
+        "directory": config.directory,
+        "repo_type": config.repo_type,
+        "revision": config.revision,
+        "checksum": config.checksum,
+        "checksum_workers": config.checksum_workers,
+        "download_workers": config.download_workers,
+        "stall_timeout_seconds": config.stall_timeout_seconds,
+        "stall_retries": config.stall_retries,
+        "verify_after_mirror": config.verify_after_mirror,
+        "hf_xet_high_performance": config.hf_xet_high_performance,
+        "hf_xet_reconstruct_write_sequentially": config.hf_xet_reconstruct_write_sequentially,
+        "hf_xet_num_concurrent_range_gets": config.hf_xet_num_concurrent_range_gets,
+        "token_path": config.token_path,
+        "cache_dir": config.cache_dir,
+        "tmp_dir": config.tmp_dir,
+    }
+    for key, env_var, description in CONFIG_OPTIONS:
+        print(f"{key}: {values[key]}")
+        if env_var:
+            print(f"  env: {env_var}")
+        print(f"  {description}")
+    return 0
+
+
+def set_config_value(config: Config, key: str, value: str) -> None:
+    normalized = key.replace("-", "_")
+    if normalized == "directory":
+        config.directory = Path(value).expanduser()
+    elif normalized == "repo_type":
+        config.repo_type = value
+    elif normalized == "revision":
+        config.revision = value
+    elif normalized == "checksum":
+        config.checksum = parse_bool(value)
+    elif normalized == "checksum_workers":
+        config.checksum_workers = parse_positive_int(value, default=1)
+    elif normalized == "download_workers":
+        config.download_workers = parse_positive_int(value, default=1)
+    elif normalized in {"stall_timeout", "stall_timeout_seconds"}:
+        config.stall_timeout_seconds = parse_nonnegative_int(value, default=600)
+    elif normalized == "stall_retries":
+        config.stall_retries = parse_nonnegative_int(value, default=3)
+    elif normalized in {"verify_after_mirror", "audit_after_mirror"}:
+        config.verify_after_mirror = parse_bool(value)
+    elif normalized == "hf_xet_high_performance":
+        config.hf_xet_high_performance = parse_bool(value)
+    elif normalized == "hf_xet_reconstruct_write_sequentially":
+        config.hf_xet_reconstruct_write_sequentially = parse_bool(value)
+    elif normalized == "hf_xet_num_concurrent_range_gets":
+        config.hf_xet_num_concurrent_range_gets = parse_positive_int(value, default=16)
+    elif normalized == "token_path":
+        config.token_path = Path(value).expanduser()
+    elif normalized == "cache_dir":
+        config.cache_dir = Path(value).expanduser()
+    elif normalized == "tmp_dir":
+        config.tmp_dir = Path(value).expanduser()
+    else:
+        raise SystemExit(f"Unsupported config key: {key}")
+
+
+def handle_list(
+    config: Config,
+    *,
+    repo_id: str | None = None,
+    repo_type: str | None = None,
+    check_upstream: bool = False,
+    verbose: bool = False,
+    json_output: bool = False,
+    hub=None,
+) -> int:
+    errors: list[dict[str, str]] = []
+    if repo_id is not None:
+        selected_type = repo_type or config.repo_type
+        root = archive_path(config, repo_id, selected_type)
+        if not root.is_dir():
+            message = f"mirror not found: {selected_type}:{repo_id} -> {root}"
+            if json_output:
+                errors.append(
+                    {
+                        "code": "mirror-not-found",
+                        "repo_id": repo_id,
+                        "repo_type": selected_type,
+                        "message": message,
+                    }
+                )
+                print_status_json(config, [], errors)
+            else:
+                print(message)
+            return 1
+        entries = [build_mirror_status(config, root, repo_id, selected_type)]
+        if check_upstream:
+            observe_upstreams(config, entries, hub=hub)
+        if json_output:
+            print_status_json(config, entries, errors)
+        elif verbose:
+            print_mirror_detail_verbose(entries[0])
+        else:
+            print_mirror_detail(entries[0])
+        return 0
+
+    entries = collect_mirror_status(config, repo_type=repo_type)
+    if check_upstream:
+        observe_upstreams(config, entries, hub=hub)
+    if json_output:
+        print_status_json(config, entries, errors)
+        return 0
+
+    archive_root = Path(config.directory)
+    known_sizes = [entry.payload_size for entry in entries if entry.payload_size is not None]
+    unknown_sizes = len(entries) - len(known_sizes)
+    summary = f"archive: {archive_root}  mirrors={len(entries)}  recorded_payload={format_bytes(sum(known_sizes))}"
+    if unknown_sizes:
+        summary += f"  unknown_payload={unknown_sizes}"
+    print(summary)
+    print_mirror_table(entries)
+    return 0
+
+
+def handle_remove(args, config: Config) -> int:
+    root = archive_path(config, args.model, args.repo_type)
+    staged = removal_path(config, args.model, args.repo_type)
+    removal_control = Path(config.directory) / REMOVALS_DIR
+    try:
+        with ModelLock(removal_control, "remove", args.model, args.repo_type):
+            if staged.exists() or staged.is_symlink():
+                return resume_remove(args, config, root, staged)
+            if root.is_symlink():
+                print(f"remove refused unsafe mirror path: {root}")
+                return 1
+            if not root.is_dir():
+                print(f"mirror not found: {args.repo_type}:{args.model} -> {root}")
+                return 1
+
+            with ModelLock(root, "remove", args.model, args.repo_type):
+                marker = removal_record_path(root)
+                pending = marker.exists() or marker.is_symlink()
+                try:
+                    record = read_removal_record(root) if pending else None
+                except ValueError:
+                    record = None
+                record = record or inspect_removal(root, args.model, args.repo_type)
+                if pending:
+                    print(f"prepared interrupted removal found: {root}")
+                print_removal_summary(record)
+                publication_error = active_publication_removal_error(root)
+                if publication_error is not None:
+                    marker.unlink(missing_ok=True)
+                    print(publication_error)
+                    return 1
+                if not args.yes and not confirm_removal(args.model):
+                    marker.unlink(missing_ok=True)
+                    print(f"cancelled: {args.repo_type}:{args.model} was not removed")
+                    return 0
+                write_removal_record(root, record)
+
+            try:
+                stage_removal(root, staged, record)
+                complete_removal(staged)
+            except (OSError, ValueError) as exc:
+                print(
+                    f"removal interrupted: {args.repo_type}:{args.model} -> "
+                    f"{staged if staged.exists() else root} ({exc}); "
+                    "rerun the same remove command to resume"
+                )
+                return 1
+            finish_removal_cleanup(config, staged)
+    except (OSError, ValueError) as exc:
+        print(f"remove failed: {args.repo_type}:{args.model} -> {exc}")
+        return 1
+
+    print(
+        f"removed: {args.repo_type}:{args.model} "
+        f"({record.payload_files} files, {format_bytes(record.payload_size)})"
+    )
+    return 0
+
+
+def resume_remove(args, config: Config, root: Path, staged: Path) -> int:
+    if staged.is_symlink() or not staged.is_dir():
+        print(f"remove refused unsafe interrupted-removal path: {staged}")
+        return 1
+    try:
+        record = read_removal_record(staged)
+    except ValueError:
+        record = None
+    if record is not None and (
+        record.repo_id != args.model or record.repo_type != args.repo_type
+    ):
+        print(
+            f"remove resume refused: removal record identity is "
+            f"{record.repo_type}:{record.repo_id}, expected {args.repo_type}:{args.model}"
+        )
+        return 1
+    record = record or inspect_removal(staged, args.model, args.repo_type, original_path=root)
+    print(f"interrupted removal found: {staged}")
+    print_removal_summary(record)
+    if not args.yes and not confirm_removal(args.model):
+        print(f"cancelled: interrupted removal remains at {staged}")
+        return 0
+    try:
+        complete_removal(staged)
+    except OSError as exc:
+        print(
+            f"removal still incomplete: {args.repo_type}:{args.model} -> {staged} ({exc}); "
+            "rerun the same remove command to resume"
+        )
+        return 1
+
+    finish_removal_cleanup(config, staged)
+    print(
+        f"removed interrupted mirror: {args.repo_type}:{args.model} "
+        f"({record.payload_files} original files, {format_bytes(record.payload_size)})"
+    )
+    if root.exists() or root.is_symlink():
+        print(f"note: a newer mirror still exists and was not removed: {root}")
+    return 0
+
+
+def inspect_removal(
+    root: Path,
+    repo_id: str,
+    repo_type: str,
+    *,
+    original_path: Path | None = None,
+) -> RemovalRecord:
+    payload_files, payload_size = mirror_payload_stats(root)
+    state = None
+    snapshot = None
+    exceptions: list[str] = []
+    try:
+        state = read_verification_state(root)
+    except (OSError, ValueError, yaml.YAMLError):
+        exceptions.append("verification-metadata-error")
+    try:
+        snapshot = read_snapshot_plan(root)
+    except (OSError, ValueError):
+        exceptions.append("snapshot-metadata-error")
+    if state is not None:
+        for tag in list_exception_tags(state, None):
+            append_unique(exceptions, tag)
+    if (
+        state is not None
+        and state.resolved_commit
+        and snapshot is not None
+        and snapshot.resolved_commit != state.resolved_commit
+    ):
+        append_unique(exceptions, "snapshot-stale")
+    resolved_commit = (
+        state.resolved_commit
+        if state is not None and state.resolved_commit
+        else snapshot.resolved_commit if snapshot is not None else ""
+    )
+    checked_at = state.checked_at_utc if state is not None else ""
+    return RemovalRecord(
+        repo_id=repo_id,
+        repo_type=repo_type,
+        original_path=str(original_path or root),
+        status=state.status if state is not None else "unverified",
+        exceptions=",".join(exceptions) or "none",
+        resolved_commit=resolved_commit,
+        checked_at_utc=checked_at or "unknown",
+        check_age=verification_age_label(checked_at) if checked_at else "unknown",
+        payload_files=payload_files,
+        payload_size=payload_size,
+    )
+
+
+def print_removal_summary(record: RemovalRecord) -> None:
+    print("mirror selected for permanent removal:")
+    print(f"  repository: {record.repo_id}")
+    print(f"  repo_type: {record.repo_type}")
+    print(f"  path: {record.original_path}")
+    print(f"  status: {record.status}")
+    print(f"  exceptions: {record.exceptions}")
+    print(f"  resolved_commit: {record.resolved_commit or 'unknown'}")
+    print(f"  last_checked: {record.checked_at_utc}")
+    print(f"  verification_age: {record.check_age}")
+    print(f"  payload_files: {record.payload_files}")
+    print(f"  payload_size: {format_bytes(record.payload_size)} ({record.payload_size} bytes)")
+
+
+def active_publication_removal_error(root: Path) -> str | None:
+    from .torrent_publication import load_fenced_publication
+
+    try:
+        fenced = load_fenced_publication(root)
+    except (OSError, ValueError) as exc:
+        return f"remove blocked: torrent publication state is unreadable: {exc}"
+    if fenced is None:
+        return None
+    record = fenced[0]
+    return (
+        f"remove blocked by active torrent publication {record.publication_id}. "
+        f"Stop any external client if applicable, then run "
+        f"'model-mirror torrent stop --repo-type {record.repo_type} {record.repo_id}' and "
+        f"'model-mirror torrent retire --repo-type {record.repo_type} {record.repo_id}'."
+    )
+
+
+def confirm_removal(repo_id: str) -> bool:
+    try:
+        response = input(f"Type '{repo_id}' to confirm permanent removal: ")
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    return response.strip() == repo_id
+
+
+def finish_removal_cleanup(config: Config, staged: Path) -> None:
+    prune_empty_removal_parents(
+        staged.parent,
+        stop=Path(config.directory) / REMOVALS_DIR,
+    )
+
+
+def collect_mirror_status(config: Config, *, repo_type: str | None = None) -> list[MirrorStatusEntry]:
+    archive_root = Path(config.directory)
+    entries: list[MirrorStatusEntry] = []
+    selected_types = [repo_type] if repo_type is not None else list(REPO_TYPE_DIRS)
+    for selected_type in selected_types:
+        type_dir = REPO_TYPE_DIRS[selected_type]
+        repo_root = archive_root / type_dir
+        if not repo_root.exists():
+            continue
+        for owner in sorted(path for path in repo_root.iterdir() if path.is_dir()):
+            for repo in sorted(path for path in owner.iterdir() if path.is_dir()):
+                repo_id = f"{owner.name}/{repo.name}"
+                entries.append(build_mirror_status(config, repo, repo_id, selected_type))
+    entries.sort(key=lambda entry: (entry.repo_type, entry.repo_id))
+    return entries
+
+
+def build_mirror_status(config: Config, root: Path, repo_id: str, repo_type: str) -> MirrorStatusEntry:
+    state = read_verification_state(root)
+    snapshot = read_snapshot_plan(root)
+    payload_files, payload_size, payload_source = recorded_payload_stats(root, snapshot)
+    if (
+        payload_source == "snapshot"
+        and state is not None
+        and state.resolved_commit
+        and snapshot is not None
+        and snapshot.resolved_commit != state.resolved_commit
+    ):
+        payload_files, payload_size, payload_source = None, None, "unknown"
+    expected_files = len(snapshot.files) if snapshot is not None else None
+    return MirrorStatusEntry(
+        root=root,
+        repo_id=repo_id,
+        repo_type=repo_type,
+        state=state,
+        active_lock=read_active_lock(root),
+        payload_files=payload_files,
+        payload_size=payload_size,
+        payload_source=payload_source,
+        expected_files=expected_files,
+        snapshot_commit=snapshot.resolved_commit if snapshot is not None else "",
+        snapshot_requested_revision=snapshot.requested_revision if snapshot is not None else "",
+        progress=progress_snapshot(
+            root,
+            stall_timeout_seconds=config.stall_timeout_seconds,
+            scan_incomplete=False,
+        ),
+        torrent_status=list_torrent_status(root),
+    )
+
+
+def recorded_payload_stats(root: Path, snapshot) -> tuple[int | None, int | None, str]:
+    manifest_path = root / MANIFEST
+    if manifest_path.exists():
+        manifest = load_manifest(root)
+        sizes = [row.get("size") for row in manifest.values()]
+        total_size = (
+            sum(sizes)
+            if all(isinstance(size, int) and not isinstance(size, bool) and size >= 0 for size in sizes)
+            else None
+        )
+        return len(manifest), total_size, "manifest"
+    if snapshot is not None:
+        sizes = [item.size for item in snapshot.files]
+        total_size = sum(sizes) if all(size is not None and size >= 0 for size in sizes) else None
+        return len(snapshot.files), total_size, "snapshot"
+    return None, None, "unknown"
+
+
+def observe_upstreams(config: Config, entries: list[MirrorStatusEntry], *, hub=None) -> None:
+    selected_hub = hub or HuggingFaceHub(config)
+    for entry in entries:
+        state = entry.state
+        requested_revision = (
+            state.requested_revision
+            if state is not None and state.requested_revision
+            else entry.snapshot_requested_revision or config.revision
+        )
+        observed_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        try:
+            snapshot = get_snapshot(selected_hub, entry.repo_id, entry.repo_type, requested_revision)
+        except Exception as exc:
+            entry.upstream_observation = UpstreamObservation(
+                status="unavailable",
+                commit=None,
+                observed_at_utc=observed_at,
+                error=str(exc),
+            )
+            continue
+        local_commit = resolved_commit_for_status(entry)
+        entry.upstream_observation = UpstreamObservation(
+            status=(
+                "available"
+                if not local_commit
+                else "current"
+                if local_commit == snapshot.resolved_commit
+                else "changed"
+            ),
+            commit=snapshot.resolved_commit,
+            observed_at_utc=observed_at,
+        )
+
+
+def print_mirror_table(entries: list[MirrorStatusEntry]) -> None:
+    headers = ["TYPE", "REPOSITORY", "FILES", "SIZE", "COMMIT", "CHECKED", "EXCEPTIONS"]
+    include_torrent = any(entry.torrent_status is not None for entry in entries)
+    include_activity = any(entry.progress.active for entry in entries)
+    include_live_upstream = any(entry.upstream_observation is not None for entry in entries)
+    if include_live_upstream:
+        headers.append("UPSTREAM NOW")
+    if include_torrent:
+        headers.append("TORRENT")
+    if include_activity:
+        headers.append("ACTIVITY")
+
+    rows = []
+    for entry in entries:
+        state = entry.state
+        commit = resolved_commit_for_status(entry)
+        row = [
+            entry.repo_type,
+            entry.repo_id,
+            file_count_label(entry),
+            format_optional_bytes(entry.payload_size),
+            shorten_commit(commit),
+            verification_age_label(state.checked_at_utc) if state is not None else "unknown",
+            ",".join(mirror_exception_tags(entry)) or "-",
+        ]
+        if include_live_upstream:
+            row.append(format_upstream_observation(entry.upstream_observation))
+        if include_torrent:
+            row.append(entry.torrent_status or "-")
+        if include_activity:
+            row.append(format_progress_detail(entry.progress) or "-")
+        rows.append(row)
+    print_table(headers, rows, right_aligned={"FILES", "SIZE"})
+
+
+def print_table(headers: list[str], rows: list[list[str]], *, right_aligned: set[str]) -> None:
+    widths = [
+        max([len(header), *(len(row[index]) for row in rows)])
+        for index, header in enumerate(headers)
+    ]
+
+    def formatted(row: list[str]) -> str:
+        cells = []
+        for index, value in enumerate(row):
+            if headers[index] in right_aligned:
+                cells.append(value.rjust(widths[index]))
+            else:
+                cells.append(value.ljust(widths[index]))
+        return "  ".join(cells).rstrip()
+
+    print(formatted(headers))
+    print(formatted(["-" * width for width in widths]))
+    for row in rows:
+        print(formatted(row))
+
+
+def print_mirror_detail(entry: MirrorStatusEntry) -> None:
+    state = entry.state
+    exceptions = mirror_exception_tags(entry)
+    print(entry.repo_id)
+    print()
+    status = state.status if state is not None else "unverified"
+    checked = verification_age_label(state.checked_at_utc) if state is not None else "unknown"
+    print_status_field("Verification", f"{status} · {checked} ago" if checked != "unknown" else status)
+    commit = resolved_commit_for_status(entry)
+    revision = (
+        state.requested_revision
+        if state is not None and state.requested_revision
+        else entry.snapshot_requested_revision or "unknown"
+    )
+    snapshot = shorten_commit(commit) if commit else "unknown"
+    print_status_field("Commit", f"{snapshot} · {revision}")
+    payload = (
+        f"{entry.payload_files} {'file' if entry.payload_files == 1 else 'files'} · "
+        f"{format_optional_bytes(entry.payload_size)}"
+        if entry.payload_files is not None
+        else "unknown"
+    )
+    print_status_field("Payload", payload)
+    print_status_field("Upstream", human_upstream_status(entry))
+    print_status_field("Torrent", entry.torrent_status or "not published")
+
+    if exceptions:
+        print_status_field("Attention", ", ".join(exceptions))
+    if entry.active_lock is not None:
+        print_status_field("Lock", format_lock_detail(entry.active_lock))
+    progress = format_progress_detail(entry.progress)
+    if progress is not None:
+        print_status_field("Activity", progress)
+
+    next_steps = status_next_steps(entry)
+    for index, step in enumerate(next_steps):
+        print_status_field("Next" if index == 0 else "", step)
+
+    if state is not None and state.repair_paths:
+        print()
+        print("Repair paths")
+        for value in state.repair_paths:
+            print(f"  {value}")
+    if state is not None and state.issues:
+        print()
+        print("Issues")
+        for value in state.issues:
+            print(f"  {value}")
+
+
+def print_status_field(label: str, value: str) -> None:
+    print(f"  {label:<14}{value}")
+
+
+def human_upstream_status(entry: MirrorStatusEntry) -> str:
+    observation = entry.upstream_observation
+    if observation is not None:
+        value = f"{observation.status} now"
+        if observation.commit:
+            value += f" · {shorten_commit(observation.commit)}"
+        if observation.error:
+            value += f" · {observation.error}"
+        return value
+    state = entry.state
+    if state is None or not state.upstream_status:
+        return "unknown"
+    suffix = " when last checked" if state.upstream_status != "unknown" else ""
+    return f"{state.upstream_status}{suffix}"
+
+
+def format_upstream_observation(observation: UpstreamObservation | None) -> str:
+    if observation is None:
+        return "-"
+    if observation.commit:
+        return f"{observation.status}:{shorten_commit(observation.commit)}"
+    return observation.status
+
+
+def status_next_steps(entry: MirrorStatusEntry) -> list[str]:
+    state = entry.state
+    if state is None:
+        return [f"model-mirror verify {entry.repo_id}"]
+    if primary_state_tag(state) == "unverified":
+        return [f"model-mirror verify {entry.repo_id}"]
+    steps = []
+    if state.repair_paths:
+        steps.append(f"model-mirror repair {entry.repo_id}")
+    if state.upstream_status == "changed":
+        steps.append(f"model-mirror repair --update {entry.repo_id}")
+    return steps
+
+
+def print_mirror_detail_verbose(entry: MirrorStatusEntry) -> None:
+    state = entry.state
+    exceptions = mirror_exception_tags(entry)
+    print(f"repository: {entry.repo_id}")
+    print(f"repo_type: {entry.repo_type}")
+    print(f"path: {entry.root}")
+    print(f"status: {state.status if state is not None else 'unverified'}")
+    print(f"exceptions: {','.join(exceptions) if exceptions else 'none'}")
+    print(f"last_checked: {state.checked_at_utc if state is not None and state.checked_at_utc else 'unknown'}")
+    print(f"last_check_age: {verification_age_label(state.checked_at_utc) if state is not None else 'unknown'}")
+    print(f"requested_revision: {state.requested_revision if state is not None else 'unknown'}")
+    print(f"resolved_commit: {resolved_commit_for_status(entry) or 'unknown'}")
+    print(f"snapshot_commit: {entry.snapshot_commit or 'unknown'}")
+    print(f"upstream_commit: {state.upstream_commit if state is not None and state.upstream_commit else 'unknown'}")
+    print(f"upstream_status: {state.upstream_status if state is not None else 'unknown'}")
+    print(f"offline_only: {str(state.offline_only).lower() if state is not None else 'unknown'}")
+    print(f"payload_files: {entry.payload_files if entry.payload_files is not None else 'unknown'}")
+    if entry.payload_size is None:
+        print("payload_size: unknown")
+    else:
+        print(f"payload_size: {format_bytes(entry.payload_size)} ({entry.payload_size} bytes)")
+    print(f"payload_source: {entry.payload_source}")
+    if entry.expected_files is None:
+        print("expected_files: unknown")
+    else:
+        stale_suffix = " (snapshot stale)" if snapshot_is_stale(entry) else ""
+        print(f"expected_files: {entry.expected_files} recorded{stale_suffix}")
+    print(f"lock: {format_lock_detail(entry.active_lock) if entry.active_lock is not None else 'none'}")
+    print(f"progress: {format_progress_detail(entry.progress) or 'none'}")
+    print(f"torrent: {entry.torrent_status or 'none'}")
+    observation = entry.upstream_observation
+    if observation is None:
+        print("live_upstream: not checked")
+    else:
+        detail = f"{observation.status} commit={observation.commit or 'unknown'} observed_at={observation.observed_at_utc}"
+        if observation.error:
+            detail += f" error={observation.error}"
+        print(f"live_upstream: {detail}")
+    print_detail_values("repair_paths", state.repair_paths if state is not None else [])
+    print_detail_values("issues", state.issues if state is not None else [])
+
+
+def print_status_json(
+    config: Config,
+    entries: list[MirrorStatusEntry],
+    errors: list[dict[str, str]],
+) -> None:
+    document = {
+        "schema": "model-mirror-status",
+        "version": 1,
+        "archive": str(Path(config.directory)),
+        "repositories": [mirror_status_json(entry) for entry in entries],
+        "errors": errors,
+    }
+    print(json.dumps(document, indent=2, sort_keys=True))
+
+
+def mirror_status_json(entry: MirrorStatusEntry) -> dict:
+    state = entry.state
+    observation = entry.upstream_observation
+    return {
+        "repo_id": entry.repo_id,
+        "repo_type": entry.repo_type,
+        "path": str(entry.root),
+        "requested_revision": (
+            state.requested_revision
+            if state is not None and state.requested_revision
+            else entry.snapshot_requested_revision or None
+        ),
+        "resolved_commit": resolved_commit_for_status(entry) or None,
+        "last_verification": {
+            "status": state.status if state is not None else "unverified",
+            "checked_at": state.checked_at_utc if state is not None and state.checked_at_utc else None,
+            "offline_only": state.offline_only if state is not None else None,
+            "issues": list(state.issues) if state is not None else [],
+            "repair_paths": list(state.repair_paths) if state is not None else [],
+        },
+        "payload": {
+            "files": entry.payload_files,
+            "bytes": entry.payload_size,
+            "source": entry.payload_source,
+        },
+        "snapshot": {
+            "commit": entry.snapshot_commit or None,
+            "expected_files": entry.expected_files,
+            "stale": snapshot_is_stale(entry),
+        },
+        "upstream": {
+            "recorded": {
+                "status": state.upstream_status if state is not None else "unknown",
+                "commit": state.upstream_commit if state is not None and state.upstream_commit else None,
+            },
+            "live": (
+                {
+                    "status": observation.status,
+                    "commit": observation.commit,
+                    "observed_at": observation.observed_at_utc,
+                    "error": observation.error,
+                }
+                if observation is not None
+                else None
+            ),
+        },
+        "exceptions": mirror_exception_tags(entry),
+        "lock": entry.active_lock,
+        "activity": [progress_entry_json(item) for item in entry.progress.entries],
+        "torrent": torrent_status_json(entry),
+    }
+
+
+def progress_entry_json(entry: ProgressEntry) -> dict:
+    return {
+        "path": entry.path,
+        "stage": entry.stage,
+        "bytes_done": entry.bytes_done,
+        "bytes_total": entry.bytes_total,
+        "updated_at": entry.updated_at_utc or None,
+        "idle_seconds": entry.idle_seconds,
+        "stalled": entry.stalled,
+        "source": entry.source,
+        "rate_bytes_per_second": entry.rate_bytes_per_second,
+    }
+
+
+def torrent_status_json(entry: MirrorStatusEntry) -> dict | None:
+    if entry.torrent_status is None:
+        return None
+    if entry.torrent_status == "metadata-error":
+        return {"status": "metadata-error"}
+    from .torrent_publication import load_fenced_publication
+
+    try:
+        fenced = load_fenced_publication(entry.root)
+    except (OSError, ValueError):
+        return {"status": "metadata-error"}
+    if fenced is None:
+        return None
+    record = fenced[0]
+    try:
+        coverage = torrent_coverage_status(entry.root)
+    except (OSError, ValueError, RuntimeError):
+        coverage = "metadata-error"
+    return {
+        "publication_id": record.publication_id,
+        "resolved_commit": record.resolved_commit,
+        "profile": record.profile,
+        "lifecycle": record.lifecycle,
+        "client_mode": record.client_mode,
+        "desired_seed": record.desired_seed,
+        "observed_backend": record.observed_backend,
+        "coverage": coverage,
+        "content_verification": record.content_verification,
+        "publication_trust": record.publication_trust,
+        "upstream_provenance": record.upstream_provenance,
+        "upstream_availability": record.upstream_availability,
+        "infohash_v1": record.infohash_v1,
+        "infohash_v2": record.infohash_v2,
+    }
+
+
+def print_detail_values(label: str, values: list[str]) -> None:
+    if not values:
+        print(f"{label}: none")
+        return
+    print(f"{label}:")
+    for value in values:
+        print(f"  - {value}")
+
+
+def resolved_commit_for_status(entry: MirrorStatusEntry) -> str:
+    if entry.state is not None and entry.state.resolved_commit:
+        return entry.state.resolved_commit
+    return entry.snapshot_commit
+
+
+def shorten_commit(commit: str) -> str:
+    return commit[:12] if commit else "-"
+
+
+def file_count_label(entry: MirrorStatusEntry) -> str:
+    return str(entry.payload_files) if entry.payload_files is not None else "?"
+
+
+def mirror_exception_tags(entry: MirrorStatusEntry) -> list[str]:
+    tags = list_exception_tags(entry.state, entry.active_lock, entry.progress)
+    if snapshot_is_stale(entry):
+        append_unique(tags, "snapshot-stale")
+    marker = removal_record_path(entry.root)
+    if marker.exists() or marker.is_symlink():
+        append_unique(tags, "removal-pending")
+    return tags
+
+
+def snapshot_is_stale(entry: MirrorStatusEntry) -> bool:
+    return bool(
+        entry.snapshot_commit
+        and entry.state is not None
+        and entry.state.resolved_commit
+        and entry.snapshot_commit != entry.state.resolved_commit
+    )
+
+
+def list_torrent_status(root: Path) -> str | None:
+    from .torrent_publication import load_fenced_publication
+
+    try:
+        fenced = load_fenced_publication(root)
+    except (OSError, ValueError):
+        return "metadata-error"
+    if fenced is None:
+        return None
+    record = fenced[0]
+    parts = [record.lifecycle, record.client_mode]
+    parts.append(f"desired={'seeding' if record.desired_seed else 'stopped'}")
+    parts.append(f"observed={record.observed_backend}")
+    state = read_verification_state(root)
+    if state is not None and state.upstream_status == "changed":
+        parts.append("update-available")
+    try:
+        coverage_status = torrent_coverage_status(root)
+    except (OSError, ValueError, RuntimeError):
+        coverage_status = "metadata-error"
+    parts.append(f"coverage={coverage_status}")
+    return ",".join(parts)
+
+
+def torrent_coverage_status(root: Path) -> str:
+    snapshot = read_snapshot_plan(root)
+    if snapshot is None:
+        return "unavailable"
+    from .torrent_coverage import TorrentCoverageRecorder
+
+    recorder = TorrentCoverageRecorder(root, snapshot)
+    return "complete" if recorder.complete else "partial"
+
+
+def archive_cache_usage(config: Config) -> CacheUsage:
+    archive_root = Path(config.directory)
+    cache_root = archive_runtime_cache_path(config)
+    tmp_root = archive_runtime_tmp_path(config)
+    return CacheUsage(
+        archive_cache=directory_size(cache_root),
+        archive_tmp=directory_size(tmp_root),
+        mirror_cache=sum(directory_size(path) for path in mirror_cache_dirs(archive_root)),
+    )
+
+
+def handle_clean_cache(config: Config, *, force: bool) -> int:
+    archive_root = Path(config.directory)
+    targets = cleanup_targets(config)
+    unsafe = [path for path, label in targets if not is_safe_cleanup_target(path, archive_root, label)]
+    if unsafe:
+        for path in unsafe:
+            print(f"refusing unsafe cleanup target: {path}")
+        return 1
+
+    sized_targets = [(path, label, directory_size(path)) for path, label in targets if path.exists()]
+    total_size = sum(size for _path, _label, size in sized_targets)
+    print(f"cleanup mode: {'force' if force else 'dry-run'}")
+    print(f"reclaimable={format_bytes(total_size)}")
+    for path, label, size in sized_targets:
+        if force:
+            shutil.rmtree(path)
+            action = "removed"
+        else:
+            action = "would-remove"
+        print(f"{action}: {label} {path} size={format_bytes(size)}")
+    return 0
+
+
+def cleanup_targets(config: Config) -> list[tuple[Path, str]]:
+    archive_root = Path(config.directory)
+    cache_root = archive_runtime_cache_path(config)
+    tmp_root = archive_runtime_tmp_path(config)
+    targets = [(cache_root, "archive-cache"), (tmp_root, "archive-tmp")]
+    selected = {path.resolve(strict=False) for path, _label in targets}
+    for path, label in (
+        (archive_root / ".cache", "legacy-archive-cache"),
+        (archive_root / ".tmp", "legacy-archive-tmp"),
+    ):
+        if path.resolve(strict=False) not in selected:
+            targets.append((path, label))
+    targets.extend((path, "mirror-cache") for path in mirror_cache_dirs(archive_root))
+    return targets
+
+
+def mirror_cache_dirs(archive_root: Path) -> list[Path]:
+    targets: list[Path] = []
+    for type_dir in REPO_TYPE_DIRS.values():
+        for repo in sorted((archive_root / type_dir).glob("*/*")):
+            targets.append(repo / ".cache")
+    return targets
+
+
+def is_safe_cleanup_target(path: Path, archive_root: Path, label: str) -> bool:
+    resolved_path = path.resolve(strict=False)
+    resolved_archive = archive_root.resolve(strict=False)
+    protected = {resolved_archive, *(resolved_archive / type_dir for type_dir in REPO_TYPE_DIRS.values())}
+    expected_names = {
+        "archive-cache": {"cache", ".cache"},
+        "archive-tmp": {"tmp", ".tmp"},
+        "legacy-archive-cache": {".cache"},
+        "legacy-archive-tmp": {".tmp"},
+        "mirror-cache": {".cache"},
+    }
+    return (
+        resolved_path.name in expected_names.get(label, set())
+        and resolved_path.is_relative_to(resolved_archive)
+        and resolved_path not in protected
+    )
+
+
+def directory_size(path: Path) -> int:
+    if not path.exists():
+        return 0
+    total_size = 0
+    for child in path.rglob("*"):
+        if child.is_file():
+            total_size += child.stat().st_size
+    return total_size
+
+
+def mirror_payload_stats(root: Path) -> tuple[int, int]:
+    files = 0
+    total_size = 0
+    for path in iter_payload_files(root):
+        files += 1
+        total_size += path.stat().st_size
+    return files, total_size
+
+
+def format_bytes(size: int) -> str:
+    value = float(size)
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB", "PiB"):  # pragma: no branch
+        if abs(value) < 1024 or unit == "PiB":
+            if unit == "B":
+                return f"{int(value)} B"
+            return f"{value:.1f} {unit}"
+        value /= 1024
+
+
+def format_optional_bytes(size: int | None) -> str:
+    return format_bytes(size) if size is not None else "unknown"
+
+
+def format_lock_detail(info: dict | None) -> str:
+    if not info:
+        return "lock held"
+    parts = []
+    for key in ("command", "pid", "host", "started_at_utc"):
+        value = info.get(key)
+        if value:
+            parts.append(f"{key}={value}")
+    return " ".join(parts) if parts else "lock held"
+
+
+def format_progress_detail(progress: ProgressSnapshot) -> str | None:
+    if not progress.active:
+        return None
+    entry = selected_progress_entry(progress.entries)
+    parts = [
+        f"active={len(progress.entries)}",
+        f"path={shorten_path(entry.path)}",
+        f"stage={entry.stage}",
+        f"bytes={format_progress_bytes(entry)}",
+    ]
+    rate = format_rate(entry.rate_bytes_per_second)
+    if rate is not None:
+        parts.append(f"rate={rate}")
+    if entry.idle_seconds is not None:
+        parts.append(f"idle={format_age_seconds(entry.idle_seconds)}")
+    if progress.stalled_count:
+        parts.append(f"stalled={progress.stalled_count}")
+    if entry.source != "heartbeat":
+        parts.append(f"source={entry.source}")
+    return " ".join(parts)
+
+
+def selected_progress_entry(entries: list[ProgressEntry]) -> ProgressEntry:
+    stalled = [entry for entry in entries if entry.stalled]
+    if stalled:
+        return max(stalled, key=lambda entry: entry.idle_seconds or 0)
+    return sorted(entries, key=lambda entry: entry.path)[0]
+
+
+def format_progress_bytes(entry: ProgressEntry) -> str:
+    if entry.bytes_total:
+        percent = (entry.bytes_done / entry.bytes_total) * 100
+        return f"{format_bytes(entry.bytes_done)}/{format_bytes(entry.bytes_total)}({percent:.1f}%)"
+    return format_bytes(entry.bytes_done)
+
+
+def format_rate(rate: float | None) -> str | None:
+    if rate is None:
+        return None
+    return f"{format_bytes(int(rate))}/s"
+
+
+def shorten_path(path: str, *, max_length: int = 48) -> str:
+    if len(path) <= max_length:
+        return path
+    return f"...{path[-(max_length - 3):]}"
+
+
+def list_state_tags(state, active_lock: dict | None, progress: ProgressSnapshot | None = None) -> list[str]:
+    tags = [primary_state_tag(state)]
+    if state.offline_only:
+        append_unique(tags, "offline")
+    if state.upstream_status == "changed":
+        append_unique(tags, "upstream-changed")
+    if state_has_upstream_unavailable(state):
+        append_unique(tags, "upstream-unavailable")
+    if active_lock is not None:
+        append_unique(tags, "busy")
+    if progress is not None and progress.any_stalled:
+        append_unique(tags, "stalled")
+    return tags
+
+
+def list_exception_tags(
+    state: VerificationState | None,
+    active_lock: dict | None,
+    progress: ProgressSnapshot | None = None,
+) -> list[str]:
+    if state is None:
+        tags = ["unverified"]
+        if active_lock is not None:
+            tags.append("busy")
+        if progress is not None and progress.any_stalled:
+            tags.append("stalled")
+        return tags
+    tags = list_state_tags(state, active_lock, progress)
+    return [tag for tag in tags if tag != "clean"]
+
+
+def primary_state_tag(state) -> str:
+    if state.status == "unavailable":
+        return "upstream-unavailable"
+    if state.status == "incomplete":
+        if state_has_manifest_incomplete(state):
+            return "manifest-incomplete"
+        return "incomplete"
+    if state.status == "dirty":
+        if state.repair_paths:
+            return "needs-repair"
+        if any(str(issue) == "verification skipped" for issue in state.issues):
+            return "unverified"
+        return "dirty"
+    if state.status == "in_progress":
+        return "in-progress"
+    return state.status or "unknown"
+
+
+def append_unique(values: list[str], value: str) -> None:
+    if value not in values:
+        values.append(value)
+
+
+def state_has_manifest_incomplete(state) -> bool:
+    return state_has_cached_hash_missing(state) or any(".manifest missing" in str(issue) for issue in state.issues)
+
+
+def handle_verify(args, config: Config, *, hub=None) -> int:
+    if args.all:
+        failures = 0
+        changed = 0
+        repair_needed = 0
+        cache_incomplete = 0
+        for repo_id in list_model_ids(config):
+            if args.max_age and should_skip_recent_clean(config, repo_id, args.repo_type, args.max_age):
+                print(f"skipped recent clean verification: {repo_id}")
+                continue
+            try:
+                rc = verify_one(config, repo_id, args, hub=hub)
+            except ModelBusyError as exc:
+                print(f"skipped busy: {repo_id} -> {exc.root} ({lock_label(exc.info)})")
+                failures += 1
+                continue
+            state = read_verification_state(archive_path(config, repo_id, args.repo_type))
+            if state is not None and state.upstream_status == "changed":
+                changed += 1
+            if rc != 0:
+                failures += 1
+                if state is not None and state.repair_paths:
+                    repair_needed += 1
+                if state is not None and state_has_cached_hash_missing(state):
+                    cache_incomplete += 1
+        if repair_needed:
+            print("next: model-mirror repair --all")
+        if cache_incomplete:
+            print("cached verification incomplete: run full verification with model-mirror verify --all")
+        if changed:
+            print("update changed upstreams: model-mirror repair --all --update")
+        return 1 if failures else 0
+
+    if not args.model:
+        raise SystemExit("verify requires a model id unless --all is used")
+    return verify_one(config, args.model, args, hub=hub)
+
+
+def handle_repair(args, config: Config, *, hub=None) -> int:
+    if args.all and args.model:
+        raise SystemExit("repair accepts a model id or --all, not both")
+    if args.all:
+        failures = 0
+        for repo_id in list_model_ids(config):
+            state = read_verification_state(archive_path(config, repo_id, args.repo_type))
+            if state is not None and state.offline_only:
+                print(f"skipped offline-only: {repo_id}; repair requires an upstream repository")
+                continue
+            try:
+                rc = repair_one(config, repo_id, args, hub=hub)
+            except ModelBusyError as exc:
+                print(f"skipped busy: {repo_id} -> {exc.root} ({lock_label(exc.info)})")
+                failures += 1
+                continue
+            if rc != 0:
+                failures += 1
+        return 1 if failures else 0
+
+    if not args.model:
+        raise SystemExit("repair requires a model id unless --all is used")
+    return repair_one(config, args.model, args, hub=hub)
+
+
+def handle_upgrade(args, config: Config) -> int:
+    if args.all and args.model:
+        raise SystemExit("upgrade accepts a model id or --all, not both")
+    if not args.all and not args.model:
+        raise SystemExit("upgrade requires a model id unless --all is used")
+    repo_ids = list_repo_ids(config, args.repo_type) if args.all else [args.model]
+    failures = 0
+    for repo_id in repo_ids:
+        root = archive_path(config, repo_id, args.repo_type)
+        try:
+            with ModelLock(root, "upgrade", repo_id, args.repo_type):
+                snapshot = read_snapshot_plan(root)
+                if snapshot is None:
+                    print(
+                        f"upgrade unavailable: {repo_id} has no pinned snapshot description; "
+                        f"run model-mirror verify {repo_id}"
+                    )
+                    failures += 1
+                    continue
+                from .torrent_coverage import upgrade_coverage
+
+                result = upgrade_coverage(
+                    root,
+                    snapshot,
+                    dry_run=args.dry_run,
+                    on_progress=lambda rel, done, total: print_upgrade_progress(
+                        repo_id,
+                        rel,
+                        done,
+                        total,
+                    ),
+                )
+        except (OSError, ValueError, RuntimeError) as exc:
+            print(f"upgrade failed: {repo_id} -> {exc}")
+            failures += 1
+            continue
+        action = "would-hash" if args.dry_run else "hashed"
+        print(
+            f"{'upgrade dry-run' if args.dry_run else 'upgraded'}: {repo_id} "
+            f"coverage={result.covered_files}/{result.total_files} "
+            f"{action}_files={result.hashed_files} {action}_bytes={format_bytes(result.hashed_bytes)} "
+            f"path={result.path}"
+        )
+        if not result.complete and not args.dry_run:
+            failures += 1
+    return 1 if failures else 0
+
+
+def print_upgrade_progress(repo_id: str, rel: str, done: int, total: int) -> None:
+    if done == total:
+        print(f"hashed: {repo_id}:{rel} {format_bytes(total)}")
+
+
+def handle_torrent(args, config: Config) -> int:
+    if args.torrent_command is None:
+        print("torrent requires a subcommand; run model-mirror help torrent")
+        return 2
+    if args.torrent_command == "serve":
+        from .torrent_seed import serve
+
+        print(
+            f"managed torrent backend: {'single reconciliation' if args.once else 'serving'} "
+            f"archive={config.directory}"
+        )
+        try:
+            serve(config, poll_seconds=args.poll_seconds, once=args.once)
+        except (OSError, ValueError, RuntimeError) as exc:
+            print(f"managed torrent backend failed: {exc}")
+            return 1
+        return 0
+    if args.torrent_command in {"handoff", "import", "join"}:
+        return handle_torrent_receive(args, config)
+
+    root = archive_path(config, args.model, args.repo_type)
+    if args.torrent_command == "retire":
+        return handle_torrent_retire(args, root)
+    try:
+        with ModelLock(root, f"torrent-{args.torrent_command}", args.model, args.repo_type):
+            return handle_torrent_locked(args, root)
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"torrent {args.torrent_command} failed: {args.model} -> {exc}")
+        return 1
+
+
+def handle_torrent_locked(args, root: Path) -> int:
+    from .torrent_publication import (
+        create_publication,
+        load_fenced_publication,
+        set_seed_desired,
+    )
+
+    if args.torrent_command in {"create", "publish"}:
+        external = bool(args.external)
+        result = create_publication(
+            root,
+            repo_id=args.model,
+            repo_type=args.repo_type,
+            desired_seed=args.torrent_command == "publish" and not external,
+            client_mode="external" if external else "managed",
+        )
+        action = "created" if result.created else "reused"
+        print(
+            f"torrent {action}: {result.record.publication_id} "
+            f"coverage_hashed_files={result.coverage_hashed_files} "
+            f"coverage_hashed_bytes={format_bytes(result.coverage_hashed_bytes)}"
+        )
+        print_torrent_handoff(result.record, root)
+        if args.torrent_command == "publish" and not external:
+            print("desired seed: enabled; model-mirror torrent serve reconciles it now and after restart")
+        elif external:
+            print("client mode: external; model-mirror records the fence but does not manage client runtime")
+        return 0
+    if args.torrent_command == "show":
+        fenced = load_fenced_publication(root)
+        if fenced is None:
+            print(f"unpublished: {args.model}")
+            return 0
+        print_torrent_status(fenced[0], root)
+        return 0
+    if args.torrent_command == "stop":
+        record = set_seed_desired(root, desired=False)
+        print(f"torrent stopping: {record.publication_id}; publication fence retained")
+        return 0
+    raise ValueError(f"unsupported torrent command: {args.torrent_command}")
+
+
+def handle_torrent_retire(args, root: Path) -> int:
+    from .torrent_publication import (
+        retire_publication,
+        set_seed_desired,
+        wait_for_maintenance_detach,
+    )
+
+    try:
+        with ModelLock(root, "torrent-retire-stop", args.model, args.repo_type):
+            set_seed_desired(root, desired=False)
+        wait_for_maintenance_detach(root)
+        with ModelLock(root, "torrent-retire", args.model, args.repo_type):
+            record = retire_publication(root)
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"torrent retire failed: {args.model} -> {exc}")
+        return 1
+    print(
+        f"torrent retired: {record.publication_id}; local update fence released. "
+        "Already distributed torrent metadata cannot be revoked."
+    )
+    return 0
+
+
+def print_torrent_handoff(record, root: Path) -> None:
+    print(f"torrent: {root / record.torrent_path}")
+    print(f"recovery: {root / record.recovery_path}")
+    print(f"magnet: {record.magnet_uri}")
+    print(f"external client data location: {root.parent}")
+
+
+def handle_torrent_receive(args, config: Config) -> int:
+    from .torrent_import import (
+        external_handoff,
+        import_external_payload,
+        join_torrent,
+        parse_publication_metainfo,
+    )
+
+    try:
+        if args.torrent_command == "handoff":
+            metainfo = args.torrent_file.read_bytes()
+            parsed = parse_publication_metainfo(metainfo)
+            destination, command = external_handoff(config, parsed, args.torrent_file)
+            print(f"publication: huggingface:{parsed.descriptor.repo_type}:{parsed.descriptor.repo_id}@{parsed.descriptor.resolved_commit}")
+            print(f"external client data location: {destination}")
+            print(f"after download: {command}")
+            return 0
+        if args.torrent_command == "import":
+            result = import_external_payload(
+                config,
+                metainfo=args.torrent_file.read_bytes(),
+                payload_root=args.payload_root,
+                seed=args.seed,
+            )
+        else:
+            result = join_torrent(
+                config,
+                args.source,
+                seed=args.seed,
+                metadata_timeout_seconds=args.metadata_timeout,
+                on_progress=print_join_progress,
+            )
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"torrent {args.torrent_command} failed: {exc}")
+        return 1
+    print(
+        f"torrent imported: {result.publication.publication_id} -> {result.path} "
+        f"reread_files={result.reread_files} reread_bytes={format_bytes(result.reread_bytes)}"
+    )
+    print(
+        "content=torrent-verified publication_trust=trusted-infohash "
+        "upstream_provenance=not-upstream-verified upstream_availability=unknown"
+    )
+    print_torrent_handoff(result.publication, result.path)
+    if result.publication.desired_seed:
+        print("desired seed: enabled; model-mirror torrent serve will reconcile it")
+    return 0
+
+
+def print_join_progress(status) -> None:
+    print(
+        f"torrent download: {status.name} {status.progress * 100:.1f}% "
+        f"rate={format_bytes(int(status.download_payload_rate))}/s peers={status.num_peers}"
+    )
+
+
+def print_torrent_status(record, root: Path) -> None:
+    print("feature_stability: experimental")
+    print(f"publication: {record.publication_id}")
+    print(f"lifecycle: {record.lifecycle}")
+    print(f"resolved_commit: {record.resolved_commit}")
+    print(f"profile: {record.profile}")
+    print(f"content_verification: {record.content_verification}")
+    print(f"publication_trust: {record.publication_trust}")
+    print(f"upstream_provenance: {record.upstream_provenance}")
+    print(f"upstream_availability: {record.upstream_availability}")
+    state = read_verification_state(root)
+    print(
+        f"update_available: "
+        f"{str(state is not None and state.upstream_status == 'changed').lower()}"
+    )
+    print("archive_schema: model-mirror-snapshot/1")
+    print(f"coverage_profile: {record.profile}")
+    print(f"coverage_state: {torrent_coverage_status(root)}")
+    print(f"client_mode: {record.client_mode}")
+    print(f"desired_seed: {str(record.desired_seed).lower()}")
+    print(f"observed_backend: {record.observed_backend}")
+    if record.observed_detail:
+        print(f"observed_detail: {record.observed_detail}")
+    print(f"infohash_v1: {record.infohash_v1}")
+    print(f"infohash_v2: {record.infohash_v2}")
+    print_torrent_handoff(record, root)
+
+
+def state_has_cached_hash_missing(state) -> bool:
+    return any(str(issue).startswith("cached_hash_missing:") for issue in state.issues)
+
+
+def state_has_upstream_unavailable(state) -> bool:
+    return state.status == "unavailable" or any(
+        str(issue).startswith("upstream unavailable:") for issue in state.issues
+    )
+
+
+def repair_one(config: Config, repo_id: str, args, *, hub=None) -> int:
+    selected_hub = hub or HuggingFaceHub(config)
+    print_verification_age(config, repo_id, args.repo_type)
+    if args.force_partial:
+        print(
+            "warning: --force-partial can leave the repository inconsistent when verification data is incomplete"
+        )
+    result = repair(
+        config,
+        repo_id,
+        hub=selected_hub,
+        repo_type=args.repo_type,
+        update=args.update,
+        force_partial=args.force_partial,
+    )
+    if result.status == "verify-required":
+        print(f"run verify first: model-mirror verify {repo_id}")
+    if result.status == "verification-incomplete":
+        print(
+            f"could not fully repair {repo_id}; missing verification data for some files. "
+            f"Run full verify and repair again: model-mirror verify {repo_id} && model-mirror repair {repo_id}"
+        )
+    if result.status == "offline-only":
+        print(
+            f"cannot repair offline-only model {repo_id}; upstream link is disabled. "
+            f"Run model-mirror online {repo_id} to re-enable Hub-backed repair."
+        )
+    print_repair_commit_notice(repo_id, result)
+    print(f"{result.status}: {repo_id} -> {result.path}")
+    return 0 if result.status in {"complete", "repaired", "updated"} else 1
+
+
+def verify_one(config: Config, repo_id: str, args, *, hub=None) -> int:
+    selected_hub = hub or HuggingFaceHub(config)
+    root = archive_path(config, repo_id, args.repo_type)
+    with ModelLock(root, "verify", repo_id, args.repo_type):
+        return verify_one_locked(config, repo_id, args, selected_hub, root)
+
+
+def verify_one_locked(config: Config, repo_id: str, args, selected_hub, root: Path) -> int:
+    existing_state = read_verification_state(root)
+    requested_revision = selected_revision_arg(args) or (
+        existing_state.requested_revision if existing_state else config.revision
+    )
+
+    if args.offline:
+        return verify_one_offline(config, root, repo_id, args, existing_state, mode="offline")
+    if existing_state is not None and existing_state.offline_only:
+        return verify_one_offline(config, root, repo_id, args, existing_state, mode="offline-only")
+
+    try:
+        upstream_snapshot = get_snapshot(selected_hub, repo_id, args.repo_type, requested_revision)
+    except Exception as exc:
+        return handle_upstream_unavailable(root, repo_id, args, existing_state, requested_revision, exc)
+    resolved_commit = existing_state.resolved_commit if existing_state and existing_state.resolved_commit else upstream_snapshot.resolved_commit
+    try:
+        snapshot = upstream_snapshot if resolved_commit == upstream_snapshot.resolved_commit else get_snapshot(
+            selected_hub, repo_id, args.repo_type, resolved_commit
+        )
+    except Exception as exc:
+        return handle_upstream_unavailable(root, repo_id, args, existing_state, requested_revision, exc)
+    metadata = snapshot.files
+    checksum_result = None
+    manifest_verified = False
+    if not args.cached and config.checksum:
+        if (root / MANIFEST).exists():
+            checksum_result = verify_checksums(root, strict=args.strict)
+            if checksum_result.ok:
+                write_checksums(root, max_workers=config.checksum_workers)
+                manifest_verified = True
+        else:
+            write_checksums(root, max_workers=config.checksum_workers)
+            manifest_verified = True
+    from_manifest = args.cached or manifest_verified
+    result = verify_remote(
+        root,
+        metadata,
+        cached=args.cached,
+        from_manifest=from_manifest,
+        strict=args.strict,
+    )
+    if checksum_result is not None:
+        merge_checksum_result(result, checksum_result)
+    if args.repo_type == "model":
+        audit = audit_model(root, skip_transformers=True)
+    else:
+        audit = None
+    state = state_from_results(
+        repo_id,
+        args.repo_type,
+        requested_revision,
+        result,
+        audit,
+        resolved_commit=resolved_commit,
+        upstream_commit=upstream_snapshot.resolved_commit,
+    )
+    write_verification_state(root, state)
+
+    if state.status == "incomplete":
+        print(f"cached verification incomplete: {repo_id}{upstream_change_suffix(state)}")
+        print(f"run full verification: model-mirror verify {repo_id}")
+        if state.upstream_status == "changed":
+            print_update_next_step(repo_id)
+        return 1
+    if audit is not None and not audit.ok:
+        print(f"verification failed: {repo_id}{upstream_change_suffix(state)}")
+        print_verification_next_steps(repo_id, state)
+        return 1
+    if result.ok:
+        mode = "cached" if args.cached else "full"
+        print(f"verified ({mode}): {repo_id}{upstream_change_suffix(state)}")
+        if state.upstream_status == "changed":
+            print_update_next_step(repo_id)
+        return 0
+    print(f"verification failed: {repo_id}{upstream_change_suffix(state)}")
+    print_verification_next_steps(repo_id, state)
+    return 1
+
+
+def upstream_change_suffix(state) -> str:
+    return " upstream=changed" if state.upstream_status == "changed" else ""
+
+
+def print_verification_next_steps(repo_id: str, state) -> None:
+    if state.repair_paths:
+        print(f"next: model-mirror repair {repo_id}")
+    if state.upstream_status == "changed":
+        print_update_next_step(repo_id)
+
+
+def print_update_next_step(repo_id: str) -> None:
+    print(f"update changed upstream: model-mirror repair --update {repo_id}")
+
+
+def print_repair_commit_notice(repo_id: str, result) -> None:
+    if result.upstream_status == "changed":
+        print(
+            f"upstream changed: {repo_id} local={result.resolved_commit} "
+            f"upstream={result.upstream_commit} not_applied"
+        )
+
+
+def verify_one_offline(config: Config, root: Path, repo_id: str, args, existing_state, *, mode: str) -> int:
+    if existing_state is None:
+        print(f"{mode} verification unavailable: {repo_id}")
+        return 1
+    if args.cached:
+        print(f"verified ({mode} cached): {repo_id} state={existing_state.status}")
+        return 0 if existing_state.clean else 1
+    if not (root / MANIFEST).exists():
+        state = local_incomplete_state(repo_id, args.repo_type, existing_state, f"{MANIFEST} missing")
+        write_verification_state(root, state)
+        print(f"{mode} verification incomplete: {repo_id} missing {MANIFEST}")
+        return 1
+    result = verify_checksums(root, strict=args.strict)
+    remote_result = RemoteVerifyResult(
+        missing=result.missing,
+        hash_mismatches=result.failures,
+        extras=result.extras,
+    )
+    state = state_from_results(
+        repo_id,
+        args.repo_type,
+        existing_state.requested_revision,
+        remote_result,
+        resolved_commit=existing_state.resolved_commit,
+        upstream_commit=existing_state.upstream_commit,
+        offline_only=existing_state.offline_only,
+    )
+    write_verification_state(root, state)
+    if result.ok:
+        print(f"verified ({mode} full): {repo_id}")
+        return 0
+    print(f"{mode} verification failed: {repo_id}")
+    if existing_state.offline_only:
+        print(f"repair unavailable for offline-only model: {repo_id}")
+    else:
+        print_verification_next_steps(repo_id, state)
+    return 1
+
+
+def local_incomplete_state(repo_id: str, repo_type: str, existing_state, issue: str) -> VerificationState:
+    return VerificationState(
+        status="incomplete",
+        repo_id=repo_id,
+        repo_type=repo_type,
+        requested_revision=existing_state.requested_revision,
+        resolved_commit=existing_state.resolved_commit,
+        upstream_commit=existing_state.upstream_commit,
+        upstream_status=existing_state.upstream_status,
+        offline_only=existing_state.offline_only,
+        repair_paths=[],
+        issues=[issue],
+    )
+
+
+def handle_upstream_unavailable(
+    root: Path,
+    repo_id: str,
+    args,
+    existing_state,
+    requested_revision: str,
+    exc: Exception,
+) -> int:
+    issue = f"upstream unavailable: {exc}"
+    if existing_state is not None:
+        issues = [item for item in existing_state.issues if not str(item).startswith("upstream unavailable:")]
+        issues.append(issue)
+        state = VerificationState(
+            status=existing_state.status,
+            repo_id=repo_id,
+            repo_type=args.repo_type,
+            requested_revision=requested_revision,
+            resolved_commit=existing_state.resolved_commit,
+            upstream_commit=existing_state.upstream_commit,
+            upstream_status=existing_state.upstream_status,
+            offline_only=existing_state.offline_only,
+            repair_paths=existing_state.repair_paths,
+            issues=issues,
+            checked_at_utc=existing_state.checked_at_utc,
+        )
+    else:
+        state = VerificationState(
+            status="unavailable",
+            repo_id=repo_id,
+            repo_type=args.repo_type,
+            requested_revision=requested_revision,
+            issues=[issue],
+        )
+    write_verification_state(root, state)
+    print(f"verification failed: {repo_id} upstream repository unavailable: {exc}")
+    print(
+        f"if the source repository is no longer available and you want to keep this local mirror, "
+        f"run: model-mirror offline {repo_id}"
+    )
+    return 1
+
+
+def handle_offline_mode(args, config: Config, *, offline_only: bool) -> int:
+    command = "offline" if offline_only else "online"
+    root = archive_path(config, args.model, args.repo_type)
+    with ModelLock(root, command, args.model, args.repo_type):
+        state = read_verification_state(root)
+        if state is None:
+            print(f"verification state unavailable: {args.model}")
+            print(f"run verify first: model-mirror verify {args.model}")
+            return 1
+        state.offline_only = offline_only
+        if offline_only:
+            state.issues = [item for item in state.issues if not str(item).startswith("upstream unavailable:")]
+            if state.status == "unavailable":
+                state.status = "incomplete"
+                state.issues.append("local verification required")
+        write_verification_state(root, state)
+    if offline_only:
+        print(f"offline-only enabled: {args.model}")
+    else:
+        print(f"offline-only disabled: {args.model}")
+    return 0
+
+
+def list_model_ids(config: Config) -> list[str]:
+    return list_repo_ids(config, "model")
+
+
+def list_repo_ids(config: Config, repo_type: str) -> list[str]:
+    repos_root = Path(config.directory) / REPO_TYPE_DIRS[repo_type]
+    if not repos_root.exists():
+        return []
+    result = []
+    for owner in sorted(path for path in repos_root.iterdir() if path.is_dir()):
+        for repo in sorted(path for path in owner.iterdir() if path.is_dir()):
+            result.append(f"{owner.name}/{repo.name}")
+    return result
+
+
+def parse_age(value: str) -> int:
+    units = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+    value = value.strip().lower()
+    if not value:
+        raise ValueError("empty age")
+    unit = value[-1]
+    if unit in units:
+        return int(value[:-1]) * units[unit]
+    return int(value)
+
+
+def verification_age_seconds(checked_at_utc: str) -> int | None:
+    if not checked_at_utc:
+        return None
+    try:
+        checked = datetime.fromisoformat(checked_at_utc)
+    except ValueError:
+        return None
+    if checked.tzinfo is None:
+        checked = checked.replace(tzinfo=timezone.utc)
+    return max(0, int((datetime.now(timezone.utc) - checked).total_seconds()))
+
+
+def verification_age_label(checked_at_utc: str) -> str:
+    seconds = verification_age_seconds(checked_at_utc)
+    return format_age_seconds(seconds)
+
+
+def format_age_seconds(seconds: int | None) -> str:
+    if seconds is None:
+        return "unknown"
+    if seconds < 120:
+        return f"{seconds}s"
+    minutes = seconds // 60
+    if minutes < 120:
+        return f"{minutes}m"
+    hours = minutes // 60
+    if hours < 48:
+        return f"{hours}h"
+    return f"{hours // 24}d"
+
+
+def print_verification_age(config: Config, repo_id: str, repo_type: str) -> None:
+    root = archive_path(config, repo_id, repo_type)
+    state = read_verification_state(root)
+    if state is None:
+        print("verification age: unavailable")
+        return
+    age = verification_age_seconds(state.checked_at_utc)
+    if age is None:
+        path = verification_state_path(root)
+        modified = datetime.fromtimestamp(path.stat().st_mtime, timezone.utc)
+        age = max(0, int((datetime.now(timezone.utc) - modified).total_seconds()))
+    print(f"verification age: {format_age_seconds(age)}")
+    if age is not None and age > 24 * 60 * 60:
+        print("warning: verification is older than 24h; run verify again for fresh repair paths")
+
+
+def should_skip_recent_clean(config: Config, repo_id: str, repo_type: str, max_age: str) -> bool:
+    state = read_verification_state(archive_path(config, repo_id, repo_type))
+    if state is None or not state.clean or state_has_upstream_unavailable(state):
+        return False
+    age = verification_age_seconds(state.checked_at_utc)
+    return age is not None and age <= parse_age(max_age)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())