llmt-cli 0.2.0__py3-none-any.whl

llmt/doctor.py

@@ -0,0 +1,970 @@
+"""``llmt doctor`` core — diagnose why your seeds aren't seeding (WP-14.4b).
+
+Red-team finding 2: many willing seeders are silently useless — blocked
+ports, CGNAT, VPN misbinding, pathological upload caps, disabled DHT/PEX,
+queueing or ratio limits that quietly stopped the torrents, wrong content
+paths, non-seeding add states. ``llmt doctor`` reads the torrent client's
+OWN state and settings and prints one boring, practical
+PASS / WARN / FAIL / N-A line per check, with a one-line fix hint on every
+non-PASS.
+
+Honesty contract (D15): every check labels what it can actually observe.
+Almost every signal here is the client's self-reported view over its local
+API — "connection status: connected" means *the client says so*, not that
+llmt probed your port from the internet. Where a client's API does not
+expose a signal at all, the check reports N-A with the reason — never PASS.
+
+Fail-closed: a torrent whose state this module does not recognize is NEVER
+reported healthy; it FAILs with an "unknown state" diagnosis. A torrent that
+is not 100% complete is NEVER healthy.
+
+Doctor is strictly read-only diagnosis: it never adds, resumes, rechecks,
+moves, hashes, or offers anything, so it cannot create a back-door around
+the WP-14.4-S seed-safety invariant (only full-file SHA-256 registry
+matches are ever offered for seeding, and only by ``llmt scan``).
+
+This module builds ON TOP of the frozen WP-14.4-S adapters in ``clients.py``
+(``QBittorrentClient`` / ``TransmissionClient``) without modifying them: the
+read-only sources below reuse each adapter's authenticated session / RPC
+plumbing additively (``_login``/``_headers``/``session`` for qBittorrent,
+``_rpc`` for Transmission).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+import requests
+
+from .clients import ClientError, QBittorrentClient, TransmissionClient
+from .layout import DEFAULT_BASE_DIR, MODE_DIRECT, MODE_LINKFARM  # noqa: F401
+from .output import human_size, safe_text
+
+# Check statuses.
+PASS = "PASS"
+WARN = "WARN"
+FAIL = "FAIL"
+NA = "N-A"
+
+#: An upload cap at or below this (bytes/s) is plainly pathological for
+#: seeding multi-GB models. A *reasonable* cap (e.g. 1 MB/s) must not warn.
+PATHOLOGICAL_UP_CAP_BPS = 50 * 1024
+
+#: Exit code when doctor finds at least one FAIL (0 = no failures found).
+#: Chosen outside the 1-14 range already used by errors.py / clients.py.
+EXIT_DOCTOR_FAIL = 15
+
+#: Bound on per-torrent tracker fetches (one API call each on qBittorrent).
+MAX_TRACKER_FETCH = 100
+
+#: Bound on files walked when inspecting a multi-file content directory.
+MAX_LAYOUT_WALK = 256
+
+
+# --------------------------------------------------------------------------- #
+# Snapshot data model (what a source can actually observe; None = not exposed)
+# --------------------------------------------------------------------------- #
+
+@dataclass
+class TrackerStatus:
+    url: str
+    state: str          # "working"|"updating"|"not-contacted"|"not-working"|"disabled"
+    message: str = ""
+
+
+@dataclass
+class TorrentHealth:
+    info_hash: str
+    name: str
+    raw_state: str
+    category: str                     # seeding|downloading|paused|queued|
+                                      # checking|errored|unknown
+    progress: Optional[float]         # 0.0-1.0, None = client didn't say
+    save_path: str = ""
+    content_path: str = ""
+    ratio: Optional[float] = None
+    ratio_limit: Optional[float] = None   # effective applicable limit, None=none
+    error_message: str = ""
+    trackers: Optional[list] = None       # None = not fetched / not exposed
+
+    def label(self) -> str:
+        h = (self.info_hash or "")[:8]
+        return f"{safe_text(self.name) or '(unnamed)'} ({h or 'no-hash'})"
+
+
+@dataclass
+class ClientSnapshot:
+    kind: str
+    endpoint: str
+    reachable: bool
+    reach_error: str = ""
+    version: str = ""
+    connection_status: Optional[str] = None   # qBt self-view: connected/
+                                              # firewalled/disconnected
+    port_open: Optional[bool] = None          # Transmission daemon port-test
+    dht_enabled: Optional[bool] = None
+    pex_enabled: Optional[bool] = None
+    upload_limit_bps: Optional[int] = None    # None = not exposed; <=0 = uncapped
+    bound_interface: Optional[str] = None     # None = not exposed; "" = not bound
+    queueing_enabled: Optional[bool] = None
+    global_ratio_limit: Optional[float] = None  # None = disabled/unknown
+    client_default_save_path: str = ""        # client's own default save dir
+                                              # (the client's perspective); ""
+                                              # = not exposed
+    torrents: list = field(default_factory=list)
+
+
+@dataclass
+class CheckResult:
+    check: str
+    scope: str      # "client" or the torrent label
+    status: str     # PASS | WARN | FAIL | N-A
+    detail: str
+    hint: str = ""  # one-line fix hint; required by convention on non-PASS
+
+    def to_dict(self) -> dict:
+        return {"check": self.check, "scope": self.scope,
+                "status": self.status, "detail": self.detail,
+                "hint": self.hint}
+
+
+# --------------------------------------------------------------------------- #
+# State normalization (fail-closed: unmapped -> "unknown", never healthy)
+# --------------------------------------------------------------------------- #
+
+_QBT_STATE_MAP = {
+    "uploading": "seeding", "stalledUP": "seeding", "forcedUP": "seeding",
+    "queuedUP": "queued", "queuedDL": "queued",
+    "pausedUP": "paused", "pausedDL": "paused",
+    "stoppedUP": "paused", "stoppedDL": "paused",
+    "checkingUP": "checking", "checkingDL": "checking",
+    "checkingResumeData": "checking", "moving": "checking",
+    "allocating": "downloading", "downloading": "downloading",
+    "stalledDL": "downloading", "forcedDL": "downloading",
+    "metaDL": "downloading", "forcedMetaDL": "downloading",
+    "error": "errored", "missingFiles": "errored",
+}
+
+_TR_STATUS_MAP = {
+    0: "paused", 1: "checking", 2: "checking", 3: "queued",
+    4: "downloading", 5: "queued", 6: "seeding",
+}
+
+_QBT_TRACKER_MAP = {
+    0: "disabled", 1: "not-contacted", 2: "working",
+    3: "updating", 4: "not-working",
+}
+
+
+# --------------------------------------------------------------------------- #
+# Read-only sources over the frozen adapters (additive; clients.py untouched)
+# --------------------------------------------------------------------------- #
+
+class DoctorSource:
+    """Read-only view of one torrent client. ``snapshot`` never mutates the
+    client and never adds/starts/stops anything."""
+
+    kind = "base"
+
+    def snapshot(self, hashes: Optional[set] = None) -> ClientSnapshot:
+        raise NotImplementedError
+
+
+class NullDoctorSource(DoctorSource):
+    """No client configured — reachability fails with a config hint."""
+
+    kind = "none"
+
+    def snapshot(self, hashes=None):
+        return ClientSnapshot(
+            kind="none", endpoint="(none)", reachable=False,
+            reach_error=("no torrent client configured; pass --qb-url or "
+                         "--tr-url (or set LLMT_QB_URL / LLMT_TR_URL)"))
+
+
+class QbtDoctorSource(DoctorSource):
+    kind = "qbittorrent"
+
+    def __init__(self, client: QBittorrentClient):
+        self.client = client
+
+    def _get(self, path: str, params: Optional[dict] = None):
+        c = self.client
+        r = c.session.get(f"{c.url}{path}", params=params or {},
+                          headers=c._headers(), timeout=c.timeout)
+        if r.status_code != 200:
+            raise ClientError(f"qBittorrent GET {path} failed "
+                              f"(HTTP {r.status_code}).")
+        return r
+
+    def snapshot(self, hashes=None):
+        snap = ClientSnapshot(kind=self.kind, endpoint=self.client.url,
+                              reachable=False)
+        try:
+            self.client._login()
+            snap.version = safe_text(
+                self._get("/api/v2/app/version").text.strip())
+            prefs = self._get("/api/v2/app/preferences").json()
+            transfer = self._get("/api/v2/transfer/info").json()
+            torrents = self._get("/api/v2/torrents/info").json()
+        except (ClientError, requests.RequestException, ValueError) as exc:
+            snap.reach_error = safe_text(str(exc))
+            return snap
+        snap.reachable = True
+        if not isinstance(prefs, dict):
+            prefs = {}
+        if not isinstance(transfer, dict):
+            transfer = {}
+        if not isinstance(torrents, list):
+            torrents = []
+
+        if isinstance(prefs.get("up_limit"), (int, float)):
+            snap.upload_limit_bps = int(prefs["up_limit"])
+        if isinstance(prefs.get("dht"), bool):
+            snap.dht_enabled = prefs["dht"]
+        if isinstance(prefs.get("pex"), bool):
+            snap.pex_enabled = prefs["pex"]
+        if isinstance(prefs.get("queueing_enabled"), bool):
+            snap.queueing_enabled = prefs["queueing_enabled"]
+        if (prefs.get("max_ratio_enabled") is True
+                and isinstance(prefs.get("max_ratio"), (int, float))
+                and prefs["max_ratio"] >= 0):
+            snap.global_ratio_limit = float(prefs["max_ratio"])
+        iface = prefs.get("current_network_interface")
+        if isinstance(iface, str):
+            snap.bound_interface = safe_text(iface)
+        cs = transfer.get("connection_status")
+        if isinstance(cs, str):
+            snap.connection_status = safe_text(cs)
+        sp = prefs.get("save_path")
+        if isinstance(sp, str):
+            snap.client_default_save_path = safe_text(sp)
+
+        wanted = {h.lower() for h in hashes} if hashes else None
+        selected = []
+        for t in torrents:
+            if not isinstance(t, dict):
+                continue
+            th = self._torrent(t)
+            if wanted is not None and th.info_hash.lower() not in wanted:
+                continue
+            selected.append(th)
+        for th in selected[:MAX_TRACKER_FETCH]:
+            th.trackers = self._trackers(th.info_hash)
+        snap.torrents = selected
+        return snap
+
+    def _torrent(self, t: dict) -> TorrentHealth:
+        raw = t.get("state") if isinstance(t.get("state"), str) else ""
+        progress = t.get("progress")
+        rl = t.get("ratio_limit")
+        eff = None
+        if isinstance(rl, (int, float)):
+            if rl >= 0:
+                eff = float(rl)          # per-torrent limit
+            # -2 = "use global" resolved by the ratio check via the snapshot;
+            # -1 = explicitly unlimited for this torrent.
+            elif int(rl) == -2:
+                eff = -2.0               # sentinel: defer to global
+        return TorrentHealth(
+            info_hash=str(t.get("hash") or ""),
+            name=str(t.get("name") or ""),
+            raw_state=safe_text(raw),
+            category=_QBT_STATE_MAP.get(raw, "unknown"),
+            progress=float(progress)
+            if isinstance(progress, (int, float)) else None,
+            save_path=str(t.get("save_path") or ""),
+            content_path=str(t.get("content_path") or ""),
+            ratio=float(t.get("ratio"))
+            if isinstance(t.get("ratio"), (int, float)) else None,
+            ratio_limit=eff,
+        )
+
+    def _trackers(self, info_hash: str) -> Optional[list]:
+        if not info_hash:
+            return None
+        try:
+            rows = self._get("/api/v2/torrents/trackers",
+                             params={"hash": info_hash}).json()
+        except (ClientError, requests.RequestException, ValueError):
+            return None
+        out = []
+        if not isinstance(rows, list):
+            return None
+        for r in rows:
+            if not isinstance(r, dict):
+                continue
+            url = str(r.get("url") or "")
+            if url.startswith("**"):
+                continue  # DHT/PEX/LSD pseudo-entries
+            state = _QBT_TRACKER_MAP.get(r.get("status"), "not-working")
+            out.append(TrackerStatus(url=safe_text(url), state=state,
+                                     message=safe_text(str(r.get("msg") or ""))))
+        return out
+
+
+class TransmissionDoctorSource(DoctorSource):
+    kind = "transmission"
+
+    _FIELDS = ["id", "name", "hashString", "status", "percentDone", "error",
+               "errorString", "downloadDir", "uploadRatio", "seedRatioMode",
+               "seedRatioLimit", "trackerStats", "isFinished"]
+
+    def __init__(self, client: TransmissionClient):
+        self.client = client
+
+    def snapshot(self, hashes=None):
+        snap = ClientSnapshot(kind=self.kind, endpoint=self.client.url,
+                              reachable=False)
+        try:
+            sess = self.client._rpc("session-get", {}).get("arguments") or {}
+            tor = (self.client._rpc(
+                "torrent-get", {"fields": self._FIELDS}).get("arguments")
+                or {}).get("torrents") or []
+        except (ClientError, requests.RequestException, ValueError) as exc:
+            snap.reach_error = safe_text(str(exc))
+            return snap
+        snap.reachable = True
+        if not isinstance(sess, dict):
+            sess = {}
+        snap.version = safe_text(str(sess.get("version") or ""))
+        dd = sess.get("download-dir")
+        if isinstance(dd, str):
+            snap.client_default_save_path = safe_text(dd)
+        if isinstance(sess.get("dht-enabled"), bool):
+            snap.dht_enabled = sess["dht-enabled"]
+        if isinstance(sess.get("pex-enabled"), bool):
+            snap.pex_enabled = sess["pex-enabled"]
+        if isinstance(sess.get("speed-limit-up-enabled"), bool):
+            if not sess["speed-limit-up-enabled"]:
+                snap.upload_limit_bps = 0
+            elif isinstance(sess.get("speed-limit-up"), (int, float)):
+                # Transmission expresses this in kB/s (SI).
+                snap.upload_limit_bps = int(sess["speed-limit-up"]) * 1000
+        qflags = [sess.get("seed-queue-enabled"),
+                  sess.get("download-queue-enabled")]
+        if any(isinstance(q, bool) for q in qflags):
+            snap.queueing_enabled = any(q is True for q in qflags)
+        if (sess.get("seedRatioLimited") is True
+                and isinstance(sess.get("seedRatioLimit"), (int, float))):
+            snap.global_ratio_limit = float(sess["seedRatioLimit"])
+        # Interface binding is not exposed over the RPC -> stays None (N-A).
+        try:
+            pt = self.client._rpc("port-test", {}).get("arguments") or {}
+            if isinstance(pt.get("port-is-open"), bool):
+                snap.port_open = pt["port-is-open"]
+        except (ClientError, requests.RequestException, ValueError):
+            snap.port_open = None
+
+        wanted = {h.lower() for h in hashes} if hashes else None
+        for t in tor:
+            if not isinstance(t, dict):
+                continue
+            th = self._torrent(t, snap)
+            if wanted is not None and th.info_hash.lower() not in wanted:
+                continue
+            snap.torrents.append(th)
+        return snap
+
+    def _torrent(self, t: dict, snap: ClientSnapshot) -> TorrentHealth:
+        status = t.get("status")
+        category = _TR_STATUS_MAP.get(status, "unknown") \
+            if isinstance(status, int) else "unknown"
+        err = t.get("error")
+        error_message = ""
+        if isinstance(err, int) and err != 0:
+            category = "errored"
+            error_message = safe_text(str(t.get("errorString") or f"error {err}"))
+        mode = t.get("seedRatioMode")
+        eff = None
+        if mode == 1 and isinstance(t.get("seedRatioLimit"), (int, float)):
+            eff = float(t["seedRatioLimit"])
+        elif mode == 0:
+            eff = -2.0  # defer to global
+        # mode 2 = unlimited for this torrent -> None
+        name = str(t.get("name") or "")
+        ddir = str(t.get("downloadDir") or "")
+        content = os.path.join(ddir, name) if (ddir and name) else ""
+        progress = t.get("percentDone")
+        trackers = []
+        for ts in (t.get("trackerStats") or []):
+            if not isinstance(ts, dict):
+                continue
+            if ts.get("lastAnnounceSucceeded") is True:
+                state = "working"
+            elif ts.get("hasAnnounced") is False:
+                state = "not-contacted"
+            else:
+                state = "not-working"
+            trackers.append(TrackerStatus(
+                url=safe_text(str(ts.get("announce") or ts.get("host") or "")),
+                state=state,
+                message=safe_text(str(ts.get("lastAnnounceResult") or ""))))
+        return TorrentHealth(
+            info_hash=str(t.get("hashString") or ""),
+            name=name,
+            raw_state=f"status={status}" + (f" error={err}" if error_message else ""),
+            category=category,
+            progress=float(progress)
+            if isinstance(progress, (int, float)) else None,
+            save_path=ddir,
+            content_path=content,
+            ratio=float(t.get("uploadRatio"))
+            if isinstance(t.get("uploadRatio"), (int, float)) else None,
+            ratio_limit=eff,
+            error_message=error_message,
+            trackers=trackers,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Checks (pure functions over a ClientSnapshot; unit-testable, no network)
+# --------------------------------------------------------------------------- #
+
+_CLIENT_CHECKS = ("client-reachable", "port-reachability", "dht", "pex",
+                  "upload-cap", "vpn-bind", "queueing", "ratio-limit",
+                  "layout-base-visible")
+
+
+def _effective_ratio_limit(t: TorrentHealth, snap: ClientSnapshot):
+    if t.ratio_limit is None:
+        return None
+    if t.ratio_limit == -2.0:
+        return snap.global_ratio_limit
+    return t.ratio_limit
+
+
+def _under(base: str, path: str) -> bool:
+    if not base or not path:
+        return False
+    base = os.path.abspath(os.path.expanduser(base))
+    path = os.path.abspath(path)
+    return path == base or path.startswith(base + os.sep)
+
+
+def run_checks(snap: ClientSnapshot,
+               layout_base: Optional[str] = None) -> list:
+    """All doctor checks over one snapshot. Read-only; touches only the local
+    filesystem (lstat/exists) for the layout checks."""
+    layout_base = os.path.abspath(
+        os.path.expanduser(layout_base or DEFAULT_BASE_DIR))
+    out: list = []
+
+    # 1. client reachable ---------------------------------------------------
+    if not snap.reachable:
+        out.append(CheckResult(
+            "client-reachable", "client", FAIL,
+            f"{snap.kind} at {safe_text(snap.endpoint)} did not respond: "
+            f"{snap.reach_error}",
+            "check the WebUI/RPC URL, credentials, and that the client is "
+            "running (--qb-url/--tr-url or LLMT_QB_URL/LLMT_TR_URL)"))
+        for check in _CLIENT_CHECKS[1:]:
+            out.append(CheckResult(check, "client", NA,
+                                   "client unreachable; check not run",
+                                   "fix client-reachable first"))
+        return out
+    out.append(CheckResult(
+        "client-reachable", "client", PASS,
+        f"{snap.kind} {snap.version or '(unknown version)'} responded at "
+        f"{safe_text(snap.endpoint)}"))
+
+    # 2. port reachability (client's own view; NOT an independent probe) ----
+    if snap.port_open is not None:
+        if snap.port_open:
+            out.append(CheckResult(
+                "port-reachability", "client", PASS,
+                "the daemon's own port-test reports the peer port OPEN "
+                "(tested by the daemon, not independently verified by llmt)"))
+        else:
+            out.append(CheckResult(
+                "port-reachability", "client", FAIL,
+                "the daemon's own port-test reports the peer port CLOSED",
+                "forward the listen port on your router/VPN; CGNAT or a VPN "
+                "without port-forwarding leaves you connectable-out only"))
+    elif snap.connection_status is not None:
+        cs = snap.connection_status
+        if cs == "connected":
+            out.append(CheckResult(
+                "port-reachability", "client", PASS,
+                "client self-reports connection status 'connected' (the "
+                "client's own view — llmt did not probe the port from "
+                "outside)"))
+        elif cs == "firewalled":
+            out.append(CheckResult(
+                "port-reachability", "client", FAIL,
+                "client self-reports connection status 'firewalled' — "
+                "inbound peers cannot reach you",
+                "forward the listen port (router/VPN port-forwarding); "
+                "CGNAT needs a VPN or seedbox that supports forwarding"))
+        elif cs == "disconnected":
+            out.append(CheckResult(
+                "port-reachability", "client", FAIL,
+                "client self-reports connection status 'disconnected'",
+                "check the client's network binding / VPN state"))
+        else:
+            out.append(CheckResult(
+                "port-reachability", "client", WARN,
+                f"client reports unrecognized connection status "
+                f"'{safe_text(cs)}' — not assumed healthy",
+                "inspect the client's connection status manually"))
+    else:
+        out.append(CheckResult(
+            "port-reachability", "client", NA,
+            "this client's API exposes no port/connection signal llmt can "
+            "read", "test the port manually (e.g. the client's built-in "
+            "port test or your tracker's peer view)"))
+
+    # 3./4. DHT / PEX -------------------------------------------------------
+    for check, val in (("dht", snap.dht_enabled), ("pex", snap.pex_enabled)):
+        label = check.upper()
+        if val is True:
+            out.append(CheckResult(check, "client", PASS,
+                                   f"{label} enabled (per client settings)"))
+        elif val is False:
+            out.append(CheckResult(
+                check, "client", WARN,
+                f"{label} is disabled in the client settings",
+                f"enable {label} unless you seed private trackers only; "
+                f"without it many peers will never discover your seed"))
+        else:
+            out.append(CheckResult(
+                check, "client", NA,
+                f"this client's API did not expose the {label} setting",
+                f"verify {label} is on in the client's options"))
+
+    # 5. upload cap ----------------------------------------------------------
+    cap = snap.upload_limit_bps
+    if cap is None:
+        out.append(CheckResult(
+            "upload-cap", "client", NA,
+            "this client's API did not expose the global upload limit",
+            "check the client's global upload limit manually"))
+    elif cap <= 0:
+        out.append(CheckResult("upload-cap", "client", PASS,
+                               "no global upload cap set"))
+    elif cap <= PATHOLOGICAL_UP_CAP_BPS:
+        out.append(CheckResult(
+            "upload-cap", "client", FAIL,
+            f"global upload cap is {human_size(cap)}/s — effectively "
+            f"useless for seeding multi-GB models",
+            "raise or remove the global upload limit (and check "
+            "alternative/scheduled speed limits)"))
+    else:
+        out.append(CheckResult(
+            "upload-cap", "client", PASS,
+            f"global upload cap {human_size(cap)}/s is a sane, "
+            f"deliberate limit (note: llmt cannot see scheduler/alternative "
+            f"limits on every client)"))
+
+    # 6. VPN bind ------------------------------------------------------------
+    iface = snap.bound_interface
+    if iface is None:
+        out.append(CheckResult(
+            "vpn-bind", "client", NA,
+            "this client's API does not expose interface binding",
+            "if you bind the client to a VPN interface, verify it in the "
+            "client's network options"))
+    elif iface == "":
+        out.append(CheckResult(
+            "vpn-bind", "client", PASS,
+            "client is not bound to a specific network interface "
+            "(per client settings)"))
+    else:
+        connected = (snap.connection_status == "connected"
+                     or snap.port_open is True)
+        broken = (snap.connection_status in ("disconnected", "firewalled")
+                  or snap.port_open is False)
+        if connected:
+            out.append(CheckResult(
+                "vpn-bind", "client", PASS,
+                f"bound to interface '{safe_text(iface)}' and the client "
+                f"reports itself connected — llmt cannot verify this is the "
+                f"interface you intended (check it is your VPN)"))
+        elif broken:
+            out.append(CheckResult(
+                "vpn-bind", "client", FAIL,
+                f"bound to interface '{safe_text(iface)}' while the client "
+                f"reports itself not connected — a stale or misbound VPN "
+                f"interface silently stops all seeding",
+                "confirm the interface still exists and the VPN is up "
+                "(qBittorrent: Options > Advanced > Network interface)"))
+        else:
+            out.append(CheckResult(
+                "vpn-bind", "client", WARN,
+                f"bound to interface '{safe_text(iface)}'; llmt cannot "
+                f"confirm from the API whether that interface is up",
+                "verify the bound interface matches your active VPN"))
+
+    # 7. queueing interference ----------------------------------------------
+    queued = [t for t in snap.torrents if t.category == "queued"]
+    if snap.queueing_enabled is None and not queued:
+        out.append(CheckResult(
+            "queueing", "client", NA,
+            "this client's API did not expose the queueing setting and no "
+            "examined torrent is queued",
+            "check the client's queueing/active-torrent limits manually"))
+    elif queued:
+        out.append(CheckResult(
+            "queueing", "client", FAIL,
+            f"{len(queued)} examined torrent(s) are queue-stalled "
+            f"(waiting, not seeding): "
+            + ", ".join(t.label() for t in queued[:5]),
+            "raise the active-torrents / active-uploads limits or disable "
+            "queueing so complete torrents actually seed"))
+    elif snap.queueing_enabled:
+        out.append(CheckResult(
+            "queueing", "client", PASS,
+            "queueing is enabled but no examined torrent is currently "
+            "queued (per client state)"))
+    else:
+        out.append(CheckResult("queueing", "client", PASS,
+                               "torrent queueing disabled"))
+
+    # 8. ratio-limit interference ---------------------------------------------
+    stopped_by_ratio = []
+    for t in snap.torrents:
+        lim = _effective_ratio_limit(t, snap)
+        if (lim is not None and lim >= 0 and t.category == "paused"
+                and t.progress is not None and t.progress >= 1.0
+                and t.ratio is not None and t.ratio >= lim):
+            stopped_by_ratio.append(t)
+    if stopped_by_ratio:
+        out.append(CheckResult(
+            "ratio-limit", "client", FAIL,
+            f"{len(stopped_by_ratio)} complete torrent(s) appear stopped by "
+            f"a share-ratio limit (ratio >= limit and paused): "
+            + ", ".join(t.label() for t in stopped_by_ratio[:5]),
+            "raise/remove the share-ratio limit (or set its action to "
+            "nothing) so finished torrents keep seeding"))
+    elif snap.global_ratio_limit is not None:
+        out.append(CheckResult(
+            "ratio-limit", "client", PASS,
+            f"a global share-ratio limit of {snap.global_ratio_limit:g} is "
+            f"set but has not stopped any examined torrent (per client "
+            f"state)"))
+    else:
+        out.append(CheckResult(
+            "ratio-limit", "client", PASS,
+            "no global share-ratio limit reported stopping anything"))
+
+    # layout-base visibility from the client's filesystem namespace (S3):
+    # if the client's own default save path does not exist on the machine
+    # doctor runs on, llmt and the client are on different filesystems, so a
+    # link farm under layout_base (a local path) may be invisible to the
+    # client and a seed handoff would recheck to 0% and fail closed.
+    default_path = snap.client_default_save_path
+    if not default_path:
+        out.append(CheckResult(
+            "layout-base-visible", "client", NA,
+            "the client did not report a default save path, so llmt cannot "
+            "tell whether it shares a filesystem with this machine",
+            "run 'llmt doctor' on the machine the client runs on"))
+    elif os.path.isdir(os.path.expanduser(default_path)):
+        out.append(CheckResult(
+            "layout-base-visible", "client", PASS,
+            f"the client's own default save path "
+            f"({safe_text(default_path)}) exists on this machine, so an llmt "
+            f"link farm under {safe_text(layout_base)} should be visible to "
+            f"the client (filesystem-namespace check only, not a per-torrent "
+            f"probe)"))
+    else:
+        out.append(CheckResult(
+            "layout-base-visible", "client", WARN,
+            f"the client's own default save path "
+            f"({safe_text(default_path)}) does not exist on the machine llmt "
+            f"is running on -- the client looks dockerized or remote "
+            f"(different filesystem). An llmt link farm under "
+            f"{safe_text(layout_base)} is a path on THIS machine, so the "
+            f"client may not be able to see it and a seed handoff could "
+            f"recheck to 0% and fail closed",
+            "point 'llmt scan --layout-base' at a directory the client can "
+            "see (one of its mounted volumes), or run llmt on the same "
+            "host/namespace as the client"))
+
+    # Per-torrent checks -----------------------------------------------------
+    for t in snap.torrents:
+        out.extend(_torrent_checks(t, snap, layout_base))
+    return out
+
+
+def _torrent_checks(t: TorrentHealth, snap: ClientSnapshot,
+                    layout_base: str) -> list:
+    out = [_check_complete_seeding(t), _check_trackers(t)]
+    out.extend(_check_layout(t, layout_base))
+    return out
+
+
+def _check_complete_seeding(t: TorrentHealth) -> CheckResult:
+    scope = t.label()
+    check = "complete-and-seeding"
+    if t.category == "errored":
+        return CheckResult(
+            check, scope, FAIL,
+            f"client reports an error state ({t.raw_state}): "
+            f"{t.error_message or 'no message'}",
+            "open the torrent in the client; if files went missing, "
+            "re-run 'llmt scan' to rebuild the layout, then force-recheck")
+    if t.progress is None:
+        return CheckResult(
+            check, scope, FAIL,
+            "client did not report completion progress — fail-closed, not "
+            "assumed complete",
+            "force-recheck the torrent in the client and inspect its state")
+    if t.progress < 1.0:
+        return CheckResult(
+            check, scope, FAIL,
+            f"only {t.progress * 100:.1f}% complete per the client — a "
+            f"partial file is never seedable and is NOT healthy",
+            "let the download finish, or if the data exists on disk "
+            "force-recheck (llmt scan adds paused -> recheck -> resume)")
+    if t.category == "seeding":
+        return CheckResult(
+            check, scope, PASS,
+            f"100% complete and state '{t.raw_state}' — the client reports "
+            f"it as actively offered to peers (upload activity itself "
+            f"depends on demand)")
+    if t.category == "checking":
+        return CheckResult(
+            check, scope, WARN,
+            f"recheck/verification in progress (state '{t.raw_state}')",
+            "wait for the recheck to finish, then confirm it resumes "
+            "seeding")
+    if t.category == "paused":
+        return CheckResult(
+            check, scope, FAIL,
+            f"complete but paused/stopped (state '{t.raw_state}') — "
+            f"seeding nothing",
+            "resume/start the torrent (check ratio limits and queueing if "
+            "it re-pauses itself)")
+    if t.category == "queued":
+        return CheckResult(
+            check, scope, FAIL,
+            f"complete but queue-stalled (state '{t.raw_state}')",
+            "raise the client's active-torrent limits (see the queueing "
+            "check)")
+    if t.category == "downloading":
+        return CheckResult(
+            check, scope, WARN,
+            f"client says 100% but state '{t.raw_state}' is a download "
+            f"state — inconsistent, not assumed seeding",
+            "force-recheck the torrent so the client re-evaluates it")
+    return CheckResult(
+        check, scope, FAIL,
+        f"unrecognized client state '{t.raw_state}' — fail-closed: an "
+        f"unknown state is never reported healthy",
+        "inspect the torrent in the client; force-recheck and resume if "
+        "complete")
+
+
+def _check_trackers(t: TorrentHealth) -> CheckResult:
+    scope = t.label()
+    check = "tracker-announce"
+    if t.trackers is None:
+        return CheckResult(
+            check, scope, NA,
+            "tracker status not available from the client for this torrent",
+            "check the torrent's Trackers tab in the client")
+    real = [tr for tr in t.trackers if tr.state != "disabled"]
+    if not real:
+        return CheckResult(
+            check, scope, NA,
+            "no trackers on this torrent (DHT/PEX only) — announce not "
+            "applicable",
+            "keep DHT/PEX enabled or peers cannot find this seed")
+    working = [tr for tr in real if tr.state == "working"]
+    dead = [tr for tr in real if tr.state == "not-working"]
+    if working:
+        if dead:
+            named = "; ".join(
+                tr.url + (f" ({tr.message})" if tr.message else "")
+                for tr in dead)[:300]
+            return CheckResult(
+                check, scope, WARN,
+                f"{len(working)}/{len(real)} tracker tier(s) working, but "
+                f"{len(dead)} not working FROM THIS MACHINE: {named} — often a "
+                f"UDP tier blocked by a container/NAT/firewall while an HTTP "
+                f"tier is fine (per the client's last announce, not "
+                f"independently verified by llmt); seeding still works over "
+                f"the working tier(s)",
+                "if the unreachable tier is UDP, allow outbound UDP to it "
+                "from your network/container; seeding continues over the "
+                "working tier meanwhile")
+        return CheckResult(
+            check, scope, PASS,
+            f"{len(working)}/{len(real)} tracker(s) report 'working' — as "
+            f"reported by the client's last announce, not independently "
+            f"verified by llmt")
+    pending = [tr for tr in real if tr.state in ("not-contacted", "updating")]
+    if pending and len(pending) == len(real):
+        return CheckResult(
+            check, scope, WARN,
+            "trackers not contacted yet (per the client) — too early to "
+            "call the announce healthy",
+            "wait for the first announce, then re-run doctor")
+    msgs = "; ".join(tr.message for tr in real if tr.message)[:200]
+    return CheckResult(
+        check, scope, FAIL,
+        "no tracker reports a successful announce (per the client)"
+        + (f" — client says: {msgs}" if msgs else ""),
+        "check the tracker URL and that your network/VPN allows the "
+        "announce; a failed announce means the tracker never lists you")
+
+
+def _check_layout(t: TorrentHealth, layout_base: str) -> list:
+    """Content-path / layout sanity + duplicate-copy check.
+
+    Uses the frozen WP-14.2b plan semantics: llmt-planned torrents keep
+    ``savepath == plan.save_path`` (autoTMM off, QBITTORRENT_ADD_RECIPE) and,
+    in link-farm mode, present the bytes through links under the layout base
+    that resolve to the user's original file. Doctor can only inspect the
+    filesystem it runs on: when the client runs on another host the paths
+    are reported N-A, never PASS.
+    """
+    scope = t.label()
+    out = []
+    path = t.content_path or (
+        os.path.join(t.save_path, t.name) if t.save_path and t.name else "")
+    in_farm = _under(layout_base, t.save_path) or _under(layout_base, path)
+
+    if not path:
+        out.append(CheckResult(
+            "layout-path", scope, NA,
+            "client did not report a content path",
+            "verify the torrent's save path in the client"))
+        out.append(CheckResult(
+            "duplicate-copy", scope, NA,
+            "no content path to inspect", ""))
+        return out
+
+    exists = os.path.lexists(path)
+    if not exists:
+        if in_farm:
+            out.append(CheckResult(
+                "layout-path", scope, FAIL,
+                f"expected llmt link-farm path is missing: "
+                f"{safe_text(path)}",
+                "re-run 'llmt scan' to rebuild the link farm, then "
+                "force-recheck in the client"))
+        else:
+            out.append(CheckResult(
+                "layout-path", scope, NA,
+                f"path {safe_text(path)} is not visible from this machine "
+                f"— if the client runs on another host that may be fine; "
+                f"doctor can only inspect the local filesystem",
+                "run 'llmt doctor' on the machine the client runs on"))
+        out.append(CheckResult(
+            "duplicate-copy", scope, NA,
+            "content path not inspectable from this machine", ""))
+        return out
+
+    broken = _broken_links(path)
+    if broken:
+        out.append(CheckResult(
+            "layout-path", scope, FAIL,
+            f"broken link(s) in the content path — the original file was "
+            f"moved or deleted: {safe_text(broken[0])}"
+            + (f" (+{len(broken) - 1} more)" if len(broken) > 1 else ""),
+            "restore/relocate the original file or re-run 'llmt scan', "
+            "then force-recheck"))
+    elif t.save_path and t.content_path and not _under(t.save_path,
+                                                       t.content_path):
+        out.append(CheckResult(
+            "layout-path", scope, WARN,
+            f"content path {safe_text(t.content_path)} lies outside the "
+            f"save path {safe_text(t.save_path)} — the client appears to "
+            f"have relocated it (autoTMM?), which breaks the frozen "
+            f"add-recipe assumption (savepath == plan.save_path)",
+            "disable Automatic Torrent Management for llmt-added torrents "
+            "and move the torrent back to its planned save path"))
+    else:
+        via = (f" via the llmt link farm ({MODE_LINKFARM} mode under "
+               f"{safe_text(layout_base)})" if in_farm
+               else f" ({MODE_DIRECT}: the client reads the file in place)")
+        out.append(CheckResult(
+            "layout-path", scope, PASS,
+            f"content present at {safe_text(path)}{via} — presence and "
+            f"link integrity only; byte-correctness is the client "
+            f"recheck's job, not doctor's"))
+
+    out.append(_check_duplicate(path, scope, in_farm))
+    return out
+
+
+def _broken_links(path: str) -> list:
+    """Symlinks under ``path`` (bounded walk) whose targets are gone."""
+    broken = []
+    if os.path.islink(path) and not os.path.exists(path):
+        return [path]
+    if os.path.isdir(path):
+        seen = 0
+        for root, dirs, files in os.walk(path):
+            for nm in files + dirs:
+                if seen >= MAX_LAYOUT_WALK:
+                    return broken
+                seen += 1
+                p = os.path.join(root, nm)
+                if os.path.islink(p) and not os.path.exists(p):
+                    broken.append(p)
+    return broken
+
+
+def _check_duplicate(path: str, scope: str, in_farm: bool) -> CheckResult:
+    check = "duplicate-copy"
+    try:
+        target = path
+        if os.path.isdir(path) and not os.path.islink(path):
+            # inspect the first regular file found (bounded)
+            found = None
+            seen = 0
+            for root, _dirs, files in os.walk(path):
+                for nm in files:
+                    seen += 1
+                    if seen > MAX_LAYOUT_WALK:
+                        break
+                    found = os.path.join(root, nm)
+                    break
+                if found or seen > MAX_LAYOUT_WALK:
+                    break
+            if not found:
+                return CheckResult(check, scope, NA,
+                                   "no files found under the content path "
+                                   "to inspect", "")
+            target = found
+        st = os.lstat(target)
+    except OSError as exc:
+        return CheckResult(check, scope, NA,
+                           f"could not stat content: {safe_text(str(exc))}",
+                           "")
+    if os.path.islink(target):
+        return CheckResult(
+            check, scope, PASS,
+            "content is presented through a symlink — no duplicate copy of "
+            "the bytes exists")
+    if getattr(st, "st_nlink", 1) > 1:
+        return CheckResult(
+            check, scope, PASS,
+            "content is a hardlink (link count > 1) — no duplicate copy of "
+            "the bytes exists")
+    if in_farm:
+        return CheckResult(
+            check, scope, WARN,
+            "a real (non-linked) copy sits inside the llmt layout "
+            "directory — the link farm should reference your original "
+            "file, not duplicate it",
+            "re-run 'llmt scan' so the layout is rebuilt as links, then "
+            "remove the duplicate copy")
+    return CheckResult(
+        check, scope, PASS,
+        "direct use of the file in place — no llmt-created duplicate "
+        "(llmt cannot rule out copies elsewhere on disk)")
+
+
+def summarize(results: Iterable) -> dict:
+    counts = {PASS: 0, WARN: 0, FAIL: 0, NA: 0}
+    for r in results:
+        counts[r.status] = counts.get(r.status, 0) + 1
+    return {"pass": counts[PASS], "warn": counts[WARN],
+            "fail": counts[FAIL], "na": counts[NA],
+            "ok": counts[FAIL] == 0}