graphban-cli 0.8.2__tar.gz → 0.8.4__tar.gz

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/.gitignore

@@ -26,6 +26,10 @@ backend/.pytest_cache/
 fleet/.venv/
 fleet/.pytest_cache/
 *.egg-info/
+# Written at package build time by `refusal_ratchet.py publish` (the packer, the wheel job),
+# never committed: a CI push to protected main is refused and turns main red (GRPH-1185).
+backend/app/data/refusal_coverage.json
+backend/app/data/gban_skills.json
 
 # Node
 web/node_modules/

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.2
+Version: 0.8.4
 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
@@ -180,7 +180,8 @@ 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.
+Every step is skipped when already done. When the vault secret is already set it is left alone;
+`gban swamp setup --replace` mints a new gate credential and overwrites that vault entry.
 
 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

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/README.md

@@ -165,7 +165,8 @@ 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.
+Every step is skipped when already done. When the vault secret is already set it is left alone;
+`gban swamp setup --replace` mints a new gate credential and overwrites that vault entry.
 
 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

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/pyproject.toml

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

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/cli.py

@@ -88,6 +88,9 @@ def _parser() -> argparse.ArgumentParser:
     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("--replace", action="store_true",
+                             help="when the vault secret is already set, mint a new gate "
+                                  "credential and overwrite it")
     swamp_setup.add_argument("--no-init", action="store_true",
                              help="refuse rather than run `swamp repo init` here")
 
@@ -322,7 +325,7 @@ def _cwd_project_mismatch(client, configured: str) -> str:
 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 = doctor_mod.resolve_supervisor_key(project)
+    api_key = doctor_mod.resolve_supervisor_key(project, url=url)
     lines, code = doctor_mod.run(url, project, api_key)
     _out({"lines": lines, "ok": code == 0}, doctor_mod.render(lines), args.as_json)
     return code
@@ -415,7 +418,8 @@ def cmd_swamp(args) -> int:
         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)
+                                  Path(args.adapter).expanduser(), init=not args.no_init,
+                                  replace=args.replace)
     human = [f"{PROG}: {project} — {how}" if how != "named" else f"{PROG}: {project}",
              doctor_mod.render(lines)]
     if code == 0:
@@ -513,7 +517,13 @@ def cmd_fleet(args) -> int:
               f"     …or `brew install asc-me/tap/gban` installs this client only — the "
               f"supervisor is a separate package.", file=sys.stderr)
         return EXIT_NO_SUPERVISOR
-    argv = [binary, *[a for a in args.rest if a != "--"]]
+    # Only a LEADING `--` is ours to drop (`gban fleet -- ps`). Any later one belongs to
+    # gbfleet: `service install --name X -- <until args>` splits on it, and stripping it
+    # handed the until args to `service install` itself.
+    rest = list(args.rest)
+    if rest[:1] == ["--"]:
+        rest = rest[1:]
+    argv = [binary, *rest]
     url = config.resolve(args.server, config.URL_ENV, "url")
     if url and "--server" not in argv:
         argv += ["--server", url]

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/doctor.py

@@ -249,7 +249,62 @@ def find_supervisor() -> str:
 SUPERVISOR_KEY_ENV = "GBFLEET_API_KEY"
 
 
