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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.1.0
+Version: 0.2.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
@@ -26,32 +26,63 @@ Specified by [PRD-40](https://github.com/asc-me/graphban/blob/main/docs/prd-40-g
 
 ## Install
 
-Not on PyPI yet, so it installs from the repository. `uv tool install` puts it on your PATH
-in its own environment, which is what you want for a CLI:
+```bash
+uv tool install graphban-cli
+```
+
+or, on macOS:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+brew install asc-me/tap/gban
 ```
 
-Add `gbfleet` too if you run waves — it is a separate package, and `gban fleet` hands off to it:
+The formula carries no `resource` stanzas — `graphban-cli` has no runtime dependencies, so
+there is nothing to vendor and nothing to regenerate when a transitive moves. The supervisor
+is deliberately not in the tap; see below.
+
+Add the supervisor too if you run waves — a separate package, and `gban fleet` hands off to
+it. At a terminal, `gban fleet` will offer to run this for you when it finds no supervisor;
+it asks first and never installs on a bare return, because a person who typed a read-only
+command did not consent to software being installed:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+uv tool install graphban-fleet
 ```
 
-`uv tool update-shell` once, if uv says the bin directory is not on your PATH. Upgrade either
-with `uv tool upgrade graphban-cli` (or `--all`); reinstalling from the same URL also works,
-since the spec is a branch rather than a pin.
+That also gives you `gbagent`, the first-party coding agent: it is an entry point of
+`graphban-fleet`, not a package of its own, because the supervisor resolves it on PATH like
+any other vendor binary.
+
+`uv tool update-shell` once, if uv says the bin directory is not on your PATH.
+`uv tool upgrade --all` to move both forward.
+
+Two commands rather than one, and an extra (`graphban-cli[fleet]`) is deliberately not
+offered: `uv tool install` exposes only the REQUESTED package's executables, so an extra
+installs `gbfleet` into `gban`'s environment and puts it on no path at all. Measured — with
+the extra, `gban fleet` reported "gbfleet is not installed here" while `gbfleet` sat in the
+very environment it was running from.
+
+`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
+exactly one distribution. `gbfleet` brings httpx and its transitives, which is why they are
+separate packages and not one.
 
 With pip instead, into an environment you already have:
 
 ```bash
-pip install "graphban-cli @ git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+pip install graphban-cli
 ```
 
-`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
-exactly one distribution. `gbfleet` brings httpx and its four transitive dependencies, which
-is why they are separate packages and not one.
+`gban` looks for `gbfleet` beside its own interpreter before falling back to PATH, so that
+shape works with neither on PATH.
+
+To run an unreleased change, install from the repository instead — the same spec the release
+builds from:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/docs/releasing.md).
 
 ```bash
 gban login --server https://cloud.agentldgr.dev
@@ -77,6 +108,48 @@ role the key does not permit is the server's refusal, printed in the server's ow
 widening a ceiling means minting a different credential, and keeping those two acts apart is
 the point of having a ceiling. It lands on the agent's next poll.
 
+## Enabling delegation on a project
+
+```bash
+gban login          # once, at a terminal
+gban setup          # everything mechanical between that and a delegating agent
+gban setup --auto   # …or every project whose repository sits here or beside here
+```
+
+An agent with the delegation skill runs all of this for you except `gban login`, which it
+hands back as a `! gban login` line to type — it needs a terminal, and no agent has one — and
+then carries on from where you left it.
+
+**The directory names the project.** Run `setup` from inside the repository the work belongs
+to and it matches that directory against the projects you can read. An explicit `--project`
+wins; nothing else does. In particular the default `gban login` stores is *not* used here and
+is named in the refusal when it exists — logging in once inside one project must not quietly
+mint a credential for it while you are standing in another repository, and a key in the wrong
+project is not a mistake anybody notices quickly.
+
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
+installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
+and then **verifies** rather than asserting: it asks the new credential what it can actually
+see. Restart the harness afterwards — MCP servers are read at startup.
+
+Three properties worth knowing, each of which is a bug this command exists to not have:
+
+- **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
+  day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
+- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
+  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
+  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
+  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
+  because a credential outside the repository cannot be committed.
+- **`--auto` matches, and says so.** A project carries no repository link — no remote, no
+  path — so `--auto` compares your project ids and names against this directory, what is in
+  it, and its siblings. One level, never a recursive walk. Two directories answering to one
+  project, or one directory answering to two, are **refused rather than guessed**: a
+  credential minted into the wrong repository is not a mistake anybody notices quickly.
+- **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
+  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
+  credential still commits it.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

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

@@ -11,32 +11,63 @@ Specified by [PRD-40](https://github.com/asc-me/graphban/blob/main/docs/prd-40-g
 
 ## Install
 
-Not on PyPI yet, so it installs from the repository. `uv tool install` puts it on your PATH
-in its own environment, which is what you want for a CLI:
+```bash
+uv tool install graphban-cli
+```
+
+or, on macOS:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+brew install asc-me/tap/gban
 ```
 
