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

{graphban_cli-0.4.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.4.0 → graphban_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.4.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
@@ -128,11 +128,17 @@ mint a credential for it while you are standing in another repository, and a key
 project is not a mistake anybody notices quickly.
 
 `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
+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
@@ -158,6 +164,12 @@ Three properties worth knowing, each of which is a bug this command exists to no
 - **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
   `.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.4.0 → graphban_cli-0.5.0}/README.md

@@ -113,11 +113,17 @@ mint a credential for it while you are standing in another repository, and a key
 project is not a mistake anybody notices quickly.
 
 `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
+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
@@ -143,6 +149,12 @@ Three properties worth knowing, each of which is a bug this command exists to no
 - **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
   `.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.4.0 → graphban_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.4.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.4.0 → graphban_cli-0.5.0}/src/gban/cli.py

@@ -278,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
@@ -411,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.4.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.

graphban_cli-0.5.0/src/gban/gitignore.py

@@ -0,0 +1,176 @@
+"""Keep gban/gbfleet credentials out of `git add`.
+
+The files this tool writes into a checkout — `.mcp.json`, Grok's project config, a
+Cursor seat, a gbfleet enrolment instruction, a Swamp vault — are live keys. A warning
+attached to writing them still writes them, and `git add .` does not read warnings.
+So setup *writes the ignore lines*, and doctor *fails* if a file that exists would
+still be committed. Asking git (`check-ignore`) rather than grepping `.gitignore`
+is the load-bearing bit: an equivalent pattern (`.cursor/`, a user exclude file)
+already does the job, and a string match would either duplicate it or miss it.
+
+A path git already tracks is a different refusal. gitignore does not untrack, and
+pretending it does is how a key that is already in the index keeps shipping.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+# Same three states as `gban.doctor`, inlined so this module cannot import doctor
+# (doctor calls `check`, and a cycle here would make `gban doctor` fail to import).
+PASS, FAIL, UNKNOWN = "PASS", "FAIL", "UNKNOWN"
+
+
+def _line(side: str, status: str, name: str, detail: str = "") -> dict:
+    return {"side": side, "status": status, "name": name, "detail": detail, "report": ""}
+
+
+#: What we write. Concrete files gban and gbfleet actually emit, plus the two swamp
+#: paths `docs/swamp.md` names. `.gbfleet-*` covers instruction, seat, probes and an
+#: in-tree worktree pool without enumerating each one as it appears.
+PATTERNS = (
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".grok/config.toml",
+    ".grok/mcp.json",
+    ".gbfleet-*",
+    ".swamp/",
+    "graphban-swamp/",
+)
+
+#: What we ASK git about. A glob is not a path; these are the files that would be
+#: committed. Directory patterns keep the trailing slash: `check-ignore .swamp`
+#: does not honour `.swamp/`, but `check-ignore .swamp/` does. `.gbfleet-instruction`
+#: is the representative of `.gbfleet-*` because it carries a live enrolment code.
+PROBES = (
+    ".mcp.json",
+    ".cursor/mcp.json",
+    ".grok/config.toml",
+    ".grok/mcp.json",
+    ".gbfleet-instruction",
+    ".swamp/",
+    "graphban-swamp/",
+)
+
+HEADER = "# Graphban — live keys and seats. Maintained by `gban setup`."
+
+
+def is_repo(path: Path) -> bool:
+    """`.git` is a directory in a clone and a file in a worktree."""
+    return (path / ".git").exists()
+
+
+def _git(repo: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["git", "-C", str(repo), *args],
+                          capture_output=True, text=True, timeout=10)
+
+
+def usable(repo: Path) -> bool:
+    """A `.git` marker is not a repository git will answer. Tests (and `--auto`)
+    plant an empty `.git` directory as the marker; writing a gitignore that git
+    then cannot honour would FAIL every one of them."""
+    if not is_repo(repo):
+        return False
+    try:
+        done = _git(repo, "rev-parse", "--is-inside-work-tree")
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.returncode == 0 and done.stdout.strip() == "true"
+
+
+def tracked(repo: Path, rel: str) -> bool:
+    try:
+        done = _git(repo, "ls-files", "--error-unmatch", "--", rel)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.returncode == 0
+
+
+def ignored(repo: Path, rel: str) -> bool:
+    """Would `git add` skip this path? Tracked files are not ignored, even when a
+    pattern matches — that is git's rule, and it is why a tracked credential is a
+    FAIL rather than a write-to-gitignore."""
+    try:
+        done = _git(repo, "check-ignore", "-q", "--", rel)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return done.returncode == 0
+
+
+def _probe_for(pattern: str) -> str:
+    if pattern == ".gbfleet-*":
+        return ".gbfleet-instruction"
+    return pattern
+
+
+def missing(repo: Path) -> list[str]:
+    """Patterns that would not actually ignore their probe path."""
+    return [p for p in PATTERNS if not ignored(repo, _probe_for(p))]
+
+
+def leaking(repo: Path) -> list[str]:
+    """Probes that exist on disk or are tracked, and would still be committed."""
+    out = []
+    for rel in PROBES:
+        disk = rel.rstrip("/")
+        if tracked(repo, disk) or (repo / disk).exists():
+            if not ignored(repo, rel):
+                out.append(disk)
+    return out
+
+
+def ensure(repo: Path) -> list[dict]:
+    """Append any missing patterns to `.gitignore`. Idempotent.
+
+    Not a git repository: nothing to write (the caller already reports that). A
+    pattern git already honours — however it is spelled — is left alone.
+    """
+    if not usable(repo):
+        return []
+    needed = missing(repo)
+    if not needed:
+        return [_line("config", PASS, "gitignore",
+                      "credential paths are gitignored")]
+    path = repo / ".gitignore"
+    try:
+        existing = path.read_text(encoding="utf-8") if path.exists() else ""
+        block = "\n".join([HEADER, *needed]) + "\n"
+        text = block if not existing else existing.rstrip("\n") + "\n\n" + block
+        path.write_text(text, encoding="utf-8")
+    except OSError as exc:
+        return [_line("config", FAIL, "gitignore",
+                      f"could not write {path}: {exc}. Refusing to leave a key "
+                      "unignored — add the lines by hand, or use --scope user")]
+    still = missing(repo)
+    if still:
+        return [_line("config", FAIL, "gitignore",
+                      f"wrote {path} but git still would not ignore "
+                      f"{', '.join(still)}")]
+    return [_line("config", PASS, "gitignore",
+                  f"added to {path}: {', '.join(needed)}")]
+
+
+def check(repo: Path) -> list[dict]:
+    """Doctor: fail if a credential file would be committed, not if the patterns
+    are merely absent. Absence of the files is not a clean result either — that
+    prints UNKNOWN, because 'nobody has written a key here yet' is not 'safe'.
+    """
+    if not usable(repo):
+        return []
+    live = leaking(repo)
+    if live:
+        tracked_ones = [p for p in live if tracked(repo, p)]
+        if tracked_ones:
+            return [_line("local", FAIL, "gitignore",
+                          f"git tracks {', '.join(tracked_ones)} — gitignore will "
+                          "not stop a commit. `git rm --cached` them, or use "
+                          "--scope user")]
+        return [_line("local", FAIL, "gitignore",
+                      f"{', '.join(live)} is not gitignored and would be committed. "
+                      "`gban setup` adds the lines")]
+    uncovered = [p for p in PROBES if not ignored(repo, p)]
+    if uncovered:
+        return [_line("local", UNKNOWN, "gitignore",
+                      "credential paths are not gitignored yet; `gban setup` adds "
+                      "the lines so a later spawn cannot commit them")]
+    return [_line("local", PASS, "gitignore", "credential paths are gitignored")]