@minhspark/codex-mcp-bridge 1.26.7 → 1.26.9

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.26.7",
+  "version": "1.26.9",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,47 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.26.9] - 2026-11-03
+
+### Fixed
+
+- Shorten the "Applying managed settings" step of `npx @minhspark/codex-mcp-bridge@latest`. Each Codex `mcp` command takes several seconds to start on a machine with many MCP servers and plugins, and one update ran about sixteen of them. The Codex installers now read their own entry with one `codex mcp get` instead of listing every server first, the verification reads all three registrations from a single `codex mcp list`, and the updater no longer runs a second, separate verification process after setup has already verified the saved settings.
+- Show which component the updater is configuring while managed settings are applied, instead of a single line that looked frozen for a minute or more.
+- Stop reporting `MCP registration is missing` for `claude-bridge`, `codex-native-relay` and `antigravity-bridge` when Codex CLI was merely too slow to answer. A slow inventory now says so, and the three registrations are reported as not checked. Codex `mcp` commands used by setup may take up to 120 seconds instead of 30, so a busy computer no longer fails an otherwise complete update.
+
+### Verification
+
+- Regression coverage checks that verification makes exactly one Codex inventory call, that only Codex's own "No MCP server named" error counts as an absent entry, that a timed-out inventory is reported as unchecked, and that the updater runs setup once and relays only its progress lines.
+
+### Upgrade
+
+```powershell
+npx.cmd -y @minhspark/codex-mcp-bridge@latest
+```
+
+This command runs the 1.26.9 updater itself, so the shorter sequence applies to this update.
+
+## [1.26.8] - 2026-11-03
+
+### Fixed
+
+- Discover Claude Desktop's migrated Windows MSIX data under `%LOCALAPPDATA%\Claude-Data\claude_*`. Ignore old roots containing only migration markers, including an alias to a discovered retired root, without deleting data or guessing between active profiles. Explicit data-root overrides remain authoritative.
+- Retarget verified older bridge source registrations during managed setup, including renamed checkouts, while preserving custom environment values, project restrictions and disabled settings. Changed configuration files receive unique backups, including repeated Desktop migrations on the same day. Custom launchers, extra arguments, unrelated packages and unavailable old source remain protected and receive specific recovery guidance.
+- Restore a missing Antigravity sidecar definition when only its ordinary enable/disable registration remains. Preserve a deliberately disabled sidecar and refuse custom orphan settings.
+- Include the failed setup components and safe recovery guidance in updater errors instead of reporting only `EXIT_1`. Detailed local setup failures remain available through `codex-bridge-setup --check --json`; raw child output and private configuration are excluded from the updater summary.
+
+### Verification
+
+- Regression coverage includes migrated MSIX roots, retired aliases, multiple profiles, verified legacy entrypoints, exact configuration backups, concurrent configuration changes, disabled sidecars and bounded error summaries. Native delivery on the reporter's Windows 11 / Claude Desktop 4.4212 environment has not been exercised.
+
+### Upgrade
+
+```powershell
+npx.cmd -y @minhspark/codex-mcp-bridge@latest
+```
+
+After active work finishes, reconnect the affected MCP clients or restart their host apps so existing direct processes load the updated registrations.
+
 ## [1.26.7] - 2026-11-03
 
 ### Fixed

package/docs/new-windows-setup.md

@@ -114,6 +114,57 @@ incomplete.
 has no bridge tools, inspect and reconnect `codex-bridge` using `/mcp` before
 attempting delivery.
 
+### Claude Desktop MSIX data migration
+
+Discovery includes `%LOCALAPPDATA%\Claude-Data\claude_*` as well as
+`%APPDATA%\Claude` and the older
+`%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude` layout.
+Directories containing only regular `.user-data-left*` migration markers are
+ignored. An old directory link is ignored only when it points to another
+discovered marker-only directory. A marker beside real data does not make that
+data disposable, and setup never deletes these directories.
+
+If multiple directories still contain account data, setup refuses to guess.
+Select the actual directory used by the signed-in app for that invocation:
+
+```powershell
+$env:CLAUDE_DESKTOP_USER_DATA = 'C:\Users\YourUser\AppData\Local\Claude-Data\claude_YourPackageId'
+codex-bridge-setup.cmd --check --json
+```
+
+Replace the example with the existing directory; do not create an empty
+directory to bypass discovery. Explicit data-root and config-file overrides
+remain authoritative. Configuration discovery without account state does not
+establish a signed-in account or prove native delivery readiness.
+
+### Older source registrations and incomplete setup
+
+Managed setup can retarget a recognized older source installation, including a
+renamed checkout. Another installation must have the bridge's exact package
+identity and regular source files, with supported Node arguments. Custom
+launchers, extra arguments, unrelated packages and missing old source cannot
+be adopted automatically. Inspect the named registration before replacing its
+`command` and `args`; preserve its environment, project restrictions and
+disabled settings. Existing changed configuration files receive backups.
+
+If only Antigravity's `sidecars["codex-bridge"]` setting remains after its
+`sidecar.json` was removed, setup restores the definition when that setting is
+empty or contains only a boolean `enabled`. A saved `false` stays disabled.
+Custom residual settings still require inspection; deleting `sidecar.json`
+alone does not remove the registration in `.gemini\config\config.json`.
+
+The updater names recognized failed components and provides static recovery
+guidance. For the detailed local report, run:
+
+```powershell
+codex-bridge-setup.cmd --json
+```
+
+This command applies setup again; `--check --json` only inspects it. Review and
+redact local details before sharing them. After a successful migration, let
+active work finish and reconnect the affected MCP clients so direct processes
+load the new registration. A saved configuration change does not restart them.
+
 Local `npm install` and `npm ci` do not configure apps. For a deliberate
 package-only installation, a direct global npm install can use
 `CODEX_BRIDGE_SKIP_SETUP=1` or `--ignore-scripts`. This differs from the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.26.7",
+  "version": "1.26.9",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.26.7",
+  "version": "1.26.9",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-antigravity-bridge.mjs

