@minhspark/codex-mcp-bridge 1.22.11 → 1.22.12

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,28 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.12] - 2026-10-20
+
+### Fixed
+
+- Move directly registered Codex entries to the supervisor. `claude-mcp-bridge-install` and `codex-native-relay-install` used to refuse an existing `codex-native-relay` entry that had `env_vars`, the very setting the README told users to add, and `codex mcp add` drops `env_vars` and every comment in `config.toml`. When the environment does not change, the installers now edit only `command` and `args` of the existing table in place, read the entry back through `codex mcp get --json`, and restore the previous file if anything differs. Seen on 2026-10-20: both Codex-side entries still pointed at `src/claude-bridge.mjs` and `src/native-relay-companion.mjs`, so `claude-bridge` stayed `1.22.8 STALE` after v1.22.10 until Codex Desktop restarted.
+- On Windows and macOS, `codex-native-relay-install` adds `CODEX_APP_TOOLS_PIPE_PATH` to the relay's `env_vars` itself, by name only, instead of asking for a hand edit.
+- An entry written as an inline table or with dotted keys, which the in-place edit does not handle, still goes through `codex mcp add` when that loses nothing; if the relay's `env_vars` cannot then be added, the installer says so instead of failing. Datetimes written with a space instead of `T` no longer stop the scan.
+- Keep relay requests and peer messages that reach the listener while a reload quiesces. A client whose connection was still in the kernel's accept queue when the listener closed was reset: the relay client reported `RELAY_DELIVERY_UNCONFIRMED` for a request the companion never read, and a Claude peer message was lost after a successful write. Quiesce now removes the socket path first, waits a few event-loop turns for queued connections, answers relay clients with `RELAY_RELOADING` (no message sent), and reads peer messages into the inbox that the next worker restores. A relay client answered with `RELAY_RELOADING` during reload also no longer keeps the old listener from closing. The relay now binds a private name and hard-links it to the public path, because closing a Unix socket server unlinks the path it was bound to; a companion that binds the public path while a reload drains keeps its socket.
+
+### Verification
+
+- 18 new tests. The installer tests run both installers against a fake `codex` and a live-shaped `config.toml`; 7 tests fail on v1.22.10. The race tests block the event loop while a client connects and writes, then quiesce; the relay and peer cases fail on v1.22.10 with `write EPIPE` and an empty inbox. A successor companion's socket survives the old listener closing; that test fails when the relay binds the public path directly.
+- Both installers were also run against the real Codex CLI 0.163.0 with a temporary `CODEX_HOME`, covering a CRLF file, a multi-line `args` array with comments, a rerun and a fresh install. Only `command`, `args` and the added `env_vars` changed.
+- An independent review of reload safety covered the relay, the peer endpoint and the supervisor. Two of five claims survived two refutation attempts each; both are fixed above. A second review of this change found three more defects that survived refutation: inline-table entries refused, space-separated datetimes refused, and the close-time unlink of a successor's socket. All three are fixed, each with a test.
+
+- CodeQL reported a file-system race in the first version of the config write: it checked the file, then wrote it by path. The installer now reads `config.toml` through one file descriptor, keeps its device, inode, mode and contents, and checks all four again through a new descriptor just before the atomic rename. The remaining `js/path-injection` reports on the config and relay socket paths come from operator configuration (`CODEX_HOME`, `CODEX_NATIVE_RELAY_SOCKET` or the home directory) and were dismissed as false positives, as in earlier releases.
+
+### Limitations
+
+- Windows named pipes cannot be removed from the namespace before the listener closes, so a client that connects in the last moment before close can still be reset there. It is reported as unconfirmed, never as delivered.
+- Moving an entry to the supervisor needs one Codex Desktop restart. The installer does not touch an entry whose environment must also change while it has custom `env_vars`, `cwd`, tool filters or timeouts; it prints the exact `command` and `args` to set by hand.
+
 ## [1.22.11] - 2026-10-20
 
 ### Fixed

package/README.md

@@ -116,14 +116,14 @@ Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
 
 ### Native relay pipe forwarding
 
-Add this to the relay's **existing** entry in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`), keeping its `command`, `args`, and other settings:
+On Windows and macOS, `codex-native-relay-install` adds this to the relay's entry in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and keeps its other settings:
 
 ```toml
 [mcp_servers.codex-native-relay]
 env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
 ```
 
