@minhspark/codex-mcp-bridge 1.22.10 → 1.22.11

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [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/package.json

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

package/scripts/install-native-relay.mjs

@@ -24,7 +24,7 @@ import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.10";
+const VERSION = "1.22.11";
 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"];

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.11";
 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/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.11";
 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

@@ -28,7 +28,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, 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 +38,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.10";
+const VERSION = "1.22.11";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {
@@ -46,6 +46,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,6 +414,7 @@ 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;
@@ -558,7 +562,7 @@ 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.end(`${JSON.stringify(errorResponse(this.refusal.code, this.refusal.message, false))}\n`);
       return;
     }
     let buffer = Buffer.alloc(0);
@@ -712,10 +716,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 +739,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,8 +757,16 @@ 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();
@@ -861,6 +881,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

@@ -616,6 +616,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 +656,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();
@@ -1150,6 +1152,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

@@ -100,3 +100,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";
     }