@bridge_gpt/mcp-server 0.2.28 → 0.2.30

package/build/install-bridge.js

@@ -57,10 +57,23 @@
  * repository prompt asks for a new project name rather than an existing
  * registration (see `RepoNamePromptMode`).
  *
- * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the two exceptions to "this command
- * consumes a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
- * API key yet, so the pre-flight ping of Step 2 CANNOT be made: the exchange is
- * what mints the key, and it REPLACES that ping. The order becomes:
+ * ORDINARY-ENTRY INVITE RECLASSIFICATION (BAPI-661) — the have-key branch's own
+ * credential input (`--api-key`, `BAPI_API_KEY`, or its hidden prompt) is
+ * CREDENTIAL-AGNOSTIC: it accepts a full API key OR a bootstrap-invite token,
+ * because a user handed only an invite has no way to know it belongs in a
+ * different flag. `classifyEnteredCredential` inspects the resolved value
+ * immediately after input resolution (before repository-name resolution); a
+ * `bapi_inv_…` value flips the branch's `bootstrapInviteMode`/`inviteToken` and
+ * the run falls into the SAME bootstrap-invite protocol described below, verbatim.
+ * Explicit `--invite`/`BAPI_INVITE` and `--email`/`BAPI_SIGNUP_EMAIL` are never
+ * reclassified — they are already unambiguous and remain authoritative.
+ *
+ * BOOTSTRAP-INVITE MODE (BAPI-606) — one of the exceptions to "this command
+ * consumes a key, it does not create one" (the ordinary-entry reclassification
+ * above is the other). With `--invite` (or `BAPI_INVITE`, or a reclassified
+ * ordinary-entry value) there is no API key yet, so the pre-flight ping of Step 2
+ * CANNOT be made: the exchange is what mints the key, and it REPLACES that ping.
+ * The order becomes:
  *
  *   resolve bootstrap-invite token (no-echo prompt by DEFAULT — the delivered
  *   one-liner is secret-free) → resolve repo name → scaffold → generate