-Append the variable name if `env_vars` already exists. Reconnect the relay in Codex Desktop after editing.
+If you register the relay by hand, add the same line and append the variable name if `env_vars` already exists. Only the name is saved, never the temporary pipe path. Restart Codex Desktop after active work finishes so it relaunches the relay.
 
 ### Linux / WSL (Bash)
 

package/docs/new-macos-setup.md

@@ -22,10 +22,11 @@ connector. For a local Desktop installation, use the following path instead:
    `CODEX_BRIDGE_ALLOWED_ROOTS`, rather than the example's entire home directory;
    macOS separates multiple roots with `:`. Preserve an existing entry's
    custom settings.
-4. Add [native relay pipe forwarding](../README.md#native-relay-pipe-forwarding)
-   to the existing relay entry. Forward `CODEX_APP_TOOLS_PIPE_PATH` by name,
-   not its temporary value. The relay needs the trusted app-bundled Node runtime
-   selected by the installer; do not substitute an arbitrary Homebrew/nvm Node.
+4. Check that the relay entry has
+   [native relay pipe forwarding](../README.md#native-relay-pipe-forwarding).
+   The installer adds `CODEX_APP_TOOLS_PIPE_PATH` by name, never its temporary
+   value. The relay needs the trusted app-bundled Node runtime selected by the
+   installer; do not substitute an arbitrary Homebrew/nvm Node.
 5. Reconnect the affected MCP servers in the actual Desktop Code conversations,
    or restart the affected app after active work finishes. Complete
    [installation verification](../README.md#verify-the-installation), including

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.11",
+  "version": "1.22.12",
   "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.11",
+  "version": "1.22.12",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-codex-mcp.mjs

@@ -7,9 +7,9 @@ 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 { codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { applyStdioMcpRegistration, codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
-import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { codexAccessPaths, enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
 import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
@@ -43,12 +43,12 @@ const existing = servers.some((server) => server.name === serverName)
   ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
 const registration = codexMcpRegistration({ name: serverName, existing, node: nodeBin, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
-run(registration.args);
+const applied = applyStdioMcpRegistration({ name: serverName, registration, existing, run, configPath: codexAccessPaths().config });
 
 console.log(`platform: ${PLATFORM_LABEL}`);
-console.log(`registered MCP server "${serverName}" with Codex:`);
+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(`command: ${nodeBin} ${entry} ${entryArgs.join(" ")}`);
 console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
-console.log("\nReconnect claude-bridge once in the existing Codex Desktop task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle. Do not create a replacement task.");
-console.log("Verify claude_bridge_status from that task: autoReload must be enabled, runtime state must be current, and the session policy must match this installation. A separate diagnostic process does not verify the app's loaded MCP process.");
+console.log("\nOne-time step: after active Codex work finishes, quit and reopen Codex Desktop once so it starts the supervisor. Later compatible installed updates reload automatically when the worker is idle. Do not create a replacement task.");
+console.log("Verify claude_bridge_status from an existing task: it must report \"automatic reload: current\" with a supervisor pid, runtime state current, and the session policy of this installation. A separate diagnostic process does not verify the app's loaded MCP process.");
 console.log(`remove: node scripts/install-codex-mcp.mjs --remove`);

package/scripts/install-native-relay.mjs

@@ -17,14 +17,14 @@ import {
   spawnEnv,
 } from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
-import { stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
+import { applyStdioMcpRegistration, stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
-import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { codexAccessPaths, enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
 import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.11";
+const VERSION = "1.22.12";
 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"];
@@ -80,16 +80,12 @@ const existingServer = servers.some((server) => server.name === serverName)
  */
 const runtime = resolveCodexDesktopNodeBin();
 
-if (IS_MACOS || IS_WINDOWS) {
-  console.log(`Native Desktop setup: in ${path.join(homeDir(), ".codex", "config.toml")} (or CODEX_HOME/config.toml), add env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"] to the existing [mcp_servers.${serverName}] entry after registration.`);
-  console.log("Preserve existing settings and append the name to any existing env_vars list; do not save the temporary pipe path. Reconnect the relay or restart Codex Desktop after active work finishes, then check native_relay_status in the existing task.");
-}
-
 const registration = stdioMcpRegistration({ name: serverName, existing: existingServer, node: runtime.path, entry, entryArgs, envOverrides: {
   ...(process.env.CLAUDE_DESKTOP_USER_DATA !== undefined ? { CLAUDE_DESKTOP_USER_DATA: process.env.CLAUDE_DESKTOP_USER_DATA } : {}),
 } });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
-run(registration.args);
+const ensureEnvVars = IS_MACOS || IS_WINDOWS ? ["CODEX_APP_TOOLS_PIPE_PATH"] : [];
+const applied = applyStdioMcpRegistration({ name: serverName, registration, existing: existingServer, run, configPath: codexAccessPaths().config, ensureEnvVars });
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`relay runtime: ${runtime.path} (${runtime.source})`);
@@ -105,8 +101,10 @@ if (runtime.source === "process.execPath" && hasCodexDesktopApp()) {
   );
   console.log("runtime shipped inside Codex Desktop if that happens.");
 }
-console.log(`registered MCP server "${serverName}" with Codex:`);
+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 (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.`);
 
 const existing = readRelayConfig()?.relayThreadId;
 if (existing) {
@@ -134,5 +132,5 @@ if (process.argv.includes("--desktop-tasks")) {
   writeRelayConfig({ ...readRelayConfig(), desktopTasks: true });
   console.log("Desktop task creation enabled: exact saved local projects, immediate visibility, Codex Desktop permissions.");
 }
-console.log("Reconnect codex-native-relay once in the existing Codex Desktop task to load the supervisor, then verify native_relay_status reports autoReload enabled. Subsequent compatible installed-source updates reload automatically when safely idle.");
+console.log("One-time step: after active Codex work finishes, quit and reopen Codex Desktop once so it starts the supervisor. Then call native_relay_status in an existing task: it must report \"automatic reload: current\" with a supervisor pid. Later compatible installed updates reload automatically when the relay is idle.");
 console.log("remove: node scripts/install-native-relay.mjs --remove");

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.11";
+const VERSION = "1.22.12";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/codex-mcp-registration.mjs

@@ -1,18 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+import { retargetMcpServerToml } from "./codex-mcp-toml.mjs";
+
+const PRESERVED_FIELDS = ["enabled", "disabled_reason", "enabled_tools", "disabled_tools", "startup_timeout_sec", "tool_timeout_sec"];
+
+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]);
+}
+
+function addLosesSettings(existing) {
+  const customized = ["enabled_tools", "disabled_tools", "startup_timeout_sec", "tool_timeout_sec", "disabled_reason"]
+    .some((key) => existing[key] != null && (!Array.isArray(existing[key]) || existing[key].length > 0));
+  return existing.enabled === false || customized || Boolean(existing.transport?.cwd) || Boolean(existing.transport?.env_vars?.length);
+}
+
 export function stdioMcpRegistration({ name, existing, node, entry, entryArgs = [], envOverrides = {} }) {
-  if (existing) {
-    const customized = ["enabled_tools", "disabled_tools", "startup_timeout_sec", "tool_timeout_sec", "disabled_reason"]
-      .some((key) => existing[key] != null && (!Array.isArray(existing[key]) || existing[key].length > 0));
-    if (existing.enabled === false || customized || existing.transport?.type !== "stdio" || existing.transport?.cwd || existing.transport?.env_vars?.length) {
-      throw new Error(`The existing MCP entry has custom access, timeout, or transport settings. The installer will not remove or reset it. Keep those settings and update only command=${JSON.stringify(node)} and args=${JSON.stringify([entry, ...entryArgs])} in the existing entry, then reconnect that MCP server once.`);
-    }
-  }
   const values = { ...existing?.transport?.env, ...envOverrides };
-  const args = ["mcp", "add", name];
-  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [key, value] of Object.entries(values)) {
     if (typeof value !== "string") throw new Error(`MCP environment value ${key} must be a string`);
-    args.push("--env", `${key}=${value}`);
   }
-  return { args: [...args, "--", node, entry, ...entryArgs], environment: values, environmentKeys: Object.keys(values).sort() };
+  const commandArgs = [entry, ...entryArgs];
+  const manual = `Keep those settings and update only command=${JSON.stringify(node)} and args=${JSON.stringify(commandArgs)} in the existing entry, then restart Codex Desktop once.`;
+  const plan = { command: node, commandArgs, environment: values, environmentKeys: Object.keys(values).sort(), manual };
+  const addIsSafe = !existing || existing.transport?.type === "stdio" && !addLosesSettings(existing);
+  const addArgs = ["mcp", "add", name];
+  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) addArgs.push("--env", `${key}=${value}`);
+  const add = addIsSafe ? { args: [...addArgs, "--", node, ...commandArgs] } : {};
+  if (existing?.transport?.type === "stdio" && sameEnvironment(existing.transport.env, values)) return { ...plan, ...add, mode: "retarget" };
+  if (!addIsSafe) throw new Error(`The existing MCP entry has custom access, timeout, or transport settings. The installer will not remove or reset it. ${manual}`);
+  return { ...plan, ...add, mode: "add" };
 }
 
 export function codexMcpRegistration({ name, existing, node, entry, entryArgs = [], env, desktopOnly }) {
@@ -28,3 +45,105 @@ export function codexMcpRegistration({ name, existing, node, entry, entryArgs =
   if (values.CODEX_BRIDGE_DESKTOP_TASKS === "1") values.CODEX_BRIDGE_AUTOSTART = "0";
   return stdioMcpRegistration({ name, existing, node, entry, entryArgs, envOverrides: values });
 }
+
+function readConfigSnapshot(configPath) {
+  let descriptor;
+  try { descriptor = fs.openSync(configPath, "r"); }
+  catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  try {
+    const stats = fs.fstatSync(descriptor, { bigint: true });
+    return { path: fs.realpathSync.native(configPath), contents: fs.readFileSync(descriptor, "utf8"), dev: stats.dev, ino: stats.ino, mode: Number(stats.mode & 0o777n) };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function writeConfigAtomically(snapshot, next) {
+  const temporary = path.join(path.dirname(snapshot.path), `.${path.basename(snapshot.path)}.bridge-${process.pid}.tmp`);
+  fs.writeFileSync(temporary, next, { encoding: "utf8", mode: snapshot.mode, flag: "wx" });
+  try {
+    const current = readConfigSnapshot(snapshot.path);
+    if (!current || current.dev !== snapshot.dev || current.ino !== snapshot.ino || current.contents !== snapshot.contents) {
+      throw new Error("The Codex configuration changed while the installer was updating it; nothing was changed. Run the installer again.");
+    }
+    fs.renameSync(temporary, snapshot.path);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function verificationErrors(before, after, registration, ensureEnvVars) {
+  const errors = [];
+  const transport = after?.transport ?? {};
+  if (transport.type !== "stdio") errors.push("transport is no longer stdio");
+  if (transport.command !== registration.command) errors.push(`command is ${JSON.stringify(transport.command)}`);
+  if (JSON.stringify(transport.args ?? []) !== JSON.stringify(registration.commandArgs)) errors.push(`args are ${JSON.stringify(transport.args)}`);
+  if (!sameEnvironment(transport.env, registration.environment)) errors.push("the environment block changed");
+  const envVars = transport.env_vars ?? [];
+  for (const variable of [...(before?.transport?.env_vars ?? []), ...ensureEnvVars]) {
+    if (!envVars.includes(variable)) errors.push(`env_vars lost ${variable}`);
+  }
+  if (before) {
+    if ((transport.cwd ?? null) !== (before.transport?.cwd ?? null)) errors.push("cwd changed");
+    for (const field of PRESERVED_FIELDS) {
+      if (JSON.stringify(after[field] ?? null) !== JSON.stringify(before[field] ?? null)) errors.push(`${field} changed`);
+    }
+  }
+  return errors;
+}
+
+export function applyStdioMcpRegistration({ name, registration, existing, run, configPath, ensureEnvVars = [] }) {
+  const original = readConfigSnapshot(configPath);
+  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;
+    writeConfigAtomically(current, next);
+    return true;
+  };
+  let mode = registration.mode;
+  let mutated = false;
+  let edited = false;
+  let envVarsAdded = ensureEnvVars.length === 0;
+  let notice = null;
+  try {
+    if (mode === "retarget") {
+      try {
+        edited = editInPlace();
+        mutated = edited;
+        envVarsAdded = true;
+      } catch (error) {
+        if (!registration.args) throw new Error(`${error.message}. ${registration.manual}`);
+        mode = "add";
+      }
+    }
+    if (mode === "add") {
+      run(registration.args);
+      mutated = true;
+      if (!envVarsAdded) {
+        try {
+          edited = editInPlace() || edited;
+          envVarsAdded = true;
+        } catch (error) {
+          notice = `Add env_vars = ${JSON.stringify(ensureEnvVars)} to the ${name} entry by hand (${error.message}).`;
+        }
+      }
+    }
+    const errors = verificationErrors(existing, JSON.parse(run(["mcp", "get", name, "--json"])), registration, envVarsAdded ? ensureEnvVars : []);
+    if (errors.length) throw new Error(`Codex did not read back the expected ${name} entry (${errors.join("; ")})`);
+  } catch (error) {
+    if (!mutated) throw error;
+    const current = readConfigSnapshot(configPath);
+    if (original === null) fs.rmSync(configPath, { force: true });
+    else if (current) writeConfigAtomically(current, original.contents);
+    else fs.writeFileSync(original.path, original.contents, { encoding: "utf8", mode: original.mode, flag: "wx" });
+    throw new Error(`${error.message}; the previous Codex configuration was restored`);
+  }
+  return { mode, edited, envVarsAdded, notice };
+}

package/src/codex-mcp-toml.mjs

@@ -0,0 +1,239 @@
+const BARE_KEY = /[A-Za-z0-9_-]/;
+const WHITESPACE = /[ \t]/;
+
+class TomlScanError extends Error {}
+
+function fail(message) {
+  throw new TomlScanError(message);
+}
+
+function skipWhitespace(text, index) {
+  while (index < text.length && WHITESPACE.test(text[index])) index++;
+  return index;
+}
+
+function lineEnd(text, index) {
+  const newline = text.indexOf("\n", index);
+  return newline === -1 ? text.length : newline + 1;
+}
+
+function readString(text, index) {
+  const quote = text[index];
+  const multiline = text.startsWith(quote.repeat(3), index);
+  const delimiter = multiline ? quote.repeat(3) : quote;
+  let cursor = index + delimiter.length;
+  let value = "";
+  while (cursor < text.length) {
+    if (text.startsWith(delimiter, cursor)) {
+      let end = cursor + delimiter.length;
+      if (multiline) while (text[end] === quote && end - cursor < 5) end++;
+      if (multiline) value += quote.repeat(end - cursor - 3);
+      return { end, value };
+    }
+    const character = text[cursor];
+    if (!multiline && (character === "\n" || character === "\r")) fail("Unterminated single-line string");
+    if (quote === '"' && character === "\\") {
+      const escape = text[cursor + 1];
+      const simple = { b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", e: "\u001b", '"': '"', "\\": "\\" };
+      if (escape in simple) { value += simple[escape]; cursor += 2; continue; }
+      const width = escape === "u" ? 4 : escape === "U" ? 8 : escape === "x" ? 2 : 0;
+      if (width) {
+        const hex = text.slice(cursor + 2, cursor + 2 + width);
+        if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(hex)) fail("Invalid string escape");
+        value += String.fromCodePoint(Number.parseInt(hex, 16));
+        cursor += 2 + width;
+        continue;
+      }
+      if (multiline && /[ \t\r\n]/.test(escape)) {
+        let next = cursor + 1;
+        while (next < text.length && /[ \t]/.test(text[next])) next++;
+        if (text[next] === "\r") next++;
+        if (text[next] !== "\n") fail("Invalid line-ending backslash");
+        while (next < text.length && /[ \t\r\n]/.test(text[next])) next++;
+        cursor = next;
+        continue;
+      }
+      fail("Invalid string escape");
+    }
+    value += character;
+    cursor++;
+  }
+  return fail("Unterminated string");
+}
+
+function readKey(text, index, terminator) {
+  const parts = [];
+  let cursor = skipWhitespace(text, index);
+  for (;;) {
+    if (text[cursor] === '"' || text[cursor] === "'") {
+      if (text.startsWith(text[cursor].repeat(3), cursor)) fail("Multi-line strings are not valid keys");
+      const string = readString(text, cursor);
+      parts.push(string.value);
+      cursor = string.end;
+    } else {
+      const start = cursor;
+      while (cursor < text.length && BARE_KEY.test(text[cursor])) cursor++;
+      if (cursor === start) fail("Invalid key");
+      parts.push(text.slice(start, cursor));
+    }
+    cursor = skipWhitespace(text, cursor);
+    if (text[cursor] === ".") { cursor = skipWhitespace(text, cursor + 1); continue; }
+    if (!text.startsWith(terminator, cursor)) fail(`Expected ${terminator} after key`);
+    return { parts, end: cursor + terminator.length };
+  }
+}
+
+function skipTrivia(text, index) {
+  let cursor = index;
+  for (;;) {
+    cursor = skipWhitespace(text, cursor);
+    if (text[cursor] === "#") cursor = lineEnd(text, cursor);
+    else if (text[cursor] === "\r" || text[cursor] === "\n") cursor++;
+    else return cursor;
+  }
+}
+
+function readValue(text, index) {
+  const character = text[index];
+  if (character === '"' || character === "'") return { end: readString(text, index).end };
+  if (character === "[" || character === "{") {
+    const close = character === "[" ? "]" : "}";
+    let cursor = skipTrivia(text, index + 1);
+    while (text[cursor] !== close) {
+      if (cursor >= text.length) fail("Unterminated array or inline table");
+      if (close === "}") {
+        const key = readKey(text, cursor, "=");
+        cursor = skipWhitespace(text, key.end);
+      }
+      cursor = skipTrivia(text, readValue(text, cursor).end);
+      if (text[cursor] === ",") cursor = skipTrivia(text, cursor + 1);
+      else if (text[cursor] !== close) fail("Expected a separator in an array or inline table");
+    }
+    return { end: cursor + 1 };
+  }
+  let cursor = index;
+  const scalar = () => { while (cursor < text.length && !/[ \t\r\n#,\]}]/.test(text[cursor])) cursor++; };
+  scalar();
+  if (cursor === index) fail("Missing value");
+  if (/^\d{4}-\d{2}-\d{2}$/.test(text.slice(index, cursor)) && /^ \d{2}:\d{2}/.test(text.slice(cursor, cursor + 6))) {
+    cursor++;
+    scalar();
+  }
+  return { end: cursor };
+}
+
+function scan(text) {
+  const statements = [];
+  let cursor = text.startsWith("\uFEFF") ? 1 : 0;
+  while (cursor < text.length) {
+    const start = cursor;
+    const content = skipWhitespace(text, cursor);
+    const character = text[content];
+    if (content >= text.length || character === "\n" || character === "\r" || character === "#") {
+      cursor = lineEnd(text, content);
+      continue;
+    }
+    if (character === "[") {
+      const array = text[content + 1] === "[";
+      const key = readKey(text, content + (array ? 2 : 1), array ? "]]" : "]");
+      statements.push({ kind: array ? "array-table" : "table", path: key.parts, start });
+      cursor = lineEnd(text, key.end);
+      continue;
+    }
+    const key = readKey(text, content, "=");
+    const valueStart = skipWhitespace(text, key.end);
+    const { end: valueEnd } = readValue(text, valueStart);
+    const tail = skipWhitespace(text, valueEnd);
+    if (tail < text.length && !["\r", "\n", "#"].includes(text[tail])) fail("Unexpected text after a value");
+    cursor = lineEnd(text, valueEnd);
+    statements.push({ kind: "value", path: key.parts, start, valueStart, valueEnd, end: cursor });
+  }
+  return statements;
+}
+
+export function scanTomlStatements(text) {
+  try { return scan(text); }
+  catch (error) {
+    if (error instanceof TomlScanError) throw new Error(`The Codex configuration could not be scanned safely (${error.message}); it was not changed`);
+    throw error;
+  }
+}
+
+function samePath(left, right) {
+  return left.length === right.length && left.every((part, index) => part === right[index]);
+}
+
+export function tomlString(value) {
+  return JSON.stringify(String(value)).replaceAll("\u007f", "\\u007F");
+}
+
+function tomlArray(values) {
+  return `[${values.map(tomlString).join(", ")}]`;
+}
+
+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 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);
+    cursor = skipTrivia(raw, string.end);
+    if (raw[cursor] === ",") cursor = skipTrivia(raw, cursor + 1);
+  }
+  return values;
+}
+
+export function retargetMcpServerToml(contents, name, { command, args, ensureEnvVars = [] }) {
+  const statements = scanTomlStatements(contents);
+  const serverPath = ["mcp_servers", name];
+  const headers = statements.filter((statement) => statement.kind !== "value");
+  const owners = headers.filter((statement) => statement.kind === "table" && samePath(statement.path, serverPath));
+  if (owners.length !== 1) throw new Error(`Expected exactly one [mcp_servers.${name}] table in the Codex configuration; it was not changed`);
+  const header = owners[0];
+  const sectionEnd = headers.find((statement) => statement.start > header.start)?.start ?? contents.length;
+  const section = statements.filter((statement) => statement.kind === "value" && statement.start > header.start && statement.start < sectionEnd);
+  for (const statement of statements) {
+    if (statement.kind !== "value" || section.includes(statement)) continue;
+    const owner = headers.filter((candidate) => candidate.start < statement.start).at(-1);
+    const fullPath = [...(owner?.kind === "table" ? owner.path : []), ...statement.path];
+    if (samePath(fullPath, serverPath) || ["command", "args", "env_vars"].some((key) => samePath(fullPath, [...serverPath, key]))) {
+      throw new Error(`The ${name} MCP entry is also defined outside its table; it was not changed`);
+    }
+  }
+  const find = (key) => {
+    const matches = section.filter((statement) => samePath(statement.path, [key]));
+    if (matches.length > 1) throw new Error(`The ${name} MCP entry defines ${key} more than once; it was not changed`);
+    return matches[0];
+  };
+  const commandStatement = find("command");
+  const argsStatement = find("args");
+  if (!commandStatement) throw new Error(`The ${name} MCP entry has no command; it was not changed`);
+  const newline = contents.includes("\r\n") ? "\r\n" : "\n";
+  const edits = [{ start: commandStatement.valueStart, end: commandStatement.valueEnd, text: tomlString(command) }];
+  if (argsStatement) edits.push({ start: argsStatement.valueStart, end: argsStatement.valueEnd, text: tomlArray(args) });
+  else edits.push({ start: commandStatement.end, end: commandStatement.end, text: `${contents.slice(commandStatement.end - 1, commandStatement.end) === "\n" ? "" : newline}args = ${tomlArray(args)}${newline}` });
+  if (ensureEnvVars.length) {
+    const envVarsStatement = find("env_vars");
+    if (envVarsStatement) {
+      let existing;
+      try { existing = parseStringArray(contents, envVarsStatement); }
+      catch (error) {
+        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]) });
+    } else {
+      const anchor = argsStatement ?? commandStatement;
+      const lineBreak = contents.slice(anchor.end - 1, anchor.end) === "\n" ? "" : newline;
+      edits.push({ start: anchor.end, end: anchor.end, text: `${lineBreak}env_vars = ${tomlArray(ensureEnvVars)}${newline}`, after: true });
+    }
+  }
+  edits.sort((left, right) => right.start - left.start || (left.after ? 0 : 1) - (right.after ? 0 : 1));
+  let updated = contents;
+  for (const edit of edits) updated = `${updated.slice(0, edit.start)}${edit.text}${updated.slice(edit.end)}`;
+  return updated;
+}

package/src/index.mjs

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.11";
+const VERSION = "1.22.12";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/native-relay-companion.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import net from "node:net";
 import path from "node:path";
@@ -28,7 +29,7 @@ import {
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { assertAccountIdentity } from "./bridge-account-context.mjs";
-import { createReloadControl, exitWhenClientCloses } from "./reload-control.mjs";
+import { createReloadControl, drainPendingAccepts, exitWhenClientCloses } from "./reload-control.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
 import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
@@ -38,7 +39,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.11";
+const VERSION = "1.22.12";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -421,6 +422,14 @@ export class RelaySocketServer {
     this.provisionalSockets = new Set();
     this.startGeneration = 0;
     this.startPromise = null;
+    this.withdrawn = false;
+    this.boundIdentity = null;
+  }
+
+  withdraw() {
+    if (!this.started || IS_WINDOWS || this.withdrawn || !this.#ownsPublicPath()) return;
+    this.withdrawn = true;
+    try { fs.rmSync(this.socketPath, { force: true }); } catch {}
   }
 
   start() {
@@ -438,6 +447,8 @@ export class RelaySocketServer {
     if (!IS_WINDOWS) fs.mkdirSync(path.dirname(this.socketPath), { recursive: true });
 
     const generation = ++this.startGeneration;
+    this.withdrawn = false;
+    this.boundIdentity = null;
     this.aclReady = !IS_WINDOWS || !this.strict;
     this.server = net.createServer((socket) => this.#handleConnection(socket));
     await this.#listen({ replaceStale: true });
@@ -504,7 +515,54 @@ export class RelaySocketServer {
    * swept, an accepted one means a live companion already has the socket and
    * this process leaves it alone.
    */
+  #bind(target) {
+    return new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(target, () => {
+        this.server.off("error", reject);
+        resolve();
+      });
+    });
+  }
+
+  #ownsPublicPath() {
+    if (!this.boundIdentity) return false;
+    try {
+      const current = fs.lstatSync(this.socketPath, { bigint: true });
+      return current.dev === this.boundIdentity.dev && current.ino === this.boundIdentity.ino;
+    } catch { return false; }
+  }
+
+  async #listenLinked(replaceStale) {
+    const privatePath = path.join(path.dirname(this.socketPath), `.${randomBytes(6).toString("hex")}.sock`);
+    try { await this.#bind(privatePath); }
+    catch (error) {
+      if (["ENAMETOOLONG", "EINVAL"].includes(error.code)) return false;
+      throw error;
+    }
+    try {
+      for (let attempt = 0; ; attempt++) {
+        try { fs.linkSync(privatePath, this.socketPath); break; }
+        catch (error) {
+          if (error.code !== "EEXIST") throw error;
+          if (!replaceStale || attempt || await this.#socketIsLive()) throw new Error(`another native relay companion already owns ${this.socketPath}`);
+          this.log(`removing the stale relay socket left at ${this.socketPath}`);
+          fs.rmSync(this.socketPath, { force: true });
+        }
+      }
+      const identity = fs.lstatSync(this.socketPath, { bigint: true });
+      this.boundIdentity = { dev: identity.dev, ino: identity.ino };
+    } catch (error) {
+      await this.#closeServer();
+      throw error;
+    } finally {
+      fs.rmSync(privatePath, { force: true });
+    }
+    return true;
+  }
+
   async #listen({ replaceStale }) {
+    if (!IS_WINDOWS && await this.#listenLinked(replaceStale)) return;
     try {
       await new Promise((resolve, reject) => {
         this.server.once("error", reject);
@@ -562,6 +620,8 @@ export class RelaySocketServer {
     }
     if (!this.accepting) {
       socket.on("error", () => {});
+      socket.setTimeout(5000, () => socket.destroy());
+      socket.resume();
       socket.end(`${JSON.stringify(errorResponse(this.refusal.code, this.refusal.message, false))}\n`);
       return;
     }
@@ -645,7 +705,7 @@ export class RelaySocketServer {
       catch { resolve(); }
     });
     try {
-      if (this.started && !IS_WINDOWS) fs.rmSync(this.socketPath, { force: true });
+      if (this.started && !IS_WINDOWS && !this.withdrawn && (!this.boundIdentity || this.#ownsPublicPath())) fs.rmSync(this.socketPath, { force: true });
     } catch {}
     this.started = false;
   }
@@ -772,7 +832,11 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
       const reason = inspect();
       if (reason) throw new Error(reason);
       ownedSockets = servers.filter((relay) => relay.started).map((relay) => relay.socketPath);
+      for (const relay of servers) relay.withdraw();
+      await drainPendingAccepts();
+      const late = inspect();
       await stop();
+      if (late) throw new Error(late);
     },
     exportState: () => ({ ownedSockets }),
     restore(payload) {

package/src/peer-protocol.mjs

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { homeDir, IS_WINDOWS } from "./platform.mjs";
-import { cloneReloadState } from "./reload-control.mjs";
+import { cloneReloadState, drainPendingAccepts } from "./reload-control.mjs";
 import { hardenedBridgeEnabled } from "./hardened-root-policy.mjs";
 import { protectCurrentUserPipe } from "./windows-pipe-acl.mjs";
 
@@ -586,6 +586,8 @@ export function readTranscriptOutcome(sessionId, cwd, msgId) {
   return null;
 }
 
+const RELOAD_DRAIN_MS = 1000;
+
 /**
  * Registers this process as a peer that Claude sessions can see in their agent
  * list and reply to. Without a registered socket, Claude has no address to
@@ -1140,6 +1142,19 @@ export class PeerEndpoint {
   async quiesce() {
     const reason = this.reloadReason();
     if (reason) throw new Error(reason);
+    const withdrawn = this.started && !IS_WINDOWS;
+    if (withdrawn) { try { fs.rmSync(this.socketPath, { force: true }); } catch {} }
+    await drainPendingAccepts();
+    const deadline = Date.now() + RELOAD_DRAIN_MS;
+    while (this.connections.size && Date.now() < deadline) await new Promise((resolve) => globalThis.setTimeout(resolve, 10));
+    const late = this.reloadReason();
+    if (late) {
+      if (withdrawn) {
+        try { this.server?.close(); } catch {}
+        this.started = false;
+      }
+      throw new Error(late);
+    }
     const revision = this.activityRevision;
     this.reloadPaused = true;
     globalThis.clearInterval(this.responsePoll);

package/src/reload-control.mjs

@@ -21,6 +21,10 @@ export function clientReloadReason(client) {
   return null;
 }
 
+export async function drainPendingAccepts(turns = 3) {
+  for (let turn = 0; turn < turns; turn++) await new Promise((resolve) => setImmediate(resolve));
+}
+
 export function createReloadControl({ entry, inspect = () => null, quiesce = () => {}, exportState = () => ({}), restore = () => {}, activate = () => {}, resume = activate, env = process.env, channel = process } = {}) {
   if (!["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"].includes(entry)) throw new Error("Invalid reload entry point");
   const enabled = env.CODEX_BRIDGE_WORKER === "1" && typeof channel.send === "function";