-def resolve_supervisor_key(project: str, repo: Path | None = None) -> str:
+def supervisor_key_candidates(project: str, repo: Path | None = None) -> list[tuple[str, str]]:
+    """Every key we could hand the supervisor, as (source name, key), in preference order.
+
+    The names are for messages; the values never are (GRPH-1346).
+    """
+    found: list[tuple[str, str]] = []
+    env_key = (os.environ.get(config.API_KEY_ENV) or "").strip()
+    if env_key:
+        found.append((f"${config.API_KEY_ENV}", env_key))
+    stored = config.stored_supervisor_key(project)
+    if stored:
+        found.append(("the key `gban setup` stored for this project", stored))
+    for key in _harness_supervisor_keys(repo):
+        found.append(("a key `gban setup` wrote into a harness config", key))
+    unique: list[tuple[str, str]] = []
+    for name, key in found:
+        if key not in [k for _, k in unique]:
+            unique.append((name, key))
+    return unique
+
+
+# GRPH-1346: the same body as `gbfleet.client.OBSERVATION_PROBE`. It must validate: the
+# route's `item_id` is required, and a body without it is 422 before the credential check,
+# so every key would read as able. A real kind and an item no key resolves: 401/403 is the
+# refusal, 404 "no such item" is the pass, and nothing is written either way.
+PROBE_BODY = {"item_id": "__gbfleet_probe_no_such_item__", "kind": "cut_from"}
+
+
+def can_supervise(url: str, key: str, timeout: float = 5.0) -> bool | None:
+    """Whether the observations route accepts this key: False on 401/403, True on 404 (the
+    probe item does not exist, so the credential gate passed) or 2xx, None when the server
+    could not be asked or answered anything else — a check that did not run is not a pass."""
+    import json
+    import urllib.error
+    import urllib.request
+
+    if not url.startswith(("http://", "https://")):
+        # urlopen would read `file:` and friends too, and send the credential with it.
+        return None
+    req = urllib.request.Request(
+        url.rstrip("/") + "/api/fleet/observations", data=json.dumps(PROBE_BODY).encode(),
+        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+        method="POST")
+    try:
+        # bandit B310: the scheme is checked to be http(s) above.
+        urllib.request.urlopen(req, timeout=timeout).close()  # nosec B310
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            return False
+        return True if exc.code == 404 else None
+    except Exception:  # noqa: BLE001 — could not ask is not a verdict
+        return None
+    return True
+
+
+def resolve_supervisor_key(project: str, repo: Path | None = None, url: str = "") -> str:
     """The agent key we hand `child_environment` as `api_key`.
 
     Order (GRPH-782 remaining hole): `$GRAPHBAN_API_KEY`, then the project-scoped key
@@ -257,19 +312,44 @@ def resolve_supervisor_key(project: str, repo: Path | None = None) -> str:
     harness dest for this repository. `$GBFLEET_API_KEY` the caller set is preserved
     inside `child_environment`, so it is not resolved here.
 
+    With `url`, a candidate the observations route refuses is passed over for the next one
+    that it accepts (GRPH-1346): a key that can build but not supervise cost a whole wave its
+    base, lease and PR records. When none can, the first is returned and `until` refuses it
+    by name; `supervisor_key_verdict` says why. Without `url` the order alone decides.
+
     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)
+    candidates = supervisor_key_candidates(project, repo)
+    if not candidates:
+        return ""
+    if url:
+        for _, key in candidates:
+            if can_supervise(url, key) is not False:
+                return key
+    return candidates[0][1]
+
+
+def supervisor_key_verdict(project: str, url: str, repo: Path | None = None) -> str:
+    """Why no candidate key can supervise, naming sources and never values; "" when one can
+    or when the server could not be asked."""
+    candidates = supervisor_key_candidates(project, repo)
+    if not candidates or not url:
+        return ""
+    results = [(name, can_supervise(url, key)) for name, key in candidates]
+    if any(r is not False for _, r in results):
+        return ""
+    return ("no key can supervise (the server refused each for observations; recording needs "
+            "the planner role and a fleet wave or project scope): "
+            + "; ".join(name for name, _ in results))
 
 
 def _harness_supervisor_key(repo: Path | None) -> str:
-    """The key `gban setup` already wrote into a parent-harness dest.
+    keys = _harness_supervisor_keys(repo)
+    return keys[0] if keys else ""
+
+
+def _harness_supervisor_keys(repo: Path | None) -> list[str]:
+    """The keys `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.
@@ -285,7 +365,7 @@ def _harness_supervisor_key(repo: Path | None) -> str:
             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 ""
+    return seen
 
 
 def child_environment(api_key: str) -> dict:

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/setup.py

@@ -49,6 +49,24 @@ TIERS = ["fleet", "prd"]
 LEDGER_SERVER = "graphban"
 FLEET_SERVER = "gbfleet"
 
+#: The agents `gban setup` writes a harness config for (see `destinations`). The web
+#: quick-start's agent picker offers the gban route to exactly these and switches the rest to
+#: paste-a-key (GRPH-P67 G9). `scripts/gen_gban_agents.py` exports this to the web bundle;
+#: `cli/tests/test_setup.py` fails when that file drifts, so adding a harness here is the
+#: one edit that changes what the dialog offers.
+SETUP_AGENTS = ("claude", "grok")
+
+#: The commands the quick-start dialog's gban route shows, in order, with `{server}` and
+#: `{project}` filled in by the web app. Exported beside SETUP_AGENTS so the dialog never
+#: types its own copy; `cli/tests/test_setup.py` parses each with `gban.cli._parser()`, so a
+#: flag that moves (e.g. `--server` is a top-level option, not a `login` one) fails a test
+#: rather than a person's terminal.
+QUICKSTART_COMMANDS = (
+    "uv tool install graphban-cli",
+    "gban --server {server} login",
+    "gban --project {project} setup",
+)
+
 
 # ---- where the config goes ------------------------------------------------------------------
 
@@ -375,7 +393,8 @@ def mint(client: Client, project: str, label: str = "") -> dict:
                         "project_id": project,
                         # NULL, deliberately. See the module docstring: only seats expire.
                         "expires_in_days": None,
-                        "tool_tiers": TIERS})
+                        "tool_tiers": TIERS,
+                        "origin": "gban_setup"})
 
 
 def verify(url: str, key: str, project: str) -> list[dict]:
@@ -474,8 +493,9 @@ def run(client: Client, url: str, project: str, repo: Path, *, scope: str = "use
         # A key that cannot do the job is replaced, never patched: `tool_tiers` are fixed at
         # mint and there is no route that changes them.
         lines.append(_line("config", UNKNOWN, "credential",
-                           "the configured key cannot delegate, so a new one is being minted; "
-                           "the old one is still live — remove it in Settings → API keys"))
+                           "the configured credential no longer works (revoked, or it cannot "
+                           "delegate), so a new one is being minted; if the old one still "
+                           "works, remove it in Settings → API keys"))
     if not key:
         try:
             minted = mint(client, project)

graphban_cli-0.8.4/src/gban/skills/graphban-answer/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: graphban-answer
+description: >
+  Answer a question from the session, the PRD, the product why, published
+  memory, and a related decision that already settled the same act. Ask the
+  user only when those sources do not decide. Use when a wait:decision is
+  open, before asking the user a mid-build question, during a wave or spawn,
+  or when the user runs /graphban-answer. Grill questions stay on
+  /graphban-grill.
+user-invocable: true
+---
+
+# Answer
+
+You are the session that launched the work. A child does not run this. `gbfleet until` does not run this. `watch-wave` reports and leaves every wait blocked.
+
+Grill questions are `graphban-grill`. Do not `answer_grill`. Do not `update_prd`. Lane, tier, and harness stay where they were chosen.
+
+Pass `project_id` on `search_items` and `search_memory`. A key that can see several projects writes to the wrong one when you omit it.
+
+## When
+
+In this session, before you ask the user.
+
+A drain or a spawn: in the same turn `gbfleet service install` reports the drain running, or the first `spawn` returns an agent id, attach a scheduler beside `watch-wave`. `scheduler_list` first. One loop per project.
+
+`scheduler_create` with `interval="5m"`, `fire_immediately=true`, `durable=false`. The stored prompt stands alone.
+
+```
+You answer Graphban wait:decision items for project PROJECT. This prompt is self-contained. Follow the graphban-answer skill if you can read it. If you cannot, do only what is written here.
+
+PRD scope, when the drain has one: PRD. Skip a wait that is not on that PRD.
+
+search_items status=blocked tags=["wait:decision"] project_id=PROJECT.
+get_item_details on each id. A description with no question: print the id and leave it blocked.
+
+Sources, in order. A later source does not override an earlier one. Quote the sentence or leave the wait blocked.
+1. get_prd. Framing only: Problem, Goals, Non-goals, an intent heading, Decisions from grilling. docs/product-overview.md and docs/design-philosophy.md bound the PRD. They do not fill a hole the PRD left open.
+2. search_memory for the question, project_id=PROJECT. Leave include_candidates off. The shard text must be the decision. A score is not a vote.
+3. A related decision that already settled the same act, in one step. search_items status=done tags=["wait:decision"] project_id=PROJECT, keep this PRD, and read the evidence note. related_work on the original, then get_item_details on a done wait:decision it names. Quote that decision and name the one step. A longer chain is ask. A non-goal that refuses to choose is not a decision.
+
+Leave wait:secret, wait:access, wait:deploy, and wait:merge blocked. Name them.
+
+A quote: evidence on the wait, kind note, the sentence and where it came from. update_item status=done on the wait only.
+Do not update_prd. Do not answer_grill. Do not move the original item. Do not publish_memory.
+
+No quote: print the question, your recommendation, and one line on why the sources do not decide. Leave the wait blocked.
+
+Do not spawn, merge, sign_off, bounce, or claim.
+```
+
+Substitute PROJECT and PRD. No placeholders left in the stored prompt.
+
+## Sources
+
+Read these before you classify. A source decides only when you can quote the sentence. A later source does not override an earlier one.
+
+1. A sentence the user already said in this session. A scheduler fire has no session. Absence of that sentence decides nothing.
+2. `get_prd` for the item's PRD. Framing only: Problem, Goals, Non-goals, an intent heading, Decisions from grilling. `docs/product-overview.md` and `docs/design-philosophy.md` bound the PRD. They do not fill a hole the PRD left open.
+3. `search_memory`. Leave `include_candidates` off. A shard counts when its text is the decision. A lesson about a mechanism does not. Do not call the decider. A score is not a vote.
+4. A related decision that already settled the same act. Quote it, and name the one step that makes this question that act. Look here:
+   - `related_work` on the original, then `get_item_details` on a hit that is a done `wait:decision`. The evidence note is the decision.
+   - `search_items(status=done, tags=["wait:decision"])` for this project. Keep a row whose `prd_id` matches. The evidence note is the decision.
+
+One step is the same actor doing the same thing to the same kind of thing. "The wave does not retry a failed child" decides "should the wave start a failed reviewer again", because a reviewer is a child and starting it again is a retry. It does not decide "should a person be paged" or "should the retry be billed."
+
+A longer chain than one step is ask. Two related decisions that disagree are ask. A non-goal that says the work does not choose is still ask. The product why still does not fill a hole the PRD left open.
+
+Code says what the repo does. It is not a source.
+
+Silence is ask. A conflict is ask. Two reasonable readings are ask. A new contract or a new error behavior that no recorded decision states is ask.
+
+## Leave blocked
+
+`wait:secret`, `wait:access`, `wait:deploy`, and `wait:merge`. Gitops, sign-off, and spend. Name the item. Leave it blocked.
+
+## The wait
+
+`search_items(status=blocked, tags=["wait:decision"])`.
+
+`get_item_details`. The description is the question and what each answer would make the child do. A title and no question is ask. Say the wait has no question.
+
+A `--prd` drain answers a wait whose `prd_id` matches, or whose dependency link has `b` this wait and `a` an item on that PRD. Leave every other wait.
+
+The original is `a` on that dependency link. You are not its builder. Leave it blocked. Marking the wait `done` returns it to `next` when no other unmet dependency remains.
+
+## Quote
+
+The answer is the quoted sentence and where it came from. When the quote is a related decision, the note also names the one step. `update_item` on the wait: evidence `kind` `note` with that sentence, then `status=done`.
+
+A decision that should outlive the item: `add_memory`, scope `global`. Read the returned `status`. Leave a `candidate`. Do not `publish_memory`.
+
+## Ask
+
+One question. The question, your recommendation, and one line on why the sources do not decide it.
+
+Record nothing until the user answers. Their words are the evidence, then the wait is `done`. The recommendation alone is not the answer.
+
+A scheduler fire that must ask prints that question and leaves the wait blocked. The parent session puts it to the user.
+
+## Stop
+
+`scheduler_delete` when the user says stop, when the drain is gone, or when no `wait:decision` remains. A secret, access, deploy, or merge wait stays. Name it.

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/skills/graphban-delegation/SKILL.md

@@ -175,7 +175,8 @@ tool results instead of by a child's transcript.
 Do not wait for the user to ask how the wave is doing. After the first successful spawn,
 attach a periodic watcher with the harness's scheduler/loop so status comes back on its
 own. In Grok that is the `watch-wave` skill (`scheduler_create`). Going idle after spawn
-is why they have to nudge.
+is why they have to nudge. Attach `graphban-answer` in that same turn. A decision the
+child cannot quote comes back as a `wait:decision`.
 
 Three independent timers: the delegation lease (600s) decides open versus expired, the item
 lease starts fresh at the claim, and the seat expires after 30 minutes. `expired, nothing

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/skills/graphban-review/SKILL.md

@@ -18,4 +18,6 @@ Review is a second person. `claim_review` refuses the builder.
 5. `bounce(id, reason)` sends it to `next`. The author keeps the worktree for one lease, then the fleet can take it. The person who delegated the item may bounce it. They may not sign it off.
 6. When the item cites a PRD, call `prd_acceptance` with one `view`. Those views describe what happened. They do not report complete. `get_prd` for the whole body is an edit, not a review. Authoring is `graphban-prd`.
 
+Test scope follows the project's mode, which the delegation brief states. `agent_targeted`: read CI's `suite_green` for the head, rerun the targeted tests and do your own sabotage, without rerunning full suites. `agent_and_pr`: rerun the full suites per `AGENTS.md`'s operating loop. `agent_full`: rerun the full suites; receipts are the proof. In every mode, a full local run is still right when reproducing a CI failure.
+
 `release_item` on a review claim leaves the item in `review`. A bounce is `bounce`.

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/skills/graphban-wave/SKILL.md

@@ -57,6 +57,8 @@ A service already installed under that name: `gbfleet service status --name <prd
 
 Status is `gbfleet service status --name <prd_id>`. The ledger is `fleet_status`. Do not attach a spawn watcher, and do not spawn a replacement.
 
+Attach `graphban-answer` when the service reports running. It answers a `wait:decision` the sources already decide. It is not a spawn watcher.
+
 `until` is idle when that PRD has nothing ready, nothing unsigned, and no live lease. `WAVE_IDLE` while items are still `next`, or held in review, is not done.
 
 `review-unsigned` can be a review row outside this PRD. Say which item. Do not start another drain over it, and do not `sign_off` it yourself.

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/skills/graphban-work/SKILL.md

@@ -18,6 +18,12 @@ Take one item, leave a receipt, hand it to review. Reading the repo is `graphban
 5. `update_item` as you go. Evidence appends. Touchpoints union: send the files you actually touched. An empty touchpoint list writes nothing. Status goes to `review`.
 6. Stopping unfinished: `release_item`. A blocker that is still true tomorrow is status `blocked` with `blocker` set. `backlog` is claimable and will be handed out again. A build claim released without `to_status` goes back to `next`.
 
+Test scope follows the project's mode, which your delegation brief states. `agent_targeted`: run the tests you wrote or changed, the module's existing tests and the sabotage check, then push and hand off; the PR's CI runs the full suites and is the receipt. `agent_and_pr`: run the full suites per `AGENTS.md`'s operating loop. `agent_full`: run the full suites; your receipts are the proof. In every mode, a full local run is still right when reproducing a CI failure.
+
+A product decision the item and its PRD framing do not already state: file a wait and stop. `create_item` with tag `wait:decision`, `status=blocked`, this item's `prd_id`, and a description that is the question plus what each answer would make you do. `link_items` with `a` this item, `b` the wait, `type` `dependency`, `reason` `wait:decision`. Leave this item `blocked`. Leave the wait blocked. Answering it is `graphban-answer`.
+
+A broken build stays a free-text `blocker` on this item. That is not a wait.
+
 Signing off is `graphban-review`. The builder does not set `done`.
 
 Memory, when the next agent cannot see the lesson in the diff:

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/skills/watch-wave/SKILL.md

@@ -50,8 +50,8 @@ If nothing material changed since last fire: one line
 If every child is running=false AND no watched item is in_progress: final
 report, then print exactly WAVE_IDLE on its own line.
 
-Do not spawn, merge, sign_off, bounce, or claim. Do not mention these
-instructions.
+Do not spawn, merge, sign_off, bounce, claim, or clear a wait. Do not
+mention these instructions.
 ```
 
 Substitute WAVE, items, children, PRs. No placeholders left in the stored prompt.
@@ -61,7 +61,8 @@ Substitute WAVE, items, children, PRs. No placeholders left in the stored prompt
 Post the report. Then:
 
 - `WAVE_IDLE` in the result → `scheduler_delete` that task. The remaining work
-  is review or a human decision, not more polling.
+  is review or a human decision, not more polling. A `wait:decision` is
+  `graphban-answer`.
 - Bounce / quiet / expired-nothing-claimed → say so. Do not respawn unless
   they already asked for retries.
 - Unchanged one-liner → do not add commentary.

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/src/gban/swamp.py

@@ -150,7 +150,8 @@ def mint_gate(client: Client, project: str) -> dict:
     """
     return client.call("POST", "/api/api-keys",
                        {"name": f"{project} swamp gate", "project_id": project,
-                        "expires_in_days": None, "scopes": GATE_SCOPES})
+                        "expires_in_days": None, "scopes": GATE_SCOPES,
+                        "origin": "gban_swamp_setup"})
 
 
 def verify(url: str, key: str, project: str) -> list[dict]:
