graphban-cli 0.8.3__tar.gz → 0.8.5__tar.gz

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.3
+Version: 0.8.5
 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
@@ -87,6 +87,7 @@ Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/do
 ```bash
 gban login --server https://cloud.agentldgr.dev
 gban doctor                       # both halves: the ledger, and the local fleet
+                                  # (also reports the result to the server; --no-report opts out)
 gban agents                       # the roster, and why an agent is stuck
 gban agents role SA-A4 planner    # what used to need a browser
 gban seats issue worker worker planner                  # one entry per agent
@@ -171,6 +172,15 @@ Three properties worth knowing, each of which is a bug this command exists to no
   committed. It asks git (`check-ignore`), so an equivalent pattern already in the
   file is left alone.
 
+## Machine reports
+
+`gban setup` and `gban doctor` send the server a report of their PASS/FAIL/UNKNOWN lines, tagged
+with a random machine id kept in `~/.graphban/machine.json` (delete it and you are a new
+machine). A report whose every line is PASS turns the dashboard's "Connect your agent" step ✓ (an UNKNOWN is never a pass); the list is
+under Settings → Machines. Pass `--no-report` to skip it. When the report cannot be delivered,
+the command prints `UNKNOWN report could not report to <server>: <reason>` and still exits on
+its own checks — an undelivered report never counts as proof.
+
 ## Wiring a checkout to Swamp
 
 ```bash
@@ -180,7 +190,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
@@ -220,7 +231,7 @@ A real post needs a git commit (there is nothing to send for a repo with no HEAD
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**
 read when it cannot turn echo off — it warns, but the warning arrives after the person has
 decided to type — so a login through a pipe, a heredoc or an editor's command runner would
-put the password in the scrollback. There is no non-interactive login yet (PRD-40 open
+put the password in the scrollback. `gban login --pair` is the alternative with no password prompt: it prints a short code, and a person signed in to the web app approves it in the quick-start dialog (step ③). The session you get is the approver's, and the code is single-use and expires after 10 minutes. There is no unattended login yet (PRD-40 open
 question 2: an API key cannot reach the JWT routes, so CI would need a service session).
 
 ## Why not `gb`

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/README.md

@@ -72,6 +72,7 @@ Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/do
 ```bash
 gban login --server https://cloud.agentldgr.dev
 gban doctor                       # both halves: the ledger, and the local fleet
+                                  # (also reports the result to the server; --no-report opts out)
 gban agents                       # the roster, and why an agent is stuck
 gban agents role SA-A4 planner    # what used to need a browser
 gban seats issue worker worker planner                  # one entry per agent
@@ -156,6 +157,15 @@ Three properties worth knowing, each of which is a bug this command exists to no
   committed. It asks git (`check-ignore`), so an equivalent pattern already in the
   file is left alone.
 
+## Machine reports
+
+`gban setup` and `gban doctor` send the server a report of their PASS/FAIL/UNKNOWN lines, tagged
+with a random machine id kept in `~/.graphban/machine.json` (delete it and you are a new
+machine). A report whose every line is PASS turns the dashboard's "Connect your agent" step ✓ (an UNKNOWN is never a pass); the list is
+under Settings → Machines. Pass `--no-report` to skip it. When the report cannot be delivered,
+the command prints `UNKNOWN report could not report to <server>: <reason>` and still exits on
+its own checks — an undelivered report never counts as proof.
+
 ## Wiring a checkout to Swamp
 
 ```bash
@@ -165,7 +175,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
@@ -205,7 +216,7 @@ A real post needs a git commit (there is nothing to send for a repo with no HEAD
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**
 read when it cannot turn echo off — it warns, but the warning arrives after the person has
 decided to type — so a login through a pipe, a heredoc or an editor's command runner would
-put the password in the scrollback. There is no non-interactive login yet (PRD-40 open
+put the password in the scrollback. `gban login --pair` is the alternative with no password prompt: it prints a short code, and a person signed in to the web app approves it in the quick-start dialog (step ③). The session you get is the approver's, and the code is single-use and expires after 10 minutes. There is no unattended login yet (PRD-40 open
 question 2: an API key cannot reach the JWT routes, so CI would need a service session).
 
 ## Why not `gb`

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/pyproject.toml

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

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/src/gban/cli.py

@@ -13,12 +13,14 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 
-from gban import config, doctor as doctor_mod, setup as setup_mod, stackmap, swamp as swamp_mod
+from gban import config, doctor as doctor_mod, machine as machine_mod, setup as setup_mod, stackmap, swamp as swamp_mod
 from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
                        Client, NoSession,
-                       Refused, Unreachable, authenticated, login)
+                       Refused, Unreachable, authenticated, login, pair_poll,
+                       pair_start)
 
 PROG = "gban"
 
