@bridge_gpt/mcp-server 0.2.30 → 0.2.32

package/build/install-bridge.js

@@ -19,11 +19,17 @@
  *           (R5). Halt on failure — so a bad key never lands in the config and
  *           traps later retries behind overwrite-consent.
  *   Step 3  Write the per-host MCP config (.mcp.json / .cursor/mcp.json /
- *           .vscode/mcp.json) with REAL values (BAPI_REPO_NAME / BAPI_API_KEY /
- *           BAPI_BASE_URL / BAPI_DOCS_DIR), read-merge-write so unrelated servers
- *           survive, pinning the launcher to the exact running version. Detected
- *           Windsurf / Codex (global configs we never write into automatically)
- *           get printed manual instructions.
+ *           .vscode/mcp.json), read-merge-write so unrelated servers survive,
+ *           pinning the launcher to the exact running version. A VALID, UNTRACKED
+ *           (freshly-gitignored) config receives REAL values (BAPI_REPO_NAME /
+ *           BAPI_API_KEY / BAPI_BASE_URL / BAPI_DOCS_DIR). A git-TRACKED config
+ *           receives the real key only after an explicit default-No TTY consent —
+ *           otherwise (interactive decline or any non-TTY run) the SECRET-FREE
+ *           entry (no BAPI_API_KEY; the server self-resolves it) so the key is
+ *           never committed on the next push. An INVALID (present-but-unparseable)
+ *           config is left byte-identical and reported with manual-merge
+ *           instructions (BAPI-666). Detected Windsurf / Codex (global configs we
+ *           never write into automatically) get printed manual instructions.
  *   Step 4  Persist the routing credential to the user-scoped store
  *           (`~/.config/bridge/credentials.json`, target `bapi:<repo>`) via
  *           `upsertBapiCredential`. Non-blocking (fail-open) — mirrors Stage 6.
@@ -87,13 +93,24 @@
  * that can replay a redemption, so a successful exchange with a failed local write
  * would leave an unrecoverable admin key and a permanently spent invite.
  *
+ * SELF-SERVE REPLAY (BAPI-667) — the self-serve arm is the one place the CLI both
+ * creates AND holds the invite token, so it is the one place a retry cannot ask the
+ * user to re-present it. Its pending record therefore additionally stores the minted
+ * token, and a self-serve run LOOKS THAT RECORD UP BEFORE MINTING: a resumable
+ * record short-circuits the mint entirely and re-drives the same exchange. A fresh
+ * mint is reachable only after the replayed token draws a conclusive 401 AND the
+ * user explicitly consents to discard the stored record.
+ *
  * SECRET DISCIPLINE: THREE secrets now — the API key, the bootstrap-invite token,
  * and the client-generated `key_secret`. NONE is ever printed or logged — not in
  * stdout, stderr, error messages, or --dry-run output (they are redacted to
  * `<REDACTED>`). The ONLY places a secret is durably written are the per-host MCP
  * config (Step 3, gitignored) and the user-scoped credential store (Step 4 / the
- * pending record). The bootstrap-invite token itself is NEVER written to disk —
- * only a SHA-256 fingerprint of it, to key the pending record.
+ * pending record). A USER-SUPPLIED bootstrap-invite token is never written to disk —
+ * only a SHA-256 fingerprint of it, to key the pending record. An INTERNALLY MINTED
+ * self-serve token is the sole exception (BAPI-667): it is stored inside the same
+ * 0600, fsync'd pending record as the `key_secret`, purely so the signup can be
+ * replayed, and it is discarded when that record is promoted.
  */
 import { readFile, writeFile, mkdir, stat, rename, chmod, unlink, open } from "fs/promises";
 import { spawn } from "child_process";
@@ -109,7 +126,7 @@ import { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host
 import { writeMcpInstallState } from "./mcp-install-state.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
-import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, resolveBapiCredentials, } from "./credential-store.js";
+import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPendingCredential, repointBootstrapPendingCredential, promoteBootstrapPendingCredential, lookupSelfServeBootstrapPendingCredential, discardBootstrapPendingCredential, getBootstrapPendingTarget, resolveBapiCredentials, } from "./credential-store.js";
 // BAPI-631: the optional GitHub connect offer reuses the standalone command's flow and
 // API primitives verbatim — no duplicated polling, browser, or picker logic here.
 import { fetchGithubConfigurationState } from "./connect-github-api.js";
@@ -185,10 +202,29 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "was already configured and zero changes were made, without a fabricated applied count.";
 /** Default base URL when `BAPI_BASE_URL` is unset (mirrors index.ts). */
 export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
+/**
+ * The Bridge web setup page for an ALREADY-normalized base URL (BAPI-669, U8).
+ *
+ * Every message that used to name a page without an address ("Security page",
+ * "setup UI", "Get Started page") now interpolates this, so the guidance is
+ * actionable on the hosted default and on a custom deployment alike. Deliberately
+ * NOT a per-deployment web-path discovery mechanism — that was rejected; `<base>/setup`
+ * is truthful for both. It carries only a URL and never a credential.
+ */
+export function buildInstallBridgeSetupUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/setup`;
+}
 /** Default docs dir when `BAPI_DOCS_DIR` is unset (mirrors index.ts). */
 export const DEFAULT_BAPI_DOCS_DIR = "docs/tmp";
-/** User-facing usage text. */
-export function getInstallBridgeUsage() {
+/**
+ * User-facing usage text.
+ *
+ * `baseUrl` (BAPI-669, U8) makes the API-key guidance name a real address. The CLI
+ * passes the run's VALIDATED, normalized base URL; direct callers (and the parser's
+ * `help` result) get the hosted default.
+ */
+export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
+    const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
     return [
         "Usage:",
         "  npx -y @bridge_gpt/mcp-server@latest install-bridge [flags]",
@@ -204,17 +240,28 @@ export function getInstallBridgeUsage() {
         "step). So not every run applies config fields. Indexing is never asked about —",
         "it starts automatically once the repository reaches full parse readiness.",
         "",
+        "Your API key is written to a project MCP config only when that file is safe: a",
+        "valid, git-ignored config gets the real key, but a config already TRACKED by git",
+        "gets it only after an explicit default-No confirmation (and never at all in a",
+        "non-interactive run) — otherwise a secret-free entry is written and the server",
+        "resolves your key from the credential store at runtime. A config file that",
+        "cannot be parsed is left untouched, with manual-merge instructions printed.",
+        "",
         "Run it bare — `install-bridge` with no flags — in a terminal and it asks",
-        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT.trim()}\` first. Answer yes (or press Enter) for the`,
-        "existing-key flow below; answer no and it asks for an email and creates a new",
-        "Bridge workspace for you (the self-serve flow). That question is asked ONLY for a",
-        "bare interactive run: passing ANY flag, setting BAPI_API_KEY, or running without",
-        "an interactive terminal keeps the existing deterministic behavior and no prompt.",
+        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT}\` first, with three numbered choices:`,
+        ...INSTALL_BRIDGE_ONBOARDING_CHOICES.map((choice) => `  ${choice}`),
+        "There is NO default — pressing Enter selects nothing; you must type 1, 2, or 3",
+        "(one blank or invalid answer re-prompts once, then exits with guidance). Option 1",
+        "is the existing-key flow below, option 2 is the bootstrap-invite flow, and option 3",
+        "prompts for an email and creates a brand-new Bridge workspace for you (the",
+        "self-serve flow). That question is asked ONLY for a bare interactive run: passing",
+        "ANY flag, setting BAPI_API_KEY, or running without an interactive terminal keeps",
+        "the existing deterministic behavior and no prompt.",
         "",
         "Inputs (the only two irreducible ones):",
         "  --api-key <key>   Bridge API key OR bootstrap invite. Falls back to the",
         "                    BAPI_API_KEY env var, then an interactive (no-echo) prompt.",
-        "                    Generate a key in the Bridge API web UI Security page — this",
+        `                    Generate a key at ${setupUrl} (Security page) — this`,
         "                    command consumes a key, it does not create one. A value",
         "                    detected as a bootstrap invite (bapi_inv_…), from any of the",
         "                    three sources above, is instead redeemed to CREATE a new",
