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

{graphban_cli-0.3.0 → graphban_cli-0.5.0}/.gitignore

@@ -57,6 +57,24 @@ dist-release/
 # Project MCP config — holds a real API key
 .mcp.json
 
+# gban --scope project writes the same live key into Grok's project file, and
+# gbfleet's grok adapter writes the child's seat there. Tracked, spawn refuses
+# (fleet/tests/test_repo_keeps_its_own_config.py); unignored, it is one `git add`
+# from a committed credential. `.grok/mcp.json` is the pre-GRPH-575 name.
+.grok/config.toml
+.grok/mcp.json
+
+# gbfleet: enrolment code (`.gbfleet-instruction`), fallback seat, doctor/spawn
+# probes, in-tree worktree pool. Salvage already excludes the seat paths from a
+# WIP commit; git status in the parent checkout still offers them to `git add`.
+.gbfleet-*
+
+# Swamp vault ciphertext, and a nested copy of the adapter. docs/swamp.md: commit
+# `.swamp.yaml`; do not commit these. The adapter is a sibling on purpose — a
+# nested clone is one add from a tree whose licence forbids carrying Swamp source.
+.swamp/
+graphban-swamp/
+
 # Cursor claim manifest — per-session runtime state (see .cursor/hooks/README.md)
 .cursor/graphban-claim.json
 .cursor/agentledger-claim.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.3.0
+Version: 0.5.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,49 @@ 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, stores that key next to the login
+session (a `gb_sk_…`, never the refresh token), 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.
+
+`gban fleet` and `gban doctor`'s local half then use that minted key. They do not feed the
+login session to the supervisor. The order is `$GBFLEET_API_KEY` if you set it, then
+`$GRAPHBAN_API_KEY`, then the key `gban setup` stored — and, for a machine that already ran
+setup, the one already in the harness dest.
 
 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.
+- **It gitignores the files it and `gbfleet` write into the checkout.** `.mcp.json`,
+  `.cursor/mcp.json`, `.grok/config.toml`, `.gbfleet-*`, `.swamp/`, `graphban-swamp/`.
+  A warning that said "make sure it is gitignored" still wrote the key; `gban setup`
+  now adds the lines, and `gban doctor` FAILs if a credential file would still be
+  committed. It asks git (`check-ignore`), so an equivalent pattern already in the
+  file is left alone.
 
 ## Wiring a checkout to Swamp
 

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

@@ -112,28 +112,49 @@ 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, stores that key next to the login
+session (a `gb_sk_…`, never the refresh token), 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.
+
+`gban fleet` and `gban doctor`'s local half then use that minted key. They do not feed the
+login session to the supervisor. The order is `$GBFLEET_API_KEY` if you set it, then
+`$GRAPHBAN_API_KEY`, then the key `gban setup` stored — and, for a machine that already ran
+setup, the one already in the harness dest.
 
 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.
+- **It gitignores the files it and `gbfleet` write into the checkout.** `.mcp.json`,
+  `.cursor/mcp.json`, `.grok/config.toml`, `.gbfleet-*`, `.swamp/`, `graphban-swamp/`.
+  A warning that said "make sure it is gitignored" still wrote the key; `gban setup`
+  now adds the lines, and `gban doctor` FAILs if a credential file would still be
+  committed. It asks git (`check-ignore`), so an equivalent pattern already in the
+  file is left alone.
 
 ## Wiring a checkout to Swamp
 

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

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

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

@@ -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 "
@@ -275,7 +278,7 @@ def cmd_whoami(args) -> int:
 def cmd_doctor(args) -> int:
     url = config.resolve(args.server, config.URL_ENV, "url")
     project = config.resolve(args.project, config.PROJECT_ENV, "project")
-    api_key = os.environ.get(config.API_KEY_ENV, "")
+    api_key = doctor_mod.resolve_supervisor_key(project)
     lines, code = doctor_mod.run(url, project, api_key)
     _out({"lines": lines, "ok": code == 0}, doctor_mod.render(lines), args.as_json)
     return code
@@ -310,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
@@ -340,7 +344,8 @@ 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
 
@@ -406,9 +411,11 @@ def cmd_fleet(args) -> int:
     # message is the one its own tests pin.
     #
     # The ENVIRONMENT goes through the same function `doctor` uses (GRPH-782). It used not
