@minhspark/codex-mcp-bridge 1.22.12 → 1.22.14

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,50 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.14] - 2026-10-21
+
+### Fixed
+
+- Start the Codex Desktop native relay when it is missing instead of failing every Claude-to-Codex call. Codex Desktop runs `codex-native-relay` only while a task has its MCP servers loaded: at launch it starts them for about a second to build its tool catalog and then cancels them, so after a Desktop restart `codex_bridge_status`, `list_codex_threads`, `send_to_codex_thread` and `delegate_to_codex` failed with `connect ENOENT .../native-relay.sock-accounts-v2` until a task was opened. When a Desktop request cannot reach the relay before anything was written and Codex Desktop is running on macOS or Windows, the bridge now opens the destination task, or the most recent Codex Desktop task of the sender's project, in the background through `codex://threads/<id>`, waits up to 20 seconds for the relay socket and retries once. A failed wake backs off for one minute. `CODEX_BRIDGE_RELAY_WAKE=0` turns this off. On Windows the bridge recognises Codex Desktop by the packaged `OpenAI.Codex_*\app\ChatGPT.exe`, and the project fallback also accepts a task of the same git repository, so a Claude Code session in a linked worktree can wake the relay through the main checkout's task.
+- Open Codex Desktop tasks on Windows without reporting a false failure. `explorer.exe codex://threads/<id>` opens the task but always exits with code 1, so `open_codex_thread` and the `open` option of the send tools reported an error after a successful open, and the relay wake gave up although Codex had loaded the task. Links now go through PowerShell `Start-Process`, which returns 0 on success and fails when no `codex://` handler is registered. The URL is passed base64-encoded, never interpolated into the command.
+- Report the relay-down cause accurately. The guidance now says that the relay runs only while a task has its MCP servers loaded, points to a regular project task rather than the internal Native Relay executor task (which reports a missing rollout when opened, by design), and appears only when the relay was actually unreachable. The Desktop failure text no longer doubles its final period.
+- Read compressed Codex rollouts. Codex compresses rollouts that have been idle for about a week to `rollout-*.jsonl.zst` (244 of 269 files on the test Mac). The bridge matched only `.jsonl`, so a send to such a task delivered the message but returned an empty reply (`No trusted pre-send rollout watermark is available`), and `read_codex_thread` with a `turnId` failed. Discovery now accepts both forms, decompresses with Node's zstd support (22.15+ or 23.8+; older runtimes get a clear error) under a separate 256 MiB limit, follows Codex rewriting the file as plain `.jsonl` when the task resumes, retries reads that race that rewrite, and caches unchanged compressed scans. The VS Code task bridge also lists compressed tasks.
+- Prune the runtime snapshot cache. Nothing removed snapshots from `~/.codex/bridge-runtimes` (76 directories, 1.8 GB measured). Supervisors now lease their worker runtimes and prune one minute after start and after each activation: runtimes that are leased, referenced by a running process, among the three most recently used, or used in the last 24 hours are kept, at most eight are removed per hourly pass, and orphaned digest files, stale leases and abandoned temporaries are cleaned up. On macOS snapshots are APFS clones (`/bin/cp -c`), because `COPYFILE_FICLONE` never clones there.
+- `inspect_bridge_project` reports a missing `CODEX_BRIDGE_PROJECT_POLICY` as `policy_not_configured` with next steps instead of failing. Errors from read-only tools no longer carry the "No Desktop mutation was dispatched ... do not resend" boilerplate, `wait_codex_reply` and `read_codex_thread` keep their no-resend guidance only while the turn can still change, and error sentences are punctuated.
+- The Claude Code registration check detects an unsupervised shared Claude Desktop bridge entry, including one renamed to `codex-bridge-desktop`, and `install-claude-desktop` updates that entry instead of adding a second one. Neither claims or removes entries that run another program.
+- The relay companion and `claude-bridge` drain accepted work on SIGTERM, SIGINT and SIGHUP like they do when the MCP client closes; a second signal exits at once. A relay listener whose startup is refused or cancelled no longer leaves a dead public socket. `install-native-relay --remove` also removes the account and Desktop task sockets and names the retired executor task.
+- Adding a missing name to an existing `env_vars` array keeps its comments and layout.
+
+### Verification
+
+- 1,489 tests before, 1,564 after, 0 failures (23 platform skips). New tests cover the relay wake (destination and project fallback, executor exclusion, back-off, coalescing, retry only before a write), compressed discovery, reads, rematerialization races and the descriptor-leak path, snapshot pruning and liveness re-checks, the read-only tool surface, and registration detection. Each behaviour test was confirmed to fail on the previous code.
+- Measured on Codex Desktop 26.1016.6573.0 on Windows 11: after the relay processes were stopped, opening a regular task that was not loaded brought all three `\\.\pipe\LOCAL\codex-native-relay*` pipes back and the wake returned in 4.8 seconds. Reopening the task whose MCP session was still loaded did not restart the relay within 20 seconds, which the wake reported and backed off from.
+- Measured on Codex Desktop 26.1013 (Codex Framework 155.0.8059.80) on macOS: a relay process outside the app-server's process tree is refused with `dynamic_app_tools_peer_rejected reason=untrusted-process-ancestry`, so the relay cannot be kept alive outside a task's MCP session. Opening a regular task with `open -g codex://threads/<id>` started a new `codex-native-relay` supervisor within about 10 seconds, after which `delegate_to_codex` created a task and returned Codex's reply (`RELAY-OK 22:17`) through the relay.
+- A read-only probe on a real compressed task returned an available watermark (57.9 MB decompressed in 185 ms) and an authoritative turn read, both `unavailable` before the fix.
+- Three adversarial reviews ran over the changes; every confirmed finding is fixed with a test.
+
+### Limitations
+
+- On macOS the wake opens the task without activating Codex Desktop. On Windows the `codex://` handler brings the Codex Desktop window forward.
+- The wake helps only when the opened task does not already have its MCP servers loaded. If the relay process died while its task stayed loaded, reopening that task does not restart it; open another task or reconnect the task's MCP servers.
+- The wake It needs either the destination task or an earlier Codex Desktop task in the sender's project; otherwise the bridge reports the relay-down guidance.
+- Codex can unload a task's MCP servers when the task is idle; the next request wakes the relay again.
+
+## [1.22.13] - 2026-10-20
+
+### Fixed
+
+- Find the Codex Desktop native tools pipe on Desktop 26.1013. That build serves the native app tools on `\\.\pipe\codex-app-tools-<id>` and no longer passes `CODEX_APP_TOOLS_PIPE_PATH` on the app-server command line. Windows discovery only looked at `codex-browser-use-*` pipes, which answer `No handler registered for method: tools/call`, so the relay companion never opened `codex-native-relay-accounts-v2` and every Claude-to-Codex send failed with `RELAY_UNAVAILABLE` (`connect ENOENT`). Discovery now also accepts `codex-app-tools-*` pipes. The existing checks still apply: the pipe must be local, owned by the exact `ChatGPT.exe` ancestor of the companion's app-server, and answer a read-only `list_projects` call. `codex-app-tools-*` sorts first, so it is tried before the browser pipes.
+
+### Verification
+
+- One new test covers a Desktop 26.1013 snapshot with both pipe kinds and checks that only the app-tools pipe is probed. It fails on v1.22.12. A pipe with another `codex-` prefix, and an app-tools pipe owned by another process, are still rejected.
+- On a Windows machine running Codex Desktop 26.1013.4894.0, `resolveNativeToolsPipePath` from v1.22.12 returned `null` and the fixed code returned the live `codex-app-tools-*` pipe, owned by the Desktop process that started the app-server. `list_projects` through that pipe returned the saved projects; the five `codex-browser-use-*` pipes returned `No handler registered for method: tools/call`.
+
+### Limitations
+
+- A running companion keeps its old discovery code until it reloads. After updating, restart Codex Desktop, or let automatic reload pick up the new source, then check `native_relay_status`.
+
 ## [1.22.12] - 2026-10-20
 
 ### Fixed