@@ -137,18 +150,27 @@ export function buildPrewarmCommandPreview() {
  * (`maybe_auto_parse_if_ready`), with no prompt on any path.
  */
 export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running " +
-    "in the install-spawn context so it SKIPS its Stage 8, Stage 9, and Stage 10 offers — this " +
-    "session's only closing interaction is the concise capability report and learn recommendation " +
-    "below). " +
-    "Complete the command's read-after-write concise capability report first: the single 'What Bridge " +
+    "in the install-spawn context so it SKIPS its Stage 8, Stage 9, and Stage 10 offers). " +
+    "The command chooses its own mode from the install manifest's `configured` flag — do NOT force a " +
+    "mode: when `configured` is false it runs its fresh-configuration flow, and when `configured` is " +
+    "true it runs JOIN MODE. In JOIN MODE the command must NOT derive, approve, apply, or offer any " +
+    "configuration and applies zero fields for any caller; a joining member's only closing interaction " +
+    "is the welcome plus the concise capability report (no /learn-repository prompt for a member). " +
+    "Complete the command's concise capability report: the single 'What Bridge " +
     "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it " +
     "(Regularly useful, then Occasionally useful, each tool's display_name only, plus each tier's " +
     "server-computed '+N more' where non-zero). Do not render the obsolete five-section report, and do " +
     "not locally filter, count, or fall back to the complete tool_capabilities catalog. " +
+    "The install-spawn skip set is exactly Stage 8, Stage 9, and Stage 10. The command-owned Stage 11 " +
+    "(invite teammates) is NOT in that skip set: it is independently gated and may run only when the " +
+    "caller's role is admin AND customer_type is b2b AND an interactive response is available; " +
+    "otherwise it is skipped silently. If Stage 11 mints a teammate key, show that plaintext key " +
+    "exactly once and never repeat it in any summary, retry, or diagnostic. " +
     "Do NOT ask any indexing question, call parse_repository, mention /parse-repository, or claim " +
     "indexing has started or is pending — indexing is decided entirely by the server-side readiness " +
     "funnel with no visibility from this session, so say nothing about it at all. " +
-    "After the capability report, recommend /learn-repository as the next step: explain briefly that it " +
+    "After the capability report on the fresh-configuration path, recommend /learn-repository as the " +
+    "next step: explain briefly that it " +
     "learns repository-specific architecture, review, testing, correctness, and validation-manual " +
     "configuration by researching the actual codebase. Do NOT run /learn-repository yourself — only " +
     "recommend it; running it is the human's next explicit invocation. " +
@@ -156,9 +178,11 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "integration's own configure_in pointer, verbatim. The pointer is per-integration and is NOT " +
     "always the setup UI: GitHub's is a terminal command (connect-github), while Jira, SFCC, and " +
     "Bitbucket point at the setup UI. Follow whatever the report says rather than assuming. " +
-    "End with an explicit summary line stating how many config fields the apply_install_manifest call " +
+    "On the fresh-configuration path, end with an explicit summary line stating how many config fields " +
+    "the apply_install_manifest call " +
     "applied (e.g. 'Applied 8 of 9 derived fields') — if 0 fields were applied, say so loudly and " +
-    "explain what is still pending.";
+    "explain what is still pending. In JOIN MODE there is no apply — state instead that the project " +
+    "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";
 /** Default docs dir when `BAPI_DOCS_DIR` is unset (mirrors index.ts). */
@@ -172,10 +196,13 @@ export function getInstallBridgeUsage() {
         "One-command Bridge API project bootstrap. Scaffolds the project, writes the",
         "per-host MCP config with your credentials, verifies connectivity, persists the",
         "routing credential, then — on a TTY, only after a Y/N consent prompt — opens a",
-        "fresh session in your selected tool to derive the remaining config, present a",
-        "concise capability report, and recommend /learn-repository. Indexing is never",
-        "asked about — it starts automatically once the repository reaches full parse",
-        "readiness.",
+        "fresh session in your selected tool. If the project is not yet configured it",
+        "derives the remaining config, presents a concise capability report, and",
+        "recommends /learn-repository. If the project is already configured it instead",
+        "joins you to it without proposing or applying any changes and just shows the",
+        "concise capability report (a b2b admin is additionally offered a teammate-invite",
+        "step). So not every run applies config fields. Indexing is never asked about —",
+        "it starts automatically once the repository reaches full parse readiness.",
         "",
         "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`,
@@ -185,11 +212,15 @@ export function getInstallBridgeUsage() {
         "an interactive terminal keeps the existing deterministic behavior and no prompt.",
         "",
         "Inputs (the only two irreducible ones):",
-        "  --api-key <key>   Bridge API key. Falls back to the BAPI_API_KEY env var,",
-        "                    then an interactive (no-echo) prompt. Generate one in the",
-        "                    Bridge API web UI Security page — this command consumes a",
-        "                    key, it does not create one (--email and --invite are the",
-        "                    exceptions: they CREATE the project and its first admin key).",
+        "  --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",
+        "                    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",
+        "                    project and its first admin key — the same as --invite —",
+        "                    so it skips repository lookup entirely (--email and --invite",
+        "                    remain the explicit, preferred entry points for a new project).",
         "                    NEVER printed or logged.",
         "  --repo <name>     Repository name. --repo and BAPI_REPO_NAME still take",
         "                    priority and short-circuit before any network call. When",
@@ -244,10 +275,12 @@ export function getInstallBridgeUsage() {
         `                                ${HOST_PLATFORM_ORDER.join(", ")}.`,
         "                                Both --tools=claude-code,codex and",
         "                                --tools claude-code,codex are accepted. On an",
-        "                                interactive terminal WITHOUT this flag the",
-        "                                checklist starts EMPTY — no tool is pre-selected",
-        "                                (not even Claude Code) and you must select at",
-        "                                least one. A non-interactive (non-TTY) run without",
+        "                                interactive terminal WITHOUT this flag you get a",
+        "                                numbered picker: enter one or more tool numbers,",
+        "                                comma-separated (e.g. 1,3), and press Enter once —",
+        "                                no tool is pre-selected (not even Claude Code) and",
+        "                                you must select at least one. A non-interactive",
+        "                                (non-TTY) run without",
         "                                --tools writes the legacy automatic set (Claude",
         "                                Code plus any detected Cursor / Copilot VS Code)",
         "                                and never opens an agent terminal (it prints",
@@ -710,8 +743,16 @@ export function createDefaultInstallBridgeDeps() {
     };
 }
 /**
- * Resolve the API key: `--api-key` → `BAPI_API_KEY` env → interactive no-echo
- * prompt. Fails (secret-free) when none is available and stdin is non-interactive.
+ * Resolve the ordinary credential entry: `--api-key` → `BAPI_API_KEY` env →
+ * interactive no-echo prompt. Fails (secret-free) when none is available and
+ * stdin is non-interactive.
+ *
+ * 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
+ * resolves and routes an invite into the existing redemption workflow. This
+ * function itself performs no classification; it only resolves which raw string
+ * was entered.
  */
 export async function resolveApiKey(options, deps) {
     if (typeof options.apiKey === "string" && options.apiKey.trim().length > 0) {
@@ -722,16 +763,20 @@ export async function resolveApiKey(options, deps) {
         return { ok: true, value: fromEnv.trim() };
     }
     if (deps.isTTY && deps.promptSecret) {
-        const entered = (await deps.promptSecret("Bridge API key (input hidden): ")).trim();
+        const entered = (await deps.promptSecret("Bridge API key or invite (input hidden): ")).trim();
         if (entered.length > 0) {
             return { ok: true, value: entered };
         }
-        return { ok: false, error: "No API key entered." };
+        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.",
+        };
     }
     return {
         ok: false,
-        error: "An API key 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. Pass --api-key or set the BAPI_API_KEY " +
+            "environment variable (no interactive terminal is available to prompt for it).",
     };
 }
 /**
@@ -836,8 +881,8 @@ 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). */
-export const INSTALL_BRIDGE_KEY_SELECTOR_PROMPT = "Do you have a Bridge API key? [Y/n] ";
+/** 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] ";
 /**
  * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
  *
@@ -980,87 +1025,78 @@ export async function resolveRepoName(options, deps, mode = "existing-registrati
 /** A per-host MCP config target (mirrors runInit's configTargets shape). */
 /** Stable wording of the interactive tool-selection prompt (BAPI-635). */
 export const INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT = "Which AI coding tools do you use on this project?";
+/** A one-based selection token is exactly one or more digits, no sign/decimal/leading-zero. */
+const SELECTION_TOKEN_PATTERN = /^[1-9][0-9]*$/;
 /**
- * Interactive numbered multi-select prompt on stderr (TTY only). Displays a
- * legend and usage line plus each option with a checked/unchecked marker seeded
- * from `defaults`, accepts a comma-separated list of numbers that TOGGLE the rows
- * and RE-PROMPT (acceptance is a separate bare Enter), and accepts only a NON-EMPTY
- * selection on a bare Enter — an empty one prints "Select at least one tool." and
- * re-prompts (AC-1/AC-3). Reprints on an invalid token rather than corrupting
- * state. Resolves safely (to the current set, including an empty one) on EOF /
- * synchronous close so a readline regression can never hang or discard the answer.
+ * Interactive single-shot numbered picker on stderr (TTY only). Renders the
+ * heading and each option exactly once, then accepts ONE strict
+ * comma-separated line of one-based numbers and resolves immediately — there
+ * is no preselected/toggle state and no separate confirmation step (BAPI-663).
+ *
+ * A blank line or a line containing any invalid token (non-numeric, zero,
+ * signed, leading-zero, decimal, out-of-range) is rejected atomically — the
+ * whole line is discarded, one error line is printed, and the picker
+ * re-prompts without re-rendering the option list. A valid line is
+ * deduplicated and returned in `options` order regardless of entry order.
+ *
+ * Resolves to `[]` on EOF / synchronous close before any line has been
+ * committed, so a readline regression can never hang. Returns `[]`
+ * immediately, without creating a readline interface, when `options` is
+ * empty.
  */
-export function promptMultiSelectViaReadline(promptText, options, defaults, input = process.stdin, output = process.stderr) {
+export function promptMultiSelectViaReadline(promptText, options, input = process.stdin, output = process.stderr) {
+    if (options.length === 0)
+        return Promise.resolve([]);
     return new Promise((resolve) => {
-        const selected = new Set(defaults);
-        const render = () => {
-            output.write(`\n${promptText}\n`);
-            output.write("[x] = selected · [ ] = not selected\n");
-            options.forEach((opt, idx) => {
-                const mark = selected.has(opt.id) ? "[x]" : "[ ]";
-                output.write(`  ${idx + 1}. ${mark} ${opt.label}\n`);
-            });
-            output.write("Type numbers to toggle, e.g. 1,3 — then Enter. Enter with ≥1 selected accepts.\n");
-            output.write("Enter numbers to toggle (comma-separated), or press Enter to accept: ");
-        };
         const rl = readline.createInterface({ input, output });
-        let answered = false;
-        const finish = () => {
-            answered = true;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
             rl.close();
-            resolve(options.filter((o) => selected.has(o.id)).map((o) => o.id));
+            resolve(result);
         };
         // EOF / synchronous close must resolve rather than deadlock the top-level
-        // await; `answered` guards the synchronous close from discarding a real answer.
-        rl.on("close", () => {
-            if (!answered)
-                resolve(options.filter((o) => selected.has(o.id)).map((o) => o.id));
+        // await; the `settled` guard stops a synchronous `close` (fired by `rl.close()`
+        // above) from replacing an already-committed answer with the EOF fallback.
+        rl.on("close", () => finish([]));
+        output.write(`\n${promptText}\n`);
+        options.forEach((opt, idx) => {
+            output.write(`  ${idx + 1}. ${opt.label}\n`);
         });
-        const ask = () => {
-            render();
-            rl.question("", (answer) => {
+        output.write("Enter the number(s) of the tools you use (e.g. 1,3), then Enter.\n");
+        const prompt = () => {
+            rl.question("> ", (answer) => {
                 const trimmed = answer.trim();
                 if (trimmed.length === 0) {
-                    // AC-3: a bare Enter accepts ONLY a non-empty selection; an empty one
-                    // re-prompts rather than resolving to nothing. EOF/close (handled above)
-                    // still resolves the current — possibly empty — set so input can never hang.
-                    if (selected.size === 0) {
-                        output.write("Select at least one tool.\n");
-                        ask();
-                        return;
-                    }
-                    finish();
+                    output.write("Select at least one tool.\n");
+                    prompt();
                     return;
                 }
                 const tokens = trimmed.split(",").map((t) => t.trim());
-                const nums = [];
-                let bad = false;
+                const indices = [];
                 for (const tok of tokens) {
+                    if (!SELECTION_TOKEN_PATTERN.test(tok)) {
+                        output.write(`Invalid selection. Enter numbers between 1 and ${options.length}.\n`);
+                        prompt();
+                        return;
+                    }
                     const n = Number(tok);
-                    if (!Number.isInteger(n) || n < 1 || n > options.length) {
-                        bad = true;
-                        break;
+                    if (n < 1 || n > options.length) {
+                        output.write(`Invalid selection. Enter numbers between 1 and ${options.length}.\n`);
+                        prompt();
+                        return;
                     }
-                    nums.push(n);
-                }
-                if (bad) {
-                    output.write(`Invalid selection. Enter numbers between 1 and ${options.length}.\n`);
-                    ask();
-                    return;
-                }
-                for (const n of nums) {
-                    const opt = options[n - 1];
-                    if (selected.has(opt.id))
-                        selected.delete(opt.id);
-                    else
-                        selected.add(opt.id);
+                    indices.push(n);
                 }
-                // Toggling re-renders the updated checklist and re-prompts; acceptance is a
-                // separate, deliberate bare Enter (AC-1/AC-3) rather than an implicit accept.
-                ask();
+                const chosen = new Set(indices);
+                finish(options
+                    .filter((_, idx) => chosen.has(idx + 1))
+                    .map((o) => o.id));
             });
         };
-        ask();
+        prompt();
     });
 }
 /**
@@ -1080,13 +1116,11 @@ export async function resolveSelectedHostPlatforms(deps, options) {
     }
     const ctx = await buildDetectionContext(deps);
     const detected = new Set(detectDefaultPlatforms(ctx));
-    // 2. Interactive multi-select on a TTY. AC-2: no row is pre-selected — the
-    // picker seeds an EMPTY default set (dropping the former forced Claude Code
-    // inclusion and detected-platform seeding) and requires an explicit selection.
+    // 2. Interactive single-shot numbered picker on a TTY. No row is pre-selected
+    // — the picker has no default state and requires an explicit selection.
     if (deps.isTTY && deps.promptMultiSelect) {
         const optionList = allHostTargets().map((t) => ({ id: t.id, label: t.label }));
-        const defaults = [];
-        const chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList, defaults);
+        const chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList);
         return HOST_PLATFORM_ORDER.filter((id) => chosen.includes(id));
     }
     // 3. Legacy non-TTY automatic set: Claude + detected Cursor / Copilot VS Code.
@@ -1195,20 +1229,41 @@ export async function chooseInstallBridgeLaunchAgent(agents, deps) {
  *    completes.
  *
  * Condition-specific warning prefixes are added by the caller, never inside here.
+ *
+ * `toolLabels` (BAPI-661) names the actually-selected platform(s) in the
+ * `"configured"` message so "open it in an AI coding tool" becomes "open it in
+ * GitHub Copilot (VS Code)" when that is what was selected — an empty array (the
+ * explicit empty-selection call site, or any caller with nothing to name) falls
+ * back to the prior generic "an AI coding tool" wording unchanged.
  */
-export function buildManualInstallBridgeContinuation(kind) {
+export function buildManualInstallBridgeContinuation(kind, toolLabels) {
     if (kind === "empty-selection") {
         return [
             "No AI coding tools were configured, so nothing was set up for this project.",
             "Re-run install-bridge and select at least one tool to configure it.",
         ].join("\n");
     }
+    const toolPhrase = formatToolLabelPhrase(toolLabels);
     return [
-        "To finish configuring this project, open it in an AI coding tool that has the",
+        `To finish configuring this project, open it in ${toolPhrase} that has the`,
         "Bridge MCP server configured and run /install-bridge.",
         "Until the project is configured, your Bridge MCP tools stay limited.",
     ].join("\n");
 }
+/**
+ * Format 0, 1, or many tool labels into a readable phrase for the continuation
+ * message. Empty falls back to the generic "an AI coding tool"; one label is used
+ * bare; two or more join with a serial (Oxford) comma and "and".
+ */
+function formatToolLabelPhrase(labels) {
+    if (labels.length === 0)
+        return "an AI coding tool";
+    if (labels.length === 1)
+        return labels[0];
+    if (labels.length === 2)
+        return `${labels[0]} and ${labels[1]}`;
+    return `${labels.slice(0, -1).join(", ")}, and ${labels[labels.length - 1]}`;
+}
 /** The exact consent-prompt prefix, shared with tests so the copy cannot drift. */
 export const INSTALL_BRIDGE_LAUNCH_CONSENT_PROMPT_PREFIX = "Bridge can configure and set up this project for you automatically. Open a ";
 /**
@@ -1287,6 +1342,17 @@ function hostConfigTargetsForPlatforms(platforms) {
         .filter((t) => t.scope === "project" && t.format === "json")
         .map((t) => ({ relPath: t.relPath, topLevelKey: t.topLevelKey }));
 }
+/**
+ * Derive the human-facing labels for a set of selected platforms, in registry
+ * (`HOST_PLATFORM_ORDER`) order rather than the caller's input order, so a
+ * continuation message names selected tools deterministically (BAPI-661).
+ * Deduplicates by platform ID and reads every label from `MCP_HOST_TARGETS` —
+ * never a second, hand-maintained label map.
+ */
+export function labelsForPlatforms(platforms) {
+    const set = new Set(platforms);
+    return HOST_PLATFORM_ORDER.filter((id) => set.has(id)).map((id) => MCP_HOST_TARGETS[id].label);
+}
 /** Resolve which project-local host configs to write, mirroring runInit detection. */
 async function resolveHostConfigTargets(deps) {
     const targets = [
@@ -1447,9 +1513,19 @@ export function buildPingUrl(baseUrl, repoName) {
     return url.toString();
 }
 /**
- * Verify connectivity. Distinguishes a rejected key (401/403) 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.
+ * Fixed, secret-free fallback for an HTTP 403 whose body carries no usable
+ * `detail` (absent, malformed, unreadable, or a non-string `detail`). Deliberately
+ * does NOT claim the key is invalid or expired — a 403 means the credential was
+ * understood but denied access, which is a different (and often more actionable)
+ * failure than an invalid/expired key.
+ */
+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.";
+/**
+ * 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.
  */
 export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     const url = buildPingUrl(baseUrl, repoName);
@@ -1474,7 +1550,7 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
     }
     if (resp.ok)
         return { ok: true };
-    if (resp.status === 401 || resp.status === 403) {
+    if (resp.status === 401) {
         return {
             ok: false,
             message: `The Bridge API rejected the credential (HTTP ${resp.status}). The API key may be invalid or expired ` +
@@ -1482,6 +1558,27 @@ export async function verifyConnectivity(deps, baseUrl, repoName, apiKey) {
                 "permission error.)",
         };
     }
+    if (resp.status === 403) {
+        // BAPI-661: a 403 means the credential was understood but access to THIS repo
+        // was denied — the server's `detail` (e.g. "repository '<name>' is not
+        // registered; verify the repo_name") is a safe, specific, non-secret message
+        // that is far more actionable than the blanket invalid-key diagnosis 401 uses.
+        // Only a nonblank string `detail` is ever surfaced; any other shape (missing
+        // body, invalid JSON, a non-string/blank detail, or a body-read exception)
+        // collapses to the fixed fallback so nothing unvalidated ever reaches the user.
+        let detail;
+        try {
+            const body = (await resp.json());
+            detail = body?.detail;
+        }
+        catch {
+            return { ok: false, message: CONNECTIVITY_ACCESS_DENIED_FALLBACK };
+        }
+        if (typeof detail === "string" && detail.trim().length > 0) {
+            return { ok: false, message: detail.trim() };
+        }
+        return { ok: false, message: CONNECTIVITY_ACCESS_DENIED_FALLBACK };
+    }
     if (resp.status === 404) {
         return {
             ok: false,
@@ -1651,6 +1748,21 @@ export async function exchangeBootstrapInvite(deps, baseUrl, token, repoName, ke
  * treated as a `failed` mint rather than fed into the redemption path.
  */
 export const BOOTSTRAP_INVITE_TOKEN_PREFIX = "bapi_inv_";
+/**
+ * Classify a value entered through the ORDINARY credential input (`--api-key`,
+ * `BAPI_API_KEY`, or the have-key hidden prompt) as a bootstrap-invite token or a
+ * full API key (BAPI-661). This lets a user who was handed an invite but reaches
+ * for the ordinary key input still get redeemed correctly, instead of the invite
+ * being sent as an (invalid) API key to repository resolution / connectivity.
+ *
+ * Pure and total: trims first, then does a case-sensitive prefix check against
+ * {@link BOOTSTRAP_INVITE_TOKEN_PREFIX}. Blank and every non-matching value is
+ * `"api-key"` — the existing resolvers already reject a blank value, so this
+ * function does not need to special-case it. Never logs or returns the value.
+ */
+export function classifyEnteredCredential(value) {
+    return value.trim().startsWith(BOOTSTRAP_INVITE_TOKEN_PREFIX) ? "invite" : "api-key";
+}
 /** The self-serve mint endpoint: `<base>/setup/bootstrap/self-serve`. No query string — ever. */
 export function buildSelfServeMintUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup/bootstrap/self-serve`;
@@ -1996,8 +2108,14 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const branch = branchResult.branch;
-    const bootstrapInviteMode = branch.kind === "need-key";
-    const selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
+    // Mutable (BAPI-661): an ordinary have-key credential that classifies as a
+    // bootstrap invite (see the have-key arm below) flips `bootstrapInviteMode` to
+    // true AFTER branch selection, before repository-name resolution — everything
+    // downstream that branches on these two flags then follows the existing
+    // bootstrap-invite protocol automatically. Explicit `--invite`/`BAPI_INVITE` and
+    // `--email`/`BAPI_SIGNUP_EMAIL` never pass through this reclassification.
+    let bootstrapInviteMode = branch.kind === "need-key";
+    let selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
     // ---- Resolve inputs (may prompt when interactive) ----
     // Resolve the credential/entry input first so a fully-empty non-interactive
     // invocation fails with the (more relevant) missing-input message before the repo
@@ -2030,7 +2148,20 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             errorLog(`Error: ${keyResult.error}`);
             return 1;
         }
-        apiKey = keyResult.value;
+        // BAPI-661: an invite pasted into the ordinary credential input (flag, env, or
+        // hidden prompt) is redeemed like an explicit --invite, not sent as an API key
+        // to repository resolution / connectivity. Reclassifying BEFORE that
+        // resolution is what lets the rest of the function reuse the existing
+        // bootstrap-invite protocol verbatim.
+        if (classifyEnteredCredential(keyResult.value) === "invite") {
+            inviteToken = keyResult.value.trim();
+            apiKey = "";
+            bootstrapInviteMode = true;
+            selfServeSignupMode = false;
+        }
+        else {
+            apiKey = keyResult.value;
+        }
     }
     // baseUrl is resolved BEFORE repository input because the have-key branch needs
     // it for the server-resolution request.
@@ -2077,7 +2208,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             else {
                 // Feature-detect + degrade: 404 (old server), 409 (unresolved/ambiguous/
                 // client-scoped), and network/other errors all fall back to the existing
-                // local resolution WITHOUT a cause-specific message or leaked detail.
+                // local resolution — WITHOUT a cause-specific message or leaked detail, but
+                // (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.");
                 const repoResult = await resolveRepoName(options, deps, "existing-registration");
                 if (!repoResult.ok) {
                     errorLog(`Error: ${repoResult.error}`);
@@ -2159,7 +2294,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // Return BEFORE any config/credential write, materialization, prewarm, or spawn, so a
     // bare `--tools=` (or an EOF-resolved picker) cleanly does nothing but guide a re-run.
     if (planLaunch.kind === "manual" && planLaunch.reason === "empty-selection") {
-        log(buildManualInstallBridgeContinuation("empty-selection"));
+        // Explicit empty selection: no labels to name, so the generic fallback is
+        // intentional here — pass [] rather than `labelsForPlatforms(selectedPlatforms)`.
+        log(buildManualInstallBridgeContinuation("empty-selection", []));
         return 0;
     }
     // ---- Finalize the launch agent for spawn-capable decisions ----
@@ -2609,7 +2746,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // 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"));
+                log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
                 return 0;
             }
             log("");
@@ -2623,13 +2760,13 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             return 0;
         }
         // Declined (or non-TTY suppression): the deterministic setup is complete and durable.
-        log(buildManualInstallBridgeContinuation("configured"));
+        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"));
+    log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
     return 0;
 }