@minhspark/codex-mcp-bridge 1.22.10 → 1.22.12

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.22.10",
+  "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,45 @@ 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
+
+- Stop `claude-bridge` and native relay companion workers from outliving their MCP client. The supervisor ends a worker's stdin and IPC channel and waits before killing it, but MCP clients such as the SDK stdio transport kill the supervisor about 4 seconds after closing it. `index.mjs` already exited on stdin end; the other two workers did not, so they kept running with parent PID 1 and kept their relay and peer sockets. Each `npm test` run left two such processes, and the same could happen in Codex Desktop or Claude Desktop whenever an MCP client closed.
+- Both workers now exit on their own when stdin ends or the supervisor channel disconnects. They first stop taking new work and wait up to 35 seconds for work already accepted: the companion refuses new relay connections with `RELAY_STOPPING` (`sent: false`) and finishes accepted connections, active requests and pending Desktop dispatches; `claude-bridge` unregisters its peer endpoint and finishes open peer connections, in-flight sends and queued reply forwards. A late activation from the supervisor cannot reopen the relay during this drain, and losing the supervisor's output pipes no longer crashes the worker mid-drain. The supervisor waits for that drain before forcing a stop when its client closes; retiring a quiesced worker after a reload keeps its 6-second limit.
+
+### Verification
+
+- Every MCP supervisor test now records the supervisor and worker PIDs it sees and fails if any outlives its client, killing leftovers so a failure cannot accumulate processes. On v1.22.10, 4 tests fail: the real `claude-bridge` and companion upgrade tests leave their workers behind, and a new test that kills the supervisor finds both workers still running.
+- New tests cover the drain: an accepted relay delivery finishes before exit, a late connection is refused with `RELAY_STOPPING`, a late activation is rejected, a worker whose parent is killed during a drain still exits 0 after its work finishes (it crashes on v1.22.10's output handling), and the peer endpoint stops accepting while keeping open connections.
+- Two full `npm test` runs on macOS left no process from a `mcp-supervisor-test-` directory; the run on v1.22.10 left two.
+
+### Limitations
+
+- On Windows the supervisor's workers belong to its job object and end with it, so they never outlived their client there, and a drain cannot continue after the client kills the supervisor. The supervisor-kill test passes on Windows for that reason rather than through the drain.
+
 ## [1.22.10] - 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.10",
+  "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.10",
+  "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.10";
+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

@@ -18,7 +18,7 @@ import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
 import { assertRecipientClass, preflightFailure } from "./recipient-preflight.mjs";
 import { resolveCodexSenderContext } from "./codex-sender-context.mjs";
 import { ReplyForwarder } from "./reply-forwarder.mjs";
-import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
+import { assertRoutingReload, clientReloadReason, createReloadControl, exitWhenClientCloses } from "./reload-control.mjs";
 import { readClaudeAccountContext } from "./desktop-account-context.mjs";
 import { assertAccountIdentity, bindUnsolicitedClaudeMessageAccount, publicAccountState, readBridgeAccounts, requireBridgeAccounts, sameAccountIdentity } from "./bridge-account-context.mjs";
 import { recoverClaudeDesktopSession, resolveClaudeDesktopSession, sameClaudeDesktopRecipient } from "./claude-session-router.mjs";
@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.10";
+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;
@@ -811,5 +811,13 @@ try {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+exitWhenClientCloses({
+  prepare: () => peer.closeIntake(),
+  busy: () => peer.connections.size ? "Peer socket connections are still open"
+    : peer.requestQueues.size ? "Claude messages are still being sent"
+      : replyForwarder.forwardingReason(),
+  stop: async () => { replyForwarder.close(); peer.stop(); codex.close(); await peer.closed; },
+  log,
+});
 reload.listen();
 log(`ready on ${PLATFORM_LABEL} as peer "${peer.name}" (${peer.started ? peer.socketPath : "peer endpoint down"})`);

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.10";
+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/mcp-supervisor.mjs

@@ -6,11 +6,14 @@ import { fileURLToPath } from "node:url";
 import { createReleaseSnapshot, sourceRevision } from "./release-snapshot.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { isMainModule, stableInstallPath } from "./install-paths.mjs";
+import { CLIENT_CLOSE_DRAIN_MS, CLIENT_CLOSE_STOP_MS } from "./reload-control.mjs";
 
 const WORKER_NODE = stableInstallPath(process.execPath);
 const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUE = 256;
+const RETIRE_GRACE_MS = 6000;
+const CLIENT_CLOSE_GRACE_MS = CLIENT_CLOSE_DRAIN_MS + CLIENT_CLOSE_STOP_MS + 1000;
 const hasId = (message) => Object.hasOwn(message, "id");
 const idKey = (id) => JSON.stringify(id);
 const errorMessage = (id, message) => ({ jsonrpc: "2.0", id, error: { code: -32603, message } });
@@ -111,7 +114,7 @@ class Worker {
     this.handlers.exit(this, error);
   }
 
-  async stop() {
+  async stop(graceMs = RETIRE_GRACE_MS) {
     this.retiring = true;
     if (this.stopping) return this.stopping;
     this.stopping = (async () => {
@@ -123,7 +126,7 @@ class Worker {
       };
       this.process.stdin.end();
       if (this.process.connected) this.process.disconnect();
-      if (await wait(6000)) return;
+      if (await wait(graceMs)) return;
       if (this.process.exitCode === null && this.process.signalCode === null) {
         this.process.kill("SIGKILL");
       }
@@ -324,7 +327,7 @@ export async function runSupervisor(entry, options = {}) {
     if (stopping) return;
     stopping = true;
     clearInterval(timer);
-    await Promise.allSettled([...workers].map((worker) => worker.stop()));
+    await Promise.allSettled([...workers].map((worker) => worker.stop(CLIENT_CLOSE_GRACE_MS)));
     process.stdin.pause();
   };
   const preparationStarted = performance.now();

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 } 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.10";
+const VERSION = "1.22.12";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -46,6 +47,9 @@ function errorResponse(code, message, sent, details) {
   return { ok: false, v: RELAY_PROTOCOL_VERSION, error: { code, message, ...size, ...(sent === false ? { sent: false } : {}) } };
 }
 
+const RELAY_RELOADING_REFUSAL = Object.freeze({ code: "RELAY_RELOADING", message: "The native relay is reloading; no message was sent" });
+const RELAY_STOPPING_REFUSAL = Object.freeze({ code: "RELAY_STOPPING", message: "The native relay is shutting down because its MCP client closed; no message was sent" });
+
 function boundRequest(payload) {
   return payload?.v === ACCOUNT_RELAY_PROTOCOL_VERSION;
 }
@@ -411,12 +415,21 @@ export class RelaySocketServer {
     this.connections = new Set();
     this.handlers = new Set();
     this.accepting = true;
+    this.refusal = RELAY_RELOADING_REFUSAL;
     this.closed = Promise.resolve();
     this.processHandlers = new Map();
     this.aclReady = !IS_WINDOWS || !strict;
     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() {
@@ -434,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 });
@@ -500,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);
@@ -558,7 +620,9 @@ export class RelaySocketServer {
     }
     if (!this.accepting) {
       socket.on("error", () => {});
-      socket.end(`${JSON.stringify(errorResponse("RELAY_RELOADING", "The native relay is reloading; no message was sent", false))}\n`);
+      socket.setTimeout(5000, () => socket.destroy());
+      socket.resume();
+      socket.end(`${JSON.stringify(errorResponse(this.refusal.code, this.refusal.message, false))}\n`);
       return;
     }
     let buffer = Buffer.alloc(0);
@@ -641,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;
   }
@@ -712,10 +776,16 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
   const servers = [...new Set(relays)];
   let startups = [];
   let ownedSockets = [];
-  const inspect = () => {
+  let stopping = false;
+  const deliveryReason = () => {
     if (servers.some((relay) => relay.handlers.size)) return "Native relay requests are still active";
     if (servers.some((relay) => relay.connections.size)) return "Native relay clients are still connected";
     if (nativeTools.pending.size) return "Native Desktop dispatches are still pending";
+    return null;
+  };
+  const inspect = () => {
+    const reason = deliveryReason();
+    if (reason) return reason;
     if (nativeTools.connecting || startups.some((startup) => startup.busy)) return "Native relay startup is still pending";
     return null;
   };
@@ -729,6 +799,8 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
     nativeTools.close();
   };
   const activate = async () => {
+    if (stopping) throw new Error("The native relay is shutting down because its MCP client closed");
+    for (const relay of servers) relay.refusal = RELAY_RELOADING_REFUSAL;
     if (startups.length) {
       for (const relay of servers) relay.accepting = true;
       return;
@@ -745,14 +817,26 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
   };
   return {
     inspect,
+    deliveryReason,
     activate,
     stop,
+    refuseNewDeliveries() {
+      stopping = true;
+      for (const relay of servers) {
+        relay.refusal = RELAY_STOPPING_REFUSAL;
+        relay.accepting = false;
+      }
+    },
     async quiesce() {
       for (const relay of servers) relay.accepting = false;
       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) {
@@ -861,6 +945,7 @@ if (invokedDirectly) {
   if (!reload.staged) void lifecycle.activate().catch((error) => log(`native relay startup failed: ${error.message}`));
   mcp.server.onclose = () => { void lifecycle.stop(); };
   await mcp.connect(new StdioServerTransport());
+  exitWhenClientCloses({ prepare: () => lifecycle.refuseNewDeliveries(), busy: lifecycle.deliveryReason, stop: lifecycle.stop, log });
   reload.listen();
   log(`ready on ${PLATFORM_LABEL} (${strictDesktop ? accountRelay.socketPath : relay.started ? relay.socketPath : "socket down"})`);
 }

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
@@ -616,6 +618,7 @@ export class PeerEndpoint {
     this.connections = new Set();
     this.activityRevision = 0;
     this.reloadPaused = false;
+    this.intakeClosed = false;
     this.processHandlersRegistered = false;
     this.strict = hardenedBridgeEnabled(env);
     this.protectSocket = protectSocket ?? (hardenedBridgeEnabled(env) ? protectCurrentUserPipe : null);
@@ -655,6 +658,7 @@ export class PeerEndpoint {
 
   start() {
     if (this.reloadPaused) throw new Error("The peer endpoint is quiesced for reload");
+    if (this.intakeClosed) throw new Error("The peer endpoint is shutting down because its MCP client closed");
     if (this.started) return;
     if (this.startPromise) return this.startPromise;
     const starting = this.#startOnce();
@@ -1138,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);
@@ -1150,6 +1167,12 @@ export class PeerEndpoint {
     if (revision !== this.activityRevision || this.reloadReason()) throw new Error("Peer activity raced with reload; the endpoint remains quiesced");
   }
 
+  closeIntake() {
+    this.intakeClosed = true;
+    this.#removeRegistration();
+    if (this.server?.listening) this.server.close();
+  }
+
   async resume() {
     this.reloadPaused = false;
     await this.start();

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";
@@ -100,3 +104,38 @@ export function createReloadControl({ entry, inspect = () => null, quiesce = ()
     },
   };
 }
+
+export const CLIENT_CLOSE_DRAIN_MS = 35000;
+export const CLIENT_CLOSE_STOP_MS = 5000;
+
+export function exitWhenClientCloses({ prepare = () => {}, busy = () => null, stop = () => {}, log = () => {}, drainMs = CLIENT_CLOSE_DRAIN_MS, stopMs = CLIENT_CLOSE_STOP_MS, pollMs = 50, stdin = process.stdin, channel = process, outputs = [process.stdout, process.stderr], exit = (code) => process.exit(code) } = {}) {
+  let closing = null;
+  const bounded = (promise, ms) => {
+    let timer;
+    return Promise.race([Promise.resolve(promise).then(() => true), new Promise((resolve) => { timer = setTimeout(() => resolve(false), ms); })])
+      .finally(() => clearTimeout(timer));
+  };
+  const close = (why) => closing ??= (async () => {
+    log(`MCP client closed (${why}); draining before exit`);
+    let code = 0;
+    try {
+      await prepare();
+      const deadline = Date.now() + drainMs;
+      let reason = busy();
+      while (reason && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        reason = busy();
+      }
+      if (reason) log(`exiting after ${drainMs} ms with work still open: ${reason}`);
+      if (!await bounded(stop(), stopMs)) log(`listener shutdown exceeded ${stopMs} ms`);
+    } catch (error) {
+      code = 1;
+      log(`shutdown failed: ${error?.message ?? String(error)}`);
+    }
+    exit(code);
+  })();
+  for (const output of outputs) output?.on("error", (error) => { void close(`output failed: ${error?.code ?? error?.message}`); });
+  stdin?.once("end", () => { void close("stdin ended"); });
+  channel?.once("disconnect", () => { void close("supervisor channel disconnected"); });
+  return { close, get closing() { return closing !== null; } };
+}

package/src/reply-forwarder.mjs

@@ -106,8 +106,13 @@ export class ReplyForwarder {
     return { ...counts, attempts, maxPerSession: this.maxPerSession, closed: this.closed };
   }
 
+  forwardingReason() {
+    return this.active || this.queue.length || this.timer !== null ? "Reply forwarding is still active or queued" : null;
+  }
+
   reloadReason() {
-    if (this.active || this.queue.length || this.timer !== null) return "Reply forwarding is still active or queued";
+    const forwarding = this.forwardingReason();
+    if (forwarding) return forwarding;
     if ([...this.records.values()].some(({ receipt }) => ["queued", "sending", "unknown"].includes(receipt.status))) {
       return "A reply forwarding outcome remains unconfirmed";
     }