@@ -44,14 +46,20 @@ def _parser() -> argparse.ArgumentParser:
                      "written to session.json at mode 600; the access token is never stored, "
                      "because it is renewed on every invocation anyway."))
     login_cmd.add_argument("--email", default=None)
+    login_cmd.add_argument(
+        "--pair", action="store_true",
+        help=("sign in without typing a password here: prints a short code that a signed-in "
+              "person approves in the web app's quick-start dialog"))
 
     sub.add_parser("logout", help="end the session, here and on the server")
-    sub.add_parser(
+    doctor_cmd = sub.add_parser(
         "doctor", help="check both halves: the ledger, and the local fleet",
         description=("Everything that can be checked before anything is spawned. The ledger "
                      "half runs here; the local half is `gbfleet doctor`, run as a subprocess. "
                      "Neither half silences the other: what could not be checked prints "
                      "UNKNOWN with its reason, never a pass."))
+    doctor_cmd.add_argument("--no-report", action="store_true",
+                            help="do not send the result to the server (Settings → Machines)")
 
     setup_cmd = sub.add_parser(
         "setup", help="enable delegation on a project",
@@ -75,6 +83,8 @@ def _parser() -> argparse.ArgumentParser:
              "lookup")
     setup_cmd.add_argument("--no-install", action="store_true",
                            help="do not install the supervisor")
+    setup_cmd.add_argument("--no-report", action="store_true",
+                           help="do not send the result to the server (Settings → Machines)")
 
     swamp_cmd = sub.add_parser(
         "swamp", help="wire this checkout to Swamp's Graphban adapter",
@@ -88,6 +98,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")
 
@@ -180,6 +193,8 @@ def _server(args) -> str:
 
 def cmd_login(args) -> int:
     url = _server(args)
+    if args.pair:
+        return _login_pair(args, url)
     # A TERMINAL, OR NOTHING. `getpass` falls back to a plain echoing read when it cannot
     # turn echo off, and warns about it — which is the wrong trade for a password: the
     # warning arrives after the person has already decided to type. Without a tty the
@@ -202,7 +217,38 @@ def cmd_login(args) -> int:
         # same rule criterion 4 applies to an expired session applies to a cancelled login.
         print(f"\n{PROG}: cancelled", file=sys.stderr)
         return EXIT_REFUSED
-    pair = login(url, email, password)
+    return _finish_login(args, url, email, login(url, email, password))
+
+
+def _login_pair(args, url: str) -> int:
+    """Device-code sign-in (GRPH-1366): the identity is whoever approves the code in the app."""
+    started = pair_start(url)
+    code = started.get("user_code") or ""
+    print(f"{PROG}: open the quick-start dialog in {url} (step 3) and enter this code:\n\n"
+          f"       {code}\n\n     waiting for approval (expires in "
+          f"{int(started.get('expires_in', 0)) // 60} min)…", file=sys.stderr)
+    deadline = time.monotonic() + float(started.get("expires_in", 600))
+    interval = max(float(started.get("interval", 3)), 0.0)
+    try:
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            try:
+                got = pair_poll(url, started.get("device_code", ""))
+            except Refused:
+                print(f"{PROG}: the code expired or was already used. Run `{PROG} login --pair` "
+                      f"again.", file=sys.stderr)
+                return EXIT_REFUSED
+            if got.get("status") == "approved":
+                return _finish_login(args, url, got.get("email") or "", got)
+    except KeyboardInterrupt:
+        print(f"\n{PROG}: cancelled", file=sys.stderr)
+        return EXIT_REFUSED
+    print(f"{PROG}: the code expired before anyone approved it. Run `{PROG} login --pair` "
+          f"again.", file=sys.stderr)
+    return EXIT_REFUSED
+
+
+def _finish_login(args, url: str, email: str, pair: dict) -> int:
     refresh = pair.get("refresh_token") or ""
     if not refresh:
         print(f"{PROG}: the server returned no refresh token", file=sys.stderr)
@@ -322,8 +368,10 @@ 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)
+    if not getattr(args, "no_report", False):
+        lines += machine_mod.send(url, project, lines)  # UNKNOWN when undelivered: exit unchanged
     _out({"lines": lines, "ok": code == 0}, doctor_mod.render(lines), args.as_json)
     return code
 
@@ -351,6 +399,8 @@ def cmd_setup(args) -> int:
         return EXIT_REFUSED
     lines, code, made = setup_mod.run(client, url, project, Path.cwd(), scope=args.scope,
                                       install=not args.no_install)
+    if not args.no_report:
+        lines += machine_mod.send(url, project, lines)
     human = [doctor_mod.render(lines)]
     if how != "named":
         human.insert(0, f"{PROG}: {project} — {how}")
@@ -385,6 +435,8 @@ def _setup_auto(args, url: str, client) -> int:
         got, code, made = setup_mod.run(client, url, pid, repo, scope=args.scope,
                                         install=not args.no_install)
         lines += [{**l, "name": f"{pid}: {l['name']}"} for l in got]
+        if not args.no_report:
+            lines += [{**l, "name": f"{pid}: {l['name']}"} for l in machine_mod.send(url, pid, got)]
         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. "
@@ -415,7 +467,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:

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/src/gban/client.py

@@ -135,6 +135,15 @@ def login(url: str, email: str, password: str) -> dict:
                             {"email": email, "password": password})
 
 