@@ -3,8 +3,10 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
-import { isMainModule, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
+import { randomUUID } from "node:crypto";
+import { applyStdioMcpRegistration, CODEX_MCP_TIMEOUT_MS, readCodexMcpServer, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { bridgeEntrypointConflict, isBridgeSource, isMainModule, isNodeLauncher, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
+import { backupRegularConfigFile } from "../src/project-policy.mjs";
 import { homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
@@ -60,27 +62,25 @@ export function validateCodexExecutable(executable, { platform = process.platfor
   return resolved;
 }
 
-function ownEntry(entry, expected, label, retarget = false, supervised = false) {
+function ownEntry(entry, expected, label, retarget = false, supervised = false, node = stableNodeBin()) {
   if (entry === undefined || entry === null) return;
   object(entry, label);
   const script = entry.args?.[0];
   const managed = supervised && Array.isArray(entry.args) && entry.args.length === 2
     && typeof script === "string" && path.basename(script) === "mcp-supervisor.mjs" && entry.args[1] === path.basename(expected);
+  const commandArgs = supervised ? [path.join(path.dirname(expected), "mcp-supervisor.mjs"), path.basename(expected)] : [expected];
+  const conflict = detail => bridgeEntrypointConflict(label, node, commandArgs, detail);
   if (!Array.isArray(entry.args) || !managed && entry.args.length !== 1 || typeof script !== "string") {
-    throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
+    throw conflict("a different entrypoint");
   }
   const target = managed ? path.join(path.dirname(expected), "mcp-supervisor.mjs") : expected;
-  if (path.resolve(script) === path.resolve(target) && !managed) return;
-  const source = path.dirname(script);
-  if (!path.isAbsolute(script) || script.includes("\0") || path.resolve(script) !== path.resolve(target)
-    && (!retarget || path.basename(script) !== path.basename(target)
-      || path.basename(source) !== "src" || path.basename(path.dirname(source)).toLowerCase() !== "codex-mcp-bridge")) {
-    throw new Error(`${label} is already configured with a different entrypoint; it was not changed`);
+  const current = path.isAbsolute(script) && path.relative(target, script) === "";
+  if (!current && (!retarget || path.basename(script) !== path.basename(target)
+    || !isBridgeSource(script, [], [path.basename(expected)])) || script.includes("\0")) {
+    throw conflict("a different entrypoint");
   }
-  const command = entry.command;
-  if (typeof command !== "string" || command.includes("\0") || !/^(?:node|node\.exe)$/i.test(path.basename(command))
-    || !path.isAbsolute(command) && command !== path.basename(command)) {
-    throw new Error(`${label} is already configured with a different launcher; it was not changed`);
+  if (!isNodeLauncher(entry.command)) {
+    throw conflict("a different launcher");
   }
 }
 
@@ -105,7 +105,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
   let codex = null;
   if (targets.includes("codex")) {
     if (codexExisting && codexExisting.transport?.type !== "stdio") throw new Error("The existing Antigravity MCP transport is not stdio");
-    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget, true);
+    ownEntry(codexExisting?.transport, entry, "Codex Antigravity bridge", retarget, true, node);
     const existingCaller = codexExisting?.transport?.env?.ANTIGRAVITY_BRIDGE_CALLER;
     if (existingCaller !== undefined && existingCaller !== "codex") throw new Error("The existing Codex bridge has a conflicting caller identity");
     codex = remove ? { remove: Boolean(codexExisting) } : stdioMcpRegistration({ name: NAME, existing: codexExisting, node, entry: supervisorEntry, entryArgs: [path.basename(entry)], envOverrides: { ANTIGRAVITY_BRIDGE_CALLER: "codex" } });
@@ -116,7 +116,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const value = structuredClone(original.value);
     if (value.mcpServers !== undefined) object(value.mcpServers, "Claude mcpServers");
     const existing = value.mcpServers?.[NAME];
-    ownEntry(existing, entry, "Claude Antigravity bridge", retarget, true);
+    ownEntry(existing, entry, "Claude Antigravity bridge", retarget, true, node);
     if (existing?.type !== undefined && existing.type !== "stdio") throw new Error("The existing Claude bridge transport is not stdio");
     if (existing?.env !== undefined) object(existing.env, "Claude bridge environment");
     if (existing?.env?.ANTIGRAVITY_BRIDGE_CALLER !== undefined && existing.env.ANTIGRAVITY_BRIDGE_CALLER !== "claude") throw new Error("The existing Claude bridge has a conflicting caller identity");
@@ -135,7 +135,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const mcp = structuredClone(originalMcp.value);
     if (mcp.mcpServers !== undefined) object(mcp.mcpServers, "Antigravity mcpServers");
     const outbound = mcp.mcpServers?.[OUTBOUND];
-    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget, true);
+    ownEntry(outbound, outboundEntry, "Antigravity outbound bridge", retarget, true, node);
     if (outbound?.type !== undefined && outbound.type !== "stdio" || outbound?.url !== undefined || outbound?.serverUrl !== undefined || outbound?.httpUrl !== undefined) throw new Error("The existing Antigravity outbound bridge transport is not stdio");
     if (outbound?.env !== undefined) object(outbound.env, "Antigravity outbound bridge environment");
     if (Object.keys(outbound?.env ?? {}).some((name) => /^(?:CLAUDE|CODEX_|ANTIGRAVITY_BRIDGE_CALLER$)/i.test(name))) throw new Error("The existing Antigravity outbound bridge contains a foreign caller environment; review it before installation");
@@ -151,12 +151,17 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const mcpEdit = changed(originalMcp, mcp);
     if (mcpEdit) edits.push(mcpEdit);
     const originalSidecar = snapshot(path.join(configRoot, "sidecars", SIDECAR, "sidecar.json"));
-    if (originalSidecar.text !== null) ownEntry(originalSidecar.value, sidecarEntry, "Antigravity sidecar", retarget);
+    if (originalSidecar.text !== null) ownEntry(originalSidecar.value, sidecarEntry, "Antigravity sidecar", retarget, false, node);
     const originalConfig = snapshot(path.join(configRoot, "config.json"));
     const config = structuredClone(originalConfig.value);
     if (config.sidecars !== undefined) object(config.sidecars, "Antigravity sidecars");
     if (config.sidecars?.[SIDECAR] !== undefined) object(config.sidecars[SIDECAR], "Antigravity bridge sidecar settings");
-    if (originalSidecar.text === null && config.sidecars?.[SIDECAR] !== undefined) throw new Error("An Antigravity sidecar with this name exists without a matching bridge definition");
+    if (originalSidecar.text === null && config.sidecars?.[SIDECAR] !== undefined) {
+      const settings = config.sidecars[SIDECAR];
+      const plain = Object.keys(settings).every(key => key === "enabled") && (settings.enabled === undefined || typeof settings.enabled === "boolean");
+      if (!setup || remove || !plain) throw new Error('SETUP_SIDECAR_DEFINITION_MISSING: Antigravity config.json still contains sidecars["codex-bridge"] without sidecar.json. Restore the previous bridge definition, or back up config.json and remove only the stale sidecars["codex-bridge"] entry before rerunning setup.');
+      notices.push("Restored the missing bridge sidecar definition and preserved its saved enabled preference.");
+    }
     let definition = null;
     if (remove) { if (config.sidecars) delete config.sidecars[SIDECAR]; }
     else {
@@ -202,8 +207,11 @@ function assertCurrent(edit) {
 export function applyJsonEdits(edits) {
   for (const edit of edits) assertCurrent(edit);
   const completed = [];
+  const suffix = randomUUID();
   try {
     for (const edit of edits) {
+      assertCurrent(edit);
+      if (edit.text !== null) backupRegularConfigFile(edit.file, `${edit.file}.backup-${suffix}`, edit.text, 16 * 1024 * 1024);
       assertCurrent(edit);
       if (edit.next === null) fs.unlinkSync(edit.file);
       else {
@@ -248,10 +256,8 @@ export function runAntigravityInstaller(args = process.argv.slice(2), { prepareR
   let codexExisting = null;
   if (options.targets.includes("codex")) {
     const codexBin = validateCodexExecutable(resolveCodexBin(process.env.CODEX_EXE));
-    run = (command) => execFileSync(codexBin, command, { encoding: "utf8", env: spawnEnv(), windowsHide: true, shell: false, timeout: 30000, stdio: "pipe" });
-    const inventory = JSON.parse(run(["mcp", "list", "--json"]));
-    if (!Array.isArray(inventory)) throw new Error("Codex returned an invalid MCP inventory");
-    if (inventory.some((item) => item.name === NAME)) codexExisting = JSON.parse(run(["mcp", "get", NAME, "--json"]));
+    run = (command) => execFileSync(codexBin, command, { encoding: "utf8", env: spawnEnv(), windowsHide: true, shell: false, timeout: CODEX_MCP_TIMEOUT_MS, stdio: "pipe" });
+    codexExisting = readCodexMcpServer(run, NAME);
   }
   const plan = planAntigravityInstallation({ ...options, home, root, node, codexExisting });
   if (!options.remove) {

package/scripts/install-claude-desktop.mjs

@@ -10,12 +10,12 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
-import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
+import { bridgeEntrypointConflict, isBridgeSource, isNodeLauncher, stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
-const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
+const cfgPath = path.resolve(process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath());
 const entryOption = process.argv.indexOf("--entry-name");
 const requestedEntryName = entryOption < 0 ? undefined : process.argv[entryOption + 1];
 if (entryOption >= 0 && !["codex-bridge", "codex-bridge-desktop"].includes(requestedEntryName)) throw new Error("--entry-name must be codex-bridge or codex-bridge-desktop");
@@ -113,14 +113,12 @@ const entryName = requestedEntryName ?? bridgeEntries[0] ?? "codex-bridge";
 if ((requestedEntryName || setup) && cfg.mcpServers[entryName] !== undefined) {
   const existing = cfg.mcpServers[entryName];
   const script = existing?.args?.[0];
-  const source = typeof script === "string" && path.isAbsolute(script) ? path.dirname(script) : null;
-  const ownedSource = source && (sourceDirectories.has(source)
-    || path.basename(source) === "src" && path.basename(path.dirname(source)).toLowerCase() === "codex-mcp-bridge");
+  const ownedSource = isBridgeSource(script, sourceDirectories, ["index.mjs"]);
   const supervised = existing?.args?.length === 2 && path.basename(script ?? "") === "mcp-supervisor.mjs" && existing.args[1] === "index.mjs";
   const direct = existing?.args?.length === 1 && ["index.mjs", "codex-bridge-launcher.mjs"].includes(path.basename(script ?? ""));
-  if (!existing || typeof existing !== "object" || Array.isArray(existing) || !ownedSource || !(supervised || direct)
+  if (!existing || typeof existing !== "object" || Array.isArray(existing) || !ownedSource || !(supervised || direct) || !isNodeLauncher(existing.command)
       || existing.type !== undefined && existing.type !== "stdio" || ["url", "httpUrl", "serverUrl"].some((key) => existing[key] !== undefined)) {
-    throw new Error(`Desktop ${entryName} has an unrecognized or customized entrypoint; no configuration was changed`);
+    throw bridgeEntrypointConflict(`Desktop ${entryName}`, nodeBin, [path.join(root, "src", "mcp-supervisor.mjs"), "index.mjs"]);
   }
   if (existing.env !== undefined && (!existing.env || typeof existing.env !== "object" || Array.isArray(existing.env)
       || Object.values(existing.env).some((value) => typeof value !== "string"))) throw new Error(`Desktop ${entryName} environment must contain string values`);
@@ -193,13 +191,20 @@ if (setup) cfg.preferences = { ...cfg.preferences, menuBarEnabled: true };
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...cfg.mcpServers[entryName].env }) });
 
 const changed = original === null || JSON.stringify(JSON.parse(original.data.toString("utf8"))) !== JSON.stringify(cfg);
+function configSibling(suffix) {
+  const directory = path.resolve(path.dirname(cfgPath));
+  const file = path.resolve(directory, `${path.basename(cfgPath)}.${suffix}`);
+  const relative = path.relative(directory, file);
+  if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`) || path.dirname(file) !== directory) throw new Error("Unsafe Desktop configuration sibling path");
+  return file;
+}
+
 if (changed) {
-  const backup = `${cfgPath}.bak-${new Date().toISOString().slice(0, 10)}-codexbridge`;
+  const backup = configSibling(`bak-${new Date().toISOString().slice(0, 10)}-codexbridge-${randomUUID()}`);
   if (original) {
-    try { fs.writeFileSync(backup, original.data, { flag: "wx", mode: 0o600 }); }
-    catch (error) { if (error.code !== "EEXIST") throw error; }
+    fs.writeFileSync(backup, original.data, { flag: "wx", mode: 0o600 });
   }
-  const temporary = `${cfgPath}.${randomUUID()}.tmp`;
+  const temporary = configSibling(`${randomUUID()}.tmp`);
   try {
     fs.writeFileSync(temporary, `${JSON.stringify(cfg, null, 2)}\n`, { flag: "wx", mode: 0o600 });
     const current = readConfig();

package/scripts/install-codex-mcp.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { PLATFORM_LABEL, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { desktopTasksConfigured } from "../src/native-relay.mjs";
-import { applyStdioMcpRegistration, codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { applyStdioMcpRegistration, codexMcpRegistration, readCodexMcpServer } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { codexAccessPaths, enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
 import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
@@ -37,10 +37,7 @@ if (remove) {
   process.exit(0);
 }
 
-const servers = JSON.parse(run(["mcp", "list", "--json"]));
-if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
-const existing = servers.some((server) => server.name === serverName)
-  ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
+const existing = readCodexMcpServer(run, serverName);
 const registration = codexMcpRegistration({ name: serverName, existing, node: nodeBin, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
 const applied = applyStdioMcpRegistration({ name: serverName, registration, existing, run, configPath: codexAccessPaths().config });

package/scripts/install-native-relay.mjs

@@ -17,7 +17,7 @@ import {
   spawnEnv,
 } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
-import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { applyStdioMcpRegistration, readCodexMcpServer, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { codexAccessPaths, enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
 import { stableInstallPath } from "../src/install-paths.mjs";
@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.7";
+const VERSION = "1.26.9";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
@@ -69,10 +69,7 @@ if (!IS_MACOS && !IS_WINDOWS) {
   console.log("claude-bridge will keep using the app-server path here.");
 }
 
-const servers = JSON.parse(run(["mcp", "list", "--json"]));
-if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
-const existingServer = servers.some((server) => server.name === serverName)
-  ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
+const existingServer = readCodexMcpServer(run, serverName);
 /**
  * Registering under whichever Node happens to run this installer is what made
  * the companion unreachable on macOS: Codex Desktop rejects a peer whose
@@ -105,7 +102,7 @@ if (runtime.source === "process.execPath" && hasCodexDesktopApp()) {
   console.log("runtime shipped inside Codex Desktop if that happens.");
 }
 console.log(`registered MCP server "${serverName}" with Codex (${applied.mode === "retarget" ? "existing entry retargeted in place; its other settings were kept" : "codex mcp add"}):`);
-console.log(run(["mcp", "get", serverName]));
+if (!process.argv.includes("--setup")) console.log(run(["mcp", "get", serverName]));
 if (applied.notice) console.log(`NOTE: ${applied.notice}`);
 else if (ensureEnvVars.length) console.log(`env_vars includes ${ensureEnvVars.join(", ")}; the temporary pipe path itself is never saved.`);
 

package/scripts/setup.mjs

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 import { exitForVersionRequest } from "../src/cli-version.mjs";
-import { printSetup, runSetup } from "../src/setup.mjs";
+import { printSetup, runSetup, setupFailureResult } from "../src/setup.mjs";
 
 exitForVersionRequest(import.meta.url);
 try {
-  const result = runSetup({ args: process.argv.slice(2) });
+  const onProgress = process.argv.includes("--progress") ? (step) => process.stderr.write(`setup-progress: ${step}\n`) : undefined;
+  const result = runSetup({ args: process.argv.slice(2), onProgress });
   printSetup(result, { json: process.argv.includes("--json") });
   if (result.configured === false && !result.dryRun) process.exitCode = 1;
 } catch (error) {
-  process.stderr.write(`Bridge setup: ${error.message}\n`);
-  process.stderr.write("Bridge configuration was not completed. Run codex-bridge-setup to retry after resolving the reported error.\n");
+  if (process.argv.includes("--json")) printSetup(setupFailureResult(error), { json: true });
+  else {
+    process.stderr.write(`Bridge setup: ${error.message}\n`);
+    process.stderr.write("Bridge configuration was not completed. Run codex-bridge-setup to retry after resolving the reported error.\n");
+  }
   process.exitCode = 1;
 }

package/scripts/update.mjs

@@ -12,6 +12,7 @@ import { isMainModule } from "../src/install-paths.mjs";
 import { readRegularConfigFile } from "../src/project-policy.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { bridgeDiagnostic, withBridgeDiagnostic } from "../src/recipient-preflight.mjs";
+import { SETUP_INSPECTION, setupFailureSummary } from "../src/setup.mjs";
 
 const PACKAGE = "@minhspark/codex-mcp-bridge";
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -64,9 +65,18 @@ export function resolveUpdateNpm(env = process.env) {
   throw failure("UPDATE_NPM_NOT_FOUND", "A supported npm CLI could not be located. Run this updater through npm exec.", "preflight");
 }
 
-function execute(command, args, options) {
+const SETUP_PROGRESS = /^setup-progress: ([^\u0000-\u001f\u007f]{1,120})$/;
+
+function execute(command, args, { onStderrLine, ...options }) {
   return new Promise(resolve => {
-    execFile(command, args, options, (error, stdout, stderr) => resolve({ status: error ? 1 : 0, error, stdout, stderr }));
+    const child = execFile(command, args, options, (error, stdout, stderr) => resolve({ status: error ? 1 : 0, error, stdout, stderr }));
+    if (!onStderrLine || !child.stderr) return;
+    let pending = "";
+    child.stderr.on("data", chunk => {
+      const lines = (pending + chunk).split(/\r?\n/);
+      pending = lines.pop();
+      for (const line of lines) onStderrLine(line);
+    });
   });
 }
 
@@ -86,7 +96,7 @@ function neutralDirectory(roots, env) {
   throw failure("UPDATE_DIRECTORY_UNAVAILABLE", "No working directory outside the package installation is available.", "preflight");
 }
 
-function childFailure(result, phase) {
+function childFailure(result, phase, setupCommand = false) {
   const match = /npm\s+(?:ERR!|error)\s+code\s+([A-Z][A-Z0-9_]{0,79}|\d{1,10})\b/.exec(String(result?.stderr ?? ""));
   const signal = result?.error?.signal ?? result?.signal;
   const value = match?.[1] ?? result?.error?.code ?? (signal ? null : result?.status ?? result?.exitCode);
@@ -96,11 +106,13 @@ function childFailure(result, phase) {
     : /^SIG[A-Z0-9]{1,20}$/.test(signal ?? "") ? `SIGNAL_${signal}` : null;
   const cause = code ? Object.assign(new Error("The child command reported a failure."), { code }) : undefined;
   const permissionDenied = phase === "installation" && ["EPERM", "EACCES"].includes(code);
+  const setupSummary = setupCommand && phase === "verification" && !signal && !timedOut ? setupFailureSummary(result?.stdout) : null;
   return failure(permissionDenied ? "UPDATE_INSTALL_PERMISSION" : code === "EBUSY" ? "UPDATE_PACKAGE_BUSY" : timedOut ? "UPDATE_COMMAND_TIMEOUT" : phase === "verification" ? "UPDATE_SETUP_INCOMPLETE" : "UPDATE_NPM_FAILED",
     permissionDenied ? "npm could not write to the installation directory. Run codex-bridge-update --user to install and configure the bridge in your user account without administrator rights. Existing work and receipts were preserved."
       : timedOut ? `The update command exceeded its deadline. ${RETRY}`
       : code === "EBUSY" ? `The installed package is still held open by another process. No process was stopped. ${RETRY}`
-      : `The ${phase === "verification" ? "installed setup verification" : "npm command"} did not complete. ${RETRY}`, phase, cause);
+      : setupSummary ? `The global bridge settings are incomplete. ${setupSummary} ${RETRY}`
+      : `The ${phase === "verification" ? "installed setup verification" : "npm command"} did not complete. ${setupCommand ? `${SETUP_INSPECTION} ` : ""}${RETRY}`, phase, cause);
 }
 
 function serviceQuiescent(config) {
@@ -138,13 +150,13 @@ export async function runUpdate({ args = [], env = process.env, platform = proce
   const prefixArgs = userPrefix ? ["--prefix", userPrefix] : [];
   let cwd = neutralDirectory([root], env);
   let childEnv = Object.fromEntries(Object.entries(env).filter(([name]) => !/^AGENT_RELAY_(?!DIRECTORY$)/i.test(name)));
-  const command = async (arguments_, phase, timeout = 600000, environment = childEnv) => {
+  const command = async (arguments_, phase, timeout = 600000, environment = childEnv, setupCommand = false, onStderrLine) => {
     let result;
     try {
       result = await run(process.execPath, arguments_, { env: environment, cwd, encoding: "utf8", windowsHide: true,
-        shell: false, timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
-    } catch (error) { throw childFailure({ error, stderr: error.stderr }, phase); }
-    if (result?.error || (result?.status ?? result?.exitCode ?? 0) !== 0) throw childFailure(result, phase);
+        shell: false, timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], ...(onStderrLine ? { onStderrLine } : {}) });
+    } catch (error) { throw childFailure({ error, stdout: error.stdout, stderr: error.stderr }, phase, setupCommand); }
+    if (result?.error || (result?.status ?? result?.exitCode ?? 0) !== 0) throw childFailure(result, phase, setupCommand);
     return String(result?.stdout ?? "");
   };
   const modules = (await command([npm, "root", "--global", ...prefixArgs], "preflight", 30000)).trim();
@@ -200,13 +212,13 @@ export async function runUpdate({ args = [], env = process.env, platform = proce
   await command([npm, "install", "--global", "--prefix", prefix, `${PACKAGE}@${version}`, "--ignore-scripts"],
     "installation", 600000, { ...childEnv, CODEX_BRIDGE_SKIP_SETUP: "1" });
   if (packageVersion(globalRoot) !== version) throw failure("UPDATE_VERSION_MISMATCH", "The global package version does not match the updater version. Rerun the same update command.", "verification");
-  for (const check of [false, true]) {
-    onProgress(check ? "Verifying the global bridge settings and owned relay runtime." : "Applying managed settings from the installed bridge.");
-    let setup;
-    try { setup = JSON.parse(await command([path.join(globalRoot, "scripts", "setup.mjs"), ...(check ? ["--check"] : []), "--json"], "verification")); }
-    catch (error) { if (error?.code) throw error; throw failure("UPDATE_SETUP_INCOMPLETE", `Global setup did not return a verifiable result. ${RETRY}`, "verification"); }
-    if (setup?.configured !== true) throw failure("UPDATE_SETUP_INCOMPLETE", `The global bridge settings are incomplete. ${RETRY}`, "verification");
-  }
+  onProgress("Applying and verifying managed settings from the installed bridge. Each step can take up to a minute while Codex CLI reads its configuration.");
+  const setupProgress = line => { const step = SETUP_PROGRESS.exec(line)?.[1]; if (step) onProgress(`  ${step}`); };
+  let setup;
+  try { setup = JSON.parse(await command([path.join(globalRoot, "scripts", "setup.mjs"), "--json", "--progress"], "verification", 600000, childEnv, true, setupProgress)); }
+  catch (error) { if (error?.code) throw error; throw failure("UPDATE_SETUP_INCOMPLETE", `Global setup did not return a verifiable result. ${SETUP_INSPECTION} ${RETRY}`, "verification"); }
+  if (setup?.configured !== true) throw failure("UPDATE_SETUP_INCOMPLETE", `The global bridge settings are incomplete. ${setupFailureSummary(setup) ?? SETUP_INSPECTION} ${RETRY}`, "verification");
+  onProgress("Verifying the owned relay runtime.");
   const service = await awaitService(globalRoot, false, "verification");
   return { updated: true, configured: true, version, previousVersion, migrated, service, opensApps: false, opensChats: false };
 }

package/src/claude-bridge.mjs

@@ -31,7 +31,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.7";
+const VERSION = "1.26.9";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/claude-code-registration.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { bridgeEntrypointConflict, isBridgeSource, isNodeLauncher } from "./install-paths.mjs";
 
 const PACKAGE_SOURCE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -31,7 +32,7 @@ function configurationObject(value, label) {
   return value;
 }
 
-function initialBridgeEntry(entry, root, label) {
+function initialBridgeEntry(entry, root, node, label) {
   configurationObject(entry, label);
   if (entry.type !== undefined && entry.type !== "stdio" || ["url", "serverUrl", "httpUrl"].some((key) => entry[key] !== undefined)) {
     throw new Error(`${label} has a conflicting transport; no configuration was changed`);
@@ -41,11 +42,9 @@ function initialBridgeEntry(entry, root, label) {
   const leaf = typeof script === "string" ? path.basename(script) : null;
   const supervised = args?.length === 2 && leaf === "mcp-supervisor.mjs" && args[1] === "index.mjs";
   const direct = args?.length === 1 && ["index.mjs", "codex-bridge-launcher.mjs"].includes(leaf);
-  const source = typeof script === "string" && path.isAbsolute(script) ? path.dirname(path.resolve(script)) : null;
-  const ownSource = source && (source === PACKAGE_SOURCE || source === path.join(root, "src")
-    || path.basename(source) === "src" && path.basename(path.dirname(source)).toLowerCase() === "codex-mcp-bridge");
-  if (!Array.isArray(args) || !(supervised || direct) || !ownSource) {
-    throw new Error(`${label} is already configured with an unrecognized or customized entrypoint; no configuration was changed`);
+  const ownSource = isBridgeSource(script, [PACKAGE_SOURCE, path.join(root, "src")], ["index.mjs"]);
+  if (!Array.isArray(args) || !(supervised || direct) || !ownSource || !isNodeLauncher(entry.command)) {
+    throw bridgeEntrypointConflict(label, node, [path.join(root, "src", "mcp-supervisor.mjs"), "index.mjs"]);
   }
   if (entry.env !== undefined) {
     configurationObject(entry.env, `${label} environment`);
@@ -67,7 +66,7 @@ export function planInitialCodeRegistration({ code, desktop, root, node, environ
   const sharedNative = desktop.mcpServers?.[name] ?? desktop.mcpServers?.[`${name}-desktop`];
   const inheritedShared = originalCode === undefined && sharedNative?.env?.CODEX_BRIDGE_DESKTOP_TASKS === "1";
   const source = inheritedShared ? sharedNative : originalCode;
-  if (source !== undefined) initialBridgeEntry(source, root, `Claude Code ${name}`);
+  if (source !== undefined) initialBridgeEntry(source, root, node, `Claude Code ${name}`);
   const defaults = Object.fromEntries(INITIAL_ENVIRONMENT_KEYS.filter((key) => environment[key] !== undefined).map((key) => [key, environment[key]]));
   if (Object.values(defaults).some((value) => typeof value !== "string")) throw new Error("Bridge environment defaults must be strings");
   const scopeKeys = ["CODEX_BRIDGE_THREAD_POLICY", "CODEX_BRIDGE_ALLOWED_ROOTS", "CODEX_BRIDGE_PROJECT_POLICY", "CODEX_BRIDGE_ALLOWED_THREADS", "CODEX_BRIDGE_HARDENED"];
@@ -94,7 +93,7 @@ export function planInitialCodeRegistration({ code, desktop, root, node, environ
   if (JSON.stringify(originalCode) !== JSON.stringify(replacement)) changes.push({ kind: originalCode ? "update-user-code-entry" : "create-user-code-entry", name });
   const shared = updatedDesktop.mcpServers?.[name];
   if (shared !== undefined) {
-    initialBridgeEntry(shared, root, `Shared Desktop ${name}`);
+    initialBridgeEntry(shared, root, node, `Shared Desktop ${name}`);
     const destination = `${name}-desktop`;
     if (Object.hasOwn(updatedDesktop.mcpServers, destination)) {
       throw new Error(`Shared Desktop ${destination} already exists; resolve the name collision before installation`);

package/src/codex-mcp-registration.mjs

@@ -1,9 +1,32 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { retargetMcpServerToml } from "./codex-mcp-toml.mjs";
+import { backupRegularConfigFile } from "./project-policy.mjs";
 
 const PRESERVED_FIELDS = ["enabled", "disabled_reason", "enabled_tools", "disabled_tools", "startup_timeout_sec", "tool_timeout_sec"];
 
+export const CODEX_MCP_TIMEOUT_MS = 120000;
+
+function missingServerError(error, name) {
+  const output = `${error?.stderr ?? ""}\n${error?.stdout ?? ""}\n${error?.message ?? ""}`;
+  return output.includes(`No MCP server named '${name}' found`);
+}
+
+export function readCodexMcpServer(run, name) {
+  let output;
+  try { output = run(["mcp", "get", name, "--json"]); }
+  catch (error) {
+    if (missingServerError(error, name)) return null;
+    throw error;
+  }
+  const entry = JSON.parse(output);
+  if (!entry || typeof entry !== "object" || Array.isArray(entry) || entry.name !== name) {
+    throw new Error(`Codex returned an invalid ${name} entry; existing configuration was not changed`);
+  }
+  return entry;
+}
+
 function sameEnvironment(left = {}, right = {}) {
   const keys = (value) => Object.keys(value ?? {}).sort();
   return JSON.stringify(keys(left)) === JSON.stringify(keys(right)) && keys(left).every((key) => left[key] === right[key]);
@@ -99,12 +122,19 @@ function verificationErrors(before, after, registration, ensureEnvVars) {
 
 export function applyStdioMcpRegistration({ name, registration, existing, run, configPath, ensureEnvVars = [] }) {
   const original = readConfigSnapshot(configPath);
+  let backedUp = false;
+  const ensureBackup = () => {
+    if (!original || backedUp) return;
+    backupRegularConfigFile(original.path, `${original.path}.backup-${randomUUID()}`, original.contents, 16 * 1024 * 1024);
+    backedUp = true;
+  };
   const target = { command: registration.command, args: registration.commandArgs, ensureEnvVars };
   const editInPlace = () => {
     const current = readConfigSnapshot(configPath);
     if (!current) throw new Error("The Codex configuration file does not exist");
     const next = retargetMcpServerToml(current.contents, name, target);
     if (next === current.contents) return false;
+    ensureBackup();
     writeConfigAtomically(current, next);
     return true;
   };
@@ -120,11 +150,12 @@ export function applyStdioMcpRegistration({ name, registration, existing, run, c
         mutated = edited;
         envVarsAdded = true;
       } catch (error) {
-        if (!registration.args) throw new Error(`${error.message}. ${registration.manual}`);
+        if (!registration.args || backedUp) throw new Error(`${error.message}. ${registration.manual}`);
         mode = "add";
       }
     }
     if (mode === "add") {
+      ensureBackup();
       run(registration.args);
       mutated = true;
       if (!envVarsAdded) {

package/src/desktop-account-context.mjs

@@ -33,6 +33,31 @@ function directoryStat(directory) {
   return stat;
 }
 
+function retiredRoot(root, candidates) {
+  let initial;
+  try { initial = fs.lstatSync(root, { bigint: true }); }
+  catch (error) { if (isMissing(error)) return false; throw error; }
+  let directory = root;
+  let destination;
+  if (initial.isSymbolicLink()) {
+    destination = fs.realpathSync.native(root);
+    directory = candidates.find((candidate) => {
+      if (candidate === root) return false;
+      try {
+        directoryStat(candidate);
+        return fs.realpathSync.native(candidate).toLowerCase() === destination.toLowerCase();
+      } catch (error) { if (isMissing(error) || error.message === "invalid directory") return false; throw error; }
+    });
+    if (!directory) throw new Error("invalid directory");
+  }
+  const before = directoryStat(directory);
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  const retired = entries.length > 0 && entries.every((entry) => entry.isFile() && /^\.user-data-left(?:\.|$)/i.test(entry.name));
+  if (!sameVersion(before, directoryStat(directory)) || !sameVersion(initial, fs.lstatSync(root, { bigint: true }))
+      || destination !== undefined && fs.realpathSync.native(root) !== destination) throw new Error("root changed");
+  return retired;
+}
+
 function candidateRoots({ platform, env, root }) {
   const selected = root !== undefined ? root : env.CLAUDE_DESKTOP_USER_DATA;
   if (selected !== undefined) return [absoluteDirectory(selected)];
@@ -42,30 +67,42 @@ function candidateRoots({ platform, env, root }) {
       : env.XDG_CONFIG_HOME || path.join(home, ".config");
   const roots = [absoluteDirectory(path.join(config, "Claude"))];
   if (platform === "win32") {
-    const packages = absoluteDirectory(path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "Packages"));
-    let entries;
-    try {
-      directoryStat(packages);
-      entries = fs.readdirSync(packages, { withFileTypes: true });
-    } catch (error) {
-      if (!isMissing(error)) throw error;
-      entries = [];
-    }
-    if (entries.length > MAX_PACKAGES) throw new Error("package scan limit");
-    for (const entry of entries) {
-      if (!PACKAGE_NAME.test(entry.name)) continue;
-      const packageRoot = path.join(packages, entry.name);
-      directoryStat(packageRoot);
-      roots.push(path.join(packageRoot, "LocalCache", "Roaming", "Claude"));
+    const local = absoluteDirectory(env.LOCALAPPDATA || path.join(home, "AppData", "Local"));
+    for (const [name, suffix] of [["Packages", ["LocalCache", "Roaming", "Claude"]], ["Claude-Data", []]]) {
+      const parent = path.resolve(local, name);
+      const relative = path.relative(local, parent);
+      if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) throw new Error("invalid package directory");
+      let entries;
+      try {
+        directoryStat(parent);
+        entries = fs.readdirSync(parent, { withFileTypes: true });
+      } catch (error) {
+        if (!isMissing(error)) throw error;
+        entries = [];
+      }
+      if (entries.length > MAX_PACKAGES) throw new Error("package scan limit");
+      for (const entry of entries) {
+        if (!PACKAGE_NAME.test(entry.name)) continue;
+        const packageRoot = path.join(parent, entry.name);
+        directoryStat(packageRoot);
+        roots.push(path.join(packageRoot, ...suffix));
+      }
     }
   }
   const unique = [...new Map(roots.map((value) => [platform === "win32" ? value.toLowerCase() : value, value])).values()].sort();
   if (unique.length > MAX_ROOTS) throw new Error("root scan limit");
-  return unique;
+  if (platform !== "win32") return unique;
+  const active = unique.filter((candidate) => !retiredRoot(candidate, unique));
+  if (active.length === unique.length) return active;
+  return active.filter((candidate) => {
+    try { directoryStat(candidate); return true; }
+    catch (error) { if (isMissing(error)) return false; throw error; }
+  });
 }
 
 export function resolveClaudeDesktopConfigRoot({ platform = process.platform, env = process.env } = {}) {
   const roots = candidateRoots({ platform, env });
+  if (!roots.length) throw Object.assign(new Error("No active Claude Desktop data root remains after migration. Start Claude Desktop or set CLAUDE_DESKTOP_USER_DATA to its active data directory, then rerun setup."), { code: "CLAUDE_DESKTOP_DATA_ROOT_UNAVAILABLE" });
   if (roots.length === 1) return roots[0];
   const account = readClaudeAccountContext({ platform, env });
   if (account.status === "verified" || account.status === "signed_out") return account.root;
@@ -79,7 +116,7 @@ export function resolveClaudeDesktopConfigRoot({ platform = process.platform, en
     const ordinary = path.resolve(env.APPDATA || path.join(home, "AppData", "Roaming"), "Claude");
     return roots.find((root) => root.toLowerCase() !== ordinary.toLowerCase());
   }
-  throw new Error("Multiple Claude Desktop data roots exist. Set CLAUDE_DESKTOP_USER_DATA to the application's active data directory, then rerun setup.");
+  throw Object.assign(new Error("Multiple Claude Desktop data roots exist. Set CLAUDE_DESKTOP_USER_DATA to the application's active data directory, then rerun setup."), { code: "CLAUDE_DESKTOP_DATA_ROOT_AMBIGUOUS" });
 }
 
 function readConfig(root) {

package/src/index.mjs

@@ -44,7 +44,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.7";
+const VERSION = "1.26.9";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/install-paths.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { readRegularConfigFile } from "./project-policy.mjs";
 
 const KEG_PATH = /^(\/.*?)\/Cellar\/([^/]+)\/[^/]+(\/.*)?$/;
 
@@ -36,6 +37,40 @@ export function stableNodeBin(env = process.env) {
   return stableInstallPath(process.execPath, env);
 }
 
+export function isNodeLauncher(command) {
+  return typeof command === "string" && !command.includes("\0")
+    && /^(?:node|node\.exe)$/i.test(path.basename(command))
+    && (path.isAbsolute(command) || command === path.basename(command));
+}
+
+export function isBridgeSource(script, sources = [], workers = []) {
+  if (typeof script !== "string" || !path.isAbsolute(script) || script.includes("\0")) return false;
+  const source = path.dirname(path.resolve(script));
+  if ([...sources].some(value => path.relative(value, source) === "")) return true;
+  if (path.basename(source) !== "src") return false;
+  const root = path.dirname(source);
+  try {
+    for (const directory of [root, source]) {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
+    }
+    const metadata = JSON.parse(readRegularConfigFile(path.join(root, "package.json"), { maxBytes: 128 * 1024 }));
+    if (metadata?.name !== "@minhspark/codex-mcp-bridge" || typeof metadata.version !== "string"
+      || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.+-]+)?$/.test(metadata.version)) return false;
+    for (const name of new Set([path.basename(script), ...workers])) {
+      if (typeof name !== "string" || path.basename(name) !== name) return false;
+      const stat = fs.lstatSync(path.join(source, name));
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+
+export function bridgeEntrypointConflict(label, node, args, detail = "an unrecognized or customized entrypoint") {
+  const code = "SETUP_ENTRYPOINT_CONFLICT";
+  return Object.assign(new Error(`${code}: ${label} has ${detail}; no configuration was changed. Restore the previous bridge package so setup can verify its package.json, or back up this registration and update only command=${JSON.stringify(node)} and args=${JSON.stringify(args)}. Preserve its other settings, then rerun setup.`), { code });
+}
+
 /**
  * True when `entry` names the running main module, however it was reached.
  * Node resolves the main module with the JavaScript realpath, which follows

package/src/native-relay-companion.mjs

@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.7";
+const VERSION = "1.26.9";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/setup.mjs

@@ -8,13 +8,64 @@ import { resolveCodexBin, resolvePackagedCodexBin } from "./platform.mjs";
 import { readRegularConfigFile } from "./project-policy.mjs";
 import { stableInstallPath } from "./install-paths.mjs";
 import { resolveClaudeDesktopConfigRoot } from "./desktop-account-context.mjs";
+import { CODEX_MCP_TIMEOUT_MS } from "./codex-mcp-registration.mjs";
 
 const ROOT = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const CODEX_PACKAGE = "@openai/codex@0.166.0";
 const MAX_CONFIG = 16 * 1024 * 1024;
+export const SETUP_INSPECTION = "Inspect locally with codex-bridge-setup --check --json.";
+const SETUP_COMPONENTS = new Set([
+  "Setup preflight", "Claude Desktop data directory", "Codex CLI", "Codex / claude-bridge",
+  "Codex / codex-native-relay", "Codex / codex-native-relay and executor", "Codex / antigravity-bridge",
+  "Claude Code / codex-bridge", "Claude Desktop / codex-bridge-desktop", "Claude Code / antigravity-bridge",
+  "Claude Desktop / background preference", "Antigravity / agent-bridge", "Antigravity / codex-bridge sidecar",
+  "Antigravity / all components", "Native relay executor", "Claude registration names", "Independent background relay",
+]);
+const SETUP_FAILURES = Object.freeze({
+  CLAUDE_DESKTOP_DATA_ROOT_AMBIGUOUS: "Multiple active directories; set CLAUDE_DESKTOP_USER_DATA to the active Claude data directory.",
+  CLAUDE_DESKTOP_DATA_ROOT_UNAVAILABLE: "Data directory unavailable; check access and the CLAUDE_DESKTOP_USER_DATA override.",
+  SETUP_ENTRYPOINT_CONFLICT: "Existing entrypoint could not be verified; review the preserved registration before migration.",
+  SETUP_SIDECAR_DEFINITION_MISSING: "Sidecar settings remain without a verified definition; review both sidecar configuration files.",
+  SETUP_COMPONENT_INCOMPLETE: "Configuration could not be completed or verified.",
+});
+
+function failureCode(error) {
+  return typeof error?.code === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(error.code) ? error.code : "SETUP_COMPONENT_INCOMPLETE";
+}
+
+function failedComponent(name, error) {
+  return { name, status: "incomplete", code: failureCode(error), detail: error.message };
+}
+
+export function setupFailureResult(error) {
+  const selected = failureCode(error);
+  const code = Object.hasOwn(SETUP_FAILURES, selected) ? selected : "SETUP_COMPONENT_INCOMPLETE";
+  const name = code === "CLAUDE_DESKTOP_DATA_ROOT_AMBIGUOUS" || code === "CLAUDE_DESKTOP_DATA_ROOT_UNAVAILABLE"
+    ? "Claude Desktop data directory" : "Setup preflight";
+  return { configured: false, liveVerified: false, components: [{ name, status: "incomplete", code, detail: SETUP_FAILURES[code] }], nextActions: [SETUP_INSPECTION] };
+}
+
+export function setupFailureSummary(value) {
+  if (typeof value === "string") {
+    if (Buffer.byteLength(value) > 128 * 1024) return null;
+    try { value = JSON.parse(value); } catch { return null; }
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.configured !== false) return null;
+  const failures = new Map();
+  for (const items of [value.components, value.verification]) {
+    if (!Array.isArray(items)) continue;
+    for (const item of items.slice(0, 128)) {
+      if (!item || item.status !== "incomplete" || !SETUP_COMPONENTS.has(item.name) || failures.has(item.name)) continue;
+      const code = typeof item.code === "string" && Object.hasOwn(SETUP_FAILURES, item.code) ? item.code : "SETUP_COMPONENT_INCOMPLETE";
+      failures.set(item.name, `${item.name}: ${SETUP_FAILURES[code]}`);
+    }
+  }
+  if (!failures.size) return null;
+  return `${SETUP_INSPECTION} ${[...failures.values()].slice(0, 6).join(" ")}${failures.size > 6 ? " Additional incomplete components are listed by that command." : ""}`;
+}
 
 export function setupArguments(args) {
-  const allowed = new Set(["--postinstall", "--check", "--dry-run", "--json", "--no-download", "--help"]);
+  const allowed = new Set(["--postinstall", "--check", "--dry-run", "--json", "--no-download", "--progress", "--help"]);
   if (args.some((arg) => !allowed.has(arg))) throw new Error("Unknown setup option; use codex-bridge-setup --help");
   if (args.includes("--check") && args.includes("--dry-run")) throw new Error("Use --check or --dry-run, not both");
   return Object.fromEntries([...allowed].map((arg) => [arg.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()), args.includes(arg)]));
@@ -56,6 +107,7 @@ export function setupProcessFailure(command, args, result) {
   try { structured = JSON.parse(String(result.stdout || "")); } catch {}
   const validCode = value => typeof value === "string" && /^[A-Z][A-Z0-9_]{0,79}$/.test(value);
   const codes = [structured?.code, structured?.service?.code, structured?.permissions?.code, structured?.diagnostic?.code,
+    ...String(result.stderr || "").split(/\r?\n/).map(line => /^(?:Error: )?([A-Z][A-Z0-9_]{0,79}):/.exec(line)?.[1]).filter(code => Object.hasOwn(SETUP_FAILURES, code ?? "")),
     ...String(result.stderr || "").split(/\r?\n/).map(line => /^([A-Z][A-Z0-9_]{0,79}) \| /.exec(line)?.[1])].filter(validCode);
   const lines = String(result.stderr || "").split(/\r?\n/).filter(line => /^Error:|^(?:Expected|Refusing|Invalid|Unknown|Shared|Claude|Codex|Configuration|The existing|Missing|Unsafe)/.test(line)
     && !/Command failed|--env|password|secret|token|authorization/i.test(line));
@@ -97,9 +149,16 @@ export function setupEnvironment(env, paths, codex) {
     CLAUDE_DESKTOP_CONFIG: paths.desktop, CODEX_EXE: codex, CODEX_BIN: codex };
 }
 
+function codexInventoryFailure(error) {
+  const detail = error?.message?.includes("ETIMEDOUT") || error?.code === "ETIMEDOUT"
+    ? `Codex CLI did not list its MCP servers within ${CODEX_MCP_TIMEOUT_MS / 1000} seconds; the computer may be busy. Rerun the check when it is idle`
+    : error?.message ?? String(error);
+  return Object.assign(new Error(detail), error?.code ? { code: error.code } : {});
+}
+
 function configurationCheck(label, check, components) {
   try { const details = check(); components.push({ name: label, status: "configured", ...details }); }
-  catch (error) { components.push({ name: label, status: "incomplete", detail: error.message }); }
+  catch (error) { components.push(failedComponent(label, error)); }
 }
 
 function assertEntry(entry, worker, root, { caller } = {}) {
@@ -107,7 +166,7 @@ function assertEntry(entry, worker, root, { caller } = {}) {
   const args = entry.args ?? [];
   const expected = ["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs", "antigravity-bridge.mjs", "antigravity-outbound-bridge.mjs"].includes(worker)
     ? [path.join(root, "src", "mcp-supervisor.mjs"), worker] : [path.join(root, "src", worker)];
-  if (JSON.stringify(args) !== JSON.stringify(expected)) throw new Error("MCP entry points to a different installation or unsupported launcher");
+  if (JSON.stringify(args) !== JSON.stringify(expected)) throw Object.assign(new Error("MCP entry points to a different installation or unsupported launcher"), { code: "SETUP_ENTRYPOINT_CONFLICT" });
   if (caller && entry.env?.ANTIGRAVITY_BRIDGE_CALLER !== caller) throw new Error("Antigravity caller registration is missing or conflicting");
   if (entry.enabled === false || entry.disabled === true) return { deliveryEnabled: false,
     notices: ["This MCP registration is intentionally disabled. Its saved choice was preserved; delivery through this connector is disabled."] };
@@ -120,15 +179,16 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
   let inventory;
   configurationCheck("Codex CLI", () => {
     codex = ensureSetupCodex({ env, paths, platform, download: false, run, resolve }).binary;
-    inventory = JSON.parse(run(codex, ["mcp", "list", "--json"], setupEnvironment(env, paths, codex), 30000));
-    if (!Array.isArray(inventory)) throw new Error("Codex returned an invalid MCP inventory");
+    try { inventory = JSON.parse(run(codex, ["mcp", "list", "--json"], setupEnvironment(env, paths, codex), CODEX_MCP_TIMEOUT_MS)); }
+    catch (error) { throw codexInventoryFailure(error); }
+    if (!Array.isArray(inventory)) { inventory = undefined; throw new Error("Codex returned an invalid MCP inventory"); }
   }, components);
   const native = platform === "win32" || platform === "darwin";
   for (const [name, worker] of [["claude-bridge", "claude-bridge.mjs"], ...(native ? [["codex-native-relay", "native-relay-companion.mjs"]] : []), ["antigravity-bridge", "antigravity-bridge.mjs"]]) {
     configurationCheck(`Codex / ${name}`, () => {
-      const item = inventory?.find((server) => server.name === name);
-      if (!item) throw new Error("MCP registration is missing");
-      const entry = JSON.parse(run(codex, ["mcp", "get", name, "--json"], setupEnvironment(env, paths, codex), 30000));
+      if (!inventory) throw new Error("Not checked because Codex CLI did not report its MCP servers; the registration may still be present");
+      const entry = inventory.find((server) => server?.name === name);
+      if (!entry) throw new Error("MCP registration is missing");
       const details = assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
       if (name === "codex-native-relay" && !entry.transport.env_vars?.includes("CODEX_APP_TOOLS_PIPE_PATH")) throw new Error("Native pipe forwarding is missing");
       return details;
@@ -177,7 +237,7 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
   return { configured: components.every((item) => item.status === "configured"), liveVerified: false, components };
 }
 
-export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
+export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin, onProgress = () => {} } = {}) {
   const options = setupArguments(args);
   if (options.help) return { help: `Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings in an interactive terminal with: ${platform === "win32" ? "npx.cmd" : "npx"} -y @minhspark/codex-mcp-bridge@latest\nThe updater installs the package with lifecycle scripts disabled, then directly configures Claude Desktop, Claude Code, Codex, Antigravity and the independent worker relay. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration, background relay health and loaded native app connections are verified separately.` };
   if (options.postinstall && !automaticSetupEnabled(env)) return { skipped: true, reason: "Automatic configuration runs only for a global npm install; use codex-bridge-setup for manual setup." };
@@ -192,6 +252,7 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const base = setupEnvironment(env, paths, runtime.binary);
   const components = [];
   const install = (name, script, arguments_, environment = base) => {
+    onProgress(name);
     try {
       const output = run(process.execPath, [path.join(root, "scripts", script), ...arguments_], environment, 180000);
       let details = {};
@@ -201,7 +262,7 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
         ...(typeof details.liveVerified === "boolean" ? { liveVerified: details.liveVerified, transportReady: details.transportReady === true } : {}),
         ...(details.backgroundPreference ? { backgroundPreference: details.backgroundPreference } : {}) });
       return true;
-    } catch (error) { components.push({ name, status: "incomplete", detail: error.message }); return false; }
+    } catch (error) { components.push(failedComponent(name, error)); return false; }
   };
   const code = install(planned[0], "install-claude-code.mjs", ["--install", "--setup", "--desktop-config", paths.desktop], {
     ...base, CODEX_BRIDGE_DESKTOP_TASKS: native ? "1" : "0", CODEX_BRIDGE_AUTOSTART: native ? "0" : "1", CODEX_BRIDGE_THREAD_POLICY: "roots",
@@ -214,6 +275,7 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   install("Codex / claude-bridge", "install-codex-mcp.mjs", ["--setup"]);
   if (code) install("Antigravity / all components", "install-antigravity-bridge.mjs", ["--all", "--setup"]);
   install("Independent background relay", "setup-background-relay.mjs", ["--json"]);
+  onProgress("Verifying saved settings");
   const inspection = checkSetup({ env: base, platform, root, run, resolve: () => runtime.binary });
   return { configured: components.every((item) => item.status === "configured") && inspection.configured, liveVerified: false,
     cliInstalled: runtime.installed, components, verification: inspection.components,