@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/launcher-config-inspection.js

@@ -22,20 +22,16 @@
  * carries config bodies, `env` maps, credential values, or raw error text.
  */
 import path from "path";
-import { getProjectJsonTargets, hostAdapterForTarget } from "./mcp-host-targets.js";
-import { LEGACY_SERVER_NAMES, MCP_SERVER_NAME, MCP_PACKAGE_NAME, resolveRegistrationKey, } from "./mcp-identity.js";
+import { codexHome, isCodexHomeOverrideHonored } from "./codex-home.js";
+import { inspectCodexLauncher } from "./codex-launcher-pin.js";
+import { getProjectJsonTargets, hostAdapterForTarget, MCP_HOST_TARGETS, } from "./mcp-host-targets.js";
+import { LEGACY_SERVER_NAMES, MCP_SERVER_NAME, MCP_PACKAGE_NAME, resolveRegistrationKey, WORKTREE_SHIM_TOKEN, } from "./mcp-identity.js";
 /**
  * The npm package every Bridge launcher spec names. Retained as a compatibility
  * alias — `doctor.ts` still imports this name — assigned from the shared
  * constant so there is no duplicate package-name literal.
  */
 export const BRIDGE_PACKAGE_NAME = MCP_PACKAGE_NAME;
-/**
- * The subcommand token that marks a worktree shim registration. A shim points at
- * a sibling worktree's server rather than a published package, so no pin applies
- * and no rewrite is ever safe (BAPI-714 / worktree provisioning).
- */
-const WORKTREE_SHIM_TOKEN = "mcp-invoke";
 /**
  * Every project-local MCP config Bridge registers into. Exported so `doctor`,
  * `init`, and `upgrade` can no longer drift apart on which paths exist or which
@@ -155,6 +151,10 @@ const REASON_TEXT = {
     "malformed-version": "the launcher pin is not a valid MAJOR.MINOR.PATCH release",
     "pinned-ahead-of-target": "the launcher pin is newer than the target version and must not be downgraded",
     "duplicate-registration": DUPLICATE_REGISTRATION_GUIDANCE,
+    // BAPI-1445: Codex's global TOML is read by a conservative scanner that refuses
+    // anything it cannot interpret with confidence. The wording is fixed so no file
+    // content, argument, or environment value can ever reach a diagnostic.
+    unlocatable: "the Codex Bridge launcher cannot be located safely; resolve its configuration manually, then re-run the upgrade",
 };
 /** Render a reason code as sanitized prose. */
 export function describeLauncherReason(reason) {
@@ -351,31 +351,38 @@ async function inspectOne(target, options) {
             reason: "no-package-token",
         };
     }
