@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/install-bridge.js

@@ -36,8 +36,26 @@
  * reload the just-written `.mcp.json`, and field derivation needs an agent
  * runtime the shell does not have.
  *
- * BOOTSTRAP-INVITE MODE (BAPI-606) — the one exception to "this command consumes
- * a key, it does not create one". With `--invite` (or `BAPI_INVITE`) there is no
+ * 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
+ * command is written to a restricted (0600) launch script and only a short
+ * `. '<path>'` runner is spawned (BAPI-626, via `materializeWorkerLaunchCommand`).
+ * Materialization happens BEFORE any install side effect, because a command that
+ * cannot be launched is a whole-run failure, not a Step 5 warning.
+ *
+ * ONBOARDING BRANCHES — `have-key` (consume an existing key) vs. `need-key` (this
+ * command creates the project AND its first admin key). There are two need-key
+ * methods, differing only in how the first token is obtained: `bootstrap-invite`
+ * (BAPI-606) redeems a pre-issued invite; `self-serve` (BAPI-618) mints one from an
+ * email. Both then feed the SAME redemption protocol. Selection is pure and
+ * deterministic from flags/env, except that a BARE interactive run is asked which
+ * branch it wants (BAPI-626) — without that question a first-time user cannot
+ * discover self-serve at all. Either need-key method NAMES a new project, so the
+ * 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:
  *
