@minhspark/codex-mcp-bridge 1.22.9 → 1.22.11

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.22.9",
+  "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,39 @@ 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
+
+- Re-read the whole rollout set when Codex appends between per-segment reads. The pre-send watermark, dispatch, turn and creation readers and Codex sender verification now repeat find, read and set check together, up to three times, instead of failing with `A rollout segment changed while reading`. Only read races qualify: identity, history, account, workspace and dispatch mismatches still fail at once.
+- Keep observing an accepted Desktop send or creation while Codex is still writing its rollout. When a read keeps reporting that the rollout changed while reading, the wait polls again until its deadline and then returns the pending receipt with that reason, instead of reporting the delivery as failed. Seen live on 2026-10-20: an accepted send reported `failed` while the reply was later recovered from the same receipt. A rollout whose last record stays incomplete, for example after Codex stopped mid-write, is still reported at once with its turn status and reason.
+
+### Verification
+
+- 8 new regression tests reproduce the append during the set check for the watermark, the turn and dispatch reply readers, sender verification and both wait paths; all fail on v1.22.8. Two more pin that a permanently incomplete rollout is reported without waiting, and a unit test pins which messages are retried.
+- Two rounds of independent review shaped the wait behavior. A deferred released turn stays the observed turn even if a newer turn starts. The deferral reason is cleared after a clean read, and a timeout reports it as an unavailable observation. Only the set level retries, so an actively written rollout is scanned at most three times per observation. Deferral is limited to `changed while reading`, because `incomplete final record` can be permanent. Each of these has a regression test that fails without its fix.
+
+### Limitations
+
+- The original race was seen once in a live Desktop send and cannot be triggered on demand; the regression tests reproduce it deterministically by appending to the rollout during the set check. A Codex Desktop or MCP restart still ends in-memory peer receipts, as before.
+
 ## [1.22.9] - 2026-10-20
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.9",
+  "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.9",
+  "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.9";
+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.9";
+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/codex-native-response.mjs

@@ -5,7 +5,7 @@ import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { scanRollout } from "./rollout-reader.mjs";
 import { fileIdentity, sameFileIdentity } from "./file-identity.mjs";