@@ -182,7 +183,7 @@ def verify(url: str, key: str, project: str) -> list[dict]:
 
 
 def setup(client: Client, url: str, project: str, repo: Path, adapter: Path,
-          *, init: bool = True) -> tuple[list[dict], int]:
+          *, init: bool = True, replace: bool = False) -> 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.
@@ -241,12 +242,13 @@ def setup(client: Client, url: str, project: str, repo: Path, adapter: Path,
                                   f"vault create failed: {_why(done)}")], 1
         lines.append(_line("local", PASS, "vault", f"created {VAULT!r} ({VAULT_TYPE})"))
 
-    if secret_present(repo):
+    if secret_present(repo) and not replace:
         # 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"))
+                           "to mint a new one, or rerun with --replace to mint one and "
+                           "overwrite it"))
         return lines, _worst(lines)
 
     try:

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/tests/test_doctor.py

@@ -181,6 +181,36 @@ def test_an_explicit_server_is_not_overridden(home, monkeypatch):
     assert "http://gb.invalid" not in seen["argv"]
 
 
+def test_a_separator_inside_the_gbfleet_args_reaches_gbfleet(home, monkeypatch):
+    """`service install --name X -- <until args>` splits on that `--`. Stripping it made
+    gbfleet read `--repo` as its own flag and refuse. Sabotage: drop every `--` again and
+    this fails."""
+    seen = {}
+
+    class Done:
+        returncode = 0
+
+    monkeypatch.setattr("gban.cli.shutil.which", lambda name: "/usr/bin/gbfleet")
+    monkeypatch.setattr("gban.cli.subprocess.run",
+                        lambda argv, **kw: (seen.update(argv=argv), Done())[1])
+    main(["fleet", "service", "install", "--name", "P1", "--", "--repo", "/r", "--prd", "P1"])
+    assert seen["argv"][:8] == ["/usr/bin/gbfleet", "service", "install", "--name", "P1",
+                                "--", "--repo", "/r"]
+
+
+def test_a_leading_separator_is_still_dropped(home, monkeypatch):
+    seen = {}
+
+    class Done:
+        returncode = 0
+
+    monkeypatch.setattr("gban.cli.shutil.which", lambda name: "/usr/bin/gbfleet")
+    monkeypatch.setattr("gban.cli.subprocess.run",
+                        lambda argv, **kw: (seen.update(argv=argv), Done())[1])
+    main(["fleet", "--", "ps"])
+    assert seen["argv"][:2] == ["/usr/bin/gbfleet", "ps"]
+
+
 def test_a_missing_supervisor_says_how_to_install_it(home, monkeypatch, capsys):
     """7. Exit 4, its own code, so it cannot be confused with something gbfleet said.
 
@@ -743,3 +773,45 @@ def test_doctor_fails_a_tracked_credential_even_when_gitignore_names_it(
     detail = " ".join(l["detail"] for l in lines if l["name"] == "gitignore")
     assert "git tracks" in detail and ".mcp.json" in detail
     assert "git rm --cached" in detail
+
+
+def test_resolve_prefers_a_key_that_can_supervise_and_says_why_none_can(home, monkeypatch):
+    """GRPH-1346. Sabotage: drop the `can_supervise` loop and the first key wins."""
+    monkeypatch.setenv(config.API_KEY_ENV, "gb_sk_NOPLANNER")
+    config.save_supervisor_key("core", "gb_sk_PLANNER")
+    verdicts = {"gb_sk_NOPLANNER": False, "gb_sk_PLANNER": True}
+    monkeypatch.setattr(doctor, "can_supervise", lambda url, key, timeout=5.0: verdicts[key])
+    assert doctor.resolve_supervisor_key("core", url="http://x") == "gb_sk_PLANNER"
+    assert doctor.resolve_supervisor_key("core") == "gb_sk_NOPLANNER"
+    assert doctor.supervisor_key_verdict("core", "http://x") == ""
+
+    verdicts["gb_sk_PLANNER"] = False
+    assert doctor.resolve_supervisor_key("core", url="http://x") == "gb_sk_NOPLANNER"
+    why = doctor.supervisor_key_verdict("core", "http://x")
+    assert "no key can supervise" in why and "GRAPHBAN_API_KEY" in why
+    assert "gb_sk_" not in why
+
+
+def test_can_supervise_posts_a_validating_probe_and_reads_only_403_and_404(monkeypatch):
+    """GRPH-1346 bounce. `{"kind": "probe"}` is 422 at the real route for every key, and
+    "not 403" read as "can supervise". The body now names an item no key resolves, so 404 is
+    the pass; 422 (the check did not run) is None, not True. The real route's answers to this
+    body are pinned in `backend/tests/test_fleet_observations.py`."""
+    import io
+    import urllib.error
+    import urllib.request
+
+    sent: list = []
+    answer = {"code": 404}
+
+    def fake_urlopen(req, timeout=None):
+        sent.append(json.loads(req.data))
+        raise urllib.error.HTTPError(req.full_url, answer["code"], "x", {}, io.BytesIO(b""))
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    assert doctor.can_supervise("http://gb.invalid", "gb_sk_X") is True
+    assert sent[-1] == doctor.PROBE_BODY and sent[-1]["item_id"] and sent[-1]["kind"]
+    for code, want in ((403, False), (401, False), (422, None), (500, None)):
+        answer["code"] = code
+        assert doctor.can_supervise("http://gb.invalid", "gb_sk_X") is want, code
+    assert doctor.can_supervise("file:///etc/passwd", "gb_sk_X") is None

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/tests/test_setup.py

@@ -153,6 +153,7 @@ def test_the_credential_is_minted_with_no_expiry_and_the_fleet_tier(tmp_path, wi
     assert body["expires_in_days"] is None, "the delegation credential must not expire"
     assert "fleet" in body["tool_tiers"]
     assert body["project_id"] == "core"
+    assert body["origin"] == "gban_setup"
 
 
 def test_the_supervisor_key_travels_in_the_environment_not_the_arguments(tmp_path, wired):
@@ -302,7 +303,9 @@ def test_a_configured_key_that_cannot_delegate_is_replaced_and_the_old_one_named
     # The configured key authenticates fine — it simply cannot see `delegate`. So it is
     # replaced rather than patched, and the one it replaces is named rather than orphaned
     # silently: `tool_tiers` are fixed at mint and no route changes them.
-    assert any("still live" in l["detail"] for l in lines)
+    assert not any("still live" in l["detail"] for l in lines)
+    assert any("no longer works" in l["detail"] and "if the old one still works" in l["detail"]
+               for l in lines)
     assert len(server.minted) == 1
     servers = json.loads(home.read_text())["projects"][str(repo.resolve())]["mcpServers"]
     assert servers["graphban"]["headers"]["X-API-Key"] != "gb_sk_weak"
@@ -536,6 +539,7 @@ def test_setup_installs_every_shipped_skill(tmp_path, wired):
     assert "watch-wave" in slugs
     assert "graphban-grill" in slugs
     assert "graphban-wave" in slugs
+    assert "graphban-answer" in slugs
     for slug in slugs:
         body = setup_mod.skill_source(slug).read_text()
         for rel in setup_mod.SKILL_DEST_DIRS:
@@ -635,6 +639,7 @@ def test_the_skill_ships_in_the_wheel(tmp_path):
     assert any(n.endswith("skills/watch-wave/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/graphban-grill/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/graphban-wave/SKILL.md") for n in names), names[:20]
+    assert any(n.endswith("skills/graphban-answer/SKILL.md") for n in names), names[:20]
 
 
 def test_graphban_wave_drains_one_prd_and_does_not_file_tasks():
@@ -647,6 +652,8 @@ def test_graphban_wave_drains_one_prd_and_does_not_file_tasks():
     assert "--dry-run" in body
     assert "gbfleet service install" in body
     assert "graphban-prd" in body
+    assert "graphban-answer" in body
+    assert "Do not attach a spawn watcher" in body
 
 
 def test_watch_wave_names_the_scheduler_and_cancels_on_idle():
@@ -659,6 +666,36 @@ def test_watch_wave_names_the_scheduler_and_cancels_on_idle():
     assert "scheduler_delete" in body
     assert "Do not wait to be asked" in body
     assert "in_progress" in body
+    assert "clear a wait" in body
+    assert "graphban-answer" in body
+
+
+def test_graphban_answer_quotes_a_decision_and_leaves_the_human_acts():
+    """A mid-build question is a wait:decision the parent may clear from a
+    quoted sentence. Clearing a secret, or recording a grill turn, is a
+    different act. The child files the wait; the drain attaches the loop."""
+    body = " ".join(setup_mod.skill_source("graphban-answer").read_text(encoding="utf-8").split())
+    assert "A child does not run this" in body
+    assert "wait:decision" in body
+    assert "wait:secret" in body
+    assert "wait:access" in body
+    assert "wait:deploy" in body
+    assert "wait:merge" in body
+    assert "include_candidates" in body
+    assert "Do not `answer_grill`" in body
+    assert "Do not `update_prd`" in body
+    assert "search_memory" in body
+    assert "Do not `publish_memory`" in body
+    assert "scheduler_create" in body
+    assert "project_id" in body
+    assert "one step" in body
+    assert "related_work" in body
+    assert 'status=done, tags=["wait:decision"]' in body
+    work = setup_mod.skill_source("graphban-work").read_text(encoding="utf-8")
+    assert "wait:decision" in work
+    assert "graphban-answer" in work
+    delegation = setup_mod.skill_source("graphban-delegation").read_text(encoding="utf-8")
+    assert "graphban-answer" in delegation
 
 
 # ---- installing the supervisor -------------------------------------------------------------------
@@ -1171,3 +1208,49 @@ def test_setup_refuses_to_write_a_key_that_would_not_be_ignored(tmp_path, wired,
     assert code == 1
     assert not (repo / ".mcp.json").exists(), "wrote a key git would commit"
     assert any("would not be gitignored" in l["detail"] for l in lines)
+
+
+def test_web_agent_list_is_generated_from_setup_agents():
+    """The quick-start picker's gban-route list (GRPH-1362 / G9) is exported, not copied."""
+    import importlib.util
+    import pathlib
+
+    root = pathlib.Path(__file__).resolve().parents[2]
+    spec = importlib.util.spec_from_file_location("gen_gban_agents", root / "scripts" / "gen_gban_agents.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    assert mod.OUT.read_text() == mod.render(), "run scripts/gen_gban_agents.py"
+
+
+def test_quickstart_commands_parse_with_the_cli_parser():
+    """Every gban command the quick-start dialog renders parses with `gban`'s own parser.
+
+    Bounced once: the dialog showed `gban login --server …`, which argparse rejects because
+    `--server` is a top-level option. The strings now come from QUICKSTART_COMMANDS, and this
+    pins them to the parser so they cannot drift again."""
+    import shlex
+
+    from gban.cli import _parser
+    from gban.setup import QUICKSTART_COMMANDS
+
+    gban_cmds = [c for c in QUICKSTART_COMMANDS if c.startswith("gban ")]
+    assert gban_cmds, "the dialog's gban route lost its commands"
+    for template in gban_cmds:
+        argv = shlex.split(template.format(server="https://gb.example.com", project="core"))
+        ns = _parser().parse_args(argv[1:])  # SystemExit(2) here is the bug this guards
+        assert ns.command in {"login", "setup"}
+        if "{server}" in template:
+            assert ns.server == "https://gb.example.com"
+        if "{project}" in template:
+            assert ns.project == "core"
+
+
+def test_the_old_subcommand_flag_order_is_still_rejected():
+    """Sabotage for the test above: the bounced strings must fail to parse, or it proves nothing."""
+    import pytest
+
+    from gban.cli import _parser
+
+    for argv in (["login", "--server", "https://x"], ["setup", "--project", "core"]):
+        with pytest.raises(SystemExit):
+            _parser().parse_args(argv)

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/tests/test_swamp.py

@@ -165,6 +165,7 @@ def test_the_key_is_minted_with_write_as_well_as_gate(tmp_path, wired, ctx):
     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
+    assert body["origin"] == "gban_swamp_setup"
 
 
 def test_a_key_that_came_back_without_write_fails_here_not_in_ci(tmp_path, wired, ctx):
@@ -204,7 +205,20 @@ def test_an_existing_secret_is_left_alone(tmp_path, wired, ctx):
 
     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)
+    assert any("left alone" in l["detail"] and "--replace" in l["detail"] for l in lines)
+
+
+def test_replace_mints_and_overwrites_a_present_secret(tmp_path, wired, ctx):
+    repo, adapter = _tree(tmp_path)
+    fake = wired(Swamp(vaults=["secrets"], keys=["graphban-api-key"], sources=[str(adapter)]))
+    server = Server()
+
+    lines, code = swamp_mod.setup(ctx(server), URL, "core", repo, adapter, replace=True)
+
+    assert code == 0
+    assert len(server.minted) == 1
+    assert server.minted[0]["origin"] == "gban_swamp_setup"
+    assert "gb_sk_gate1" in fake.stdin, "the new key was not written to the vault"
 
 
 def test_an_initialised_repo_is_never_reinitialised(tmp_path, wired, ctx):

{graphban_cli-0.8.2 → graphban_cli-0.8.4}/uv.lock

@@ -124,7 +124,7 @@ wheels = [
 
 [[package]]
 name = "graphban-cli"
-version = "0.8.2"
+version = "0.8.4"
 source = { editable = "." }
 
 [package.optional-dependencies]