graphban-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{graphban_cli-0.2.0 → graphban_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: gban — a Graphban client for the human at a terminal
 Project-URL: Homepage, https://github.com/asc-me/graphban
 Project-URL: Repository, https://github.com/asc-me/graphban
@@ -150,6 +150,22 @@ Three properties worth knowing, each of which is a bug this command exists to no
   `.mcp.json` is refused rather than warned about, because a warning attached to committing a
   credential still commits it.
 
+## Wiring a checkout to Swamp
+
+```bash
+gban swamp setup
+```
+
+Steps 3 and 5 of [the Swamp runbook](https://github.com/asc-me/graphban/blob/main/docs/swamp.md):
+`repo init`, `extension source add`, `vault create`, and the **gate** credential — minted,
+piped to `swamp vault put` on stdin, then checked for the scopes it actually came back with.
+Every step is skipped when already done.
+
+Two things it will not do. It does not install Swamp, because that install pipes a remote
+script into a shell. And it never writes the gate key into an MCP config: `gban setup`'s agent
+key must not carry `gate`, or the agent doing the work attests its own completion — which
+fails silently, since a gate that always says yes looks exactly like a gate that held.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

{graphban_cli-0.2.0 → graphban_cli-0.3.0}/README.md

@@ -135,6 +135,22 @@ Three properties worth knowing, each of which is a bug this command exists to no
   `.mcp.json` is refused rather than warned about, because a warning attached to committing a
   credential still commits it.
 
+## Wiring a checkout to Swamp
+
+```bash
+gban swamp setup
+```
+
+Steps 3 and 5 of [the Swamp runbook](https://github.com/asc-me/graphban/blob/main/docs/swamp.md):
+`repo init`, `extension source add`, `vault create`, and the **gate** credential — minted,
+piped to `swamp vault put` on stdin, then checked for the scopes it actually came back with.
+Every step is skipped when already done.
+
+Two things it will not do. It does not install Swamp, because that install pipes a remote
+script into a shell. And it never writes the gate key into an MCP config: `gban setup`'s agent
+key must not carry `gate`, or the agent doing the work attests its own completion — which
+fails silently, since a gate that always says yes looks exactly like a gate that held.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

{graphban_cli-0.2.0 → graphban_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"

{graphban_cli-0.2.0 → graphban_cli-0.3.0}/src/gban/cli.py

@@ -15,7 +15,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from gban import config, doctor as doctor_mod, setup as setup_mod
+from gban import config, doctor as doctor_mod, setup as setup_mod, swamp as swamp_mod
 from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
                        Client, NoSession,
                        Refused, Unreachable, authenticated, login)
@@ -73,6 +73,21 @@ def _parser() -> argparse.ArgumentParser:
     setup_cmd.add_argument("--no-install", action="store_true",
                            help="do not install the supervisor")
 
+    swamp_cmd = sub.add_parser(
+        "swamp", help="wire this checkout to Swamp's Graphban adapter",
+        description=("Mints the GATE credential — the one that attests completion — and puts "
+                     "it in the Swamp vault and nowhere else. It is deliberately not the "
+                     "agent key `gban setup` writes into your MCP config: an agent that can "
+                     "attest its own work turns the completion gate into theatre, and nothing "
+                     "errors when it does. Does not install Swamp; a remote install script is "
+                     "for a person to read and run."))
+    swamp_do = swamp_cmd.add_subparsers(dest="act")
+    swamp_setup = swamp_do.add_parser("setup", help="init, source, vault, and the gate key")
+    swamp_setup.add_argument("--adapter", default=swamp_mod.DEFAULT_ADAPTER,
+                             help=f"the graphban-swamp checkout (default: {swamp_mod.DEFAULT_ADAPTER})")
+    swamp_setup.add_argument("--no-init", action="store_true",
+                             help="refuse rather than run `swamp repo init` here")
+
     fleet = sub.add_parser(
         "fleet", help="hand off to gbfleet (the supervisor)",
         description=("Passes everything through to `gbfleet` and returns its exit code "
@@ -330,6 +345,37 @@ def _setup_auto(args, url: str, client) -> int:
     return worst
 
 
+def cmd_swamp(args) -> int:
+    """Wire this checkout to Swamp's Graphban adapter (GRPH-796).
+
+    Mints a SECOND credential — the gate key — and puts it in the vault and nowhere else. The
+    agent key `gban setup` writes into the MCP config must never carry `gate`: an agent that
+    can attest its own completion turns the gate into theatre, and nothing errors when it does.
+    """
+    if args.act != "setup":
+        print(f"{PROG}: usage: {PROG} swamp setup", file=sys.stderr)
+        return EXIT_REFUSED
+    url = _server(args)
+    client = authenticated(url, act="swamp setup")
+    repo = Path.cwd()
+    asked = (args.project or os.environ.get(config.PROJECT_ENV) or "").strip()
+    try:
+        project, how = setup_mod.resolve_project(
+            client, repo, asked, config.settings().get("project", ""))
+    except setup_mod.Unresolved as exc:
+        print(f"{PROG}: {exc}", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, code = swamp_mod.setup(client, url, project, repo,
+                                  Path(args.adapter).expanduser(), init=not args.no_init)
+    human = [f"{PROG}: {project} — {how}" if how != "named" else f"{PROG}: {project}",
+             doctor_mod.render(lines)]
+    if code == 0:
+        human.append(f"\n     The gate key is in the vault and in no MCP config. Keep it that "
+                     f"way: an agent that can attest its own work is not gated.")
+    _out({"lines": lines, "ok": code == 0, "project": project}, "\n".join(human), args.as_json)
+    return code
+
+
 def cmd_fleet(args) -> int:
     """A subprocess, never an import (D5).
 
@@ -481,7 +527,7 @@ def cmd_keys(args) -> int:
 
 COMMANDS = {"login": cmd_login, "logout": cmd_logout, "whoami": cmd_whoami,
             "doctor": cmd_doctor, "setup": cmd_setup, "fleet": cmd_fleet, "seats": cmd_seats,
-            "agents": cmd_agents, "keys": cmd_keys}
+            "agents": cmd_agents, "keys": cmd_keys, "swamp": cmd_swamp}
 
 
 def main(argv: list[str] | None = None) -> int:

graphban_cli-0.3.0/src/gban/swamp.py

@@ -0,0 +1,278 @@
+"""Wire a checkout to Swamp's Graphban adapter (GRPH-796).
+
+`docs/swamp.md` §3 and §5 are five commands and one credential, and the credential is the
+part worth automating carefully rather than the commands.
+
+**The gate key is not the agent key, and this is the whole reason to be careful.** `gban
+setup` mints an agent credential and writes it into the harness MCP config, where the agent
+doing the work reads it. A gate key attests completion: `update_item(status="done")` refuses
+without one. Put a gate key where the building agent can read it and the completion gate stops
+being a gate — an agent would attest its own work, and nothing would error. So this mints a
+SECOND, separate credential and puts it in exactly one place: the Swamp vault. It never writes
+to an MCP config, and `test_swamp.py` asserts that rather than trusting the code to stay that
+way.
+
+**It does not install Swamp.** The documented install is `curl -fsSL … | sh`, and running a
+remote script is categorically different from `uv tool install graphban-fleet`, which names a
+package in a package manager. A missing `swamp` is reported with the command to run, for a
+person to run.
+
+**It shells out; it does not wrap.** Same shape as `gban fleet` → `gbfleet`, and here it is
+also a licensing boundary: Swamp is AGPL-3.0 with an extension exception that forbids copies
+of its source. Calling a binary is not copying one.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from gban.client import Client, Refused, Unreachable
+from gban.doctor import FAIL, PASS, UNKNOWN, _line
+
+#: What `docs/swamp.md` §5 names. Changing either renames somebody's existing wiring, so they
+#: are constants rather than options.
+VAULT = "secrets"
+SECRET_KEY = "graphban-api-key"
+VAULT_TYPE = "local_encryption"
+
+#: The adapter repository, a SIBLING of the checkout — `docs/swamp.md` says "sibling, not this
+#: tree", because a nested copy is one `git add` from being committed into a repository whose
+#: licence forbids carrying it.
+DEFAULT_ADAPTER = "../graphban-swamp"
+
+#: Reported, never run. See the module docstring.
+INSTALL = "curl -fsSL https://swamp-club.com/install.sh | sh    # review it first"
+
+#: `read` and `write` ride along with `gate` deliberately: `attest_ci.py` attests through
+#: `update_item`, which `mcp_server` refuses without `write`, so a `gate`-only key mints
+#: successfully and 403s on the first real attestation. `fleet.mint` carries all three for the
+#: same reason.
+GATE_SCOPES = ["read", "write", "gate"]
+
+
+def find() -> str:
+    return shutil.which("swamp") or ""
+
+
+def run(repo: Path, *args: str, stdin: str | None = None,
+        timeout: float = 120.0) -> subprocess.CompletedProcess:
+    """One swamp invocation, always `--json`, always scoped to `repo` by WORKING DIRECTORY.
+
+    Not `--repo-dir`. Swamp's own "Not a swamp repository" error recommends that flag —
+    "specify an existing repository with `swamp <command> --repo-dir /path/to/repo`" — and
+    `swamp 20260830` rejects it on every verb tried, `repo init`, `vault list` and
+    `extension source list` alike: *Unknown option "--repo-dir"*. Taking a tool's advice about
+    its own flags is exactly the kind of assumption that survives a test suite and dies on
+    contact, which is what happened here.
+
+    `cwd` is what swamp actually uses to find a repository, so it is what scopes this. The
+    caller's own directory is never relied on.
+    """
+    return subprocess.run(["swamp", *args, "--json"], input=stdin, cwd=str(repo),
+                          capture_output=True, text=True, timeout=timeout)
+
+
+def spoke(done: subprocess.CompletedProcess) -> dict:
+    """Swamp answers in JSON on both paths, including its errors — PRETTY-PRINTED across
+    several lines, which is why this parses whole streams rather than lines.
+
+    Reading line by line found nothing and left the caller falling back to "the last line of
+    stderr", which for a formatted object is `}`. An error report of `}` is worse than none:
+    it looks like a real message.
+    """
+    for stream in (done.stdout, done.stderr):
+        text = (stream or "").strip()
+        if not text:
+            continue
+        try:
+            got = json.loads(text)
+        except ValueError:
+            start = text.find("{")
+            try:
+                got = json.loads(text[start:]) if start >= 0 else None
+            except ValueError:
+                got = None
+        if isinstance(got, dict):
+            return got
+    return {}
+
+
+def initialised(repo: Path) -> bool:
+    """A `.swamp.yaml` is the repository. Asked of the FILE rather than by running a command,
+    so a swamp that is missing or broken does not read as an uninitialised checkout."""
+    return (repo / ".swamp.yaml").exists()
+
+
+# The response keys below are what `swamp 20260830` ACTUALLY returns, captured by running it.
+# The first draft guessed `vaults` and `keys`; the real names are `results` and `secretKeys`,
+# and the guesses failed silently in the worst direction — `secret_present` would have returned
+# False forever, so every run would mint another live gate credential and overwrite the vault
+# entry. The test double agreed, because it was built from the same guess.
+
+def vaults(repo: Path) -> list[str]:
+    got = spoke(run(repo, "vault", "list"))
+    rows = got.get("results") if isinstance(got, dict) else None
+    if not isinstance(rows, list):
+        return []
+    return [str(r.get("name") or "") for r in rows if isinstance(r, dict)]
+
+
+def secret_present(repo: Path) -> bool:
+    """`list-keys` names the keys and NOT their values, which is why idempotence can be
+    decided without reading a credential into this process at all."""
+    got = spoke(run(repo, "vault", "list-keys", VAULT))
+    keys = got.get("secretKeys") if isinstance(got, dict) else None
+    if isinstance(keys, list):
+        return any(SECRET_KEY == (k if isinstance(k, str) else str((k or {}).get("key", "")))
+                   for k in keys)
+    return False
+
+
+def sources(repo: Path) -> list[str]:
+    got = spoke(run(repo, "extension", "source", "list"))
+    rows = got.get("sources") if isinstance(got, dict) else None
+    if not isinstance(rows, list):
+        return []
+    return [str(r.get("path") or r) if isinstance(r, dict) else str(r) for r in rows]
+
+
+def mint_gate(client: Client, project: str) -> dict:
+    """A gate credential, pinned to one project because the server insists and because the
+    insistence is right: `key_gate_ids` falls back to every writable project when
+    `project_id` is null, so one leaked CI secret would attest completions across all of them.
+
+    No expiry, for the same reason `gban setup`'s key has none — a credential that dies
+    overnight makes "CI can attest" quietly stop being true, and the failure surfaces as a
+    completion refusal nobody connects to a key.
+    """
+    return client.call("POST", "/api/api-keys",
+                       {"name": f"{project} swamp gate", "project_id": project,
+                        "expires_in_days": None, "scopes": GATE_SCOPES})
+
+
+def verify(url: str, key: str, project: str) -> list[dict]:
+    """Ask the credential what it is, rather than trusting the mint.
+
+    A gate key that cannot WRITE is the specific dead key this checks for: `attest_ci.py`
+    attests through `update_item`, so `gate` alone mints fine and 403s on the first real
+    attestation — months later, in CI.
+    """
+    try:
+        got = Client(url, api_key=key).call(
+            "POST", "/api/mcp",
+            {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+             "params": {"name": "get_context", "arguments": {"project_id": project}}})
+        ctx = json.loads(got["result"]["content"][0]["text"])
+    except (Unreachable, Refused) as exc:
+        return [_line("ledger", FAIL, "gate key", f"minted, but unusable: {exc}")]
+    except (KeyError, IndexError, TypeError, ValueError):
+        return [_line("ledger", UNKNOWN, "gate key",
+                      "the server answered get_context in a shape this version cannot read")]
+    scopes = set(ctx.get("scopes") or [])
+    missing = [s for s in ("write", "gate") if s not in scopes]
+    if missing:
+        return [_line("ledger", FAIL, "gate key",
+                      f"minted without {', '.join(missing)} — it would 403 on the first real "
+                      "attestation rather than here")]
+    return [_line("ledger", PASS, "gate key",
+                  f"read+write+gate on {project}, and it is not the agent's key")]
+
+
+def setup(client: Client, url: str, project: str, repo: Path, adapter: Path,
+          *, init: bool = True) -> tuple[list[dict], int]:
+    """Wire this checkout. Every step is skipped when already done and says which.
+
+    Nothing here writes an MCP config. The gate key goes into the vault and nowhere else.
+    """
+    lines: list[dict] = []
+    if not find():
+        return [_line("local", UNKNOWN, "swamp",
+                      f"not installed. Install it yourself — this does not run remote "
+                      f"scripts:\n{INSTALL}")], 0
+
+    if not initialised(repo):
+        if not init:
+            return lines + [_line("local", FAIL, "repository",
+                                  f"{repo} has no .swamp.yaml and --no-init was given")], 1
+        done = run(repo, "repo", "init", "--tool", "none")
+        if done.returncode != 0:
+            return lines + [_line("local", FAIL, "repository",
+                                  f"swamp repo init failed: {_why(done)}")], 1
+        lines.append(_line("local", PASS, "repository", f"initialised {repo/'.swamp.yaml'}"))
+    else:
+        # NEVER --force. `docs/swamp.md`: do not re-init a tree that already has a vault.
+        lines.append(_line("local", PASS, "repository", ".swamp.yaml already here"))
+
+    if not adapter.exists():
+        lines.append(_line("local", FAIL, "adapter",
+                           f"{adapter} does not exist — clone asc-me/graphban-swamp beside "
+                           "this checkout, or pass --adapter"))
+        return lines, 1
+    if adapter.resolve().is_relative_to(repo.resolve()):
+        # The runbook says "sibling, not this tree", and the reason is a licence: a nested
+        # copy is one `git add` from being committed into a repository that may not carry it.
+        lines.append(_line("local", UNKNOWN, "adapter",
+                           f"{adapter} is INSIDE this checkout; the runbook asks for a "
+                           "sibling, because a nested copy can be committed by accident"))
+    known = sources(repo)
+    if any(Path(s).resolve() == adapter.resolve() for s in known if s):
+        lines.append(_line("local", PASS, "adapter", f"{adapter} already a source"))
+    else:
+        done = run(repo, "extension", "source", "add", str(adapter))
+        lines.append(_line("local", PASS if done.returncode == 0 else FAIL, "adapter",
+                           str(adapter) if done.returncode == 0
+                           else f"source add failed: {_why(done)}"))
+        if done.returncode != 0:
+            return lines, 1
+
+    if VAULT in vaults(repo):
+        lines.append(_line("local", PASS, "vault", f"{VAULT!r} already exists"))
+    else:
+        done = run(repo, "vault", "create", VAULT_TYPE, VAULT)
+        if done.returncode != 0:
+            return lines + [_line("local", FAIL, "vault",
+                                  f"vault create failed: {_why(done)}")], 1
+        lines.append(_line("local", PASS, "vault", f"created {VAULT!r} ({VAULT_TYPE})"))
+
+    if secret_present(repo):
+        # Left alone rather than replaced. Overwriting would strand a credential that is
+        # still live on the server, and the person may have put a deliberate one there.
+        lines.append(_line("local", PASS, "secret",
+                           f"{VAULT}/{SECRET_KEY} already set — left alone. Delete it first "
+                           "to mint a new one"))
+        return lines, _worst(lines)
+
+    try:
+        minted = mint_gate(client, project)
+    except Refused as exc:
+        return lines + [_line("ledger", FAIL, "mint", str(exc))], 1
+    key = minted.get("plaintext") or ""
+    if not key:
+        return lines + [_line("ledger", FAIL, "mint", "the server returned no key")], 1
+
+    # STDIN, never argv. Swamp's own help says so: "Piping via stdin is recommended for
+    # scripts and CI to avoid exposing secrets in the process argument list."
+    done = run(repo, "vault", "put", VAULT, SECRET_KEY, stdin=key)
+    if done.returncode != 0:
+        return lines + [_line("local", FAIL, "secret",
+                              f"the key was MINTED and not stored ({_why(done)}) — revoke it "
+                              "in Settings → API keys, it is live and in nothing")], 1
+    lines.append(_line("local", PASS, "secret", f"{VAULT}/{SECRET_KEY} stored from stdin"))
+    lines += verify(url, key, project)
+    return lines, _worst(lines)
+
+
+def _why(done: subprocess.CompletedProcess) -> str:
+    got = spoke(done)
+    if isinstance(got, dict) and got.get("error"):
+        return str(got["error"])[:200]
+    tail = (done.stderr or done.stdout or "").strip().splitlines()
+    return (tail[-1][:200] if tail else f"exit {done.returncode}")
+
+
+def _worst(lines: list[dict]) -> int:
+    from gban.doctor import SEVERITY
+
+    return 1 if max((SEVERITY[l["status"]] for l in lines), default=0) == SEVERITY[FAIL] else 0

{graphban_cli-0.2.0 → graphban_cli-0.3.0}/tests/test_acts.py

@@ -164,7 +164,7 @@ INVOCATIONS = {
 #: Driven separately: `login` sends a password (its own test), `doctor` and `fleet` are PR 2,
 #: `setup` writes config files and so needs a repository and a target of its own
 #: (`test_setup.py`, which makes the same route-documentation assertion this file does).
-NOT_DRIVEN_HERE = {"login", "doctor", "fleet", "setup"}
+NOT_DRIVEN_HERE = {"login", "doctor", "fleet", "setup", "swamp"}
 
 
 def _documented() -> list[re.Pattern]:

graphban_cli-0.3.0/tests/test_swamp.py

@@ -0,0 +1,322 @@
+"""`gban swamp setup` — the gate credential, and where it must not go (GRPH-796).
+
+The load-bearing test in this file is `test_the_gate_key_never_reaches_an_mcp_config`. Every
+other failure here is loud; that one is silent. A gate key written where `gban setup` writes
+the agent key hands a completion-attesting credential to the agent doing the work — and then
+`update_item(status="done")` succeeds, CI is green, the board says the gate held, and it did
+not. There is no error to notice.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from gban import setup as setup_mod, swamp as swamp_mod
+from gban.client import Refused
+
+URL = "http://gb.invalid"
+
+
+class Server:
+    def __init__(self, *, scopes=("read", "write", "gate"), refuse=None):
+        self.scopes, self.refuse, self.minted = list(scopes), refuse, []
+
+    def call(self, method, path, body=None):
+        if path == "/api/api-keys":
+            if self.refuse is not None:
+                raise self.refuse
+            self.minted.append(body)
+            return {"id": "k1", "plaintext": "gb_sk_gate1"}
+        raise AssertionError(f"unexpected {method} {path}")
+
+
+@pytest.fixture()
+def ctx(monkeypatch):
+    """`get_context` through the minted key, as the deployment answers it."""
+    def _wire(server):
+        def call(self, method, path, body=None):
+            return {"result": {"content": [{"text": json.dumps({"scopes": server.scopes})}]}}
+        monkeypatch.setattr(swamp_mod.Client, "call", call)
+        return server
+    return _wire
+
+
+class Swamp:
+    """A recorded `swamp`. Answers `--json` the way the real binary does, errors included."""
+
+    def __init__(self, *, vaults=(), keys=(), sources=(), fail=()):
+        self.vaults, self.keys, self.sources = list(vaults), list(keys), list(sources)
+        self.fail, self.calls, self.stdin, self.cwds = set(fail), [], [], []
+
+    def __call__(self, argv, input=None, capture_output=True, text=True, timeout=None,
+                 cwd=None):
+        self.cwds.append(cwd)
+        verb = " ".join(a for a in argv[1:] if not a.startswith("--"))
+        self.calls.append(verb)
+        if input is not None:
+            self.stdin.append(input)
+        for bad in self.fail:
+            if verb.startswith(bad):
+                return subprocess.CompletedProcess(argv, 1, "", '{"error": "nope"}')
+        payload = {}
+        # THE SHAPES ARE COPIED FROM THE REAL BINARY, not invented. The first version of this
+        # double answered `vaults` and `keys`; `swamp 20260830` answers `results` and
+        # `secretKeys`. Both readers failed silently against it and the double agreed with
+        # them, because the double and the reader were written from one guess.
+        if verb.startswith("vault list-keys"):
+            payload = {"vaultName": "secrets", "vaultType": "local_encryption",
+                       "secretKeys": list(self.keys), "count": len(self.keys)}
+        elif verb.startswith("vault list"):
+            payload = {"query": "", "results": [
+                {"id": "v1", "name": v, "type": "local_encryption"} for v in self.vaults]}
+        elif verb.startswith("extension source list"):
+            payload = {"sources": [{"path": s, "expandedPaths": [s], "status": "valid"}
+                                   for s in self.sources]}
+        return subprocess.CompletedProcess(argv, 0, json.dumps(payload), "")
+
+
+@pytest.fixture()
+def wired(monkeypatch):
+    def _wire(fake):
+        monkeypatch.setattr(swamp_mod, "find", lambda: "/usr/local/bin/swamp")
+        monkeypatch.setattr(swamp_mod.subprocess, "run", fake)
+        return fake
+    return _wire
+
+
+def _tree(tmp_path):
+    repo, adapter = tmp_path / "repo", tmp_path / "graphban-swamp"
+    repo.mkdir()
+    adapter.mkdir()
+    (repo / ".swamp.yaml").write_text("{}\n")
+    return repo, adapter
+
+
+# ---- the one that is silent when it breaks -------------------------------------------------
+
+def test_the_gate_key_never_reaches_an_mcp_config(tmp_path, wired, ctx, monkeypatch):
+    """THE INVARIANT. `gban setup` writes the agent key into ~/.claude.json; a gate key there
+    would let the building agent attest its own completion, with nothing to notice."""
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+    monkeypatch.setattr(setup_mod, "write_entries",
+                        lambda *a, **k: pytest.fail("swamp setup wrote an MCP config"))
+    home = tmp_path / ".claude.json"
+    monkeypatch.setattr(setup_mod, "claude_home", lambda: home)
+
+    lines, code = swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert code == 0, lines
+    assert not home.exists(), "swamp setup created a harness config"
+    assert not (repo / ".mcp.json").exists()
+
+
+def test_the_secret_travels_on_stdin_not_argv(tmp_path, wired, ctx):
+    """`ps` is world-readable, and Swamp's own help says the same: piping via stdin is
+    recommended for scripts and CI to avoid exposing secrets in the argument list."""
+    repo, adapter = _tree(tmp_path)
+    fake = wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+
+    swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert "gb_sk_gate1" in fake.stdin
+    for call in fake.calls:
+        assert "gb_sk_" not in call, f"a credential appeared in argv: {call}"
+
+
+def test_the_key_is_minted_with_write_as_well_as_gate(tmp_path, wired, ctx):
+    """`gate` alone mints fine and 403s on the first real attestation, because `attest_ci.py`
+    attests through `update_item` — months later, in CI."""
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+    server = Server()
+
+    swamp_mod.setup(ctx(server), URL, "core", repo, adapter)
+
+    body = server.minted[0]
+    assert set(body["scopes"]) == {"read", "write", "gate"}
+    assert body["project_id"] == "core", "an unpinned gate key attests everywhere"
+    assert body["expires_in_days"] is None
+
+
+def test_a_key_that_came_back_without_write_fails_here_not_in_ci(tmp_path, wired, ctx):
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+
+    lines, code = swamp_mod.setup(ctx(Server(scopes=("read", "gate"))), URL, "core", repo, adapter)
+
+    assert code == 1
+    assert any("403 on the first real attestation" in l["detail"] for l in lines)
+
+
+# ---- refusing to do a person's job ----------------------------------------------------------
+
+def test_a_missing_swamp_is_reported_never_installed(tmp_path, monkeypatch, ctx):
+    """The documented install pipes a remote script into a shell. That is not something a
+    tool should do on somebody's behalf, however convenient."""
+    repo, adapter = _tree(tmp_path)
+    monkeypatch.setattr(swamp_mod, "find", lambda: "")
+    monkeypatch.setattr(swamp_mod.subprocess, "run",
+                        lambda *a, **k: pytest.fail("ran a command with no swamp installed"))
+
+    lines, code = swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert code == 0, "a missing swamp is not a failed setup"
+    assert any("curl" in l["detail"] and "install.sh" in l["detail"] for l in lines)
+
+
+def test_an_existing_secret_is_left_alone(tmp_path, wired, ctx):
+    """Overwriting would strand a live credential on the server, and the one there may be
+    deliberate."""
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], keys=["graphban-api-key"], sources=[str(adapter)]))
+    server = Server()
+
+    lines, code = swamp_mod.setup(ctx(server), URL, "core", repo, adapter)
+
+    assert code == 0
+    assert server.minted == [], "minted a second gate key over a working one"
+    assert any("left alone" in l["detail"] for l in lines)
+
+
+def test_an_initialised_repo_is_never_reinitialised(tmp_path, wired, ctx):
+    """`docs/swamp.md`: do not `repo init --force` a tree that already has a vault."""
+    repo, adapter = _tree(tmp_path)
+    fake = wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+
+    swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert not any(c.startswith("repo init") for c in fake.calls)
+    assert not any("--force" in c for c in fake.calls)
+
+
+def test_a_nested_adapter_is_flagged(tmp_path, wired, ctx):
+    """The runbook asks for a sibling. A copy inside the tree is one `git add` from being
+    committed into a repository whose licence forbids carrying Swamp source."""
+    repo, _ = _tree(tmp_path)
+    inside = repo / "graphban-swamp"
+    inside.mkdir()
+    wired(Swamp(vaults=["secrets"], sources=[str(inside)]))
+
+    lines, _ = swamp_mod.setup(ctx(Server()), URL, "core", repo, inside)
+
+    assert any("INSIDE this checkout" in l["detail"] for l in lines)
+
+
+def test_a_missing_adapter_refuses_before_minting(tmp_path, wired, ctx):
+    repo, _ = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"]))
+    server = Server()
+
+    lines, code = swamp_mod.setup(ctx(server), URL, "core", repo, tmp_path / "nope")
+
+    assert code == 1
+    assert server.minted == [], "minted a key for a wiring it could not finish"
+
+
+def test_a_key_minted_and_not_stored_says_to_revoke_it(tmp_path, wired, ctx):
+    """The one genuinely bad state: live on the server, present in nothing. It must not be
+    reported as a generic failure."""
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], sources=[str(adapter)], fail=["vault put"]))
+
+    lines, code = swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert code == 1
+    said = " ".join(l["detail"] for l in lines)
+    assert "revoke it" in said and "Settings" in said
+
+
+def test_a_refused_mint_stores_nothing(tmp_path, wired, ctx):
+    repo, adapter = _tree(tmp_path)
+    fake = wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+
+    lines, code = swamp_mod.setup(ctx(Server(refuse=Refused(403, "no", ""))), URL, "core",
+                                  repo, adapter)
+
+    assert code == 1
+    assert not any(c.startswith("vault put") for c in fake.calls)
+
+
+def test_every_swamp_call_is_scoped_to_the_repository(tmp_path, wired, ctx):
+    """By `cwd`, because `--repo-dir` does not exist. Swamp's own error text recommends that
+    flag and `swamp 20260830` rejects it on every verb — found by running the real binary,
+    which is the only place a tool's advice about its own flags can be checked.
+
+    Scoping matters either way: a caller standing somewhere else must not wire a different
+    checkout, silently."""
+    repo, adapter = _tree(tmp_path)
+    fake = wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+
+    swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert fake.cwds, "no swamp call was made"
+    assert all(c == str(repo) for c in fake.cwds), fake.cwds
+    assert not any("--repo-dir" in c for c in fake.calls)
+
+
+def test_a_pretty_printed_error_is_read_as_one(tmp_path, wired, ctx):
+    """Swamp formats its JSON across lines. Reading line by line found nothing and fell back
+    to the last line of stderr — which for a formatted object is `}`, an error report that
+    looks like a real message."""
+    repo, adapter = _tree(tmp_path)
+
+    class Formatted(Swamp):
+        def __call__(self, argv, **kw):
+            done = super().__call__(argv, **kw)
+            if "put" in argv:
+                return subprocess.CompletedProcess(
+                    argv, 1, "", '{\n  "error": "vault is sealed"\n}\n')
+            return done
+
+    wired(Formatted(vaults=["secrets"], sources=[str(adapter)]))
+    lines, code = swamp_mod.setup(ctx(Server()), URL, "core", repo, adapter)
+
+    assert code == 1
+    said = " ".join(l["detail"] for l in lines)
+    assert "vault is sealed" in said, said
+
+
+def test_every_route_swamp_setup_calls_is_documented(tmp_path, wired, monkeypatch):
+    """The check `test_acts.py` makes for the verbs it drives, made here for the one it
+    cannot: `swamp` needs a checkout and a binary of its own."""
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets"], sources=[str(adapter)]))
+    reference = (Path(__file__).resolve().parents[2] / "docs" / "api-reference.md"
+                 ).read_text(encoding="utf-8")
+    seen = []
+
+    class Watching(Server):
+        def call(self, method, path, body=None):
+            seen.append(path)
+            return super().call(method, path, body)
+
+    def context(self, method, path, body=None):
+        seen.append(path)
+        return {"result": {"content": [{"text": json.dumps({"scopes": list(swamp_mod.GATE_SCOPES)})}]}}
+
+    monkeypatch.setattr(swamp_mod.Client, "call", context)
+    swamp_mod.setup(Watching(), URL, "core", repo, adapter)
+
+    assert seen, "swamp setup made no HTTP call"
+    for path in seen:
+        assert f"`{path}`" in reference, f"{path} is not in docs/api-reference.md"
+
+
+def test_the_readers_match_what_swamp_actually_returns(tmp_path, wired, ctx):
+    """A shape pinned against the recorded output of `swamp 20260830`.
+
+    This exists because the alternative already happened: the readers looked for `vaults` and
+    `keys`, the real binary answers `results` and `secretKeys`, and the double was written
+    from the same guess as the readers — so the suite was green while `secret_present` could
+    only ever return False. That failure mints another live gate credential on every run.
+    """
+    repo, adapter = _tree(tmp_path)
+    wired(Swamp(vaults=["secrets", "other"], keys=["graphban-api-key"], sources=[str(adapter)]))
+
+    assert swamp_mod.vaults(repo) == ["secrets", "other"]
+    assert swamp_mod.secret_present(repo) is True
+    assert swamp_mod.sources(repo) == [str(adapter)]