-Add `gbfleet` too if you run waves — it is a separate package, and `gban fleet` hands off to it:
+The formula carries no `resource` stanzas — `graphban-cli` has no runtime dependencies, so
+there is nothing to vendor and nothing to regenerate when a transitive moves. The supervisor
+is deliberately not in the tap; see below.
+
+Add the supervisor too if you run waves — a separate package, and `gban fleet` hands off to
+it. At a terminal, `gban fleet` will offer to run this for you when it finds no supervisor;
+it asks first and never installs on a bare return, because a person who typed a read-only
+command did not consent to software being installed:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+uv tool install graphban-fleet
 ```
 
-`uv tool update-shell` once, if uv says the bin directory is not on your PATH. Upgrade either
-with `uv tool upgrade graphban-cli` (or `--all`); reinstalling from the same URL also works,
-since the spec is a branch rather than a pin.
+That also gives you `gbagent`, the first-party coding agent: it is an entry point of
+`graphban-fleet`, not a package of its own, because the supervisor resolves it on PATH like
+any other vendor binary.
+
+`uv tool update-shell` once, if uv says the bin directory is not on your PATH.
+`uv tool upgrade --all` to move both forward.
+
+Two commands rather than one, and an extra (`graphban-cli[fleet]`) is deliberately not
+offered: `uv tool install` exposes only the REQUESTED package's executables, so an extra
+installs `gbfleet` into `gban`'s environment and puts it on no path at all. Measured — with
+the extra, `gban fleet` reported "gbfleet is not installed here" while `gbfleet` sat in the
+very environment it was running from.
+
+`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
+exactly one distribution. `gbfleet` brings httpx and its transitives, which is why they are
+separate packages and not one.
 
 With pip instead, into an environment you already have:
 
 ```bash
-pip install "graphban-cli @ git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+pip install graphban-cli
 ```
 
-`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
-exactly one distribution. `gbfleet` brings httpx and its four transitive dependencies, which
-is why they are separate packages and not one.
+`gban` looks for `gbfleet` beside its own interpreter before falling back to PATH, so that
+shape works with neither on PATH.
+
+To run an unreleased change, install from the repository instead — the same spec the release
+builds from:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/docs/releasing.md).
 
 ```bash
 gban login --server https://cloud.agentldgr.dev
@@ -62,6 +93,48 @@ role the key does not permit is the server's refusal, printed in the server's ow
 widening a ceiling means minting a different credential, and keeping those two acts apart is
 the point of having a ceiling. It lands on the agent's next poll.
 
+## Enabling delegation on a project
+
+```bash
+gban login          # once, at a terminal
+gban setup          # everything mechanical between that and a delegating agent
+gban setup --auto   # …or every project whose repository sits here or beside here
+```
+
+An agent with the delegation skill runs all of this for you except `gban login`, which it
+hands back as a `! gban login` line to type — it needs a terminal, and no agent has one — and
+then carries on from where you left it.
+
+**The directory names the project.** Run `setup` from inside the repository the work belongs
+to and it matches that directory against the projects you can read. An explicit `--project`
+wins; nothing else does. In particular the default `gban login` stores is *not* used here and
+is named in the refusal when it exists — logging in once inside one project must not quietly
+mint a credential for it while you are standing in another repository, and a key in the wrong
+project is not a mistake anybody notices quickly.
+
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
+installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
+and then **verifies** rather than asserting: it asks the new credential what it can actually
+see. Restart the harness afterwards — MCP servers are read at startup.
+
+Three properties worth knowing, each of which is a bug this command exists to not have:
+
+- **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
+  day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
+- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
+  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
+  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
+  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
+  because a credential outside the repository cannot be committed.
+- **`--auto` matches, and says so.** A project carries no repository link — no remote, no
+  path — so `--auto` compares your project ids and names against this directory, what is in
+  it, and its siblings. One level, never a recursive walk. Two directories answering to one
+  project, or one directory answering to two, are **refused rather than guessed**: a
+  credential minted into the wrong repository is not a mistake anybody notices quickly.
+- **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
+  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
+  credential still commits it.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

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

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

{graphban_cli-0.1.0 → graphban_cli-0.2.0}/src/gban/cli.py

