@bridge_gpt/mcp-server 0.2.31 → 0.2.33

package/README.md

@@ -31,18 +31,29 @@ npx -y @bridge_gpt/mcp-server@latest install-bridge
 ```
 
 Run bare like that in a terminal and it starts by asking
-**`Do you have a Bridge API key or invite? [Y/n]`**:
-
-- **Yes** (or just press Enter) — the existing-key flow. It asks for your **API key**
-  (generate one on the Bridge API web UI **Security** page) and a **repo name**
-  matching your server-side registration; everything else is derived. A
-  `bapi_inv_…` credential entered here instead of a full API key is automatically
-  detected and redeemed as a **bootstrap invite** — it creates a brand-new project
-  and mints your admin API key rather than looking up an existing repository.
-- **No** — the **self-serve** flow. It asks for an **email**, then a name for your new
-  Bridge project, and creates the workspace and your own admin API key for you. No
-  account, no key, and no invite needed beforehand. Same as passing
-  `--email you@example.com` (see below).
+**`How would you like to connect to Bridge API?`** with three numbered choices:
+
+```
+1. I have a Bridge API key
+2. I have an invite token
+3. I'm new — set me up with just my email
+```
+
+- **1** — the existing-key flow. It asks for your **API key** (generate one on the
+  Bridge API web UI **Security** page) and a **repo name** matching your server-side
+  registration; everything else is derived. A `bapi_inv_…` credential entered here
+  instead of a full API key is automatically detected and redeemed as a **bootstrap
+  invite** — it creates a brand-new project and mints your admin API key rather than
+  looking up an existing repository.
+- **2** — the **bootstrap-invite** flow. It asks for the invite token you were given,
+  with echo suppressed. Same as passing `--invite` (see below).
+- **3** — the **self-serve** flow, and the right answer if you have nothing yet. It
+  asks for an **email**, then a name for your new Bridge project, and creates the
+  workspace and your own admin API key for you. No account, no key, and no invite
+  needed beforehand. Same as passing `--email you@example.com` (see below).
+
+There is **no default**: pressing Enter selects nothing. A blank or invalid answer
+re-prompts once with a hint, then exits with guidance naming all three routes.
 
 That question is asked only for a *bare interactive* run. Passing any flag, setting
 `BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the
@@ -51,11 +62,12 @@ existing deterministic behavior.
 From there `install-bridge` scaffolds the project, writes your editor's MCP config
 with real values, verifies connectivity, persists your API key to the user-scoped
 credential store, and opens a fresh agent session that runs `/install-bridge` to