-    const common = {
+    return {
         ...keyed,
         filePresent: true,
         bridgeEntryPresent: true,
         shape: "standard",
         spec: pin.spec,
+        ...classifyStandardPin(pin, targetVersion),
     };
+}
+/**
+ * Classify a parsed Bridge package token against the target version.
+ *
+ * Shared by the project JSON inspection and the global Codex inspection so a pin
+ * means the same thing wherever it was written. Order matters and is part of the
+ * contract: unpinned forms normalize, a non-exact specifier is refused, a
+ * non-release target is refused, a pin ahead of the target is never downgraded,
+ * and only then is the exact pin compared.
+ */
+function classifyStandardPin(pin, targetVersion) {
     // Bare and explicit `@latest` are the two forms an exact-pin policy normalizes
     // rather than rejects — both mean "whatever npx resolves", which is exactly the
     // non-determinism BAPI-429 pinned away from.
     if (pin.specifier === null || pin.specifier === "latest") {
-        return { ...common, action: "normalize-unpinned" };
+        return { action: "normalize-unpinned" };
     }
     if (!isExactVersion(pin.specifier)) {
-        return {
-            ...common,
-            action: "unsupported",
-            reason: classifyNonExactSpecifier(pin.specifier),
-        };
+        return { action: "unsupported", reason: classifyNonExactSpecifier(pin.specifier) };
     }
     const comparison = compareExactVersions(pin.specifier, targetVersion);
     if (comparison === null) {
         // The TARGET is not an exact release. Refuse rather than guess.
         return {
-            ...common,
             currentVersion: pin.specifier,
             action: "unsupported",
             reason: "malformed-version",
@@ -383,20 +390,18 @@ async function inspectOne(target, options) {
     }
     if (comparison > 0) {
         return {
-            ...common,
             currentVersion: pin.specifier,
             action: "ahead",
             reason: "pinned-ahead-of-target",
         };
     }
     return {
-        ...common,
         currentVersion: pin.specifier,
         action: comparison === 0 ? "already-current" : "repin",
     };
 }
 /** Classify why a non-exact specifier cannot be treated as a release pin. */
-function classifyNonExactSpecifier(specifier) {
+export function classifyNonExactSpecifier(specifier) {
     if (/^[\^~]|^[<>=]/.test(specifier) || specifier.includes(" - ") || specifier.includes("||")) {
         return "version-range";
     }
@@ -410,3 +415,163 @@ function classifyNonExactSpecifier(specifier) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Resolve Codex's global config location through {@link codexHome}.
+ *
+ * `$CODEX_HOME/config.toml` is shown only when an absolute override was actually
+ * honored — even if it happens to equal the default location — so a relative or
+ * blank override falls back to the default display exactly as `codexHome` falls
+ * back to the default path.
+ */
+export function resolveCodexConfigLocation(env, homedir) {
+    return {
+        filePath: path.join(codexHome(env, homedir), "config.toml"),
+        displayPath: isCodexHomeOverrideHonored(env)
+            ? "$CODEX_HOME/config.toml"
+            : MCP_HOST_TARGETS.codex.displayPath,
+    };
+}
+/**
+ * Inspect Codex's global Bridge launcher, read-only, with exactly one read.
+ *
+ * Only `ENOENT` is absence. Any other read failure is a blocking
+ * `file-unreadable`, and the exception text is discarded: it can carry an
+ * absolute path. After the scan, the launcher is classified with the same shared
+ * pin rules as the project JSON targets.
+ */
+export async function inspectGlobalLauncherConfigs(options) {
+    const { targetVersion } = options;
+    const { filePath, displayPath } = resolveCodexConfigLocation(options.env, options.homedir);
+    const base = {
+        hostId: "codex",
+        scope: "global",
+        displayPath,
+        targetVersion,
+        spec: null,
+        currentVersion: null,
+        registrationKey: null,
+        legacyRegistration: false,
+    };
+    let raw;
+    try {
+        raw = await options.readFile(filePath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            return {
+                ...base,
+                filePresent: false,
+                bridgeEntryPresent: false,
+                shape: "none",
+                action: "skip-inactive",
+            };
+        }
+        return {
+            ...base,
+            filePresent: true,
+            bridgeEntryPresent: false,
+            shape: "none",
+            action: "invalid",
+            reason: "file-unreadable",
+        };
+    }
+    const found = inspectCodexLauncher(raw);
+    switch (found.kind) {
+        case "none":
+            // A readable file with no Bridge declaration: the user never configured
+            // Bridge in Codex, so it is not a participant.
+            return {
+                ...base,
+                filePresent: true,
+                bridgeEntryPresent: false,
+                shape: "none",
+                action: "skip-inactive",
+            };
+        case "duplicate":
+            return {
+                ...base,
+                filePresent: true,
+                bridgeEntryPresent: true,
+                shape: "custom",
+                action: "duplicate-registration",
+                reason: "duplicate-registration",
+            };
+        case "unlocatable":
+            return {
+                ...base,
+                filePresent: true,
+                bridgeEntryPresent: true,
+                shape: "custom",
+                action: "invalid",
+                reason: "unlocatable",
+            };
+        case "worktree-shim":
+            return {
+                ...base,
+                filePresent: true,
+                bridgeEntryPresent: true,
+                registrationKey: found.registrationName,
+                legacyRegistration: found.registrationName !== MCP_SERVER_NAME,
+                shape: "worktree-shim",
+                action: "skip-worktree-shim",
+            };
+        case "located": {
+            const keyed = {
+                ...base,
+                filePresent: true,
+                bridgeEntryPresent: true,
+                registrationKey: found.registrationName,
+                legacyRegistration: found.registrationName !== MCP_SERVER_NAME,
+            };
+            // Same order as the JSON targets: shim first (the parser already routed
+            // shims above), then the package token, then the shared pin rules.
+            const pin = parseLauncherPin(found.args);
+            if (!pin) {
+                return { ...keyed, shape: "custom", action: "invalid", reason: "unlocatable" };
+            }
+            const classified = classifyStandardPin(pin, targetVersion);
+            return {
+                ...keyed,
+                shape: "standard",
+                spec: pin.spec,
+                ...classified,
+                action: classified.action,
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Effective Claude Code pin (BAPI-1446)
+// ---------------------------------------------------------------------------
+/**
+ * The exact release the project's Claude Code launcher is pinned to, or null.
+ *
+ * Install uses this to pin the SessionStart upgrade-notice hook to the same build
+ * the project's MCP config launches. It answers null — never a guess from the
+ * running process, and never `@latest` — when the config is absent, unreadable,
+ * a worktree shim, a custom launcher, ambiguous (both registration keys), or
+ * pinned to anything other than one exact `MAJOR.MINOR.PATCH`. Read-only.
+ */
+export async function discoverClaudeCodeEffectivePin(options) {
+    try {
+        const relPath = MCP_HOST_TARGETS["claude-code"].relPath;
+        const target = relPath ? launcherTargetFor(relPath) : undefined;
+        if (!target)
+            return null;
+        const [found] = await inspectLauncherConfigs({
+            cwd: options.cwd,
+            targetVersion: options.targetVersion,
+            readFile: options.readFile,
+            targets: [target],
+        });
+        if (!found || found.shape !== "standard" || !found.bridgeEntryPresent)
+            return null;
+        if (isPrerequisiteFailure(found))
+            return null;
+        return isExactVersion(found.currentVersion) ? found.currentVersion : null;
+    }
+    catch {
+        return null;
+    }
+}

package/build/mcp-host-targets.js

@@ -77,6 +77,7 @@ export const MCP_HOST_TARGETS = {
         launchAgent: "claude",
         capabilities: { mcpConfiguration: true, customCommands: true, worktreeProvisioning: true, sessionSpawning: true },
         writeStrategy: "vendor-first",
+        reloadHint: "run /mcp or restart Claude Code",
         // Claude Code is always a candidate default.
         detect: () => true,
     },
@@ -90,6 +91,7 @@ export const MCP_HOST_TARGETS = {
         launchAgent: "cursor-agent",
         capabilities: { mcpConfiguration: true, customCommands: true, worktreeProvisioning: true, sessionSpawning: true },
         writeStrategy: "direct",
+        reloadHint: "toggle bridge off and on in Cursor Settings → MCP, or reload the window",
         detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".cursor")) ||
             typeof ctx.env.CURSOR_TRACE_DIR === "string" &&
                 ctx.env.CURSOR_TRACE_DIR.length > 0,
@@ -103,6 +105,7 @@ export const MCP_HOST_TARGETS = {
         hostKind: "vscode-json",
         capabilities: { mcpConfiguration: true, customCommands: true, worktreeProvisioning: false, sessionSpawning: false },
         writeStrategy: "direct",
+        reloadHint: "restart the bridge server (MCP: List Servers)",
         detect: (ctx) => ctx.exists(joinPath(ctx.cwd, ".vscode")),
     },
     codex: {
@@ -119,6 +122,7 @@ export const MCP_HOST_TARGETS = {
         // registration remains the ordinary interactive default.
         capabilities: { mcpConfiguration: true, customCommands: true, worktreeProvisioning: true, sessionSpawning: true },
         writeStrategy: "vendor-first",
+        reloadHint: "restart Codex",
         detect: (ctx) => ctx.exists(joinPath(ctx.homedir, ".codex")),
     },
     windsurf: {

package/build/mcp-identity.js

@@ -18,6 +18,13 @@
 export const MCP_SERVER_NAME = "bridge";
 /** The current published npm package name for the MCP server. */
 export const MCP_PACKAGE_NAME = "@bridge_gpt/mcp-server";
+/**
+ * The subcommand token that marks a worktree shim registration. A shim points at
+ * a sibling worktree's server rather than a published package, so no pin applies
+ * and no rewrite is ever safe (BAPI-714 / worktree provisioning). Shared by the
+ * JSON launcher inspection and the pure Codex TOML parser (BAPI-1445).
+ */
+export const WORKTREE_SHIM_TOKEN = "mcp-invoke";
 /** The README resource URI served by the MCP server. */
 export const MCP_README_URI = `${MCP_SERVER_NAME}://readme`;
 /**

package/build/mcp-install-state.js

@@ -16,6 +16,7 @@
  * All filesystem access is through injected dependencies so the module is fully
  * unit-testable with in-memory fakes.
  */
+import { validPackagedAssetInventory } from "./generated-assets-context.js";
 import { executorIdFromLaunchdFilename, executorIdFromSystemdFilename, } from "./executor/service-unit.js";
 import { HOST_PLATFORM_ORDER, isHostPlatformId, } from "./mcp-host-targets.js";
 /** Current on-disk schema version. */
@@ -217,8 +218,7 @@ export async function readMcpInstallState(cwd, deps) {
     catch (err) {
         if (isEnoent(err))
             return { status: "missing" };
-        // A non-ENOENT read error is treated as missing state, not a crash.
-        return { status: "missing" };
+        return { status: "unreadable" };
     }
     let parsed;
     try {
@@ -271,6 +271,9 @@ export async function readMcpInstallState(cwd, deps) {
         status: "valid",
         state: {
             version: MCP_INSTALL_STATE_VERSION,
+            ...(doc.packagedAssets === undefined ? {} : validPackagedAssetInventory(doc.packagedAssets)
+                ? { packagedAssets: doc.packagedAssets }
+                : { packagedAssetsStatus: (doc.packagedAssets && typeof doc.packagedAssets === "object" && doc.packagedAssets.version !== 1 ? "unsupported" : "invalid") }),
             selectedPlatforms: normalizePlatforms(rawPlatforms),
             projectConfigPaths: normalizeProjectPaths(projectConfigPaths),
             // Entries that are not generated-unit locators are DROPPED rather than
@@ -291,6 +294,7 @@ export function serializeMcpInstallState(state) {
     // Explicit key order — do not rely on object insertion order for stability.
     const ordered = {
         version: state.version,
+        ...(state.packagedAssets ? { packagedAssets: cleanAssetInventory(state.packagedAssets) } : {}),
         selectedPlatforms: state.selectedPlatforms,
         projectConfigPaths: state.projectConfigPaths,
         // Re-normalized at serialization time, not trusted from the input object:
@@ -315,10 +319,13 @@ export function serializeMcpInstallState(state) {
  */
 export async function writeMcpInstallState(cwd, input, deps) {
     const existing = await readMcpInstallState(cwd, deps);
+    if (!canPreserveAssetInventory(existing))
+        return { ok: false, error: "Existing installation state cannot be safely preserved." };
     const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
     const priorCapabilities = existing.status === "valid" ? (existing.state.capabilities ?? []) : [];
     const state = {
         version: MCP_INSTALL_STATE_VERSION,
+        ...(existing.status === "valid" && existing.state.packagedAssets ? { packagedAssets: existing.state.packagedAssets } : {}),
         selectedPlatforms: normalizePlatforms(input.selectedPlatforms),
         projectConfigPaths: normalizeProjectPaths(input.projectConfigPaths),
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths([
@@ -330,6 +337,11 @@ export async function writeMcpInstallState(cwd, input, deps) {
         // them (BAPI-775).
         capabilities: normalizeCapabilities(priorCapabilities),
     };
+    if (input.packagedAssets) {
+        if (!validPackagedAssetInventory(input.packagedAssets))
+            return { ok: false, error: "Invalid packaged-asset inventory." };
+        state.packagedAssets = cleanAssetInventory(input.packagedAssets);
+    }
     const finalPath = installStatePath(cwd);
     return persistMcpInstallState(cwd, state, finalPath, deps);
 }
@@ -351,8 +363,7 @@ async function persistMcpInstallState(cwd, state, finalPath, deps) {
                 // Best-effort cleanup only; ignore secondary failures.
             }
         }
-        const message = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: `failed to persist install state: ${message}` };
+        return { ok: false, error: "failed to persist install state" };
     }
     return { ok: true, path: finalPath, state };
 }
@@ -379,11 +390,14 @@ export async function recordInstalledProjectArtifact(cwd, relPath, deps) {
         };
     }
     const existing = await readMcpInstallState(cwd, deps);
+    if (!canPreserveAssetInventory(existing))
+        return { ok: false, error: "Existing installation state cannot be safely preserved." };
     const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];
     const priorPaths = existing.status === "valid" ? existing.state.projectConfigPaths : [];
     const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
     const state = {
         version: MCP_INSTALL_STATE_VERSION,
+        ...(existing.status === "valid" && existing.state.packagedAssets ? { packagedAssets: existing.state.packagedAssets } : {}),
         selectedPlatforms: normalizePlatforms(priorPlatforms),
         projectConfigPaths: normalizeProjectPaths([...priorPaths, relPath]),
         // Preserved, not rebuilt: recording a workflow file must not drop the
@@ -417,11 +431,14 @@ export async function recordInstalledExecutorServiceUnit(cwd, unitPath, homeDir,
         };
     }
     const existing = await readMcpInstallState(cwd, deps);
+    if (!canPreserveAssetInventory(existing))
+        return { ok: false, error: "Existing installation state cannot be safely preserved." };
     const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];
     const priorPaths = existing.status === "valid" ? existing.state.projectConfigPaths : [];
     const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
     const state = {
         version: MCP_INSTALL_STATE_VERSION,
+        ...(existing.status === "valid" && existing.state.packagedAssets ? { packagedAssets: existing.state.packagedAssets } : {}),
         selectedPlatforms: normalizePlatforms(priorPlatforms),
         projectConfigPaths: normalizeProjectPaths(priorPaths),
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths([...priorUnitPaths, locator]),
@@ -453,12 +470,15 @@ export async function recordInstalledConductorCapability(cwd, capability, deps)
         };
     }
     const existing = await readMcpInstallState(cwd, deps);
+    if (!canPreserveAssetInventory(existing))
+        return { ok: false, error: "Existing installation state cannot be safely preserved." };
     const priorPlatforms = existing.status === "valid" ? existing.state.selectedPlatforms : [];
     const priorPaths = existing.status === "valid" ? existing.state.projectConfigPaths : [];
     const priorUnitPaths = existing.status === "valid" ? existing.state.executorServiceUnitPaths : [];
     const priorCapabilities = existing.status === "valid" ? (existing.state.capabilities ?? []) : [];
     const state = {
         version: MCP_INSTALL_STATE_VERSION,
+        ...(existing.status === "valid" && existing.state.packagedAssets ? { packagedAssets: existing.state.packagedAssets } : {}),
         selectedPlatforms: normalizePlatforms(priorPlatforms),
         projectConfigPaths: normalizeProjectPaths(priorPaths),
         executorServiceUnitPaths: normalizeExecutorServiceUnitPaths(priorUnitPaths),
@@ -466,3 +486,29 @@ export async function recordInstalledConductorCapability(cwd, capability, deps)
     };
     return persistMcpInstallState(cwd, state, installStatePath(cwd), deps);
 }
+function canPreserveAssetInventory(existing) {
+    return existing.status === "missing" || (existing.status === "valid" && !existing.state.packagedAssetsStatus);
+}
+function cleanAssetInventory(inventory) {
+    if (!validPackagedAssetInventory(inventory))
+        throw new Error("Invalid packaged-asset inventory.");
+    return { version: 1, packageVersion: inventory.packageVersion, rootBinding: inventory.rootBinding,
+        assets: inventory.assets.map(a => ({ id: a.id, destination: a.destination, host: a.host })) };
+}
+export async function recordPackagedAssetInventory(cwd, inventory, deps) {
+    if (!validPackagedAssetInventory(inventory))
+        return { ok: false, error: "Invalid packaged-asset inventory." };
+    const prior = await readMcpInstallState(cwd, deps);
+    if (!canPreserveAssetInventory(prior))
+        return { ok: false, error: "Existing installation state cannot be safely preserved." };
+    const state = prior.status === "valid" ? prior.state : undefined;
+    const records = new Map();
+    if (state?.packagedAssets?.rootBinding === inventory.rootBinding) {
+        for (const a of state.packagedAssets.assets)
+            records.set(`${a.host}:${a.id}`, a);
+    }
+    for (const a of inventory.assets)
+        records.set(`${a.host}:${a.id}`, a);
+    return writeMcpInstallState(cwd, { selectedPlatforms: state?.selectedPlatforms ?? [],
+        projectConfigPaths: state?.projectConfigPaths ?? [], packagedAssets: { ...inventory, assets: [...records.values()] } }, deps);
+}

package/build/merge-workflow-install.js

@@ -43,6 +43,7 @@
  * remediation sentence, because subprocess text is unbounded and can carry a
  * remote URL with an embedded token.
  */
+import { resolve } from "node:path";
 import { MERGE_WORKFLOW_EXPECTED_VERSION, MERGE_WORKFLOW_PATH, } from "./conductor/merge-execution-contract.js";
 import { MERGE_WORKFLOW_API_KEY_SECRET_NAME, } from "./merge-workflow-config.js";
 import { MERGE_WORKFLOW_CLASSIFICATION_TEXT, classifyMergeWorkflowContent, } from "./merge-workflow-drift.js";
@@ -247,10 +248,8 @@ export async function runMergeWorkflowPreflight(deps, options) {
     if (!repositoryRoot)
         return { ok: false, result: fail("not_repository_root") };
     const normalizedCwd = deps.cwd.endsWith("/") ? deps.cwd.slice(0, -1) : deps.cwd;
-    const normalizedRoot = repositoryRoot.endsWith("/")
-        ? repositoryRoot.slice(0, -1)
-        : repositoryRoot;
-    if (normalizedRoot !== normalizedCwd) {
+    const normalizedRoot = repositoryRoot.endsWith("/") ? repositoryRoot.slice(0, -1) : repositoryRoot;
+    if (resolve(normalizedRoot) !== resolve(normalizedCwd)) {
         return { ok: false, result: fail("not_repository_root") };
     }
     deps.log(`  repository root: ${normalizedRoot}`);

package/build/pipeline-utils.js

@@ -178,7 +178,7 @@ export const UPGRADE_ADVICE_SURFACING_INSTRUCTIONS = " Upgrade advice: when any
 export function resolveRecipe(pipeline, instructions, variables, skipSteps, autoApprove, options) {
     // Validate required variables are provided
     const declared = pipeline.variables ?? [];
-    const missing = declared.filter((v) => !(v in variables));
+    const missing = declared.filter((v) => v !== "verification_scope" && !(v in variables));
     if (missing.length > 0) {
         throw new Error(`Missing required variable(s): ${missing.join(", ")}. ` +
             `Pipeline "${pipeline.name}" declares: [${declared.join(", ")}].`);
@@ -189,7 +189,11 @@ export function resolveRecipe(pipeline, instructions, variables, skipSteps, auto
     // `execution_mode` must not be able to make a phase believe an orchestrator is
     // watching when none is.
     const executionMode = options?.executionMode ?? "inline";
-    variables = { ...variables, [EXECUTION_MODE_VARIABLE]: executionMode };
+    variables = {
+        ...variables,
+        verification_scope: variables.verification_scope === "targeted" ? "targeted" : "full",
+        [EXECUTION_MODE_VARIABLE]: executionMode,
+    };
     // Filter and resolve steps
     const resolvedSteps = [];
     let stepIndex = 1;