package/README.md

@@ -198,7 +198,7 @@ Dispatch expires after two minutes; operation history remains stored. Disconnect
 - **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory (or Homebrew's `bin`) on PATH.
 - **PowerShell blocks scripts:** use `npm.cmd`, installer `.cmd` launchers, and `codex.exe`.
 - **No sessions or wrong project:** open the intended Claude **Code** session and use the exact project directory saved in Codex Desktop.
-- **Relay unavailable:** check [pipe forwarding](#native-relay-pipe-forwarding), reconnect, and run `native_relay_status` in the task.
+- **Relay unavailable:** Codex Desktop runs the relay only while a task has its MCP servers loaded. On macOS the bridge opens the destination task (or your project's latest Codex task) in the background to start it; otherwise open a regular project task and send it a turn. If it still fails, check [pipe forwarding](#native-relay-pipe-forwarding) and run `native_relay_status` in that task.
 - **Timeout or unconfirmed send:** inspect the original task or receipt before sending again.
 
 [More fixes](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#troubleshooting) · [Report an issue](https://github.com/buidangminh23/codex-mcp-bridge/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.12",
+  "version": "1.22.14",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "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.22.12",
+  "version": "1.22.14",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-claude-desktop.mjs

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 
-import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
+import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, homeDir, resolveCodexBin } from "../src/platform.mjs";
+import { readRegularConfigFile } from "../src/project-policy.mjs";
 import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
@@ -18,7 +19,6 @@ const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
 const reset = process.argv.includes("--reset");
 const forceDesktopTasks = process.argv.includes("--desktop-tasks");
 const fullAccess = process.argv.includes("--full-access") || fullAccessEnabled();
-if (fullAccess) enableCodexFullAccess();
 
 /**
  * This bridge is intentionally the local hand-off point between Claude and
@@ -88,7 +88,22 @@ cfg.mcpServers = cfg.mcpServers ?? {};
  * already says, then the default. `--reset` drops the middle one for the rare
  * case of wanting the defaults back.
  */
-const previousEntry = (reset ? {} : cfg.mcpServers["codex-bridge"]) ?? {};
+const KNOWN_ENTRY_NAMES = new Set(["codex-bridge", "codex-bridge-desktop"]);
+const sourceDirectories = new Set([path.join(root, "src"), path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "src")]);
+const runsThisBridge = (entry) => {
+  const script = entry?.args?.[0];
+  if (typeof script !== "string" || !sourceDirectories.has(path.dirname(path.resolve(script)))) return false;
+  const name = path.basename(script);
+  return name === "index.mjs" || name === "mcp-supervisor.mjs" && entry.args[1] === "index.mjs";
+};
+const bridgeEntries = Object.keys(cfg.mcpServers).filter((name) => KNOWN_ENTRY_NAMES.has(name) || runsThisBridge(cfg.mcpServers[name]));
+if (bridgeEntries.length > 1) {
+  throw new Error(`Claude Desktop already has several bridge entries (${bridgeEntries.join(", ")}); remove all but one and re-run. No configuration was changed.`);
+}
+const entryName = bridgeEntries[0] ?? "codex-bridge";
+if (fullAccess) enableCodexFullAccess();
+
+const previousEntry = (reset ? {} : cfg.mcpServers[entryName]) ?? {};
 const previousEnv = previousEntry.env ?? {};
 const settled = (name, fallback) => process.env[name] ?? previousEnv[name] ?? fallback;
 const desktopMode = forceDesktopTasks ? "1" : settled("CODEX_BRIDGE_DESKTOP_TASKS");
@@ -100,7 +115,7 @@ const kept = Object.keys(previousEnv).filter(
     !(desktopEnabled && name === "CODEX_BRIDGE_AUTOSTART"),
 );
 
-cfg.mcpServers["codex-bridge"] = {
+cfg.mcpServers[entryName] = {
   ...previousEntry,
   command: nodeBin,
   args: [path.join(root, "src", "mcp-supervisor.mjs"), "index.mjs"],
@@ -149,7 +164,7 @@ cfg.mcpServers["codex-bridge"] = {
   },
 };
 
-createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...cfg.mcpServers["codex-bridge"].env }) });
+createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...cfg.mcpServers[entryName].env }) });
 
 const backup = `${cfgPath}.bak-${new Date().toISOString().slice(0, 10)}-codexbridge`;
 if (original) {
@@ -170,8 +185,8 @@ try {
 }
 
 console.log(`platform: ${PLATFORM_LABEL}`);
-console.log(`updated ${cfgPath}`);
-console.log(JSON.stringify(cfg.mcpServers["codex-bridge"], null, 2));
+console.log(`updated ${cfgPath} (entry ${entryName})`);
+console.log(JSON.stringify(cfg.mcpServers[entryName], null, 2));
 console.log(`Desktop tasks: ${desktopEnabled ? "enabled" : "disabled"} (${desktopMode === undefined ? "automatic relay configuration" : forceDesktopTasks ? "--desktop-tasks" : "explicit environment setting"}).`);
 
 if (reset) {
@@ -181,7 +196,7 @@ if (reset) {
   console.log("Pass the variable to override one, or --reset to drop them all.");
 }
 
-const writtenRoots = cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_ALLOWED_ROOTS;
+const writtenRoots = cfg.mcpServers[entryName].env.CODEX_BRIDGE_ALLOWED_ROOTS;
 if (writtenRoots.split(path.delimiter).some((entry) => entry.split(path.sep).includes("node_modules"))) {
   console.log(
     "\nWARNING: CODEX_BRIDGE_ALLOWED_ROOTS points inside an install directory, which is not a workspace.\n" +
@@ -190,7 +205,7 @@ if (writtenRoots.split(path.delimiter).some((entry) => entry.split(path.sep).inc
   );
 }
 
-if (cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_THREAD_POLICY === "owned") {
+if (cfg.mcpServers[entryName].env.CODEX_BRIDGE_THREAD_POLICY === "owned") {
   console.log(
     "\nNOTE: thread policy is `owned` - this bridge may only act on threads it created itself.\n" +
       "A thread you open in the Codex app or the VS Code extension will answer NOT AUTHORIZED,\n" +
@@ -200,6 +215,19 @@ if (cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_THREAD_POLICY === "owned") {
   );
 }
 
+if (entryName === "codex-bridge") {
+  const codeConfig = path.join(process.env.CLAUDE_CONFIG_DIR || homeDir(), ".claude.json");
+  let codeEntry;
+  try { codeEntry = JSON.parse(readRegularConfigFile(codeConfig, { missing: true, maxBytes: 8 * 1024 * 1024 }) ?? "{}").mcpServers?.["codex-bridge"]; } catch {}
+  if (codeEntry) {
+    console.log(
+      `\nWARNING: ${codeConfig} also registers codex-bridge for Claude Code. A Desktop entry with the same name can\n` +
+        "shadow it inside Code sessions and hide the calling task. Rename this Desktop entry, for example to\n" +
+        "codex-bridge-desktop; later installer runs update the renamed entry in place.",
+    );
+  }
+}
+
 console.log("\nReconnect codex-bridge once in the existing Claude task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle.");
 console.log("Verify codex_bridge_status from that task: autoReload must be enabled and runtime state must be current. A separate diagnostic process does not verify the app's loaded MCP process.");
 if (desktopEnabled) console.log("Verify Desktop tasks are enabled and the native relay is available. Configuration changes require MCP reconnect even when source auto-reload is enabled; keep the destination task open in Codex Desktop.");

package/scripts/install-native-relay.mjs

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { CodexAppServerClient } from "../src/app-server-client.mjs";
-import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
+import { accountRelaySocketPath, bootstrapRelayThread, desktopTaskSocketPath, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
 import {
   IS_MACOS,
   IS_WINDOWS,
@@ -24,7 +24,7 @@ import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.12";
+const VERSION = "1.22.14";
 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"];
@@ -47,12 +47,15 @@ if (remove) {
   } catch (err) {
     console.log(`${serverName} was not registered (${err.message.trim().split("\n").at(-1)})`);
   }
-  for (const leftover of [relayConfigPath(), ...(IS_WINDOWS ? [] : [relaySocketPath()])]) {
+  const retiredExecutor = readRelayConfig()?.relayThreadId;
+  const sockets = IS_WINDOWS ? [] : [...new Set([relaySocketPath(), desktopTaskSocketPath(), accountRelaySocketPath()])];
+  for (const leftover of [relayConfigPath(), ...sockets]) {
     if (fs.existsSync(leftover)) {
       fs.rmSync(leftover, { force: true });
       console.log(`removed ${leftover}`);
     }
   }
+  if (retiredExecutor) console.log(`archive the retired relay executor task ${retiredExecutor} in Codex Desktop if it is still listed; a reinstall bootstraps a new one`);
   process.exit(0);
 }
 

package/src/bridge-readiness.mjs

@@ -1,3 +1,5 @@
+import { RELAY_DOWN_GUIDANCE } from "./thread-delivery.mjs";
+
 export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = true, verifyTargetProject }) {
   const issues = [];
   if (sender?.status !== "verified") issues.push({ code: "SENDER_UNVERIFIED", detail: sender?.reason ?? "No current Code session identity", action: "Load the user-level Claude Code bridge entry in this existing task; a shared Desktop entry cannot identify the caller. Run the Code registration check, then reload the affected client." });
@@ -18,6 +20,6 @@ export function bridgeReadiness({ sender, scope, targetCwd, nativeAvailable = tr
       issues.push({ code: error.code ?? "PROJECT_SCOPE_UNVERIFIED", detail: error.message, action: "Select a destination in the verified sender's project. A project grant does not authorize cross-project delivery." });
     }
   }
-  if (!nativeAvailable) issues.push({ code: "RELAY_UNAVAILABLE", action: "Open Codex Desktop and check native_relay_status in its existing task." });
+  if (!nativeAvailable) issues.push({ code: "RELAY_UNAVAILABLE", action: RELAY_DOWN_GUIDANCE });
   return { ready: issues.length === 0, readyScope: "transport-identity-and-project", hostToolPermission: "evaluated-by-client-at-call-time", sender, projectPolicy, target, issues };
 }

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.12";
+const VERSION = "1.22.14";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -46,6 +46,7 @@ const peer = new PeerEndpoint({
   name: defaultPeerName,
   cwd: process.env.CLAUDE_BRIDGE_CWD ?? process.cwd(),
   log,
+  signalExit: false,
 });
 
 const codex = new CodexAppServerClient({
@@ -337,7 +338,7 @@ function registerTool(name, definition, handler) {
   });
 }
 
-registerProjectOnboardingTools(registerTool, { beforePrepare: async (extra) => {
+registerProjectOnboardingTools(registerTool, { options: { policyRegistration: "codex" }, beforePrepare: async (extra) => {
   runtime.assertCurrent();
   if (!desktopOnly) throw new Error("Project onboarding requires a verified Desktop caller");
   await assertSender(extra?._meta);
@@ -811,7 +812,7 @@ try {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-exitWhenClientCloses({
+const shutdown = exitWhenClientCloses({
   prepare: () => peer.closeIntake(),
   busy: () => peer.connections.size ? "Peer socket connections are still open"
     : peer.requestQueues.size ? "Claude messages are still being sent"
@@ -819,5 +820,7 @@ exitWhenClientCloses({
   stop: async () => { replyForwarder.close(); peer.stop(); codex.close(); await peer.closed; },
   log,
 });
+let signals = 0;
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => { if (++signals > 1) process.exit(1); void shutdown.close(signal); });
 reload.listen();
 log(`ready on ${PLATFORM_LABEL} as peer "${peer.name}" (${peer.started ? peer.socketPath : "peer endpoint down"})`);

package/src/claude-code-registration.mjs

@@ -1,8 +1,22 @@
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_SOURCE = path.dirname(fileURLToPath(import.meta.url));
 
 function worker(entry) {
   return entry?.args?.length === 2 && path.basename(entry.args[0]) === "mcp-supervisor.mjs" && entry.args[1] === "index.mjs";
 }
+function bridgeSource(entry) {
+  const script = entry?.args?.[0];
+  if (typeof script !== "string" || !(worker(entry) || path.basename(script) === "index.mjs")) return null;
+  return path.dirname(path.resolve(script));
+}
+function bridgeSources(source) {
+  return new Set([PACKAGE_SOURCE, ...(worker(source) ? [bridgeSource(source)] : [])]);
+}
+function bridgeEntry(entry, sources) {
+  return worker(entry) || sources.has(bridgeSource(entry));
+}
 const stable = (value) => JSON.stringify(value, Object.keys(value ?? {}).sort());
 
 export function planCodeRegistration({ code, desktop, policyFile, name = "codex-bridge" }) {
@@ -19,20 +33,27 @@ export function planCodeRegistration({ code, desktop, policyFile, name = "codex-
   const changes = [{ kind: "user-code-entry", name }];
   const comparable = (entry) => {
     const normalized = structuredClone(entry);
+    if (worker(entry) || entry.args.length === 1) normalized.args = [path.join(bridgeSource(entry), "mcp-supervisor.mjs"), "index.mjs"];
     delete normalized.env?.CODEX_BRIDGE_ALLOWED_ROOTS;
     delete normalized.env?.CODEX_BRIDGE_PROJECT_POLICY;
     return JSON.stringify({ ...normalized, env: stable(normalized.env) });
   };
+  const sources = bridgeSources(source);
+  const sameBridge = (entry, location) => {
+    if (bridgeSource(entry) === bridgeSource(source)) return true;
+    if (bridgeEntry(entry, sources)) throw new Error(`${location} runs another bridge installation from ${bridgeSource(entry)}; update or remove it before migration`);
+    return false;
+  };
   for (const [project, config] of Object.entries(updated.projects ?? {})) {
     for (const [alias, entry] of Object.entries(config.mcpServers ?? {})) {
-      if (!worker(entry) || path.resolve(entry.args[0]) !== path.resolve(source.args[0])) continue;
+      if (!sameBridge(entry, `Project ${project} entry ${alias}`)) continue;
       if (comparable(entry) !== comparable(source)) throw new Error(`Project ${project} has a customized ${alias} entry; review its settings instead of replacing it`);
       delete config.mcpServers[alias];
       changes.push({ kind: "remove-duplicate-project-entry", project, name: alias });
     }
   }
   for (const [alias, entry] of Object.entries(updatedDesktop.mcpServers ?? {})) {
-    if (!worker(entry) || path.resolve(entry.args[0]) !== path.resolve(source.args[0])) continue;
+    if (!sameBridge(entry, `Shared Desktop entry ${alias}`)) continue;
     if (comparable(entry) !== comparable(source)) throw new Error(`Shared Desktop entry ${alias} has customized settings; review it before migration`);
     delete updatedDesktop.mcpServers[alias];
     changes.push({ kind: "remove-shared-desktop-entry", name: alias });
@@ -44,10 +65,13 @@ export function checkCodeRegistration({ code, desktop, name = "codex-bridge" })
   const entry = code.mcpServers?.[name];
   const issues = [];
   if (!worker(entry)) issues.push("User-level Claude Code bridge is missing or does not use the supervisor");
-  const shared = Object.keys(desktop.mcpServers ?? {}).filter((key) => worker(desktop.mcpServers[key]));
+  const sources = bridgeSources(entry);
+  const shared = Object.keys(desktop.mcpServers ?? {}).filter((key) => bridgeEntry(desktop.mcpServers[key], sources));
   if (shared.length) issues.push(`Shared Desktop bridge entries can hide the Code caller identity: ${shared.join(", ")}`);
+  const unsupervised = shared.filter((key) => !worker(desktop.mcpServers[key]));
+  if (unsupervised.length) issues.push(`Shared Desktop bridge entries run without the supervisor and keep stale code loaded: ${unsupervised.join(", ")}`);
   const overrides = Object.entries(code.projects ?? {}).flatMap(([project, config]) => Object.entries(config.mcpServers ?? {})
-    .filter(([, item]) => worker(item)).map(([alias]) => ({ project, alias })));
+    .filter(([, item]) => bridgeEntry(item, sources)).map(([alias]) => ({ project, alias })));
   if (overrides.length) issues.push("Project-specific bridge entries override or duplicate the user-level registration");
   if (!entry?.env?.CODEX_BRIDGE_PROJECT_POLICY) issues.push("No shared live project policy configured");
   return { ready: issues.length === 0, issues, shared, overrides, policyFile: entry?.env?.CODEX_BRIDGE_PROJECT_POLICY ?? null };

package/src/codex-mcp-toml.mjs

@@ -175,15 +175,37 @@ function parseStringArray(text, statement) {
   const raw = text.slice(statement.valueStart, statement.valueEnd);
   if (!raw.startsWith("[")) fail("env_vars is not an array");
   const values = [];
+  let lastEnd = null;
+  let trailingComma = false;
   let cursor = skipTrivia(raw, 1);
   while (raw[cursor] !== "]") {
     if (raw[cursor] !== '"' && raw[cursor] !== "'") fail("env_vars must contain only strings");
     const string = readString(raw, cursor);
     values.push(string.value);
+    lastEnd = statement.valueStart + string.end;
     cursor = skipTrivia(raw, string.end);
-    if (raw[cursor] === ",") cursor = skipTrivia(raw, cursor + 1);
+    trailingComma = raw[cursor] === ",";
+    if (trailingComma) cursor = skipTrivia(raw, cursor + 1);
   }
-  return values;
+  return { values, lastEnd, trailingComma, close: statement.valueStart + cursor };
+}
+
+function appendToStringArray(contents, statement, array, missing, newline) {
+  const lineStart = contents.lastIndexOf("\n", array.close - 1) + 1;
+  const closeOwnsLine = lineStart > statement.valueStart && !contents.slice(lineStart, array.close).trim();
+  if (!closeOwnsLine) {
+    if (array.lastEnd === null) return [{ start: statement.valueStart, end: statement.valueEnd, text: tomlArray(missing) }];
+    return [{ start: array.lastEnd, end: array.lastEnd, text: `, ${missing.map(tomlString).join(", ")}` }];
+  }
+  const leading = (index) => contents.slice(index).match(/^[ \t]*/)[0];
+  const elementLine = array.lastEnd === null ? null : contents.lastIndexOf("\n", array.lastEnd - 1) + 1;
+  const indent = elementLine !== null && elementLine > statement.valueStart ? leading(elementLine)
+    : `${leading(contents.lastIndexOf("\n", statement.valueStart - 1) + 1)}  `;
+  const trailing = array.lastEnd === null || array.trailingComma;
+  const lines = missing.map((variable, index) => `${indent}${tomlString(variable)}${index < missing.length - 1 || trailing ? "," : ""}${newline}`).join("");
+  const edits = [{ start: lineStart, end: lineStart, text: lines }];
+  if (array.lastEnd !== null && !array.trailingComma) edits.push({ start: array.lastEnd, end: array.lastEnd, text: "," });
+  return edits;
 }
 
 export function retargetMcpServerToml(contents, name, { command, args, ensureEnvVars = [] }) {
@@ -224,8 +246,8 @@ export function retargetMcpServerToml(contents, name, { command, args, ensureEnv
         if (error instanceof TomlScanError) throw new Error(`The ${name} MCP entry has env_vars that are not a string list; it was not changed`);
         throw error;
       }
-      const missing = ensureEnvVars.filter((variable) => !existing.includes(variable));
-      if (missing.length) edits.push({ start: envVarsStatement.valueStart, end: envVarsStatement.valueEnd, text: tomlArray([...existing, ...missing]) });
+      const missing = [...new Set(ensureEnvVars.filter((variable) => !existing.values.includes(variable)))];
+      if (missing.length) edits.push(...appendToStringArray(contents, envVarsStatement, existing, missing, newline));
     } else {
       const anchor = argsStatement ?? commandStatement;
       const lineBreak = contents.slice(anchor.end - 1, anchor.end) === "\n" ? "" : newline;

package/src/codex-native-response.mjs

@@ -3,13 +3,14 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { scanRollout } from "./rollout-reader.mjs";
+import { scanRollout, isCompressedRollout, rolloutBasePath, asRolloutChange, memoizeCompressedScan } from "./rollout-reader.mjs";
 import { fileIdentity, sameFileIdentity } from "./file-identity.mjs";
 import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable, retryRolloutRead } from "./rollout-segments.mjs";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const MAX_ROLLOUT_BYTES = 16 * 1024 * 1024;
 const MAX_REPLY_BYTES = 1024 * 1024;
+const MAX_CACHED_RECORD_BYTES = 1024 * 1024;
 const DESKTOP_ORIGINATORS = new Set(["Codex Desktop", "codex_work_desktop"]);
 const COMPLETED = new Set(["task_complete", "task_completed", "turn_complete", "turn_completed"]);
 const STARTED = new Set(["task_started", "turn_started"]);
@@ -59,6 +60,14 @@ function pathIdentity(candidate, kind) {
 }
 
 function capturePathBoundary(file, sessions) {
+  try {
+    return readPathBoundary(file, sessions);
+  } catch (error) {
+    throw asRolloutChange(error, "The Codex rollout changed while reading");
+  }
+}
+
+function readPathBoundary(file, sessions) {
   const resolvedFile = fs.realpathSync.native(file);
   const relative = path.relative(sessions, resolvedFile);
   if (relative.startsWith("..") || path.isAbsolute(relative) || path.relative(file, resolvedFile)) throw new Error("The Codex rollout path escapes its sessions directory");
@@ -95,10 +104,20 @@ function readStableRolloutSet(threadId, env, readSegments) {
   });
 }
 
-function readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefixSize, dispatchOutputs, dispatchAfterOffset }) {
+function readStableOnce(found, maxBytes, options) {
   const { file, sessions } = found;
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_ROLLOUT_BYTES) throw new Error("The Codex rollout read limit is invalid");
   const beforeBoundary = capturePathBoundary(file, sessions);
+  const key = crypto.createHash("sha256").update(JSON.stringify({ maxBytes, ...options })).digest("hex");
+  const scanned = memoizeCompressedScan(file, `native:${key}`, () => scanSegment(file, maxBytes, options), { keep: (value) => value.retainedBytes <= MAX_CACHED_RECORD_BYTES });
+  const afterBoundary = capturePathBoundary(file, sessions);
+  if (!samePathBoundary(beforeBoundary, afterBoundary) || !sameFileIdentity(scanned.identity, beforeBoundary.file)) {
+    throw new Error("The Codex rollout changed while reading");
+  }
+  return { ...scanned, file, sessions };
+}
+
+function scanSegment(file, maxBytes, { threadId, turnId, afterOffset, prefixSize, dispatchOutputs, dispatchAfterOffset }) {
   const records = [];
   const dispatches = [];
   const otherTurnStarts = [];
@@ -139,11 +158,7 @@ function readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefix
       }
     },
   });
-  const afterBoundary = capturePathBoundary(file, sessions);
-  if (!samePathBoundary(beforeBoundary, afterBoundary) || !sameFileIdentity(snapshot.identity, beforeBoundary.file)) {
-    throw new Error("The Codex rollout changed while reading");
-  }
-  return { ...snapshot, file, sessions, records, dispatches, otherTurnStarts, retainedBytes, session, latestContext, turnBeforeWatermark, prefixSha256: digest.digest("hex") };
+  return { ...snapshot, records, dispatches, otherTurnStarts, retainedBytes, session, latestContext, turnBeforeWatermark, prefixSha256: digest.digest("hex") };
 }
 
 function canonicalDirectory(value, label) {
@@ -175,6 +190,22 @@ function uniqueTurn(snapshots) {
   return selected[0];
 }
 
+function segmentMark(marks, file) {
+  return marks.find((mark) => rolloutBasePath(mark.file) === rolloutBasePath(file));
+}
+
+function validSegmentMarks(marks, watermark) {
+  return Array.isArray(marks) && marks.length && marks.length <= 64 && marks.every((mark) => object(mark) && typeof mark.file === "string") &&
+    new Set(marks.map((mark) => rolloutBasePath(mark.file))).size === marks.length &&
+    marks.some((mark) => mark.file === watermark.file && mark.size === watermark.size && mark.prefixSha256 === watermark.prefixSha256);
+}
+
+function assertMarkedPrefix(snapshot, mark) {
+  const sameStorage = isCompressedRollout(snapshot.file) === isCompressedRollout(mark.file);
+  if ((sameStorage && !sameFileIdentity(snapshot.identity, mark.identity)) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
+  if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
+}
+
 function delegationOutputs(executorThreadId, prompt) {
   const escaped = prompt.replace(/[&<>]/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[character]);
   // Older Desktop rollouts stored raw text; current builds escape XML text content.
@@ -422,19 +453,14 @@ export function resolveCodexNativeDispatchResponse(binding, { env = process.env,
     const cwd = canonicalDirectory(expectedCwd, "The selected native task workspace");
     if (watermark.cwd !== cwd) throw new Error("The selected native task workspace changed after dispatch");
     const marks = watermark.segments ?? [watermark];
-    if (!Array.isArray(marks) || !marks.length || marks.length > 64 || new Set(marks.map((mark) => mark.file)).size !== marks.length ||
-        !marks.some((mark) => mark.file === watermark.file && mark.size === watermark.size && mark.prefixSha256 === watermark.prefixSha256) ||
-        marks.some((mark) => !Number.isSafeInteger(mark.size) || mark.size < 1)) throw new Error("The pre-send segment watermarks are invalid");
+    if (!validSegmentMarks(marks, watermark) || marks.some((mark) => !Number.isSafeInteger(mark.size) || mark.size < 1)) throw new Error("The pre-send segment watermarks are invalid");
     const outputs = delegationOutputs(executorThreadId, prompt);
     const snapshots = readStableRolloutSet(threadId, env, (found) => {
-      if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
+      if (marks.some((mark) => !segmentMark(found, mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
       return found.map((entry) => {
-        const mark = marks.find(({ file }) => file === entry.file);
+        const mark = segmentMark(marks, entry.file);
         const snapshot = readStable(entry, maxRolloutBytes, { threadId, afterOffset: mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs });
-        if (mark) {
-          if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
-          if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
-        }
+        if (mark) assertMarkedPrefix(snapshot, mark);
         validateIdentity(snapshot, threadId, cwd, desktopEvidence);
         return snapshot;
       });
@@ -464,23 +490,18 @@ export function readCodexNativeTurnResponse({ threadId, turnId, previousTurnId,
     const cwd = canonicalDirectory(expectedCwd, "The selected native task workspace");
     if (watermark.cwd !== cwd) throw new Error("The selected native task workspace changed after dispatch");
     const marks = watermark.segments ?? [watermark];
-    if (!Array.isArray(marks) || !marks.length || marks.length > 64
-        || new Set(marks.map((mark) => mark.file)).size !== marks.length
-        || !marks.some((mark) => mark.file === watermark.file && mark.size === watermark.size && mark.prefixSha256 === watermark.prefixSha256)) throw new Error("The pre-send segment watermarks are invalid");
+    if (!validSegmentMarks(marks, watermark)) throw new Error("The pre-send segment watermarks are invalid");
     for (const mark of marks) if (!Number.isSafeInteger(mark.size) || mark.size < 1) throw new Error("The pre-send rollout watermark size is invalid");
     const outputs = delegationOutputs(executorThreadId, prompt);
     const snapshots = readStableRolloutSet(threadId, env, (found) => {
-      if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
+      if (marks.some((mark) => !segmentMark(found, mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
       let retainedBytes = 0;
       return found.map((entry) => {
-        const mark = marks.find(({ file }) => file === entry.file);
+        const mark = segmentMark(marks, entry.file);
         const snapshot = readStable(entry, maxRolloutBytes, { threadId, turnId, afterOffset: existingTurn ? 0 : mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs, dispatchAfterOffset: mark?.size ?? 0 });
         retainedBytes += snapshot.retainedBytes;
         if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
-        if (mark) {
-          if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
-          if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
-        }
+        if (mark) assertMarkedPrefix(snapshot, mark);
         if (snapshot.turnBeforeWatermark) throw new Error("The observed turn was already present before dispatch");
         validateIdentity(snapshot, threadId, cwd, desktopEvidence);
         return snapshot;
@@ -490,7 +511,7 @@ export function readCodexNativeTurnResponse({ threadId, turnId, previousTurnId,
     const matchedDispatches = snapshots.flatMap((snapshot) => snapshot.dispatches);
     if (matchedDispatches.length !== 1 || matchedDispatches[0].turnId !== turnId) throw new Error("The observed turn is not uniquely correlated to the exact native dispatch");
     validateSession(selected, threadId, cwd, desktopEvidence);
-    const selectedMark = marks.find(({ file }) => file === selected.file);
+    const selectedMark = segmentMark(marks, selected.file);
     if (existingTurn && !selectedMark) throw new Error("The active native turn has no pre-send rollout watermark");
     dispatchObserved = selected.records.some(({ record, start }) => start >= (selectedMark?.size ?? 0) &&
       record.type === "response_item" && record.payload.type === "function_call_output" &&

package/src/codex-sender-context.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { scanRollout } from "./rollout-reader.mjs";
+import { scanRollout, memoizeCompressedScan } from "./rollout-reader.mjs";
 import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable, retryRolloutRead } from "./rollout-segments.mjs";
 
 const METADATA_KEY = "x-codex-turn-metadata";
@@ -38,7 +38,7 @@ function reviewFlag(metadata, field) {
 
 export function findRollout(sessions, threadId) {
   const files = findRolloutSegments(sessions, threadId);
-  if (files.length !== 1) throw new Error("Multiple rollouts match the calling Codex task");
+  if (files.length !== 1) throw new Error("Multiple rollouts match the Codex task");
   return files[0];
 }
 
@@ -48,7 +48,18 @@ export function readState(file, maxBytes) {
   return retryRolloutRead(() => readStateOnce(file, maxBytes));
 }
 
+export function readTaskState(sessions, threadId, maxBytes) {
+  return retryRolloutRead(() => {
+    const file = findRollout(sessions, threadId);
+    return { ...readStateOnce(file, maxBytes), file };
+  });
+}
+
 function readStateOnce(file, maxBytes) {
+  return memoizeCompressedScan(file, `state:${maxBytes}`, () => scanState(file, maxBytes));
+}
+
+function scanState(file, maxBytes) {
   let session, context, lifecycle;
   const snapshot = scanRollout(file, {
     maxRecordBytes: maxBytes,