-derive and apply the remaining config, presents a **capability report** (what you can
-use now and what you'll unlock), and closes by asking whether to index the
-repository. It does **not** automatically run `/learn-repository` or index without
-your consent — both remain available as separate steps. Add `--dry-run` to preview
-every step without writing, pinging, or spawning anything.
+derive and apply the remaining config, presents a concise **capability report**
+("What Bridge can help with"), and recommends `/learn-repository` as your next step.
+It does **not** run `/learn-repository` itself — that stays your next explicit
+invocation. There is **no indexing question**: indexing starts automatically
+server-side once the repository reaches full parse readiness. Add `--dry-run` to
+preview every step without writing, pinging, or spawning anything.
 
 **Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
 at all — run the command your operator gave you:
@@ -148,12 +160,30 @@ shown**.
 The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
 **visible** interactive prompt (email is not a secret, so it is echoed as you type —
 unlike the API key and the invite token, which use a hidden prompt). That prompt is
-what answering **no** to `Do you have a Bridge API key or invite? [Y/n]` on a bare run reaches,
-so `install-bridge --email you@example.com` and a bare `install-bridge` + "no" land
-in the same place. The email is still **never written to a log line**. No email
+what **option 3** of the bare-run chooser reaches, so
+`install-bridge --email you@example.com` and a bare `install-bridge` + `3` land in
+the same place. The email is still **never written to a log line**. No email
 verification is performed and no message is sent to the address — it only labels your
 new workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.
 
+##### Self-serve retries resume automatically
+
+A self-serve run that fails part-way through — a network blip on the exchange, a
+failed connectivity check, an interrupted credential write — saves its signup state
+under `bootstrap-pending:<repo>` in the credential store (mode `0600`, fsync'd, the
+same record that already holds your `key_secret`).
+
+**Just re-run the self-serve flow.** It detects that saved attempt, prints
+`resuming your previous signup attempt for <repo>`, and re-drives the *same*
+exchange — it does **not** sign up again, so a retry never creates a second
+workspace. This is why the self-serve record stores the minted invite token: you
+were never shown that token, so nothing else could re-present it.
+
+Do **not** copy, display, or hand-remove that record. If the saved invite has
+genuinely expired, the CLI says so and **asks for confirmation** before discarding
+it and starting fresh — it never discards it silently, because a record whose
+exchange already succeeded is the only trace of a live admin key.
+
 Because this flow *creates* the project, it asks you to **name a new project**
 (`Name your new Bridge project [<inferred>]: `) rather than to match an existing
 server-side registration. The name must be globally unique; if it's taken, you're
@@ -689,12 +719,14 @@ Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for
 
 ### `doctor`
 
-The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
+The package also ships a strictly **read-only** `doctor` subcommand — titled **`bridge doctor — read-only diagnostics`** — that diagnoses your whole Bridge install without changing anything:
 
 ```
 npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 ```
 
+The report always leads with the advisory **`Install status`** section (repo identity, credential resolution, server connectivity, bootstrap-field completeness, integration credentials, indexing state) **before** the `start-tickets` prerequisite diagnostics; the launcher-cache and MCP tool-surface sections follow. `Install status` is read-only GETs only and never affects the exit code.
+
 It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
 ### `setup-epic`

package/build/connect-github-api.js

@@ -22,6 +22,7 @@ const TERMINAL_STATUSES = new Set([
     "connected",
     "expired",
     "invalid",
+    "revoked",
     "verification-failed",
     "no-repositories",
     "conflict",
@@ -228,6 +229,108 @@ export async function confirmGithubConnection(deps, repoName, state, githubRepos
         },
     };
 }
+const ALL_HANDOFF_STATUSES = new Set([
+    "pending",
+    "staged",
+    "awaiting-organization-approval",
+    "connected",
+    "expired",
+    "revoked",
+    "verification-failed",
+    "no-repositories",
+    "conflict",
+    "failed",
+]);
+/**
+ * Mint a delegated handoff link.
+ *
+ * Deliberately parses only the URL and expiry: the backend does not return the state as
+ * a separate field, and nothing here should reconstruct one.
+ */
+export async function mintGithubHandoff(deps, repoName) {
+    const res = await postJson(deps, "/setup/github/cli/handoff", {
+        repo_name: repoName,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const installUrl = asString(body?.install_url);
+    const expiresAt = asString(body?.expires_at);
+    const ttlSeconds = body?.ttl_seconds;
+    if (!body || !installUrl || !expiresAt || typeof ttlSeconds !== "number") {
+        return { ok: false, kind: "malformed" };
+    }
+    return { ok: true, value: { installUrl, expiresAt, ttlSeconds } };
+}
+/** Strictly parse one handoff list item. Returns null for any malformed shape. */
+function parseHandoffSnapshot(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    const state = asString(rec.state);
+    const status = asString(rec.status);
+    if (!state || !status || !ALL_HANDOFF_STATUSES.has(status))
+        return null;
+    const candidates = parseCandidates(rec.candidates ?? []);
+    if (candidates === null)
+        return null;
+    return {
+        state,
+        status: status,
+        createdAt: asNullableString(rec.created_at),
+        expiresAt: asNullableString(rec.expires_at),
+        revokedAt: asNullableString(rec.revoked_at),
+        candidates,
+        githubRepoName: asNullableString(rec.github_repo_name),
+    };
+}
+/** Discover outstanding delegated handoffs for a project (the resume/revoke lookup). */
+export async function listGithubHandoffs(deps, repoName) {
+    const res = await postJson(deps, "/setup/github/cli/handoffs", {
+        repo_name: repoName,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const rawHandoffs = body?.handoffs;
+    if (!body || !Array.isArray(rawHandoffs)) {
+        return { ok: false, kind: "malformed" };
+    }
+    const out = [];
+    for (const raw of rawHandoffs) {
+        const parsed = parseHandoffSnapshot(raw);
+        // A malformed entry is a malformed RESPONSE, not an item to quietly drop: dropping
+        // it would silently shrink the admin's picker and could hide a live handoff.
+        if (!parsed)
+            return { ok: false, kind: "malformed" };
+        out.push(parsed);
+    }
+    return { ok: true, value: out };
+}
+/** Revoke one outstanding delegated handoff. The state travels in the body. */
+export async function revokeGithubHandoff(deps, repoName, state) {
+    const res = await postJson(deps, "/setup/github/cli/revoke", {
+        repo_name: repoName,
+        state,
+    });
+    if (!res.ok)
+        return res;
+    if (res.value.status !== 200) {
+        return { ok: false, kind: classifyStatus(res.value.status) };
+    }
+    const body = asRecord(res.value.body);
+    const status = asString(body?.status);
+    if (!body || (status !== "revoked" && status !== "already-revoked")) {
+        return { ok: false, kind: "malformed" };
+    }
+    return { ok: true, value: status };
+}
 /**
  * Read whether GitHub is already configured for a project.
  *

package/build/connect-github.js

@@ -28,8 +28,8 @@ import { DEFAULT_BAPI_BASE_URL } from "./install-bridge.js";
 import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { resolveBapiCredentials, } from "./credential-store.js";
-import { POLL_DEADLINE_MS, confirmGithubConnection, mintGithubConnection, pollGithubConnection, } from "./connect-github-api.js";
-const USAGE = `Usage: connect-github [--repo <repo_name>]
+import { POLL_DEADLINE_MS, confirmGithubConnection, listGithubHandoffs, mintGithubConnection, mintGithubHandoff, pollGithubConnection, revokeGithubHandoff, } from "./connect-github-api.js";
+const USAGE = `Usage: connect-github [--repo <repo_name>] [--handoff | --resume | --revoke]
 
 Connect a GitHub repository to a Bridge project from your terminal.
 
@@ -37,10 +37,24 @@ Opens the GitHub App install page in your browser, waits for you to install it,
 then asks which repository to connect. You are never asked for a GitHub token or
 password — you authenticate to GitHub in the browser.
 
+If you do not administer the GitHub organization yourself, use the delegated
+handoff: mint a link with --handoff, send it to whoever does, and finish with
+--resume once they have completed their part.
+
 Options:
   --repo <repo_name>   Bridge project to connect (inferred from this directory
                        when omitted; you will be asked to confirm).
-  --help               Show this message.`;
+  --handoff            Print a shareable install link (valid 72 hours) instead of
+                       connecting here. Does not open a browser or wait.
+  --resume             Look up an outstanding handoff and finish connecting it.
+                       Works from any machine holding this project's API key.
+  --revoke             Invalidate an outstanding handoff link.
+  --help               Show this message.
+
+--handoff, --resume, and --revoke are mutually exclusive. Minting a new link does
+not invalidate an existing one — use --revoke for that.`;
+/** The three delegated modes, for the mutual-exclusion check and its message. */
+const DELEGATED_MODE_FLAGS = ["--handoff", "--resume", "--revoke"];
 /**
  * Parse argv. Deliberately strict — an unknown flag is an error, not something to
  * ignore. In particular there is NO `--yes` (every bind is confirmed by a human) and no
@@ -55,6 +69,18 @@ export function parseConnectGithubArgs(argv) {
             out.help = true;
             continue;
         }
+        if (arg === "--handoff") {
+            out.handoff = true;
+            continue;
+        }
+        if (arg === "--resume") {
+            out.resume = true;
+            continue;
+        }
+        if (arg === "--revoke") {
+            out.revoke = true;
+            continue;
+        }
         if (arg === "--repo") {
             const value = argv[i + 1];
             if (!value || value.startsWith("-")) {
@@ -91,6 +117,18 @@ export function parseConnectGithubArgs(argv) {
         }
         return { ok: false, error: `Unexpected argument: ${arg}` };
     }
+    // Mutually exclusive: each mode is a different operation on a different object, and
+    // guessing at a precedence order would silently do something the caller did not ask
+    // for. Refuse rather than pick.
+    const selected = DELEGATED_MODE_FLAGS.filter((flag) => (flag === "--handoff" && out.handoff) ||
+        (flag === "--resume" && out.resume) ||
+        (flag === "--revoke" && out.revoke));
+    if (selected.length > 1) {
+        return {
+            ok: false,
+            error: `Choose only one of ${DELEGATED_MODE_FLAGS.join(", ")} (got ${selected.join(", ")}).`,
+        };
+    }
     return { ok: true, value: out };
 }
 /** Echoed single-line prompt on stderr. */
@@ -195,6 +233,28 @@ export async function resolveConnectGithubRepoName(args, deps) {
     const validated = validateRepoName(chosen);
     return validated.ok ? { ok: true, value: validated.value } : { ok: false, error: validated.error };
 }
+/**
+ * Resolve the project for non-interactive `--handoff` (BAPI-686).
+ *
+ * Synchronous and prompt-free, because mint mode may legitimately run without a TTY.
+ * That removes the interactive confirmation that makes inference safe in the default
+ * flow, so this deliberately does NOT fall back to guessing from the directory name:
+ * either `--repo` was given, or the caller is told to give it. Silently minting a live
+ * bearer link against the wrong project is a worse outcome than an error message.
+ */
+export function resolveHandoffRepoName(args, _deps) {
+    if (!args.repo) {
+        return {
+            ok: false,
+            error: "connect-github --handoff needs an explicit project: pass --repo <repo_name>. " +
+                "It cannot ask you to confirm an inferred name when run non-interactively.",
+        };
+    }
+    const validated = validateRepoName(args.repo);
+    return validated.ok
+        ? { ok: true, value: validated.value }
+        : { ok: false, error: validated.error };
+}
 // ---------------------------------------------------------------------------
 // Browser handoff
 // ---------------------------------------------------------------------------
@@ -262,6 +322,47 @@ function reportNoConnection(deps, detail) {
     deps.stderr(detail);
     return 1;
 }
+/**
+ * Ask which repository to bind. Returns null when the user declined or chose nothing.
+ *
+ * Extracted from `runGithubConnectionFlow` (BAPI-686) so the delegated `--resume` path
+ * reuses this exact interaction rather than growing a parallel copy that could drift
+ * from it. Behavior — the single-candidate `[y/N]`, the numbered picker, the absence of
+ * a default, and every message — is unchanged from BAPI-631.
+ */
+async function chooseCandidate(deps, candidates) {
+    if (candidates.length === 1) {
+        const only = candidates[0];
+        // Even with one option: show the full identity and require a yes. The user is
+        // authorizing a binding, not acknowledging a notice.
+        const answer = (await deps.promptLine(`Connect ${candidateLabel(only)}? [y/N]: `))
+            .trim()
+            .toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            deps.stderr("");
+            deps.stderr("No GitHub connection was made. Nothing was changed.");
+            return null;
+        }
+        return only;
+    }
+    deps.stderr("");
+    deps.stderr("Your GitHub installation includes multiple repositories:");
+    candidates.forEach((c, i) => {
+        deps.stderr(`  ${String(i + 1).padStart(2, " ")}. ${candidateLabel(c)}`);
+    });
+    deps.stderr("");
+    // No default: a stray Enter must not bind anything.
+    const answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
+    const index = Number(answer);
+    if (!/^\d+$/.test(answer) || !Number.isInteger(index) || index < 1 || index > candidates.length) {
+        deps.stderr("");
+        deps.stderr("No GitHub connection was made. No repository was selected.");
+        return null;
+    }
+    const selected = candidates[index - 1];
+    deps.stderr(`Selected ${candidateLabel(selected)}.`);
+    return selected;
+}
 export async function runGithubConnectionFlow(deps, api, repoName) {
     renderStep(deps, 0);
     const minted = await mintGithubConnection(api, repoName);
@@ -313,39 +414,9 @@ export async function runGithubConnectionFlow(deps, api, repoName) {
         return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"]);
     }
     renderStep(deps, 3);
-    let selected = null;
-    if (candidates.length === 1) {
-        const only = candidates[0];
-        // Even with one option: show the full identity and require a yes. The user is
-        // authorizing a binding, not acknowledging a notice.
-        const answer = (await deps.promptLine(`Connect ${candidateLabel(only)}? [y/N]: `))
-            .trim()
-            .toLowerCase();
-        if (answer !== "y" && answer !== "yes") {
-            deps.stderr("");
-            deps.stderr("No GitHub connection was made. Nothing was changed.");
-            return 1;
-        }
-        selected = only;
-    }
-    else {
-        deps.stderr("");
-        deps.stderr("Your GitHub installation includes multiple repositories:");
-        candidates.forEach((c, i) => {
-            deps.stderr(`  ${String(i + 1).padStart(2, " ")}. ${candidateLabel(c)}`);
-        });
-        deps.stderr("");
-        // No default: a stray Enter must not bind anything.
-        const answer = (await deps.promptLine(`Choose a repository [1-${candidates.length}]: `)).trim();
-        const index = Number(answer);
-        if (!/^\d+$/.test(answer) || !Number.isInteger(index) || index < 1 || index > candidates.length) {
-            deps.stderr("");
-            deps.stderr("No GitHub connection was made. No repository was selected.");
-            return 1;
-        }
-        selected = candidates[index - 1];
-        deps.stderr(`Selected ${candidateLabel(selected)}.`);
-    }
+    const selected = await chooseCandidate(deps, candidates);
+    if (!selected)
+        return 1;
     renderStep(deps, 4);
     const confirmed = await confirmGithubConnection(api, repoName, minted.value.state, selected.github_repository_id);
     if (!confirmed.ok) {
@@ -365,6 +436,207 @@ export async function runGithubConnectionFlow(deps, api, repoName) {
     return 0;
 }
 // ---------------------------------------------------------------------------
+// BAPI-686: delegated handoff modes
+//
+// Three self-contained flows that share nothing with `runGithubConnectionFlow` except
+// the API transport and the candidate picker. The default flow above is deliberately
+// untouched (AC-7): it still opens the browser itself and still never emits a URL.
+// ---------------------------------------------------------------------------
+/**
+ * The one place in this file permitted to write a bearer URL to stdout.
+ *
+ * `openGithubInstallPage`'s no-print contract is what keeps the *default* flow's nonce
+ * out of the user's scrollback, and it stays intact — mint mode never calls it. Here the
+ * URL is the entire deliverable: the admin has to be able to copy it and send it on. It
+ * goes to stdout only (never stderr, never a log, never an error path), so it can be
+ * piped without dragging the surrounding narration along with it.
+ */
+export async function runGithubHandoffMintFlow(deps, api, repoName) {
+    const minted = await mintGithubHandoff(api, repoName);
+    if (!minted.ok) {
+        return reportNoHandoff(deps, FAILURE_MESSAGES[minted.kind]);
+    }
+    deps.stdout(minted.value.installUrl);
+    deps.stderr("");
+    deps.stderr(`Send this link to whoever administers your GitHub organization.`);
+    deps.stderr(`It works once and expires ${formatExpiry(minted.value.expiresAt)}.`);
+    deps.stderr("They'll finish in their browser — ask them to ping you, then run " +
+        "`connect-github --resume`.");
+    return 0;
+}
+/** Render an expiry for humans without pretending to know the reader's locale. */
+function formatExpiry(iso) {
+    const parsed = Date.parse(iso);
+    if (Number.isNaN(parsed))
+        return "in 72 hours";
+    return `on ${new Date(parsed).toISOString().replace("T", " ").slice(0, 16)} UTC`;
+}
+/** The no-handoff framing, mirroring `reportNoConnection` for the delegated modes. */
+function reportNoHandoff(deps, detail) {
+    deps.stderr("");
+    deps.stderr("No handoff link was created.");
+    deps.stderr(detail);
+    return 1;
+}
+/** Statuses a handoff can still be revoked from. Anything else has nothing to withdraw. */
+const REVOCABLE_STATUSES = new Set([
+    "pending",
+    "awaiting-organization-approval",
+    "staged",
+]);
+/** One fixed, actionable line per non-staged handoff status. Never any upstream detail. */
+const HANDOFF_STATUS_MESSAGES = {
+    pending: "Nobody has completed the link yet. Ask them to open it, then run connect-github --resume again.",
+    expired: "The link expired before it was used. Run connect-github --handoff to create a new one.",
+    revoked: "This link was revoked. Run connect-github --handoff to create a new one.",
+    "verification-failed": "Bridge could not verify the GitHub installation. Run connect-github --handoff to create a new link.",
+    "no-repositories": "The GitHub App installation did not include any repositories Bridge can access. " +
+        "Create a new link with connect-github --handoff and ask them to grant access to at least one repository.",
+    conflict: "This GitHub installation or project is already connected to a different Bridge " +
+        "account or repository. Contact support if that is unexpected.",
+    failed: "The GitHub install did not complete. Run connect-github --handoff to create a new link.",
+};
+/**
+ * Label one handoff for the selection prompt.
+ *
+ * Uses ONLY status and timestamps. The state never appears — it is a bearer credential,
+ * and printing it into a picker would paste it into the user's scrollback for no reason.
+ */
+function handoffLabel(h) {
+    const created = h.createdAt ? ` · created ${h.createdAt.slice(0, 16).replace("T", " ")}` : "";
+    return `${h.status}${created}`;
+}
+/**
+ * Choose among discovered handoffs.
+ *
+ * A single candidate is returned without a prompt: unlike a repository *binding*, which
+ * always requires an explicit yes, selecting which handoff to inspect changes nothing on
+ * its own — the binding confirmation still happens downstream.
+ */
+export async function selectDelegatedHandoff(deps, handoffs) {
+    if (handoffs.length === 0)
+        return null;
+    if (handoffs.length === 1)
+        return handoffs[0];
+    deps.stderr("");
+    deps.stderr("Outstanding handoff links:");
+    handoffs.forEach((h, i) => {
+        deps.stderr(`  ${String(i + 1).padStart(2, " ")}. ${handoffLabel(h)}`);
+    });
+    deps.stderr("");
+    // No default: a stray Enter must not pick one.
+    const answer = (await deps.promptLine(`Choose a handoff [1-${handoffs.length}]: `)).trim();
+    const index = Number(answer);
+    if (!/^\d+$/.test(answer) || !Number.isInteger(index) || index < 1 || index > handoffs.length) {
+        return null;
+    }
+    return handoffs[index - 1];
+}
+/**
+ * Look up an outstanding handoff and continue it (AC-4, AC-6).
+ *
+ * Status-only, never polling: a delegated handoff waits on a person who may take days,
+ * so blocking a terminal on it would be useless. The admin re-runs this when they are
+ * told the other half is done.
+ */
+export async function runGithubHandoffResumeFlow(deps, api, repoName) {
+    const listed = await listGithubHandoffs(api, repoName);
+    if (!listed.ok) {
+        return reportNoConnection(deps, FAILURE_MESSAGES[listed.kind]);
+    }
+    if (listed.value.length === 0) {
+        return reportNoConnection(deps, "No handoff links exist for this project. Run connect-github --handoff to create one.");
+    }
+    const selected = await selectDelegatedHandoff(deps, listed.value);
+    if (!selected) {
+        return reportNoConnection(deps, "No handoff was selected.");
+    }
+    if (selected.status === "connected") {
+        deps.stdout(`Connected ${selected.githubRepoName ?? repoName}.`);
+        return 0;
+    }
+    if (selected.status === "awaiting-organization-approval") {
+        // R-6: this is genuinely in-flight, not a failure — the link stays live until its
+        // deadline, and approval may still land. Reported as a live state (exit 0) so a
+        // scripted caller does not treat "waiting on a human" as an error.
+        deps.stderr("");
+        deps.stderr("The install was sent to a GitHub organization owner for approval, and that " +
+            "approval has not happened yet.");
+        deps.stderr("GitHub does not notify Bridge when it lands, so re-run connect-github --resume " +
+            "once the owner has approved it.");
+        if (selected.expiresAt) {
+            deps.stderr(`The link stays usable until ${formatExpiry(selected.expiresAt)}.`);
+        }
+        return 0;
+    }
+    if (selected.status !== "staged") {
+        const message = HANDOFF_STATUS_MESSAGES[selected.status] ?? HANDOFF_STATUS_MESSAGES.failed;
+        if (selected.status === "pending" || selected.status === "expired") {
+            // AC-8 fallback. Bridge cannot safely discover an existing installation on an org
+            // it was never called back about, so this deliberately does NOT claim to have
+            // detected one — it points at the documented manual path instead.
+            deps.stderr("");
+            deps.stderr(message);
+            deps.stderr("If the GitHub App is already installed on that organization, GitHub may not " +
+                "send Bridge a callback at all. In that case follow the manual installation-ID " +
+                "steps in the GitHub App setup guide (docs/install/github-app.md).");
+            // `pending` is a live state, not a failure; `expired` is terminal.
+            return selected.status === "pending" ? 0 : 1;
+        }
+        return reportNoConnection(deps, message);
+    }
+    // Staged: reuse the existing candidate flow verbatim — same labels, same picker, same
+    // explicit [y/N] on a single candidate. A delegated handoff gets no auto-bind shortcut.
+    const candidates = selected.candidates;
+    if (candidates.length === 0) {
+        return reportNoConnection(deps, OUTCOME_MESSAGES["no-repositories"]);
+    }
+    const chosen = await chooseCandidate(deps, candidates);
+    if (!chosen)
+        return 1;
+    const confirmed = await confirmGithubConnection(api, repoName, selected.state, chosen.github_repository_id);
+    if (!confirmed.ok) {
+        return reportNoConnection(deps, FAILURE_MESSAGES[confirmed.kind]);
+    }
+    deps.stdout(`Connected ${confirmed.value.githubRepoFullName ?? confirmed.value.githubRepoName}.`);
+    if (confirmed.value.indexingStatus === "started") {
+        deps.stdout("Indexing started automatically.");
+    }
+    else if (confirmed.value.indexingStatus === "waiting-for-setup") {
+        deps.stdout("Indexing will start automatically once setup completes.");
+    }
+    return 0;
+}
+/** Invalidate an outstanding handoff (R-5). */
+export async function runGithubHandoffRevokeFlow(deps, api, repoName) {
+    const listed = await listGithubHandoffs(api, repoName);
+    if (!listed.ok) {
+        return reportNoRevocation(deps, FAILURE_MESSAGES[listed.kind]);
+    }
+    const revocable = listed.value.filter((h) => REVOCABLE_STATUSES.has(h.status));
+    if (revocable.length === 0) {
+        return reportNoRevocation(deps, "There are no handoff links left to revoke.");
+    }
+    const selected = await selectDelegatedHandoff(deps, revocable);
+    if (!selected) {
+        return reportNoRevocation(deps, "No handoff was selected.");
+    }
+    const revoked = await revokeGithubHandoff(api, repoName, selected.state);
+    if (!revoked.ok) {
+        return reportNoRevocation(deps, FAILURE_MESSAGES[revoked.kind]);
+    }
+    deps.stdout(revoked.value === "already-revoked"
+        ? "That handoff link was already revoked."
+        : "Handoff link revoked. It can no longer be used.");
+    return 0;
+}
+function reportNoRevocation(deps, detail) {
+    deps.stderr("");
+    deps.stderr("Nothing was revoked.");
+    deps.stderr(detail);
+    return 1;
+}
+// ---------------------------------------------------------------------------
 // Process boundary
 // ---------------------------------------------------------------------------
 /**
@@ -386,14 +658,22 @@ export async function runConnectGithubCli(argv, injected) {
             deps.stdout(USAGE);
             return 0;
         }
-        // Checked BEFORE minting: this flow always ends in a human choice, so a
+        const mintOnly = parsed.value.handoff;
+        // Checked BEFORE minting: these flows always end in a human choice, so a
         // non-interactive run can only ever strand a code it can never confirm.
-        if (!deps.isTTY) {
+        //
+        // `--handoff` is the one exception (BAPI-686), and only because the premise no
+        // longer holds for it: it ends at a printed URL, not at a prompt, and it strands
+        // nothing because handoffs are discoverable server-side afterwards via --resume.
+        // --resume and --revoke both still prompt, so they keep the gate.
+        if (!deps.isTTY && !mintOnly) {
             deps.stderr("connect-github needs an interactive terminal: it asks you to confirm which " +
                 "repository to connect. Run it directly in your terminal.");
             return 1;
         }
-        const repo = await resolveConnectGithubRepoName(parsed.value, deps);
+        const repo = mintOnly
+            ? resolveHandoffRepoName(parsed.value, deps)
+            : await resolveConnectGithubRepoName(parsed.value, deps);
         if (!repo.ok) {
             deps.stderr(repo.error);
             return 1;
@@ -415,6 +695,12 @@ export async function runConnectGithubCli(argv, injected) {
             baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
             apiKey: cred.credentials.apiKey,
         };
+        if (parsed.value.handoff)
+            return await runGithubHandoffMintFlow(deps, api, repo.value);
+        if (parsed.value.resume)
+            return await runGithubHandoffResumeFlow(deps, api, repo.value);
+        if (parsed.value.revoke)
+            return await runGithubHandoffRevokeFlow(deps, api, repo.value);
         return await runGithubConnectionFlow(deps, api, repo.value);
     }
     catch {