-    # to, so the doctor certified a local half this command could not reproduce.
+    # to, so the doctor certified a local half this command could not reproduce. The key
+    # is resolved the same way too: env, then the setup-minted agent key, never the login
+    # session — a doctor PASS that does not predict `gban fleet` is the original lie.
     return subprocess.run(argv, env=doctor_mod.child_environment(
-        os.environ.get(config.API_KEY_ENV, ""))).returncode
+        doctor_mod.resolve_supervisor_key(project))).returncode
 
 
 def _project(args, act: str) -> str:

graphban_cli-0.5.0/src/gban/config.py

@@ -0,0 +1,212 @@
+"""Where `gban` keeps its two facts, and why they are two files (PRD-40 D3, D10).
+
+`~/.graphban/` is shared with `graphban`, the operator's database-side tool, and the sharing
+stops at the directory. `gban` reads `gban.json` (`url`, `project`) and `session.json` (a refresh
+token) and **never opens `config.json`**, which is `graphban`'s and may hold a database link.
+
+A third file, `supervisor.json`, holds the project-scoped **agent** keys `gban setup` minted
+(`gb_sk_…`). It is not the login session. `gban fleet` / `gban doctor` hand that key to
+`gbfleet`; feeding the refresh token instead is how a working session produces "session
+expired" on the supervisor (GRPH-782).
+
+The grill made that stricter than the draft. Reading `config.json` and ignoring the keys it did
+not recognise would have been true and insufficient: the risk is not misreading a database
+password, it is that password living in a file which now has a second consumer and a second
+reason to be copied onto another machine. `graphban` runs in a container against a database;
+`gban` runs on a laptop against HTTP; the credential that must not cross that line lives in its
+own file, so copying a config never carries it.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+import subprocess
+from pathlib import Path
+
+#: The directory both tools use. Shared deliberately — a person has one Graphban.
+HOME_ENV = "GRAPHBAN_HOME"
+
+#: `gban`'s own settings. NOT `config.json`, which belongs to `graphban` (D10).
+SETTINGS_FILE = "gban.json"
+
+#: The refresh token, alone in its own file so that copying settings never carries it.
+SESSION_FILE = "session.json"
+
+#: Project-scoped agent keys `gban setup` minted. Next to the session, never inside it —
+#: a refresh token and a `gb_sk_…` are different credentials, and mixing them is the
+#: remaining hole GRPH-782 was reopened for.
+SUPERVISOR_KEYS_FILE = "supervisor.json"
+
+#: `graphban`'s file. Named here only so the test that asserts `gban` never opens it has
+#: something to name, and so a reader knows the omission is deliberate.
+NOT_OURS = "config.json"
+
+#: What a minted agent key looks like. `gbfleet` wants this; a user refresh token is not it.
+AGENT_KEY_PREFIX = "gb_sk_"
+
+URL_ENV = "GRAPHBAN_URL"
+PROJECT_ENV = "GRAPHBAN_PROJECT"
+API_KEY_ENV = "GRAPHBAN_API_KEY"
+
+#: Owner read/write and nothing else. A credential at rest gets the same mode the seat files
+#: in `gbfleet` get, for the same reason.
+PRIVATE = stat.S_IRUSR | stat.S_IWUSR
+
+
+def home() -> Path:
+    return Path(os.environ.get(HOME_ENV) or (Path.home() / ".graphban"))
+
+
+def _read(path: Path) -> dict:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        # A missing file and an unreadable one are the same to a caller that has a default,
+        # and neither is worth a traceback in front of somebody trying to log in.
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def _write(path: Path, payload: dict) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Created private BEFORE anything is written to it. Writing first and chmod-ing after
+    # leaves a window where the token is world-readable, which is the whole failure.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, PRIVATE)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=1, sort_keys=True)
+        fh.write("\n")
+    _make_private(path)
+    return path
+
+
+def _make_private(path: Path) -> None:
+    """Owner-only, including on Windows where `chmod 0600` is a no-op (GRPH-855)."""
+    os.chmod(path, PRIVATE)
+    if os.name != "nt":
+        return
+    user = os.environ.get("USERNAME") or ""
+    if not user:
+        return
+    subprocess.run(
+        ["icacls", str(path), "/inheritance:r", "/grant:r", f"{user}:(F)"],
+        capture_output=True, text=True, timeout=30,
+    )
+    listing = subprocess.run(
+        ["icacls", str(path)], capture_output=True, text=True, timeout=30,
+    )
+    if listing.returncode != 0:
+        return
+    me = user.casefold()
+    prefix = str(path)
+    for line in listing.stdout.splitlines():
+        if ":(" not in line:
+            continue
+        principal = line.split(":(")[0].strip()
+        if principal.lower().startswith(prefix.lower()):
+            principal = principal[len(prefix):].strip()
+        if not principal:
+            continue
+        if principal.rsplit("\\", 1)[-1].casefold() == me:
+            continue
+        subprocess.run(
+            ["icacls", str(path), "/remove", principal],
+            capture_output=True, text=True, timeout=30,
+        )
+
+
+def is_private(path: Path) -> bool:
+    """Whether `path` is owner-only. POSIX is the mode bits; Windows is the ACL.
+
+    Asserting `st_mode == 0o600` goes red on NTFS for a reason that has nothing to do
+    with whether anyone else can read the file (GRPH-855).
+    """
+    path = Path(path)
+    if os.name != "nt":
+        try:
+            return stat.S_IMODE(path.stat().st_mode) == PRIVATE
+        except OSError:
+            return False
+    user = (os.environ.get("USERNAME") or "").casefold()
+    listing = subprocess.run(
+        ["icacls", str(path)], capture_output=True, text=True, timeout=30,
+    )
+    if listing.returncode != 0:
+        return False
+    prefix = str(path)
+    saw_owner = False
+    for line in listing.stdout.splitlines():
+        if ":(" not in line:
+            continue
+        principal = line.split(":(")[0].strip()
+        if principal.lower().startswith(prefix.lower()):
+            principal = principal[len(prefix):].strip()
+        if not principal:
+            continue
+        account = principal.rsplit("\\", 1)[-1].casefold()
+        if account == user:
+            saw_owner = True
+            continue
+        return False
+    return saw_owner
+
+
+def settings() -> dict:
+    return _read(home() / SETTINGS_FILE)
+
+
+def save_settings(**values: str) -> Path:
+    merged = {k: v for k, v in {**settings(), **values}.items() if v}
+    return _write(home() / SETTINGS_FILE, merged)
+
+
+def session() -> dict:
+    return _read(home() / SESSION_FILE)
+
+
+def save_session(refresh_token: str, *, user: str = "") -> Path:
+    return _write(home() / SESSION_FILE,
+                  {"refresh_token": refresh_token, "user": user})
+
+
+def clear_session() -> bool:
+    path = home() / SESSION_FILE
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _agent_key(value: str) -> str:
+    value = (value or "").strip()
+    return value if value.startswith(AGENT_KEY_PREFIX) else ""
+
+
+def save_supervisor_key(project: str, key: str) -> Path | None:
+    """Store the project-scoped agent key `gban setup` minted. Refuses a refresh token."""
+    key = _agent_key(key)
+    if not project or not key:
+        return None
+    blob = _read(home() / SUPERVISOR_KEYS_FILE)
+    keys = blob.get("keys") if isinstance(blob.get("keys"), dict) else {}
+    keys[project] = key
+    return _write(home() / SUPERVISOR_KEYS_FILE, {"keys": keys})
+
+
+def stored_supervisor_key(project: str) -> str:
+    """The agent key setup stored for this project, or empty. Never reads `session.json`."""
+    if not project:
+        return ""
+    blob = _read(home() / SUPERVISOR_KEYS_FILE)
+    keys = blob.get("keys") if isinstance(blob.get("keys"), dict) else {}
+    return _agent_key(str(keys.get(project) or ""))
+
+
+def resolve(flag: str | None, env: str, key: str) -> str:
+    """D10's precedence, in one place: flag, then environment, then the settings file.
+
+    One function rather than three lookups at each call site, because a precedence that is
+    re-implemented per option is one that will eventually differ per option.
+    """
+    return (flag or os.environ.get(env) or settings().get(key) or "").strip()

{graphban_cli-0.3.0 → graphban_cli-0.5.0}/src/gban/doctor.py

@@ -16,7 +16,7 @@ import shutil
 import subprocess
 from pathlib import Path
 
-from gban import config
+from gban import config, gitignore
 from gban.client import Client, NoSession, Refused, Unreachable, authenticated
 
 PASS, FAIL, UNKNOWN = "PASS", "FAIL", "UNKNOWN"
@@ -200,6 +200,31 @@ def install_supervisor(timeout: float = 600.0) -> tuple[bool, str]:
     return True, ""
 
 
+def _sibling_binary(name: str) -> str:
+    """An executable beside this interpreter, trying the platform suffix that actually
+    exists. On Windows a `pip install` of both packages drops `gbfleet.exe` into
+    `Scripts\\`; on Unix it drops `gbfleet` into `bin/`. Checking the bare name on Windows
+    is the same hole the Unix sibling check used to have — the file is there and the lookup
+    says it is not.
+
+    `os.access(X_OK)` is true of almost every file on Windows, so a leftover extensionless
+    `gbfleet` (chmod 0644 even) would win over `gbfleet.exe` if we asked for the bare name
+    first (GRPH-855).
+    """
+    import sys
+
+    parent = Path(sys.executable).parent
+    bare, exe = parent / name, parent / f"{name}.exe"
+    if os.name == "nt":
+        # X_OK is true of almost every file here, so a leftover extensionless
+        # `gbfleet` would win over `gbfleet.exe` (GRPH-855).
+        return str(exe) if exe.is_file() else ""
+    for candidate in (bare, exe):
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return ""
+
+
 def find_supervisor() -> str:
     """`gbfleet`, from beside this interpreter first and only then from PATH.
 