@@ -232,7 +279,7 @@ export function getInstallBridgeUsage() {
         "                    non-interactive). In the existing-key flow it MUST match the",
         "                    server-side repo registration (it keys the credential store",
         "                    as bapi:<repo>). In either new-project flow (--email,",
-        "                    --invite, or a negative answer to the key question above) it",
+        "                    --invite, or chooser option 2 or 3 above) it",
         "                    instead NAMES the project this run creates, so you are asked",
         "                    to name a new project rather than match an existing one; the",
         "                    name must be globally unique.",
@@ -243,14 +290,22 @@ export function getInstallBridgeUsage() {
         "                    It requests a fresh workspace for that email, then creates",
         "                    the project and mints your own admin API key in one command.",
         "                    Falls back to the BAPI_SIGNUP_EMAIL env var, then a visible",
-        "                    interactive prompt — which is also what a negative answer to",
-        "                    the bare-run key question above reaches. The email is NOT a",
+        "                    interactive prompt — which is also what chooser option 3 on a",
+        "                    bare run reaches. The email is NOT a",
         "                    secret (it is shown as you type), but it is never printed to",
         "                    a log. Mutually",
         "                    exclusive with --api-key and --invite. No email verification",
         "                    is performed and no message is sent to the address — it only",
         "                    labels the new workspace.",
         "",
+        "                    RESUMABLE: a self-serve run that fails mid-protocol saves its",
+        "                    signup state under bootstrap-pending:<repo> in the credential",
+        "                    store. Re-running the self-serve flow RESUMES that attempt —",
+        "                    it does not sign up again — so a retry never creates a second",
+        "                    workspace. Never copy, display, or hand-remove that record; if",
+        "                    the saved invite has genuinely expired the CLI asks before",
+        "                    discarding it.",
+        "",
         "Bootstrap-invite onboarding (no web UI, no pre-existing key):",
         "  --invite [token]  Redeem a bootstrap invite you were already given: creates",
         "                    the project and mints your own admin API key in one command.",
@@ -289,7 +344,10 @@ export function getInstallBridgeUsage() {
         "                                launches nothing.",
         "  --force                       Overwrite an existing real BAPI_API_KEY in a",
         "                                host config (or in the credential store) without",
-        "                                prompting.",
+        "                                prompting. It does NOT bypass the git-tracked",
+        "                                config safeguard below: --force authorizes",
+        "                                replacing a credential, not disclosing your key",
+        "                                into version control.",
         "  --dry-run                     Preview every step (scaffold targets, config",
         "                                files + keys with the key REDACTED, ping",
         "                                target, credential target, and the consent-gated",
@@ -300,12 +358,15 @@ export function getInstallBridgeUsage() {
         "  --agent claude|cursor-agent   Explicit launch override for the post-install",
         "                                session — it always wins, and there is NO Claude",
         "                                default. Without it the launch tool is derived",
-        "                                from your selection: Claude Code opens `claude`,",
-        "                                Cursor opens `cursor-agent`; if several launchable",
-        "                                tools are selected the wizard asks which single one",
-        "                                to open; and a selection whose tools have no",
-        "                                agentic CLI (e.g. Copilot) opens nothing and prints",
-        "                                how to finish configuring later.",
+        "                                from your selection: Claude Code opens `claude`.",
+        "                                Cursor is NOT auto-opened (its cursor-agent CLI",
+        "                                first-run workspace-trust prompt collapses a spawned",
+        "                                session); selecting Cursor writes .cursor/mcp.json",
+        "                                and prints how to finish by running /install-bridge",
+        "                                in a new Cursor session. A selection whose tools have",
+        "                                no agentic CLI (e.g. Copilot) likewise opens nothing",
+        "                                and prints how to finish configuring later. Passing",
+        "                                --agent cursor-agent still force-spawns it.",
         "  -h, --help                    Show this help.",
         "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
@@ -561,6 +622,25 @@ export function promptSecretViaReadline(promptText, input = process.stdin, outpu
         muted = true;
     });
 }
+/**
+ * The deferral command printed with the GitHub offer (BAPI-669, U6). Declining is
+ * cheap precisely because this exists — the connection is a standalone command.
+ */
+export const INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND = "npx -y @bridge_gpt/mcp-server connect-github";
+/**
+ * The `Step 4b` label + purpose + deferral lines printed immediately before the
+ * GitHub prompt (BAPI-669, U6). Shared with {@link buildLaunchStepPreview} so the
+ * live run and the `--dry-run` preview can never advertise different behavior.
+ */
+export const INSTALL_BRIDGE_GITHUB_OFFER_CONTEXT = [
+    "",
+    "Step 4b — optional: connect GitHub.",
+    "  This installs the Bridge GitHub App so pull requests and code review work. It opens",
+    "  github.com in your browser; no GitHub credential is shared with Bridge.",
+    `  You can do this later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
+];
+/** Default-No GitHub offer prompt (BAPI-669, U6 — flipped from the old `(Y/n)`). */
+export const INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT = "Connect GitHub? [y/N]: ";
 /**
  * Offer to connect GitHub, if it is not already connected (BAPI-631).
  *
@@ -571,7 +651,7 @@ export function promptSecretViaReadline(promptText, input = process.stdin, outpu
  * Reuses the shared connect-github flow rather than duplicating the API, polling,
  * browser, or picker logic — there is exactly one implementation of that handshake.
  */
-async function offerGithubConnection(repoName, deps, log) {
+export async function offerGithubConnection(repoName, baseUrl, deps, log) {
     // No prompt surface → no offer. Never assume consent on a non-interactive run.
     if (!deps.isTTY || !deps.promptLine)
         return;
@@ -592,8 +672,11 @@ async function offerGithubConnection(repoName, deps, log) {
         if (!cred.ok)
             return;
         const api = {
+            // BAPI-668 (R9-2): the ALREADY-VALIDATED base URL is passed in. This helper
+            // deliberately no longer re-derives it from `deps.env` — normalization has
+            // exactly one point, at the CLI entry boundary.
             fetch: deps.fetch,
-            baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
+            baseUrl,
             apiKey: cred.credentials.apiKey,
         };
         const state = await fetchGithubConfigurationState(api, repoName);
@@ -605,8 +688,14 @@ async function offerGithubConnection(repoName, deps, log) {
             log("  note: could not read GitHub configuration status; skipping the GitHub offer.");
             return;
         }
-        const answer = (await deps.promptLine("Connect GitHub? (Y/n): ")).trim().toLowerCase();
-        if (answer === "n" || answer === "no")
+        // BAPI-669 (U6): explain the action BEFORE asking, and default to No. Opening a
+        // browser is a side effect the user should opt IN to, so a bare Enter now skips.
+        for (const line of INSTALL_BRIDGE_GITHUB_OFFER_CONTEXT)
+            log(line);
+        const answer = (await deps.promptLine(INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT)).trim().toLowerCase();
+        // Only an explicit yes proceeds — blank input, EOF, "n", and anything malformed
+        // all skip without opening a browser.
+        if (answer !== "y" && answer !== "yes")
             return; // declining is a normal outcome
         const connectDeps = createDefaultConnectGithubDeps();
         const code = await runGithubConnectionFlow(connectDeps, api, repoName);
@@ -735,11 +824,20 @@ export function createDefaultInstallBridgeDeps() {
         prepareBootstrapPending: prepareBootstrapPendingCredential,
         repointBootstrapPending: repointBootstrapPendingCredential,
         promoteBootstrapPending: promoteBootstrapPendingCredential,
+        lookupSelfServeBootstrapPending: lookupSelfServeBootstrapPendingCredential,
+        discardBootstrapPending: discardBootstrapPendingCredential,
         buildShellCommand: buildGenericAgentShellCommand,
         spawnTerminalTab: getDefaultSpawnTerminalTabForPlatform(process.platform),
         startTicketsDeps: createDefaultStartTicketsDeps(),
         log: (m) => console.log(m),
         errorLog: (m) => console.error(m),
+        // Debug-only sink (BAPI-666): gated on BAPI_INSTALL_DEBUG so it is silent on a
+        // normal install and never pollutes stdout/stderr. Emits to stderr (never
+        // stdout) so any diagnostic can never be mistaken for machine-readable output.
+        debugLog: (m) => {
+            if (process.env.BAPI_INSTALL_DEBUG)
+                console.error(m);
+        },
     };
 }
 /**
@@ -747,6 +845,10 @@ export function createDefaultInstallBridgeDeps() {
  * interactive no-echo prompt. Fails (secret-free) when none is available and
  * stdin is non-interactive.
  *
+ * Returns WHICH source won alongside the value (BAPI-668, R11-1), so a rejected
+ * credential can name where it came from. The source is a safe label; the value
+ * is never printed anywhere.
+ *
  * Despite the name, this is CREDENTIAL-AGNOSTIC (BAPI-661): the returned value may
  * be a full Bridge API key or a bootstrap-invite token (`bapi_inv_…`) — the caller
  * classifies it with {@link classifyEnteredCredential} immediately after this
@@ -756,27 +858,29 @@ export function createDefaultInstallBridgeDeps() {
  */
 export async function resolveApiKey(options, deps) {
     if (typeof options.apiKey === "string" && options.apiKey.trim().length > 0) {
-        return { ok: true, value: options.apiKey.trim() };
+        return { ok: true, value: options.apiKey.trim(), source: "flag" };
     }
     const fromEnv = deps.env.BAPI_API_KEY;
     if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
-        return { ok: true, value: fromEnv.trim() };
+        return { ok: true, value: fromEnv.trim(), source: "env" };
     }
     if (deps.isTTY && deps.promptSecret) {
         const entered = (await deps.promptSecret("Bridge API key or invite (input hidden): ")).trim();
         if (entered.length > 0) {
-            return { ok: true, value: entered };
+            return { ok: true, value: entered, source: "prompt" };
         }
+        // BAPI-667: the old copy ended with "try the hidden prompt again", which was
+        // simply false — the process exits here, so there is no prompt left to retry —
+        // and it named no route usable by someone who has no key at all.
         return {
             ok: false,
-            error: "No Bridge API key or invite entered. Pass --api-key, set the BAPI_API_KEY environment " +
-                "variable, or try the hidden prompt again.",
+            error: `No Bridge API key or invite entered. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
     return {
         ok: false,
-        error: "A Bridge API key or invite is required. Pass --api-key or set the BAPI_API_KEY " +
-            "environment variable (no interactive terminal is available to prompt for it).",
+        error: "A Bridge API key or invite is required (no interactive terminal is available to prompt " +
+            `for it). ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
     };
 }
 /**
@@ -881,8 +985,40 @@ export function resolveInstallBridgeOnboardingBranch(options, env) {
         return { kind: "need-key", method: "self-serve" };
     return { kind: "have-key" };
 }
-/** The exact visible text of the bare-TTY onboarding selector (BAPI-626, BAPI-661). */
-export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key or invite? [Y/n] ";
+/**
+ * The bare-TTY onboarding chooser (BAPI-667), replacing the BAPI-626/661 Y/n
+ * question. The old prompt defaulted a bare Enter to "yes" and dropped the newest
+ * users — the ones with no key, no invite, and no account — into a hidden API-key
+ * prompt they could not answer, then exited. The self-serve path built for exactly
+ * that user was never named. The chooser names all three routes and has NO default,
+ * so Enter can no longer route anyone into a prompt they cannot satisfy.
+ *
+ * Interaction contract mirrors the BAPI-663 tool picker: render the heading and the
+ * numbered options once, accept ONE strict line.
+ */
+export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "How would you like to connect to Bridge API?";
+/** The chooser's numbered options, in render order. Index + 1 is the accepted token. */
+export const INSTALL_BRIDGE_ONBOARDING_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",
+];
+/** The single-line answer prompt drawn after the options (no bracketed default). */
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT = "Enter 1, 2, or 3: ";
+/** The one hint line printed after a blank/invalid answer, before the single re-prompt. */
+export const INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT = "Enter 1, 2, or 3.";
+/**
+ * The one place the "no usable credential" copy lives (BAPI-667, U1-3).
+ *
+ * Centralized because the chooser failure and {@link resolveApiKey}'s two failure
+ * branches previously drifted: only one of them mentioned self-serve, and one
+ * advised "try the hidden prompt again" — false, because the process has already
+ * exited by the time the user reads it. All three now name the SAME three routes.
+ */
+export const INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE = "Re-run install-bridge and choose an option: pass --api-key <key> if you have a Bridge API " +
+    "key (or set BAPI_API_KEY), --invite if you were sent an invite token, or --email <addr> " +
+    "to sign up with just an email — on a bare interactive run, re-run and choose option 3 to " +
+    "sign up with just an email.";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
  *
@@ -903,6 +1039,13 @@ export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key
  * A prompt failure becomes a typed, secret-free failure rather than an exception:
  * the caller turns it into an exit code, and terminal/internal error text never
  * reaches the user.
+ *
+ * BAPI-667 replaced the Y/n question with a three-option chooser. Two properties
+ * are load-bearing: there is NO default (a bare Enter can no longer route a
+ * brand-new user into the hidden key prompt), and option 3 names the self-serve
+ * route explicitly so it is discoverable without reading `--help`. Validation is
+ * bounded to ONE re-prompt — an unanswerable prompt that loops is the same
+ * dead-end in a different costume.
  */
 export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
     const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
@@ -916,30 +1059,39 @@ export async function resolveInstallBridgeOnboardingBranchForRun(options, deps,
     }
     const promptLine = deps.promptLine;
     try {
-        // Bounded so a prompt seam that returns the same invalid value forever (a
-        // misbehaving pipe that passes the TTY check) cannot spin indefinitely.
-        for (let attempt = 0; attempt < 5; attempt += 1) {
-            const answer = (await promptLine(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT)).trim().toLowerCase();
-            // Blank = accept the bracketed default (Y), matching the prompt's own contract.
-            if (answer.length === 0 || answer === "y" || answer === "yes") {
+        // Render the heading + options EXACTLY once; a re-prompt after an invalid
+        // answer re-asks the question without redrawing the list (BAPI-663 contract).
+        deps.log(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT);
+        for (const choice of INSTALL_BRIDGE_ONBOARDING_CHOICES)
+            deps.log(choice);
+        // Bounded to two reads total: the first answer, then ONE re-prompt after a
+        // single hint line. EOF resolves as an empty answer (promptLineViaReadline
+        // resolves "" on close), so it costs one re-prompt and then fails cleanly —
+        // it can never hang or silently select a branch.
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const answer = (await promptLine(INSTALL_BRIDGE_ONBOARDING_CHOICE_PROMPT)).trim();
+            // Option 1 stays credential-agnostic: a `bapi_inv_…` value pasted into the
+            // hidden key prompt is still reclassified downstream (BAPI-661).
+            if (answer === "1")
                 return { ok: true, branch: { kind: "have-key" } };
+            if (answer === "2") {
+                return { ok: true, branch: { kind: "need-key", method: "bootstrap-invite" } };
             }
-            if (answer === "n" || answer === "no") {
+            if (answer === "3")
                 return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
-            }
-            deps.log("Please answer y or n (press Enter for yes).");
+            if (attempt === 0)
+                deps.log(INSTALL_BRIDGE_ONBOARDING_CHOICE_HINT);
         }
         return {
             ok: false,
-            error: "No valid answer to the Bridge API key question. Re-run and answer y or n.",
+            error: `No option was selected. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
     catch {
         // Secret-free by construction: the caught value is never surfaced.
         return {
             ok: false,
-            error: "Could not read your answer from the terminal. Re-run with --api-key <key> if you have a " +
-                "Bridge API key, or --email <addr> to create a new Bridge workspace.",
+            error: `Could not read your answer from the terminal. ${INSTALL_BRIDGE_ENTRY_ROUTES_ADVICE}`,
         };
     }
 }
@@ -1131,18 +1283,37 @@ export async function resolveSelectedHostPlatforms(deps, options) {
         legacy.push("copilot-vscode");
     return HOST_PLATFORM_ORDER.filter((id) => legacy.includes(id));
 }
+/**
+ * Launch agents install-bridge will NEVER auto-spawn from a host SELECTION, even
+ * though their CLI exists and the host's MCP config is still written normally.
+ *
+ * `cursor-agent` is excluded: its FIRST-RUN workspace-trust handshake collapses
+ * under our osascript-spawned launch — the "Workspace Trust Required" dialog
+ * renders, then the process exits before a selection registers, so configuration
+ * never runs (reproduced on a pristine, never-trusted workspace; the identical
+ * command works only where Cursor already trusts the directory). The trust gate is
+ * cursor-agent's own behavior on an untrusted workspace and is not something our
+ * launch can drive, so we treat Cursor as a no-auto-launch host: selecting it
+ * still writes `.cursor/mcp.json`, then prints the manual `/install-bridge`
+ * continuation (same path as Copilot/Codex/Windsurf, which have no agentic CLI).
+ * An explicit `--agent cursor-agent` override still spawns it — a deliberate,
+ * documented power-user opt-in that bypasses this selection guard.
+ */
+const SELECTION_NON_LAUNCHABLE_AGENTS = new Set(["cursor-agent"]);
 /**
  * Resolve the post-install launch decision from the selected host platforms and an
  * OPTIONAL explicit `--agent` override (BAPI-657). Pure and total:
  *
  *  - An explicit `--agent` is an ABSOLUTE override (ratified AC-4): a valid explicit
  *    agent always returns `spawn(agent)`, regardless of which tools were selected —
- *    the flag is honored even for a host outside the selection.
+ *    the flag is honored even for a host outside the selection, and it bypasses the
+ *    {@link SELECTION_NON_LAUNCHABLE_AGENTS} guard below.
  *  - Otherwise the selection drives it: map each selected host through
- *    {@link agentForPlatform}, drop non-launchable hosts, dedup in registry order,
- *    then return `manual("empty-selection")` for an empty selection,
- *    `manual("no-launchable-agent")` for zero launchable agents, `spawn` for one, or
- *    `choose-one` for more than one.
+ *    {@link agentForPlatform}, drop hosts that are non-launchable OR excluded from
+ *    selection auto-spawn ({@link SELECTION_NON_LAUNCHABLE_AGENTS}, e.g. Cursor),
+ *    dedup in registry order, then return `manual("empty-selection")` for an empty
+ *    selection, `manual("no-launchable-agent")` for zero launchable agents, `spawn`
+ *    for one, or `choose-one` for more than one.
  *
  * Never prompts, logs, resolves an {@link AgentSpec}, or touches the filesystem.
  */
@@ -1158,8 +1329,9 @@ export function resolveInstallBridgeLaunchDecision(selectedPlatforms, explicitAg
         if (!selectedPlatforms.includes(id))
             continue;
         const agent = agentForPlatform(id);
-        if (agent && !agents.includes(agent))
+        if (agent && !SELECTION_NON_LAUNCHABLE_AGENTS.has(agent) && !agents.includes(agent)) {
             agents.push(agent);
+        }
     }
     if (agents.length === 0)
         return { kind: "manual", reason: "no-launchable-agent" };
@@ -1171,12 +1343,17 @@ export function resolveInstallBridgeLaunchDecision(selectedPlatforms, explicitAg
  * The human-facing tool label for a launch agent, derived by scanning the host
  * registry's {@link HostTargetDefinition.launchAgent} metadata rather than keeping a
  * duplicate agent→label map (BAPI-657). Returns e.g. `"Claude Code"` for `"claude"`
- * and `"Cursor"` for `"cursor-agent"`, falling back to the raw agent name if no host
- * advertises it (never expected for a registered launch agent).
+ * and `"Cursor"` for `"cursor-agent"`.
+ *
+ * BAPI-669 (U3): the fallback is NEUTRAL rather than the raw agent binary name. This
+ * function's output is user-facing copy ("open a session in …"), so an unregistered
+ * agent must degrade to generic prose instead of leaking a binary name into a
+ * sentence that reads as a product name. Never expected for a registered agent.
  */
+export const UNKNOWN_LAUNCH_TOOL_LABEL = "your AI coding tool";
 export function toolLabelForLaunchAgent(agent) {
     const target = allHostTargets().find((t) => t.launchAgent === agent);
-    return target?.label ?? agent;
+    return target?.label ?? UNKNOWN_LAUNCH_TOOL_LABEL;
 }
 /**
  * Interactive numbered chooser for when MORE THAN ONE launchable tool was selected
@@ -1246,7 +1423,7 @@ export function buildManualInstallBridgeContinuation(kind, toolLabels) {
     const toolPhrase = formatToolLabelPhrase(toolLabels);
     return [
         `To finish configuring this project, open it in ${toolPhrase} that has the`,
-        "Bridge MCP server configured and run /install-bridge.",
+        "Bridge MCP server configured, start a new session, and run /install-bridge.",
         "Until the project is configured, your Bridge MCP tools stay limited.",
     ].join("\n");
 }
@@ -1401,58 +1578,244 @@ export function buildInstallBridgeServerEntry(cwd, repoName, apiKey, baseUrl, do
     };
     return { command: entry.command, args: entry.args, env };
 }
-/** Read + parse an existing host config; `null` if absent/unparseable. */
+/**
+ * Build the per-host `bridge-api` MCP entry WITHOUT an API key (BAPI-666). Same
+ * version-pinned launcher and non-secret env (repo name, base URL, docs dir,
+ * project root) as {@link buildInstallBridgeServerEntry}, but `BAPI_API_KEY` is
+ * OMITTED ENTIRELY — never set to `YOUR_API_KEY` or `<REDACTED>`. A placeholder
+ * key literal in the config would OVERRIDE credential-store resolution at runtime,
+ * so the key is left absent and the server self-resolves it from the environment
+ * or the user-scoped store. This is the safe entry for a git-tracked target the
+ * user declined (or could not be prompted) to write a real key into.
+ */
+export function buildInstallBridgeSecretFreeServerEntry(cwd, repoName, baseUrl, docsDir) {
+    const entry = buildBridgeApiEntry(cwd);
+    const env = {
+        ...entry.env,
+        BAPI_REPO_NAME: repoName,
+        BAPI_BASE_URL: baseUrl,
+        BAPI_DOCS_DIR: docsDir,
+    };
+    // buildBridgeApiEntry is already secret-free; delete defensively so a future
+    // change to the scaffold entry can never smuggle a key into the secret-free path.
+    delete env.BAPI_API_KEY;
+    return { command: entry.command, args: entry.args, env };
+}
+/**
+ * Fixed, secret-free credential-store guidance (BAPI-666). Names the resolved
+ * user-scoped credentials path and the safe target id `bapi:<repoName>` so a user
+ * whose config did not receive the real key knows exactly where the server WILL
+ * resolve it from at runtime. Carries no API key, invite, or `key_secret` value.
+ */
+function formatCredentialStoreGuidance(repoName, credentialStorePath) {
+    return [
+        "  The bridge-api server resolves your key at runtime from the BAPI_API_KEY environment",
+        `  variable or the user-scoped credential store (${credentialStorePath}, target`,
+        `  bapi:${repoName}), so it stays out of this file entirely.`,
+    ];
+}
+/**
+ * Render the secret-free `bridge-api` entry as a MERGE-ME snippet for one host
+ * target (BAPI-666). Uses the target's real root key (`mcpServers` for Claude /
+ * Cursor, `servers` for VS Code) and the secret-free entry ONLY, so the API key
+ * can never enter the generated snippet. The snippet is for MERGING into the
+ * existing file — never for replacing it.
+ */
+function formatSecretFreeManualMerge(relPath, topLevelKey, secretFreeEntry) {
+    const snippet = JSON.stringify({ [topLevelKey]: { "bridge-api": secretFreeEntry } }, null, 2);
+    return [
+        `  To configure ${relPath} by hand, MERGE this secret-free entry into the existing`,
+        "  file (do not replace the file):",
+        snippet,
+    ];
+}
+/**
+ * Fixed, secret-free wording for a present-but-unparseable host config (BAPI-666).
+ * Names only the relative path and states it was left untouched — never the raw
+ * content or the caught parser/filesystem exception text.
+ */
+function formatInvalidConfigNotice(relPath) {
+    return `  ${relPath} could not be parsed safely — it was left untouched.`;
+}
+/**
+ * Read + classify an existing host config into `absent | invalid | parsed`
+ * (BAPI-666). Only an `ENOENT` read failure is `absent`; every other read error,
+ * JSON parse failure (comments, trailing commas, truncation), and a `null` /
+ * array / non-object JSON root is `invalid` so an unreadable-but-present file is
+ * never overwritten as though it were missing.
+ */
 async function readHostConfig(deps, fullPath) {
     let raw;
     try {
         raw = await deps.readFile(fullPath);
     }
-    catch {
-        return null;
-    }
+    catch (err) {
+        // A missing file is the only benign, freshly-writable state. Any other read
+        // failure (permissions, I/O) is treated as `invalid` so we never clobber a
+        // present-but-unreadable file. Do NOT carry the exception text forward.
+        if (err?.code === "ENOENT")
+            return { state: "absent" };
+        return { state: "invalid" };
+    }
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        return parsed && typeof parsed === "object" ? parsed : null;
+        parsed = JSON.parse(raw);
     }
     catch {
-        return null;
+        return { state: "invalid" };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { state: "invalid" };
     }
+    return { state: "parsed", config: parsed };
+}
+/** Narrow an unknown value to a plain (non-array) record, else `undefined`. */
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
 }
 /**
  * Detect whether any resolved host config already carries a real (non-placeholder)
  * `BAPI_API_KEY` for the `bridge-api` server — the trigger for overwrite consent.
+ * An `invalid` (present-but-unsafe) config conservatively returns `true` so the
+ * overwrite-consent gate assumes a real key MAY be present rather than silently
+ * replacing a file we could not inspect (BAPI-666).
  */
 async function detectExistingRealKey(deps, targets) {
     for (const target of targets) {
-        const parsed = await readHostConfig(deps, path.join(deps.cwd, target.relPath));
-        const entry = parsed?.[target.topLevelKey]?.["bridge-api"];
-        if (entry?.env && !isPlaceholderApiKey(entry.env.BAPI_API_KEY)) {
+        const result = await readHostConfig(deps, path.join(deps.cwd, target.relPath));
+        if (result.state === "invalid")
+            return true;
+        if (result.state === "absent")
+            continue;
+        const topLevel = asRecord(result.config[target.topLevelKey]);
+        const entry = asRecord(topLevel?.["bridge-api"]);
+        const env = asRecord(entry?.["env"]);
+        if (env && !isPlaceholderApiKey(env["BAPI_API_KEY"])) {
             return true;
         }
     }
     return false;
 }
+/** The fixed, secret-free hard warning shown for a git-tracked project config (BAPI-666). */
+function trackedConfigWarning(relPath) {
+    return `${relPath} is tracked by git — writing your API key here would commit it on your next push`;
+}
+/**
+ * Read-only probe: is `relPath` already tracked by git in the project (BAPI-666)?
+ * Runs `git ls-files --error-unmatch -- <relPath>` through the injected, list-based
+ * command seam (never a shell string) with `cwd = deps.cwd`. ONLY exit code 0 means
+ * tracked; every other outcome — a non-zero exit (untracked / gitignored), a non-git
+ * directory, or a thrown command failure — is treated as NOT tracked, preserving the
+ * required fail-open behavior (a probe failure must never block the install). Emits at
+ * most a fixed debug-level line (safe relative path + exit classification) and never
+ * the command's stdout/stderr, exception text, env, or config content.
+ */
+async function isTrackedProjectConfig(deps, relPath) {
+    try {
+        const result = await deps.startTicketsDeps.runCommand("git", ["ls-files", "--error-unmatch", "--", relPath], { cwd: deps.cwd });
+        if (result.exitCode === 0)
+            return true;
+        deps.debugLog(`install-bridge: git-tracked probe for ${relPath} → not tracked (exit ${result.exitCode})`);
+        return false;
+    }
+    catch {
+        deps.debugLog(`install-bridge: git-tracked probe for ${relPath} → not tracked (probe failed)`);
+        return false;
+    }
+}
+/**
+ * Interactively ask whether to write the REAL API key into a git-tracked config
+ * (BAPI-666). Prints the required hard warning, then a default-No y/N prompt.
+ * Returns `true` ONLY for an explicit `y`/`yes` (trimmed, case-insensitive). A
+ * missing prompt seam, blank / negative / malformed answer, or a prompt exception
+ * all DECLINE. Independent of --force: --force authorizes credential replacement,
+ * not disclosure of the key into version control.
+ */
+async function requestTrackedConfigConsent(deps, relPath) {
+    deps.errorLog(trackedConfigWarning(relPath));
+    if (!deps.promptLine)
+        return false;
+    let answer;
+    try {
+        answer = await deps.promptLine(`Write your API key into ${relPath} anyway? (y/N) `);
+    }
+    catch {
+        return false;
+    }
+    const normalized = (answer ?? "").trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
+}
 /**
  * Write the `bridge-api` entry into each host config via read-merge-write,
- * preserving unrelated servers and top-level keys. Returns the list of written
- * relative paths.
+ * preserving unrelated servers and top-level keys (BAPI-666). Per target:
+ *
+ *  - `invalid` (present but unparseable/unsafe): leave the file byte-identical (no
+ *    mkdir, no write), emit a loud secret-free notice + manual-merge instructions,
+ *    and record it under `skipped`. This is non-fatal — remaining targets continue.
+ *  - tracked by git: write a REAL key only after explicit TTY consent; otherwise
+ *    (interactive decline OR any non-TTY run) write the secret-free entry and print
+ *    the credential-store guidance + `git rm --cached` remediation. Tracked-file
+ *    consent is evaluated only AFTER the invalid check, so a to-be-skipped file
+ *    never receives a misleading write-consent prompt.
+ *  - untracked (the common freshly-gitignored case): write the real key.
  */
-async function writeHostConfigs(deps, targets, entry) {
+async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
     const written = [];
+    const skipped = [];
     for (const target of targets) {
         const fullPath = path.join(deps.cwd, target.relPath);
-        const parsed = (await readHostConfig(deps, fullPath)) ?? {};
-        if (!parsed[target.topLevelKey] || typeof parsed[target.topLevelKey] !== "object") {
-            parsed[target.topLevelKey] = {};
+        const read = await readHostConfig(deps, fullPath);
+        // (Step 5.16) Invalid state is evaluated BEFORE any tracked-file consent so a
+        // file that will be skipped never triggers a misleading write-consent prompt.
+        if (read.state === "invalid") {
+            deps.errorLog(formatInvalidConfigNotice(target.relPath));
+            for (const line of formatSecretFreeManualMerge(target.relPath, target.topLevelKey, entries.secretFree)) {
+                deps.errorLog(line);
+            }
+            skipped.push({ relPath: target.relPath, reason: "invalid" });
+            continue;
         }
-        parsed[target.topLevelKey]["bridge-api"] = entry;
+        // Choose the entry variant. A real key only lands in an untracked target, or a
+        // tracked target the user EXPLICITLY consented to on a TTY.
+        const tracked = trackedState.get(target.relPath) ?? false;
+        let entry = entries.real;
+        let mode = "real-key";
+        if (tracked) {
+            const interactive = deps.isTTY && Boolean(deps.promptLine);
+            const consented = interactive ? await requestTrackedConfigConsent(deps, target.relPath) : false;
+            if (consented) {
+                entry = entries.real;
+                mode = "real-key";
+            }
+            else {
+                entry = entries.secretFree;
+                mode = "secret-free";
+                // A non-TTY run never prompts; surface the same hard warning up front
+                // (requestTrackedConfigConsent already printed it on the interactive path).
+                if (!interactive)
+                    deps.errorLog(trackedConfigWarning(target.relPath));
+                for (const line of formatCredentialStoreGuidance(ctx.repoName, ctx.credentialStorePath)) {
+                    deps.errorLog(line);
+                }
+                deps.errorLog(`  To stop tracking it: git rm --cached -- ${target.relPath}`);
+            }
+        }
+        // Build the document. Preserve everything on a `parsed` config; start fresh only
+        // for `absent` — decided AFTER the safety branches above so an absent file is
+        // never initialized before its tracked-state consent is resolved.
+        const config = read.state === "parsed" ? read.config : {};
+        const topLevel = asRecord(config[target.topLevelKey]) ?? {};
+        topLevel["bridge-api"] = entry;
+        config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
-        await deps.writeFile(fullPath, JSON.stringify(parsed, null, 2) + "\n", {
+        await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
             encoding: "utf-8",
         });
-        written.push(target.relPath);
+        written.push({ relPath: target.relPath, mode });
     }
-    return written;
+    return { written, skipped };
 }
 /**
  * Provision the selected GLOBAL (Codex, Copilot CLI) and MANUAL (Windsurf)
@@ -1461,9 +1824,15 @@ async function writeHostConfigs(deps, targets, entry) {
  * config paths are never added to the repository .gitignore. Returns secret-free
  * log lines and whether Codex was auto-provisioned (so the legacy Codex manual
  * hint can be suppressed).
+ *
+ * `needKey` (BAPI-669, R8) is supplied only in a need-key run. When any selected
+ * target ends up `manual-required` — Windsurf's always-manual path, or a Codex
+ * config that declined an automatic merge — the credential-store line is appended
+ * ONCE for the whole batch, so selecting both does not print it twice.
  */
-async function provisionSelectedGlobalTargets(deps, platforms, entry) {
+async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
     const logLines = [];
+    let anyManualRequired = false;
     const provisionDeps = {
         fs: {
             readFile: deps.readFile,
@@ -1493,6 +1862,7 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry) {
                 logLines.push(`  configured ${target.label} (${outcome.displayPath})`);
                 break;
             case "manual-required":
+                anyManualRequired = true;
                 logLines.push(`  ${target.label}: add the bridge-api MCP server manually to ${outcome.displayPath} ` +
                     "(the API key is redacted in printed instructions).");
                 break;
@@ -1504,6 +1874,9 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry) {
                 break;
         }
     }
+    if (needKey && anyManualRequired) {
+        logLines.push(`  ${formatNeedKeyCredentialStoreLine(needKey.repoName, needKey.credentialStorePath)}`);
+    }
     return logLines;
 }
 /** Build the `/jira/ping` URL exactly like the MCP `ping` tool / buildGetUrl. */
@@ -1521,13 +1894,30 @@ export function buildPingUrl(baseUrl, repoName) {
  */
 const CONNECTIVITY_ACCESS_DENIED_FALLBACK = "The Bridge API denied access to this repository (HTTP 403). Verify the repo_name and that this " +
     "credential is authorized for it.";
+/**
+ * Source attribution appended to a 401 (BAPI-668, R11-2). Names WHERE the
+ * rejected credential came from — the source is safe to print, the value is not —
+ * so a user with a stale key exported in a shell profile is not left re-running
+ * the same failing command. A prompt-sourced (or unattributed) key keeps today's
+ * message byte-for-byte.
+ */
+const CONNECTIVITY_KEY_SOURCE_ATTRIBUTION = {
+    env: " (this key came from the BAPI_API_KEY environment variable — unset it to be prompted for a " +
+        "different one)",
+    flag: " (this key came from the --api-key flag — omit it to be prompted for a different one)",
+    prompt: "",
+};
 /**
  * Verify connectivity. Distinguishes a rejected/expired credential (401) from a
  * repository-specific access denial (403, BAPI-661) from an unknown repo /
  * not-found (404) where the response allows. The key is sent in the `X-API-Key`
  * header and NEVER appears in any returned message.
+ *
+ * `apiKeySource` (BAPI-668) is supplied only on the ORDINARY API-key path. A
+ * bootstrap-minted key is verified WITHOUT it, because attributing a
+ * server-minted credential to `--api-key` or `BAPI_API_KEY` would be simply false.
  */
-export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
+export async function verifyConnectivity(deps, baseUrl, repoName, apiKey, apiKeySource) {
     const url = buildPingUrl(baseUrl, repoName);
     let resp;
     try {
@@ -1551,11 +1941,16 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     if (resp.ok)
         return { ok: true };
     if (resp.status === 401) {
+        // BAPI-669 (U8): the remediation names an ADDRESS, derived from the same
+        // already-normalized `baseUrl` this function was handed — never a bare page name,
+        // and never a re-read of BAPI_BASE_URL.
+        const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
         return {
             ok: false,
             message: `The Bridge API rejected the credential (HTTP ${resp.status}). The API key may be invalid or expired ` +
-                "— generate a fresh one in the Bridge API web UI Security page. (An expired token can also surface as a " +
-                "permission error.)",
+                `— generate a fresh one at ${setupUrl} (Security page). (An expired token can also surface as a ` +
+                "permission error.)" +
+                (apiKeySource ? CONNECTIVITY_KEY_SOURCE_ATTRIBUTION[apiKeySource] : ""),
         };
     }
     if (resp.status === 403) {
@@ -1657,10 +2052,15 @@ export function generateBootstrapKeySecret(randomBytes) {
     return randomBytes(BOOTSTRAP_KEY_SECRET_BYTES).toString("base64url");
 }
 /**
- * SHA-256 hex digest of the bootstrap-invite token — the key under which the
- * pending record is stored. The TOKEN ITSELF IS NEVER WRITTEN TO DISK; only this
- * one-way fingerprint, so a retry can recognize "same invite, same repo" and reuse
- * the exact pending `key_secret` (the replay proof).
+ * SHA-256 hex digest of the bootstrap-invite token — the identity guard on every
+ * pending record, so a retry can recognize "same invite, same repo" and reuse the
+ * exact pending `key_secret` (the replay proof).
+ *
+ * For a USER-SUPPLIED invite the fingerprint is the only trace on disk. BAPI-667
+ * additionally stores the token itself for an INTERNALLY MINTED self-serve invite
+ * (which the user was never shown and cannot re-present) — the fingerprint remains
+ * the identity guard in both shapes, and prepare / repoint / promote / discard all
+ * still match on it.
  */
 export function fingerprintBootstrapInvite(token) {
     return createHash("sha256").update(token, "utf-8").digest("hex");
@@ -1689,12 +2089,15 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
         // The message may contain the request (some fetch impls echo it), so it is
         // deliberately NOT interpolated here.
         void err;
+        // MODE-NEUTRAL (BAPI-667). This function cannot tell a `--invite` run from a
+        // self-serve one, and the two need OPPOSITE retry instructions ("re-present the
+        // same invite" vs. "choose the email option"), so it states only the coarse
+        // fact. The caller appends {@link buildBootstrapRetryAdvice}.
         return {
             ok: false,
             kind: "failed",
             message: `Could not reach the Bridge API at ${baseUrl} to redeem the bootstrap invite. Check ` +
-                "BAPI_BASE_URL and your network, then re-run — the invite has not been used, and the " +
-                "re-run will reuse the same locally-stored secret.",
+                "BAPI_BASE_URL and your network. The invite has not been used.",
         };
     }
     if (resp.ok) {
@@ -1859,6 +2262,76 @@ export const BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE = [
 export const BOOTSTRAP_INVITE_REJECTED_MESSAGE = "The Bridge API rejected the bootstrap invite (HTTP 401). The invite is invalid, expired, or " +
     "revoked — ask your Bridge API operator for a new one. (Your locally-stored secret was sent " +
     "unchanged, so this is not a lost-secret problem.)";
+/**
+ * The 401 explanation for a REPLAYED SELF-SERVE token (BAPI-667). Unlike the two
+ * messages above this is not a dead end: the token was minted by this CLI, so it
+ * can mint another one — but only after the user explicitly consents to discard
+ * the expired record, because that record is the only replay proof for a signup
+ * whose exchange may in fact have succeeded.
+ *
+ * Sanitized by construction: it names no token, no fingerprint, and no secret.
+ */
+export const BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE = "The Bridge API rejected the stored signup invite (HTTP 401) — it is invalid, expired, or " +
+    "revoked. Your saved signup attempt cannot be resumed with it.";
+/**
+ * Mode-aware retry guidance (BAPI-667, R4-5), formatted in ONE place so a
+ * self-serve user is never told to "re-run with the same bootstrap invite" — a
+ * token they were never shown and cannot re-present.
+ *
+ * Secret-free by construction: it interpolates nothing.
+ */
+export function buildBootstrapRetryAdvice(selfServeSignupMode) {
+    return selfServeSignupMode
+        ? "Re-run install-bridge and choose the email option — your previous attempt will resume."
+        : "Re-run install-bridge with the same bootstrap invite — the redemption will replay and " +
+            "return the same key.";
+}
+/**
+ * Shared consent gate for a `credential-conflict` from `prepareBootstrapPending`
+ * (BAPI-667).
+ *
+ * An existing `bapi:<repo>` credential is never clobbered without consent:
+ * `--force`, else an interactive prompt, else a hard non-interactive failure —
+ * always BEFORE the exchange, so nothing is consumed on either branch.
+ *
+ * This gate lives in ONE place because the self-serve and ordinary-invite arms
+ * now prepare their own pending records (self-serve must additionally persist its
+ * replay token in the same durable write). While the gate sat inline in whichever
+ * arm happened to own the single shared call, gating that call behind
+ * `if (!selfServeSignupMode)` silently dropped the prompt from the self-serve arm
+ * — an `--email` / option-3 run against an already-provisioned repo hard-failed on
+ * a TTY without ever offering the overwrite. Routing both arms through this helper
+ * makes that drift impossible.
+ *
+ * `grantConsent` runs before the retry so the caller can record consent for its own
+ * later repoint/promote writes. `retry` re-issues the CALLER'S prepare params with
+ * `allowOverwriteExistingCredential: true`, so the self-serve arm keeps its
+ * `selfServeReplayToken` on the retried write.
+ *
+ * Returns the result untouched when it is not a credential-conflict, the retried
+ * result after consent, or `null` when the user declined or could not be asked —
+ * in which case the reason is already logged and the caller returns non-zero.
+ *
+ * Secret-free: it names only the logical credential target.
+ */
+export async function resolveCredentialConflictConsent(prepared, ctx) {
+    if (prepared.ok || prepared.kind !== "credential-conflict")
+        return prepared;
+    if (!ctx.isTTY || !ctx.promptLine) {
+        ctx.errorLog(`Error: ${prepared.error} Re-run with --force to overwrite it (refusing to overwrite a ` +
+            "credential non-interactively without consent).");
+        return null;
+    }
+    const answer = (await ctx.promptLine(`The credential store already holds a key for ${prepared.target}. Overwrite it? [y/N]: `))
+        .trim()
+        .toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        ctx.errorLog("Aborted: existing credential left unchanged (re-run with --force to overwrite).");
+        return null;
+    }
+    ctx.grantConsent();
+    return ctx.retry();
+}
 /**
  * Render the --dry-run preview lines. Every secret is ALWAYS redacted — the
  * spawnCommand, config preview, and (in bootstrap-invite mode) the exchange body
@@ -1881,7 +2354,9 @@ export function buildDryRunPreview(plan) {
         "",
         "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
         `Step 2 — connectivity ping (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
-        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned):",
+        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
+        "         a git-tracked config needs default-No consent for the real key, else a",
+        "         secret-free entry; an unparseable config is skipped and left untouched):",
         ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
         ...(plan.manualEditors.length > 0
             ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
@@ -1925,9 +2400,16 @@ function buildLaunchStepPreview(plan) {
         // BAPI-631: described, never performed in --dry-run — a preview must not open a
         // browser or reach the network. It is also strictly optional, so it carries no step
         // number of its own and never changes the 5-step count.
+        //
+        // BAPI-669 (U6): the quoted prompt and the purpose/deferral context below MUST
+        // stay in step with the live offer — the preview advertising the old `(Y/n)`
+        // default while the run asked `[y/N]` is exactly the drift this fixes.
         "Step 4b — optional GitHub connect (SKIPPED in --dry-run): read GitHub's configured state",
         "          via the install manifest and, only when it is unconfigured and the terminal is",
-        "          interactive, offer 'Connect GitHub? (Y/n)' before the agent session starts.",
+        `          interactive, offer '${INSTALL_BRIDGE_GITHUB_CONNECT_PROMPT.replace(/:\s*$/, "")}' before the agent session starts.`,
+        "          It installs the Bridge GitHub App so pull requests and code review work, opens",
+        "          github.com in your browser, and shares no GitHub credential with Bridge; it",
+        `          defaults to No and can be run later instead: ${INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND}`,
     ];
     if (plan.launch.kind === "spawn") {
         return [
@@ -1978,9 +2460,12 @@ function buildBootstrapDryRunPreview(plan) {
     const selfServeStep = plan.selfServeSignup
         ? [
             "Step 2·pre — self-serve signup (PREVIEWED, SKIPPED in --dry-run): no Bridge workspace",
-            "          signup is requested, no mint call is made, and no email is sent or transmitted;",
-            "          a real run would request a fresh workspace for your email and receive an invite",
-            "          token, which then feeds the SAME redemption protocol below.",
+            "          signup is requested, no mint call is made, no email is sent or transmitted, and",
+            `          ${pendingTarget} is neither read nor written;`,
+            "          a real run would first check that record and RESUME a saved attempt if one",
+            "          exists, otherwise request a fresh workspace for your email and durably store the",
+            "          returned invite token alongside the key_secret — which then feeds the SAME",
+            "          redemption protocol below.",
         ]
         : [];
     return [
@@ -1998,7 +2483,9 @@ function buildBootstrapDryRunPreview(plan) {
         `          POST ${plan.exchangeUrl}`,
         `          body: {"token": "${REDACTED_API_KEY}", "repo_name": "${plan.repoName}", "key_secret": "${REDACTED_API_KEY}"}`,
         `Step 2c — connectivity ping with the newly-minted key (before any durable key write): GET ${plan.pingUrl} (X-API-Key: ${REDACTED_API_KEY})`,
-        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned):",
+        "Step 3 — write per-host MCP config (read-merge-write, launcher version-pinned;",
+        "         a git-tracked config needs default-No consent for the real key, else a",
+        "         secret-free entry; an unparseable config is skipped and left untouched):",
         ...plan.configTargets.map((t) => `  ${t}: BAPI_REPO_NAME=${plan.repoName}, BAPI_API_KEY=${REDACTED_API_KEY}, BAPI_BASE_URL=${plan.baseUrl}, BAPI_DOCS_DIR=${plan.docsDir}`),
         ...(plan.manualEditors.length > 0
             ? [`  ${plan.manualEditors.join(" + ")}: detected (global config) — manual setup instructions would be printed.`]
@@ -2041,12 +2528,29 @@ export function manualEditorNames(editors) {
         names.push("Codex");
     return names;
 }
+/**
+ * Where the key a need-key run just MINTED actually lives (BAPI-669, R8).
+ *
+ * A manual-setup path tells the user to paste `BAPI_API_KEY` into a global config —
+ * but an invite / self-serve user has never seen their key, because the CLI minted
+ * it and stored it. Without this line the instruction is unfollowable.
+ *
+ * SECRET DISCIPLINE (hard constraint): this formatter accepts NO key material. Its
+ * parameters are a repo name and a filesystem path, both printable; it must never be
+ * handed `apiKey`, `inviteToken`, `keySecret`, a signup email, or a credential record.
+ */
+export function formatNeedKeyCredentialStoreLine(repoName, credentialStorePath) {
+    return `Your API key is stored at ${credentialStorePath} under "bapi:${repoName}" — copy BAPI_API_KEY from there.`;
+}
 /**
  * Build the manual-instruction block for the DETECTED global-config editors only
  * (key always redacted). Returns `null` when neither Windsurf nor Codex is
  * detected, so the caller prints nothing for users who don't use them.
+ *
+ * `needKey` (BAPI-669, R8) is supplied only for a bootstrap-invite, reclassified-invite,
+ * or self-serve run — the three flows where the key was minted rather than supplied.
  */
-function buildManualHostInstructions(entry, editors) {
+function buildManualHostInstructions(entry, editors, needKey) {
     if (!editors.windsurf && !editors.codex)
         return null;
     const redactedEnv = { ...entry.env, BAPI_API_KEY: REDACTED_API_KEY };
@@ -2062,9 +2566,252 @@ function buildManualHostInstructions(entry, editors) {
     if (editors.codex) {
         lines.push("", "  Codex → ~/.codex/config.toml (add an [mcp_servers.bridge-api] table with the", "  same command/args/env shown above, BAPI_API_KEY set to your key).");
     }
+    if (needKey) {
+        lines.push("", `  ${formatNeedKeyCredentialStoreLine(needKey.repoName, needKey.credentialStorePath)}`);
+    }
     return lines.join("\n");
 }
 // ---------------------------------------------------------------------------
+// Secret-safe failure classification + reporting (BAPI-668)
+// ---------------------------------------------------------------------------
+/**
+ * The single diagnosis pointer every install failure block ends with. Defined
+ * ONCE and reused by the Step 1–5 catch, the `index.ts` dispatch catch, the
+ * tests, and the feature documentation, so the command text cannot drift.
+ */
+export const INSTALL_BRIDGE_DOCTOR_COMMAND = "npx -y @bridge_gpt/mcp-server doctor";
+/**
+ * The canonical pointer LINE (BAPI-669, U9a). One syntax — no quotes, no alternate
+ * punctuation — shared by the Step 1–5 catch and by every operational fatal in the
+ * ping / exchange / network / self-serve regions, so a user sees the same sentence
+ * wherever an install dies. It must appear EXACTLY ONCE per fatal exit.
+ */
+export const INSTALL_BRIDGE_DOCTOR_POINTER = `Diagnose with: ${INSTALL_BRIDGE_DOCTOR_COMMAND}`;
+/**
+ * The classified cause used whenever the thrown value carries no `code` we
+ * recognize. Deliberately fixed and free-form-free: it names the opt-in debug
+ * switch instead of echoing anything about the caught value.
+ */
+export const INSTALL_BRIDGE_UNCLASSIFIED_CAUSE = "unexpected error (run with BAPI_INSTALL_DEBUG=1 for details)";
+/** Fixed last-resort step label for the `index.ts` install-bridge dispatch catch. */
+export const INSTALL_BRIDGE_DISPATCH_STEP_LABEL = "install-bridge dispatch";
+/** Labels prefixing the OPT-IN raw diagnostics (never emitted by default). */
+export const INSTALL_BRIDGE_DEBUG_MESSAGE_LABEL = "debug (BAPI_INSTALL_DEBUG) raw message:";
+export const INSTALL_BRIDGE_DEBUG_STACK_LABEL = "debug (BAPI_INSTALL_DEBUG) raw stack:";
+/**
+ * Closed filesystem-code → cause map. A `Map` (not an object literal) so a
+ * hostile `code` such as `"constructor"` or `"__proto__"` can never resolve
+ * through the prototype chain into a bogus "cause".
+ */
+const INSTALL_BRIDGE_FILESYSTEM_CAUSES = new Map([
+    ["EACCES", "permission denied"],
+    ["EPERM", "permission denied"],
+    ["ENOSPC", "no space left on device"],
+    ["EROFS", "read-only file system"],
+]);
+/** Closed allowlist of standard network codes that all collapse to one cause. */
+const INSTALL_BRIDGE_NETWORK_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+]);
+/**
+ * Read `error.code` without trusting the value at all: a non-object, a throwing
+ * getter, and a non-string `code` all degrade to `undefined` rather than
+ * escaping. Nothing else on the caught value is ever touched.
+ */
+function extractInstallBridgeErrorCode(error) {
+    try {
+        if (typeof error !== "object" || error === null)
+            return undefined;
+        const code = error.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Map a caught value to a SHORT, FIXED cause label (BAPI-668, R5-1).
+ *
+ * SECRET DISCIPLINE — safe by SUPPRESSION, not by redaction: the normal path
+ * reads ONLY a safely-guarded string `code`. It never reads `error.message`,
+ * never calls `String(error)`, and never serializes the caught object, because a
+ * free-form message can embed a secret this module does not hold in scope and
+ * therefore could not scrub (the exact case `secret-safety.test.ts` guards).
+ * Never pass an API key, invite token, or `key_secret` through here.
+ */
+export function classifyInstallBridgeFailure(error) {
+    const code = extractInstallBridgeErrorCode(error);
+    if (code === undefined)
+        return INSTALL_BRIDGE_UNCLASSIFIED_CAUSE;
+    const filesystemCause = INSTALL_BRIDGE_FILESYSTEM_CAUSES.get(code);
+    if (filesystemCause !== undefined)
+        return filesystemCause;
+    if (INSTALL_BRIDGE_NETWORK_CODES.has(code))
+        return "network error";
+    return INSTALL_BRIDGE_UNCLASSIFIED_CAUSE;
+}
+/** Read one debug-only field defensively; a hostile getter degrades to `undefined`. */
+function readInstallBridgeDebugValue(read) {
+    try {
+        const value = read();
+        if (typeof value === "string")
+            return value;
+        if (value === undefined || value === null)
+            return undefined;
+        return String(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the fixed, secret-free failure block for an unexpected install failure
+ * (BAPI-668, R5-1/R5-3). Pure — the caller decides which sink receives the lines.
+ *
+ * Default output is exactly: the failed step label, the classified cause, the
+ * doctor pointer, and (only when the caller supplies it) the resume advice.
+ *
+ * SECRET DISCIPLINE — as with {@link classifyInstallBridgeFailure}, the default
+ * path is safe by SUPPRESSION: it never reads `message`/`stack`, never stringifies
+ * the caught value, and never accepts a credential in its context. The raw message
+ * and full stack are OPT-IN diagnostics that appear only when `debugEnabled` is
+ * true (i.e. the user set `BAPI_INSTALL_DEBUG`), and even that extraction is
+ * guarded so a hostile thrown value cannot make the last-resort formatter throw.
+ */
+export function buildInstallBridgeFailureLines(error, context) {
+    const lines = [
+        `Error: install-bridge failed at: ${context.step}`,
+        `  cause: ${classifyInstallBridgeFailure(error)}`,
+        `  ${INSTALL_BRIDGE_DOCTOR_POINTER}`,
+    ];
+    if (context.resumeAdvice)
+        lines.push(`  ${context.resumeAdvice}`);
+    if (context.debugEnabled) {
+        const isError = error instanceof Error;
+        const rawMessage = isError
+            ? readInstallBridgeDebugValue(() => error.message)
+            : readInstallBridgeDebugValue(() => String(error));
+        const rawStack = isError
+            ? readInstallBridgeDebugValue(() => error.stack)
+            : undefined;
+        lines.push(`  ${INSTALL_BRIDGE_DEBUG_MESSAGE_LABEL} ${rawMessage ?? "<unavailable>"}`);
+        if (rawStack)
+            lines.push(`  ${INSTALL_BRIDGE_DEBUG_STACK_LABEL} ${rawStack}`);
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// Base-URL normalization + validation (BAPI-668, R9)
+// ---------------------------------------------------------------------------
+/** The ONE user-facing rejection for a malformed/non-http(s) `BAPI_BASE_URL`. */
+function buildInstallBridgeBaseUrlError(value) {
+    return `BAPI_BASE_URL must be an absolute http(s) URL (got: "${value}")`;
+}
+/**
+ * Normalize and validate `BAPI_BASE_URL` ONCE, at the CLI entry boundary (R9-1).
+ *
+ * `new URL()` alone does NOT restrict the scheme — it happily accepts
+ * `ftp://x.com`, `javascript:alert(1)`, and `foo:bar` — so the protocol is checked
+ * explicitly. An ABSENT variable defaults; an explicitly EMPTY or whitespace-only
+ * one is REJECTED rather than silently defaulting, because "exported but blank" is
+ * a misconfiguration, not an opt-out.
+ *
+ * The value is a URL, not a secret, so echoing it in the error is intentional.
+ */
+export function resolveInstallBridgeBaseUrl(env) {
+    const supplied = env.BAPI_BASE_URL;
+    // A non-string (absent property, or an explicit `undefined`) is "unset" and
+    // defaults; any supplied string — including "" and "   " — must validate.
+    const candidate = typeof supplied === "string" ? supplied.trim() : DEFAULT_BAPI_BASE_URL;
+    if (candidate.length === 0)
+        return { ok: false, error: buildInstallBridgeBaseUrlError("") };
+    let parsed;
+    try {
+        parsed = new URL(candidate);
+    }
+    catch {
+        return { ok: false, error: buildInstallBridgeBaseUrlError(candidate) };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, error: buildInstallBridgeBaseUrlError(candidate) };
+    }
+    // The TRIMMED candidate is returned, not `parsed.toString()`: the latter would
+    // append a path slash ("https://x.com" → "https://x.com/") and change every
+    // downstream URL the existing tests and consumers already pin.
+    return { ok: true, value: candidate };
+}
+// ---------------------------------------------------------------------------
+// Printed Step 1–5 labels (BAPI-668, R5-1)
+// ---------------------------------------------------------------------------
+/**
+ * Every printed Step 1–5 label, defined once. `runInstallBridgeCli` uses each
+ * constant BOTH when logging the step AND when recording the current step, so a
+ * failure can never be attributed to a label the user did not just see.
+ */
+export const INSTALL_BRIDGE_STEP_LABELS = {
+    scaffold: "Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…",
+    selfServeMint: "Step 2/5 — requesting Bridge self-serve setup…",
+    inviteRedeem: "Step 2/5 — redeeming the bootstrap invite…",
+    verifyConnectivity: "Step 2/5 — verifying connectivity…",
+    writeHostConfigs: "Step 3/5 — writing per-host MCP config…",
+    promoteCredential: "Step 4/5 — promoting the bootstrap credential…",
+    persistCredential: "Step 4/5 — persisting routing credential…",
+};
+/**
+ * The Step 5 label, which names the agent being opened. Same rule: log == record.
+ * BAPI-669 (U3): it prints the host tool's DISPLAY label ("Claude Code"), never the
+ * raw agent binary name ("claude") — the user picked a tool, not a binary.
+ */
+export function buildInstallBridgeLaunchStepLabel(agent) {
+    return `Step 5/5 — opening a ${toolLabelForLaunchAgent(agent)} session for /install-bridge configuration + concise capability report…`;
+}
+// ---------------------------------------------------------------------------
+// Working-directory banner + project-root gate (BAPI-669, U2)
+//
+// This gate is READ-ONLY by construction: it prints where the install is aimed,
+// probes a single path through the injected `deps.stat` seam, and (on a TTY only)
+// asks one question. It must stay AHEAD of onboarding selection, credential
+// resolution, repository resolution, tool selection, every network call, `runInit`,
+// launch materialization, and every write — so a decline can abort with nothing
+// minted, exchanged, or written.
+//
+// Declining is a user-initiated CANCEL, not a failure: it exits 0. A non-TTY run
+// warns and continues, preserving automation compatibility (legitimate non-git
+// installs exist, so blocking outright was rejected).
+// ---------------------------------------------------------------------------
+/** Prefix of the always-printed "where am I installing" banner. */
+export const INSTALL_BRIDGE_CWD_BANNER_PREFIX = "Installing Bridge into: ";
+/** The shared no-`.git` finding, reused by both the TTY prompt and the non-TTY warning. */
+export const INSTALL_BRIDGE_NO_GIT_WARNING = "This doesn't look like a project root (no .git found)";
+/** Default-No confirmation shown only on a TTY when `.git` is absent. */
+export const INSTALL_BRIDGE_NO_GIT_PROMPT = `${INSTALL_BRIDGE_NO_GIT_WARNING} — continue? [y/N]: `;
+/** Printed on decline. Paired with exit code 0 — a cancel is not an error. */
+export const INSTALL_BRIDGE_NO_GIT_ABORT = "Aborted — run install-bridge from your project root, or re-run and confirm to continue.";
+/** The non-TTY form: same finding, stated as a warning, then the run continues. */
+export const INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING = `Warning: ${INSTALL_BRIDGE_NO_GIT_WARNING} — continuing (non-interactive).`;
+/**
+ * Existence probe for `<cwd>/.git`, through the injected `stat` boundary. A git
+ * worktree's `.git` is a FILE rather than a directory, so only existence is
+ * checked — never the entry type. Any probe failure is treated as "absent"; this
+ * is a hint for a warning, never an authorization decision. Repository-name
+ * inference is untouched by it.
+ */
+async function hasProjectRootMarker(deps) {
+    try {
+        await deps.stat(path.join(deps.cwd, ".git"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
 // CLI entry
 // ---------------------------------------------------------------------------
 /**
@@ -2081,18 +2828,90 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         deps.resolveRepoViaServer = (baseUrl, apiKey) => resolveRepoViaServer(deps.fetch, baseUrl, apiKey);
     }
     const { log, errorLog } = deps;
+    /**
+     * Emit an OPERATIONAL fatal (BAPI-669, U9a): one or more already-composed,
+     * secret-free error lines, then the canonical doctor pointer exactly once.
+     *
+     * Scope is deliberately narrow — the ping / exchange / network / self-serve
+     * failures, i.e. the ones where the machine's state is the open question. It is
+     * NOT used for user-directed cancellations (the missing-`.git` exit-0 abort, a
+     * declined overwrite, a declined signup discard) or for nonfatal warnings (the
+     * Step 5 terminal-spawn failure), where "run doctor" is noise rather than help.
+     */
+    const reportFatal = (...lines) => {
+        for (const line of lines)
+            errorLog(line);
+        errorLog(`  ${INSTALL_BRIDGE_DOCTOR_POINTER}`);
+    };
+    /** {@link reportFatal} plus the exit code, for the common `return fatal(…)` shape. */
+    const fatal = (...lines) => {
+        reportFatal(...lines);
+        return 1;
+    };
+    // ---- BAPI-668 (R9): normalize + validate BAPI_BASE_URL ONCE, here ----
+    // Resolved BEFORE the parser purely because it is pure and side-effect-free, so
+    // help / parser-error usage text can name the user's REAL base URL (BAPI-669 U8)
+    // instead of the hosted default. Error PRECEDENCE is deliberately unchanged: the
+    // `!ok` return still happens after the argument-error return below, so a run with
+    // both a bad flag and a bad BAPI_BASE_URL still reports the argument error first.
+    const baseUrlResult = resolveInstallBridgeBaseUrl(deps.env);
+    // A rejected value cannot be interpolated into guidance, so usage falls back to
+    // the documented default — the run is about to fail on it anyway.
+    const usageBaseUrl = baseUrlResult.ok ? baseUrlResult.value : DEFAULT_BAPI_BASE_URL;
     const parsed = parseInstallBridgeArgs(argv);
     if (parsed.status === "help") {
-        log(parsed.usage);
+        log(getInstallBridgeUsage(usageBaseUrl));
         return 0;
     }
     if (parsed.status === "error") {
         errorLog(`Error: ${parsed.message}`);
         errorLog("");
-        errorLog(getInstallBridgeUsage());
+        errorLog(getInstallBridgeUsage(usageBaseUrl));
         return 1;
     }
     const options = parsed.options;
+    // Deliberately still ahead of the onboarding branch, any prompt, any network
+    // call, and the --dry-run preview: a scheme-less value (the classic error) used
+    // to throw ERR_INVALID_URL deep inside `buildPingUrl` — even in --dry-run — often
+    // after the user had already answered a repo prompt. Failing here means no prompt
+    // is shown and no side effect occurs.
+    if (!baseUrlResult.ok) {
+        errorLog(baseUrlResult.error);
+        return 1;
+    }
+    const baseUrl = baseUrlResult.value;
+    /** `<base>/setup` — the one web surface every guidance string points at (U8). */
+    const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
+    // Replace the RUN-LOCAL env with a shallow copy carrying the normalized value so
+    // every downstream `deps.env` consumer observes it. The caller-owned object (and
+    // `process.env`) is never mutated.
+    deps.env = { ...deps.env, BAPI_BASE_URL: baseUrl };
+    // ---- BAPI-669 (U2): working-directory banner + project-root gate ----
+    // See the section comment on `hasProjectRootMarker`: read-only, and positioned
+    // ahead of ALL credential and configuration work so a decline costs nothing.
+    log(`${INSTALL_BRIDGE_CWD_BANNER_PREFIX}${deps.cwd}`);
+    if (!(await hasProjectRootMarker(deps))) {
+        if (deps.isTTY && deps.promptLine) {
+            let answer = "";
+            try {
+                answer = (await deps.promptLine(INSTALL_BRIDGE_NO_GIT_PROMPT)).trim().toLowerCase();
+            }
+            catch {
+                // A prompt that cannot be read is NOT confirmation. Never infer it — the
+                // default is No, so a malformed or failed read takes the abort path.
+                answer = "";
+            }
+            if (answer !== "y" && answer !== "yes") {
+                log(INSTALL_BRIDGE_NO_GIT_ABORT);
+                // Exit 0: the user cancelled, and nothing was resolved, written, or spent.
+                return 0;
+            }
+        }
+        else {
+            // Automation compatibility: warn, never prompt, never abort.
+            errorLog(INSTALL_BRIDGE_NO_GIT_NONINTERACTIVE_WARNING);
+        }
+    }
     // Onboarding branch: have-key vs. a need-key method (`bootstrap-invite` = redeem
     // a pre-issued invite, `self-serve` = mint one from an email, BAPI-618). BOTH
     // need-key methods share the downstream redemption protocol, so
@@ -2126,6 +2945,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     let apiKey = "";
     let inviteToken = "";
     let signupEmail = "";
+    // BAPI-668 (R11-1): retained ONLY while the resolved value stays on the ordinary
+    // API-key path. A value reclassified as a bootstrap invite, and either explicit
+    // need-key method, leave it undefined — those paths never run the ordinary
+    // key-authentication ping, so there is no source to attribute.
+    let apiKeySource;
     if (selfServeSignupMode) {
         const emailResult = await resolveSignupEmail(options, deps);
         if (!emailResult.ok) {
@@ -2158,14 +2982,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             apiKey = "";
             bootstrapInviteMode = true;
             selfServeSignupMode = false;
+            // Deliberately NOT retained: the redemption path mints its own key, so any
+            // flag/env attribution on its later ping would name the wrong credential.
+            apiKeySource = undefined;
         }
         else {
             apiKey = keyResult.value;
+            apiKeySource = keyResult.source;
         }
     }
-    // baseUrl is resolved BEFORE repository input because the have-key branch needs
-    // it for the server-resolution request.
-    const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
+    // `baseUrl` was resolved and validated at the entry boundary above (BAPI-668),
+    // well before the have-key branch's server-resolution request needs it.
     const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
     // ---- Resolve the repository name ----
     // Need-key (invite or self-serve): choose-a-name for the project this run is
@@ -2212,7 +3039,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // (BAPI-661) WITH a visible signal that the fallback is happening, so a
                 // guessed name is never confirmed silently as if it had been verified.
                 log("Couldn't auto-resolve your repo from the key; falling back to a guessed name — confirm " +
-                    "it matches the setup UI.");
+                    `it matches ${setupUrl} (setup UI).`);
                 const repoResult = await resolveRepoName(options, deps, "existing-registration");
                 if (!repoResult.ok) {
                     errorLog(`Error: ${repoResult.error}`);
@@ -2387,386 +3214,619 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             return 1;
         }
     }
-    // ---- Step 1 — scaffold (secret-free placeholders only) ----
-    log("Step 1/5 — scaffolding project (commands, agents, pipelines, config placeholders)…");
-    await deps.runInit(deps.cwd);
-    // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
-    let inviteFingerprint = "";
-    if (bootstrapInviteMode) {
-        // ---- Self-serve signup (BAPI-618): mint the invite token from the email ----
-        // This is the ONE step that precedes the unchanged BAPI-606 redemption below.
-        // It sits AFTER the --dry-run return above, so a preview never mints, never
-        // sends the email, and never writes a pending secret. On success the minted
-        // token is assigned to `inviteToken` and the flow falls into the existing
-        // persist-before-exchange block VERBATIM — identical to a --invite token from
-        // here on. On failure we return BEFORE any CSPRNG/pending write, so nothing is
-        // persisted. The email and the token are never logged.
-        if (selfServeSignupMode) {
-            log("Step 2/5 — requesting Bridge self-serve setup…");
-            const mint = await mintSelfServeInvite(deps, baseUrl, signupEmail);
-            if (!mint.ok) {
-                if (mint.category === "rate-limited") {
-                    errorLog("Error: Self-serve setup is temporarily rate limited. Try again later.");
-                }
-                else if (mint.category === "invalid") {
-                    errorLog("Error: Self-serve setup could not be requested. Check the email value and try again.");
+    // ---- BAPI-668 (R5-1): the guarded Step 1–5 execution region ----
+    // Everything ABOVE this point — argument parsing, base-URL validation, input
+    // resolution, the dry-run preview, and every deliberate pre-execution validation
+    // return — stays OUTSIDE the catch: those failures are already explained, and
+    // folding them into a generic block would make them worse, not safer. Everything
+    // from the Step 1 scaffold through the terminal Step 5 returns is inside, so no
+    // fs/permission/disk failure can print a raw Node stack. Every explicitly handled
+    // branch inside (fatal gitignore protection, fail-open credential persistence,
+    // advisory install-state persistence, the GitHub offer, prewarm warnings, and the
+    // nonfatal Step 5 spawn failure) keeps its own behavior — the catch only ever sees
+    // an exception that ESCAPED all of them.
+    let currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
+    let bootstrapExchangeSucceeded = false;
+    try {
+        // ---- Step 1 — scaffold (secret-free placeholders only) ----
+        currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
+        log(currentStep);
+        await deps.runInit(deps.cwd);
+        // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
+        let inviteFingerprint = "";
+        if (bootstrapInviteMode) {
+            // ---- Self-serve resume (BAPI-667) — runs BEFORE any mint ----
+            // Every self-serve run used to mint a FRESH invite, so a retry after any
+            // mid-protocol failure presented a new fingerprint against its own pending
+            // record and hard-failed with `pending-conflict` whose only advice was to
+            // delete the record by hand — potentially destroying the sole trace of a live
+            // admin key. It also littered a new tenant row server-side per attempt.
+            //
+            // So the stored record is consulted FIRST. A resumable record supplies the
+            // token, the fingerprint, and the `key_secret`, and the mint endpoint is never
+            // called at all. This is the whole of R4-2, and it is what makes the normal
+            // retry path free of orphan tenants.
+            let resumedSelfServeReplay = false;
+            let keySecret = "";
+            let reusedPendingSecret = false;
+            if (selfServeSignupMode) {
+                const lookup = await deps.lookupSelfServeBootstrapPending({ repoName }, credentialWriteDeps);
+                if (!lookup.ok) {
+                    // Fail BEFORE the mint endpoint is called and leave the stored record
+                    // untouched — an ordinary-invite record, a malformed record, and an
+                    // unreadable store are all states where minting again would compound the
+                    // problem rather than recover from it.
+                    return fatal(`Error: ${lookup.error}`);
                 }
-                else {
-                    errorLog("Error: Unable to complete self-serve setup. Check connectivity and retry.");
+                if (lookup.state === "resumable") {
+                    // SECRETS: assigned, never logged. The single line below names only the repo.
+                    inviteToken = lookup.replayToken;
+                    inviteFingerprint = lookup.inviteFingerprint;
+                    keySecret = lookup.keySecret;
+                    resumedSelfServeReplay = true;
+                    // The stored secret IS the replay proof, so a 401 here is a rejected
+                    // invite, not a lost secret (mirrors `prepared.reused`).
+                    reusedPendingSecret = true;
+                    log(`  resuming your previous signup attempt for ${repoName}`);
                 }
-                return 1;
             }
-            // Treated identically to a manually supplied invite token from here on.
-            inviteToken = mint.token;
-        }
-        // ===================================================================
-        // LOAD-BEARING ORDERING — NOT DEFENSIVE POLISH. DO NOT "TIDY" THIS.
-        //
-        // The key_secret is generated HERE, fsynced to a pending record HERE, and
-        // only THEN sent to the exchange. That order is the protocol:
-        //
-        //   * The locally-stored key_secret is the ONLY proof that can replay a
-        //     redemption. The server's replay branch matches on (repo_name, bcrypt of
-        //     key_secret); it never returns a recoverable credential.
-        //   * So a successful exchange followed by a failed local write = an
-        //     unrecoverable admin key AND a permanently spent invite. The user cannot
-        //     re-run (a new secret gets a correct 401) and cannot re-mint (the repo
-        //     name is now globally taken by the project they just created); only an
-        //     operator can dig them out.
-        //
-        // Therefore the write is FAIL-CLOSED: if it does not land (including its
-        // fsync), we abort with a non-zero exit and NEVER call fetch. Nothing is
-        // consumed. Moving this persist after the exchange — the "natural" order —
-        // reintroduces exactly the bug above. (Contrast Step 4 in normal mode, which
-        // is deliberately fail-open: there, the key already exists server-side and a
-        // persist failure only degrades start-tickets routing.)
-        // ===================================================================
-        inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
-        log("Step 2/5 — redeeming the bootstrap invite…");
-        let prepared = await deps.prepareBootstrapPending({
-            repoName,
-            inviteFingerprint,
-            generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
-            allowOverwriteExistingCredential: overwriteConsent,
-        }, credentialWriteDeps);
-        // An existing bapi:<repo> credential is never clobbered without consent. The
-        // gate mirrors the host-config gate above: --force, else an interactive prompt,
-        // else a hard non-interactive failure — all BEFORE the exchange.
-        if (!prepared.ok && prepared.kind === "credential-conflict") {
-            if (deps.isTTY && deps.promptLine) {
-                const answer = (await deps.promptLine(`The credential store already holds a key for ${prepared.target}. Overwrite it? [y/N]: `)).trim().toLowerCase();
-                if (answer !== "y" && answer !== "yes") {
-                    errorLog("Aborted: existing credential left unchanged (re-run with --force to overwrite).");
-                    return 1;
+            /**
+             * Mint a self-serve invite and durably store it WITH a fresh `key_secret`.
+             *
+             * Shared by the initial signup and the consented refresh below — the only two
+             * places a self-serve token is ever created. The ordering inside is the same
+             * load-bearing protocol described below: mint the token, durably store the
+             * token plus the `key_secret`, and only THEN exchange. Logs its own
+             * (secret-free) failure and returns false; the caller exits non-zero.
+             */
+            const mintAndPrepareSelfServe = async () => {
+                const mint = await mintSelfServeInvite(deps, baseUrl, signupEmail);
+                if (!mint.ok) {
+                    if (mint.category === "rate-limited") {
+                        // BAPI-668 (R12-1): the limiter is a single GLOBAL per-hour signup bucket,
+                        // not a per-IP/per-email one — so "temporarily rate limited" read as "you
+                        // did something wrong" when nothing on the user's machine is at fault.
+                        // Message-only: the return value and the caller's exit code are unchanged.
+                        reportFatal("Error: Bridge's self-serve signup capacity for this hour is exhausted (this is a " +
+                            "global service limit, not a problem with your machine). Try again in about an hour.");
+                    }
+                    else if (mint.category === "invalid") {
+                        reportFatal("Error: Self-serve setup could not be requested. Check the email value and try again.");
+                    }
+                    else {
+                        reportFatal("Error: Unable to complete self-serve setup. Check connectivity and retry.");
+                    }
+                    return false;
                 }
-                overwriteConsent = true;
-                prepared = await deps.prepareBootstrapPending({
+                // Treated identically to a manually supplied invite token from here on.
+                inviteToken = mint.token;
+                inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
+                const prepareSelfServePending = (allowOverwrite) => deps.prepareBootstrapPending({
                     repoName,
                     inviteFingerprint,
                     generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
-                    allowOverwriteExistingCredential: true,
+                    allowOverwriteExistingCredential: allowOverwrite,
+                    // R4-1: the minted token rides the SAME durable write as the key_secret.
+                    // It is stored ONLY here — a user-supplied invite stays fingerprint-only.
+                    selfServeReplayToken: inviteToken,
                 }, credentialWriteDeps);
+                // An existing bapi:<repo> credential is never clobbered without consent —
+                // the self-serve arm uses the SAME gate as the ordinary-invite arm below.
+                const prep = await resolveCredentialConflictConsent(await prepareSelfServePending(overwriteConsent), {
+                    isTTY: deps.isTTY,
+                    promptLine: deps.promptLine,
+                    errorLog,
+                    grantConsent: () => {
+                        overwriteConsent = true;
+                    },
+                    retry: () => prepareSelfServePending(true),
+                });
+                if (prep === null)
+                    return false;
+                if (!prep.ok) {
+                    reportFatal(`Error: could not durably store the signup credential (${prep.kind}). ${prep.error} ` +
+                        "No workspace has been set up — fix the problem and re-run.");
+                    return false;
+                }
+                keySecret = prep.keySecret;
+                reusedPendingSecret = prep.reused;
+                log(`  saved the pending credential for ${prep.target} (fsynced before the exchange)`);
+                return true;
+            };
+            // ---- Self-serve signup (BAPI-618): mint the invite token from the email ----
+            // This is the ONE step that precedes the unchanged BAPI-606 redemption below.
+            // It sits AFTER the --dry-run return above, so a preview never mints, never
+            // sends the email, and never writes a pending secret. On failure we return
+            // BEFORE the exchange, so nothing is consumed. The email and the token are
+            // never logged. SKIPPED ENTIRELY when the run resumed a stored attempt.
+            if (selfServeSignupMode && !resumedSelfServeReplay) {
+                currentStep = INSTALL_BRIDGE_STEP_LABELS.selfServeMint;
+                log(currentStep);
+                if (!(await mintAndPrepareSelfServe()))
+                    return 1;
             }
-            else {
-                errorLog(`Error: ${prepared.error} Re-run with --force to overwrite it (refusing to overwrite a ` +
-                    "credential non-interactively without consent).");
-                return 1;
-            }
-        }
-        // A pending record left by a DIFFERENT invite is that redemption's only replay
-        // proof. Unlike the credential conflict above there is no consent path — not
-        // even --force — so re-running is not the fix and must not be advised.
-        if (!prepared.ok && prepared.kind === "pending-conflict") {
-            errorLog(`Error: ${prepared.error} This invite has NOT been used, and re-running will not clear ` +
-                "the conflict.");
-            return 1;
-        }
-        if (!prepared.ok) {
-            // Fail closed: the exchange has NOT been called, so the invite is unspent.
-            errorLog(`Error: could not durably store the bootstrap credential (${prepared.kind}). ${prepared.error} ` +
-                "The bootstrap invite has NOT been used — fix the problem and re-run.");
-            return 1;
-        }
-        const keySecret = prepared.keySecret;
-        const reusedPendingSecret = prepared.reused;
-        log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
-        // The exchange REPLACES the pre-flight ping: in invite mode there is no key to
-        // ping with — this call is what mints it.
-        let exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
-        // 409 repo_name_taken: the server ROLLED BACK, so the invite is NOT consumed and
-        // the SAME token can be retried under a new name — with the SAME pending secret,
-        // re-pointed to that name.
-        while (!exchange.ok && exchange.kind === "repo-name-taken") {
-            if (!deps.isTTY || !deps.promptLine) {
-                errorLog(`Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT ` +
-                    "been used).");
-                return 1;
-            }
-            errorLog(exchange.message);
-            const answer = (await deps.promptLine("Choose a different repo name: ")).trim();
-            const validated = validateRepoName(answer);
-            if (!validated.ok) {
-                errorLog(`Error: invalid repo name — ${validated.error}.`);
-                return 1;
+            // ===================================================================
+            // LOAD-BEARING ORDERING — NOT DEFENSIVE POLISH. DO NOT "TIDY" THIS.
+            //
+            // The key_secret is generated HERE, fsynced to a pending record HERE, and
+            // only THEN sent to the exchange. That order is the protocol:
+            //
+            //   * The locally-stored key_secret is the ONLY proof that can replay a
+            //     redemption. The server's replay branch matches on (repo_name, bcrypt of
+            //     key_secret); it never returns a recoverable credential.
+            //   * So a successful exchange followed by a failed local write = an
+            //     unrecoverable admin key AND a permanently spent invite. The user cannot
+            //     re-run (a new secret gets a correct 401) and cannot re-mint (the repo
+            //     name is now globally taken by the project they just created); only an
+            //     operator can dig them out.
+            //
+            // Therefore the write is FAIL-CLOSED: if it does not land (including its
+            // fsync), we abort with a non-zero exit and NEVER call fetch. Nothing is
+            // consumed. Moving this persist after the exchange — the "natural" order —
+            // reintroduces exactly the bug above. (Contrast Step 4 in normal mode, which
+            // is deliberately fail-open: there, the key already exists server-side and a
+            // persist failure only degrades start-tickets routing.)
+            //
+            // BAPI-667: the self-serve arm satisfies this same ordering inside
+            // `mintAndPrepareSelfServe` (or has already loaded a durable record via the
+            // resume lookup), so the block below is the ORDINARY-INVITE preparation only.
+            // ===================================================================
+            if (!selfServeSignupMode) {
+                inviteFingerprint = fingerprintBootstrapInvite(inviteToken);
+                currentStep = INSTALL_BRIDGE_STEP_LABELS.inviteRedeem;
+                log(currentStep);
+                const prepareInvitePending = (allowOverwrite) => deps.prepareBootstrapPending({
+                    repoName,
+                    inviteFingerprint,
+                    generateKeySecret: () => generateBootstrapKeySecret(deps.randomBytes),
+                    allowOverwriteExistingCredential: allowOverwrite,
+                    // Deliberately NO `selfServeReplayToken`: a user-supplied invite is
+                    // re-presentable by the user, so it stays fingerprint-only on disk.
+                }, credentialWriteDeps);
+                // An existing bapi:<repo> credential is never clobbered without consent. The
+                // gate mirrors the host-config gate above: --force, else an interactive prompt,
+                // else a hard non-interactive failure — all BEFORE the exchange.
+                const prepared = await resolveCredentialConflictConsent(await prepareInvitePending(overwriteConsent), {
+                    isTTY: deps.isTTY,
+                    promptLine: deps.promptLine,
+                    errorLog,
+                    grantConsent: () => {
+                        overwriteConsent = true;
+                    },
+                    retry: () => prepareInvitePending(true),
+                });
+                if (prepared === null)
+                    return 1;
+                // A pending record left by a DIFFERENT invite is that redemption's only replay
+                // proof, so it is never overwritten. BAPI-667 removed the unconditional
+                // "re-running will not clear the conflict" suffix that used to be appended
+                // here: it is FALSE for a stored self-serve record, which a re-run resumes
+                // automatically. The credential store's own mode-aware message is now the
+                // single source of truth for what the user should do.
+                if (!prepared.ok && prepared.kind === "pending-conflict") {
+                    errorLog(`Error: ${prepared.error}`);
+                    return 1;
+                }
+                if (!prepared.ok) {
+                    // Fail closed: the exchange has NOT been called, so the invite is unspent.
+                    errorLog(`Error: could not durably store the bootstrap credential (${prepared.kind}). ${prepared.error} ` +
+                        "The bootstrap invite has NOT been used — fix the problem and re-run.");
+                    return 1;
+                }
+                keySecret = prepared.keySecret;
+                reusedPendingSecret = prepared.reused;
+                log(`  saved the pending credential for ${prepared.target} (fsynced before the exchange)`);
             }
-            const nextRepo = validated.value;
-            const repointed = await deps.repointBootstrapPending({
-                fromRepoName: repoName,
-                toRepoName: nextRepo,
-                inviteFingerprint,
-                allowOverwriteExistingCredential: overwriteConsent,
-            }, credentialWriteDeps);
-            if (!repointed.ok) {
-                errorLog(`Error: could not re-point the pending bootstrap credential to '${nextRepo}' ` +
-                    `(${repointed.kind}). ${repointed.error} The bootstrap invite has NOT been used.`);
-                return 1;
+            // The exchange REPLACES the pre-flight ping: in invite mode there is no key to
+            // ping with — this call is what mints it.
+            //
+            // The outer loop runs at most TWICE: once for the initial (or resumed)
+            // exchange, and — only after an explicit consent to discard an expired
+            // self-serve record — once more with a freshly minted token (R4-3).
+            let exchange;
+            let selfServeRefreshed = false;
+            for (;;) {
+                exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                // 409 repo_name_taken: the server ROLLED BACK, so the invite is NOT consumed and
+                // the SAME token can be retried under a new name — with the SAME pending secret,
+                // re-pointed to that name.
+                while (!exchange.ok && exchange.kind === "repo-name-taken") {
+                    if (!deps.isTTY || !deps.promptLine) {
+                        errorLog(`Error: ${exchange.message} Re-run with a different --repo (the bootstrap invite has NOT ` +
+                            "been used).");
+                        return 1;
+                    }
+                    errorLog(exchange.message);
+                    const answer = (await deps.promptLine("Choose a different repo name: ")).trim();
+                    const validated = validateRepoName(answer);
+                    if (!validated.ok) {
+                        errorLog(`Error: invalid repo name — ${validated.error}.`);
+                        return 1;
+                    }
+                    const nextRepo = validated.value;
+                    const repointed = await deps.repointBootstrapPending({
+                        fromRepoName: repoName,
+                        toRepoName: nextRepo,
+                        inviteFingerprint,
+                        allowOverwriteExistingCredential: overwriteConsent,
+                    }, credentialWriteDeps);
+                    if (!repointed.ok) {
+                        errorLog(`Error: could not re-point the pending bootstrap credential to '${nextRepo}' ` +
+                            `(${repointed.kind}). ${repointed.error} The bootstrap invite has NOT been used.`);
+                        return 1;
+                    }
+                    repoName = nextRepo;
+                    // Same token, same key_secret — never regenerated inside the rename loop.
+                    exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
+                }
+                if (exchange.ok)
+                    break;
+                // ---- Consent-gated self-serve recovery (BAPI-667, R4-3) ----
+                // ONLY a REPLAYED self-serve token that the server CONCLUSIVELY rejected (401)
+                // may be discarded and re-minted. Every other failure — network error, timeout,
+                // 5xx, malformed response, a freshly minted token's first 401, and any ordinary
+                // --invite 401 — leaves the record untouched, because in those cases the stored
+                // record may still be the only proof of a live admin key.
+                if (exchange.kind === "invalid-invite" &&
+                    resumedSelfServeReplay &&
+                    !selfServeRefreshed) {
+                    if (!deps.isTTY || !deps.promptLine) {
+                        return fatal(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE, `The saved attempt at ${getBootstrapPendingTarget(repoName)} in ${credentialStorePath} ` +
+                            "has been left untouched. Re-run install-bridge on an interactive terminal to " +
+                            "discard it and start a fresh signup.");
+                    }
+                    errorLog(BOOTSTRAP_SELF_SERVE_EXPIRED_MESSAGE);
+                    let consented = false;
+                    try {
+                        const answer = (await deps.promptLine(`Discard the saved signup at ${getBootstrapPendingTarget(repoName)} in ` +
+                            `${credentialStorePath} and start a fresh one? [y/N]: `)).trim().toLowerCase();
+                        consented = answer === "y" || answer === "yes";
+                    }
+                    catch {
+                        // A prompt that cannot be read is NOT consent. Never infer it.
+                        consented = false;
+                    }
+                    if (!consented) {
+                        errorLog("Aborted: the saved signup attempt was left unchanged (nothing was discarded).");
+                        return 1;
+                    }
+                    const discarded = await deps.discardBootstrapPending({ repoName, inviteFingerprint }, credentialWriteDeps);
+                    if (!discarded.ok) {
+                        // Stop WITHOUT minting: a fresh mint on top of a record we failed to
+                        // remove would strand the old record and its (possibly live) key.
+                        return fatal(`Error: could not discard the saved signup (${discarded.kind}). ${discarded.error}`);
+                    }
+                    log("Requesting a fresh Bridge self-serve setup…");
+                    if (!(await mintAndPrepareSelfServe()))
+                        return 1;
+                    selfServeRefreshed = true;
+                    // The refreshed token is brand new, so a 401 on it is no longer a
+                    // replay rejection and must not re-enter this branch.
+                    resumedSelfServeReplay = false;
+                    continue;
+                }
+                // The pending record is deliberately LEFT INTACT: it is the replay proof for a
+                // retry (network failure / transient error), and destroying it would be the
+                // unrecoverable case above. Every arm here is a terminal exchange failure —
+                // invalid invite, network error, unreadable/unexpected response — so each
+                // carries the doctor pointer exactly once (BAPI-669, U9a).
+                return fatal(exchange.kind === "invalid-invite"
+                    ? reusedPendingSecret
+                        ? BOOTSTRAP_INVITE_REJECTED_MESSAGE
+                        : BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE
+                    : // Transient/coarse failure: the exchange result is mode-neutral, so the
+                        // actionable retry instruction is appended here where the mode is known.
+                        `Error: ${exchange.message} ${buildBootstrapRetryAdvice(selfServeSignupMode)}`);
             }
-            repoName = nextRepo;
-            // Same token, same key_secret — never regenerated inside the rename loop.
-            exchange = await exchangeBootstrapInvite(deps, baseUrl, inviteToken, repoName, keySecret);
-        }
-        if (!exchange.ok) {
-            if (exchange.kind === "invalid-invite") {
-                errorLog(reusedPendingSecret
-                    ? BOOTSTRAP_INVITE_REJECTED_MESSAGE
-                    : BOOTSTRAP_INVITE_LOST_SECRET_MESSAGE);
+            // BAPI-668 (R5-2): the ONE orchestration transition that says "the invite is
+            // spent and the key exists server-side". From here a failure is RESUMABLE, so
+            // this same flag gates both the promotion path below and the catch block's
+            // resume guidance — the two can never disagree about post-exchange state.
+            bootstrapExchangeSucceeded = true;
+            // The server-returned name is authoritative from here on: config, ping,
+            // credential target, and the spawned session all key off it.
+            if (exchange.repoName !== repoName) {
+                const repointed = await deps.repointBootstrapPending({
+                    fromRepoName: repoName,
+                    toRepoName: exchange.repoName,
+                    inviteFingerprint,
+                    allowOverwriteExistingCredential: overwriteConsent,
+                }, credentialWriteDeps);
+                if (!repointed.ok) {
+                    return fatal(`Error: the project was created as '${exchange.repoName}' but the pending credential could ` +
+                        `not be re-pointed to it (${repointed.kind}). ${repointed.error}`);
+                }
+                repoName = exchange.repoName;
             }
-            else {
-                errorLog(`Error: ${exchange.message}`);
+            log(`  bootstrap invite redeemed — project '${repoName}' is ready`);
+            // The minted key. From here the flow rejoins the existing path unchanged.
+            apiKey = keySecret;
+        }
+        // ---- Step 2 (cont.) — verify connectivity BEFORE writing the key anywhere durable ----
+        // R5: ping before persisting anything durably. Pinging before writeHostConfigs
+        // (and the credential store) means a bad key on a first-time install halts
+        // WITHOUT leaving an invalid key in the config — which would otherwise trip the
+        // overwrite-consent gate on every retry (a trapped state). In invite mode this
+        // runs AFTER the exchange, with the just-minted key; the pending record is the one
+        // deliberate write that precedes it, for the protocol reason above.
+        if (!bootstrapInviteMode) {
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.verifyConnectivity;
+            log(currentStep);
+        }
+        // BAPI-668: a bootstrap-minted key is verified WITHOUT source attribution.
+        const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey, bootstrapInviteMode ? undefined : apiKeySource);
+        if (!ping.ok) {
+            // BAPI-667: in either need-key mode the exchange already succeeded and the
+            // pending record survives, so this failure IS resumable — but only with the
+            // instruction that matches how the token was obtained.
+            return fatal(bootstrapInviteMode
+                ? `Error: ${ping.message} ${buildBootstrapRetryAdvice(selfServeSignupMode)}`
+                : `Error: ${ping.message}`);
+        }
+        log("  connectivity OK");
+        const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
+        // BAPI-666: the secret-free variant (no BAPI_API_KEY) is written instead of the
+        // real entry into any git-tracked project config the user did not explicitly
+        // consent to, and into any target left invalid — so the real key is never
+        // written to a tracked or un-ignored project config without explicit consent.
+        const secretFreeEntry = buildInstallBridgeSecretFreeServerEntry(deps.cwd, repoName, baseUrl, docsDir);
+        // ---- Step 3 — write per-host MCP config ----
+        // Valid, untracked (freshly-gitignored) project configs receive the REAL key.
+        // Git-tracked configs require explicit TTY consent (default-No) or fall back to
+        // the secret-free entry; invalid (unparseable) configs are left untouched.
+        currentStep = INSTALL_BRIDGE_STEP_LABELS.writeHostConfigs;
+        log(currentStep);
+        // BAPI-635 (Step 8): every project-local, secret-bearing config MUST be
+        // gitignored BEFORE the real API key is written. A project-target gitignore
+        // failure is FATAL before the secret write (fixed, secret-free message).
+        const gitignoreDeps = {
+            readFile: deps.readFile,
+            writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
+            mkdir: (p, o) => deps.mkdir(p, o),
+        };
+        for (const target of targets) {
+            try {
+                await ensureGitignoredShared(deps.cwd, target.relPath, gitignoreDeps);
             }
-            // The pending record is deliberately LEFT INTACT: it is the replay proof for a
-            // retry (network failure / transient error), and destroying it would be the
-            // unrecoverable case above.
-            return 1;
-        }
-        // The server-returned name is authoritative from here on: config, ping,
-        // credential target, and the spawned session all key off it.
-        if (exchange.repoName !== repoName) {
-            const repointed = await deps.repointBootstrapPending({
-                fromRepoName: repoName,
-                toRepoName: exchange.repoName,
-                inviteFingerprint,
-                allowOverwriteExistingCredential: overwriteConsent,
-            }, credentialWriteDeps);
-            if (!repointed.ok) {
-                errorLog(`Error: the project was created as '${exchange.repoName}' but the pending credential could ` +
-                    `not be re-pointed to it (${repointed.kind}). ${repointed.error}`);
+            catch {
+                errorLog("Error: could not add a project MCP config to .gitignore before writing your key. " +
+                    "Aborting so the API key is never written to an un-ignored file.");
                 return 1;
             }
-            repoName = exchange.repoName;
-        }
-        log(`  bootstrap invite redeemed — project '${repoName}' is ready`);
-        // The minted key. From here the flow rejoins the existing path unchanged.
-        apiKey = keySecret;
-    }
-    // ---- Step 2 (cont.) — verify connectivity BEFORE writing the key anywhere durable ----
-    // R5: ping before persisting anything durably. Pinging before writeHostConfigs
-    // (and the credential store) means a bad key on a first-time install halts
-    // WITHOUT leaving an invalid key in the config — which would otherwise trip the
-    // overwrite-consent gate on every retry (a trapped state). In invite mode this
-    // runs AFTER the exchange, with the just-minted key; the pending record is the one
-    // deliberate write that precedes it, for the protocol reason above.
-    if (!bootstrapInviteMode)
-        log("Step 2/5 — verifying connectivity…");
-    const ping = await verifyConnectivity(deps, baseUrl, repoName, apiKey);
-    if (!ping.ok) {
-        errorLog(`Error: ${ping.message}`);
-        return 1;
-    }
-    log("  connectivity OK");
-    const entry = buildInstallBridgeServerEntry(deps.cwd, repoName, apiKey, baseUrl, docsDir);
-    // ---- Step 3 — write per-host MCP config with real values ----
-    log("Step 3/5 — writing per-host MCP config…");
-    // BAPI-635 (Step 8): every project-local, secret-bearing config MUST be
-    // gitignored BEFORE the real API key is written. A project-target gitignore
-    // failure is FATAL before the secret write (fixed, secret-free message).
-    const gitignoreDeps = {
-        readFile: deps.readFile,
-        writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
-        mkdir: (p, o) => deps.mkdir(p, o),
-    };
-    for (const target of targets) {
+        }
+        // BAPI-666: after the (fatal) gitignore prerequisite has succeeded and before any
+        // target can receive the real key, probe each project target's git-tracked state
+        // (read-only, fail-open). A tracked config would carry the key into version control,
+        // so it only receives the real key with explicit TTY consent — otherwise the
+        // secret-free entry. Global targets are provisioned separately and are outside this
+        // project-local Git guard.
+        const trackedState = new Map();
+        for (const target of targets) {
+            trackedState.set(target.relPath, await isTrackedProjectConfig(deps, target.relPath));
+        }
+        const writeResult = await writeHostConfigs(deps, targets, { real: entry, secretFree: secretFreeEntry }, trackedState, { repoName, credentialStorePath });
+        for (const { relPath, mode } of writeResult.written) {
+            log(mode === "secret-free" ? `  wrote ${relPath} (secret-free — key resolved at runtime)` : `  wrote ${relPath}`);
+        }
+        for (const { relPath } of writeResult.skipped) {
+            log(`  skipped ${relPath} — existing config could not be parsed safely; left untouched`);
+        }
+        // BAPI-635: provision selected GLOBAL targets (Codex, Copilot CLI) and MANUAL
+        // targets (Windsurf) via the registry-driven emitter. Global paths are never
+        // added to the repository .gitignore.
+        // BAPI-669 (R8): only a need-key run has a key the user has never seen, so only it
+        // needs to be told where that key was stored. `bootstrapInviteMode` is true for the
+        // explicit invite, the self-serve, AND the reclassified-invite flows alike, and
+        // carries no credential — just the repo name and the store path.
+        const needKeyManual = bootstrapInviteMode
+            ? { repoName, credentialStorePath }
+            : undefined;
+        const globalLogLines = await provisionSelectedGlobalTargets(deps, selectedPlatforms, entry, needKeyManual);
+        for (const line of globalLogLines)
+            log(line);
+        // Legacy manual-editor instructions cover editors that are DETECTED but were
+        // NOT part of the selection (so the emitter above did not handle them). The two
+        // editors are suppressed INDEPENDENTLY: Codex is dropped when it was selected
+        // (auto-provisioned or emitted above), Windsurf is dropped only when it was
+        // selected — auto-provisioning Codex must never hide the Windsurf snippet.
+        const legacyManualEditors = {
+            windsurf: manualEditors.windsurf && !selectedPlatforms.includes("windsurf"),
+            codex: manualEditors.codex && !selectedPlatforms.includes("codex"),
+        };
+        const manualInstructions = buildManualHostInstructions(entry, legacyManualEditors, needKeyManual);
+        if (manualInstructions)
+            log(manualInstructions);
+        // BAPI-635 (Step 7): when both Claude Code and Copilot CLI are selected, warn
+        // that they use different, non-shared config surfaces.
+        if (selectedPlatforms.includes("claude-code") && selectedPlatforms.includes("copilot-cli")) {
+            log("  Note: Claude Code uses the project .mcp.json while GitHub Copilot CLI uses only its " +
+                "global ~/.copilot/mcp-config.json — the two are configured separately.");
+        }
+        // BAPI-635 (Step 7): Claude trust reminder — a written project MCP config is
+        // not a live connection until approved in Claude Code's trust dialog.
+        if (selectedPlatforms.includes("claude-code")) {
+            log("  Claude Code: the project MCP server is pending approval in Claude Code's trust dialog; " +
+                "restart or reload an already-running session for it to take effect.");
+        }
+        // BAPI-635 (Step 8 + Step 3): persist the secret-free install state, ignoring
+        // it before the write. Project-local paths only; global paths are never in it.
         try {
-            await ensureGitignoredShared(deps.cwd, target.relPath, gitignoreDeps);
+            await ensureGitignoredShared(deps.cwd, ".bridge/install-state.json", gitignoreDeps);
+            // writeMcpInstallState catches its own I/O errors and returns { ok: false }
+            // (it does NOT throw), so the failure warning must inspect the return value —
+            // a try/catch alone would silently swallow a real persistence failure.
+            const stateResult = await writeMcpInstallState(deps.cwd, { selectedPlatforms, projectConfigPaths: targets.map((t) => t.relPath) }, {
+                readFile: deps.readFile,
+                writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
+                rename: deps.rename,
+                mkdir: async (p, o) => {
+                    await deps.mkdir(p, o);
+                },
+                unlink: deps.unlink,
+            });
+            if (!stateResult.ok) {
+                // Install-state persistence is advisory — never fail the install over it.
+                errorLog("Warning: could not persist the install-state file (non-fatal).");
+            }
         }
         catch {
-            errorLog("Error: could not add a project MCP config to .gitignore before writing your key. " +
-                "Aborting so the API key is never written to an un-ignored file.");
-            return 1;
-        }
-    }
-    const written = await writeHostConfigs(deps, targets, entry);
-    for (const relPath of written)
-        log(`  wrote ${relPath}`);
-    // BAPI-635: provision selected GLOBAL targets (Codex, Copilot CLI) and MANUAL
-    // targets (Windsurf) via the registry-driven emitter. Global paths are never
-    // added to the repository .gitignore.
-    const globalLogLines = await provisionSelectedGlobalTargets(deps, selectedPlatforms, entry);
-    for (const line of globalLogLines)
-        log(line);
-    // Legacy manual-editor instructions cover editors that are DETECTED but were
-    // NOT part of the selection (so the emitter above did not handle them). The two
-    // editors are suppressed INDEPENDENTLY: Codex is dropped when it was selected
-    // (auto-provisioned or emitted above), Windsurf is dropped only when it was
-    // selected — auto-provisioning Codex must never hide the Windsurf snippet.
-    const legacyManualEditors = {
-        windsurf: manualEditors.windsurf && !selectedPlatforms.includes("windsurf"),
-        codex: manualEditors.codex && !selectedPlatforms.includes("codex"),
-    };
-    const manualInstructions = buildManualHostInstructions(entry, legacyManualEditors);
-    if (manualInstructions)
-        log(manualInstructions);
-    // BAPI-635 (Step 7): when both Claude Code and Copilot CLI are selected, warn
-    // that they use different, non-shared config surfaces.
-    if (selectedPlatforms.includes("claude-code") && selectedPlatforms.includes("copilot-cli")) {
-        log("  Note: Claude Code uses the project .mcp.json while GitHub Copilot CLI uses only its " +
-            "global ~/.copilot/mcp-config.json — the two are configured separately.");
-    }
-    // BAPI-635 (Step 7): Claude trust reminder — a written project MCP config is
-    // not a live connection until approved in Claude Code's trust dialog.
-    if (selectedPlatforms.includes("claude-code")) {
-        log("  Claude Code: the project MCP server is pending approval in Claude Code's trust dialog; " +
-            "restart or reload an already-running session for it to take effect.");
-    }
-    // BAPI-635 (Step 8 + Step 3): persist the secret-free install state, ignoring
-    // it before the write. Project-local paths only; global paths are never in it.
-    try {
-        await ensureGitignoredShared(deps.cwd, ".bridge/install-state.json", gitignoreDeps);
-        // writeMcpInstallState catches its own I/O errors and returns { ok: false }
-        // (it does NOT throw), so the failure warning must inspect the return value —
-        // a try/catch alone would silently swallow a real persistence failure.
-        const stateResult = await writeMcpInstallState(deps.cwd, { selectedPlatforms, projectConfigPaths: targets.map((t) => t.relPath) }, {
-            readFile: deps.readFile,
-            writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
-            rename: deps.rename,
-            mkdir: async (p, o) => {
-                await deps.mkdir(p, o);
-            },
-            unlink: deps.unlink,
-        });
-        if (!stateResult.ok) {
-            // Install-state persistence is advisory — never fail the install over it.
+            // ensureGitignored for the state file can still throw — also advisory.
             errorLog("Warning: could not persist the install-state file (non-fatal).");
         }
-    }
-    catch {
-        // ensureGitignored for the state file can still throw — also advisory.
-        errorLog("Warning: could not persist the install-state file (non-fatal).");
-    }
-    // ---- Step 4 — persist the credential ----
-    if (bootstrapInviteMode) {
-        // FAIL-CLOSED (unlike normal mode below). The pending secret IS the minted admin
-        // key — if it never lands under bapi:<repo>, the user has a live key they cannot
-        // resolve. Promotion removes the pending record and writes the credential in one
-        // durable replacement; on failure the pending record survives so a re-run replays
-        // the same redemption. The agent session is NOT spawned until this succeeds.
-        log("Step 4/5 — promoting the bootstrap credential…");
-        const promoted = await deps.promoteBootstrapPending({ repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent }, credentialWriteDeps);
-        if (!promoted.ok) {
-            errorLog(`Error: the project and API key were created, but the credential could not be stored ` +
-                `(${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending ` +
-                "record — re-run install-bridge with the same bootstrap invite to finish (the redemption " +
-                "will replay and return the same key).");
-            return 1;
+        // ---- Step 4 — persist the credential ----
+        // Gated on the post-exchange transition rather than the mode flag (BAPI-668):
+        // in bootstrap mode the exchange loop above is the ONLY way to reach here, so the
+        // two are equivalent — but keying promotion to the same state that justifies the
+        // catch block's resume guidance makes that invariant explicit and un-driftable.
+        if (bootstrapExchangeSucceeded) {
+            // FAIL-CLOSED (unlike normal mode below). The pending secret IS the minted admin
+            // key — if it never lands under bapi:<repo>, the user has a live key they cannot
+            // resolve. Promotion removes the pending record and writes the credential in one
+            // durable replacement; on failure the pending record survives so a re-run replays
+            // the same redemption. The agent session is NOT spawned until this succeeds.
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.promoteCredential;
+            log(currentStep);
+            const promoted = await deps.promoteBootstrapPending({ repoName, inviteFingerprint, allowOverwriteExistingCredential: overwriteConsent }, credentialWriteDeps);
+            if (!promoted.ok) {
+                // Mode-aware (BAPI-667): a self-serve user has no invite to "re-present" —
+                // telling them to is an instruction they cannot follow.
+                return fatal(`Error: the project and API key were created, but the credential could not be stored ` +
+                    `(${promoted.kind}). ${promoted.error} Your key is still saved locally as a pending ` +
+                    `record. ${buildBootstrapRetryAdvice(selfServeSignupMode)}`);
+            }
+            log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
         }
-        log(`  stored routing credential for ${promoted.target} at ${promoted.path}`);
-    }
-    else {
-        // ---- persist routing credential (non-blocking / fail-open) ----
-        log("Step 4/5 — persisting routing credential…");
-        try {
-            const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
-            if (result.ok) {
-                log(`  stored routing credential for ${result.target} at ${result.path}`);
+        else {
+            // ---- persist routing credential (non-blocking / fail-open) ----
+            currentStep = INSTALL_BRIDGE_STEP_LABELS.persistCredential;
+            log(currentStep);
+            try {
+                const result = await deps.upsertCredential(repoName, apiKey, credentialWriteDeps);
+                if (result.ok) {
+                    log(`  stored routing credential for ${result.target} at ${result.path}`);
+                }
+                else {
+                    log(`  warning: could not persist the routing credential (${result.kind}). ` +
+                        `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
+                        "and will fail open to the premium/Opus tier (the most expensive) — " +
+                        "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+                        "'npx -y @bridge_gpt/mcp-server doctor'.");
+                }
             }
-            else {
-                log(`  warning: could not persist the routing credential (${result.kind}). ` +
-                    `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
-                    "and will fail open to the premium/Opus tier (the most expensive) — " +
-                    "set BAPI_API_KEY in the shell or re-run install-bridge, then verify with " +
+            catch {
+                // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
+                // included in the warning.
+                log("  warning: could not persist the routing credential (unexpected error). " +
+                    "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
+                    "to the premium/Opus tier (the most expensive) until fixed — verify with " +
                     "'npx -y @bridge_gpt/mcp-server doctor'.");
             }
         }
-        catch {
-            // Fail-open: persistence is best-effort (mirrors Stage 6). The secret is never
-            // included in the warning.
-            log("  warning: could not persist the routing credential (unexpected error). " +
-                "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
-                "to the premium/Opus tier (the most expensive) until fixed — verify with " +
-                "'npx -y @bridge_gpt/mcp-server doctor'.");
-        }
-    }
-    // ---- optional GitHub connect offer (BAPI-631) ----
-    // Placed AFTER the credential is durable (the flow needs a resolvable key) and BEFORE
-    // the agent spawn, for two reasons: the spawned session's capability report should
-    // observe GitHub as configured if the user connects it here, and running it after the
-    // spawn would put two prompts on the same terminal at once.
-    await offerGithubConnection(repoName, deps, log);
-    // ---- Step 3b (await) — settle the background pre-warm before the session opens ----
-    // The warm was kicked off (only on a spawn-capable path) right after the
-    // launch-command guards; await it HERE so the bucket is settled before the spawned
-    // session's first MCP launch, but AFTER all the work it overlapped with — and BEFORE
-    // the consent prompt, so no spawn ever races an in-flight warm. Strictly fail-open —
-    // the exit code is never affected. Skipped entirely when no session will be opened.
-    if (prewarmPromise) {
-        const prewarm = await prewarmPromise;
-        if (prewarm.ok) {
-            log("  launcher bucket warmed (the first MCP launch will not pay a cold install).");
-            log(`  ${MCP_TIMEOUT_GUIDANCE}`);
+        // ---- optional GitHub connect offer (BAPI-631) ----
+        // Placed AFTER the credential is durable (the flow needs a resolvable key) and BEFORE
+        // the agent spawn, for two reasons: the spawned session's capability report should
+        // observe GitHub as configured if the user connects it here, and running it after the
+        // spawn would put two prompts on the same terminal at once.
+        await offerGithubConnection(repoName, baseUrl, deps, log);
+        // ---- Step 3b (await) — settle the background pre-warm before the session opens ----
+        // The warm was kicked off (only on a spawn-capable path) right after the
+        // launch-command guards; await it HERE so the bucket is settled before the spawned
+        // session's first MCP launch, but AFTER all the work it overlapped with — and BEFORE
+        // the consent prompt, so no spawn ever races an in-flight warm. Strictly fail-open —
+        // the exit code is never affected. Skipped entirely when no session will be opened.
+        if (prewarmPromise) {
+            const prewarm = await prewarmPromise;
+            if (prewarm.ok) {
+                log("  launcher bucket warmed (the first MCP launch will not pay a cold install).");
+                log(`  ${MCP_TIMEOUT_GUIDANCE}`);
+            }
+            else {
+                // Escalate to a stronger, still secret-free warning when pre-warm didn't
+                // complete cleanly — but the install itself still succeeds (exit unaffected).
+                errorLog(`Warning: could not pre-warm the version-pinned launcher bucket${prewarm.warning ? ` (${prewarm.warning})` : ""}. ` +
+                    `The first MCP launch may pay a one-time cold install and could be slow. ${MCP_TIMEOUT_GUIDANCE}`);
+            }
         }
-        else {
-            // Escalate to a stronger, still secret-free warning when pre-warm didn't
-            // complete cleanly — but the install itself still succeeds (exit unaffected).
-            errorLog(`Warning: could not pre-warm the version-pinned launcher bucket${prewarm.warning ? ` (${prewarm.warning})` : ""}. ` +
-                `The first MCP launch may pay a one-time cold install and could be slow. ${MCP_TIMEOUT_GUIDANCE}`);
-        }
-    }
-    // ---- Step 5 — consent-gate, then spawn the selected tool (or print continuation) ----
-    // AC-7: for a spawn-capable path, ask Y/N first (`requestInstallBridgeLaunchConsent`
-    // resolves to no-spawn without prompting on a non-TTY run). A decline, a no-launchable
-    // selection, a non-TTY run, or a declined/aborted chooser all skip the spawn and fall
-    // through to the shared /install-bridge continuation + limited-tools notice below — so
-    // every no-session outcome gets identical, accurate remediation.
-    if (finalAgentName && launchCommand) {
-        const consent = await requestInstallBridgeLaunchConsent(toolLabelForLaunchAgent(finalAgentName), deps);
-        if (consent === "spawn") {
-            log(`Step 5/5 — opening a ${finalAgentName} session for /install-bridge configuration + concise capability report…`);
-            const terminal = detectTerminal(undefined, deps.env);
-            // Only the validated short runner reaches the terminal — never the inline prompt.
-            // The branded "Bridge Install" title labels the tab/badge instead of "install
-            // Implementation" (AC-6).
-            const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, launchCommand, {
-                key: "install",
-                worktreePath: deps.cwd,
-                title: "Bridge Install",
-            });
-            if (!spawnResult.ok) {
-                // Steps 1–4 (scaffold, config, connectivity-verified, credential persist) all
-                // succeeded and are durable; only the best-effort Step 5 tab spawn failed. The
-                // deterministic setup is complete, so this is a non-fatal warning (exit 0), with
-                // the same shared continuation so the remediation is consistent.
-                errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}).`);
-                log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
+        // ---- Step 5 — consent-gate, then spawn the selected tool (or print continuation) ----
+        // AC-7: for a spawn-capable path, ask Y/N first (`requestInstallBridgeLaunchConsent`
+        // resolves to no-spawn without prompting on a non-TTY run). A decline, a no-launchable
+        // selection, a non-TTY run, or a declined/aborted chooser all skip the spawn and fall
+        // through to the shared /install-bridge continuation + limited-tools notice below — so
+        // every no-session outcome gets identical, accurate remediation.
+        if (finalAgentName && launchCommand) {
+            const consent = await requestInstallBridgeLaunchConsent(toolLabelForLaunchAgent(finalAgentName), deps);
+            if (consent === "spawn") {
+                currentStep = buildInstallBridgeLaunchStepLabel(finalAgentName);
+                log(currentStep);
+                const terminal = detectTerminal(undefined, deps.env);
+                // Only the validated short runner reaches the terminal — never the inline prompt.
+                // The branded "Bridge Install" title labels the tab/badge instead of "install
+                // Implementation" (AC-6).
+                const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, launchCommand, {
+                    key: "install",
+                    worktreePath: deps.cwd,
+                    title: "Bridge Install",
+                });
+                if (!spawnResult.ok) {
+                    // Steps 1–4 (scaffold, config, connectivity-verified, credential persist) all
+                    // succeeded and are durable; only the best-effort Step 5 tab spawn failed. The
+                    // deterministic setup is complete, so this is a non-fatal warning (exit 0), with
+                    // the same shared continuation so the remediation is consistent.
+                    errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}).`);
+                    log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
+                    return 0;
+                }
+                // BAPI-669 (U3): the handoff speaks the HOST TOOL'S display label, never the
+                // raw agent binary name — computed once so all three sentences agree.
+                const handoffToolLabel = toolLabelForLaunchAgent(finalAgentName);
+                log("");
+                log(`install-bridge setup steps complete. A fresh ${handoffToolLabel} session is now applying ` +
+                    "configuration, presenting the concise capability report, and recommending /learn-repository.");
+                // The trust dialog is the single most common place a spawned session stalls:
+                // the tab opens, nothing is approved, and the install looks hung.
+                log(`In the new tab: approve the workspace and the 'bridge-api' MCP server if ${handoffToolLabel} ` +
+                    "asks — configuration can't proceed until you do.");
+                // Recovery was previously printed ONLY on no-spawn paths, so a tab that opened
+                // and then died left the user with no instruction at all.
+                log(`If that tab is closed or fails, open a session in ${handoffToolLabel} and run /install-bridge.`);
+                log("NOTE: the install is not finished until that session's apply reports applied fields — " +
+                    "it will pause to ask you to approve the project description. Indexing starts automatically " +
+                    "once the repository reaches full parse readiness — there is no indexing question to answer. " +
+                    `Verify afterwards at ${setupUrl} (Get Started page — install status panel) or via the ` +
+                    "session's 'Applied N of M' summary.");
                 return 0;
             }
-            log("");
-            log(`install-bridge setup steps complete. A fresh ${finalAgentName} session is now applying ` +
-                "configuration, presenting the concise capability report, and recommending /learn-repository.");
-            log("NOTE: the install is not finished until that session's apply reports applied fields — " +
-                "it will pause to ask you to approve the project description. Indexing starts automatically " +
-                "once the repository reaches full parse readiness — there is no indexing question to answer. " +
-                "Verify afterwards on the project's Get Started page (install status panel) or via the " +
-                "session's 'Applied N of M' summary.");
+            // Declined (or non-TTY suppression): the deterministic setup is complete and durable.
+            log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
             return 0;
         }
-        // Declined (or non-TTY suppression): the deterministic setup is complete and durable.
+        // No launchable session (a no-launchable selection, or a non-TTY / declined chooser):
+        // finalAgentName is null, so nothing was materialized. The configured hosts are
+        // durable — print the shared continuation + limited-tools note (never the
+        // empty-selection variant, which already returned above).
         log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
         return 0;
     }
-    // No launchable session (a no-launchable selection, or a non-TTY / declined chooser):
-    // finalAgentName is null, so nothing was materialized. The configured hosts are
-    // durable — print the shared continuation + limited-tools note (never the
-    // empty-selection variant, which already returned above).
-    log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
-    return 0;
+    catch (error) {
+        // Resume guidance ONLY after the exchange actually succeeded (R5-2): before
+        // that the invite is unspent and there is nothing to resume. The wording comes
+        // from the mode-aware helper, never a fresh literal, so a self-serve user is
+        // never told to re-present a token they were never shown.
+        const resumeAdvice = bootstrapInviteMode && bootstrapExchangeSucceeded
+            ? buildBootstrapRetryAdvice(selfServeSignupMode)
+            : undefined;
+        // The formatter receives ONLY safe context: a printed step label, the debug
+        // gate, and the helper-produced advice. No apiKey, inviteToken, fingerprint,
+        // keySecret, signup email, or response body is in scope for it by construction.
+        // Raw diagnostics are emitted through `errorLog`, NOT `deps.debugLog`, whose
+        // contract admits only secret-free text.
+        const lines = buildInstallBridgeFailureLines(error, {
+            step: currentStep,
+            debugEnabled: Boolean(deps.env.BAPI_INSTALL_DEBUG),
+            ...(resumeAdvice ? { resumeAdvice } : {}),
+        });
+        for (const line of lines)
+            errorLog(line);
+        return 1;
+    }
 }