@@ -70,10 +88,18 @@ 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, } from "./credential-store.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
+// 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 { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, } from "./start-tickets.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>";
 /**
@@ -126,8 +152,10 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "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. " +
-    "Never request, echo, or transport any credential — only ever direct the human to the setup UI via " +
-    "the command's configure_in pointer. " +
+    "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.";
@@ -146,13 +174,20 @@ export function getInstallBridgeUsage() {
         "routing credential, then opens a fresh agent session to derive the remaining",
         "config, present a capability report, and offer optional repository indexing.",
         "",
+        "Run it bare — `install-bridge` with no flags — in a terminal and it asks",
+        `\`${INSTALL_BRIDGE_KEY_SELECTOR_PROMPT.trim()}\` first. Answer yes (or press Enter) for the`,
+        "existing-key flow below; answer no and it asks for an email and creates a new",
+        "Bridge workspace for you (the self-serve flow). That question is asked ONLY for a",
+        "bare interactive run: passing ANY flag, setting BAPI_API_KEY, or running without",
+        "an interactive terminal keeps the existing deterministic behavior and no prompt.",
+        "",
         "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 (--invite is the one exception:",
-        "                    it CREATES the project and its first admin key). NEVER",
-        "                    printed or logged.",
+        "                    key, it does not create one (--email and --invite are the",
+        "                    exceptions: they CREATE the project and its first admin key).",
+        "                    NEVER printed or logged.",
         "  --repo <name>     Repository name. --repo and BAPI_REPO_NAME still take",
         "                    priority and short-circuit before any network call. When",
         "                    neither is set, a compatible server resolves the unique",
@@ -160,10 +195,13 @@ export function getInstallBridgeUsage() {
         "                    server is older, the key is unresolvable, or resolution",
         "                    fails, it falls back to an inferred default you confirm",
         "                    interactively (and to a required --repo when stdin is",
-        "                    non-interactive). MUST match the server-side repo",
-        "                    registration (it keys the credential store as bapi:<repo>).",
-        "                    With --invite it is the name your NEW project is created",
-        "                    under (globally unique).",
+        "                    non-interactive). In the existing-key flow it MUST match the",
+        "                    server-side repo registration (it keys the credential store",
+        "                    as bapi:<repo>). In either new-project flow (--email,",
+        "                    --invite, or a negative answer to the key question above) it",
+        "                    instead NAMES the project this run creates, so you are asked",
+        "                    to name a new project rather than match an existing one; the",
+        "                    name must be globally unique.",
         "",
         "Self-serve onboarding (no account, no API key, no pre-issued invite):",
         "  --email <addr>    Create a brand-new Bridge workspace from just an email —",
@@ -171,8 +209,10 @@ export function getInstallBridgeUsage() {
         "                    It requests a fresh workspace for that email, then creates",
         "                    the project and mints your own admin API key in one command.",
         "                    Falls back to the BAPI_SIGNUP_EMAIL env var, then a visible",
-        "                    interactive prompt. The email is NOT a secret (it is shown",
-        "                    as you type), but it is never printed to a log. Mutually",
+        "                    interactive prompt — which is also what a negative answer to",
+        "                    the bare-run key question above reaches. The email is NOT a",
+        "                    secret (it is shown as you type), but it is never printed to",
+        "                    a log. Mutually",
         "                    exclusive with --api-key and --invite. No email verification",
         "                    is performed and no message is sent to the address — it only",
         "                    labels the new workspace.",
@@ -196,6 +236,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.",
@@ -235,6 +287,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;
@@ -309,6 +362,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)
@@ -359,9 +423,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).
  *
@@ -420,6 +511,66 @@ export function promptSecretViaReadline(promptText, input = process.stdin, outpu
         muted = true;
     });
 }
+/**
+ * Offer to connect GitHub, if it is not already connected (BAPI-631).
+ *
+ * Entirely best-effort and non-destructive: by the time this runs the install itself is
+ * already complete and durable, so nothing here may fail the run. Every branch that is
+ * not "the user said yes and it worked" simply proceeds to the agent session.
+ *
+ * Reuses the shared connect-github flow rather than duplicating the API, polling,
+ * browser, or picker logic — there is exactly one implementation of that handshake.
+ */
+async function offerGithubConnection(repoName, deps, log) {
+    // No prompt surface → no offer. Never assume consent on a non-interactive run.
+    if (!deps.isTTY || !deps.promptLine)
+        return;
+    try {
+        const credDeps = {
+            env: deps.env,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+            stderr: () => { },
+        };
+        // Resolve through the shared resolver rather than reusing an in-memory key from
+        // this run: the offered flow is the same shell-spawned surface the standalone
+        // command uses, and it must resolve credentials the same way (project MCP config
+        // env is NOT visible to a spawned shell).
+        const cred = await resolveBapiCredentials(repoName, credDeps);
+        if (!cred.ok)
+            return;
+        const api = {
+            fetch: deps.fetch,
+            baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
+            apiKey: cred.credentials.apiKey,
+        };
+        const state = await fetchGithubConfigurationState(api, repoName);
+        if (state === "configured")
+            return;
+        if (state === "unavailable") {
+            // Do NOT fabricate "unconfigured" from a probe that simply failed — offering to
+            // connect an already-connected repo is worse than staying quiet.
+            log("  note: could not read GitHub configuration status; skipping the GitHub offer.");
+            return;
+        }
+        const answer = (await deps.promptLine("Connect GitHub? (Y/n): ")).trim().toLowerCase();
+        if (answer === "n" || answer === "no")
+            return; // declining is a normal outcome
+        const connectDeps = createDefaultConnectGithubDeps();
+        const code = await runGithubConnectionFlow(connectDeps, api, repoName);
+        if (code !== 0) {
+            log("  note: GitHub was not connected. Your install is complete — connect GitHub later with " +
+                `'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`);
+        }
+    }
+    catch {
+        // The install is already durable; a failure here is never fatal to it.
+        log("  note: the GitHub connection offer could not run. Your install is complete — connect " +
+            `GitHub later with 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${repoName}'.`);
+    }
+}
 /** Echoed single-line prompt on stderr (used for repo confirmation / value). */
 function promptLineViaReadline(promptText) {
     return new Promise((resolve) => {
@@ -524,6 +675,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,
@@ -666,6 +819,68 @@ 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] ";
+/**
+ * Interactive wrapper around {@link resolveInstallBridgeOnboardingBranch}.
+ *
+ * The pure resolver defaults every un-signalled invocation to `have-key`, which is
+ * correct for a script but wrong for a human: a first-time user with nothing yet
+ * runs a bare `install-bridge`, gets the hidden API-key prompt, and has no way to
+ * discover that the self-serve email path exists. So a BARE INTERACTIVE run — and
+ * only that — is asked which branch it wants.
+ *
+ * "Bare" is deliberately strict. Any of these keeps the existing deterministic
+ * behaviour with NO prompt:
+ *
+ *   - stdin is not a TTY, or no `promptLine` seam is available (scripts, CI);
+ *   - any CLI argument was supplied (the user already stated an intent);
+ *   - a non-blank `BAPI_API_KEY` is present (that IS the existing-key intent);
+ *   - the pure resolver already chose a need-key branch explicitly.
+ *
+ * A prompt failure becomes a typed, secret-free failure rather than an exception:
+ * the caller turns it into an exit code, and terminal/internal error text never
+ * reaches the user.
+ */
+export async function resolveInstallBridgeOnboardingBranchForRun(options, deps, argv) {
+    const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+    // An explicit need-key intent is already unambiguous — never re-ask it.
+    if (branch.kind === "need-key")
+        return { ok: true, branch };
+    const hasEnvApiKey = (deps.env.BAPI_API_KEY ?? "").trim().length > 0;
+    const isBareInvocation = argv.length === 0;
+    if (!deps.isTTY || !deps.promptLine || !isBareInvocation || hasEnvApiKey) {
+        return { ok: true, branch };
+    }
+    const promptLine = deps.promptLine;
+    try {
+        // Bounded so a prompt seam that returns the same invalid value forever (a
+        // misbehaving pipe that passes the TTY check) cannot spin indefinitely.
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            const answer = (await promptLine(INSTALL_BRIDGE_KEY_SELECTOR_PROMPT)).trim().toLowerCase();
+            // Blank = accept the bracketed default (Y), matching the prompt's own contract.
+            if (answer.length === 0 || answer === "y" || answer === "yes") {
+                return { ok: true, branch: { kind: "have-key" } };
+            }
+            if (answer === "n" || answer === "no") {
+                return { ok: true, branch: { kind: "need-key", method: "self-serve" } };
+            }
+            deps.log("Please answer y or n (press Enter for yes).");
+        }
+        return {
+            ok: false,
+            error: "No valid answer to the Bridge API key question. Re-run and answer y or n.",
+        };
+    }
+    catch {
+        // Secret-free by construction: the caught value is never surfaced.
+        return {
+            ok: false,
+            error: "Could not read your answer from the terminal. Re-run with --api-key <key> if you have a " +
+                "Bridge API key, or --email <addr> to create a new Bridge workspace.",
+        };
+    }
+}
 /**
  * Return the explicitly configured repository name (`--repo`, then
  * `BAPI_REPO_NAME`), trimmed, or `undefined` when neither is supplied. Pure: no
@@ -682,7 +897,18 @@ export function resolveConfiguredRepoName(options, env) {
     }
     return undefined;
 }
-export async function resolveRepoName(options, deps) {
+/**
+ * Resolve the repo name: `--repo` → `BAPI_REPO_NAME` env → inferred default
+ * (from .bridge/config, else the cwd basename) confirmed interactively. Fails
+ * fast (no inference) when neither is supplied and stdin is non-interactive —
+ * the repo identity keys the credential store, so it is never silently inferred
+ * non-interactively.
+ *
+ * `mode` selects only the WORDING (prompt and non-interactive error); resolution
+ * order, inference, and validation are identical in both. It defaults to
+ * `existing-registration` to preserve the behaviour of pre-BAPI-626 callers.
+ */
+export async function resolveRepoName(options, deps, mode = "existing-registration") {
     const configured = resolveConfiguredRepoName(options, deps.env);
     if (configured !== undefined) {
         return { ok: true, value: configured };
@@ -692,9 +918,13 @@ export async function resolveRepoName(options, deps) {
     if (!deps.isTTY || !deps.promptLine) {
         return {
             ok: false,
-            error: "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable " +
-                "(no interactive terminal is available to confirm an inferred name). It must match the " +
-                "server-side repository registration.",
+            error: mode === "new-project"
+                ? "A project name is required. Pass --repo or set the BAPI_REPO_NAME environment " +
+                    "variable (no interactive terminal is available to confirm an inferred name). It " +
+                    "names the new Bridge project this run creates and must be globally unique."
+                : "A repo name is required. Pass --repo or set the BAPI_REPO_NAME environment variable " +
+                    "(no interactive terminal is available to confirm an inferred name). It must match the " +
+                    "server-side repository registration.",
         };
     }
     // Infer a sensible default: existing .bridge/config, else the cwd basename.
@@ -709,18 +939,182 @@ export async function resolveRepoName(options, deps) {
             inferred = validated.value;
     }
     if (inferred) {
-        const answer = (await deps.promptLine(`Repo name [${inferred}] (must match server-side registration): `)).trim();
+        const promptText = mode === "new-project"
+            ? `Name your new Bridge project [${inferred}]: `
+            : `Repo name [${inferred}] (must match server-side registration): `;
+        const answer = (await deps.promptLine(promptText)).trim();
         const chosen = answer.length > 0 ? answer : inferred;
         if (chosen.length > 0)
             return { ok: true, value: chosen };
     }
     else {
-        const answer = (await deps.promptLine("Repo name (must match server-side registration): ")).trim();
+        const promptText = mode === "new-project"
+            ? "Name your new Bridge project: "
+            : "Repo name (must match server-side registration): ";
+        const answer = (await deps.promptLine(promptText)).trim();
         if (answer.length > 0)
             return { ok: true, value: answer };
     }
     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 = [
@@ -822,6 +1216,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`);
@@ -1159,7 +1605,29 @@ export function buildDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — persist routing credential: target ${plan.credentialTarget} at ${plan.credentialStorePath}`,
-        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+        ...buildLaunchStepPreview(plan),
+    ];
+}
+/**
+ * The Step 5 preview lines, shared by both previews so the launch description
+ * cannot drift between the have-key and need-key flows.
+ *
+ * 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.
+ */
+function buildLaunchStepPreview(plan) {
+    return [
+        // 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}`,
     ];
 }
 /**
@@ -1214,7 +1682,7 @@ function buildBootstrapDryRunPreview(plan) {
         `Step 3b — pre-warm the version-pinned launcher bucket (fail-open, env sanitized — BAPI_API_KEY / BAPI_INVITE removed): ${plan.prewarmCommand}`,
         MCP_TIMEOUT_GUIDANCE,
         `Step 4 — promote ${pendingTarget} → ${plan.credentialTarget} at ${plan.credentialStorePath} (only after the exchange succeeds)`,
-        `Step 5 — spawn agent session: ${plan.spawnCommand}`,
+        ...buildLaunchStepPreview(plan),
     ];
 }
 /**
@@ -1301,12 +1769,21 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 1;
     }
     const options = parsed.options;
-    // Onboarding branch (pure, deterministic): have-key vs. a need-key method
-    // (`bootstrap-invite` = redeem a pre-issued invite, `self-serve` = mint one from
-    // an email, BAPI-618). BOTH need-key methods share the downstream redemption
-    // protocol, so `bootstrapInviteMode` is true for both; `selfServeSignupMode`
-    // discriminates the one extra step (mint-from-email) the self-serve path adds.
-    const branch = resolveInstallBridgeOnboardingBranch(options, deps.env);
+    // Onboarding branch: have-key vs. a need-key method (`bootstrap-invite` = redeem
+    // a pre-issued invite, `self-serve` = mint one from an email, BAPI-618). BOTH
+    // need-key methods share the downstream redemption protocol, so
+    // `bootstrapInviteMode` is true for both; `selfServeSignupMode` discriminates the
+    // one extra step (mint-from-email) the self-serve path adds.
+    //
+    // The selection is pure and deterministic for every explicit, env-driven, and
+    // non-TTY invocation; only a BARE interactive run is asked which branch it wants
+    // (BAPI-626 — otherwise a first-time user can never reach self-serve).
+    const branchResult = await resolveInstallBridgeOnboardingBranchForRun(options, deps, argv);
+    if (!branchResult.ok) {
+        errorLog(`Error: ${branchResult.error}`);
+        return 1;
+    }
+    const branch = branchResult.branch;
     const bootstrapInviteMode = branch.kind === "need-key";
     const selfServeSignupMode = branch.kind === "need-key" && branch.method === "self-serve";
     // ---- Resolve inputs (may prompt when interactive) ----
@@ -1348,15 +1825,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     const baseUrl = deps.env.BAPI_BASE_URL ?? DEFAULT_BAPI_BASE_URL;
     const docsDir = deps.env.BAPI_DOCS_DIR ?? DEFAULT_BAPI_DOCS_DIR;
     // ---- Resolve the repository name ----
-    // Bootstrap-invite: unchanged (choose-a-name for the new project). Have-key:
+    // Need-key (invite or self-serve): choose-a-name for the project this run is
+    // about to create, so the prompt says exactly that. Have-key:
     // `--repo`/`BAPI_REPO_NAME` short-circuit deterministically; otherwise resolve
     // it server-side from the API key (BAPI-616), and on ANY non-resolution outcome
     // (unresolved / not-deployed / error) fall back to the existing local
-    // prompt/inference — never a hard failure.
+    // prompt/inference — never a hard failure. That fallback keeps the
+    // existing-registration wording: there the name must match a real project.
     let repoName;
     let attemptedServerResolution = false;
     if (bootstrapInviteMode) {
-        const repoResult = await resolveRepoName(options, deps);
+        const repoResult = await resolveRepoName(options, deps, "new-project");
         if (!repoResult.ok) {
             errorLog(`Error: ${repoResult.error}`);
             return 1;
@@ -1387,7 +1866,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 // 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.
-                const repoResult = await resolveRepoName(options, deps);
+                const repoResult = await resolveRepoName(options, deps, "existing-registration");
                 if (!repoResult.ok) {
                     errorLog(`Error: ${repoResult.error}`);
                     return 1;
@@ -1402,7 +1881,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 = {
@@ -1432,6 +1917,31 @@ 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;
+    }
+    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;
+    }
     const credentialWriteDeps = {
         env: deps.env,
         homedir: deps.homedir,
@@ -1652,13 +2162,82 @@ 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);
+    // 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).");
+        }
+    }
+    catch {
+        // 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
@@ -1721,10 +2300,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 "'npx -y @bridge_gpt/mcp-server doctor'.");
         }
     }
+    // ---- optional GitHub connect offer (BAPI-631) ----
+    // Placed AFTER the credential is durable (the flow needs a resolvable key) and BEFORE
+    // the agent spawn, for two reasons: the spawned session's capability report should
+    // observe GitHub as configured if the user connects it here, and running it after the
+    // spawn would put two prompts on the same terminal at once.
+    await offerGithubConnection(repoName, deps, log);
     // ---- Step 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);
-    const spawnResult = await deps.spawnTerminalTab(deps.startTicketsDeps, terminal, spawnCommand, {
+    // 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,
     });