@@ -213,13 +238,10 @@ def find_supervisor() -> str:
     PATH still wins for a supervisor the operator installed separately and put there on
     purpose — a sibling is a fallback for the case PATH cannot see, not an override of it.
     """
-    import sys
-
     found = shutil.which("gbfleet")
     if found:
         return found
-    beside = Path(sys.executable).parent / "gbfleet"
-    return str(beside) if beside.exists() and os.access(beside, os.X_OK) else ""
+    return _sibling_binary("gbfleet")
 
 
 #: What `gbfleet` reads. `gban` names it once, here, and both paths that launch a supervisor
@@ -227,6 +249,45 @@ def find_supervisor() -> str:
 SUPERVISOR_KEY_ENV = "GBFLEET_API_KEY"
 
 
+def resolve_supervisor_key(project: str, repo: Path | None = None) -> str:
+    """The agent key we hand `child_environment` as `api_key`.
+
+    Order (GRPH-782 remaining hole): `$GRAPHBAN_API_KEY`, then the project-scoped key
+    `gban setup` stored next to `session.json`, then the key setup already wrote into a
+    harness dest for this repository. `$GBFLEET_API_KEY` the caller set is preserved
+    inside `child_environment`, so it is not resolved here.
+
+    Never the login session. A refresh token is a different kind of credential.
+    """
+    env_key = (os.environ.get(config.API_KEY_ENV) or "").strip()
+    if env_key:
+        return env_key
+    stored = config.stored_supervisor_key(project)
+    if stored:
+        return stored
+    return _harness_supervisor_key(repo)
+
+
+def _harness_supervisor_key(repo: Path | None) -> str:
+    """The key `gban setup` already wrote into a parent-harness dest.
+
+    Lazy-imports setup: that module imports this one, and a top-level cycle would
+    make `gban doctor` fail to import on a machine that has never run setup.
+    """
+    from gban import setup as setup_mod
+
+    repo = (repo or Path.cwd()).resolve()
+    seen: list[str] = []
+    for scope in ("user", "project"):
+        dests, _ = setup_mod.destinations(
+            repo, scope, setup_mod.claude_home(), setup_mod.grok_home())
+        for dest in dests:
+            key = (setup_mod.dest_key(dest, repo) or "").strip()
+            if key.startswith(config.AGENT_KEY_PREFIX) and key not in seen:
+                seen.append(key)
+    return seen[0] if seen else ""
+
+
 def child_environment(api_key: str) -> dict:
     """The environment a `gbfleet` child is launched with, for `doctor` AND for `fleet`.
 
@@ -251,8 +312,10 @@ def child_environment(api_key: str) -> dict:
     return env
 
 
-def run(url: str, project: str, api_key: str = "") -> tuple[list[dict], int]:
-    lines = ledger(url, project) + local(url, project, api_key)
+def run(url: str, project: str, api_key: str = "",
+        repo: Path | None = None) -> tuple[list[dict], int]:
+    lines = (ledger(url, project) + local(url, project, api_key)
+             + gitignore.check(repo or Path.cwd()))
     worst = max((SEVERITY[l["status"]] for l in lines), default=0)
     # FAIL exits 1, UNKNOWN exits 0: "could not check" is not "broken", and a doctor that
     # failed a script because a laptop lacked `gbfleet` would stop being run.