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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.2.0
+Version: 0.4.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
@@ -127,28 +127,53 @@ is named in the refusal when it exists — logging in once inside one project mu
 mint a credential for it while you are standing in another repository, and a key in the wrong
 project is not a mistake anybody notices quickly.
 
-`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
-installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
-and then **verifies** rather than asserting: it asks the new credential what it can actually
-see. Restart the harness afterwards — MCP servers are read at startup.
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries
+into every parent harness that would actually read them, installs the supervisor if it is
+missing, drops the delegation skill into `.claude/skills/`, and then **verifies** rather than
+asserting: it asks the new credential what it can actually see. Restart the session that will
+call `delegate`/`spawn` afterwards — MCP servers are read at startup.
 
 Three properties worth knowing, each of which is a bug this command exists to not have:
 
 - **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
   day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
-- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
-  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
-  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
-  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
-  because a credential outside the repository cannot be committed.
+- **It writes where the harness will actually read.** There is more than one. Claude Code
+  reads `~/.claude.json`'s per-project `mcpServers` (JSON), which outranks a repository
+  `.mcp.json` — writing the repository file under a stale entry leaves the agent on the old
+  key, and surfaces as a JSON parse error because the harness is parsing a 401 body. Grok
+  reads `~/.grok/config.toml`'s `mcp_servers` (TOML, snake_case; `mcpServers` parses and
+  loads nothing). Writing only Claude's file while Grok holds a different key reports
+  success and leaves `delegate` unadvertised (GRPH-825). Grok's `gbfleet` MCP also
+  gets `--workspace ~/.grok/gbfleet-wt/<repo>`: the sibling default is a path Grok's
+  sandbox cannot write, and spawn then dies as `git worktree add` 128 (GRPH-826).
+  Claude keeps the sibling default. `--scope user` is the default because a credential
+  outside the repository cannot be committed. Re-running a working setup still
+  *repairs* a missing `gbfleet` entry and a missing `--workspace`; reuse skips a mint,
+  never a write.
 - **`--auto` matches, and says so.** A project carries no repository link — no remote, no
   path — so `--auto` compares your project ids and names against this directory, what is in
   it, and its siblings. One level, never a recursive walk. Two directories answering to one
   project, or one directory answering to two, are **refused rather than guessed**: a
   credential minted into the wrong repository is not a mistake anybody notices quickly.
 - **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
-  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
-  credential still commits it.
+  `.mcp.json` or `.grok/config.toml` 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
 

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

@@ -112,28 +112,53 @@ is named in the refusal when it exists — logging in once inside one project mu
 mint a credential for it while you are standing in another repository, and a key in the wrong
 project is not a mistake anybody notices quickly.
 
-`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
-installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
-and then **verifies** rather than asserting: it asks the new credential what it can actually
-see. Restart the harness afterwards — MCP servers are read at startup.
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries
+into every parent harness that would actually read them, installs the supervisor if it is
+missing, drops the delegation skill into `.claude/skills/`, and then **verifies** rather than
+asserting: it asks the new credential what it can actually see. Restart the session that will
+call `delegate`/`spawn` afterwards — MCP servers are read at startup.
 
 Three properties worth knowing, each of which is a bug this command exists to not have:
 
 - **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
   day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
-- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
-  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
-  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
-  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
-  because a credential outside the repository cannot be committed.
+- **It writes where the harness will actually read.** There is more than one. Claude Code
+  reads `~/.claude.json`'s per-project `mcpServers` (JSON), which outranks a repository
+  `.mcp.json` — writing the repository file under a stale entry leaves the agent on the old
+  key, and surfaces as a JSON parse error because the harness is parsing a 401 body. Grok
+  reads `~/.grok/config.toml`'s `mcp_servers` (TOML, snake_case; `mcpServers` parses and
+  loads nothing). Writing only Claude's file while Grok holds a different key reports
+  success and leaves `delegate` unadvertised (GRPH-825). Grok's `gbfleet` MCP also
+  gets `--workspace ~/.grok/gbfleet-wt/<repo>`: the sibling default is a path Grok's
+  sandbox cannot write, and spawn then dies as `git worktree add` 128 (GRPH-826).
+  Claude keeps the sibling default. `--scope user` is the default because a credential
+  outside the repository cannot be committed. Re-running a working setup still
+  *repairs* a missing `gbfleet` entry and a missing `--workspace`; reuse skips a mint,
+  never a write.
 - **`--auto` matches, and says so.** A project carries no repository link — no remote, no
   path — so `--auto` compares your project ids and names against this directory, what is in
   it, and its siblings. One level, never a recursive walk. Two directories answering to one
   project, or one directory answering to two, are **refused rather than guessed**: a
   credential minted into the wrong repository is not a mistake anybody notices quickly.
 - **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
-  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
-  credential still commits it.
+  `.mcp.json` or `.grok/config.toml` 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
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.2.0"
+version = "0.4.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.4.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)
@@ -56,14 +56,17 @@ def _parser() -> argparse.ArgumentParser:
     setup_cmd = sub.add_parser(
         "setup", help="enable delegation on a project",
         description=("Mints a project-scoped credential that does NOT expire, writes the "
-                     "graphban and gbfleet MCP entries where the harness will actually read "
-                     "them, and installs the supervisor. Only seats expire; a credential that "
-                     "died overnight would make 'delegation is set up' quietly stop being "
-                     "true. Re-running is safe: a working configuration is left alone."))
+                     "graphban and gbfleet MCP entries into Claude Code (~/.claude.json) and "
+                     "Grok (~/.grok/config.toml, TOML mcp_servers) — every file a parent "
+                     "harness will actually read — and installs the supervisor. Only seats "
+                     "expire; a credential that died overnight would make 'delegation is set "
+                     "up' quietly stop being true. Re-running is safe: a working key is "
+                     "reused, a missing gbfleet entry is still repaired."))
     setup_cmd.add_argument(
         "--scope", choices=["user", "project"], default="user",
-        help="user (default) writes ~/.claude.json, which OUTRANKS a repo .mcp.json and "
-             "cannot be committed; project writes .mcp.json beside the repo")
+        help="user (default) writes ~/.claude.json and, when it exists, ~/.grok/config.toml; "
+             "project writes .mcp.json and .grok/config.toml beside the repo. A user file "
+             "outranks the repo copy and cannot be committed")
     setup_cmd.add_argument(
         "--auto", action="store_true",
         help="every project with a repository here: matches this directory, what is in it and "
@@ -73,6 +76,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 "
@@ -295,7 +313,8 @@ def cmd_setup(args) -> int:
     if code == 0:
         human.append(f"\n     delegation is enabled on {project}. An agent can now "
                      f"`delegate(id=…, lane=…, tier=…, seat=true)` then `spawn`.")
-        human.append(f"     restart the harness so it reads the new config.")
+        human.append("     restart Claude Code and/or Grok — whichever session will call "
+                     "`delegate`/`spawn` — so it reads the new config.")
     _out({"lines": lines, "ok": code == 0, "project": project, **made},
          "\n".join(human), args.as_json)
     return code
@@ -325,11 +344,43 @@ def _setup_auto(args, url: str, client) -> int:
         done[pid], worst = {"repo": str(repo), "ok": code == 0, **made}, max(worst, code)
     human = [doctor_mod.render(lines),
              f"\n     {sum(1 for d in done.values() if d['ok'])} of {len(done)} enabled. "
-             f"Restart the harness so it reads the new config."]
+             "Restart Claude Code and/or Grok — whichever session will call "
+             "`delegate`/`spawn` — so it reads the new config."]
     _out({"lines": lines, "ok": worst == 0, "projects": done}, "\n".join(human), args.as_json)
     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 +532,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: