@bridge_gpt/mcp-server 0.2.25 → 0.2.27

package/build/install-bridge.js

@@ -88,6 +88,10 @@ 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 { provisionHostTarget, createDefaultVendorProcessDeps, } from "./mcp-host-config.js";
+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";
 // BAPI-631: the optional GitHub connect offer reuses the standalone command's flow and
@@ -109,7 +113,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() {
@@ -232,6 +240,18 @@ export function getInstallBridgeUsage() {
         "                    THE TOKEN to your shell history and to the process list.",
         "",
         "Flags:",
+        "  --tools <ids>                 Comma-separated AI-coding tools to configure,",
+        "                                bypassing the interactive picker. Accepted ids:",
+        `                                ${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.",
         "  --force                       Overwrite an existing real BAPI_API_KEY in a",
         "                                host config (or in the credential store) without",
         "                                prompting.",
@@ -271,6 +291,7 @@ export function parseInstallBridgeArgs(argv) {
     let agentName = DEFAULT_AGENT_NAME;
     let invite;
     let email;
+    let tools;
     // Track SUPPLIED-ness separately from the values: `--invite` is legitimately
     // valueless (prompt path) and `--api-key ""` is still a contradiction with it.
     let inviteSupplied = false;
@@ -345,6 +366,17 @@ export function parseInstallBridgeArgs(argv) {
             i = r.nextIndex;
             continue;
         }
+        if (arg === "--tools" || arg.startsWith("--tools=")) {
+            const r = readValue(arg, "--tools", i);
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            const parsed = parseToolsSelection(r.value);
+            if ("error" in parsed)
+                return { status: "error", message: parsed.error };
+            tools = parsed.tools;
+            i = r.nextIndex;
+            continue;
+        }
         if (arg === "--agent" || arg.startsWith("--agent=")) {
             const r = readValue(arg, "--agent", i);
             if ("error" in r)
@@ -395,9 +427,36 @@ export function parseInstallBridgeArgs(argv) {
     }
     return {
         status: "ok",
-        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied, email },
+        options: { apiKey, repo, force, dryRun, agentName, invite, inviteMode: inviteSupplied, email, tools },
     };
 }
+/**
+ * Parse a `--tools` value into a validated platform-ID selection. A blank value
+ * (`--tools=`) is an EXPLICIT empty selection (`[]`), not an error. Comma-split
+ * IDs are trimmed, deduped in registry order, and each is validated against the
+ * host registry allowlist so an unvalidated string can never choose a path or
+ * command. Unknown IDs are rejected by name (the value is safe to echo — it is
+ * a platform ID, never a secret).
+ */
+export function parseToolsSelection(value) {
+    const raw = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const seen = new Set();
+    for (const id of raw) {
+        if (!isHostPlatformId(id)) {
+            const allowed = HOST_PLATFORM_ORDER.join(", ");
+            return {
+                error: `Invalid --tools value: '${id}' (allowed tools: ${allowed}).`,
+            };
+        }
+        seen.add(id);
+    }
+    // Dedupe + deterministic registry order.
+    const tools = HOST_PLATFORM_ORDER.filter((id) => seen.has(id));
+    return { tools };
+}
 /**
  * No-echo secret prompt on stderr (so it never lands in piped stdout).
  *
@@ -620,6 +679,8 @@ export function createDefaultInstallBridgeDeps() {
         randomBytes: (size) => cryptoRandomBytes(size),
         promptSecret: isTTY ? promptSecretViaReadline : undefined,
         promptLine: isTTY ? promptLineViaReadline : undefined,
+        promptMultiSelect: isTTY ? promptMultiSelectViaReadline : undefined,
+        vendor: createDefaultVendorProcessDeps(spawn),
         fetch: productionFetch,
         resolveRepoViaServer: (baseUrl, apiKey) => resolveRepoViaServer(productionFetch, baseUrl, apiKey),
         spawnPrewarm: spawnPrewarmDefault,
@@ -900,6 +961,164 @@ export async function resolveRepoName(options, deps, mode = "existing-registrati
     }
     return { ok: false, error: "No repo name provided." };
 }
+// ---------------------------------------------------------------------------
+// Per-host config write (Step 2)
+// ---------------------------------------------------------------------------
+/** 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?";
+/**
+ * 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.
+ */
+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`);
+            options.forEach((opt, idx) => {
+                const mark = selected.has(opt.id) ? "[x]" : "[ ]";
+                output.write(`  ${idx + 1}. ${mark} ${opt.label}\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;
+            rl.close();
+            resolve(options.filter((o) => selected.has(o.id)).map((o) => o.id));
+        };
+        // 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));
+        });
+        const ask = () => {
+            render();
+            rl.question("", (answer) => {
+                const trimmed = answer.trim();
+                if (trimmed.length === 0) {
+                    finish();
+                    return;
+                }
+                const tokens = trimmed.split(",").map((t) => t.trim());
+                const nums = [];
+                let bad = false;
+                for (const tok of tokens) {
+                    const n = Number(tok);
+                    if (!Number.isInteger(n) || n < 1 || n > options.length) {
+                        bad = true;
+                        break;
+                    }
+                    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);
+                }
+                finish();
+            });
+        };
+        ask();
+    });
+}
+/**
+ * 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),
+ *   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).
+ */
+export async function resolveSelectedHostPlatforms(deps, options) {
+    // 1. Explicit --tools (empty array is an explicit empty selection).
+    if (options.tools !== undefined) {
+        return options.tools;
+    }
+    const ctx = await buildDetectionContext(deps);
+    const detected = new Set(detectDefaultPlatforms(ctx));
+    // 2. Interactive multi-select on a TTY.
+    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 chosen = await deps.promptMultiSelect(INSTALL_BRIDGE_TOOL_SELECTOR_PROMPT, optionList, defaults);
+        return HOST_PLATFORM_ORDER.filter((id) => chosen.includes(id));
+    }
+    // 3. Legacy non-TTY automatic set: Claude + detected Cursor / Copilot VS Code.
+    const legacy = ["claude-code"];
+    if (detected.has("cursor"))
+        legacy.push("cursor");
+    if (detected.has("copilot-vscode"))
+        legacy.push("copilot-vscode");
+    return HOST_PLATFORM_ORDER.filter((id) => legacy.includes(id));
+}
+/**
+ * Build a registry detection context from install deps. install-bridge has only
+ * async `stat`, but the registry's `detect` callbacks are synchronous, so we
+ * pre-probe the candidate marker paths (the same ones the registry consults) and
+ * expose them through a synchronous `exists` set. Paths are built in the registry's
+ * POSIX-join form so the lookup matches exactly what `detect` passes to `exists`.
+ */
+async function buildDetectionContext(deps) {
+    const cwd = deps.cwd;
+    const homedir = deps.homedir();
+    const posixJoin = (base, rel) => `${base.endsWith("/") ? base.slice(0, -1) : base}/${rel}`;
+    const candidates = [
+        posixJoin(cwd, ".cursor"),
+        posixJoin(cwd, ".vscode"),
+        posixJoin(cwd, ".windsurf"),
+        posixJoin(cwd, ".windsurfrules"),
+        posixJoin(homedir, ".codex"),
+    ];
+    const present = new Set();
+    await Promise.all(candidates.map(async (p) => {
+        try {
+            await deps.stat(p);
+            present.add(p);
+        }
+        catch {
+            // absent — leave out of the set.
+        }
+    }));
+    return {
+        cwd,
+        homedir,
+        env: deps.env,
+        exists: (p) => present.has(p),
+    };
+}
+/**
+ * Resolve which project-local JSON host configs to write for the selected
+ * platforms. Only the project-scoped JSON targets (Claude Code, Cursor, Copilot
+ * VS Code) are returned here; global targets (Codex, Copilot CLI) and manual
+ * targets (Windsurf) are handled by the registry-driven emitter in
+ * `runInstallBridgeCli`. The returned shape is unchanged so the existing
+ * read-merge-write path and overwrite-consent detection are preserved.
+ */
+function hostConfigTargetsForPlatforms(platforms) {
+    const set = new Set(platforms);
+    return HOST_PLATFORM_ORDER.filter((id) => set.has(id))
+        .map((id) => MCP_HOST_TARGETS[id])
+        .filter((t) => t.scope === "project" && t.format === "json")
+        .map((t) => ({ relPath: t.relPath, topLevelKey: t.topLevelKey }));
+}
 /** Resolve which project-local host configs to write, mirroring runInit detection. */
 async function resolveHostConfigTargets(deps) {
     const targets = [
@@ -1001,6 +1220,58 @@ async function writeHostConfigs(deps, targets, entry) {
     }
     return written;
 }
+/**
+ * Provision the selected GLOBAL (Codex, Copilot CLI) and MANUAL (Windsurf)
+ * targets through the registry-driven emitter (BAPI-635). Project JSON targets
+ * are handled by {@link writeHostConfigs}; this covers everything else. Global
+ * 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).
+ */
+async function provisionSelectedGlobalTargets(deps, platforms, entry) {
+    const logLines = [];
+    const provisionDeps = {
+        fs: {
+            readFile: deps.readFile,
+            writeFile: (p, data) => deps.writeFile(p, data, { encoding: "utf-8" }),
+            mkdir: async (p, o) => {
+                await deps.mkdir(p, o);
+            },
+        },
+        vendor: deps.vendor,
+        cwd: deps.cwd,
+        homedir: deps.homedir(),
+        env: deps.env,
+    };
+    const set = new Set(platforms);
+    for (const id of HOST_PLATFORM_ORDER) {
+        if (!set.has(id))
+            continue;
+        const target = MCP_HOST_TARGETS[id];
+        // Skip project JSON targets — those are handled by writeHostConfigs.
+        if (target.scope === "project" && target.format === "json")
+            continue;
+        const outcome = await provisionHostTarget(target, entry, provisionDeps);
+        switch (outcome.status) {
+            case "vendor-written":
+            case "direct-written":
+            case "created":
+                logLines.push(`  configured ${target.label} (${outcome.displayPath})`);
+                break;
+            case "manual-required":
+                logLines.push(`  ${target.label}: add the bridge-api MCP server manually to ${outcome.displayPath} ` +
+                    "(the API key is redacted in printed instructions).");
+                break;
+            case "skipped-invalid":
+                logLines.push(`  ${target.label}: skipped ${outcome.displayPath} — existing config is not valid; left untouched.`);
+                break;
+            case "failed":
+                logLines.push(`  ${target.label}: could not be configured automatically; configure it manually.`);
+                break;
+        }
+    }
+    return logLines;
+}
 /** Build the `/jira/ping` URL exactly like the MCP `ping` tool / buildGetUrl. */
 export function buildPingUrl(baseUrl, repoName) {
     const url = new URL(`${baseUrl.replace(/\/+$/, "")}/jira/ping`);
@@ -1614,7 +1885,13 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         env: deps.env,
         homedir: deps.homedir,
     });
-    const targets = await resolveHostConfigTargets(deps);
+    // 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
+    // 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);
     const plan = {
@@ -1669,6 +1946,21 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             "Check that the system temporary directory is writable so the launch script can be used.");
         return 1;
     }
+    // ---- Step 3b (kickoff) — pre-warm the @${VERSION}-pinned _npx bucket ----
+    // The @${VERSION}-pinned launcher written below lives in a DIFFERENT _npx bucket
+    // than the @latest bucket this `npx … install-bridge` invocation warmed, so the
+    // first real MCP launch would otherwise pay a cold install inline (which can
+    // exceed the client's connect deadline). Nothing before the Step 5 terminal spawn
+    // depends on the warmed bucket — only the spawned session's first MCP launch does
+    // — so START the warm HERE (fire-and-forget) and AWAIT it just before that spawn.
+    // Its multi-second `npx` resolve then overlaps the network round-trips (ping /
+    // exchange), the scaffold, and the config/credential writes instead of adding to
+    // them serially. Strictly fail-open: the default impl always RESOLVES (never
+    // rejects), so a later abort-return that skips the await leaves no unhandled
+    // rejection. Positioned AFTER the launch-command guards above so an aborted run
+    // that never reaches an install side effect also never spawns the pre-warm.
+    log("  pre-warming the version-pinned launcher bucket (in the background)…");
+    const prewarmPromise = deps.spawnPrewarm("npx", buildPrewarmArgs(), deps.env);
     const credentialWriteDeps = {
         env: deps.env,
         homedir: deps.homedir,
@@ -1889,31 +2181,81 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     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) {
+        try {
+            await ensureGitignoredShared(deps.cwd, target.relPath, gitignoreDeps);
+        }
+        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}`);
-    // Only print global-editor manual setup when Windsurf/Codex is actually detected.
-    const manualInstructions = buildManualHostInstructions(entry, manualEditors);
+    // 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);
-    // ---- 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}`);
+    // 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.
+            errorLog("Warning: could not persist the install-state file (non-fatal).");
+        }
     }
-    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}`);
+    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) {
@@ -1964,6 +2306,22 @@ 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 3b (await) — settle the background pre-warm before the session opens ----
+    // The warm was kicked off right after the launch-command guards (above); await it
+    // HERE so the bucket is settled before the spawned session's first MCP launch, but
+    // AFTER all the work it overlapped with. Strictly fail-open — the exit code is
+    // never affected, mirroring the original inline Step 3b behavior.
+    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 — 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);