@@ -13,8 +13,9 @@ import os
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
-from gban import config, doctor as doctor_mod
+from gban import config, doctor as doctor_mod, setup as setup_mod
 from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
                        Client, NoSession,
                        Refused, Unreachable, authenticated, login)
@@ -52,6 +53,26 @@ def _parser() -> argparse.ArgumentParser:
                      "Neither half silences the other: what could not be checked prints "
                      "UNKNOWN with its reason, never a pass."))
 
+    setup_cmd = sub.add_parser(
+        "setup", help="enable delegation on a project",
+        description=("Mints a project-scoped credential that does NOT expire, writes the "
+                     "graphban and gbfleet MCP entries where the harness will actually read "
+                     "them, and installs the supervisor. Only seats expire; a credential that "
+                     "died overnight would make 'delegation is set up' quietly stop being "
+                     "true. Re-running is safe: a working configuration is left alone."))
+    setup_cmd.add_argument(
+        "--scope", choices=["user", "project"], default="user",
+        help="user (default) writes ~/.claude.json, which OUTRANKS a repo .mcp.json and "
+             "cannot be committed; project writes .mcp.json beside the repo")
+    setup_cmd.add_argument(
+        "--auto", action="store_true",
+        help="every project with a repository here: matches this directory, what is in it and "
+             "its siblings against your projects BY NAME, and refuses any ambiguity rather "
+             "than guessing. A project carries no repository link, so this is a match, not a "
+             "lookup")
+    setup_cmd.add_argument("--no-install", action="store_true",
+                           help="do not install the supervisor")
+
     fleet = sub.add_parser(
         "fleet", help="hand off to gbfleet (the supervisor)",
         description=("Passes everything through to `gbfleet` and returns its exit code "
@@ -150,15 +171,52 @@ def cmd_login(args) -> int:
     if not refresh:
         print(f"{PROG}: the server returned no refresh token", file=sys.stderr)
         return EXIT_REFUSED
-    config.save_settings(url=url, project=config.resolve(args.project, config.PROJECT_ENV,
-                                                         "project"))
     path = config.save_session(refresh, user=email)
-    _out({"server": url, "session": str(path), "user": email},
-         f"{PROG}: signed in to {url} as {email}\n     session stored at {path} (mode 600)",
-         args.as_json)
+    asked = config.resolve(args.project, config.PROJECT_ENV, "project")
+    chosen, projects, why = _default_project(url, asked)
+    config.save_settings(url=url, project=chosen)
+    human = [f"{PROG}: signed in to {url} as {email}",
+             f"     session stored at {path} (mode 600)"]
+    if chosen:
+        human.append(f"     project {chosen}" + (" (the only one you can read)"
+                                                 if not asked and len(projects) == 1 else ""))
+        human.append(f"     next: `{PROG} setup` enables delegation on it")
+    elif len(projects) > 1:
+        human.append(f"     {len(projects)} projects — none set as default:")
+        human += [f"       {p.get('id', ''):<20} {p.get('name', '')}" for p in projects]
+        human.append(f"     pick one: `{PROG} setup --project <id>`")
+    elif why:
+        # Discovery failed, the login did not. Reporting this as a failed login would send
+        # somebody to re-enter a password that was already accepted.
+        human.append(f"     WARNING: could not list your projects ({why}).")
+        human.append(f"     Name one when you need it: `{PROG} setup --project <id>`")
+    else:
+        human.append("     you can read no projects yet — create one in the web app first")
+    _out({"server": url, "session": str(path), "user": email, "project": chosen,
+          "projects": [p.get("id") for p in projects]}, "\n".join(human), args.as_json)
     return 0
 
 
+def _default_project(url: str, asked: str) -> tuple[str, list[dict], str]:
+    """What `login` should store as the default, the projects it saw, and why it saw none.
+
+    ONE project is chosen for you; several are listed and none is chosen. Picking the first of
+    several would be a coin toss whose result is invisible until a key lands in the wrong
+    project, and the list is short enough to read.
+
+    An explicit `--project` is never overridden — the person naming one has said the thing
+    this function exists to guess.
+    """
+    if asked:
+        return asked, [], ""
+    try:
+        rows = authenticated(url, act="login").call("GET", "/api/projects")
+    except (Unreachable, Refused, NoSession) as exc:
+        return "", [], str(exc)
+    projects = [p for p in (rows if isinstance(rows, list) else []) if isinstance(p, dict)]
+    return (projects[0].get("id", "") if len(projects) == 1 else ""), projects, ""
+
+
 def cmd_logout(args) -> int:
     url = _server(args)
     told_server, why = False, ""
@@ -208,6 +266,70 @@ def cmd_doctor(args) -> int:
     return code
 
 
+def cmd_setup(args) -> int:
+    """Everything between a session and a delegating agent, in one act (GRPH-792)."""
+    url = _server(args)
+    # THE SESSION FIRST, and the order is the point. Resolving the project first told somebody
+    # who had never logged in that they had "no project" — true about the wrong thing, with
+    # the wrong exit code (1 rather than 3), and it sends a reader hunting for a project id
+    # when the remedy is a person at a terminal. Found by running the built wheel rather than
+    # by a test, because every test here starts from a stored session.
+    client = authenticated(url, act="setup")
+    if args.auto:
+        return _setup_auto(args, url, client)
+    # EXPLICIT ONLY. `config.resolve` would fold in the default `gban login` stored, and this
+    # is the one verb where that default is dangerous rather than convenient — see
+    # `setup.resolve_project`.
+    asked = (args.project or os.environ.get(config.PROJECT_ENV) or "").strip()
+    try:
+        project, how = setup_mod.resolve_project(
+            client, Path.cwd(), asked, config.settings().get("project", ""))
+    except setup_mod.Unresolved as exc:
+        print(f"{PROG}: {exc}", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, code, made = setup_mod.run(client, url, project, Path.cwd(), scope=args.scope,
+                                      install=not args.no_install)
+    human = [doctor_mod.render(lines)]
+    if how != "named":
+        human.insert(0, f"{PROG}: {project} — {how}")
+    if code == 0:
+        human.append(f"\n     delegation is enabled on {project}. An agent can now "
+                     f"`delegate(id=…, lane=…, tier=…, seat=true)` then `spawn`.")
+        human.append(f"     restart the harness so it reads the new config.")
+    _out({"lines": lines, "ok": code == 0, "project": project, **made},
+         "\n".join(human), args.as_json)
+    return code
+
+
+def _setup_auto(args, url: str, client) -> int:
+    """Every project that has a repository here, each in its own.
+
+    Reports what it did NOT match as loudly as what it did. A sweep that silently skipped a
+    project would leave somebody believing delegation is enabled everywhere.
+    """
+    projects = client.call("GET", "/api/projects")
+    projects = [p for p in (projects if isinstance(projects, list) else []) if isinstance(p, dict)]
+    found, notes = setup_mod.match(projects, Path.cwd())
+    if not found:
+        print(doctor_mod.render(notes) if notes else
+              f"{PROG}: no projects to match", file=sys.stderr)
+        print(f"{PROG}: matched no repository here. `{PROG} setup --project <id>` from inside "
+              f"one names it directly.", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, worst, done = list(notes), 0, {}
+    for pid, repo in sorted(found.items()):
+        lines.append(doctor_mod._line("match", doctor_mod.PASS, pid, str(repo)))
+        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]
+        done[pid], worst = {"repo": str(repo), "ok": code == 0, **made}, max(worst, code)
+    human = [doctor_mod.render(lines),
+             f"\n     {sum(1 for d in done.values() if d['ok'])} of {len(done)} enabled. "
+             f"Restart the harness so it reads the new config."]
+    _out({"lines": lines, "ok": worst == 0, "projects": done}, "\n".join(human), args.as_json)
+    return worst
+
+
 def cmd_fleet(args) -> int:
     """A subprocess, never an import (D5).
 
@@ -215,10 +337,17 @@ def cmd_fleet(args) -> int:
     and leaves `gbfleet --help` authoritative about its own commands.
     """
     binary = doctor_mod.find_supervisor()
+    if not binary:
+        # At a terminal, offer to fix it here rather than making the person read a command,
+        # copy it, run it and type this one again. Declined or unavailable, the message is
+        # what it always was.
+        if doctor_mod.offer_to_install():
+            binary = doctor_mod.find_supervisor()
     if not binary:
         print(f"{PROG}: gbfleet is not installed here. Install it with:\n"
               f"     {doctor_mod.INSTALL_SUPERVISOR}\n"
-              f"     …or run it from the repository's fleet/ directory.", file=sys.stderr)
+              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 != "--"]]
     url = config.resolve(args.server, config.URL_ENV, "url")
@@ -351,7 +480,7 @@ def cmd_keys(args) -> int:
 
 
 COMMANDS = {"login": cmd_login, "logout": cmd_logout, "whoami": cmd_whoami,
-            "doctor": cmd_doctor, "fleet": cmd_fleet, "seats": cmd_seats,
+            "doctor": cmd_doctor, "setup": cmd_setup, "fleet": cmd_fleet, "seats": cmd_seats,
             "agents": cmd_agents, "keys": cmd_keys}
 
 

{graphban_cli-0.1.0 → graphban_cli-0.2.0}/src/gban/doctor.py

@@ -118,12 +118,86 @@ def local(url: str, project: str, api_key: str) -> list[dict]:
                   f"`gbfleet doctor` {verdict}; its own report follows", report=body)]
 
 
