@bridge_gpt/mcp-server 0.2.26 → 0.2.28

package/build/install-bridge.js

@@ -30,11 +30,14 @@
  *
  * then SPAWNS a fresh agent session (Step 5) for the CONFIGURE-ONLY agentic
  * remainder: `/install-bridge` config-field derivation → the read-after-write
- * capability report → a single optional indexing-consent question. It does NOT
- * chain `/learn-repository` and does NOT index without explicit consent. The
- * fresh session is required because a CLI cannot force the running editor to
- * reload the just-written `.mcp.json`, and field derivation needs an agent
- * runtime the shell does not have.
+ * concise capability report → a `/learn-repository` recommendation (BAPI-658).
+ * It does NOT chain into running `/learn-repository` itself — that stays the
+ * human's next explicit invocation — and it never asks about, decides, or
+ * claims anything about repository indexing: indexing is entirely automatic,
+ * gated server-side by the existing readiness funnel, with no prompt on any
+ * path. The fresh session is required because a CLI cannot force the running
+ * editor to reload the just-written `.mcp.json`, and field derivation needs an
+ * agent runtime the shell does not have.
  *
  * That spawn command embeds the entire agent prompt and runs to multiple KB, which
  * no macOS terminal will accept as one typed line. So it is never typed: the full
@@ -88,7 +91,7 @@ import readline from "readline";
 import { runInit, buildBridgeApiEntry } from "./init.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.js";
