Workers print their own code and are claimed from the site; fetch and verify llama.cpp

distinct_agent/cli.py

@@ -152,16 +152,42 @@ def _runner_problem(args) -> str:
         )
     if _find_llama_server():
         return ""
+    if _obtain_llama_server(args):
+        return ""
+    from . import runtime as _runtime
+
+    where = _runtime.platform_key()
+    if _runtime.pin_for(where) is None:
+        # Nothing recorded for this platform, so nothing was attempted. Say
+        # which platform, because the answer is "add a pin for it" and that is
+        # a thing somebody can do.
+        return (
+            "This worker has no llama.cpp to run a model with, and none is recorded\n"
+            f"for {where}, so nothing was downloaded.\n"
+            "\n"
+            "  An unverified build of the program that runs the models is the one\n"
+            "  thing this project will not install for you. Either point at a build\n"
+            "  you already have:\n"
+            "\n"
+            "    --llama-server /path/to/llama-server\n"
+            "\n"
+            "  or start without a model. The worker still joins, and still runs every\n"
+            "  tool and skill in the library; only the model's own replies are absent:\n"
+            "\n"
+            "    --demo-runner\n"
+            "\n"
+            f"  To record a build for {where}, run:\n"
+            f"    python scripts/record_llama_pin.py {where}\n"
+        )
     return (
-        "This worker has no llama.cpp to run a model with.\n"
+        "This worker has no llama.cpp to run a model with, and the pinned build\n"
+        "could not be installed. The reason is above.\n"
         "\n"
-        "  llama.cpp is a separate program, not part of this project. Get a build\n"
-        "  from https://github.com/ggml-org/llama.cpp/releases, unzip it, and either\n"
-        "  put llama-server on your PATH or point at it:\n"
+        "  Point at a build you already have:\n"
         "\n"
-        "    --llama-server C:\\path\\to\\llama-server.exe\n"
+        "    --llama-server /path/to/llama-server\n"
         "\n"
-        "  Or start without a model. The worker still pairs and still runs every\n"
+        "  or start without a model. The worker still joins, and still runs every\n"
         "  tool and skill in the library; only the model's own replies are absent:\n"
         "\n"
         "    --demo-runner\n"
@@ -169,11 +195,18 @@ def _runner_problem(args) -> str:
 
 
 def _find_llama_server() -> str:
-    """Look in runtime/ first, then PATH."""
+    """Look in runtime/ first, then PATH.
+
+    ``runtime/`` is where :func:`distinct_agent.runtime.ensure` installs the
+    pinned build, so a worker that fetched one on a previous run finds it here
+    and does not fetch again.
+    """
+
+    from . import runtime as _runtime
 
-    bundled = Path(__file__).resolve().parent.parent / "runtime" / "llama-server.exe"
-    if bundled.is_file():
-        return str(bundled)
+    installed = _runtime.installed_server()
+    if installed:
+        return installed
     from shutil import which
 
     for name in ("llama-server", "llama-server.exe"):
@@ -183,6 +216,49 @@ def _find_llama_server() -> str:
     return ""
 
 
+def _obtain_llama_server(args) -> str:
+    """Fetch and verify the pinned llama.cpp for this machine, or say why not.
+
+    Returns the path, or an empty string when nothing could be installed. The
+    reasons are printed as they happen rather than collected, because the
+    download is the slow part and a volunteer watching a progress line wants to
+    know what it is for.
+    """
+
+    from . import runtime as _runtime
+
+    if getattr(args, "no_fetch_runtime", False):
+        return ""
+    pin = _runtime.pin_for()
+    if pin is None:
+        return ""
+    print(
+        f"No llama.cpp on this machine. Fetching the pinned build "
+        f"({pin.tag}, {pin.bytes / (1024 * 1024):.0f} MB) and verifying it against "
+        "its recorded SHA-256. This happens once.",
+        file=sys.stderr,
+        flush=True,
+    )
+    last = [-1]
+
+    def report(fraction: float, message: str) -> None:
+        percent = int(fraction * 100)
+        if percent // 10 != last[0] // 10 or fraction >= 1.0:
+            last[0] = percent
+            print(f"  llama.cpp: {message} ({percent}%)", file=sys.stderr, flush=True)
+
+    try:
+        return _runtime.ensure(progress=report)
+    except _runtime.RuntimeVerificationError as exc:
+        # A digest mismatch is not a transient failure and must not be retried
+        # around: it is what a substituted build looks like.
+        print(f"\n{exc}\n", file=sys.stderr, flush=True)
+        return ""
+    except _runtime.RuntimeUnavailable as exc:
+        print(f"  llama.cpp could not be installed: {exc}", file=sys.stderr, flush=True)
+        return ""
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Run a Distinct local inference worker")
     parser.add_argument(
@@ -357,6 +433,15 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="ID=PATH",
         help=argparse.SUPPRESS,
     )
+    parser.add_argument(
+        "--no-fetch-runtime",
+        action="store_true",
+        help=(
+            "never download llama.cpp. The worker uses one already on this "
+            "machine or refuses to run models, which is what an operator on a "
+            "metered or air-gapped connection wants."
+        ),
+    )
     parser.add_argument(
         "--llama-server",
         nargs="?",
@@ -539,18 +624,34 @@ def _forget_servers(args) -> int:
 def _server_pairs(urls, codes):
     """Match each --server to its --pair, or explain the mismatch.
 
-    Positional matching, because it is the only scheme that reads correctly
-    aloud: "this server, this code; that server, that code". A mismatch is an
-    error rather than a best guess, since guessing would mean sending one
-    server's pairing code to another, which is a credential leak dressed up as
-    convenience.
+    With no ``--pair`` values at all, every server is paired the other way
+    round: the worker invents a claim code, prints it, and waits for somebody
+    signed in to enter it. That is the path the website documents, because the
+    old one -- fetch a code from the page, carry it to a terminal -- reliably
+    produced a person typing a value of their own where the code went and being
+    told one program later that their code was invalid.
+
+    ``--pair`` is kept for scripted setups, where a code is minted and consumed
+    by the same program and nobody reads anything. Positional matching, because
+    it is the only scheme that reads correctly aloud: "this server, this code;
+    that server, that code". A mismatch is an error rather than a best guess,
+    since guessing would mean sending one server's code to another, which is a
+    credential leak dressed up as convenience.
     """
 
+    if not codes:
+        # NO --pair AT ALL IS THE ORDINARY CASE NOW.
+        #
+        # Every server gets its own freshly invented claim code, and the
+        # operator types it into that server's page. `None` for a code is the
+        # signal further down to register-and-wait rather than pair.
+        return [(url, None) for url in urls]
     if len(codes) != len(urls):
         print(
             f"{len(urls)} --server value(s) and {len(codes)} --pair value(s). "
-            "Each server needs its own fresh pairing code, given in the same "
-            "order. Codes are not interchangeable between servers.",
+            "Either give no --pair at all, and each server will print a code for "
+            "you to enter on its page, or give one code per server in the same "
+            "order. Codes are never interchangeable between servers.",
             file=sys.stderr,
         )
         return None
@@ -578,6 +679,92 @@ def _servers_file(explicit: str | None) -> Path:
     return shared_cache_directory().parent / "servers.json"
 
 
+def _register_and_wait(
+    url,
+    capabilities,
+    *,
+    access_code,
+    client_factory,
+    allow_remote,
+    allow_plaintext,
+    signing_public_key,
+    poll_seconds: float = 3.0,
+    announce=None,
+    sleep=None,
+):
+    """Print a claim code for this server and wait until somebody enters it.
+
+    Returns the transport once the worker has been claimed, or ``None`` if it
+    was not claimed in time or the server refused the registration.
+
+    The wait is deliberately visible. A worker that registered silently and sat
+    there would look identical to one that had hung, and the whole point of
+    this direction is that the person is looking at the terminal when the code
+    appears.
+    """
+
+    import time as _time
+
+    from .access import new_access_code as _new_code
+
+    say = announce or (lambda text: print(text, file=sys.stderr, flush=True))
+    nap = sleep or _time.sleep
+    claim_code = _new_code()
+    try:
+        transport = GradioAgentTransport.register(
+            url,
+            claim_code,
+            capabilities,
+            access_code=access_code,
+            client_factory=client_factory,
+            allow_remote=allow_remote or None,
+            allow_plaintext=allow_plaintext or None,
+            signing_public_key=signing_public_key,
+        )
+    except (AgentTransportError, TypeError, ValueError) as exc:
+        say(f"Registering with {url} failed: {exc}")
+        return None
+
+    say("")
+    say("  ┌─────────────────────────────────────────────────────────┐")
+    say("  │  This worker is waiting to be claimed.                  │")
+    say("  └─────────────────────────────────────────────────────────┘")
+    say("")
+    say(f"    Sign in at  {url}")
+    say('    open "Run a community agent", and enter this code:')
+    say("")
+    say(f"        {claim_code}")
+    say("")
+    say("    Nobody can use this machine until you do, and the code works")
+    say("    only once. Waiting…")
+    say("")
+
+    deadline = _time.monotonic() + 15 * 60
+    while _time.monotonic() < deadline:
+        try:
+            state = transport.claim_state()
+        except (AgentTransportError, TypeError, ValueError):
+            # A poll that fails is not a claim that failed. Keep waiting; a
+            # server that is really gone will still be gone at the deadline.
+            state = "waiting"
+        if state == "claimed":
+            say(f"Claimed. {capabilities.name!r} is now serving {url} as {transport.agent_id}.")
+            return transport
+        if state == "gone":
+            say(
+                "This worker's registration expired before anybody claimed it. "
+                "Nothing was left running on the server; start the worker again "
+                "for a fresh code."
+            )
+            return None
+        nap(poll_seconds)
+    say(
+        "Nobody claimed this worker within fifteen minutes, so it has stopped "
+        "waiting. Start it again for a fresh code."
+    )
+    return None
+
+
 def _join_server(
     url,
     code,
@@ -618,24 +805,38 @@ def _join_server(
         tools=capabilities.tools,
     )
     identity_key = generate_ed25519_key()
-    try:
-        transport = GradioAgentTransport.pair(
+    if code is None:
+        # THE CODE GOES FROM HERE TO THE BROWSER, NOT THE OTHER WAY.
+        transport = _register_and_wait(
             url,
-            code,
             capabilities,
             access_code=access_code,
             client_factory=client_factory,
-            allow_remote=allow_remote or None,
-            allow_plaintext=allow_plaintext or None,
+            allow_remote=allow_remote,
+            allow_plaintext=allow_plaintext,
             signing_public_key=ed25519_public_key(identity_key),
         )
-    except (AgentTransportError, TypeError, ValueError) as exc:
-        print(f"Pairing with {url} failed: {exc}", file=sys.stderr)
-        return None, None
-    print(
-        f"Paired {capabilities.name!r} with {url} as {transport.agent_id}.",
-        file=sys.stderr,
-    )
+        if transport is None:
+            return None, None
+    else:
+        try:
+            transport = GradioAgentTransport.pair(
+                url,
+                code,
+                capabilities,
+                access_code=access_code,
+                client_factory=client_factory,
+                allow_remote=allow_remote or None,
+                allow_plaintext=allow_plaintext or None,
+                signing_public_key=ed25519_public_key(identity_key),
+            )
+        except (AgentTransportError, TypeError, ValueError) as exc:
+            print(f"Pairing with {url} failed: {exc}", file=sys.stderr)
+            return None, None
+        print(
+            f"Paired {capabilities.name!r} with {url} as {transport.agent_id}.",
+            file=sys.stderr,
+        )
 
     # -------- Consent handshake: catalogue, approval, gate ----------
     #
@@ -786,9 +987,6 @@ def main(
         # crash. Argparse-level mistakes deserve argparse-level answers.
         print("--demo-prompt needs something to ask; it was empty.", file=sys.stderr)
         return 2
-    if args.server and transport is None and not args.pair:
-        print("--server requires a fresh --pair code.", file=sys.stderr)
-        return 2
     if args.list_servers:
         return _list_servers(args)
     if args.forget_server:
@@ -1290,15 +1488,17 @@ def main(
             # time anybody sees it: the servers keep a digest and this process
             # does not write it anywhere.
             access_code = new_access_code()
-            # `--server` is repeatable, so this is a list. One worker can serve
-            # several servers with the same code, and the invitation names them
-            # all rather than picking one and quietly misdirecting the people
-            # sent to the others.
-            print(
-                announce_access_code(access_code, servers=tuple(args.server or ())),
-                file=sys.stderr,
-                flush=True,
-            )
+            # PRINTED AFTER THE JOIN, NOT BEFORE IT.
+            #
+            # This used to be announced here, which put two high-entropy codes
+            # on screen at once: the access code to share, and then the claim
+            # code to enter. Two codes visible together is the same confusion
+            # this whole change exists to remove -- the person scrolls back,
+            # finds *a* code, and uses it for the wrong thing.
+            #
+            # One at a time, in the order they are needed: the claim code while
+            # the worker waits, and the access code once it is actually running
+            # and there is something worth sharing.
             # Kept so the dashboard can show it. It is printed once and stored
             # nowhere on disk, so a screen that could not show it would leave
             # somebody who scrolled past it with no way to get it back short of
@@ -1338,6 +1538,15 @@ def main(
                     flush=True,
                 )
                 return 2
+            # `--server` is repeatable, so this is a list. One worker can serve
+            # several servers with the same code, and the invitation names them
+            # all rather than picking one and quietly misdirecting the people
+            # sent to the others.
+            print(
+                announce_access_code(access_code, servers=tuple(args.server or ())),
+                file=sys.stderr,
+                flush=True,
+            )
             if len(links) == 1:
                 # One server: the transport it paired with, unwrapped. The
                 # fan-out is a real object with real behaviour and there is no

distinct_agent/runtime.py

@@ -0,0 +1,388 @@
+"""Getting llama.cpp onto a volunteer's machine, with the same rules as weights.
+
+WHY THIS EXISTS.
+
+The setup used to end with a wall. A volunteer cloned the repository, ran the
+install, ran the worker, and was told to go to another project's releases page,
+pick the right build for their machine out of a dozen, unzip it somewhere, and
+either edit their PATH or pass a path back on the command line. Their reaction
+was the correct one: *why do I have to provide this, it should be baked into
+the repo*.
+
+It cannot literally be in the repository. A llama.cpp release is around a
+hundred megabytes per platform, there is one per operating system and per
+accelerator, and it is a separate project with its own release cadence. Putting
+those in a Space repository would make every clone enormous and every llama.cpp
+release a commit here.
+
+``llama-cpp-python`` was the other obvious answer and is worse: with no
+matching wheel it compiles from source, so on a Windows machine without a
+build toolchain the failure moves from "run the worker" to ``pip install``
+itself, which is a wall one step earlier and harder to read.
+
+So this does what the project already does for model weights: fetches a
+**pinned** release over TLS and refuses to install it unless the bytes match a
+**recorded SHA-256**. One command, nothing to go and get, and the thing that
+runs the models is verified rather than trusted.
+
+WHAT IS DELIBERATELY NOT DONE.
+
+There is no trust-on-first-use path. Reading a digest out of the same response
+that carried the download proves only that the bytes arrived intact, which TLS
+already said. This project withholds a *model* for exactly that reason --
+``llama-2-7b-chat`` is refused with "no upstream repository, pinned revision or
+SHA-256 digest recorded, so this worker cannot obtain the exact published file
+or confirm what it ran" -- and the program that executes those models cannot be
+held to a lower standard than the models.
+
+A platform with no recorded digest therefore gets no automatic download. It is
+told so plainly, and keeps both manual routes: ``--llama-server`` for a build
+the operator already has, and ``--demo-runner`` to run the library's tools and
+skills with no model at all.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import platform
+import shutil
+import stat
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Optional
+
+#: Where the pins live. A data file rather than a literal so that recording a
+#: new platform, or moving to a newer llama.cpp, is a data change somebody can
+#: review as a diff of digests.
+PIN_FILE = Path(__file__).resolve().parent.parent / "llama_runtime.json"
+
+#: Releases are served from github.com and redirected to their object store.
+#: Anywhere else and the download is refused, for the same reason the weights
+#: fetcher refuses a redirect off Hugging Face: a download that has been bounced
+#: somewhere unexpected is no longer the download that was asked for.
+RUNTIME_REDIRECT_HOSTS = ("github.com", "githubusercontent.com", "github-releases.githubusercontent.com")
+
+_CHUNK = 1024 * 1024
+
+#: A llama.cpp Windows archive is about 30 MB; a CUDA one rather more. This is
+#: a bomb guard, not a size expectation: an archive claiming to be larger than
+#: this is refused before a byte of it is written.
+MAX_ARCHIVE_BYTES = 600 * 1024 * 1024
+
+#: The unpacked tree is checked against the same ceiling, so an archive that is
+#: small on the wire and enormous on disk is refused rather than unpacked.
+MAX_UNPACKED_BYTES = 900 * 1024 * 1024
+
+
+class RuntimeUnavailable(RuntimeError):
+    """The runtime could not be obtained, with a sentence saying why."""
+
+
+class RuntimeVerificationError(RuntimeUnavailable):
+    """The bytes arrived but did not match the recorded digest."""
+
+
+class _RuntimeRedirects(urllib.request.HTTPRedirectHandler):
+    max_redirections = 10
+
+    @staticmethod
+    def _permitted(url: str) -> bool:
+        parsed = urllib.parse.urlsplit(url)
+        if parsed.scheme != "https":
+            return False
+        host = (parsed.hostname or "").casefold().rstrip(".")
+        if not host:
+            return False
+        return any(
+            host == allowed or host.endswith("." + allowed)
+            for allowed in RUNTIME_REDIRECT_HOSTS
+        )
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D102
+        if not self._permitted(newurl):
+            raise urllib.error.HTTPError(
+                newurl,
+                code,
+                "the llama.cpp download was redirected off GitHub and was refused",
+                headers,
+                fp,
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def _opener() -> Callable[..., Any]:
+    return urllib.request.build_opener(_RuntimeRedirects).open
+
+
+@dataclass(frozen=True)
+class RuntimePin:
+    """One platform's recorded build."""
+
+    key: str
+    tag: str
+    asset: str
+    url: str
+    sha256: str
+    bytes: int = 0
+
+    @property
+    def recorded(self) -> bool:
+        return bool(self.url and len(self.sha256) == 64)
+
+
+def platform_key(system: str = "", machine: str = "") -> str:
+    """The key this machine looks itself up under.
+
+    Coarse on purpose: operating system and architecture, nothing about the
+    accelerator. An operator who wants a CUDA or Metal build passes
+    ``--llama-server``; automatic installation picks the build that runs
+    everywhere rather than the fastest one, because a fast build that does not
+    start is worse than a slow one that does.
+    """
+
+    system = (system or platform.system()).casefold()
+    machine = (machine or platform.machine()).casefold()
+    if machine in {"amd64", "x86_64", "x64"}:
+        arch = "x64"
+    elif machine in {"arm64", "aarch64"}:
+        arch = "arm64"
+    else:
+        arch = machine or "unknown"
+    if system.startswith("win"):
+        return f"windows-{arch}"
+    if system == "darwin":
+        return f"macos-{arch}"
+    if system == "linux":
+        return f"linux-{arch}"
+    return f"{system or 'unknown'}-{arch}"
+
+
+def load_pins(path: Optional[Path] = None) -> dict[str, RuntimePin]:
+    """Read the recorded builds, or an empty mapping if none are recorded."""
+
+    source = path or PIN_FILE
+    try:
+        raw = json.loads(source.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    builds = raw.get("builds") if isinstance(raw, Mapping) else None
+    if not isinstance(builds, Mapping):
+        return {}
+    pins: dict[str, RuntimePin] = {}
+    for key, entry in builds.items():
+        if not isinstance(entry, Mapping):
+            continue
+        pins[str(key)] = RuntimePin(
+            key=str(key),
+            tag=str(entry.get("tag", "")),
+            asset=str(entry.get("asset", "")),
+            url=str(entry.get("url", "")),
+            sha256=str(entry.get("sha256", "")).casefold(),
+            bytes=int(entry.get("bytes", 0) or 0),
+        )
+    return pins
+
+
+def pin_for(key: str = "", path: Optional[Path] = None) -> Optional[RuntimePin]:
+    pin = load_pins(path).get(key or platform_key())
+    return pin if pin is not None and pin.recorded else None
+
+
+def runtime_directory(root: Optional[Path] = None) -> Path:
+    """Where an installed llama.cpp lives: ``runtime/`` beside the project."""
+
+    return (root or PIN_FILE.parent) / "runtime"
+
+
+def installed_server(root: Optional[Path] = None) -> str:
+    """The path to an already-installed llama-server, or empty."""
+
+    directory = runtime_directory(root)
+    for name in ("llama-server.exe", "llama-server"):
+        candidate = directory / name
+        if candidate.is_file():
+            return str(candidate)
+    # Some archives nest everything one level down under build/bin.
+    for candidate in sorted(directory.glob("**/llama-server*")):
+        if candidate.is_file() and candidate.suffix in {"", ".exe"}:
+            return str(candidate)
+    return ""
+
+
+def _safe_members(archive: zipfile.ZipFile) -> list[zipfile.ZipInfo]:
+    """Every member that may be written, refusing traversal and bombs.
+
+    ``ZipFile.extractall`` sanitises paths in modern Python, but it has no
+    opinion about total size, and this archive comes from outside the project.
+    Both are checked here so the refusal names the member rather than filling a
+    volunteer's disk and failing later.
+    """
+
+    total = 0
+    members: list[zipfile.ZipInfo] = []
+    for info in archive.infolist():
+        name = info.filename
+        if name.endswith("/"):
+            continue
+        pure = Path(name)
+        if pure.is_absolute() or ".." in pure.parts or (len(name) > 1 and name[1] == ":"):
+            raise RuntimeUnavailable(
+                f"the llama.cpp archive contains an unsafe path ({name!r}) and was not unpacked"
+            )
+        total += info.file_size
+        if info.file_size > MAX_UNPACKED_BYTES or total > MAX_UNPACKED_BYTES:
+            raise RuntimeUnavailable(
+                "the llama.cpp archive unpacks to more than "
+                f"{MAX_UNPACKED_BYTES // (1024 * 1024)} MB and was refused"
+            )
+        members.append(info)
+    return members
+
+
+def ensure(
+    *,
+    root: Optional[Path] = None,
+    key: str = "",
+    progress: Optional[Callable[[float, str], None]] = None,
+    opener: Optional[Callable[..., Any]] = None,
+    pins_path: Optional[Path] = None,
+) -> str:
+    """Install the pinned llama.cpp for this machine and return its path.
+
+    Returns the path to ``llama-server``. Raises :class:`RuntimeUnavailable`
+    with a sentence a volunteer can act on when there is nothing recorded for
+    this platform, and :class:`RuntimeVerificationError` when the bytes do not
+    match -- in which case nothing is installed.
+    """
+
+    existing = installed_server(root)
+    if existing:
+        return existing
+
+    resolved = key or platform_key()
+    pin = pin_for(resolved, pins_path)
+    if pin is None:
+        raise RuntimeUnavailable(
+            f"no llama.cpp build is recorded for {resolved}, so this worker will not "
+            "download one: an unverified build of the program that runs the models is "
+            "exactly what this project refuses to install. Point at a build you already "
+            "have with --llama-server, or start without a model using --demo-runner."
+        )
+
+    target = runtime_directory(root)
+    target.mkdir(parents=True, exist_ok=True)
+    fetch = opener or _opener()
+    digest = hashlib.sha256()
+    written = 0
+
+    if progress is not None:
+        progress(0.0, f"Fetching llama.cpp {pin.tag} for {resolved}")
+
+    with tempfile.TemporaryDirectory(prefix="distinct-runtime-") as scratch:
+        archive_path = Path(scratch) / "llama.zip"
+        try:
+            request = urllib.request.Request(
+                pin.url,
+                headers={"User-Agent": "distinct-agent", "Accept": "application/octet-stream"},
+            )
+            with fetch(request, timeout=60) as response:
+                declared = 0
+                try:
+                    declared = int(response.headers.get("Content-Length") or 0)
+                except (TypeError, ValueError):
+                    declared = 0
+                if declared and declared > MAX_ARCHIVE_BYTES:
+                    raise RuntimeUnavailable(
+                        "the llama.cpp download declares more than "
+                        f"{MAX_ARCHIVE_BYTES // (1024 * 1024)} MB and was refused"
+                    )
+                with archive_path.open("wb") as handle:
+                    while True:
+                        chunk = response.read(_CHUNK)
+                        if not chunk:
+                            break
+                        handle.write(chunk)
+                        digest.update(chunk)
+                        written += len(chunk)
+                        if written > MAX_ARCHIVE_BYTES:
+                            raise RuntimeUnavailable(
+                                "the llama.cpp download exceeded "
+                                f"{MAX_ARCHIVE_BYTES // (1024 * 1024)} MB and was stopped"
+                            )
+                        if progress is not None and declared:
+                            progress(
+                                min(0.99, written / declared),
+                                f"Fetching llama.cpp {pin.tag}",
+                            )
+        except RuntimeUnavailable:
+            raise
+        except (OSError, urllib.error.URLError, ValueError) as exc:
+            raise RuntimeUnavailable(
+                f"could not fetch llama.cpp {pin.tag} for {resolved}: "
+                f"{type(exc).__name__}: {exc}. Point at a build you already have with "
+                "--llama-server, or start without a model using --demo-runner."
+            ) from exc
+
+        actual = digest.hexdigest()
+        if actual != pin.sha256:
+            raise RuntimeVerificationError(
+                f"the llama.cpp download for {resolved} does not match the recorded "
+                f"SHA-256: expected {pin.sha256}, computed {actual}. Nothing was "
+                "installed. This is what a substituted or corrupted build looks like; "
+                "report it rather than working around it."
+            )
+
+        if progress is not None:
+            progress(0.99, f"llama.cpp {pin.tag} verified, unpacking")
+
+        unpacked = Path(scratch) / "unpacked"
+        unpacked.mkdir()
+        try:
+            with zipfile.ZipFile(archive_path) as archive:
+                members = _safe_members(archive)
+                archive.extractall(unpacked, members=members)
+        except zipfile.BadZipFile as exc:
+            raise RuntimeUnavailable(
+                f"the llama.cpp download for {resolved} is not a readable archive: {exc}"
+            ) from exc
+
+        # The layout differs between releases, so the binaries are found rather
+        # than assumed, and copied flat into runtime/ where installed_server()
+        # and the existing _find_llama_server() both already look.
+        moved = 0
+        for source in sorted(unpacked.glob("**/*")):
+            if not source.is_file():
+                continue
+            destination = target / source.name
+            shutil.copy2(source, destination)
+            if not sys.platform.startswith("win"):
+                destination.chmod(destination.stat().st_mode | stat.S_IXUSR)
+            moved += 1
+
+    found = installed_server(root)
+    if not found:
+        raise RuntimeUnavailable(
+            f"the llama.cpp archive for {resolved} unpacked {moved} file(s) but none of "
+            "them was llama-server. The recorded asset is probably the wrong one; "
+            "report it rather than working around it."
+        )
+    if progress is not None:
+        progress(1.0, f"llama.cpp {pin.tag} installed in {target}")
+    return found
+
+
+def describe_availability(key: str = "", pins_path: Optional[Path] = None) -> str:
+    """One line about what this machine can install, for the start-up report."""
+
+    resolved = key or platform_key()
+    pin = pin_for(resolved, pins_path)
+    if pin is None:
+        return f"llama.cpp: no build recorded for {resolved}; supply --llama-server"
+    return f"llama.cpp: {pin.tag} recorded for {resolved}, verified on install"

distinct_agent/transport.py

@@ -42,6 +42,8 @@ from distinct_protocol.netpolicy import validate_server_url as policy_validate_s
 from .queue import OfferDecision
 
 PAIR_API = "/agent_pair"
+REGISTER_API = "/agent_register"
+CLAIM_STATE_API = "/agent_claim_state"
 SYNC_API = "/agent_sync"
 ACCEPT_API = "/agent_accept"
 COMPLETE_API = "/agent_complete"
@@ -299,6 +301,93 @@ class GradioAgentTransport:
         self._last_snapshot: AgentSnapshot | None = None
         self._last_status: dict[str, JobStatus] = {}
 
+    @classmethod
+    def register(
+        cls,
+        server_url: str,
+        claim_code: str,
+        capabilities: AgentCapabilities,
+        *,
+        client_factory: Callable[[str], PredictClient] | None = None,
+        clock: Callable[[], float] = time.time,
+        nonce_factory: Callable[[], str] | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        max_attempts: int = 3,
+        retry_delay_seconds: float = 0.25,
+        allow_remote: bool | None = None,
+        allow_plaintext: bool | None = None,
+        verify_server: bool = True,
+        signing_public_key: bytes = b"",
+        access_code: str = "",
+    ) -> GradioAgentTransport:
+        """Register with a code this worker invented, to be claimed from the site.
+
+        The same handshake as :meth:`pair` with the code travelling the other
+        way. The transport that comes back is authenticated and usable, but the
+        server will offer it no work until somebody signed in claims it, so the
+        caller polls :meth:`claim_state` before settling into the work loop.
+
+        Attempted once, like pairing, and for a stronger reason: a retry that
+        succeeded after a lost response would leave two records waiting on one
+        code, and the server refuses the second rather than allowing the claim
+        to become ambiguous.
+        """
+
+        if not isinstance(capabilities, AgentCapabilities):
+            raise TypeError("capabilities must be AgentCapabilities")
+        server_url = validate_server_url(
+            server_url, allow_remote=allow_remote, allow_plaintext=allow_plaintext
+        )
+        factory = client_factory or _default_client_factory
+        client: PredictClient | None = None
+        try:
+            client = factory(server_url)
+            raw = client.predict(
+                claim_code,
+                canonical_body(capabilities.to_dict()),
+                bytes(signing_public_key).hex() if signing_public_key else "",
+                access_code or "",
+                api_name=REGISTER_API,
+            )
+            response = _decode_response(raw, rejection_type=AgentPairingRejected)
+            credential = _credential_from_response(response)
+        except AgentTransportError:
+            _close_quietly(client)
+            raise
+        except Exception as exc:
+            _close_quietly(client)
+            raise AgentTransportUnavailable(
+                f"register request failed: {type(exc).__name__}"
+            ) from exc
+        return cls(
+            client=client,
+            credential=credential,
+            clock=clock,
+            nonce_factory=nonce_factory,
+            sleep=sleep,
+            max_attempts=max_attempts,
+            retry_delay_seconds=retry_delay_seconds,
+            server_auth=(
+                ServerAuthenticator(decode_agent_secret(credential.secret))
+                if verify_server
+                else None
+            ),
+        )
+
+    def claim_state(self) -> str:
+        """``"waiting"``, ``"claimed"`` or ``"gone"``, for this worker's own record."""
+
+        try:
+            raw = self.client.predict(self.agent_id, api_name=CLAIM_STATE_API)
+            response = _decode_response(raw)
+        except AgentTransportError:
+            raise
+        except Exception as exc:
+            raise AgentTransportUnavailable(
+                f"claim state request failed: {type(exc).__name__}"
+            ) from exc
+        return str(response.get("claim_state", "waiting"))
+
     @classmethod
     def pair(
         cls,

distinct_server/api.py

@@ -159,6 +159,74 @@ class AgentApi:
         except (ControlPlaneError, TypeError, ValueError) as exc:
             return _response({"ok": False, "error": str(exc)})
 
+    def register(
+        self,
+        claim_code: str,
+        capabilities_json: str,
+        signing_public_key_hex: str = "",
+        access_code: str = "",
+    ) -> str:
+        """Register a worker that will be claimed from the website afterwards.
+
+        The mirror image of :meth:`pair`. There, the code came from the server
+        and the volunteer carried it to the terminal; here the worker invents
+        one and the volunteer carries it to the browser. Nothing is copied out
+        of the page, which is what makes the failure this replaced -- somebody
+        inventing a value where the pairing code went -- impossible rather than
+        merely better explained.
+
+        This is the only entry point on the server that needs no account. What
+        it creates is inert: see ``ControlPlane.register_unclaimed``.
+        """
+
+        try:
+            capabilities = AgentCapabilities.from_dict(
+                _json_object(capabilities_json, maximum=65_536)
+            )
+            public_key = b""
+            if signing_public_key_hex:
+                if not isinstance(signing_public_key_hex, str):
+                    raise ValueError("signing public key must be hexadecimal text")
+                try:
+                    public_key = bytes.fromhex(signing_public_key_hex)
+                except ValueError as exc:
+                    raise ValueError("signing public key is not valid hexadecimal") from exc
+            credential = self.control_plane.register_unclaimed(
+                capabilities,
+                claim_code,
+                signing_public_key=public_key,
+                access_code=access_code or "",
+            )
+            return _response(
+                {
+                    "ok": True,
+                    "agent_id": credential.agent_id,
+                    "secret": credential.secret,
+                    "issued_at": credential.issued_at,
+                    "claim_state": "waiting",
+                    "claim_ttl_s": self.control_plane.limits.claim_ttl_seconds,
+                    "poll_interval_s": self.control_plane.limits.poll_interval_seconds,
+                    "heartbeat_interval_s": self.control_plane.limits.poll_interval_seconds,
+                    "offline_after_s": self.control_plane.limits.offline_after_seconds,
+                }
+            )
+        except (ControlPlaneError, TypeError, ValueError) as exc:
+            return _response({"ok": False, "error": str(exc)})
+
+    def claim_state(self, agent_id: str) -> str:
+        """Whether this worker has been claimed yet.
+
+        Says nothing a caller could not already know: a worker asks about the
+        record it created, and the answer is one of three words.
+        """
+
+        try:
+            return _response(
+                {"ok": True, "claim_state": self.control_plane.claim_state(str(agent_id or ""))}
+            )
+        except (ControlPlaneError, TypeError, ValueError) as exc:
+            return _response({"ok": False, "error": str(exc)})
+
     def sync(
         self,
         agent_id: str,

distinct_server/control_plane.py

@@ -324,6 +324,167 @@ class ControlPlane:
             del self._pairing_codes[digest]
             return AgentCredential(agent_id, encode_secret(secret), current)
 
+    def register_unclaimed(
+        self,
+        capabilities: AgentCapabilities,
+        claim_code: str,
+        *,
+        signing_public_key: bytes = b"",
+        access_code: str = "",
+        private: bool = False,
+        now: Optional[float] = None,
+    ) -> AgentCredential:
+        """Register a worker that has not been claimed by anybody yet.
+
+        PAIRING RUNS THE OTHER WAY ROUND NOW, AND THIS IS WHY.
+
+        The old flow asked a volunteer to sign in, find a pairing code on the
+        page, and paste it into a terminal. The reliable failure was somebody
+        typing a value of their own where the code went and being told, one
+        program later, that their code was invalid -- which reads as the server
+        rejecting *them* rather than as a copy that never happened.
+
+        So the code travels the other way. The worker invents one, prints it,
+        and registers here with nothing but its digest. It is issued a
+        credential immediately, because it needs one to ask whether it has been
+        claimed yet, but the record it gets is inert: ``owner_id`` is empty and
+        ``claim_digest`` is set, which ``_visible_locked`` treats as "this
+        worker does not exist". Nothing can list it, select it or send it work.
+
+        That inertness is what makes an unauthenticated registration safe. What
+        remains is resource use, which is bounded two ways: a hard ceiling on
+        how many unclaimed records may exist at once, and a short expiry after
+        which they are swept.
+        """
+
+        if not isinstance(capabilities, AgentCapabilities):
+            raise ValidationError("capabilities must be AgentCapabilities")
+        with self._lock:
+            current = self._now(now)
+            self._cleanup_unclaimed_locked(current)
+            try:
+                digest = pairing_code_digest(claim_code, self._pairing_pepper)
+            except ValueError as exc:
+                raise ValidationError("claim code is not a usable code") from exc
+
+            unclaimed = sum(1 for record in self._agents.values() if record.claim_digest)
+            if unclaimed >= self.limits.max_unclaimed_agents:
+                raise CapacityError(
+                    "too many workers are waiting to be claimed; try again shortly"
+                )
+            if len(self._agents) >= self.limits.max_agents:
+                raise CapacityError("agent registry is full")
+            if any(
+                hmac.compare_digest(record.claim_digest, digest)
+                for record in self._agents.values()
+                if record.claim_digest
+            ):
+                # Two workers offering one code would make the claim ambiguous,
+                # and the second one to arrive is the one that must lose.
+                raise ConflictError("that claim code is already waiting")
+
+            agent_id = capabilities.agent_id or _new_id("agent")
+            if agent_id in self._agents:
+                raise ConflictError("agent id is already registered")
+            if not capabilities.models:
+                raise ValidationError("agent must advertise at least one model")
+            if len(capabilities.models) > self.limits.max_models_per_agent:
+                raise CapacityError("agent advertises too many models")
+            if len(capabilities.tools) > self.limits.max_tools_per_agent:
+                raise CapacityError("agent advertises too many tools")
+            if not capabilities.energy_provider.strip():
+                raise ValidationError("agent must describe its energy provider")
+            if len(capabilities.energy_provider) > 256:
+                raise ValidationError("energy provider description is too long")
+            if not capabilities.agent_id:
+                capabilities = replace(capabilities, agent_id=agent_id)
+            if signing_public_key and (
+                not isinstance(signing_public_key, (bytes, bytearray))
+                or len(signing_public_key) != 32
+            ):
+                raise ValidationError("an Ed25519 public key is exactly 32 bytes")
+
+            secret = generate_secret()
+            self._agents[agent_id] = AgentRecord(
+                signing_public_key=bytes(signing_public_key),
+                owner_id="",
+                access_digest=(
+                    access_code_digest(access_code, self._pairing_pepper)
+                    if access_code
+                    else ""
+                ),
+                capabilities=copy.deepcopy(capabilities),
+                secret=secret,
+                issued_at=current,
+                last_snapshot_at=current,
+                private=bool(private),
+                registered_capabilities=copy.deepcopy(capabilities),
+                claim_digest=digest,
+                claim_expires_at=current + self.limits.claim_ttl_seconds,
+            )
+            return AgentCredential(agent_id, encode_secret(secret), current)
+
+    def claim_agent(
+        self,
+        claim_code: str,
+        owner_id: str,
+        *,
+        now: Optional[float] = None,
+    ) -> str:
+        """Bind a waiting worker to the signed-in person who typed its code.
+
+        Returns the agent id. The failure message says nothing about why, for
+        the same reason ``redeem_access_code`` says nothing: an error that told
+        a caller apart "no such code" from "expired" from "already claimed"
+        would be an oracle, and this one can be asked without an account on the
+        machine that printed the code.
+
+        Signing in is the whole check. Ownership is what a claim confers -- the
+        right to be sent other people's prompts is downstream of it -- so it
+        cannot be granted to an identity the server has not authenticated.
+        """
+
+        if not isinstance(owner_id, str) or not owner_id.strip():
+            raise AuthenticationError("that code is not valid")
+        owner_id = _single_line_identifier(owner_id, "owner_id")
+        with self._lock:
+            current = self._now(now)
+            self._cleanup_unclaimed_locked(current)
+            try:
+                digest = pairing_code_digest(claim_code, self._pairing_pepper)
+            except ValueError as exc:
+                raise AuthenticationError("that code is not valid") from exc
+            for agent_id, record in self._agents.items():
+                if not record.claim_digest:
+                    continue
+                if not hmac.compare_digest(record.claim_digest, digest):
+                    continue
+                if record.revoked or record.claim_expires_at <= current:
+                    raise AuthenticationError("that code is not valid")
+                record.owner_id = owner_id
+                # One use. Clearing the digest is also what makes the record
+                # visible, so the two can never disagree.
+                record.claim_digest = ""
+                record.claim_expires_at = 0.0
+                return agent_id
+            raise AuthenticationError("that code is not valid")
+
+    def claim_state(self, agent_id: str, *, now: Optional[float] = None) -> str:
+        """``"waiting"``, ``"claimed"``, or ``"gone"`` for a worker's own poll.
+
+        The worker asks about itself, having authenticated as itself, so this
+        tells it only what it already put there. It exists so a worker can stop
+        printing "waiting to be claimed" at the moment somebody claims it.
+        """
+
+        with self._lock:
+            current = self._now(now)
+            self._cleanup_unclaimed_locked(current)
+            record = self._agents.get(agent_id)
+            if record is None or record.revoked:
+                return "gone"
+            return "waiting" if record.claim_digest else "claimed"
+
     def _phantom_record(self) -> AgentRecord:
         """A record for an agent that does not exist, so the checks can run.
 
@@ -833,6 +994,22 @@ class ControlPlane:
             # and its grantees, which is a worker that cannot be used sitting
             # in somebody's list looking like one that can.
             return False
+        if record.claim_digest:
+            # AN UNCLAIMED WORKER DOES NOT EXIST YET.
+            #
+            # Registering without a pairing code is the one operation on this
+            # server that needs no account, which is what lets a volunteer
+            # start a worker and claim it afterwards. The price is that anybody
+            # can create one of these records, so until a signed-in person
+            # enters its claim code it must be visible to nobody and reachable
+            # by nothing.
+            #
+            # This is the single place that has to be right. Every listing,
+            # every selection, both dispatch paths and the per-agent view all
+            # ask this function first, so one `False` here keeps an unclaimed
+            # worker out of all of them at once rather than relying on six
+            # call sites to remember.
+            return False
         if not record.private:
             return True
         if not viewer_id:
@@ -875,7 +1052,12 @@ class ControlPlane:
                 if not record.access_digest:
                     continue
                 if hmac.compare_digest(record.access_digest, digest):
-                    if record.revoked:
+                    if record.revoked or record.claim_digest:
+                        # An unclaimed worker prints its access code before
+                        # anybody owns it. Honouring that code here would let a
+                        # stranger take a share of a machine whose operator has
+                        # not finished setting it up, so it grants nothing
+                        # until the worker is claimed.
                         raise AuthenticationError("that code is not valid")
                     record.granted.add(viewer_id)
                     return agent_id
@@ -890,7 +1072,7 @@ class ControlPlane:
             return tuple(
                 agent_id
                 for agent_id, record in self._agents.items()
-                if viewer_id in record.granted
+                if viewer_id in record.granted and not record.claim_digest
             )
 
     def list_agents(
@@ -1496,6 +1678,25 @@ class ControlPlane:
             del self._pairing_codes[digest]
         return len(expired)
 
+    def _cleanup_unclaimed_locked(self, now: float) -> int:
+        """Forget workers nobody claimed in time.
+
+        An unclaimed record is the only thing on this server an unauthenticated
+        caller can create, so it must not be something an unauthenticated caller
+        can accumulate. It costs a slot for at most ``claim_ttl_seconds`` and is
+        then gone; the worker holding it discovers this on its next poll and
+        says so rather than waiting for ever.
+        """
+
+        expired = [
+            agent_id
+            for agent_id, record in self._agents.items()
+            if record.claim_digest and record.claim_expires_at <= now
+        ]
+        for agent_id in expired:
+            del self._agents[agent_id]
+        return len(expired)
+
     @staticmethod
     def _cleanup_agent_nonces_locked(record: AgentRecord, now: float) -> int:
         expired = [nonce for nonce, expires_at in record.nonces.items() if expires_at <= now]

distinct_server/models.py

@@ -67,11 +67,21 @@ class ControlPlaneLimits:
     #: nobody else on the server can pair a worker. A per-owner share turns
     #: that from an outage into one account wasting its own allowance.
     max_pairing_codes_per_owner: int = 8
+    #: How many workers may sit registered-but-unclaimed at once. An unclaimed
+    #: worker is the one thing here that anybody can create without signing in,
+    #: so it is the one thing that needs a ceiling and a short life. Both are
+    #: deliberately small: a claim is something a person does within a minute
+    #: of starting a worker, not something left pending.
+    max_unclaimed_agents: int = 64
     max_nonces_per_agent: int = 2_048
     max_models_per_agent: int = 64
     max_tools_per_agent: int = 64
     max_result_characters: int = 1_000_000
     pairing_ttl_seconds: float = 600.0
+    #: How long an unclaimed worker waits to be claimed before the server
+    #: forgets it. Long enough to walk to the browser, short enough that an
+    #: abandoned worker does not hold a slot.
+    claim_ttl_seconds: float = 900.0
     poll_interval_seconds: float = 5.0
     missed_polls_before_offline: int = 3
     # A floor on the offline threshold so that lowering the poll interval
@@ -90,6 +100,7 @@ class ControlPlaneLimits:
             "max_jobs_per_conversation",
             "max_pairing_codes",
             "max_pairing_codes_per_owner",
+            "max_unclaimed_agents",
             "max_nonces_per_agent",
             "max_models_per_agent",
             "max_tools_per_agent",
@@ -98,6 +109,7 @@ class ControlPlaneLimits:
         )
         duration_fields = (
             "pairing_ttl_seconds",
+            "claim_ttl_seconds",
             "poll_interval_seconds",
             "min_offline_seconds",
             "request_clock_skew_seconds",
@@ -259,6 +271,18 @@ class AgentRecord:
     #: one; that is an ordering question rather than a freshness question, and a
     #: counter answers it without the two sides agreeing a clock.
     snapshot_counter: int = 0
+    #: Set while this worker is registered but not yet claimed by anybody.
+    #:
+    #: A worker started without a pairing code generates its own claim code,
+    #: prints it, and registers here holding only the digest. Until somebody
+    #: signed in enters that code, ``owner_id`` is empty and the record is
+    #: invisible to every viewer and every dispatch path -- see
+    #: ``ControlPlane._visible_locked``, which treats a non-empty claim digest
+    #: as "this worker does not exist yet". Claiming clears it.
+    claim_digest: str = ""
+    #: When an unclaimed record stops being claimable and is swept.
+    claim_expires_at: float = 0.0
+
     #: The capability set registered at pairing, frozen. This is the ceiling an
     #: advertisement is intersected with. It must be the *pairing* set rather
     #: than the current one: an agent that advertises nothing while its

distinct_server/render.py

@@ -366,13 +366,23 @@ def join_this_server(
 
     # STEP FOUR: the run, with this server's address and this browser's own
     # library defaults already in it.
+    # NOTHING IS COPIED OUT OF THIS PAGE ANY MORE.
+    #
+    # This used to show a server-minted pairing code and a command with a
+    # `--pair YOUR-CODE` placeholder in it, and ask the volunteer to carry the
+    # one into the other. What people did instead -- reasonably, reading a
+    # placeholder as a thing to fill in however they liked -- was invent a
+    # value, and find out one program later that "your code wasn't valid",
+    # which reads as the server rejecting them rather than as a copy that never
+    # happened. Signed out, there was not even a code on the page to copy.
+    #
+    # The code now travels the other way: the worker invents one, prints it,
+    # and waits, and it is typed into the box on this page. There is nothing
+    # here to transcribe, so there is nothing to transcribe wrongly, and the
+    # command is complete for everybody whether they are signed in or not.
     code_note = (
-        f'<p class="c-join__note">Pairing code, one use and ten minutes: '
-        f'<code class="c-join__code">{esc(code)}</code></p>'
-        if code
-        else '<p class="c-join__note">Sign in at the top of this page and a pairing '
-        "code appears here. Until then the command below is complete apart from "
-        "that one value.</p>"
+        '<p class="c-join__note">The command below is complete as it stands. '
+        "When you run it, the worker prints a code and waits.</p>"
     )
     # One line on purpose. The previous form used backslash continuations,
     # which are bash syntax: pasted into PowerShell they became stray
@@ -380,7 +390,7 @@ def join_this_server(
     # into every shell anybody actually uses.
     arguments = (
         f"-m distinct_agent --server {first} "
-        f"--pair {code or 'YOUR-CODE'} --models olmoe-1b-7b-0924-instruct --tools {tools or 'local'}"
+        f"--models olmoe-1b-7b-0924-instruct --tools {tools or 'local'}"
     )
     run_it = _command_block(f"py -3 {arguments}", platform="win") + _command_block(
         f"python3 {arguments}", platform="nix"
@@ -401,9 +411,13 @@ def join_this_server(
         '<p class="c-step-num__head">Get something to run the models with</p>'
         f"{runner}</div></li>"
         '<li class="c-step-num"><span class="c-step-num__n">4</span>'
-        '<div class="c-step-num__body"><p class="c-step-num__head">Point it at this server</p>'
+        '<div class="c-step-num__body"><p class="c-step-num__head">Run it, and claim it</p>'
         f'<code class="c-join__address">{esc(first)}</code>{alternates}{code_note}'
         f"{run_it}"
+        '<p class="c-join__note">The worker prints a code and waits. Put that code '
+        "into <em>Add a worker</em> on this page while signed in, and the machine "
+        "becomes yours. Until you do, nobody can see it and nothing can be sent "
+        "to it.</p>"
         f"{picture}</div></li>"
         # THE LAST STEP EXISTS BECAUSE PEOPLE ASK FOR IT AFTER READING THE ONE
         # BEFORE IT.

distinct_server/ui.py

@@ -2228,7 +2228,27 @@ class DistinctUI:
         profile: "gr.OAuthProfile | None",
         request: "gr.Request | None" = None,
     ) -> tuple:
-        """Give this signed-in person access to the worker that printed a code.
+        """Take a code and do whatever that code means.
+
+        ONE BOX, BECAUSE A PERSON HAS ONE CODE.
+
+        A worker prints two codes over its life: a **claim code** while it waits
+        to be adopted, and an **access code** afterwards for the people its
+        operator wants to share it with. Those are different things and they are
+        entered by different people, but nobody standing at this field knows or
+        cares which kind they are holding -- they were handed a code and told to
+        put it in. Two fields would make choosing wrongly possible, and choosing
+        wrongly would produce "that code is not valid" for a code that was
+        perfectly valid in the box next door. That is the exact shape of the
+        failure this whole change exists to remove.
+
+        So the claim is tried first and access second, and a code that is
+        neither is refused in the words both refusals already used. Both are
+        192-bit random strings drawn from the same alphabet, so in principle one
+        value could be both; at 2**-192 that is not a case worth designing
+        around, and the order makes it deterministic if it ever happened.
+        Holding a code is the authorisation in either reading, so trying both
+        grants nothing that trying one would not.
 
         Signing in is checked first and separately from the code, because they
         are two different refusals: one is "we do not know who you are" and the
@@ -2251,14 +2271,23 @@ class DistinctUI:
                 render.worker_cards(rows, narrowed_by=narrowed),
             )
 
+        typed = str(access_code or "")
         try:
-            self.control.redeem_access_code(str(access_code or ""), viewer_id)
+            self.control.claim_agent(typed, viewer_id)
             message = _status_html(
-                "That worker is now available to you. It appears below when it "
-                "is online and offers the model and mode you have chosen."
+                "That worker is yours. It is now running for you, and it appears "
+                "below when it is online and offers the model and mode you have "
+                "chosen. Share its access code with anyone else who should use it."
             )
         except (ControlPlaneError, ValueError):
-            message = _status_html("That code is not valid.")
+            try:
+                self.control.redeem_access_code(typed, viewer_id)
+                message = _status_html(
+                    "That worker is now available to you. It appears below when it "
+                    "is online and offers the model and mode you have chosen."
+                )
+            except (ControlPlaneError, ValueError):
+                message = _status_html("That code is not valid.")
 
         rows, choices, value, narrowed = self._agent_components(
             model_id, tool_values, selected_agent, mode, viewer_id=viewer_id
@@ -3282,83 +3311,48 @@ class DistinctUI:
         *,
         force: bool = False,
     ) -> tuple:
-        """The code for this browser: the one it already has, or a new one.
-
-        MINTING ON EVERY OPEN WAS BOTH A BUG AND AN OUTAGE.
-
-        The bug: a person opens the panel, copies the code, opens it again to
-        re-read the command, and is now looking at a different code from the
-        one in their clipboard.
-
-        The outage: opening a section is cheap and scriptable, the pool of
-        live codes is shared by everybody on this server, and they last ten
-        minutes — so a loop over this handler fills the pool and stops anyone
-        else pairing a worker. The control plane now caps codes per owner as
-        well, which contains the damage; not minting one that nobody asked
-        for is what stops it starting.
-
-        The plaintext lives in this browser's own state and nowhere else. The
-        server keeps only a digest, deliberately, so this is the sole copy —
-        which is exactly the right place for it, since this browser is the
-        only party entitled to read it.
-
-        OPENING A SECTION IS NAVIGATION, SO IT CANNOT FAIL.
-
-        This raised `gr.Error`, and the accordion that opens the panel is
-        wired straight to it, so a signed-out visitor who clicked "Run a
-        community agent" — the ordinary way to find out what running one
-        involves — got a red toast and a five hundred in the log for reading
-        a page. The other way in was the per-owner cap: eight live codes is
-        eight opens in a browser with no saved code, and the ninth open
-        refused with a toast rather than a sentence.
-
-        Nothing here is worth a toast. The panel already reads correctly with
-        no code in it — it is four steps, and the code belongs to one of them —
-        so the reason a code was not minted is written into the panel, where
-        the person is already looking, and the section opens either way.
+        """Render the setup panel. Nothing is minted, and nothing can fail.
+
+        THIS HANDLER USED TO ISSUE A CREDENTIAL, AND THAT WAS THE PROBLEM.
+
+        Opening a section is navigation. This one minted a server-side pairing
+        code every time it ran, which produced three separate faults:
+
+        * The code changed under people. Open the panel, copy the code, open it
+          again to re-read the command, and the clipboard no longer matched the
+          page.
+        * It was an outage waiting to happen. Opening a section is cheap and
+          scriptable, live codes came from one pool shared by everybody on this
+          server, and they lasted ten minutes -- so a loop here filled the pool
+          and stopped anyone else pairing a worker.
+        * It could refuse. Signed out it raised, so clicking "Run a community
+          agent" to find out what running one involves produced a red toast and
+          a 500 in the log for the crime of reading a page.
+
+        Each was patched in turn -- reuse the browser's live code, cap codes per
+        owner, catch the refusals -- and the patches were all correct and all
+        beside the point. The panel needed a code only because the flow made a
+        volunteer carry one from this page to their terminal, and that flow is
+        gone: the worker prints its own code and the person types it into the
+        box on this page instead.
+
+        So there is nothing to mint, nothing to run out of, nothing to expire
+        under anybody, and nothing that needs an account to read. The signature
+        keeps ``state`` and ``force`` because the accordion and the tests are
+        wired to them, and both are now ignored.
         """
 
         updated = dict(state) if isinstance(state, Mapping) else {}
-        try:
-            user_id = self._authorize(state, profile, request)
-        except LoginRequired:
-            return (
-                updated,
-                updated,
-                _status_html(
-                    "Sign in with Hugging Face to get a pairing code. The rest of "
-                    "the setup is the same either way, so it is all here to read "
-                    "first."
-                )
-                + self._join_panel("", updated),
-            )
-        existing = str(updated.get("pairing_code") or "")
-        expires = updated.get("pairing_expires")
-        alive = (
-            existing
-            and isinstance(expires, (int, float))
-            # A minute's margin: a code that expires while somebody is
-            # pasting it is worse than one re-minted slightly early.
-            and expires - 60 > time.time()
-        )
-        if alive and not force:
-            return updated, updated, self._join_panel(existing, updated)
-        try:
-            value = self.control.create_pairing_code(user_id)
-        except (ControlPlaneError, ValueError) as exc:
-            return (
-                updated,
-                updated,
-                _status_html(f"No new pairing code just now: {exc}")
-                + self._join_panel(existing, updated),
-            )
-        updated["pairing_code"] = value.code
-        updated["pairing_expires"] = value.expires_at
-        return updated, updated, self._join_panel(value.code, updated)
+        # Kept only so a browser that saved one before this change does not
+        # carry it around for ever.
+        updated.pop("pairing_code", None)
+        updated.pop("pairing_expires", None)
+        return updated, updated, self._join_panel("", updated)
 
-    # `new_pairing_code` lived here to serve a "New code" button that no
-    # longer exists. Opening the panel mints one when the held code has
-    # expired, which is the only moment a second one was ever wanted.
+    # `new_pairing_code` and the "New code" button are both gone, and so is the
+    # minting they existed to trigger. `ControlPlane.create_pairing_code` stays
+    # for `--pair`, which scripted setups still use: there a code is minted and
+    # consumed by the same program and nobody has to read anything.
 
     def build(self) -> gr.Blocks:
         # ``head`` belongs to launch() in Gradio 6, not to the constructor; the
@@ -3569,7 +3563,7 @@ class DistinctUI:
                         # and entering it here is that consent arriving.
                         with gr.Row():
                             access_code = gr.Textbox(
-                                label="Add a worker · paste an access code somebody shared with you",
+                                label="Add a worker · enter the code your worker printed, or one somebody shared with you",
                                 placeholder="XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX-XXXX",
                                 lines=1,
                                 container=True,
@@ -3577,10 +3571,11 @@ class DistinctUI:
                             access_add = gr.Button("Add worker", variant="secondary")
                         access_status = gr.HTML(
                             _status_html(
-                                "A worker prints its code when it starts, and whoever "
-                                "runs it decides who gets one. The same code can be "
-                                "given to any number of people; entering it here does "
-                                "not use it up."
+                                "A worker you started prints a code and waits here for "
+                                "you to enter it; that claims it, once. A worker somebody "
+                                "else runs prints a code they can give to any number of "
+                                "people, and entering that one does not use it up. Both "
+                                "go in this box."
                             )
                         )
                         # Boundary 1. Boundary 2 lives in its own panel far
@@ -4218,6 +4213,29 @@ class DistinctUI:
                 api_name="agent_pair",
                 queue=False,
             )
+            # THE OTHER DIRECTION. `agent_pair` takes a code the server minted;
+            # `agent_register` takes one the worker minted, and creates a record
+            # that is inert until somebody signed in claims it. Same inputs, so
+            # the same hidden controls carry both.
+            api_pair_button.click(
+                self.agent_api.register,
+                inputs=[
+                    api_pair_code,
+                    api_pair_capabilities,
+                    api_pair_pubkey,
+                    api_pair_access,
+                ],
+                outputs=api_pair_output,
+                api_name="agent_register",
+                queue=False,
+            )
+            api_pair_button.click(
+                self.agent_api.claim_state,
+                inputs=[api_pair_code],
+                outputs=api_pair_output,
+                api_name="agent_claim_state",
+                queue=False,
+            )
             signed_inputs = [api_agent_id, api_timestamp, api_nonce, api_payload, api_signature]
             api_catalogue_button.click(
                 self.agent_api.catalogue,

llama_runtime.json

@@ -0,0 +1,29 @@
+{
+  "_comment": [
+    "Pinned llama.cpp builds, one per platform, fetched and verified by",
+    "distinct_agent/runtime.py. A worker downloads the build recorded here and",
+    "refuses to install it unless the bytes hash to `sha256`.",
+    "",
+    "A platform with no entry gets no automatic download. That is deliberate:",
+    "this project already withholds a MODEL whose digest it cannot check, and",
+    "the program that executes those models is held to the same bar. Operators",
+    "on those platforms pass --llama-server, or run --demo-runner and offer the",
+    "library's tools and skills with no model at all.",
+    "",
+    "TO ADD OR MOVE A PIN: download the asset, hash it, and record the result",
+    "here. `scripts/record_llama_pin.py` does exactly that and prints the JSON.",
+    "Never copy a digest from a release page or an API response into this file:",
+    "a digest that arrived with the download proves only that the bytes were",
+    "not corrupted in transit, which TLS already said, and pinning it would",
+    "dress trust-on-first-use up as verification."
+  ],
+  "builds": {
+    "windows-x64": {
+      "tag": "b10742",
+      "asset": "llama-b10742-bin-win-cpu-x64.zip",
+      "url": "https://github.com/ggml-org/llama.cpp/releases/download/b10742/llama-b10742-bin-win-cpu-x64.zip",
+      "sha256": "a923d80953d618335ae0073233fdcfb93760dfde646e957786894259aba87d72",
+      "bytes": 18373032
+    }
+  }
+}

scripts/record_llama_pin.py

@@ -0,0 +1,92 @@
+"""Record a llama.cpp build for `llama_runtime.json`, by downloading and hashing it.
+
+The digest in that file has to be produced by someone who fetched the bytes and
+hashed them. Copying a hash out of a release page or an API response would pin
+the same origin that served the download, which proves nothing TLS had not
+already said -- and this project withholds a *model* on exactly that reasoning.
+
+Usage::
+
+    python scripts/record_llama_pin.py windows-x64          # newest build
+    python scripts/record_llama_pin.py linux-x64 --tag b10742
+
+Prints a JSON fragment to paste into `llama_runtime.json`, and exits non-zero if
+no matching asset was found. It never writes the file itself: adding a pin
+should be a diff somebody reads.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import urllib.request
+
+RELEASES = "https://api.github.com/repos/ggml-org/llama.cpp/releases?per_page=%d"
+
+#: What a platform's asset name looks like, and what must not be in it. The
+#: exclusions pick the build that runs anywhere over the one that runs fastest:
+#: an operator who wants CUDA or Metal passes --llama-server.
+PATTERNS = {
+    "windows-x64": (("win", "x64"), ("cuda", "hip", "sycl", "arm64", "vulkan")),
+    "windows-arm64": (("win", "arm64"), ("cuda", "hip", "sycl")),
+    "linux-x64": (("ubuntu", "x64"), ("cuda", "hip", "sycl", "arm64", "vulkan")),
+    "macos-arm64": (("macos", "arm64"), ()),
+    "macos-x64": (("macos", "x64"), ()),
+}
+
+
+def _get(url: str) -> bytes:
+    request = urllib.request.Request(url, headers={"User-Agent": "distinct-pin"})
+    with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310
+        return response.read()
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("platform", choices=sorted(PATTERNS))
+    parser.add_argument("--tag", default="", help="a specific build tag, e.g. b10742")
+    parser.add_argument("--scan", type=int, default=15, help="how many releases to look through")
+    args = parser.parse_args(argv)
+
+    wanted, refused = PATTERNS[args.platform]
+    releases = json.loads(_get(RELEASES % args.scan))
+    for release in releases:
+        if args.tag and release.get("tag_name") != args.tag:
+            continue
+        for asset in release.get("assets", []):
+            name = str(asset.get("name", "")).casefold()
+            if not name.endswith(".zip"):
+                continue
+            if not all(part in name for part in wanted):
+                continue
+            if any(part in name for part in refused):
+                continue
+            url = asset["browser_download_url"]
+            print(f"downloading {asset['name']} ({asset.get('size', 0)} bytes)", file=sys.stderr)
+            payload = _get(url)
+            print(
+                json.dumps(
+                    {
+                        args.platform: {
+                            "tag": release["tag_name"],
+                            "asset": asset["name"],
+                            "url": url,
+                            "sha256": hashlib.sha256(payload).hexdigest(),
+                            "bytes": len(payload),
+                        }
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+    print(
+        f"no asset matching {wanted} found in the last {args.scan} releases",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

tests/test_claim_flow.py

@@ -0,0 +1,148 @@
+"""Registering without an account must create something that can do nothing.
+
+Pairing runs the other way round now: a worker invents a code, prints it, and
+registers here, and somebody signed in enters that code to claim it. That makes
+``register_unclaimed`` the only entry point on this server that needs no
+account, so every test below is about the same question -- what can a caller do
+with a record nobody has claimed? The answer has to be "nothing".
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from distinct_server.control_plane import UNASSIGNED_AGENT, ControlPlane
+from distinct_server.models import (
+    AgentCapabilities,
+    AuthenticationError,
+    CapacityError,
+    ConflictError,
+)
+from distinct_server.security import new_access_code, new_pairing_code
+
+
+def _caps(name: str = "worker") -> AgentCapabilities:
+    return AgentCapabilities(
+        agent_id="",
+        name=name,
+        os="linux",
+        arch="x64",
+        cpu="test",
+        ram_gb=8.0,
+        models=("m1",),
+        tools=(),
+        energy_provider="test meter",
+    )
+
+
+@pytest.fixture()
+def plane() -> ControlPlane:
+    return ControlPlane()
+
+
+def test_an_unclaimed_worker_is_invisible_to_everyone(plane: ControlPlane) -> None:
+    plane.register_unclaimed(_caps(), new_pairing_code())
+    assert plane.list_agents() == ()
+    assert plane.list_agents(viewer_id="user:alice") == ()
+    assert plane.list_agents(viewer_id="user:mallory") == ()
+
+
+def test_an_unclaimed_workers_access_code_grants_nothing(plane: ControlPlane) -> None:
+    """Otherwise a stranger takes a share of a machine still being set up."""
+
+    access = new_access_code()
+    plane.register_unclaimed(_caps(), new_pairing_code(), access_code=access)
+    with pytest.raises(AuthenticationError):
+        plane.redeem_access_code(access, "user:mallory")
+
+
+def test_claiming_requires_an_account(plane: ControlPlane) -> None:
+    code = new_pairing_code()
+    plane.register_unclaimed(_caps(), code)
+    with pytest.raises(AuthenticationError):
+        plane.claim_agent(code, "")
+    with pytest.raises(AuthenticationError):
+        plane.claim_agent(code, "   ")
+
+
+def test_a_wrong_code_says_nothing_about_why(plane: ControlPlane) -> None:
+    plane.register_unclaimed(_caps(), new_pairing_code())
+    with pytest.raises(AuthenticationError) as caught:
+        plane.claim_agent(new_pairing_code(), "user:alice")
+    assert str(caught.value) == "that code is not valid"
+
+
+def test_claiming_makes_the_worker_real(plane: ControlPlane) -> None:
+    code = new_pairing_code()
+    access = new_access_code()
+    credential = plane.register_unclaimed(_caps(), code, access_code=access)
+    assert plane.claim_state(credential.agent_id) == "waiting"
+
+    assert plane.claim_agent(code, "user:alice") == credential.agent_id
+    assert plane.claim_state(credential.agent_id) == "claimed"
+    assert len(plane.list_agents()) == 1
+    # and only now does its access code mean anything
+    assert plane.redeem_access_code(access, "user:bob") == credential.agent_id
+
+
+def test_a_claim_code_is_used_once(plane: ControlPlane) -> None:
+    code = new_pairing_code()
+    plane.register_unclaimed(_caps(), code)
+    plane.claim_agent(code, "user:alice")
+    with pytest.raises(AuthenticationError):
+        plane.claim_agent(code, "user:bob")
+
+
+def test_two_workers_cannot_wait_on_one_code(plane: ControlPlane) -> None:
+    """An ambiguous claim is worse than a refused registration."""
+
+    code = new_pairing_code()
+    plane.register_unclaimed(_caps("first"), code)
+    with pytest.raises(ConflictError):
+        plane.register_unclaimed(_caps("second"), code)
+
+
+def test_an_unclaimed_worker_expires(plane: ControlPlane) -> None:
+    code = new_pairing_code()
+    credential = plane.register_unclaimed(_caps(), code, now=1000.0)
+    later = 1000.0 + plane.limits.claim_ttl_seconds + 1
+    assert plane.claim_state(credential.agent_id, now=later) == "gone"
+    with pytest.raises(AuthenticationError):
+        plane.claim_agent(code, "user:alice", now=later)
+
+
+def test_unclaimed_registrations_have_a_ceiling(plane: ControlPlane) -> None:
+    """The one unauthenticated write on this server cannot be accumulated."""
+
+    made = 0
+    with pytest.raises(CapacityError):
+        for _ in range(plane.limits.max_unclaimed_agents + 10):
+            plane.register_unclaimed(_caps(), new_pairing_code())
+            made += 1
+    assert made == plane.limits.max_unclaimed_agents
+
+
+def test_expiry_frees_the_ceiling(plane: ControlPlane) -> None:
+    for _ in range(plane.limits.max_unclaimed_agents):
+        plane.register_unclaimed(_caps(), new_pairing_code(), now=1000.0)
+    later = 1000.0 + plane.limits.claim_ttl_seconds + 1
+    plane.register_unclaimed(_caps(), new_pairing_code(), now=later)
+
+
+def test_no_job_can_be_sent_to_an_unclaimed_worker(plane: ControlPlane) -> None:
+    """The visibility gate is what dispatch consults, so this is the proof."""
+
+    credential = plane.register_unclaimed(_caps(), new_pairing_code())
+    session = plane.create_session()
+    conversation = plane.create_conversation(session.session_id)
+    job = plane.submit_job(
+        session.session_id,
+        conversation.conversation_id,
+        "hello",
+        "m1",
+        viewer_id="user:alice",
+    )
+    # Nothing to run it, so it is stranded rather than handed to the worker
+    # that is sitting right there unclaimed.
+    assert job.spec.target_agent_id != credential.agent_id
+    assert job.spec.target_agent_id == UNASSIGNED_AGENT

tests/test_llama_runtime.py

@@ -0,0 +1,188 @@
+"""The runtime fetcher must be as careful as the weights fetcher.
+
+It downloads an executable from another project and puts it on a volunteer's
+machine, so every one of these is a property somebody would be harmed by losing:
+the digest is checked before anything is installed, an archive cannot write
+outside the runtime directory, and an archive cannot fill the disk.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from distinct_agent import runtime
+
+
+def _archive(names=("llama-server.exe", "ggml.dll"), size=32, deflate=False) -> bytes:
+    buf = io.BytesIO()
+    mode = zipfile.ZIP_DEFLATED if deflate else zipfile.ZIP_STORED
+    with zipfile.ZipFile(buf, "w", mode) as handle:
+        for name in names:
+            handle.writestr(f"build/bin/{name}", b"x" * size)
+    return buf.getvalue()
+
+
+def _opener(payload: bytes):
+    class _Response:
+        headers = {"Content-Length": str(len(payload))}
+
+        def __init__(self) -> None:
+            self._buffer = io.BytesIO(payload)
+
+        def read(self, size=-1):
+            return self._buffer.read(size)
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+    return lambda request, timeout=None: _Response()
+
+
+def _pins(tmp_path: Path, sha: str, key: str = "test-x64") -> Path:
+    path = tmp_path / "pins.json"
+    path.write_text(
+        json.dumps(
+            {
+                "builds": {
+                    key: {
+                        "tag": "bTEST",
+                        "asset": "a.zip",
+                        "url": "https://github.com/ggml-org/llama.cpp/releases/download/bTEST/a.zip",
+                        "sha256": sha,
+                        "bytes": 1,
+                    }
+                }
+            }
+        )
+    )
+    return path
+
+
+def test_a_verified_archive_installs_and_is_not_fetched_twice(tmp_path: Path) -> None:
+    payload = _archive()
+    root = tmp_path / "proj"
+    root.mkdir()
+    pins = _pins(tmp_path, hashlib.sha256(payload).hexdigest())
+
+    installed = runtime.ensure(root=root, key="test-x64", opener=_opener(payload), pins_path=pins)
+    assert Path(installed).is_file()
+    assert Path(installed).name.startswith("llama-server")
+
+    def refuse(*args, **kwargs):
+        raise AssertionError("an installed runtime must not be downloaded again")
+
+    assert runtime.ensure(root=root, key="test-x64", opener=refuse, pins_path=pins) == installed
+
+
+def test_a_wrong_digest_installs_nothing(tmp_path: Path) -> None:
+    payload = _archive()
+    root = tmp_path / "proj"
+    root.mkdir()
+    with pytest.raises(runtime.RuntimeVerificationError):
+        runtime.ensure(
+            root=root, key="test-x64", opener=_opener(payload), pins_path=_pins(tmp_path, "0" * 64)
+        )
+    assert not list((root / "runtime").glob("*")) if (root / "runtime").exists() else True
+
+
+def test_an_unrecorded_platform_is_never_downloaded(tmp_path: Path) -> None:
+    """The bar the catalogue sets for a model applies to the thing that runs it."""
+
+    payload = _archive()
+    root = tmp_path / "proj"
+    root.mkdir()
+    with pytest.raises(runtime.RuntimeUnavailable) as caught:
+        runtime.ensure(
+            root=root,
+            key="mystery-arch",
+            opener=_opener(payload),
+            pins_path=_pins(tmp_path, hashlib.sha256(payload).hexdigest()),
+        )
+    assert "will not download one" in str(caught.value)
+
+
+def test_path_traversal_is_refused(tmp_path: Path) -> None:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as handle:
+        handle.writestr("../../escaped.txt", b"x")
+    payload = buf.getvalue()
+    root = tmp_path / "proj"
+    root.mkdir()
+    with pytest.raises(runtime.RuntimeUnavailable) as caught:
+        runtime.ensure(
+            root=root,
+            key="test-x64",
+            opener=_opener(payload),
+            pins_path=_pins(tmp_path, hashlib.sha256(payload).hexdigest()),
+        )
+    assert "unsafe path" in str(caught.value)
+    assert not (tmp_path / "escaped.txt").exists()
+
+
+def test_a_decompression_bomb_is_refused(tmp_path: Path) -> None:
+    """Small on the wire, enormous on disk. The digest would have matched."""
+
+    payload = _archive(names=("llama-server",), size=runtime.MAX_UNPACKED_BYTES + 1, deflate=True)
+    assert len(payload) < 5 * 1024 * 1024
+    root = tmp_path / "proj"
+    root.mkdir()
+    with pytest.raises(runtime.RuntimeUnavailable) as caught:
+        runtime.ensure(
+            root=root,
+            key="test-x64",
+            opener=_opener(payload),
+            pins_path=_pins(tmp_path, hashlib.sha256(payload).hexdigest()),
+        )
+    assert "unpacks to more than" in str(caught.value)
+
+
+def test_an_archive_without_a_server_is_refused(tmp_path: Path) -> None:
+    payload = _archive(names=("readme.txt",))
+    root = tmp_path / "proj"
+    root.mkdir()
+    with pytest.raises(runtime.RuntimeUnavailable):
+        runtime.ensure(
+            root=root,
+            key="test-x64",
+            opener=_opener(payload),
+            pins_path=_pins(tmp_path, hashlib.sha256(payload).hexdigest()),
+        )
+
+
+@pytest.mark.parametrize(
+    "url,allowed",
+    [
+        ("https://github.com/ggml-org/llama.cpp/releases/download/b1/a.zip", True),
+        ("https://objects.githubusercontent.com/whatever", True),
+        ("http://github.com/ggml-org/llama.cpp/a.zip", False),
+        ("https://github.com.evil.example/a.zip", False),
+        ("https://example.com/a.zip", False),
+    ],
+)
+def test_redirects_leave_github_nowhere(url: str, allowed: bool) -> None:
+    assert runtime._RuntimeRedirects._permitted(url) is allowed
+
+
+def test_the_shipped_pin_file_is_readable_and_pinned() -> None:
+    """Whatever is recorded must be a real 64-character digest over https."""
+
+    for key, pin in runtime.load_pins().items():
+        assert len(pin.sha256) == 64, key
+        assert int(pin.sha256, 16) >= 0, key
+        assert pin.url.startswith("https://"), key
+        assert pin.tag and pin.asset, key
+
+
+def test_platform_key_is_stable() -> None:
+    assert runtime.platform_key("Windows", "AMD64") == "windows-x64"
+    assert runtime.platform_key("Linux", "x86_64") == "linux-x64"
+    assert runtime.platform_key("Darwin", "arm64") == "macos-arm64"