-#: The command that actually installs the supervisor. NOT `uv pip install graphban-fleet`,
-#: which is what this said until somebody ran it: neither package is on PyPI, so that line
-#: 404s. A tool whose remedy does not work is worse than one that offers none — it spends the
-#: reader's trust before spending their time.
-INSTALL_SUPERVISOR = (
-    'uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"')
+#: The command that actually installs the supervisor. It has been wrong twice: first naming a
+#: PyPI package that did not exist, then a git spec that worked but stopped being the right
+#: advice the moment `graphban-fleet` was published. A remedy a tool prints is a promise, and
+#: `cli/tests/test_packaging.py` now checks this one against the same source the README uses.
+INSTALL_SUPERVISOR = "uv tool install graphban-fleet"
+
+
+def offer_to_install(stream=None) -> bool:
+    """Ask, then install `graphban-fleet` with uv. Returns whether it is there afterwards.
+
+    **Asked, never assumed.** Installing software is not a side effect anybody should get
+    from `gban fleet ps`: it writes outside this program, it takes a minute, and a person
+    who typed a read-only command did not consent to it. So it happens only at an
+    interactive prompt, only on an explicit `y`, and only when the wall has actually been
+    hit — a missing supervisor, on the command that needs one.
+
+    Nothing is installed into `gban`'s OWN environment. `uv tool install` gives the
+    supervisor its own, which is the only correct answer when `gban` may itself live in a
+    Homebrew Cellar that brew will replace: a `pip install` next to it would be silently
+    undone by the next upgrade.
+
+    Declines, non-interactive shells and a machine without uv all return False and leave the
+    caller to print the command — a prompt nobody can answer is a hang, and a hang in a
+    script is worse than the error it replaced.
+    """
+    import sys
+
+    out = stream or sys.stderr
+    if not sys.stdin.isatty():
+        return False
+    if not shutil.which("uv"):
+        return False
+    print(f"gban: gbfleet is not installed here.", file=out)
+    try:
+        answer = input(f"       run `{INSTALL_SUPERVISOR}` now? [y/N] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print("", file=out)
+        return False
+    if answer not in ("y", "yes"):
+        return False
+    done = subprocess.run(INSTALL_SUPERVISOR.split())
+    if done.returncode != 0:
+        print(f"gban: that install failed ({done.returncode}); nothing changed here.",
+              file=out)
+        return False
+    return bool(find_supervisor())
+
+
+def install_supervisor(timeout: float = 600.0) -> tuple[bool, str]:
+    """Install it, without asking. `(installed, why_not)`.
+
+    `offer_to_install` prompts because it is reached from `gban fleet`, where a person typed a
+    read-only command and did not consent to software being installed. `gban setup` is the
+    other case entirely: it mints a credential and rewrites the harness config, and installing
+    the supervisor is squarely inside what "enable delegation on this project" asks for. So
+    the consent argument is satisfied by the verb rather than by a second prompt — which an
+    agent driving this could not answer anyway.
+
+    Still nothing into `gban`'s own environment: `uv tool install` gives the supervisor its
+    own, which is the only correct answer when `gban` may live in a Homebrew Cellar that brew
+    will replace.
+    """
+    if not shutil.which("uv"):
+        return False, ("uv is not on PATH, so there is nothing to install with — "
+                       "`brew install uv`, or see https://docs.astral.sh/uv/")
+    try:
+        done = subprocess.run(INSTALL_SUPERVISOR.split(), capture_output=True, text=True,
+                              timeout=timeout)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return False, f"`{INSTALL_SUPERVISOR}` could not run: {exc}"
+    if done.returncode != 0:
+        tail = (done.stderr or done.stdout or "").strip().splitlines()
+        return False, (f"`{INSTALL_SUPERVISOR}` failed ({done.returncode})"
+                       + (f": {tail[-1][:160]}" if tail else ""))
+    if not find_supervisor():
+        # It reported success and the binary is not resolvable. Almost always uv's tool bin
+        # directory missing from PATH, which is a real state and not a failed install.
+        return False, ("installed, but `gbfleet` is not on PATH — run `uv tool update-shell` "
+                       "and open a new shell")
+    return True, ""
 
 
 def find_supervisor() -> str: