@bridge_gpt/mcp-server 0.2.39 → 0.2.42

package/build/mcp-host-config.js

@@ -23,12 +23,21 @@
  *
  * TOML NOTE: there is no comment-preserving TOML library available, so Codex
  * direct writes render a canonical document for a missing file, APPEND canonical
- * tables to an existing file that has no `bridge-api` table (preserving every
- * existing byte), and DECLINE (`manual-required`) an existing `bridge-api` table
+ * tables to an existing file that has no recognized Bridge table (preserving every
+ * existing byte), and DECLINE (`manual-required`) an existing Bridge table
  * rather than reserialize unrelated content.
  */
 import { VERSION } from "./version.generated.js";
 import { refreshBridgeApiPackageSpec } from "./init.js";
+import { hostAdapterForTarget, } from "./mcp-host-targets.js";
+import { LEGACY_SERVER_NAMES, MCP_SERVER_NAME, MCP_PACKAGE_NAME, RECOGNIZED_SERVER_NAMES, resolveRegistrationKey, } from "./mcp-identity.js";
+/**
+ * The secret-free, repair-oriented detail every duplicate-registration outcome
+ * carries. Names both keys, prescribes manual removal, and deliberately does not
+ * choose a survivor — see {@link resolveRegistrationKey}.
+ */
+export const DUPLICATE_REGISTRATION_DETAIL = `both \`${MCP_SERVER_NAME}\` and \`${LEGACY_SERVER_NAMES.join("`, `")}\` are registered here; ` +
+    "confirm which one to keep, remove the other manually, then re-run. Nothing was changed.";
 // ---------------------------------------------------------------------------
 // Path helpers (POSIX-normalized; module stays free of node:path).
 // ---------------------------------------------------------------------------
@@ -64,15 +73,16 @@ export function resolveTargetAbsPath(target, ctx) {
  * use `stdio`; Copilot CLI uses `local` + `tools: ["*"]`.
  */
 export function adaptBridgeEntryForHostTarget(entry, target) {
+    const adapter = hostAdapterForTarget(target);
     const physical = {};
-    if (target.transportType !== undefined) {
-        physical.type = target.transportType;
+    if (adapter.transportType !== undefined) {
+        physical.type = adapter.transportType;
     }
     physical.command = entry.command;
     physical.args = [...entry.args];
     physical.env = { ...entry.env };
-    if (target.extraEntryKeys) {
-        for (const [k, v] of Object.entries(target.extraEntryKeys)) {
+    if (adapter.extraEntryKeys) {
+        for (const [k, v] of Object.entries(adapter.extraEntryKeys)) {
             physical[k] = v;
         }
     }
@@ -110,36 +120,63 @@ export async function readJsonHostConfig(path, deps) {
     return { state: "valid", value: parsed };
 }
 /**
- * Merge the adapted `bridge-api` entry into an existing JSON document under the
+ * Merge the adapted Bridge entry into an existing JSON document under the
  * registry-selected root key. Unrelated top-level keys and unrelated servers are
- * preserved; only the `bridge-api` entry is replaced.
+ * preserved; only the resolved Bridge entry is replaced.
+ *
+ * BAPI-807 — resolve THEN write. The write key comes from
+ * {@link resolveRegistrationKey} rather than being assumed canonical:
+ *
+ *  - a legacy `bridge-api` entry is replaced UNDER `bridge-api`, so an existing
+ *    installation is never renamed and never gains a second entry;
+ *  - a canonical entry is replaced under `bridge`;
+ *  - when neither key exists a new entry is created under {@link MCP_SERVER_NAME};
+ *  - when BOTH exist nothing is merged — the caller gets a conflict result.
  */
 export function mergeJsonHostConfig(existing, target, adaptedEntry) {
+    const adapter = hostAdapterForTarget(target);
     const merged = { ...existing };
-    const rootRaw = merged[target.topLevelKey];
+    const rootRaw = merged[adapter.topLevelKey];
     const root = rootRaw && typeof rootRaw === "object" && !Array.isArray(rootRaw)
         ? { ...rootRaw }
         : {};
+    const resolution = resolveRegistrationKey(root);
+    if (resolution.state === "conflict") {
+        return { status: "duplicate-registration", keys: resolution.keys };
+    }
+    const writeKey = resolution.state === "absent" ? resolution.writeKey : resolution.key;
     // BAPI-714 (Group C): an UPDATE to a pre-existing Bridge registration keeps that
     // registration's own launcher args composition — only the package-spec token is
     // refreshed — so a global/manual host config written before `serve` existed is
     // never migrated to it. A registration this path CREATES receives the adapted
-    // template args, `serve` included.
-    const prior = root["bridge-api"];
+    // template args, `serve` included. The prior entry is read through the RESOLVED
+    // key, so a legacy registration's args are preserved exactly like a canonical
+    // one's.
+    const prior = root[writeKey];
     const preservedArgs = prior && typeof prior === "object" && !Array.isArray(prior)
         ? refreshBridgeApiPackageSpec(prior.args, currentLauncherSpec())
         : null;
-    root["bridge-api"] = preservedArgs ? { ...adaptedEntry, args: preservedArgs } : adaptedEntry;
-    merged[target.topLevelKey] = root;
-    return merged;
+    root[writeKey] = preservedArgs ? { ...adaptedEntry, args: preservedArgs } : adaptedEntry;
+    merged[adapter.topLevelKey] = root;
+    return { status: "merged", document: merged, registrationKey: writeKey };
 }
-/** Build a fresh JSON document containing only the Bridge entry. */
+/**
+ * Build a fresh JSON document containing only the Bridge entry.
+ *
+ * A FRESH document is by definition an absent registration, so it uses
+ * {@link MCP_SERVER_NAME} unconditionally — Claude, Cursor, VS Code, and Copilot
+ * documents created from nothing all say `bridge`. A legacy key can only ever be
+ * reached through the merge path above, which requires the key to already exist.
+ */
 function freshJsonDocument(target, adaptedEntry) {
-    return { [target.topLevelKey]: { "bridge-api": adaptedEntry } };
+    const adapter = hostAdapterForTarget(target);
+    return { [adapter.topLevelKey]: { [MCP_SERVER_NAME]: adaptedEntry } };
 }
 /**
  * Direct-write a JSON host config. Malformed existing JSON is skipped with an
- * explicit `skipped — invalid JSON` result and is never overwritten.
+ * explicit `skipped — invalid JSON` result and is never overwritten; a both-key
+ * config is skipped the same way and — critically — before `mkdir` or
+ * `writeFile` is reached (BAPI-807).
  */
 export async function writeJsonHostConfig(path, target, adaptedEntry, deps) {
     const read = await readJsonHostConfig(path, deps);
@@ -147,9 +184,22 @@ export async function writeJsonHostConfig(path, target, adaptedEntry, deps) {
         return { status: "skipped-invalid", message: "skipped — invalid JSON" };
     }
     const isCreate = read.state === "missing";
-    const doc = isCreate
-        ? freshJsonDocument(target, adaptedEntry)
-        : mergeJsonHostConfig(read.value, target, adaptedEntry);
+    let doc;
+    if (isCreate) {
+        doc = freshJsonDocument(target, adaptedEntry);
+    }
+    else {
+        const merge = mergeJsonHostConfig(read.value, target, adaptedEntry);
+        if (merge.status === "duplicate-registration") {
+            // Return BEFORE any filesystem side effect. The config keeps its exact
+            // bytes, including both registrations, for a human to disambiguate.
+            return {
+                status: "skipped-duplicate-registration",
+                message: DUPLICATE_REGISTRATION_DETAIL,
+            };
+        }
+        doc = merge.document;
+    }
     await deps.mkdir(dirnameOf(path), { recursive: true });
     await deps.writeFile(path, JSON.stringify(doc, null, 2) + "\n");
     return { status: isCreate ? "created" : "direct-written", path };
@@ -202,6 +252,10 @@ function tomlBasicString(value) {
 function tomlStringArray(values) {
     return `[${values.map(tomlBasicString).join(", ")}]`;
 }
+/** Escape dynamic text before inserting it into a regular expression. */
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 /** Deterministic env-key order for the Codex table (matches the web snippet). */
 const CODEX_ENV_ORDER = [
     "BAPI_BASE_URL",
@@ -223,28 +277,56 @@ function orderedEnvKeys(env) {
  */
 export function renderCodexBridgeToml(entry) {
     const lines = [
-        "[mcp_servers.bridge-api]",
+        `[mcp_servers.${MCP_SERVER_NAME}]`,
         `command = ${tomlBasicString(entry.command)}`,
         `args = ${tomlStringArray(entry.args)}`,
         "",
-        "[mcp_servers.bridge-api.env]",
+        `[mcp_servers.${MCP_SERVER_NAME}.env]`,
     ];
     for (const key of orderedEnvKeys(entry.env)) {
         lines.push(`${key} = ${tomlBasicString(entry.env[key])}`);
     }
     return lines.join("\n") + "\n";
 }
-/** Whether a TOML document already declares a `[mcp_servers.bridge-api]` table. */
+/**
+ * One matcher per recognized registration name (BAPI-807), each matching the
+ * bare `[mcp_servers.<name>]` table or a dotted subtable such as
+ * `[mcp_servers.<name>.env]`, at line start (allowing leading horizontal
+ * whitespace).
+ *
+ * The name is escaped through the single {@link escapeRegExp} helper and the
+ * pattern is anchored at COMPLETE table-header boundaries — `]` must follow the
+ * name or a dotted segment. That is what keeps `[mcp_servers.bridge-api-extra]`
+ * (and `[mcp_servers.bridgex]`) from matching: without the anchor, `bridge`
+ * would be a prefix of both. `bridge-api` also contains a `-`, which is not a
+ * regex metacharacter, but escaping is applied uniformly rather than reasoned
+ * about per name.
+ */
+const BRIDGE_TABLE_PATTERNS = RECOGNIZED_SERVER_NAMES.map((name) => ({
+    name,
+    pattern: new RegExp(`^[ \\t]*\\[mcp_servers\\.${escapeRegExp(name)}(\\.[^\\]]*)?\\][ \\t]*$`, "m"),
+}));
+/** Every recognized Bridge table name declared in a TOML document, in canonical-first order. */
+export function codexBridgeTableNames(content) {
+    // Never reserialize — presence only.
+    return BRIDGE_TABLE_PATTERNS.filter(({ pattern }) => pattern.test(content)).map(({ name }) => name);
+}
+/** Whether a TOML document already declares any recognized Bridge table. */
 export function codexHasBridgeTable(content) {
-    // Match the bare table header or any dotted subtable header, at line start
-    // (allowing leading whitespace). Never reserialize — presence only.
-    return /^[ \t]*\[mcp_servers\.bridge-api(\.[^\]]*)?\][ \t]*$/m.test(content);
+    return codexBridgeTableNames(content).length > 0;
 }
 /**
  * Compute the safe Codex merge action. A missing document → canonical create; an
- * existing document without a Bridge table → append (existing bytes preserved,
- * minimal newline boundary); an existing Bridge table → decline (manual-required)
- * rather than reserialize.
+ * existing document without any recognized Bridge table → append (existing bytes
+ * preserved, minimal newline boundary); an existing Bridge table under EITHER
+ * recognized name → decline (manual-required) rather than reserialize.
+ *
+ * BAPI-807: declining on a legacy-only table is what stops this path from
+ * appending a canonical `[mcp_servers.bridge]` table beside an existing
+ * `[mcp_servers.bridge-api]` one — which would be a duplicate registration
+ * created by Bridge itself. Both table names present is reported distinctly, so
+ * a caller can say "you already have two" rather than the generic "your existing
+ * config could not be safely updated".
  */
 export function mergeCodexHostConfig(existing, entry) {
     if (existing.state === "missing") {
@@ -258,7 +340,13 @@ export function mergeCodexHostConfig(existing, entry) {
         ? existing.content
         : // "valid" JsonReadResult is not used for TOML; guard anyway.
             "";
-    if (codexHasBridgeTable(content)) {
+    const present = codexBridgeTableNames(content);
+    if (present.length > 1) {
+        return { action: "duplicate-registration", keys: present };
+    }
+    if (present.length === 1) {
+        // Canonical-only or legacy-only: an existing table is never reserialized,
+        // and never duplicated under the other name.
         return { action: "manual-required" };
     }
     const boundary = content.length === 0 || content.endsWith("\n") ? "\n" : "\n\n";
@@ -280,6 +368,13 @@ async function readTomlHostConfig(path, deps) {
 export async function writeCodexHostConfig(path, entry, deps) {
     const read = await readTomlHostConfig(path, deps);
     const merge = mergeCodexHostConfig(read, entry);
+    if (merge.action === "duplicate-registration") {
+        // Before mkdir/writeFile, exactly like the JSON path.
+        return {
+            status: "skipped-duplicate-registration",
+            message: DUPLICATE_REGISTRATION_DETAIL,
+        };
+    }
     if (merge.action === "manual-required") {
         return { status: "manual-required" };
     }
@@ -287,30 +382,51 @@ export async function writeCodexHostConfig(path, entry, deps) {
     await deps.writeFile(path, merge.content);
     return { status: merge.action === "create" ? "created" : "direct-written", path };
 }
-/** Inspect a JSON host config for a `bridge-api` entry (no env values read). */
+/**
+ * Inspect a JSON host config for a Bridge entry under EITHER recognized key
+ * (no env values read).
+ */
 export async function inspectJsonHostEntry(path, target, deps) {
     const read = await readJsonHostConfig(path, deps);
     if (read.state !== "valid")
-        return { present: false };
-    const root = read.value[target.topLevelKey];
-    if (!root || typeof root !== "object" || Array.isArray(root))
-        return { present: false };
-    const entry = root["bridge-api"];
-    if (!entry || typeof entry !== "object")
-        return { present: false };
+        return { present: false, registrationKey: null };
+    const root = read.value[hostAdapterForTarget(target).topLevelKey];
+    if (!root || typeof root !== "object" || Array.isArray(root)) {
+        return { present: false, registrationKey: null };
+    }
+    const resolution = resolveRegistrationKey(root);
+    if (resolution.state === "conflict") {
+        // Reported explicitly rather than resolved: `present: true` alone would let
+        // a vendor-first caller conclude "the entry landed" and move on.
+        return { present: true, registrationKey: null, duplicateRegistration: true };
+    }
+    if (resolution.state === "absent")
+        return { present: false, registrationKey: null };
+    const entry = root[resolution.key];
+    if (!entry || typeof entry !== "object") {
+        return { present: false, registrationKey: null };
+    }
     const args = entry.args;
     return {
         present: true,
+        registrationKey: resolution.key,
         args: Array.isArray(args) ? args.filter((a) => typeof a === "string") : undefined,
     };
 }
-/** Inspect a Codex TOML config for a `bridge-api` table (no env values read). */
+/**
+ * Inspect a Codex TOML config for a Bridge table under EITHER exact recognized
+ * table name (no env values read).
+ */
 export async function inspectTomlHostEntry(path, deps) {
     const read = await readTomlHostConfig(path, deps);
     if (read.state !== "text")
-        return { present: false };
-    if (!codexHasBridgeTable(read.content))
-        return { present: false };
+        return { present: false, registrationKey: null };
+    const names = codexBridgeTableNames(read.content);
+    if (names.length === 0)
+        return { present: false, registrationKey: null };
+    if (names.length > 1) {
+        return { present: true, registrationKey: null, duplicateRegistration: true };
+    }
     // Extract the args = [...] line from the main table for pin classification.
     const m = read.content.match(/^\s*args\s*=\s*\[(.*?)\]/m);
     let args;
@@ -320,18 +436,133 @@ export async function inspectTomlHostEntry(path, deps) {
             .map((s) => s.trim().replace(/^["']|["']$/g, ""))
             .filter((s) => s.length > 0);
     }
-    return { present: true, args };
+    return { present: true, registrationKey: names[0], args };
 }
-/** Inspect any target (format-aware) for a `bridge-api` entry. */
+/** Inspect any target (format-aware) for a recognized Bridge entry. */
 export async function inspectHostEntry(target, ctx, deps) {
     const path = resolveTargetAbsPath(target, ctx);
-    return target.format === "toml"
+    return hostAdapterForTarget(target).format === "toml"
         ? inspectTomlHostEntry(path, deps)
         : inspectJsonHostEntry(path, target, deps);
 }
 // ---------------------------------------------------------------------------
 // Vendor CLI invocation builders (argv-isolated; secret-bearing for some kinds)
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Bridge MCP profile-token inspection (BAPI-775)
+//
+// The READ-ONLY counterpart of `mergeBridgeApiProfileToken` (init.ts). That
+// helper is the only writer of `BRIDGE_MCP_PROFILE`, and it writes exactly three
+// project-local host configs. This inspector answers "did that write land?"
+// without repeating the write path and without ever surfacing configuration
+// content.
+//
+// SECRET DISCIPLINE: the result carries fixed repo-relative config paths, the
+// inspected token, and booleans — never the MCP entry, its `env` object, its
+// command/args, an API key, or any unrelated profile token. A caller cannot
+// reconstruct configuration content from what this returns.
+// ---------------------------------------------------------------------------
+/**
+ * The three project-local host configs `mergeBridgeApiProfileToken` writes.
+ *
+ * Deliberately NOT derived from {@link file:./mcp-host-targets.ts}: the merge
+ * path's surface is these three files and nothing else, so an inspector built
+ * from the wider registry would report on Codex/Copilot hosts the writer never
+ * touches — and a report implying those hosts gained the token would be wrong.
+ */
+export const BRIDGE_PROFILE_TOKEN_CONFIGS = [
+    { path: ".mcp.json", topLevelKey: "mcpServers" },
+    { path: ".vscode/mcp.json", topLevelKey: "servers" },
+    { path: ".cursor/mcp.json", topLevelKey: "mcpServers" },
+];
+/**
+ * Split a stored `BRIDGE_MCP_PROFILE` value into tokens exactly the way
+ * `mergeBridgeApiProfileToken` does — raw comma splitting with trimming, and
+ * deliberately NOT `resolveProfiles`, which force-injects the implicit `core`
+ * group the stored value never contains.
+ */
+function storedProfileTokens(value) {
+    if (typeof value !== "string")
+        return [];
+    return value
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+/** The `BRIDGE_MCP_PROFILE` tokens stored on one registration entry, if any. */
+function entryProfileTokens(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return null;
+    const env = entry.env;
+    const stored = env && typeof env === "object" && !Array.isArray(env)
+        ? env.BRIDGE_MCP_PROFILE
+        : undefined;
+    return storedProfileTokens(stored);
+}
+/**
+ * Inspect one supported host config for a Bridge entry carrying `token`.
+ *
+ * BAPI-807: the entry is looked up under EVERY recognized registration key, not
+ * the `bridge-api` literal alone. A fresh install writes `bridge`, so reading
+ * only the legacy key would report `no-bridge-entry` for every current install
+ * and send the operator to re-run the base install that already ran.
+ *
+ * A config carrying BOTH keys is read as one presence question, not resolved:
+ * this function only answers "does a Bridge entry here carry the token", and
+ * either entry carrying it makes that true. Choosing WHICH duplicate wins is a
+ * write-path decision, and the write path refuses it loudly
+ * (`DuplicateRegistrationError`) rather than guessing.
+ *
+ * Every failure mode is an explicit state rather than a thrown error: a missing
+ * file is the ordinary case (the writer never creates one), and a malformed or
+ * unreadable file is a diagnosable outcome the operator can act on. Neither may
+ * surface a filesystem message or JSON parser text.
+ */
+async function inspectOneProfileConfig(projectRoot, target, token, deps) {
+    const read = await readJsonHostConfig(joinPath(projectRoot, target.path), deps);
+    if (read.state === "missing")
+        return { path: target.path, state: "absent" };
+    if (read.state !== "valid")
+        return { path: target.path, state: "unreadable" };
+    const root = read.value[target.topLevelKey];
+    if (!root || typeof root !== "object" || Array.isArray(root)) {
+        return { path: target.path, state: "no-bridge-entry" };
+    }
+    const servers = root;
+    // Own properties only, for the same reason `resolveRegistrationKey` insists on
+    // it: a `bridge` inherited from a polluted prototype is not a registration.
+    const tokenSets = RECOGNIZED_SERVER_NAMES.filter((name) => Object.prototype.hasOwnProperty.call(servers, name))
+        .map((name) => entryProfileTokens(servers[name]))
+        .filter((tokens) => tokens !== null);
+    if (tokenSets.length === 0)
+        return { path: target.path, state: "no-bridge-entry" };
+    // Only a boolean derived from the token set escapes this function — the env
+    // object itself is read here and nowhere else.
+    return {
+        path: target.path,
+        state: tokenSets.some((tokens) => tokens.includes(token)) ? "token-present" : "token-absent",
+    };
+}
+/**
+ * Read-only inspection of a `BRIDGE_MCP_PROFILE` token across the three configs
+ * `mergeBridgeApiProfileToken` can write (BAPI-775).
+ *
+ * Performs NO write and creates NO file, mirroring the writer's own
+ * never-create rule. Never throws for the ordinary
+ * absent/malformed/unreadable cases.
+ */
+export async function inspectBridgeApiProfileToken(projectRoot, token, deps) {
+    const configs = [];
+    for (const target of BRIDGE_PROFILE_TOKEN_CONFIGS) {
+        configs.push(await inspectOneProfileConfig(projectRoot, target, token, deps));
+    }
+    return {
+        token,
+        configs,
+        tokenPresent: configs.some((c) => c.state === "token-present"),
+        bridgeEntryPresent: configs.some((c) => c.state === "token-present" || c.state === "token-absent"),
+    };
+}
 /**
  * Whether a vendor kind's secret-delivery contract is VERIFIED. Only verified
  * contracts are ever invoked; an uncertain contract falls back to a direct
@@ -363,11 +594,11 @@ function buildVendorInvocation(target, entry) {
         });
         return {
             bin: vendor.bin,
-            args: ["mcp", "add-json", "bridge-api", json, "--scope", "project"],
+            args: ["mcp", "add-json", MCP_SERVER_NAME, json, "--scope", "project"],
         };
     }
     if (vendor.kind === "copilot-add") {
-        // copilot mcp add bridge-api --tools "*" --env K=V ... -- <command> <args...>
+        // copilot mcp add <name> --tools "*" --env K=V ... -- <command> <args...>
         // Env pairs (incl BAPI_API_KEY) are secret-bearing argv.
         const envArgs = [];
         for (const [k, v] of Object.entries(entry.env)) {
@@ -378,7 +609,7 @@ function buildVendorInvocation(target, entry) {
             args: [
                 "mcp",
                 "add",
-                "bridge-api",
+                MCP_SERVER_NAME,
                 "--tools",
                 "*",
                 ...envArgs,
@@ -404,8 +635,11 @@ function outcome(target, status, detail) {
 /** Direct-write a single target (JSON or Codex TOML) and map to an outcome. */
 async function directWriteTarget(target, entry, deps) {
     const path = resolveTargetAbsPath(target, deps);
-    if (target.format === "toml") {
+    if (hostAdapterForTarget(target).format === "toml") {
         const res = await writeCodexHostConfig(path, entry, deps.fs);
+        if (res.status === "skipped-duplicate-registration") {
+            return outcome(target, "skipped-duplicate-registration", res.message);
+        }
         if (res.status === "manual-required") {
             return outcome(target, "manual-required", "existing config could not be safely updated");
         }
@@ -413,6 +647,9 @@ async function directWriteTarget(target, entry, deps) {
     }
     const adapted = adaptBridgeEntryForHostTarget(entry, target);
     const res = await writeJsonHostConfig(path, target, adapted, deps.fs);
+    if (res.status === "skipped-duplicate-registration") {
+        return outcome(target, "skipped-duplicate-registration", res.message);
+    }
     if (res.status === "skipped-invalid") {
         return outcome(target, "skipped-invalid", res.message);
     }
@@ -422,10 +659,23 @@ async function directWriteTarget(target, entry, deps) {
  * Provision a single host target, honoring its write strategy:
  *   - manual-instructions → `manual-required`
  *   - direct → JSON merge-write (or Codex safe write)
- *   - vendor-first → probe + invoke the verified vendor CLI, verify the entry
- *     landed, else fall back to a safe direct write. Any missing binary, spawn
- *     error, timeout, non-zero exit, or missing post-write entry triggers the
- *     fallback rather than a fatal error.
+ *   - vendor-first → inspect, then probe + invoke the verified vendor CLI,
+ *     verify the entry landed, else fall back to a safe direct write. Any
+ *     missing binary, spawn error, timeout, non-zero exit, or missing post-write
+ *     entry triggers the fallback rather than a fatal error.
+ *
+ * BAPI-807 adds a read-only inspection BEFORE the vendor process is reached, for
+ * two reasons the vendor CLIs cannot handle themselves:
+ *
+ *  - **Both keys present → refuse.** `claude mcp add-json bridge …` would write a
+ *    third state on top of an already-ambiguous config, and a spawn cannot be
+ *    undone. The refusal happens before any process is started.
+ *  - **Legacy-only → bypass the vendor add.** Every verified vendor contract
+ *    takes the registration NAME as an argument, and the only name Bridge may
+ *    pass for a fresh add is the canonical one — so invoking it against a
+ *    `bridge-api` config would create a second entry rather than update the
+ *    existing one. The safe direct-update path resolves the key and replaces the
+ *    legacy entry in place instead.
  */
 export async function provisionHostTarget(target, entry, deps) {
     if (target.writeStrategy === "manual-instructions") {
@@ -434,24 +684,38 @@ export async function provisionHostTarget(target, entry, deps) {
     if (target.writeStrategy === "direct") {
         return directWriteTarget(target, entry, deps);
     }
-    // vendor-first
-    const invocation = buildVendorInvocation(target, entry);
-    if (invocation) {
-        const available = await deps.vendor.probeBinary(invocation.bin, deps.env);
-        if (available) {
-            const result = await deps.vendor.invokeVendorAdd(invocation, deps.env);
-            if (result.ok) {
-                // Verify the entry actually landed before trusting the vendor CLI.
-                const inspected = await inspectHostEntry(target, deps, deps.fs);
-                if (inspected.present) {
-                    return outcome(target, "vendor-written");
+    // vendor-first — inspect first, so neither refusal nor legacy preservation
+    // depends on a vendor process having already run.
+    const preInspection = await inspectHostEntry(target, deps, deps.fs);
+    if (preInspection.duplicateRegistration) {
+        return outcome(target, "skipped-duplicate-registration", DUPLICATE_REGISTRATION_DETAIL);
+    }
+    const mustPreserveLegacy = preInspection.present &&
+        preInspection.registrationKey !== null &&
+        preInspection.registrationKey !== undefined &&
+        preInspection.registrationKey !== MCP_SERVER_NAME;
+    if (!mustPreserveLegacy) {
+        const invocation = buildVendorInvocation(target, entry);
+        if (invocation) {
+            const available = await deps.vendor.probeBinary(invocation.bin, deps.env);
+            if (available) {
+                const result = await deps.vendor.invokeVendorAdd(invocation, deps.env);
+                if (result.ok) {
+                    // Verify the entry actually landed before trusting the vendor CLI.
+                    const inspected = await inspectHostEntry(target, deps, deps.fs);
+                    if (inspected.duplicateRegistration) {
+                        return outcome(target, "skipped-duplicate-registration", DUPLICATE_REGISTRATION_DETAIL);
+                    }
+                    if (inspected.present) {
+                        return outcome(target, "vendor-written");
+                    }
                 }
             }
         }
     }
     // Fallback: safe direct write (covers unverified contracts like Codex, a
-    // missing/failed vendor binary, or a nominally-successful write that left no
-    // entry).
+    // missing/failed vendor binary, a nominally-successful write that left no
+    // entry, and the legacy-preservation bypass above).
     return directWriteTarget(target, entry, deps);
 }
 // ---------------------------------------------------------------------------
@@ -468,7 +732,7 @@ export function sanitizeProbeEnv(env) {
 }
 /** The launcher spec for the current version (pins are version-locked). */
 export function currentLauncherSpec() {
-    return `@bridge_gpt/mcp-server@${VERSION}`;
+    return `${MCP_PACKAGE_NAME}@${VERSION}`;
 }
 /** Bounded probe/invoke timeout (ms). */
 const VENDOR_PROCESS_TIMEOUT_MS = 8000;