+def pair_start(url: str) -> dict:
+    """Begin a device-code sign-in: no password, no credential yet (GRPH-1366)."""
+    return Client(url).call("POST", "/api/cli/pair")
+
+
+def pair_poll(url: str, device_code: str) -> dict:
+    return Client(url).call("POST", "/api/cli/pair/token", {"device_code": device_code})
+
+
 def authenticated(url: str, *, act: str = "") -> Client:
     """A client for this invocation: one refresh exchange, access token held in memory.
 

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/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.5/src/gban/machine.py

@@ -0,0 +1,91 @@
+"""Machine identity and the report `gban setup` / `gban doctor` send (GRPH-1442).
+
+The machine id is random and lives in `machine.json` in gban's home. Wiping that directory makes
+a new machine, which is the intent: the id names an installation, not a person or a label.
+
+A report that cannot be delivered NEVER counts. It comes back as an UNKNOWN line naming the
+server and the reason, and the caller still exits on its own checks.
+"""
+from __future__ import annotations
+
+import platform
+import shutil
+import socket
+import subprocess  # nosec B404 - fixed argv, no shell
+import uuid
+from importlib import metadata
+
+from gban import config
+from gban.client import NoSession, Refused, Unreachable, authenticated
+from gban.doctor import UNKNOWN, _line
+
+MACHINE_FILE = "machine.json"
+
+
+def machine_id() -> str:
+    """The stored id, minted on first use. An unwritable home still yields a (volatile) id."""
+    path = config.home() / MACHINE_FILE
+    existing = config._read(path).get("machine_id")
+    if isinstance(existing, str) and existing:
+        return existing
+    fresh = "gbm_" + uuid.uuid4().hex
+    try:
+        config._write(path, {"machine_id": fresh})
+    except OSError:
+        pass
+    return fresh
+
+
+def _version(dist: str) -> str:
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return ""
+
+
+def _gbfleet_version() -> str:
+    exe = shutil.which("gbfleet")
+    if not exe:
+        return ""
+    try:
+        done = subprocess.run([exe, "--version"], capture_output=True, text=True,  # nosec B603
+                              timeout=5)
+        return (done.stdout or "").strip().split()[-1] if done.returncode == 0 and done.stdout.strip() else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _harnesses() -> list[str]:
+    return [name for name, binary in (("claude", "claude"), ("grok", "grok"), ("codex", "codex"))
+            if shutil.which(binary)]
+
+
+def payload(project: str, lines: list[dict]) -> dict:
+    return {
+        "machine_id": machine_id(), "label": socket.gethostname().split(".")[0],
+        "os": f"{platform.system()} {platform.release()}".strip(),
+        "gban_version": _version("gban"), "gbfleet_version": _gbfleet_version(),
+        "harnesses": _harnesses(), "project": project,
+        "lines": [{"status": l["status"], "name": l["name"], "detail": l.get("detail", "")}
+                  for l in lines],
+    }
+
+
+def send(url: str, project: str, lines: list[dict]) -> list[dict]:
+    """Deliver the report. Returns the line to append when it could not be delivered, else []."""
+    try:
+        authenticated(url, act="report").call("POST", "/api/machines/report",
+                                              payload(project, lines))
+    except NoSession as exc:
+        return [_unreported(url, exc.why)]
+    except Refused as exc:
+        return [_unreported(url, exc.detail)]
+    except Unreachable as exc:
+        return [_unreported(url, str(exc))]
+    except Exception as exc:  # noqa: BLE001 - a report must never take the command down
+        return [_unreported(url, f"{type(exc).__name__}: {exc}")]
+    return []
+
+
+def _unreported(url: str, reason: str) -> dict:
+    return _line("report", UNKNOWN, "report", f"could not report to {url}: {reason}")

{graphban_cli-0.8.3 → graphban_cli-0.8.5}/src/gban/setup.py

@@ -49,6 +49,26 @@ 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 && uv tool install graphban-fleet",
+    "gban --server {server} login",
+    "gban --server {server} login --pair",
+    "gban setup",
+    "gban --project {project} setup",
+)
+
 
 # ---- where the config goes ------------------------------------------------------------------
 
@@ -375,7 +395,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 +495,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)
@@ -750,6 +772,40 @@ def match(projects: list[dict], here: Path) -> tuple[dict, list[dict]]:
     return by_project, notes
 
 
+def normalize_remote(raw: str) -> str:
+    """`host/owner/name`, lowercased, no scheme, credentials, port or `.git`. The same rule as
+    backend/app/services/projects.py:normalize_repo_url (a separate distribution cannot import
+    it); tests on both sides pin the same table. "" when it does not look like a remote."""
+    value = (raw or "").strip()
+    m = re.match(r"^(?:[a-z][a-z0-9+.-]*://(?:[^@/]*@)?([^/:]+)(?::\d*)?|(?:[^@/]*@)?([^/:]+):?)/?(.+)$",
+                 value, re.IGNORECASE)
+    if not m or any(ch.isspace() for ch in value):
+        return ""
+    path = m.group(3).strip("/")
+    path = path[:-4] if path.endswith(".git") else path
+    return f"{m.group(1) or m.group(2)}/{path}".lower() if "/" in path else ""
+
+
+def git_remotes(here: Path) -> list[str]:
+    """Normalized URLs of every remote of the checkout at `here`, `origin` first. [] when it is
+    not a checkout or git is absent — which is "no signal", and falls through to the name match."""
+    try:
+        names_out = subprocess.run(["git", "-C", str(here), "remote"], capture_output=True,
+                                   text=True, timeout=10)
+        if names_out.returncode != 0:
+            return []
+        out = []
+        for name in sorted(names_out.stdout.split(), key=lambda n: n != "origin"):
+            got = subprocess.run(["git", "-C", str(here), "remote", "get-url", name],
+                                 capture_output=True, text=True, timeout=10)
+            norm = normalize_remote(got.stdout) if got.returncode == 0 else ""
+            if norm and norm not in out:
+                out.append(norm)
+        return out
+    except (OSError, subprocess.SubprocessError):
+        return []
+
+
 class Unresolved(Exception):
     """The directory does not name a project on this deployment (GRPH-795)."""
 
@@ -772,6 +828,15 @@ def resolve_project(client, here: Path, asked: str = "", stored: str = "") -> tu
         return asked, "named"
     rows = client.call("GET", "/api/projects")
     projects = [p for p in (rows if isinstance(rows, list) else []) if isinstance(p, dict)]
+    # The git remote is the stronger signal: a directory can be renamed, a remote names the repo.
+    remotes = git_remotes(here)
+    by_remote = [p for p in projects if str(p.get("repo_url") or "") in remotes]
+    if len(by_remote) == 1:
+        return str(by_remote[0].get("id") or ""), f"matched the git remote {by_remote[0].get('repo_url')!r}"
+    if len(by_remote) > 1:
+        raise Unresolved(
+            f"this checkout's remote matches several projects "
+            f"({', '.join(sorted(str(p.get('id')) for p in by_remote))}), so none was chosen — name one with --project")
     hits = [p for p in projects if slug(here.name) in names(p)]
     if len(hits) == 1:
         return str(hits[0].get("id") or ""), f"matched the directory name {here.name!r}"