llmt-cli 0.2.0__py3-none-any.whl

llmt/clients.py

@@ -0,0 +1,1316 @@
+"""BitTorrent client adapters for ``llmt scan`` seeding.
+
+Three real adapters plus a test fake, behind one ``SeedClient`` interface:
+
+  * ``QBittorrentClient``  — WebUI API, implementing the frozen
+    ``QBITTORRENT_ADD_RECIPE``: add **paused**, ``skip_checking=false``,
+    ``autoTMM=false``, ``savepath=<plan.save_path>``  ->  wait for magnet
+    metadata (piece layout)  ->  recheck, polled to completion  ->  resume
+    (``/torrents/start`` on WebUI API >= 2.11, i.e. qBt 5.x) ONLY when the
+    recheck confirmed 100% of the data present.
+  * ``TransmissionClient`` — RPC (``torrent-add`` paused -> wait metadata ->
+    verify, polled to completion -> start only at 100%), with the
+    ``X-Transmission-Session-Id`` 409 handshake.
+  * ``FallbackClient``     — no client reachable/configured: surface the magnet
+    plus paused-add instructions for a manual add.
+
+Security (red-team axes):
+  * Connection details come from flags / env, never hardcoded.
+  * Magnets from the API are UNTRUSTED: validated to the ``magnet:`` scheme and
+    a conservative character set, and only ever passed as form/JSON values over
+    ``requests`` — never through a shell — so there is no injection surface.
+  * Webseed URLs are never accepted here (they can carry credentials); the
+    client obtains webseeds from the torrent itself.
+  * FAIL-CLOSED HANDOFF: the adapters never resume/start a torrent whose
+    recheck/verify did not confirm 100% local possession of every wanted,
+    locally-expected file.  The link farm is
+    hardlink/symlink-only (no copy mode), so letting the client download
+    "missing" pieces would write THROUGH the links into the user's original
+    files (corruption), or pull unlinked sibling files of a multi-file
+    container.  Incomplete or unverifiable => honest error, torrent left
+    paused, non-zero exit (ClientError).
+  * Every WebUI/RPC response is status-checked -- and the qBt add BODY is
+    checked too (HTTP 200 "Fails." = rejected add); "rechecked/resumed/seeding"
+    is only ever reported for a client-confirmed state.
+  * M5 (size-aware Option C, Pat 2026-07-13): for a PARTIALLY-present
+    multi-file container the scan layer passes a ``FileSelection``.  Every
+    missing large file is marked do-not-download (qBt ``filePrio`` priority 0
+    / Transmission ``files-unwanted``) after metadata is known and BEFORE any
+    recheck or resume, and the mark is READ BACK from the client; if the
+    client does not confirm it, the handoff fails closed (torrent left
+    paused).  Missing tiny companion files (<= 10 MiB cumulative,
+    ``expect_fetch``) stay wanted and are fetched by the client after resume
+    -- the completion gate then checks per-file state instead of the scalar
+    progress, so it still requires 100% of every file the user actually has.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib.parse import parse_qsl, urlsplit
+
+import requests
+
+from .errors import LlmtError
+from .layout import M5_AUTO_FETCH_MAX_BYTES
+
+
+def magnet_embeds_userinfo(magnet: str) -> bool:
+    """True if any embedded tracker/webseed URL param carries userinfo
+    (``user:pass@host``) — a credential-smuggling vector we refuse."""
+    try:
+        query = urlsplit(magnet).query
+        for key, val in parse_qsl(query, keep_blank_values=True):
+            if key.lower() in ("tr", "ws", "xs", "as", "mt") and "://" in val:
+                if "@" in urlsplit(val).netloc:
+                    return True
+    except ValueError:
+        return True
+    return False
+
+_MAGNET_RE = re.compile(r"^magnet:\?[A-Za-z0-9=&%:._~!*'();/?@+$,\[\]-]+$")
+
+# BEP 9 (v1): xt=urn:btih:<40-hex or 32-base32>.  BEP 52 (v2):
+# xt=urn:btmh:1220<64-hex> (multihash: sha2-256 code 0x12, length 0x20).
+_BTIH_RE = re.compile(r"^(?:[0-9A-Fa-f]{40}|[A-Za-z2-7]{32})$")
+_BTMH_RE = re.compile(r"^1220[0-9A-Fa-f]{64}$", re.IGNORECASE)
+
+
+def magnet_has_valid_infohash(magnet: str) -> bool:
+    """True iff some ``xt`` param carries a well-formed BitTorrent info-hash
+    (``urn:btih:`` v1 or ``urn:btmh:`` v2).  Clients reject magnets without
+    one -- qBittorrent answers HTTP 200 with body ``Fails.`` (ADP-6) -- so
+    they are refused up front instead of after a doomed add call."""
+    try:
+        pairs = parse_qsl(urlsplit(magnet).query, keep_blank_values=True)
+    except ValueError:
+        return False
+    for key, val in pairs:
+        if key.lower() != "xt":
+            continue
+        val = val.strip()
+        low = val.lower()
+        if low.startswith("urn:btih:") and _BTIH_RE.match(val[9:]):
+            return True
+        if low.startswith("urn:btmh:") and _BTMH_RE.match(val[9:]):
+            return True
+    return False
+
+
+class ClientError(LlmtError):
+    """A torrent-client add/connection failed."""
+    exit_code = 14
+
+
+def _norm_torrent_path(path: object) -> str:
+    """Normalise an in-torrent path for name matching against a client's file
+    list: forward slashes, no leading "./" or stray leading/trailing slashes.
+    Comparison is case-sensitive (torrent paths are byte-exact)."""
+    p = str(path or "").replace("\\", "/")
+    while p.startswith("./"):
+        p = p[2:]
+    return p.strip("/")
+
+
+@dataclass(frozen=True)
+class FileSelection:
+    """M5 per-file wanted/unwanted decisions for one multi-file container.
+
+    ``unwanted``:     in-torrent paths (root-inclusive, as clients display
+                      them) of missing files that must be marked
+                      do-not-download BEFORE the torrent is ever resumed
+                      (model weights / anything over the auto-fetch cap).
+    ``expect_fetch``: in-torrent paths of missing metadata-class tiny files
+                      (<= 10 MiB cumulative) that stay wanted; the client is
+                      EXPECTED to download them after resume, so the
+                      completion gate does not require them present.
+    """
+
+    unwanted: "tuple[str, ...]" = ()
+    expect_fetch: "tuple[str, ...]" = ()
+
+    def __bool__(self) -> bool:
+        return bool(self.unwanted or self.expect_fetch)
+
+
+@dataclass
+class AddResult:
+    """Outcome of a seed handoff.
+
+    ``ok`` is honest (D15): True only when every step — add, metadata,
+    recheck to 100%, resume/start — was confirmed by the client.  A handoff
+    that could not be verified reports ok=False; a failed or refused one
+    raises ``ClientError`` (fail closed)."""
+    method: str
+    ok: bool
+    steps: list = field(default_factory=list)
+    message: str = ""
+    dry_run: bool = False
+
+
+@dataclass(frozen=True)
+class PathVisibilityProbe:
+    """S3 pre-flight result: is the torrent client on the same filesystem
+    namespace as the machine llmt runs on?  ``supported`` False means the
+    adapter could not probe (unknown client, or the read failed) -- advisory
+    only, never a gate.  ``visible_locally`` False is the signature of a
+    dockerized/remote client (its own default save path does not exist on
+    this machine)."""
+    supported: bool
+    client_default_path: str = ""
+    visible_locally: "Optional[bool]" = None
+    detail: str = ""
+
+
+def _near_zero(progress, have=None) -> bool:
+    """True when a finished recheck/verify found (almost) NONE of the data --
+    the tell-tale of a client that cannot see the layout path at all, as
+    opposed to a genuinely partial file."""
+    try:
+        if have is not None and int(have) == 0:
+            return True
+    except (TypeError, ValueError):
+        pass
+    try:
+        return float(progress) < 0.01
+    except (TypeError, ValueError):
+        return False
+
+
+def _path_blindness_hint(save_path: str) -> str:
+    """Guidance appended to a fail-closed handoff error when the client's
+    recheck/verify found (near-)none of data llmt just verified at 100%
+    locally -- almost always a path the client cannot see."""
+    return (
+        "  The client reported (almost) NONE of the data present at:\n"
+        "      " + str(save_path) + "\n"
+        "  llmt verified these file(s) at 100% on the machine it ran on, so a "
+        "near-0% recheck almost always means the torrent client cannot SEE "
+        "that path -- a qBittorrent/Transmission running in Docker (a seedbox "
+        "or unRAID box) only sees its own mounted volumes, not host paths such "
+        "as ~/.llmt/seeding-layouts.\n"
+        "  Fix: put llmt's link farm on a directory the client can see (one of "
+        "its mounted volumes) and re-run, for example:\n"
+        "      llmt scan --layout-base /path/mounted/into/the/client")
+
+
+def validate_magnet(magnet: object) -> str:
+    """Return the magnet iff it is a well-formed ``magnet:?`` URI, else raise.
+
+    Anti-injection: rejects whitespace, control chars, non-magnet schemes, and
+    anything outside a conservative URI character set."""
+    if not isinstance(magnet, str) or not magnet:
+        raise ClientError("refusing an empty/invalid magnet from the API.")
+    if any(c in magnet for c in (" ", "\n", "\r", "\t", "\x00")):
+        raise ClientError("refusing a magnet containing whitespace/control chars.")
+    if not magnet.startswith("magnet:?") or not _MAGNET_RE.match(magnet):
+        raise ClientError("refusing a malformed magnet URI (anti-injection).")
+    if not magnet_has_valid_infohash(magnet):
+        raise ClientError(
+            "refusing a magnet without a valid xt=urn:btih:/urn:btmh: "
+            "info-hash param -- clients reject these (qBittorrent answers "
+            "HTTP 200 'Fails.').")
+    if magnet_embeds_userinfo(magnet):
+        raise ClientError(
+            "refusing a magnet whose tracker/webseed URL carries credentials "
+            "(userinfo smuggling defense).")
+    return magnet
+
+
+class SeedClient:
+    name = "base"
+
+    def add(self, *, magnet: str, info_hash: Optional[str], save_path: str,
+            torrent_name: str = "", dry_run: bool = False,
+            file_selection: Optional[FileSelection] = None) -> AddResult:
+        raise NotImplementedError
+
+    def probe_local_visibility(self) -> PathVisibilityProbe:
+        """S3 best-effort pre-flight: does this client share a filesystem
+        namespace with the machine llmt runs on?  Base returns an unsupported
+        probe; real adapters override.  Never raises -- advisory only."""
+        return PathVisibilityProbe(supported=False)
+
+
+# --------------------------------------------------------------------------- #
+# qBittorrent WebUI
+# --------------------------------------------------------------------------- #
+
+class QBittorrentClient(SeedClient):
+    name = "qbittorrent"
+
+    # Poll tuning (class attributes so tests can shrink them).  All waits are
+    # bounded: ~poll_interval * *_max_polls seconds, then an honest failure.
+    poll_interval = 1.0        # seconds between polls
+    metadata_max_polls = 120   # magnet metadata wait (~2 min at defaults)
+    recheck_max_polls = 3600   # recheck completion wait (~1 h at defaults)
+    recheck_grace_polls = 5    # polls allowed for the recheck to get scheduled
+
+    def __init__(self, url: str, username: Optional[str] = None,
+                 password: Optional[str] = None,
+                 session: Optional[requests.Session] = None,
+                 timeout: int = 30):
+        url = (url or "").rstrip("/")
+        if not (url.startswith("http://") or url.startswith("https://")):
+            raise ClientError("qBittorrent URL must be http(s)://")
+        self.url = url
+        self.username = username
+        self.password = password
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self._logged_in = False
+
+    def _headers(self) -> dict:
+        # qBittorrent's WebUI requires a matching Referer for CSRF.
+        return {"Referer": self.url, "Origin": self.url}
+
+    def _login(self) -> None:
+        if self._logged_in:
+            return
+        if not (self.username or self.password):
+            self._logged_in = True  # WebUI may allow localhost without auth
+            return
+        r = self.session.post(
+            f"{self.url}/api/v2/auth/login",
+            data={"username": self.username or "", "password": self.password or ""},
+            headers=self._headers(), timeout=self.timeout,
+        )
+        # Login-success contract (accept iff the creds were accepted AND a
+        # valid authenticated session was established):
+        #   * qBt 5.x (WebUI API 2.15.x) answers a SUCCESSFUL login with HTTP
+        #     204 and an EMPTY body -- it only sets the QBT_SID_* cookie.
+        #     Legacy 4.x answers 200 "Ok.".  Brittle-matching body == "Ok."
+        #     (the old check) rejected every 5.x login and aborted the add.
+        #   * A rejected login is 200 "Fails." (bad creds) or a non-2xx status
+        #     (401/403/...); qBt does NOT set a valid session cookie for those.
+        # So any non-2xx or the literal "Fails." body is an outright failure,
+        # and a 2xx is necessary but NOT sufficient: confirm the session is
+        # really authenticated with the same lightweight probe version-detect
+        # uses.  With the session cookie now set, GET /app/webapiVersion
+        # returns 200 only when logged in -- future-proof against qBt flipping
+        # the success status between 200 and 204.
+        if not (200 <= r.status_code < 300) or r.text.strip() == "Fails.":
+            raise ClientError("qBittorrent login failed (check --qb-user/--qb-pass).")
+        probe = self._get("/api/v2/app/webapiVersion")
+        if probe.status_code != 200:
+            raise ClientError("qBittorrent login failed (check --qb-user/--qb-pass).")
+        self._logged_in = True
+
+    # -- checked HTTP helpers (H2: no response is ever discarded) ---------- #
+
+    def _get(self, path: str, params: Optional[dict] = None) -> requests.Response:
+        return self.session.get(f"{self.url}{path}", params=params or {},
+                                headers=self._headers(), timeout=self.timeout)
+
+    def _post_checked(self, path: str, data: dict, what: str) -> requests.Response:
+        r = self.session.post(f"{self.url}{path}", data=data,
+                              headers=self._headers(), timeout=self.timeout)
+        if r.status_code != 200:
+            raise ClientError(f"qBittorrent {what} failed (HTTP {r.status_code}).")
+        return r
+
+    def _properties(self, h: str) -> Optional[dict]:
+        """GET /torrents/properties; None while the torrent is not yet known
+        (magnet adds register asynchronously)."""
+        r = self._get("/api/v2/torrents/properties", {"hash": h})
+        if r.status_code == 404:
+            return None
+        if r.status_code != 200:
+            raise ClientError(
+                f"qBittorrent properties read failed (HTTP {r.status_code}).")
+        try:
+            return r.json()
+        except ValueError as exc:
+            raise ClientError("qBittorrent properties returned non-JSON.") from exc
+
+    def _info(self, h: str) -> Optional[dict]:
+        """GET /torrents/info for one hash; None if the torrent is unknown."""
+        r = self._get("/api/v2/torrents/info", {"hashes": h})
+        if r.status_code != 200:
+            raise ClientError(
+                f"qBittorrent info read failed (HTTP {r.status_code}).")
+        try:
+            entries = r.json()
+        except ValueError as exc:
+            raise ClientError("qBittorrent info returned non-JSON.") from exc
+        if not isinstance(entries, list) or not entries:
+            return None
+        # Old Web API (2.0.0, qBt 4.1.0-4.1.2) silently IGNORES the hashes=
+        # filter and returns ALL torrents; trusting entries[0] would read an
+        # arbitrary torrent's state/progress and defeat the verify-before-
+        # seed gate.  Only an entry whose hash matches is believed (case-
+        # insensitive: info-hashes are hex); no match is treated exactly
+        # like an empty response — torrent unknown, fail closed upstream.
+        for entry in entries:
+            if (isinstance(entry, dict)
+                    and str(entry.get("hash") or "").lower() == h.lower()):
+                return entry
+        return None
+
+    def _files(self, h: str) -> "list[dict]":
+        """GET /torrents/files: the torrent's file list (name, per-file
+        progress 0..1, priority, index).  Status- and shape-checked."""
+        r = self._get("/api/v2/torrents/files", {"hash": h})
+        if r.status_code != 200:
+            raise ClientError(
+                f"qBittorrent files read failed (HTTP {r.status_code}).")
+        try:
+            entries = r.json()
+        except ValueError as exc:
+            raise ClientError("qBittorrent files returned non-JSON.") from exc
+        if not isinstance(entries, list) or not entries:
+            raise ClientError(
+                "qBittorrent returned an empty/unexpected file list for the "
+                "torrent; cannot verify per-file state -- NOT seeding.")
+        return [e for e in entries if isinstance(e, dict)]
+
+    def _apply_selection(self, h: str, selection: FileSelection,
+                         steps: list) -> None:
+        """M5: mark every missing LARGE file do-not-download (priority 0)
+        BEFORE any recheck/resume, and read the mark back from the client.
+        Unconfirmed => ClientError (fail closed, torrent left paused)."""
+        if not selection.unwanted:
+            return
+        entries = self._files(h)
+        by_name: dict = {}
+        for pos, e in enumerate(entries):
+            by_name[_norm_torrent_path(e.get("name"))] = (pos, e)
+        ids = []
+        for path in selection.unwanted:
+            hit = by_name.get(_norm_torrent_path(path))
+            if hit is None:
+                raise ClientError(
+                    f"cannot mark {path!r} do-not-download: the torrent's "
+                    "file list does not contain it (torrent/manifest "
+                    "disagreement) -- refusing to continue; the torrent was "
+                    "left paused in qBittorrent and is NOT seeding.")
+            pos, e = hit
+            idx = e.get("index")
+            ids.append(idx if isinstance(idx, int)
+                       and not isinstance(idx, bool) else pos)
+        self._post_checked(
+            "/api/v2/torrents/filePrio",
+            {"hash": h, "id": "|".join(str(i) for i in ids), "priority": 0},
+            "filePrio")
+        steps.append(
+            f"POST /api/v2/torrents/filePrio (priority=0 for "
+            f"{len(ids)} missing large file(s)) -> HTTP 200")
+        self._assert_unwanted_applied(h, selection)
+        steps.append("confirmed do-not-download (priority 0) on: "
+                     + ", ".join(selection.unwanted))
+
+    def _assert_unwanted_applied(self, h: str,
+                                 selection: FileSelection) -> None:
+        """Read priorities back; every unwanted file must REALLY be at
+        priority 0 or the handoff fails closed (no resume)."""
+        if not selection.unwanted:
+            return
+        prio = {_norm_torrent_path(e.get("name")): e.get("priority")
+                for e in self._files(h)}
+        bad = []
+        for path in selection.unwanted:
+            v = prio.get(_norm_torrent_path(path))
+            try:
+                ok = int(v) == 0
+            except (TypeError, ValueError):
+                ok = False
+            if not ok:
+                bad.append(path)
+        if bad:
+            raise ClientError(
+                "qBittorrent did not confirm do-not-download (priority 0) "
+                "for: " + ", ".join(bad) + " -- refusing to resume (resuming "
+                "would download the missing large file(s) onto your disk); "
+                "the torrent was left paused in qBittorrent and is NOT "
+                "seeding.")
+
+    def _gate_selection(self, h: str, selection: FileSelection,
+                        save_path: str = "") -> None:
+        """M5 completion gate for a partial container.  The scalar
+        /torrents/info ``progress`` is computed over WANTED bytes, so with
+        still-wanted expect_fetch files missing it is legitimately < 1.0 --
+        and we refuse to trust any scalar here anyway.  The gate reads
+        per-file progress from /torrents/files (unambiguous regardless of
+        the scalar's wanted-ness semantics): every file the user is supposed
+        to HAVE must be at 100%; unwanted files are re-confirmed at priority
+        0 (so no resume window ever exists with a large missing file
+        wanted); expect_fetch files may be incomplete by design."""
+        entries = self._files(h)
+        unwanted = {_norm_torrent_path(x) for x in selection.unwanted}
+        fetch = {_norm_torrent_path(x) for x in selection.expect_fetch}
+        incomplete = []
+        saw_any_data = False
+        for pos, e in enumerate(entries):
+            name = _norm_torrent_path(e.get("name"))
+            if name in unwanted or name in fetch:
+                continue
+            try:
+                done = float(e.get("progress") or 0.0)
+            except (TypeError, ValueError):
+                done = 0.0
+            if done > 0.0:
+                saw_any_data = True
+            if done < 1.0:
+                incomplete.append(str(e.get("name") or f"file #{pos}"))
+        if incomplete:
+            base = (
+                "recheck finished but these locally-expected files are not "
+                "100% present: " + ", ".join(incomplete) + " -- refusing to "
+                "resume; the torrent was left paused in qBittorrent and is "
+                "NOT seeding.")
+            if not saw_any_data:
+                raise ClientError(base + "\n" + _path_blindness_hint(save_path))
+            raise ClientError(base + "  (Resuming would download the missing "
+                              "data into your local files.)")
+        # M5 hardening: the torrent's own metadata is the final authority on
+        # expect_fetch sizes -- a wrong-but-signed size_bytes must never
+        # cause a large download. Every expect_fetch file, and their sum,
+        # must fit the auto-fetch cap or the handoff fails closed.
+        oversized = []
+        fetch_total = 0
+        for e in entries:
+            name = _norm_torrent_path(e.get("name"))
+            if name not in fetch:
+                continue
+            size = e.get("size")
+            if (not isinstance(size, int) or isinstance(size, bool)
+                    or size < 0 or size > M5_AUTO_FETCH_MAX_BYTES):
+                oversized.append(str(e.get("name")))
+            else:
+                fetch_total += size
+        if oversized or fetch_total > M5_AUTO_FETCH_MAX_BYTES:
+            names = ", ".join(oversized) if oversized else ", ".join(
+                sorted(fetch))
+            raise ClientError(
+                "refusing to resume: the torrent itself reports companion "
+                "file(s) expected to be tiny as over the 10 MiB auto-fetch "
+                "cap (or of unknown size): " + names + " -- the signed "
+                "metadata disagreed with the torrent; the torrent was left "
+                "paused in qBittorrent and is NOT seeding.")
+        self._assert_unwanted_applied(h, selection)
+
+    def _piece_counts(self, h: str) -> "tuple[int, int]":
+        """(pieces_have, pieces_num) for the honest report; (-1, -1) if the
+        counts cannot be read (never masks the underlying refusal)."""
+        try:
+            props = self._properties(h) or {}
+            return (int(props.get("pieces_have", -1)),
+                    int(props.get("pieces_num", -1)))
+        except (ClientError, TypeError, ValueError):
+            return (-1, -1)
+
+    # -- handoff phases ----------------------------------------------------- #
+
+    def _resolve_handle(self, info_hash: str) -> Optional[str]:
+        """Finding 3: discover the ACTUAL qBittorrent WebUI addressing handle
+        for the torrent we just added, instead of assuming it equals the v1
+        info-hash.  qBittorrent (libtorrent 2.0) keys BitTorrent v2 *hybrid*
+        torrents in the WebUI by their TRUNCATED-v2 info-hash, NOT the v1
+        info-hash we computed for the magnet/.torrent identity -- so
+        ``/torrents/properties?hash=<v1>`` 404s and
+        ``/torrents/info?hashes=<v1>`` returns 0 matches, and every keyed-by-v1
+        post-add call fails closed at the metadata gate.
+
+        qBt 4.4.0+/API 2.8.3+ (present in BOTH tested images -- 4.6.7/2.9.3 and
+        5.2.3/2.15.1) exposes ``infohash_v1`` and ``infohash_v2`` on every
+        torrent in the /torrents/info list.  Query the full list (the v1-keyed
+        targeted filter can't find a hybrid torrent) and find OUR torrent by
+        matching our known v1 hash against ``infohash_v1``; use THAT torrent's
+        qBt ``hash`` field as the handle for every subsequent WebUI call.
+
+        Match precedence: ``infohash_v1`` (hybrid or v1-only), then
+        ``infohash_v2``, then the qBt ``hash`` field directly (a v1-only,
+        non-hybrid torrent on older qBt keys by the v1 hash == what we asked
+        for).  The add registers asynchronously, so poll -- bounded, reusing
+        the metadata wait budget -- and return None (caller fails closed) if
+        the torrent never appears.  This affects ONLY the WebUI addressing
+        handle: ``info_hash`` remains the torrent's cryptographic identity for
+        the magnet/.torrent resolution and the manifest/verify flow.
+        """
+        want = (info_hash or "").lower()
+        for _attempt in range(self.metadata_max_polls):
+            # Full list, no hashes= filter: qBt cannot look a hybrid torrent up
+            # by its v1 hash, so a targeted query would return nothing.
+            r = self._get("/api/v2/torrents/info")
+            if r.status_code != 200:
+                raise ClientError(
+                    f"qBittorrent info read failed (HTTP {r.status_code}).")
+            try:
+                entries = r.json()
+            except ValueError as exc:
+                raise ClientError(
+                    "qBittorrent info returned non-JSON.") from exc
+            if isinstance(entries, list):
+                v2_match = None
+                hash_match = None
+                for e in entries:
+                    if not isinstance(e, dict):
+                        continue
+                    qbt_hash = str(e.get("hash") or "").lower()
+                    if str(e.get("infohash_v1") or "").lower() == want:
+                        # Primary: hybrid or v1-only -- qBt's hash is authoritative.
+                        return qbt_hash or want
+                    if (v2_match is None
+                            and str(e.get("infohash_v2") or "").lower() == want):
+                        v2_match = qbt_hash or want
+                    if hash_match is None and qbt_hash == want:
+                        hash_match = qbt_hash
+                if v2_match is not None:
+                    return v2_match
+                if hash_match is not None:
+                    return hash_match
+            time.sleep(self.poll_interval)
+        return None
+
+    def _wait_for_metadata(self, h: str) -> None:
+        """Magnet adds resolve metadata asynchronously; until the piece layout
+        is known a recheck is a silent no-op (M4).  Poll, bounded, and fail
+        honestly on timeout — never pretend the recheck meant something."""
+        for _attempt in range(self.metadata_max_polls):
+            props = self._properties(h)
+            if props is not None and int(props.get("pieces_num") or -1) > 0:
+                return
+            time.sleep(self.poll_interval)
+        raise ClientError(
+            "timed out waiting for magnet metadata (piece layout still unknown "
+            f"after ~{int(self.metadata_max_polls * self.poll_interval)}s); the "
+            "torrent was left paused in qBittorrent and is NOT seeding.")
+
+    def _wait_recheck_complete(self, h: str) -> float:
+        """Poll until the recheck finishes; return the resulting progress
+        (0.0-1.0).  Completion is only believed after a ``checking*`` state
+        was OBSERVED and then cleared: right after the recheck POST the
+        torrent may still show its STALE pre-recheck fastresume state (often
+        progress==1.0 for an already-linked file), which must never be
+        mistaken for a finished recheck.  The grace window only extends the
+        wait for checking to appear — it never converts to success; if the
+        recheck is never observed running, fail closed."""
+        seen_checking = False
+        for attempt in range(self.recheck_max_polls):
+            info = self._info(h)
+            if info is None:
+                raise ClientError(
+                    "torrent disappeared from qBittorrent during recheck; "
+                    "NOT seeding.")
+            state = str(info.get("state") or "")
+            checking = state.startswith("checking") or state == "queuedForChecking"
+            progress = float(info.get("progress") or 0.0)
+            if checking:
+                seen_checking = True
+            elif seen_checking:
+                # The recheck was observed running and has now finished;
+                # this progress is the verified truth.
+                return progress
+            elif attempt >= self.recheck_grace_polls:
+                # The recheck was never observed running: the non-checking
+                # state (and its progress — typically a stale 100% from the
+                # pre-recheck fastresume data) cannot be trusted.  Fail
+                # closed rather than resume on stale state.
+                raise ClientError(
+                    "recheck was accepted but never observed running (state "
+                    f"stayed '{state}' through the grace window); refusing "
+                    "to trust the client's stale progress — the torrent was "
+                    "left paused in qBittorrent and is NOT seeding.")
+            time.sleep(self.poll_interval)
+        raise ClientError(
+            "recheck did not finish within "
+            f"~{int(self.recheck_max_polls * self.poll_interval)}s; the torrent "
+            "was left paused in qBittorrent and is NOT seeding.")
+
+    def _detect_start_endpoint(self) -> Optional[str]:
+        """WebUI API >= 2.11 (qBt 5.0) REMOVED /torrents/resume in favour of
+        /torrents/start (404, no alias).  Detect via /app/webapiVersion;
+        return 'start' or 'resume', or None when the version read failed
+        (caller then tries /start and falls back to /resume)."""
+        try:
+            r = self._get("/api/v2/app/webapiVersion")
+            if r.status_code != 200:
+                return None
+            ver = re.match(r"^\s*v?(\d+)\.(\d+)", r.text or "")
+            if not ver:
+                return None
+            major_minor = (int(ver.group(1)), int(ver.group(2)))
+            return "start" if major_minor >= (2, 11) else "resume"
+        except requests.RequestException:
+            return None
+
+    def _start_torrent(self, h: str, steps: list) -> str:
+        """Resume/start the torrent on the version-correct endpoint, checking
+        every response.  Returns the endpoint used."""
+        endpoint = self._detect_start_endpoint()
+        if endpoint is not None:
+            self._post_checked(f"/api/v2/torrents/{endpoint}", {"hashes": h},
+                               endpoint)
+            steps.append(f"POST /api/v2/torrents/{endpoint} (hashes={h}) "
+                         "-> HTTP 200")
+            return endpoint
+        # Version unknown: try the current endpoint first, fall back once.
+        r = self.session.post(f"{self.url}/api/v2/torrents/start",
+                              data={"hashes": h}, headers=self._headers(),
+                              timeout=self.timeout)
+        if r.status_code == 200:
+            steps.append(f"POST /api/v2/torrents/start (hashes={h}) -> HTTP 200")
+            return "start"
+        if r.status_code == 404:
+            steps.append("POST /api/v2/torrents/start -> HTTP 404 "
+                         "(pre-2.11 WebUI); retrying /api/v2/torrents/resume")
+            self._post_checked("/api/v2/torrents/resume", {"hashes": h},
+                               "resume")
+            steps.append(f"POST /api/v2/torrents/resume (hashes={h}) "
+                         "-> HTTP 200")
+            return "resume"
+        raise ClientError(f"qBittorrent start failed (HTTP {r.status_code}).")
+
+    def add(self, *, magnet, info_hash, save_path, torrent_name="",
+            dry_run=False, file_selection=None):
+        magnet = validate_magnet(magnet)
+        selection = file_selection if file_selection else None
+        steps = [
+            f"POST /api/v2/torrents/add  "
+            f"(savepath={save_path}, autoTMM=false, paused=true, stopped=true, "
+            f"skip_checking=false)"
+        ]
+        if dry_run:
+            return AddResult(self.name, True, steps,
+                             "dry-run: no WebUI calls made", True)
+        # Fix 14A-12: resolve the magnet to a .torrent up front (aria2c via the
+        # hardened build_aria2c_args choke point) -- real clients do NOT fetch
+        # magnet metadata while added paused/stopped
+        # (docs/HARNESS-magnet-metadata.md), so a paused magnet add would hang
+        # at the metadata gate forever. On ANY resolution failure this raises
+        # ClientError and the magnet is NEVER sent to qBittorrent.
+        from .download import resolve_magnet_to_torrent
+        torrent_bytes = resolve_magnet_to_torrent(magnet, info_hash)
+        steps.insert(0, "resolved magnet -> .torrent via aria2c "
+                     "(metadata-only, no payload)")
+        self._login()
+        # Per QBITTORRENT_ADD_RECIPE: paused + skip_checking=false + autoTMM=false.
+        r = self.session.post(
+            f"{self.url}/api/v2/torrents/add",
+            files={"torrents": ("resolved.torrent", torrent_bytes,
+                                "application/x-bittorrent")},
+            data={
+                "savepath": save_path,
+                "autoTMM": "false",
+                # qBt 4.x honors "paused"; qBt 5.x renamed it to "stopped".
+                # Sending both keeps "add paused" on every version.
+                "paused": "true",
+                "stopped": "true",
+                "skip_checking": "false",
+            },
+            headers=self._headers(), timeout=max(self.timeout, 60),
+        )
+        if r.status_code != 200:
+            raise ClientError(f"qBittorrent add failed (HTTP {r.status_code}).")
+        # ADP-6: qBittorrent rejects an add (e.g. an invalid magnet) with
+        # HTTP 200 and the literal body "Fails." -- the status code alone is
+        # NOT success.  Believing it would send the recheck/resume machinery
+        # chasing a torrent that was never added (phantom-seed report).
+        if (r.text or "").strip().lower() == "fails.":
+            raise ClientError(
+                "qBittorrent refused the add (HTTP 200, body 'Fails.') -- "
+                "the torrent was NOT added and is NOT seeding.")
+        h = (info_hash or "").lower()
+        if not h:
+            steps.append("WARNING: no info_hash returned by the API; recheck/"
+                         "resume must be triggered manually in qBittorrent.")
+            if selection is not None and selection.unwanted:
+                steps.append(
+                    "WARNING (M5): BEFORE resuming manually, mark these "
+                    "missing large files \"do not download\" in qBittorrent "
+                    "-- resuming without that would download them onto your "
+                    "disk: " + ", ".join(selection.unwanted))
+            return AddResult(
+                self.name, False, steps,
+                "added paused, but the handoff could not be verified (no "
+                "info_hash) — NOT seeding until you recheck and resume "
+                "manually in qBittorrent", False)
+        # Finding 3: the WebUI handle for a BitTorrent v2 *hybrid* torrent is
+        # qBt's truncated-v2 hash, NOT the v1 info-hash.  Resolve the real
+        # handle ONCE here and key every downstream call (metadata/properties,
+        # recheck, info, start/resume) on it.  info_hash itself is unchanged --
+        # it stays the torrent's cryptographic identity for the manifest/verify
+        # flow.  Fail closed if the torrent never appears (never proceed on a
+        # bad/assumed handle).
+        handle = self._resolve_handle(h)
+        if handle is None:
+            raise ClientError(
+                "added paused, but qBittorrent never listed the torrent by "
+                "its info-hash within "
+                f"~{int(self.metadata_max_polls * self.poll_interval)}s, so the "
+                "WebUI addressing handle could not be resolved; the torrent was "
+                "left paused in qBittorrent and is NOT seeding.")
+        if handle != h:
+            steps.append(
+                f"resolved qBt WebUI handle {handle} (v2-hybrid torrent keyed "
+                f"by truncated-v2 hash; v1 info_hash {h})")
+        else:
+            steps.append(f"qBt WebUI handle == info_hash ({h})")
+        h = handle
+        # M4: wait for the magnet's metadata before rechecking.
+        self._wait_for_metadata(h)
+        steps.append("waited for magnet metadata (piece layout known)")
+        # M5: set do-not-download marks BEFORE any recheck/resume so no code
+        # path can resume the torrent while a large missing file is wanted.
+        if selection is not None:
+            self._apply_selection(h, selection, steps)
+        # Recheck hashes the linked bytes; poll it to completion (C2).
+        self._post_checked("/api/v2/torrents/recheck", {"hashes": h}, "recheck")
+        steps.append(f"POST /api/v2/torrents/recheck (hashes={h}) -> HTTP 200")
+        progress = self._wait_recheck_complete(h)
+        if selection is None:
+            if progress < 1.0:
+                # FAIL CLOSED (C2): resuming an incomplete torrent would make
+                # the client download the missing pieces THROUGH the
+                # hardlinks/symlinks into the user's original files, or pull
+                # unlinked sibling files.
+                have, total = self._piece_counts(h)
+                detail = (f"{have} of {total} pieces present"
+                          if total > 0 and have >= 0
+                          else f"only {progress:.1%} of the data present")
+                tail = ("\n" + _path_blindness_hint(save_path)
+                        if _near_zero(progress, have)
+                        else "  (Resuming would download the missing data "
+                             "into your local files.)")
+                raise ClientError(
+                    f"recheck finished but found {detail} — refusing to "
+                    "resume; the torrent was left paused in qBittorrent and "
+                    "is NOT seeding." + tail)
+            steps.append("recheck complete: 100% of the data verified present")
+        else:
+            # M5 partial container: per-file gate (see _gate_selection).
+            self._gate_selection(h, selection, save_path)
+            steps.append(
+                "recheck complete: every locally-expected file verified 100% "
+                f"present ({len(selection.unwanted)} marked do-not-download, "
+                f"{len(selection.expect_fetch)} small companion file(s) to "
+                "fetch)")
+        endpoint = self._start_torrent(h, steps)
+        if selection is not None and selection.expect_fetch:
+            steps.append(
+                "the client will now fetch the small companion file(s): "
+                + ", ".join(selection.expect_fetch))
+        message = (f"added paused -> rechecked (100% present) -> resumed "
+                   f"(/{endpoint} confirmed HTTP 200)")
+        if selection is not None:
+            parts = []
+            if selection.unwanted:
+                parts.append(f"{len(selection.unwanted)} missing large "
+                             "file(s) marked do-not-download")
+            if selection.expect_fetch:
+                parts.append(f"{len(selection.expect_fetch)} small companion "
+                             "file(s) will be fetched")
+            message = (f"added paused -> priorities set -> rechecked (all "
+                       f"locally-expected files 100% present) -> resumed "
+                       f"(/{endpoint} confirmed HTTP 200); " + "; ".join(parts))
+        return AddResult(self.name, True, steps, message, False)
+
+    def probe_local_visibility(self) -> PathVisibilityProbe:
+        """S3: read qBt's own default save path (the client's perspective) and
+        check whether that path exists on the machine llmt runs on.  Works on
+        every qBt version (``/app/preferences`` ``save_path`` is stable across
+        4.6.x and 5.x).  Best-effort: any failure -> unsupported (advisory)."""
+        try:
+            self._login()
+            r = self._get("/api/v2/app/preferences")
+            if r.status_code != 200:
+                return PathVisibilityProbe(
+                    False, detail=f"preferences read HTTP {r.status_code}")
+            prefs = r.json()
+        except (ClientError, requests.RequestException, ValueError) as exc:
+            return PathVisibilityProbe(False, detail=str(exc))
+        default = str((prefs or {}).get("save_path") or "")
+        if not default:
+            return PathVisibilityProbe(
+                True, "", None, "client reported no default save path")
+        visible = os.path.isdir(os.path.expanduser(default))
+        return PathVisibilityProbe(True, default, visible)
+
+
+# --------------------------------------------------------------------------- #
+# Transmission RPC
+# --------------------------------------------------------------------------- #
+
+class TransmissionClient(SeedClient):
+    name = "transmission"
+
+    # Poll tuning (class attributes so tests can shrink them); bounded waits.
+    poll_interval = 1.0
+    metadata_max_polls = 120
+    verify_max_polls = 3600
+    verify_grace_polls = 5
+
+    def __init__(self, url: str, username: Optional[str] = None,
+                 password: Optional[str] = None,
+                 session: Optional[requests.Session] = None,
+                 timeout: int = 30):
+        url = (url or "").rstrip("/")
+        if not (url.startswith("http://") or url.startswith("https://")):
+            raise ClientError("Transmission URL must be http(s):// (RPC endpoint).")
+        self.url = url
+        self.username = username
+        self.password = password
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self._sid = ""
+
+    def _rpc(self, method: str, arguments: dict) -> dict:
+        auth = (self.username, self.password) if self.username else None
+        headers = {}
+        if self._sid:
+            headers["X-Transmission-Session-Id"] = self._sid
+        body = {"method": method, "arguments": arguments}
+        r = self.session.post(self.url, json=body, headers=headers,
+                              auth=auth, timeout=self.timeout)
+        if r.status_code == 409:
+            self._sid = r.headers.get("X-Transmission-Session-Id", "")
+            headers["X-Transmission-Session-Id"] = self._sid
+            r = self.session.post(self.url, json=body, headers=headers,
+                                  auth=auth, timeout=self.timeout)
+        if r.status_code != 200:
+            raise ClientError(f"Transmission RPC {method} failed "
+                              f"(HTTP {r.status_code}).")
+        try:
+            return r.json()
+        except ValueError as exc:
+            raise ClientError("Transmission RPC returned non-JSON.") from exc
+
+    def _rpc_ok(self, method: str, arguments: dict) -> dict:
+        """RPC call whose ``result`` field must be ``success`` (H2 analog:
+        Transmission signals errors in-body over HTTP 200)."""
+        res = self._rpc(method, arguments)
+        if res.get("result") != "success":
+            raise ClientError(f"Transmission {method}: {res.get('result')}")
+        return res
+
+    def _torrent_state(self, tid) -> dict:
+        res = self._rpc_ok("torrent-get", {"ids": [tid], "fields": [
+            "id", "status", "percentDone", "metadataPercentComplete",
+            "recheckProgress", "haveValid", "sizeWhenDone"]})
+        torrents = (res.get("arguments") or {}).get("torrents") or []
+        if not torrents:
+            raise ClientError(
+                "torrent disappeared from Transmission during the handoff; "
+                "NOT seeding.")
+        return torrents[0]
+
+    def _wait_for_metadata(self, tid) -> None:
+        """Magnet metadata resolves asynchronously; verify before that is a
+        no-op.  Bounded poll, honest failure on timeout."""
+        for _attempt in range(self.metadata_max_polls):
+            t = self._torrent_state(tid)
+            mpc = t.get("metadataPercentComplete")
+            if mpc is None or float(mpc) >= 1.0:
+                return
+            time.sleep(self.poll_interval)
+        raise ClientError(
+            "timed out waiting for magnet metadata after "
+            f"~{int(self.metadata_max_polls * self.poll_interval)}s; the "
+            "torrent was left paused in Transmission and is NOT seeding.")
+
+    def _torrent_files(self, tid) -> "tuple[list, list]":
+        """torrent-get files (name/length/bytesCompleted) + fileStats
+        (wanted/priority), shape-checked."""
+        res = self._rpc_ok("torrent-get", {"ids": [tid], "fields": [
+            "id", "files", "fileStats"]})
+        torrents = (res.get("arguments") or {}).get("torrents") or []
+        if not torrents:
+            raise ClientError(
+                "torrent disappeared from Transmission during the handoff; "
+                "NOT seeding.")
+        t = torrents[0] if isinstance(torrents[0], dict) else {}
+        files = t.get("files")
+        stats = t.get("fileStats")
+        files = files if isinstance(files, list) else []
+        stats = stats if isinstance(stats, list) else []
+        if not files:
+            raise ClientError(
+                "Transmission returned an empty/unexpected file list for the "
+                "torrent; cannot verify per-file state -- NOT seeding.")
+        return files, stats
+
+    def _indices_for(self, files: list, paths) -> "list[int]":
+        by_name: dict = {}
+        for i, f in enumerate(files):
+            if isinstance(f, dict):
+                by_name[_norm_torrent_path(f.get("name"))] = i
+        idxs = []
+        for path in paths:
+            i = by_name.get(_norm_torrent_path(path))
+            if i is None:
+                raise ClientError(
+                    f"cannot mark {path!r} do-not-download: the torrent's "
+                    "file list does not contain it (torrent/manifest "
+                    "disagreement) -- refusing to continue; the torrent was "
+                    "left paused in Transmission and is NOT seeding.")
+            idxs.append(i)
+        return idxs
+
+    def _apply_selection(self, tid, selection: FileSelection,
+                         steps: list) -> None:
+        """M5: mark every missing LARGE file files-unwanted BEFORE any
+        verify/start, and read the flag back.  Unconfirmed => ClientError
+        (fail closed, torrent left paused)."""
+        if not selection.unwanted:
+            return
+        files, _stats = self._torrent_files(tid)
+        idxs = self._indices_for(files, selection.unwanted)
+        self._rpc_ok("torrent-set", {"ids": [tid], "files-unwanted": idxs})
+        steps.append(f"torrent-set files-unwanted ({len(idxs)} missing large "
+                     "file(s)) -> success")
+        self._assert_unwanted_applied(tid, selection)
+        steps.append("confirmed do-not-download (wanted=false) on: "
+                     + ", ".join(selection.unwanted))
+
+    def _assert_unwanted_applied(self, tid,
+                                 selection: FileSelection) -> None:
+        """Read fileStats back; every unwanted file must REALLY have
+        wanted=false or the handoff fails closed (no start)."""
+        if not selection.unwanted:
+            return
+        files, stats = self._torrent_files(tid)
+        idxs = self._indices_for(files, selection.unwanted)
+        bad = []
+        for path, i in zip(selection.unwanted, idxs):
+            st = stats[i] if i < len(stats) and isinstance(stats[i], dict)                 else None
+            if st is None or st.get("wanted") is not False:
+                bad.append(path)
+        if bad:
+            raise ClientError(
+                "Transmission did not confirm do-not-download "
+                "(wanted=false) for: " + ", ".join(bad) + " -- refusing to "
+                "start (starting would download the missing large file(s) "
+                "onto your disk); the torrent was left paused in "
+                "Transmission and is NOT seeding.")
+
+    def _gate_selection(self, tid, selection: FileSelection,
+                        save_path: str = "") -> None:
+        """M5 completion gate for a partial container.  Transmission's
+        scalar ``percentDone`` covers WANTED files only (RPC spec: "How much
+        has been downloaded of the files the user wants"), so with
+        still-wanted expect_fetch files missing it is legitimately < 1.0 --
+        and we refuse to trust any scalar here anyway.  The gate reads
+        per-file bytesCompleted/length from torrent-get files: every file
+        the user is supposed to HAVE must be complete; unwanted files are
+        re-confirmed wanted=false (no start window with a large missing
+        file wanted); expect_fetch files may be incomplete by design."""
+        files, _stats = self._torrent_files(tid)
+        unwanted = {_norm_torrent_path(x) for x in selection.unwanted}
+        fetch = {_norm_torrent_path(x) for x in selection.expect_fetch}
+        incomplete = []
+        saw_any_data = False
+        for i, f in enumerate(files):
+            if not isinstance(f, dict):
+                continue
+            name = _norm_torrent_path(f.get("name"))
+            if name in unwanted or name in fetch:
+                continue
+            try:
+                length = int(f.get("length") or 0)
+                done = int(f.get("bytesCompleted") or 0)
+            except (TypeError, ValueError):
+                length, done = 1, 0
+            if done > 0:
+                saw_any_data = True
+            if done < length:
+                incomplete.append(str(f.get("name") or f"file #{i}"))
+        if incomplete:
+            base = (
+                "verify finished but these locally-expected files are not "
+                "100% present: " + ", ".join(incomplete) + " -- refusing to "
+                "start; the torrent was left paused in Transmission and is "
+                "NOT seeding.")
+            if not saw_any_data:
+                raise ClientError(base + "\n" + _path_blindness_hint(save_path))
+            raise ClientError(base + "  (Starting would download the missing "
+                              "data into your local files.)")
+        # M5 hardening: the torrent's own metadata is the final authority on
+        # expect_fetch sizes -- a wrong-but-signed size_bytes must never
+        # cause a large download. Every expect_fetch file, and their sum,
+        # must fit the auto-fetch cap or the handoff fails closed.
+        oversized = []
+        fetch_total = 0
+        for f in files:
+            if not isinstance(f, dict):
+                continue
+            name = _norm_torrent_path(f.get("name"))
+            if name not in fetch:
+                continue
+            length = f.get("length")
+            if (not isinstance(length, int) or isinstance(length, bool)
+                    or length < 0 or length > M5_AUTO_FETCH_MAX_BYTES):
+                oversized.append(str(f.get("name")))
+            else:
+                fetch_total += length
+        if oversized or fetch_total > M5_AUTO_FETCH_MAX_BYTES:
+            names = ", ".join(oversized) if oversized else ", ".join(
+                sorted(fetch))
+            raise ClientError(
+                "refusing to start: the torrent itself reports companion "
+                "file(s) expected to be tiny as over the 10 MiB auto-fetch "
+                "cap (or of unknown size): " + names + " -- the signed "
+                "metadata disagreed with the torrent; the torrent was left "
+                "paused in Transmission and is NOT seeding.")
+        self._assert_unwanted_applied(tid, selection)
+
+    def _wait_verify_complete(self, tid) -> dict:
+        """Poll until the verify finishes (status 1=queued-to-verify,
+        2=verifying); return the final torrent state.  Completion is only
+        believed after a verifying status was OBSERVED and then cleared:
+        right after torrent-verify the torrent may still show stale status 0
+        with its pre-verify percentDone.  The grace window only extends the
+        wait for verifying to appear — never converts to success; if the
+        verify is never observed running, fail closed."""
+        seen_checking = False
+        for attempt in range(self.verify_max_polls):
+            t = self._torrent_state(tid)
+            checking = int(t.get("status") or 0) in (1, 2)
+            done = float(t.get("percentDone") or 0.0)
+            if checking:
+                seen_checking = True
+            elif seen_checking:
+                # The verify was observed running and has now finished.
+                return t
+            elif attempt >= self.verify_grace_polls:
+                raise ClientError(
+                    "verify was accepted but never observed running (status "
+                    f"stayed {t.get('status')} through the grace window); "
+                    "refusing to trust the client's stale progress — the "
+                    "torrent was left paused in Transmission and is NOT "
+                    "seeding.")
+            time.sleep(self.poll_interval)
+        raise ClientError(
+            "verify did not finish within "
+            f"~{int(self.verify_max_polls * self.poll_interval)}s; the torrent "
+            "was left paused in Transmission and is NOT seeding.")
+
+    def add(self, *, magnet, info_hash, save_path, torrent_name="",
+            dry_run=False, file_selection=None):
+        magnet = validate_magnet(magnet)
+        selection = file_selection if file_selection else None
+        steps = [f"torrent-add (metainfo=<resolved .torrent>, "
+                 f"download-dir={save_path}, paused=true)"]
+        if dry_run:
+            return AddResult(self.name, True, steps,
+                             "dry-run: no RPC calls made", True)
+        # Fix 14A-12: resolve the magnet to a .torrent up front (see
+        # QbtClient.add) and hand Transmission the metainfo (base64) instead of
+        # the magnet -- a paused magnet never fetches metadata. Resolution
+        # failure raises ClientError here; the magnet is never sent.
+        from .download import resolve_magnet_to_torrent
+        torrent_bytes = resolve_magnet_to_torrent(magnet, info_hash)
+        steps.insert(0, "resolved magnet -> .torrent via aria2c "
+                     "(metadata-only, no payload)")
+        res = self._rpc("torrent-add", {
+            "metainfo": base64.b64encode(torrent_bytes).decode("ascii"),
+            "download-dir": save_path, "paused": True,
+        })
+        if res.get("result") != "success":
+            raise ClientError(f"Transmission torrent-add: {res.get('result')}")
+        args = res.get("arguments", {}) or {}
+        tobj = args.get("torrent-added") or args.get("torrent-duplicate") or {}
+        tid = tobj.get("id")
+        if tid is None:
+            steps.append("WARNING: no torrent id returned; verify/start manually.")
+            if selection is not None and selection.unwanted:
+                steps.append(
+                    "WARNING (M5): BEFORE starting manually, mark these "
+                    'missing large files "do not download" in Transmission '
+                    "-- starting without that would download them onto your "
+                    "disk: " + ", ".join(selection.unwanted))
+            return AddResult(
+                self.name, False, steps,
+                "added paused, but the handoff could not be verified (no "
+                "torrent id) — NOT seeding until you verify and start "
+                "manually in Transmission", False)
+        # Wait for magnet metadata, then verify and poll it to completion.
+        self._wait_for_metadata(tid)
+        steps.append("waited for magnet metadata")
+        # M5: set do-not-download marks BEFORE any verify/start so no code
+        # path can start the torrent while a large missing file is wanted.
+        if selection is not None:
+            self._apply_selection(tid, selection, steps)
+        self._rpc_ok("torrent-verify", {"ids": [tid]})
+        steps.append(f"torrent-verify (ids=[{tid}]) -> success")
+        t = self._wait_verify_complete(tid)
+        if selection is None:
+            done = float(t.get("percentDone") or 0.0)
+            if done < 1.0:
+                # FAIL CLOSED: starting would download the missing data
+                # through the link farm into the user's original files.
+                have = t.get("haveValid")
+                want = t.get("sizeWhenDone")
+                detail = (f"{have} of {want} bytes present"
+                          if isinstance(have, int) and isinstance(want, int)
+                          and want > 0
+                          else f"only {done:.1%} of the data present")
+                tail = ("\n" + _path_blindness_hint(save_path)
+                        if _near_zero(done, have)
+                        else "  (Starting would download the missing data "
+                             "into your local files.)")
+                raise ClientError(
+                    f"verify finished but found {detail} — refusing to "
+                    "start; the torrent was left paused in Transmission and "
+                    "is NOT seeding." + tail)
+            steps.append("verify complete: 100% of the data verified present")
+        else:
+            # M5 partial container: per-file gate (see _gate_selection).
+            self._gate_selection(tid, selection, save_path)
+            steps.append(
+                "verify complete: every locally-expected file verified 100% "
+                f"present ({len(selection.unwanted)} marked do-not-download, "
+                f"{len(selection.expect_fetch)} small companion file(s) to "
+                "fetch)")
+        self._rpc_ok("torrent-start", {"ids": [tid]})
+        steps.append(f"torrent-start (ids=[{tid}]) -> success")
+        if selection is not None and selection.expect_fetch:
+            steps.append(
+                "the client will now fetch the small companion file(s): "
+                + ", ".join(selection.expect_fetch))
+        message = ("added paused -> verified (100% present) -> started "
+                   "(torrent-start confirmed success)")
+        if selection is not None:
+            parts = []
+            if selection.unwanted:
+                parts.append(f"{len(selection.unwanted)} missing large "
+                             "file(s) marked do-not-download")
+            if selection.expect_fetch:
+                parts.append(f"{len(selection.expect_fetch)} small companion "
+                             "file(s) will be fetched")
+            message = ("added paused -> files-unwanted set -> verified (all "
+                       "locally-expected files 100% present) -> started "
+                       "(torrent-start confirmed success); "
+                       + "; ".join(parts))
+        return AddResult(self.name, True, steps, message, False)
+
+    def probe_local_visibility(self) -> PathVisibilityProbe:
+        """S3: read Transmission's own default download dir (its perspective)
+        and check whether that path exists on the machine llmt runs on.
+        Best-effort: any failure -> unsupported (advisory only)."""
+        try:
+            sess = self._rpc("session-get", {}).get("arguments") or {}
+        except (ClientError, requests.RequestException, ValueError) as exc:
+            return PathVisibilityProbe(False, detail=str(exc))
+        default = str((sess or {}).get("download-dir") or "")
+        if not default:
+            return PathVisibilityProbe(
+                True, "", None, "client reported no default download dir")
+        visible = os.path.isdir(os.path.expanduser(default))
+        return PathVisibilityProbe(True, default, visible)
+
+
+# --------------------------------------------------------------------------- #
+# Fallback (no client) + test fake
+# --------------------------------------------------------------------------- #
+
+class FallbackClient(SeedClient):
+    """No client reachable/configured: surface the magnet plus manual-add
+    instructions.  The instructions MUST keep the fail-closed handoff intact:
+    add PAUSED, recheck, and resume only on a 100% recheck — an auto-start
+    client would begin downloading before the recheck runs."""
+    name = "fallback"
+
+    def add(self, *, magnet, info_hash, save_path, torrent_name="",
+            dry_run=False, file_selection=None):
+        magnet = validate_magnet(magnet)
+        selection = file_selection if file_selection else None
+        steps = ["no torrent client configured/reachable"]
+        if selection is None:
+            steps.append(
+                f"to seed manually: add this magnet PAUSED (do not start it), "
+                f"set the save path to {save_path}, then force-recheck so the "
+                f"client discovers the existing bytes, and resume only once "
+                f"the recheck reads 100%")
+            return AddResult("fallback-magnet", True, steps, magnet, dry_run)
+        # M5: this adapter cannot set priorities itself -- instructions are
+        # its mechanism, so they must carry the same do-not-download guidance.
+        steps.append(
+            f"to seed manually: add this magnet PAUSED (do not start it) and "
+            f"set the save path to {save_path}")
+        if selection.unwanted:
+            steps.append(
+                "IMPORTANT (M5): BEFORE resuming, mark these missing large "
+                'files "do not download" (priority 0 / deselect) in your '
+                "client -- llmt never downloads model-weight files on your "
+                "behalf: " + ", ".join(selection.unwanted) + ". With them "
+                "deselected the torrent will seed only the files you have "
+                "and will show as incomplete in your client.")
+        if selection.expect_fetch:
+            steps.append(
+                "note (M5): these small companion files (<= 10 MiB total) "
+                "are missing locally and WILL be downloaded by your client "
+                f"into {save_path} once resumed: "
+                + ", ".join(selection.expect_fetch))
+        steps.append(
+            "then force-recheck so the client discovers the existing bytes, "
+            "confirm every file you already have reads 100% complete, and "
+            "only then resume (deselected files and the small companion "
+            "files above will not read 100% -- that is expected)")
+        return AddResult("fallback-magnet", True, steps, magnet, dry_run)
+
+
+class FakeClient(SeedClient):
+    """In-memory client for tests: records adds and asserts the recipe order."""
+    name = "fake"
+
+    def __init__(self, fail: bool = False):
+        self.added: list = []
+        self.fail = fail
+
+    def add(self, *, magnet, info_hash, save_path, torrent_name="",
+            dry_run=False, file_selection=None):
+        validate_magnet(magnet)  # exercise the same anti-injection gate
+        if self.fail:
+            raise ClientError("fake client add failure")
+        seq = ["add(paused=true,skip_checking=false,autoTMM=false)"]
+        if file_selection and file_selection.unwanted:
+            seq.append("set-unwanted(priority=0)")
+        seq += ["recheck", "resume"]
+        rec = {
+            "magnet": magnet, "info_hash": info_hash, "save_path": save_path,
+            "torrent_name": torrent_name, "dry_run": dry_run, "sequence": seq,
+            "file_selection": file_selection,
+        }
+        self.added.append(rec)
+        return AddResult("fake", True, seq, "recorded", dry_run)
+
+
+# --------------------------------------------------------------------------- #
+# Selection from flags / env
+# --------------------------------------------------------------------------- #
+
+def build_client(args) -> SeedClient:
+    """Choose an adapter from flags/env. Never hardcodes connection details."""
+    kind = getattr(args, "client", None)
+    qb_url = getattr(args, "qb_url", None) or os.environ.get("LLMT_QB_URL")
+    tr_url = getattr(args, "tr_url", None) or os.environ.get("LLMT_TR_URL")
+
+    if kind == "none":
+        return FallbackClient()
+
+    if kind == "qbittorrent" or (kind is None and qb_url):
+        if not qb_url:
+            raise ClientError("qBittorrent selected but no --qb-url / LLMT_QB_URL.")
+        return QBittorrentClient(
+            qb_url,
+            getattr(args, "qb_user", None) or os.environ.get("LLMT_QB_USER"),
+            getattr(args, "qb_pass", None) or os.environ.get("LLMT_QB_PASS"),
+            timeout=getattr(args, "timeout", 30),
+        )
+
+    if kind == "transmission" or (kind is None and tr_url):
+        if not tr_url:
+            raise ClientError("Transmission selected but no --tr-url / LLMT_TR_URL.")
+        return TransmissionClient(
+            tr_url,
+            getattr(args, "tr_user", None) or os.environ.get("LLMT_TR_USER"),
+            getattr(args, "tr_pass", None) or os.environ.get("LLMT_TR_PASS"),
+            timeout=getattr(args, "timeout", 30),
+        )
+
+    return FallbackClient()