-import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable } from "./rollout-segments.mjs";
+import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable, retryRolloutRead } from "./rollout-segments.mjs";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const MAX_ROLLOUT_BYTES = 16 * 1024 * 1024;
@@ -84,12 +84,15 @@ function samePathBoundary(expected, current) {
 }
 
 function readStable(found, maxBytes, { threadId, turnId, afterOffset = 0, prefixSize, dispatchOutputs, dispatchAfterOffset = afterOffset } = {}) {
-  for (let attempt = 0; ; attempt++) {
-    try { return readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefixSize, dispatchOutputs, dispatchAfterOffset }); }
-    catch (error) {
-      if (attempt >= 2 || !/changed while (reading|opening)|incomplete final record/.test(error.message)) throw error;
-    }
-  }
+  return readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefixSize, dispatchOutputs, dispatchAfterOffset });
+}
+
+function readStableRolloutSet(threadId, env, readSegments) {
+  return retryRolloutRead(() => {
+    const snapshots = readSegments(findRollouts(threadId, env));
+    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
+    return snapshots;
+  });
 }
 
 function readStableOnce(found, maxBytes, { threadId, turnId, afterOffset, prefixSize, dispatchOutputs, dispatchAfterOffset }) {
@@ -346,8 +349,7 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch, o
 export function captureCodexRolloutWatermark({ threadId, expectedCwd, desktopEvidence }, { env = process.env, maxRolloutBytes = MAX_ROLLOUT_BYTES } = {}) {
   try {
     const cwd = canonicalDirectory(expectedCwd, "The selected native task workspace");
-    const snapshots = findRollouts(threadId, env).map((found) => ({ ...found, ...readStable(found, maxRolloutBytes) }));
-    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
+    const snapshots = readStableRolloutSet(threadId, env, (found) => found.map((entry) => ({ ...entry, ...readStable(entry, maxRolloutBytes) })));
     for (const snapshot of snapshots) validateIdentity(snapshot, threadId, cwd, desktopEvidence);
     const matches = snapshots.length === 1 ? snapshots : snapshots.filter((snapshot) =>
       desktopEvidence?.latestTurnId && snapshot.latestContext?.turn_id === desktopEvidence.latestTurnId);
@@ -369,15 +371,16 @@ export function readCodexNativeCreationResponse({ threadId, turnId, expectedCwd,
     if (!UUID.test(threadId) || !UUID.test(turnId) || !UUID.test(executorThreadId)) throw new Error("The native creation response identity is invalid");
     if (typeof prompt !== "string" || !prompt.length) throw new Error("The exact creation prompt is unavailable");
     const cwd = canonicalDirectory(expectedCwd, "The created native task workspace");
-    let retainedBytes = 0;
-    const snapshots = findRollouts(threadId, env).map((found) => {
-      const snapshot = readStable(found, maxRolloutBytes, { threadId, turnId });
-      retainedBytes += snapshot.retainedBytes;
-      if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
-      validateIdentity(snapshot, threadId, cwd, desktopEvidence);
-      return snapshot;
+    const snapshots = readStableRolloutSet(threadId, env, (found) => {
+      let retainedBytes = 0;
+      return found.map((entry) => {
+        const snapshot = readStable(entry, maxRolloutBytes, { threadId, turnId });
+        retainedBytes += snapshot.retainedBytes;
+        if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
+        validateIdentity(snapshot, threadId, cwd, desktopEvidence);
+        return snapshot;
+      });
     });
-    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
     const selected = uniqueTurn(snapshots);
     validateSession(selected, threadId, cwd, desktopEvidence);
     return inspectTurnRecords(selected.records, threadId, turnId, cwd, {
@@ -392,14 +395,15 @@ export function inspectCodexNativeTurn({ threadId, turnId, expectedCwd, desktopE
   try {
     if (!UUID.test(threadId) || !UUID.test(turnId)) throw new Error("The native turn identity is invalid");
     const cwd = canonicalDirectory(expectedCwd, "The selected native task workspace");
-    let retainedBytes = 0;
-    const snapshots = findRollouts(threadId, env).map((found) => {
-      const snapshot = readStable(found, maxRolloutBytes, { threadId, turnId });
-      retainedBytes += snapshot.retainedBytes;
-      if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
-      return snapshot;
+    const snapshots = readStableRolloutSet(threadId, env, (found) => {
+      let retainedBytes = 0;
+      return found.map((entry) => {
+        const snapshot = readStable(entry, maxRolloutBytes, { threadId, turnId });
+        retainedBytes += snapshot.retainedBytes;
+        if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
+        return snapshot;
+      });
     });
-    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
     for (const snapshot of snapshots) validateIdentity(snapshot, threadId, cwd, desktopEvidence);
     const selected = uniqueTurn(snapshots);
     validateSession(selected, threadId, cwd, desktopEvidence);
@@ -421,20 +425,20 @@ export function resolveCodexNativeDispatchResponse(binding, { env = process.env,
     if (!Array.isArray(marks) || !marks.length || marks.length > 64 || new Set(marks.map((mark) => mark.file)).size !== marks.length ||
         !marks.some((mark) => mark.file === watermark.file && mark.size === watermark.size && mark.prefixSha256 === watermark.prefixSha256) ||
         marks.some((mark) => !Number.isSafeInteger(mark.size) || mark.size < 1)) throw new Error("The pre-send segment watermarks are invalid");
-    const found = findRollouts(threadId, env);
-    if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
     const outputs = delegationOutputs(executorThreadId, prompt);
-    const snapshots = found.map((entry) => {
-      const mark = marks.find(({ file }) => file === entry.file);
-      const snapshot = readStable(entry, maxRolloutBytes, { threadId, afterOffset: mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs });
-      if (mark) {
-        if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
-        if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
-      }
-      validateIdentity(snapshot, threadId, cwd, desktopEvidence);
-      return snapshot;
+    const snapshots = readStableRolloutSet(threadId, env, (found) => {
+      if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
+      return found.map((entry) => {
+        const mark = marks.find(({ file }) => file === entry.file);
+        const snapshot = readStable(entry, maxRolloutBytes, { threadId, afterOffset: mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs });
+        if (mark) {
+          if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
+          if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
+        }
+        validateIdentity(snapshot, threadId, cwd, desktopEvidence);
+        return snapshot;
+      });
     });
-    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
     const matches = snapshots.flatMap((snapshot) => snapshot.dispatches.map((dispatch) => ({ snapshot, dispatch })));
     if (!matches.length) return { status: "pending", threadId, turnId: null, text: "", assistantItems: [], replySha256: null };
     if (matches.length !== 1) throw new Error("Multiple post-send native dispatches match the reply receipt");
@@ -464,24 +468,24 @@ export function readCodexNativeTurnResponse({ threadId, turnId, previousTurnId,
         || new Set(marks.map((mark) => mark.file)).size !== marks.length
         || !marks.some((mark) => mark.file === watermark.file && mark.size === watermark.size && mark.prefixSha256 === watermark.prefixSha256)) throw new Error("The pre-send segment watermarks are invalid");
     for (const mark of marks) if (!Number.isSafeInteger(mark.size) || mark.size < 1) throw new Error("The pre-send rollout watermark size is invalid");
-    const found = findRollouts(threadId, env);
-    if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
     const outputs = delegationOutputs(executorThreadId, prompt);
-    let retainedBytes = 0;
-    const snapshots = found.map((entry) => {
-      const mark = marks.find(({ file }) => file === entry.file);
-      const snapshot = readStable(entry, maxRolloutBytes, { threadId, turnId, afterOffset: existingTurn ? 0 : mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs, dispatchAfterOffset: mark?.size ?? 0 });
-      retainedBytes += snapshot.retainedBytes;
-      if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
-      if (mark) {
-        if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
-        if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
-      }
-      if (snapshot.turnBeforeWatermark) throw new Error("The observed turn was already present before dispatch");
-      validateIdentity(snapshot, threadId, cwd, desktopEvidence);
-      return snapshot;
+    const snapshots = readStableRolloutSet(threadId, env, (found) => {
+      if (marks.some((mark) => !found.some(({ file }) => file === mark.file))) throw new Error("A pre-send rollout segment disappeared after dispatch");
+      let retainedBytes = 0;
+      return found.map((entry) => {
+        const mark = marks.find(({ file }) => file === entry.file);
+        const snapshot = readStable(entry, maxRolloutBytes, { threadId, turnId, afterOffset: existingTurn ? 0 : mark?.size ?? 0, prefixSize: mark?.size, dispatchOutputs: outputs, dispatchAfterOffset: mark?.size ?? 0 });
+        retainedBytes += snapshot.retainedBytes;
+        if (retainedBytes > maxRolloutBytes) throw new Error("The native turn exceeds the retained-record limit across segments");
+        if (mark) {
+          if (!sameFileIdentity(snapshot.identity, mark.identity) || snapshot.size < mark.size) throw new Error("The selected native task rollout identity changed after dispatch");
+          if (snapshot.prefixSha256 !== mark.prefixSha256) throw new Error("The pre-send Codex rollout history changed after dispatch");
+        }
+        if (snapshot.turnBeforeWatermark) throw new Error("The observed turn was already present before dispatch");
+        validateIdentity(snapshot, threadId, cwd, desktopEvidence);
+        return snapshot;
+      });
     });
-    assertRolloutSetStable(snapshots[0].sessions, threadId, snapshots);
     const selected = uniqueTurn(snapshots);
     const matchedDispatches = snapshots.flatMap((snapshot) => snapshot.dispatches);
     if (matchedDispatches.length !== 1 || matchedDispatches[0].turnId !== turnId) throw new Error("The observed turn is not uniquely correlated to the exact native dispatch");

package/src/codex-sender-context.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { scanRollout } from "./rollout-reader.mjs";
-import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable } from "./rollout-segments.mjs";
+import { findRolloutSegments, confirmsDesktopTask, isLegacyCliSession, assertRolloutSetStable, retryRolloutRead } from "./rollout-segments.mjs";
 
 const METADATA_KEY = "x-codex-turn-metadata";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -43,14 +43,9 @@ export function findRollout(sessions, threadId) {
 }
 
 export function readState(file, maxBytes) {
-  for (let attempt = 0; ; attempt++) {
-    try { return readStateOnce(file, maxBytes); }
-    catch (error) {
-      // A live Desktop task can append its tool event during verification.
-      // Retry the entire scan, never reuse partially observed permissions.
-      if (attempt >= 2 || !/changed while (reading|opening)|incomplete final record/.test(error.message)) throw error;
-    }
-  }
+  // A live Desktop task can append its tool event during verification.
+  // Retry the entire scan, never reuse partially observed permissions.
+  return retryRolloutRead(() => readStateOnce(file, maxBytes));
 }
 
 function readStateOnce(file, maxBytes) {
@@ -182,15 +177,18 @@ export function readCodexSenderContext(meta, { env = process.env, maxRolloutByte
     const configuredHome = env.CODEX_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), ".codex");
     if (!path.isAbsolute(configuredHome)) throw new Error("The configured Codex home must be absolute");
     const sessions = path.join(configuredHome, "sessions");
-    const matches = [], snapshots = [];
-    for (const file of findRolloutSegments(sessions, identity.threadId)) {
-      const state = readState(file, Math.min(MAX_ROLLOUT_BYTES, maxRolloutBytes));
-      if (state.session?.id !== identity.threadId) throw new Error("A rollout segment contradicts the calling task identity");
-      snapshots.push({ file, version: state.version });
-      if (state.context?.turn_id === identity.turnId || state.lifecycle?.turn_id === identity.turnId) matches.push({ file, ...state });
-      if (matches.length > 1) throw new Error("Multiple rollout segments match the calling turn");
-    }
-    assertRolloutSetStable(sessions, identity.threadId, snapshots);
+    const matches = retryRolloutRead(() => {
+      const found = [], snapshots = [];
+      for (const file of findRolloutSegments(sessions, identity.threadId)) {
+        const state = readStateOnce(file, Math.min(MAX_ROLLOUT_BYTES, maxRolloutBytes));
+        if (state.session?.id !== identity.threadId) throw new Error("A rollout segment contradicts the calling task identity");
+        snapshots.push({ file, version: state.version });
+        if (state.context?.turn_id === identity.turnId || state.lifecycle?.turn_id === identity.turnId) found.push({ file, ...state });
+        if (found.length > 1) throw new Error("Multiple rollout segments match the calling turn");
+      }
+      assertRolloutSetStable(sessions, identity.threadId, snapshots);
+      return found;
+    });
     if (matches.length !== 1) throw new Error(matches.length ? "Multiple rollout segments match the calling turn" : "The calling turn is no longer the latest active Codex turn");
     const { file, session, context, lifecycle } = matches[0];
     if (!["Codex Desktop", "codex_vscode"].includes(originator)) throw new Error("Unsupported calling host");

package/src/index.mjs

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.9";
+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.9";
+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";
     }

package/src/rollout-segments.mjs

@@ -55,6 +55,33 @@ export function isLegacyCliSession(session) {
   return session?.originator === "codex-tui" && session.source === "cli";
 }
 
+const TRANSIENT_ROLLOUT_READ = /changed while (reading|opening)|incomplete final record/;
+const ROLLOUT_CHANGED_DURING_READ = /changed while (reading|opening)/;
+const ROLLOUT_READ_ATTEMPTS = 3;
+
+function reasonText(reason) {
+  return typeof reason === "string" ? reason : reason?.message;
+}
+
+export function isTransientRolloutRead(reason) {
+  const message = reasonText(reason);
+  return typeof message === "string" && TRANSIENT_ROLLOUT_READ.test(message);
+}
+
+export function isRolloutChangedDuringRead(reason) {
+  const message = reasonText(reason);
+  return typeof message === "string" && ROLLOUT_CHANGED_DURING_READ.test(message);
+}
+
+export function retryRolloutRead(read, attempts = ROLLOUT_READ_ATTEMPTS) {
+  for (let attempt = 1; ; attempt++) {
+    try { return read(); }
+    catch (error) {
+      if (attempt >= attempts || !isTransientRolloutRead(error)) throw error;
+    }
+  }
+}
+
 export function assertRolloutSetStable(sessions, threadId, snapshots) {
   const files = findRolloutSegments(sessions, threadId);
   if (files.length !== snapshots.length || files.some((file, i) => file !== snapshots[i].file)) throw new Error("The rollout segment set changed while reading");

package/src/thread-delivery.mjs

@@ -7,6 +7,7 @@ import { creationRequestHash } from "./native-creation-receipts.mjs";
 import { DesktopTaskReceipts } from "./desktop-task-receipts.mjs";
 import { captureCodexRolloutWatermark, inspectCodexNativeTurn, readCodexNativeTurnResponse, readCodexNativeCreationResponse, resolveCodexNativeDispatchResponse } from "./codex-native-response.mjs";
 import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
+import { isRolloutChangedDuringRead } from "./rollout-segments.mjs";
 import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
 
 /**
@@ -550,6 +551,8 @@ export class DesktopTaskDelivery {
     let cursor;
     let turnId = null;
     let readSnapshots = false;
+    let deferredReason = null;
+    let deferredTurn = null;
     const readSnapshot = async () => {
       const result = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline: startedAt + timeoutMs });
       const thread = result?.thread;
@@ -560,19 +563,24 @@ export class DesktopTaskDelivery {
       if (responseObservation?.expectedCwd && realpathSync.native(thread.cwd) !== responseObservation.expectedCwd) throw new Error("The selected native task workspace changed during observation");
       return { polls: [{ thread, latestTurn: result.turns?.[0] ?? null }] };
     };
-    const expired = () => ({ threadId, turnId, status: "timeout", text: "", responseStatus: "unavailable", assistantItems: [], replySha256: null, activity: [], errors: [], durationMs: this.now() - startedAt });
+    const expired = () => ({ threadId, turnId, status: "timeout", text: "", responseStatus: "unavailable", ...(deferredReason ? { observationStatus: "unavailable", observationReason: deferredReason } : {}), assistantItems: [], replySha256: null, activity: [], errors: [], durationMs: this.now() - startedAt });
     const deadlineError = (error) => {
       const cause = error.cause ?? error;
       return this.now() - startedAt >= timeoutMs && (["DESKTOP_RESPONSE_DEADLINE", "RELAY_TIMEOUT"].includes(cause.code) ||
         cause.code === "RELAY_UNREACHABLE" && cause.message === "The Codex Desktop relay send deadline elapsed before dispatch");
     };
-    const unassigned = Symbol("workspace-unassigned");
+    const observeLater = Symbol("observe-later");
     const observe = async (selectedTurnId, resolveDispatch = false) => {
       try {
-        return await this.observeNativeResponse(threadId, selectedTurnId, responseObservation, { deadline: startedAt + timeoutMs, resolveDispatch });
+        const observed = await this.observeNativeResponse(threadId, selectedTurnId, responseObservation, { deadline: startedAt + timeoutMs, resolveDispatch });
+        deferredReason = observed?.status === "unavailable" && isRolloutChangedDuringRead(observed.reason) ? observed.reason : null;
+        return deferredReason ? observeLater : observed;
       } catch (error) {
         if (deadlineError(error)) return null;
-        if (error.code === WORKSPACE_UNASSIGNED) return unassigned;
+        if (error.code === WORKSPACE_UNASSIGNED) {
+          deferredReason = null;
+          return observeLater;
+        }
         throw error;
       }
     };
@@ -611,7 +619,7 @@ export class DesktopTaskDelivery {
       if (this.resolveResponse && responseObservation?.watermark?.status === "available" && responseObservation.operation !== "create_thread") {
         const observed = await observe(null, true);
         if (!observed) return expired();
-        if (observed === unassigned) {
+        if (observed === observeLater) {
           await pause();
           continue;
         }
@@ -634,17 +642,20 @@ export class DesktopTaskDelivery {
         continue;
       }
       if (needsAttention) return attention();
-      const existingTurn = turn?.id === previousTurnId;
-      if (turn?.id && (!existingTurn || responseObservation?.previousTurnId === previousTurnId)) {
-        if (!existingTurn) turnId = turn.id;
-        const status = turn.status;
+      const released = deferredTurn ?? turn;
+      const existingTurn = released?.id === previousTurnId;
+      if (released?.id && (!existingTurn || responseObservation?.previousTurnId === previousTurnId)) {
+        if (!existingTurn) turnId = released.id;
+        const status = released.status;
         if (RELEASE_STATUSES.has(status)) {
-          const observed = await observe(turn.id);
+          const observed = await observe(released.id);
           if (!observed) return expired();
-          if (observed === unassigned) {
+          if (observed === observeLater) {
+            deferredTurn = deferredReason ? released : null;
             await pause();
             continue;
           }
+          deferredTurn = null;
           const responseStatus = observed.status;
           if (existingTurn && !observed.dispatchObserved && !["completed", "completed_no_reply"].includes(responseStatus)) {
             turnId = null;
@@ -652,7 +663,7 @@ export class DesktopTaskDelivery {
             await this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
             continue;
           }
-          turnId = turn.id;
+          turnId = released.id;
           return {
             threadId, turnId, status,
             text: responseStatus === "completed" ? observed.text : "",
@@ -663,7 +674,7 @@ export class DesktopTaskDelivery {
             replySha256: observed.replySha256 ?? null,
             responseSource: observed.source ?? null,
             ...(observed.responseScope ? { responseScope: observed.responseScope } : {}),
-            activity: [], errors: turn.error ? [turn.error] : [], durationMs: turn.durationMs ?? this.now() - startedAt,
+            activity: [], errors: released.error ? [released.error] : [], durationMs: released.durationMs ?? this.now() - startedAt,
           };
         }
       }