-import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, isHostPlatformId, detectDefaultPlatforms, } from "./mcp-host-targets.js";
+import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, } from "./mcp-host-targets.js";
 import { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host-config.js";
 import { writeMcpInstallState } from "./mcp-install-state.js";
 import { ensureGitignored as ensureGitignoredShared, } from "./git-ignore-utils.js";
@@ -98,7 +101,7 @@ import { upsertBapiCredential, getPrimaryCredentialStorePath, prepareBootstrapPe
 // API primitives verbatim — no duplicated polling, browser, or picker logic here.
 import { fetchGithubConfigurationState } from "./connect-github-api.js";
 import { createDefaultConnectGithubDeps, runGithubConnectionFlow } from "./connect-github.js";
-import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
+import { resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, materializeWorkerLaunchCommand, MAX_TERMINAL_COMMAND_BYTES, } from "./start-tickets.js";
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
@@ -113,7 +116,11 @@ export const MCP_TIMEOUT_GUIDANCE = "Note: if your MCP client has a very short c
     "(the initial npx package resolution/download can exceed a short connect timeout).";
 /** The exact, version-pinned launcher spec the pre-warm spawns (fast-exiting --version). */
 export function buildPrewarmArgs() {
-    return ["-y", `@bridge_gpt/mcp-server@${VERSION}`, "--version"];
+    // `--prefer-offline`: the initial `@latest` bootstrap already populated the npm
+    // cache with the exact tarball this `@${VERSION}`-pinned warm needs, so resolve
+    // from cache and skip the redundant registry-metadata round-trip (falls back to
+    // the network on a genuine miss).
+    return ["-y", "--prefer-offline", `@bridge_gpt/mcp-server@${VERSION}`, "--version"];
 }
 /** Secret-free preview of the pre-warm command (no env, no key). */
 export function buildPrewarmCommandPreview() {
@@ -121,44 +128,37 @@ export function buildPrewarmCommandPreview() {
 }
 /**
  * The natural-language prompt handed to the spawned agent session. It is
- * CONFIGURE-ONLY: it derives and applies configuration, presents the capability
- * report, and ends with exactly one indexing-consent question. It never chains
- * /learn-repository and never indexes before explicit consent.
- *
- * The index-consent beat is AGENT-OWNED (asked inside this spawned session), not
- * parent-CLI-owned, because `spawnTerminalTab()` opens an asynchronous terminal
- * session: the parent CLI returns immediately and cannot reliably ask a question
- * that must appear AFTER the spawned session's capability report. Asking it via
- * the parent's `deps.promptLine` would display the question before the report
- * even exists. `deps.promptLine` therefore stays the owner of the parent-CLI
- * prompts (repository / overwrite / invite confirmation) and is intentionally
- * NOT used for this post-report question.
+ * CONFIGURE-ONLY: it derives and applies configuration, presents the concise
+ * capability report, and closes with a `/learn-repository` recommendation
+ * (BAPI-658). It never chains straight into running /learn-repository itself —
+ * that remains the human's next explicit invocation — and it never asks about,
+ * decides, or claims anything about repository indexing: indexing is entirely
+ * automatic, gated by the existing readiness funnel
+ * (`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 and Stage 9 offers — this session's only " +
-    "closing interaction is the single indexing question below). Do NOT run /learn-repository. Do NOT " +
-    "call parse_repository (or otherwise start indexing) before the capability report and explicit " +
-    "consent below. " +
-    "Complete the command's read-after-write five-section capability report first: 'Connected ✓', " +
-    "'Not yet connected ✗', 'Tools you can use now', 'Tools you'll unlock', and 'Recommended next " +
-    "step + why'. " +
-    "Only AFTER that report is fully presented, ask exactly one question using this visible prompt: " +
-    "'[Y/n] Index repository now?'. Only an explicit affirmative answer (e.g. 'y'/'yes') starts " +
-    "indexing; a blank answer, a negative answer, EOF, an unavailable interaction, and any " +
-    "non-interactive/headless run all resolve to NO. " +
-    "On an affirmative answer: call the parse_repository MCP tool exactly once, describe the accepted " +
-    "job as QUEUED, and direct later progress checks to get_parse_status or /check-parse-status " +
-    "(do NOT poll it to completion). If parse_repository returns a blocking refusal or error, do NOT " +
-    "claim the job was queued — report the sanitized result and leave indexing pending. " +
-    "On NO (or any unavailable/non-interactive resolution): do not index; print the exact copy-paste " +
-    "continuation command '/parse-repository' on its own line and state that indexing remains pending. " +
+    "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 " +
+    "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. " +
+    "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 " +
+    "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. " +
     "Never request, echo, or transport any credential — only ever direct the human to that " +
     "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 " +
-    "applied (e.g. 'Applied 8 of 9 derived fields') and whether indexing was queued or left pending — " +
-    "if 0 fields were applied, say so loudly and explain what is still pending.";
+    "applied (e.g. 'Applied 8 of 9 derived fields') — if 0 fields were applied, say so loudly and " +
+    "explain what is still pending.";
 /** 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). */
@@ -171,8 +171,11 @@ 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 opens a fresh agent session to derive the remaining",
-        "config, present a capability report, and offer optional repository indexing.",
+        "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.",
         "",
         "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`,
@@ -241,24 +244,35 @@ 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 you are",
-        "                                asked which tools you use (Claude Code plus any",
-        "                                detected editors are pre-checked). A non-",
-        "                                interactive run without --tools writes the legacy",
-        "                                automatic set (Claude Code plus any detected",
-        "                                Cursor / Copilot VS Code). --tools= (empty) is an",
-        "                                explicit empty selection and writes nothing.",
+        "                                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",
+        "                                --tools writes the legacy automatic set (Claude",
+        "                                Code plus any detected Cursor / Copilot VS Code)",
+        "                                and never opens an agent terminal (it prints",
+        "                                manual continuation instead). --tools= (empty) is",
+        "                                an explicit empty selection: it writes nothing and",
+        "                                launches nothing.",
         "  --force                       Overwrite an existing real BAPI_API_KEY in a",
         "                                host config (or in the credential store) without",
         "                                prompting.",
         "  --dry-run                     Preview every step (scaffold targets, config",
         "                                files + keys with the key REDACTED, ping",
-        "                                target, credential target, spawn command)",
-        "                                without writing, pinging, or spawning anything.",
-        "                                With --invite it also never calls the exchange",
-        "                                endpoint and never generates or stores a secret.",
-        "  --agent claude|cursor-agent   Agent to launch for the agentic remainder",
-        "                                (default: claude).",
+        "                                target, credential target, and the consent-gated",
+        "                                launch outcome) without writing, pinging,",
+        "                                prompting, or spawning anything. With --invite it",
+        "                                also never calls the exchange endpoint and never",
+        "                                generates or stores a secret.",
+        "  --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.",
         "  -h, --help                    Show this help.",
         "",
         "Environment: BAPI_BASE_URL (default https://bridgegpt-api.com) and BAPI_DOCS_DIR",
@@ -284,7 +298,10 @@ export function parseInstallBridgeArgs(argv) {
     let repo;
     let force = false;
     let dryRun = false;
-    let agentName = DEFAULT_AGENT_NAME;
+    // Undefined until `--agent` is explicitly supplied — install-bridge never falls
+    // back to DEFAULT_AGENT_NAME (BAPI-657). An omitted agent is derived from the tool
+    // selection downstream; only an explicit `--agent` value lands here.
+    let agentName;
     let invite;
     let email;
     let tools;
@@ -964,22 +981,26 @@ export async function resolveRepoName(options, deps, mode = "existing-registrati
 /** 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?";
 /**
- * Interactive numbered multi-select prompt on stderr (TTY only). Displays each
- * option with a checked/unchecked marker seeded from `defaults`, accepts a
- * comma-separated list of numbers to TOGGLE, and accepts the current selection on
- * a bare Enter. Reprints on an invalid token rather than corrupting state.
- * Resolves safely (to the seeded defaults) on EOF / synchronous close so a
- * readline regression can never hang or discard the answer.
+ * 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.
  */
 export function promptMultiSelectViaReadline(promptText, options, defaults, input = process.stdin, output = process.stderr) {
     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 });
@@ -1000,6 +1021,14 @@ export function promptMultiSelectViaReadline(promptText, options, defaults, inpu
             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();
                     return;
                 }
@@ -1026,7 +1055,9 @@ export function promptMultiSelectViaReadline(promptText, options, defaults, inpu
                     else
                         selected.add(opt.id);
                 }
-                finish();
+                // 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();
             });
         };
         ask();
@@ -1036,8 +1067,8 @@ export function promptMultiSelectViaReadline(promptText, options, defaults, inpu
  * Resolve the selected host platforms with strict precedence (BAPI-635):
  *   1. explicit `--tools` (including an explicit EMPTY selection — never falls
  *      back to detection),
- *   2. interactive multi-select on a TTY (seeded from registry detection, with
- *      Claude Code always checked as a default),
+ *   2. interactive multi-select on a TTY (AC-2: no row pre-selected — the picker
+ *      starts empty and requires an explicit ≥1 selection),
  *   3. the legacy non-TTY automatic set: Claude Code plus only the currently
  *      detected Copilot VS Code and Cursor automatic targets (never Codex or
  *      Copilot CLI just because a global directory exists).
@@ -1049,11 +1080,12 @@ export async function resolveSelectedHostPlatforms(deps, options) {
     }
     const ctx = await buildDetectionContext(deps);
     const detected = new Set(detectDefaultPlatforms(ctx));
-    // 2. Interactive multi-select on a TTY.
+    // 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.
     if (deps.isTTY && deps.promptMultiSelect) {
         const optionList = allHostTargets().map((t) => ({ id: t.id, label: t.label }));
-        // Claude Code is always a checked default; add every detected platform.
-        const defaults = HOST_PLATFORM_ORDER.filter((id) => id === "claude-code" || detected.has(id));
+        const defaults = [];
         const chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList, defaults);
         return HOST_PLATFORM_ORDER.filter((id) => chosen.includes(id));
     }
@@ -1065,6 +1097,146 @@ export async function resolveSelectedHostPlatforms(deps, options) {
         legacy.push("copilot-vscode");
     return HOST_PLATFORM_ORDER.filter((id) => legacy.includes(id));
 }
+/**
+ * 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.
+ *  - 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.
+ *
+ * Never prompts, logs, resolves an {@link AgentSpec}, or touches the filesystem.
+ */
+export function resolveInstallBridgeLaunchDecision(selectedPlatforms, explicitAgent) {
+    if (explicitAgent) {
+        return { kind: "spawn", agent: explicitAgent };
+    }
+    if (selectedPlatforms.length === 0) {
+        return { kind: "manual", reason: "empty-selection" };
+    }
+    const agents = [];
+    for (const id of HOST_PLATFORM_ORDER) {
+        if (!selectedPlatforms.includes(id))
+            continue;
+        const agent = agentForPlatform(id);
+        if (agent && !agents.includes(agent))
+            agents.push(agent);
+    }
+    if (agents.length === 0)
+        return { kind: "manual", reason: "no-launchable-agent" };
+    if (agents.length === 1)
+        return { kind: "spawn", agent: agents[0] };
+    return { kind: "choose-one", agents };
+}
+/**
+ * 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).
+ */
+export function toolLabelForLaunchAgent(agent) {
+    const target = allHostTargets().find((t) => t.launchAgent === agent);
+    return target?.label ?? agent;
+}
+/**
+ * Interactive numbered chooser for when MORE THAN ONE launchable tool was selected
+ * (AC-11). Mirrors the connect-github picker: prints each candidate by its host-tool
+ * label, asks for an exact numeric choice with NO default, validates the range, and
+ * returns the chosen agent. Returns `null` — never a silent first-candidate default —
+ * for every unavailable/invalid path: non-TTY, a missing `promptLine` seam, blank/EOF
+ * input, an out-of-range or malformed answer, or a prompt that throws. Single-purpose:
+ * it must run only AFTER the multi-select promise has resolved and closed its readline
+ * interface so two readers never contend for stdin.
+ */
+export async function chooseInstallBridgeLaunchAgent(agents, deps) {
+    if (!deps.isTTY || !deps.promptLine)
+        return null;
+    const promptLine = deps.promptLine;
+    try {
+        deps.log("");
+        deps.log("More than one selected tool can host the configuration session:");
+        agents.forEach((agent, i) => {
+            deps.log(`  ${String(i + 1).padStart(2, " ")}. ${toolLabelForLaunchAgent(agent)}`);
+        });
+        // No default: a stray Enter must not silently pick a tool.
+        const answer = (await promptLine(`Which tool should open? [1-${agents.length}]: `)).trim();
+        const index = Number(answer);
+        if (!/^\d+$/.test(answer) ||
+            !Number.isInteger(index) ||
+            index < 1 ||
+            index > agents.length) {
+            return null;
+        }
+        return agents[index - 1];
+    }
+    catch {
+        // Never surface caught exception text; an unavailable chooser is a no-spawn.
+        return null;
+    }
+}
+/**
+ * Shared, copy-pasteable "we didn't open a session for you" guidance so every
+ * no-spawn path (no-launchable selection, non-TTY suppression, chooser failure,
+ * consent decline, terminal-spawn failure) emits ONE consistent remediation
+ * (AC-5 / AC-7). Two variants:
+ *
+ *  - `"empty-selection"` — no MCP host config was written at all, so it does NOT tell
+ *    the user to run `/install-bridge` (there is no configured host to run it in); it
+ *    tells them to re-run `install-bridge` and select at least one tool.
+ *  - `"configured"` — at least one host WAS configured, so it tells the user to open
+ *    the project in an applicable AI coding tool and run `/install-bridge`, plus the
+ *    required notice that their Bridge MCP tools stay limited until configuration
+ *    completes.
+ *
+ * Condition-specific warning prefixes are added by the caller, never inside here.
+ */
+export function buildManualInstallBridgeContinuation(kind) {
+    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");
+    }
+    return [
+        "To finish configuring this project, open it in an AI coding tool that has the",
+        "Bridge MCP server configured and run /install-bridge.",
+        "Until the project is configured, your Bridge MCP tools stay limited.",
+    ].join("\n");
+}
+/** 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 ";
+/**
+ * Ask for explicit TTY consent immediately before opening the selected tool (AC-7).
+ * Returns `"spawn"` only when a live terminal user affirmatively agrees; returns
+ * `"no-spawn"` WITHOUT prompting on a non-TTY run or a missing `promptLine` seam, and
+ * on an `n`/`no` answer. Mirrors {@link offerGithubConnection}'s Y/N semantics: a
+ * blank line, `y`, or `yes` accept; `n` or `no` decline. A prompt that throws safely
+ * declines without surfacing the caught exception text. Uses only the per-call
+ * `promptLine` seam, so it must run AFTER the tool-selection, chooser, and GitHub
+ * flows have closed their readline interfaces — never while another prompt is active.
+ */
+export async function requestInstallBridgeLaunchConsent(toolLabel, deps) {
+    if (!deps.isTTY || !deps.promptLine)
+        return "no-spawn";
+    try {
+        const answer = (await deps.promptLine(`${INSTALL_BRIDGE_LAUNCH_CONSENT_PROMPT_PREFIX}${toolLabel} session to do that now? (Y/n) `))
+            .trim()
+            .toLowerCase();
+        if (answer === "n" || answer === "no")
+            return "no-spawn";
+        return "spawn";
+    }
+    catch {
+        // Never surface caught exception text; treat a prompt failure as a decline.
+        return "no-spawn";
+    }
+}
 /**
  * Build a registry detection context from install deps. install-bridge has only
  * async `stat`, but the registry's `detect` callbacks are synchronous, so we
@@ -1593,7 +1765,7 @@ export function buildDryRunPreview(plan) {
         `Repo name:        ${plan.repoName}${plan.attemptedServerResolution ? " (resolved server-side from your API key)" : ""}`,
         `Base URL (ping):  ${plan.baseUrl}`,
         `Docs dir:         ${plan.docsDir}`,
-        `Agent:            ${plan.agentName}`,
+        `Agent:            ${describePlannedLaunchAgent(plan.launch)}`,
         "",
         "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})`,
@@ -1608,26 +1780,66 @@ export function buildDryRunPreview(plan) {
         ...buildLaunchStepPreview(plan),
     ];
 }
+/**
+ * One-line description of the planned launch agent for the dry-run header (BAPI-657).
+ * Never claims an unconditional Claude spawn: it reflects the discriminated launch
+ * outcome — a single consent-gated tool, a choose-one among launchable tools, or a
+ * no-automatic-launch manual outcome.
+ */
+function describePlannedLaunchAgent(launch) {
+    if (launch.kind === "spawn") {
+        return `${toolLabelForLaunchAgent(launch.agent)} (${launch.agent}) — opens only after Y/N consent`;
+    }
+    if (launch.kind === "choose-one") {
+        const labels = launch.agents.map((a) => toolLabelForLaunchAgent(a)).join(", ");
+        return `choose one of ${labels} — the chosen tool opens only after Y/N consent`;
+    }
+    return launch.reason === "empty-selection"
+        ? "none — no tools selected"
+        : "none — no launchable tool selected; manual continuation is printed";
+}
 /**
  * The Step 5 preview lines, shared by both previews so the launch description
- * cannot drift between the have-key and need-key flows.
+ * cannot drift between the have-key and need-key flows (BAPI-657). The Step 5 body
+ * is dispatched on the discriminated launch outcome: a consent-gated single-tool
+ * spawn (with the full secret-free command shown), a consent-gated choose-one, or a
+ * no-automatic-launch manual continuation — never an unconditional Claude spawn.
  *
- * A --dry-run never writes the launch script, so the preview describes the
- * materialization rather than performing it — but it still shows the full command,
- * because the command is what the user is previewing and it is secret-free.
+ * A --dry-run never writes the launch script, prompts for consent, or spawns, so
+ * these lines describe the outcome rather than performing it.
  */
 function buildLaunchStepPreview(plan) {
-    return [
+    const githubLines = [
         // 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.
         "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.",
-        "Step 5 — spawn agent session: the full command below is stored in a restricted launch script",
-        "          (mode 0600, under the system temp dir) and only a short sourced runner is spawned",
-        "          (the script itself is NOT written in --dry-run):",
-        `          ${plan.spawnCommand}`,
+    ];
+    if (plan.launch.kind === "spawn") {
+        return [
+            ...githubLines,
+            `Step 5 — agent session (${toolLabelForLaunchAgent(plan.launch.agent)}): on a TTY the wizard first asks`,
+            "          'Open a … session to do that now? (Y/n)'; only on consent is the full command below",
+            "          stored in a restricted launch script (mode 0600, under the system temp dir) and a short",
+            "          sourced runner spawned (the script itself is NOT written in --dry-run):",
+            `          ${plan.launch.spawnCommand}`,
+        ];
+    }
+    if (plan.launch.kind === "choose-one") {
+        const labels = plan.launch.agents.map((a) => toolLabelForLaunchAgent(a)).join(", ");
+        return [
+            ...githubLines,
+            `Step 5 — agent session: more than one selected tool can host it (${labels}); on a TTY the wizard`,
+            "          asks which single tool to open, then asks Y/N consent before spawning that one session.",
+        ];
+    }
+    return [
+        ...githubLines,
+        plan.launch.reason === "empty-selection"
+            ? "Step 5 — no agent session: no tools were selected, so nothing is configured or opened; re-run and select at least one tool."
+            : "Step 5 — no automatic launch: no selected tool has an agentic CLI. The deterministic setup completes and copy-pasteable /install-bridge continuation is printed (your Bridge MCP tools stay limited until configured).",
     ];
 }
 /**
@@ -1664,7 +1876,7 @@ function buildBootstrapDryRunPreview(plan) {
         repoLine,
         `Base URL:         ${plan.baseUrl}`,
         `Docs dir:         ${plan.docsDir}`,
-        `Agent:            ${plan.agentName}`,
+        `Agent:            ${describePlannedLaunchAgent(plan.launch)}`,
         "",
         "Step 1 — scaffold (runInit): commands, agents, pipelines, .bridge/config, secret-free MCP placeholders.",
         ...selfServeStep,
@@ -1875,33 +2087,58 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             }
         }
     }
-    const agent = resolveAgentSpec(options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
-    const spawnCommand = deps.buildShellCommand(agent, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform);
     const credentialStorePath = getPrimaryCredentialStorePath({
         env: deps.env,
         homedir: deps.homedir,
     });
-    // BAPI-635: resolve the AI-coding-tool selection (explicit --tools, then TTY
-    // multi-select, then the legacy non-TTY automatic set). The selected project
-    // JSON targets drive the existing read-merge-write path; selected global
-    // (Codex / Copilot CLI) and manual (Windsurf) targets are provisioned by the
+    // BAPI-635: resolve the AI-coding-tool selection FIRST — BAPI-657 makes this
+    // selection (not a hidden --agent default) drive which post-install session opens.
+    // Explicit --tools, then the TTY multi-select, then the legacy non-TTY automatic
+    // set. The selected project JSON targets drive the read-merge-write path; selected
+    // global (Codex / Copilot CLI) and manual (Windsurf) targets are provisioned by the
     // registry-driven emitter after the connectivity check.
     const selectedPlatforms = await resolveSelectedHostPlatforms(deps, options);
     const targets = hostConfigTargetsForPlatforms(selectedPlatforms);
     // Read-only detection (safe in dry-run) of global-config editors we can't write.
     const manualEditors = await detectManualEditors(deps);
+    // BAPI-657: the pure, selection-driven launch decision. An explicit --agent is an
+    // absolute override (ratified AC-4); otherwise the selected tools map to an agent
+    // (Claude Code → claude, Cursor → cursor-agent), yielding spawn / choose-one /
+    // manual. Performs no prompting, resolveAgentSpec, or I/O.
+    const launchDecision = resolveInstallBridgeLaunchDecision(selectedPlatforms, options.agentName);
+    // Derive the plan's launch data. For a single-agent spawn we resolve the spec and
+    // build the (secret-free) command now so the dry-run preview can show it; a registry
+    // miss here is a hard error — install-bridge NEVER falls back to DEFAULT_AGENT_NAME.
+    let planLaunch;
+    if (launchDecision.kind === "spawn") {
+        const spec = resolveAgentSpec(launchDecision.agent);
+        if (!spec) {
+            errorLog(`Error: no launch agent is registered for '${launchDecision.agent}'.`);
+            return 1;
+        }
+        planLaunch = {
+            kind: "spawn",
+            agent: launchDecision.agent,
+            spawnCommand: deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform),
+        };
+    }
+    else if (launchDecision.kind === "choose-one") {
+        planLaunch = { kind: "choose-one", agents: launchDecision.agents };
+    }
+    else {
+        planLaunch = { kind: "manual", reason: launchDecision.reason };
+    }
     const plan = {
         repoName,
         baseUrl,
         docsDir,
-        agentName: options.agentName,
+        launch: planLaunch,
         configTargets: targets.map((t) => t.relPath),
         manualEditors: manualEditorNames(manualEditors),
         credentialTarget: `bapi:${repoName}`,
         credentialStorePath,
         pingUrl: buildPingUrl(baseUrl, repoName),
         prewarmCommand: buildPrewarmCommandPreview(),
-        spawnCommand,
         ...(bootstrapInviteMode
             ? { bootstrapInvite: true, exchangeUrl: buildBootstrapExchangeUrl(baseUrl) }
             : {}),
@@ -1917,30 +2154,71 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             log(line);
         return 0;
     }
-    // ---- Materialize the Step 5 launch command BEFORE any install side effect ----
-    // `spawnCommand` embeds the whole INSTALL_BRIDGE_AGENT_PROMPT and is multiple KB
-    // — far past what osascript can type into a Terminal/iTerm tab, which is why the
-    // spawn silently delivered a truncated line. It must travel via a launch script.
-    //
-    // This runs HERE, before the scaffold/mint/credential/config writes, because a
-    // command that cannot be launched safely is a whole-run failure, not a Step 5
-    // warning: the deterministic setup would otherwise complete and leave the user
-    // in the "configured but never configured by the agent" state the warning below
-    // explicitly calls out. Failing first means nothing is half-done.
-    const materialized = await materializeWorkerLaunchCommand(deps.startTicketsDeps, "install", spawnCommand);
-    if (!materialized.ok) {
-        errorLog(`Error: ${materialized.error}`);
-        return 1;
+    // ---- Resolved-empty selection: a handled no-op (exit 0), never a Claude fallback ----
+    // AC-3: with zero configured tools there is nothing to write and no session to open.
+    // 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"));
+        return 0;
     }
-    const launchCommand = materialized.command;
-    // Independent final guard on the line ACTUALLY handed to the terminal — not on
-    // the original command. It catches the two ways a "successful" materialization
-    // can still be unlaunchable: no writer seam (inline command preserved verbatim),
-    // and a runner whose script path is unexpectedly long.
-    if (Buffer.byteLength(launchCommand, "utf8") >= MAX_TERMINAL_COMMAND_BYTES) {
-        errorLog("Error: the agent session command is too long to send to the terminal safely. " +
-            "Check that the system temporary directory is writable so the launch script can be used.");
-        return 1;
+    // ---- Finalize the launch agent for spawn-capable decisions ----
+    // choose-one: pick exactly one via the numbered chooser (TTY only); a non-TTY run or
+    // a failed/aborted chooser degrades to the manual continuation (finalAgentName stays
+    // null). This runs AFTER the multi-select readline closed and BEFORE the GitHub /
+    // consent flows, so no two stdin readers ever overlap.
+    let finalAgentName = null;
+    let finalSpawnCommand = null;
+    if (planLaunch.kind === "spawn") {
+        finalAgentName = planLaunch.agent;
+        finalSpawnCommand = planLaunch.spawnCommand;
+    }
+    else if (planLaunch.kind === "choose-one") {
+        const chosen = await chooseInstallBridgeLaunchAgent(planLaunch.agents, deps);
+        if (chosen) {
+            const spec = resolveAgentSpec(chosen);
+            if (!spec) {
+                errorLog(`Error: no launch agent is registered for '${chosen}'.`);
+                return 1;
+            }
+            finalAgentName = chosen;
+            finalSpawnCommand = deps.buildShellCommand(spec, INSTALL_BRIDGE_AGENT_PROMPT, deps.cwd, deps.platform);
+        }
+        // chosen === null → non-TTY / unavailable / invalid → manual continuation below.
+    }
+    // planLaunch.kind === "manual" (no-launchable) → finalAgentName stays null.
+    // ---- Materialize the Step 5 launch command + kick off the pre-warm — ONLY for a
+    // spawn-capable path. A manual/no-launchable/chooser-declined path opens no session,
+    // so it neither materializes a launch script nor warms a bucket it will never use.
+    //
+    // Materialization runs HERE, before the scaffold/mint/credential/config writes,
+    // because a command that cannot be launched safely is a whole-run failure, not a
+    // Step 5 warning: the deterministic setup would otherwise complete and leave the user
+    // in the "configured but never configured by the agent" state. Failing first means
+    // nothing is half-done. The @VERSION-pinned launcher lives in a DIFFERENT _npx bucket
+    // than the @latest bucket this invocation warmed, so the pre-warm (fire-and-forget,
+    // strictly fail-open) overlaps the ping/exchange/scaffold/writes and is awaited just
+    // before the consent-gated spawn.
+    let launchCommand = null;
+    let prewarmPromise = null;
+    if (finalAgentName && finalSpawnCommand) {
+        const materialized = await materializeWorkerLaunchCommand(deps.startTicketsDeps, "install", finalSpawnCommand);
+        if (!materialized.ok) {
+            errorLog(`Error: ${materialized.error}`);
+            return 1;
+        }
+        launchCommand = materialized.command;
+        // Independent final guard on the line ACTUALLY handed to the terminal — not on the
+        // original command. It catches the two ways a "successful" materialization can still
+        // be unlaunchable: no writer seam (inline command preserved verbatim), and a runner
+        // whose script path is unexpectedly long.
+        if (Buffer.byteLength(launchCommand, "utf8") >= MAX_TERMINAL_COMMAND_BYTES) {
+            errorLog("Error: the agent session command is too long to send to the terminal safely. " +
+                "Check that the system temporary directory is writable so the launch script can be used.");
+            return 1;
+        }
+        log("  pre-warming the version-pinned launcher bucket (in the background)…");
+        prewarmPromise = deps.spawnPrewarm("npx", buildPrewarmArgs(), deps.env);
     }
     const credentialWriteDeps = {
         env: deps.env,
@@ -2238,25 +2516,6 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // ensureGitignored for the state file can still throw — also advisory.
         errorLog("Warning: could not persist the install-state file (non-fatal).");
     }
-    // ---- Step 3b — pre-warm the @${VERSION}-pinned _npx bucket (BAPI-451 W3) ----
-    // The launcher just written is pinned to @${VERSION}, a DIFFERENT _npx bucket
-    // than the @latest bucket this `npx … install-bridge` invocation warmed. Spawn
-    // the exact pinned launcher once with the fast-exiting `--version` flag so the
-    // first real MCP launch resolves from a warm bucket instead of paying the cold
-    // install inline (which can exceed the client's connect deadline). Strictly
-    // fail-open: a failure warns (secret-free) but never fails the install.
-    log("  pre-warming the version-pinned launcher bucket…");
-    const prewarm = await deps.spawnPrewarm("npx", buildPrewarmArgs(), deps.env);
-    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}`);
-    }
     // ---- Step 4 — persist the credential ----
     if (bootstrapInviteMode) {
         // FAIL-CLOSED (unlike normal mode below). The pending secret IS the minted admin
@@ -2306,32 +2565,71 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // 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 5 — spawn a fresh agent session for the agentic remainder ----
-    log(`Step 5/5 — opening a ${agent.name} session for /install-bridge configuration + capability report…`);
-    const terminal = detectTerminal(undefined, deps.env);
-    // Only the validated short runner reaches the terminal — never the inline prompt.
-    const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, launchCommand, {
-        key: "install",
-        worktreePath: deps.cwd,
-    });
-    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) — the
-        // user can run the agentic remainder by hand. Mirrors start-tickets treating a
-        // spawn failure as non-fatal to the run.
-        errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}). ` +
-            "The project is NOT configured yet — run /install-bridge manually in this project to derive " +
-            "and apply the config fields and see the capability report, then choose whether to run " +
-            "/parse-repository to index the repository.");
+    // ---- 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}`);
+        }
+    }
+    // ---- 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"));
+                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.");
+            return 0;
+        }
+        // Declined (or non-TTY suppression): the deterministic setup is complete and durable.
+        log(buildManualInstallBridgeContinuation("configured"));
         return 0;
     }
-    log("");
-    log(`install-bridge setup steps complete. A fresh ${agent.name} session is now applying ` +
-        "configuration, presenting the capability report, and ending with one indexing-consent question.");
-    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, and it will close by asking " +
-        "'[Y/n] Index repository now?'. Verify afterwards on the project's Get Started page " +
-        "(install status panel) or via the session's 'Applied N of M' summary.");
+    // 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"));
     return 0;
 }