@bridge_gpt/mcp-server 0.2.41 → 0.2.43

package/build/install-bridge.js

@@ -143,13 +143,15 @@ import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { runInit, buildBridgeApiEntry, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
+import { runInit, InitPreflightError, buildBridgeApiEntry, mergeBridgeApiProfileToken, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
 import { hasProjectRootMarker as sharedHasProjectRootMarker } from "./project-root.js";
 import { VERSION } from "./version.generated.js";
 import { validateRepoName } from "./bridge-config.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 { recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, writeMcpInstallState, } from "./mcp-install-state.js";
+import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, hostAdapterForTarget, } from "./mcp-host-targets.js";
+import { provisionHostTarget, createDefaultVendorProcessDeps, inspectBridgeApiProfileToken, } from "./mcp-host-config.js";
+import { MCP_SERVER_NAME, MCP_PACKAGE_NAME, resolveRegistrationKey, } from "./mcp-identity.js";
+import { DUPLICATE_REGISTRATION_GUIDANCE } from "./launcher-config-inspection.js";
+import { recordInstalledConductorCapability, recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, writeMcpInstallState, } from "./mcp-install-state.js";
 // Executor provisioning (BAPI-779). The generator and the lifecycle module are
 // imported DIRECTLY and driven programmatically — never by spawning
 // `executor install-service` as a subprocess, which would lose the typed plan,
@@ -157,8 +159,10 @@ import { recordInstalledExecutorServiceUnit, recordInstalledProjectArtifact, wri
 import { collectExecutorInstallPreflight, } from "./executor/install-preflight.js";
 import { inspectExecutorServiceState, startExecutorService, } from "./executor/service-lifecycle.js";
 import { executorLaunchdLabelForId, executorSystemdUnitNameForId, executorLaunchdPlistPathForId, executorSystemdUnitPathForId, resolvePackagedExecutorInvocation, writeExecutorServicePlan, } from "./executor/service-unit.js";
+import { collectConductorNativeLedgerSafe, } from "./conductor/doctor.js";
+import { installConductorGitHooks, } from "./conductor/git-hooks.js";
 import { runInstallBridgeConductorCli, } from "./install-bridge-conductor.js";
-import { runConductorInstallDoctor, } from "./conductor/install-doctor.js";
+import { runConductorInstallDoctor, CONDUCTOR_PROFILE_TOKEN, } from "./conductor/install-doctor.js";
 import { resolveConductorBridgeApiAccess, } from "./conductor/bridge-api-client.js";
 import { claudeReviewWorkflowPath, writeClaudeReviewWorkflow, } from "./claude-review-workflow.js";
 import { runSetupEpicCli } from "./setup-epic.js";
@@ -194,7 +198,7 @@ export function buildPrewarmArgs() {
     // 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"];
+    return ["-y", "--prefer-offline", `${MCP_PACKAGE_NAME}@${VERSION}`, "--version"];
 }
 /** Secret-free preview of the pre-warm command (no env, no key). */
 export function buildPrewarmCommandPreview() {
@@ -202,7 +206,10 @@ export function buildPrewarmCommandPreview() {
 }
 /**
  * The natural-language prompt handed to the spawned agent session. It is
- * CONFIGURE-ONLY: it derives and applies configuration, presents the concise
+ * CONFIGURE-ONLY: it derives and applies configuration (or, on the greenfield
+ * path BAPI-855 added, delegates that work wholesale to the packaged
+ * `greenfield-setup` recipe — this prompt describes the handoff in one sentence
+ * and deliberately embeds no recipe orchestration of its own), presents the concise
  * capability report — the availability-framed 'Available now' / 'Needs setup'
  * pair the server authors (BAPI-719), rendered verbatim with zero local
  * curation — and closes with the server-provided `next_step.command`
@@ -216,11 +223,16 @@ export function buildPrewarmCommandPreview() {
  */
 export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command in the install-spawn context (tell the command it is running " +
     "in the install-spawn context so it SKIPS its Stage 8, Stage 9, and Stage 10 offers). " +
-    "The command chooses its own mode from the install manifest's `configured` flag — do NOT force a " +
-    "mode: when `configured` is false it runs its fresh-configuration flow, and when `configured` is " +
-    "true it runs JOIN MODE. In JOIN MODE the command must NOT derive, approve, apply, or offer any " +
-    "configuration and applies zero fields for any caller; a joining member's closing interaction " +
-    "is the welcome plus the concise capability report. " +
+    "The command owns its own Stage 2 decision and evaluates it in a fixed order from the install " +
+    "manifest — do NOT force an outcome. `configured == true` is JOIN MODE; otherwise a manifest whose " +
+    "`greenfield_setup_path` field is already set is GREENFIELD REPORT-ONLY; otherwise the command's " +
+    "Stage 2b classifies the repository as greenfield or established. In JOIN MODE and in GREENFIELD " +
+    "REPORT-ONLY the command must NOT derive, approve, apply, or offer any configuration and applies " +
+    "zero fields for any caller; the closing interaction is the welcome plus the concise capability " +
+    "report. An established classification runs the ordinary fresh-configuration flow unchanged. " +
+    "A greenfield classification hands off to the packaged `greenfield-setup` recipe — the command " +
+    "fetches it with get_pipeline_recipe and completes every returned step in THIS same session, then " +
+    "resumes /install-bridge reporting from the recipe's own read-after-write manifest. " +
     "Complete the command's concise capability report: the single 'What Bridge " +
     "can help with' section, rendered exactly as the server's concise_tool_capabilities field gives it. " +
     "That field is exactly two availability sections in server order — 'Available now' first, then " +
@@ -232,7 +244,7 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "contract metadata only — render both kinds identically, with no label, icon, or separate list, " +
     "and never branch on it. Keep an empty section visible with a short neutral line rather than " +
     "dropping it, and after both sections close with a pointer to the Bridge MCP server README at " +
-    "https://www.npmjs.com/package/@bridge_gpt/mcp-server for the complete tool documentation, " +
+    `https://www.npmjs.com/package/${MCP_PACKAGE_NAME} for the complete tool documentation, ` +
     "including when either or both sections are empty. Do not render the obsolete five-section report, " +
     "and do not locally filter, count, sort, regroup, infer availability, fabricate an item, or fall " +
     "back to the complete tool_capabilities catalog or the workflows collection. If " +
@@ -255,8 +267,10 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "funnel with no visibility from this session, so say nothing about it at all. " +
     "Close with the server's own next step, which you must read at runtime rather than assume. Inspect " +
     "the `next_step` object on the manifest response the flow already used: on the fresh-configuration " +
-    "path that is the Stage 7 post-apply read-after-write manifest, and in JOIN MODE it is the Stage 2 " +
-    "manifest (JOIN MODE performs no read-after-write). Look at `next_step.command`: when it is a " +
+    "path that is the Stage 7 post-apply read-after-write manifest; after a greenfield handoff it is " +
+    "the read-after-write manifest the greenfield-setup recipe returned; and in JOIN MODE and " +
+    "GREENFIELD REPORT-ONLY it is the Stage 2 manifest (neither performs a read-after-write). Look at " +
+    "`next_step.command`: when it is a " +
     "NON-EMPTY string, recommend exactly that command, verbatim, in inline code — do not rename it or " +
     "substitute a command you happen to know. When it is an empty string, make NO next-command " +
     "recommendation at all and say nothing in its place: no heading, no placeholder, no 'nothing to " +
@@ -274,7 +288,11 @@ export const INSTALL_BRIDGE_AGENT_PROMPT = "Execute the /install-bridge command
     "the apply_install_manifest call " +
     "applied (e.g. 'Applied 8 of 9 derived fields') — if 0 fields were applied, say so loudly and " +
     "explain what is still pending. In JOIN MODE there is no apply — state instead that the project " +
-    "was already configured and zero changes were made, without a fabricated applied count.";
+    "was already configured and zero changes were made, without a fabricated applied count. The two " +
+    "greenfield paths report the same way: GREENFIELD REPORT-ONLY states that greenfield setup was " +
+    "already completed and that zero changes were made, and a completed greenfield handoff states " +
+    "which setup path the recipe recorded — the recipe made the only apply, so neither path invents an " +
+    "applied count or apply buckets of its own.";
 /** Default base URL when `BAPI_BASE_URL` is unset (mirrors index.ts). */
 export const DEFAULT_BAPI_BASE_URL = "https://bridgegpt-api.com";
 /**
@@ -302,7 +320,7 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
     const setupUrl = buildInstallBridgeSetupUrl(baseUrl);
     return [
         "Usage:",
-        "  npx -y @bridge_gpt/mcp-server install [flags]",
+        `  npx -y ${MCP_PACKAGE_NAME} install [flags]`,
         "",
         "One-command Bridge API project bootstrap. Scaffolds the project, writes the",
         "per-host MCP config with your credentials, verifies connectivity, persists the",
@@ -502,8 +520,17 @@ export function getInstallBridgeUsage(baseUrl = DEFAULT_BAPI_BASE_URL) {
         "                                which writes the safe project-default supervisor",
         "                                posture in one transaction; it optionally",
         "                                scaffolds a parameterized claude-review workflow",
-        "                                (its own separate consent), prints the capability",
-        "                                matrix, and re-runs the doctor. `--dry-run`",
+        "                                (its own separate consent), then closes the local",
+        "                                out-of-the-box gap in two more phases, each behind",
+        "                                its OWN consent: tool visibility adds the",
+        "                                `conductor` token to existing .mcp.json /",
+        "                                .vscode/mcp.json / .cursor/mcp.json entries (never",
+        "                                Codex or Copilot, and never creating a file) and",
+        "                                prints the MCP-client restart advisory; local",
+        "                                observability installs the managed conductor Git",
+        "                                hooks and then reports native ledger loadability",
+        "                                read-only. It finally prints the capability",
+        "                                matrix and re-runs the doctor. `--dry-run`",
         "                                performs NO write of any kind and no write-consent",
         "                                prompt (the base-URL confirmation still applies).",
         "                                Executor service units are generated by",
@@ -770,7 +797,7 @@ export function promptSecretViaReadline(promptText, input = process.stdin, outpu
  * The deferral command printed with the GitHub offer (BAPI-669, U6). Declining is
  * cheap precisely because this exists — the connection is a standalone command.
  */
-export const INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND = "npx -y @bridge_gpt/mcp-server connect-github";
+export const INSTALL_BRIDGE_CONNECT_GITHUB_COMMAND = `npx -y ${MCP_PACKAGE_NAME} connect-github`;
 /**
  * The `Step 4b` label + purpose + deferral lines printed immediately before the
  * GitHub prompt (BAPI-669, U6). Shared with {@link buildLaunchStepPreview} so the
@@ -845,13 +872,13 @@ export async function offerGithubConnection(repoName, baseUrl, deps, log) {
         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}'.`);
+                `'npx -y ${MCP_PACKAGE_NAME}@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}'.`);
+            `GitHub later with 'npx -y ${MCP_PACKAGE_NAME}@latest connect-github --repo ${repoName}'.`);
     }
 }
 /**
@@ -995,6 +1022,12 @@ export function createDefaultInstallBridgeDeps() {
             fetch: params.fetch,
             reviewPolicySource: params.reviewPolicySource,
             readWorkflowFile: () => params.readFile(claudeReviewWorkflowPath(params.cwd)),
+            // BAPI-775: the SAME project root the rest of installation resolves
+            // against, and the SAME read-only host-config inspector the
+            // tool-visibility phase reports from — so the doctor's profile-token
+            // section and the phase can never disagree about what is on disk.
+            projectRoot: params.cwd,
+            inspectProfileToken: (projectRoot, token) => inspectBridgeApiProfileToken(projectRoot, token, { readFile: params.readFile }),
             // Read-only service-state probe (BAPI-779). Typed to return a state,
             // never a runner, so the doctor cannot start/enable/reload anything.
             inspectExecutorServiceState: params.inspectExecutorServiceState,
@@ -1141,6 +1174,46 @@ function buildConductorExecutorDeps(deps, baseUrl) {
         sleep: deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
     };
 }
+/**
+ * Compose the local out-of-the-box provisioning bundle the two BAPI-775 phases
+ * run on, from the FINAL merged deps.
+ *
+ * Same shape and same rationale as {@link buildConductorExecutorDeps}: every
+ * entry is a thin adapter over an existing implementation, and nothing here
+ * decides anything. Consent, ordering, degradation, and reporting live in
+ * `install-bridge-conductor.ts`.
+ *
+ * `mergeBridgeApiProfileToken` is called with the resolved project root and the
+ * conductor token, reusing the helper byte-for-byte: its idempotent token-set
+ * merge and its refusal to create a missing host config are load-bearing, and
+ * reimplementing either here would fork the only writer of
+ * `BRIDGE_MCP_PROFILE`.
+ */
+function buildConductorLocalDeps(deps) {
+    return {
+        mergeProfileToken: () => mergeBridgeApiProfileToken(deps.cwd, CONDUCTOR_PROFILE_TOKEN),
+        inspectProfileToken: () => inspectBridgeApiProfileToken(deps.cwd, CONDUCTOR_PROFILE_TOKEN, {
+            readFile: deps.readFile,
+        }),
+        // The repository root is this command's cwd, which is what the hook
+        // installer resolves its worktree and hooks directory from.
+        installGitHooks: async () => installConductorGitHooks({ cwd: deps.cwd }),
+        // The SHARED collector (BAPI-775), so the phase's ledger verdict and the
+        // conductor doctor's cannot diverge. Its safe variant contains any
+        // collection failure as a generic degraded inspection.
+        probeNativeLedger: () => collectConductorNativeLedgerSafe(),
+        recordCapability: async (capability) => {
+            const result = await recordInstalledConductorCapability(deps.cwd, capability, {
+                readFile: deps.readFile,
+                writeFile: (p, data) => deps.writeFile(p, data),
+                rename: deps.rename,
+                mkdir: (p, o) => deps.mkdir(p, o),
+                unlink: deps.unlink,
+            });
+            return result.ok ? { ok: true } : { ok: false, error: result.error };
+        },
+    };
+}
 /**
  * Read-only local service-state inspector for the unified doctor (BAPI-779).
  *
@@ -1928,8 +2001,8 @@ 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 }));
+        .filter((t) => t.scope === "project" && hostAdapterForTarget(t).format === "json")
+        .map((t) => ({ relPath: t.relPath, topLevelKey: hostAdapterForTarget(t).topLevelKey }));
 }
 /**
  * Derive the human-facing labels for a set of selected platforms, in registry
@@ -1942,11 +2015,13 @@ export function labelsForPlatforms(platforms) {
     const set = new Set(platforms);
     return HOST_PLATFORM_ORDER.filter((id) => set.has(id)).map((id) => MCP_HOST_TARGETS[id].label);
 }
+/** Project-local host-config metadata sourced from the shared registry/adapter. */
+function toHostConfigTarget(target) {
+    return { relPath: target.relPath, topLevelKey: hostAdapterForTarget(target).topLevelKey };
+}
 /** Resolve which project-local host configs to write, mirroring runInit detection. */
 async function resolveHostConfigTargets(deps) {
-    const targets = [
-        { relPath: ".mcp.json", topLevelKey: "mcpServers" },
-    ];
+    const targets = [toHostConfigTarget(MCP_HOST_TARGETS["claude-code"])];
     const dirExists = async (rel) => {
         try {
             await deps.stat(path.join(deps.cwd, rel));
@@ -1957,10 +2032,10 @@ async function resolveHostConfigTargets(deps) {
         }
     };
     if (await dirExists(".vscode")) {
-        targets.push({ relPath: ".vscode/mcp.json", topLevelKey: "servers" });
+        targets.push(toHostConfigTarget(MCP_HOST_TARGETS["copilot-vscode"]));
     }
     if ((await dirExists(".cursor")) || deps.env.CURSOR_TRACE_DIR) {
-        targets.push({ relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" });
+        targets.push(toHostConfigTarget(MCP_HOST_TARGETS.cursor));
     }
     return targets;
 }
@@ -2021,7 +2096,7 @@ export function buildInstallBridgeSecretFreeServerEntry(cwd, repoName, baseUrl,
  */
 function formatCredentialStoreGuidance(repoName, credentialStorePath) {
     return [
-        "  The bridge-api server resolves your key at runtime from the BAPI_API_KEY environment",
+        `  The ${MCP_SERVER_NAME} server resolves your key at runtime from the BAPI_API_KEY environment`,
         `  variable or the user-scoped credential store (${credentialStorePath}, target`,
         `  bapi:${repoName}), so it stays out of this file entirely.`,
     ];
@@ -2034,7 +2109,7 @@ function formatCredentialStoreGuidance(repoName, credentialStorePath) {
  * existing file — never for replacing it.
  */
 function formatSecretFreeManualMerge(relPath, topLevelKey, secretFreeEntry) {
-    const snippet = JSON.stringify({ [topLevelKey]: { "bridge-api": secretFreeEntry } }, null, 2);
+    const snippet = JSON.stringify({ [topLevelKey]: { [MCP_SERVER_NAME]: secretFreeEntry } }, null, 2);
     return [
         `  To configure ${relPath} by hand, MERGE this secret-free entry into the existing`,
         "  file (do not replace the file):",
@@ -2102,7 +2177,16 @@ async function detectExistingRealKey(deps, targets) {
         if (result.state === "absent")
             continue;
         const topLevel = asRecord(result.config[target.topLevelKey]);
-        const entry = asRecord(topLevel?.["bridge-api"]);
+        // BAPI-807: a real key under a legacy `bridge-api` entry is just as much a
+        // reason to ask for overwrite consent as one under `bridge`. A both-key
+        // config is conservatively treated as possibly key-bearing for the same
+        // reason `invalid` is.
+        const resolution = resolveRegistrationKey(topLevel);
+        if (resolution.state === "conflict")
+            return true;
+        if (resolution.state === "absent")
+            continue;
+        const entry = asRecord(topLevel?.[resolution.key]);
         const env = asRecord(entry?.["env"]);
         if (env && !isPlaceholderApiKey(env["BAPI_API_KEY"])) {
             return true;
@@ -2175,6 +2259,28 @@ export function preserveExistingLauncherArgs(existing, entry) {
     const preserved = refreshBridgeApiPackageSpec(existingArgs, currentBridgePackageSpec());
     return preserved ? { ...entry, args: preserved } : entry;
 }
+/**
+ * Read-only pre-scan for both-key configs across EVERY project target (BAPI-807).
+ *
+ * Run before the registration phase begins writing, so a conflict discovered in
+ * `.cursor/mcp.json` cannot leave `.mcp.json` and `.vscode/mcp.json` already
+ * rewritten. A target that is absent or unparseable contributes no conflict —
+ * those are handled by the existing per-target branches, which have their own
+ * non-fatal semantics.
+ */
+async function detectDuplicateRegistrations(deps, targets) {
+    const conflicts = [];
+    for (const target of targets) {
+        const read = await readHostConfig(deps, path.join(deps.cwd, target.relPath));
+        if (read.state !== "parsed")
+            continue;
+        const topLevel = asRecord(read.config[target.topLevelKey]);
+        if (resolveRegistrationKey(topLevel).state === "conflict") {
+            conflicts.push(target.relPath);
+        }
+    }
+    return conflicts;
+}
 /**
  * Write the `bridge-api` entry into each host config via read-merge-write,
  * preserving unrelated servers and top-level keys (BAPI-666). Per target:
@@ -2192,6 +2298,13 @@ export function preserveExistingLauncherArgs(existing, entry) {
 async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
     const written = [];
     const skipped = [];
+    // BAPI-807: detect both-key configs across ALL targets BEFORE the first write.
+    // A multi-target registration phase that discovered the conflict on its third
+    // target would already have rewritten the first two.
+    const duplicateRegistrations = await detectDuplicateRegistrations(deps, targets);
+    if (duplicateRegistrations.length > 0) {
+        return { written, skipped, duplicateRegistrations };
+    }
     for (const target of targets) {
         const fullPath = path.join(deps.cwd, target.relPath);
         const read = await readHostConfig(deps, fullPath);
@@ -2235,21 +2348,33 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // never initialized before its tracked-state consent is resolved.
         const config = read.state === "parsed" ? read.config : {};
         const topLevel = asRecord(config[target.topLevelKey]) ?? {};
+        // BAPI-807: resolve WHICH key this config's registration lives under before
+        // writing. A legacy-only entry is replaced under `bridge-api`, a canonical-only
+        // entry under `bridge`, and an absent one is created under MCP_SERVER_NAME.
+        const resolution = resolveRegistrationKey(topLevel);
+        if (resolution.state === "conflict") {
+            // Unreachable: the pre-scan above returned before any write when it found a
+            // conflict. Re-checked rather than asserted, so a future caller that skips
+            // the pre-scan still cannot write over an ambiguous registration.
+            skipped.push({ relPath: target.relPath, reason: "invalid" });
+            continue;
+        }
+        const registrationKey = resolution.state === "absent" ? resolution.writeKey : resolution.key;
         // BAPI-714 (Group C): a PRE-EXISTING Bridge entry keeps its own launcher args
         // composition — only the package-spec token is refreshed — so the installer
         // never migrates a legacy bare launcher to `serve`. A newly created entry gets
         // the full template args, `serve` included. The rule is identical for the
         // real-key and secret-free variants: credential safety must not decide whether
         // a launcher is migrated.
-        topLevel["bridge-api"] = preserveExistingLauncherArgs(topLevel["bridge-api"], entry);
+        topLevel[registrationKey] = preserveExistingLauncherArgs(topLevel[registrationKey], entry);
         config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
         await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
             encoding: "utf-8",
         });
-        written.push({ relPath: target.relPath, mode });
+        written.push({ relPath: target.relPath, mode, registrationKey });
     }
-    return { written, skipped };
+    return { written, skipped, duplicateRegistrations: [] };
 }
 /**
  * Provision the selected GLOBAL (Codex, Copilot CLI) and MANUAL (Windsurf)
@@ -2266,6 +2391,7 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
  */
 async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
     const logLines = [];
+    const duplicateRegistrations = [];
     let anyManualRequired = false;
     const provisionDeps = {
         fs: {
@@ -2286,7 +2412,7 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
             continue;
         const target = MCP_HOST_TARGETS[id];
         // Skip project JSON targets — those are handled by writeHostConfigs.
-        if (target.scope === "project" && target.format === "json")
+        if (target.scope === "project" && hostAdapterForTarget(target).format === "json")
             continue;
         const outcome = await provisionHostTarget(target, entry, provisionDeps);
         switch (outcome.status) {
@@ -2297,12 +2423,19 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
                 break;
             case "manual-required":
                 anyManualRequired = true;
-                logLines.push(`  ${target.label}: add the bridge-api MCP server manually to ${outcome.displayPath} ` +
+                logLines.push(`  ${target.label}: add the ${MCP_SERVER_NAME} 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 "skipped-duplicate-registration":
+                // BAPI-807: NOT an ordinary vendor-fallback condition. The target was
+                // left byte-identical and the caller must fail loudly rather than report
+                // a configured host.
+                duplicateRegistrations.push(target.displayPath);
+                logLines.push(`  ${target.label}: skipped ${outcome.displayPath} — ${outcome.detail}`);
+                break;
             case "failed":
                 logLines.push(`  ${target.label}: could not be configured automatically; configure it manually.`);
                 break;
@@ -2311,7 +2444,7 @@ async function provisionSelectedGlobalTargets(deps, platforms, entry, needKey) {
     if (needKey && anyManualRequired) {
         logLines.push(`  ${formatNeedKeyCredentialStoreLine(needKey.repoName, needKey.credentialStorePath)}`);
     }
-    return logLines;
+    return { logLines, duplicateRegistrations };
 }
 /** Build the `/jira/ping` URL exactly like the MCP `ping` tool / buildGetUrl. */
 export function buildPingUrl(baseUrl, repoName) {
@@ -2842,7 +2975,7 @@ export const INSTALL_BRIDGE_SIGNUP_UPGRADE_REQUIRED = [
     "Signup now verifies your email address with a code before creating a workspace. Upgrade",
     "and re-run:",
     "",
-    "  npx -y @bridge_gpt/mcp-server@latest install --email <addr>",
+    `  npx -y ${MCP_PACKAGE_NAME}@latest install --email <addr>`,
 ].join("\n");
 /**
  * Mask an address for display: first character, then the domain.
@@ -3619,11 +3752,11 @@ function buildManualHostInstructions(entry, editors, needKey) {
         "Add the server manually (replace <REDACTED> with your key):",
     ];
     if (editors.windsurf) {
-        const windsurfSnippet = JSON.stringify({ mcpServers: { "bridge-api": { command: entry.command, args: entry.args, env: redactedEnv } } }, null, 2);
+        const windsurfSnippet = JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: entry.command, args: entry.args, env: redactedEnv } } }, null, 2);
         lines.push("", "  Windsurf → ~/.codeium/windsurf/mcp_config.json:", windsurfSnippet);
     }
     if (editors.codex) {
-        lines.push("", "  Codex → ~/.codex/config.toml (add an [mcp_servers.bridge-api] table with the", "  same command/args/env shown above, BAPI_API_KEY set to your key).");
+        lines.push("", `  Codex → ~/.codex/config.toml (add an [mcp_servers.${MCP_SERVER_NAME}] table with the`, "  same command/args/env shown above, BAPI_API_KEY set to your key).");
     }
     if (needKey) {
         lines.push("", `  ${formatNeedKeyCredentialStoreLine(needKey.repoName, needKey.credentialStorePath)}`);
@@ -3638,7 +3771,7 @@ function buildManualHostInstructions(entry, editors, needKey) {
  * ONCE and reused by the Step 1–5 catch, the `index.ts` dispatch catch, the
  * tests, and the feature documentation, so the command text cannot drift.
  */
-export const INSTALL_BRIDGE_DOCTOR_COMMAND = "npx -y @bridge_gpt/mcp-server doctor";
+export const INSTALL_BRIDGE_DOCTOR_COMMAND = `npx -y ${MCP_PACKAGE_NAME} doctor`;
 /**
  * The canonical pointer LINE (BAPI-669, U9a). One syntax — no quotes, no alternate
  * punctuation — shared by the Step 1–5 catch and by every operational fatal in the
@@ -3980,6 +4113,9 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             // seams above are: a test that overrides only `fetch` or only `homedir`
             // must see its override here, not a stale default captured earlier.
             executorProvisioning: buildConductorExecutorDeps(deps, conductorBaseUrl),
+            // Built from the FINAL merged deps for the same reason (BAPI-775): a test
+            // that overrides only `readFile` or only `cwd` must see its override here.
+            localProvisioning: buildConductorLocalDeps(deps),
         };
         return runInstallBridgeConductorCli(argv.slice(1), conductorDeps);
     }
@@ -5072,6 +5208,18 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             trackedState.set(target.relPath, await isTrackedProjectConfig(deps, target.relPath));
         }
         const writeResult = await writeHostConfigs(deps, targets, { real: entry, secretFree: secretFreeEntry }, trackedState, { repoName, credentialStorePath });
+        // BAPI-807: a both-key project config is a FAIL-LOUD condition, not an
+        // ordinary skip. Nothing was written (the pre-write scan returned before the
+        // first target), and continuing would report a successful install over a
+        // registration Bridge deliberately refused to touch.
+        if (writeResult.duplicateRegistrations.length > 0) {
+            errorLog(`Error: ${DUPLICATE_REGISTRATION_GUIDANCE}`);
+            for (const relPath of writeResult.duplicateRegistrations) {
+                errorLog(`  ${relPath}`);
+            }
+            errorLog("  Nothing was written. Re-run install-bridge once one entry is removed.");
+            return 1;
+        }
         // BAPI-708 (B-a): these files are the MCP SERVER REGISTRATION (BAPI_REPO_NAME,
         // BAPI_BASE_URL, BAPI_DOCS_DIR, BAPI_PROJECT_ROOT, and the version-pinned npx
         // launcher) — calling them a credentials file was simply inaccurate. Where the
@@ -5094,9 +5242,20 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         const needKeyManual = bootstrapInviteMode
             ? { repoName, credentialStorePath }
             : undefined;
-        const globalLogLines = await provisionSelectedGlobalTargets(deps, selectedPlatforms, entry, needKeyManual);
-        for (const line of globalLogLines)
+        const globalProvisioning = await provisionSelectedGlobalTargets(deps, selectedPlatforms, entry, needKeyManual);
+        for (const line of globalProvisioning.logLines)
             log(line);
+        // BAPI-807: a global target that refused because it already carries both
+        // registrations is fail-loud, exactly like the project-config case above —
+        // never an ordinary vendor fallback the run can shrug off.
+        if (globalProvisioning.duplicateRegistrations.length > 0) {
+            errorLog(`Error: ${DUPLICATE_REGISTRATION_GUIDANCE}`);
+            for (const displayPath of globalProvisioning.duplicateRegistrations) {
+                errorLog(`  ${displayPath}`);
+            }
+            errorLog("  That host was left untouched. Re-run install-bridge once one entry is removed.");
+            return 1;
+        }
         // 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
@@ -5187,7 +5346,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                         `start-tickets model routing may not resolve the key for bapi:${repoName} ` +
                         "and will fail open to the premium/Opus tier (the most expensive) — " +
                         "set BAPI_API_KEY in the shell or re-run install, then verify with " +
-                        "'npx -y @bridge_gpt/mcp-server doctor'.");
+                        `'npx -y ${MCP_PACKAGE_NAME} doctor'.`);
                 }
             }
             catch {
@@ -5196,7 +5355,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 log("  warning: could not persist the routing credential (unexpected error). " +
                     "start-tickets model routing may need BAPI_API_KEY in the shell and will fail open " +
                     "to the premium/Opus tier (the most expensive) until fixed — verify with " +
-                    "'npx -y @bridge_gpt/mcp-server doctor'.");
+                    `'npx -y ${MCP_PACKAGE_NAME} doctor'.`);
             }
         }
         // ---- commit-your-assets notice (BAPI-708, Part C) ----
@@ -5280,7 +5439,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     "server provides.");
                 // The trust dialog is the single most common place a spawned session stalls:
                 // the tab opens, nothing is approved, and the install looks hung.
-                log(`In the new tab: approve the workspace and the 'bridge-api' MCP server if ${handoffToolLabel} ` +
+                log(`In the new tab: approve the workspace and the '${MCP_SERVER_NAME}' MCP server if ${handoffToolLabel} ` +
                     "asks — configuration can't proceed until you do.");
                 // Recovery was previously printed ONLY on no-spawn paths, so a tab that opened
                 // and then died left the user with no instruction at all.
@@ -5304,6 +5463,25 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         return 0;
     }
     catch (error) {
+        // BAPI-807: a launcher-config PREFLIGHT refusal is actionable, and the
+        // operator must be told what to do — collapsing it into the generic
+        // "unexpected error" cause is how a duplicate registration would look like
+        // a bug in Bridge instead of two entries in their own config.
+        //
+        // This is safe under the module's secret-suppression discipline because
+        // `InitPreflightError` is a TYPE this codebase owns, and its payload is a
+        // closed set: a repo-relative config path plus a reason string drawn from
+        // the fixed `REASON_TEXT` table. No caught free-form message, no config
+        // body, and no env value is read here.
+        if (error instanceof InitPreflightError) {
+            errorLog("Error: these MCP launcher configs cannot be safely reconciled:");
+            for (const failure of error.failures) {
+                errorLog(`  ${failure.relPath}: ${failure.reason}`);
+            }
+            errorLog("  Nothing was changed. Resolve these by hand, then re-run install-bridge.");
+            errorLog(INSTALL_BRIDGE_DOCTOR_POINTER);
+            return 1;
+        }
         // Resume guidance ONLY after the exchange actually succeeded (R5-2): before
         // that the invite is unspent and there is nothing to resume. The wording comes
         // from the mode-aware helper, never a fresh literal, so a self-serve user is

package/build/install-doctor.js

@@ -22,6 +22,8 @@
 import path from "path";
 import { resolveBapiCredentials } from "./credential-store.js";
 import { detectClaudeLogin, formatClaudeLoginAdvisory } from "./claude-login.js";
+import { getProjectJsonTargets, hostAdapterForTarget } from "./mcp-host-targets.js";
+import { existingRegistrationKey, MCP_PACKAGE_NAME, } from "./mcp-identity.js";
 /** Default production base URL (mirrors install-bridge's DEFAULT_BAPI_BASE_URL). */
 const DEFAULT_BASE_URL = "https://bridgegpt-api.com";
 /**
@@ -36,12 +38,15 @@ const DEFAULT_BASE_URL = "https://bridgegpt-api.com";
 function buildSetupUrl(baseUrl) {
     return `${baseUrl.replace(/\/+$/, "")}/setup`;
 }
-/** Project-local MCP configs whose env blocks may carry repo/base-URL values. */
-const MCP_CONFIG_ENV_TARGETS = [
-    { relPath: ".mcp.json", topLevelKey: "mcpServers" },
-    { relPath: ".cursor/mcp.json", topLevelKey: "mcpServers" },
-    { relPath: ".vscode/mcp.json", topLevelKey: "servers" },
-];
+/**
+ * Project-local MCP configs whose env blocks may carry repo/base-URL values.
+ * Derived from the shared host-target registry's project-scoped JSON targets
+ * rather than duplicating each path/root-key pair here.
+ */
+const MCP_CONFIG_ENV_TARGETS = getProjectJsonTargets().map((target) => ({
+    relPath: target.relPath,
+    topLevelKey: hostAdapterForTarget(target).topLevelKey,
+}));
 /** Timeout for each read-only probe request. */
 const PROBE_TIMEOUT_MS = 5_000;
 /**
@@ -72,9 +77,18 @@ export async function resolveInstallDoctorTarget(deps) {
             catch {
                 continue;
             }
-            const envBlock = parsed && typeof parsed === "object"
+            // BAPI-807: read the env block through the RESOLVED registration key. A
+            // config written before the rename registers `bridge-api`, and looking
+            // only under the canonical name would report a perfectly working install
+            // as having no repo/base-URL configured at all.
+            const servers = parsed && typeof parsed === "object"
+                ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    parsed[topLevelKey]
+                : undefined;
+            const registrationKey = existingRegistrationKey(servers);
+            const envBlock = registrationKey !== null
                 ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    parsed[topLevelKey]?.["bridge-api"]?.env
+                    servers[registrationKey]?.env
                 : undefined;
             if (!envBlock)
                 continue;
@@ -410,7 +424,7 @@ export async function collectInstallStatusChecks(deps) {
                 label: "GitHub connection",
                 status: "WARN",
                 detail: "no GitHub repository is connected to this project",
-                remediation: `run 'npx -y @bridge_gpt/mcp-server@latest connect-github --repo ${target.repoName}'.`,
+                remediation: `run 'npx -y ${MCP_PACKAGE_NAME}@latest connect-github --repo ${target.repoName}'.`,
             });
         }
     }

package/build/install-reexec.js

@@ -40,6 +40,7 @@ import { VERSION } from "./version.generated.js";
 import { isNewerVersion } from "./update-check.js";
 import { fetchLatestVersion } from "./cli-release.js";
 import { runInstallBridgeCli } from "./install-bridge.js";
+import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 /** The sentinel that marks an already-re-exec'd child. Matches `upgrade-cli.ts`. */
 export const INSTALL_REEXEC_SENTINEL = "--internal-reexec";
 /**
@@ -189,7 +190,7 @@ export async function runInstallBridgeWithLatestCli(argv, deps = {}) {
     const npxCmd = platform === "win32" ? "npx.cmd" : "npx";
     const childArgs = [
         "-y",
-        "@bridge_gpt/mcp-server@latest",
+        `${MCP_PACKAGE_NAME}@latest`,
         "install",
         INSTALL_REEXEC_SENTINEL,
         ...forwardedArgs,