@minhspark/codex-mcp-bridge 1.13.3 → 1.13.5

package/src/codex-sender-context.mjs

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+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}$/;
+const LIFECYCLE = new Set(["task_started", "task_complete", "task_completed", "turn_started", "turn_complete", "turn_completed", "turn_aborted", "task_aborted"]);
+const STARTED = new Set(["task_started", "turn_started"]);
+const MAX_ROLLOUT_BYTES = 64 * 1024 * 1024;
+const MAX_ENTRIES = 100000;
+const MAX_DIRECTORIES = 4096;
+
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactObject(value, keys) {
+  return object(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function unavailable(reason, identity = {}) {
+  return { status: "unavailable", threadId: null, turnId: null, mode: null, cwd: null, source: null, ...identity, reason };
+}
+
+function reviewFlag(metadata, field) {
+  if (!Object.hasOwn(metadata, field) || metadata[field] === undefined) return "missing";
+  if (metadata[field] === true) return "enabled";
+  if (metadata[field] === false) return "disabled";
+  return "invalid";
+}
+
+function findRollout(sessions, threadId) {
+  if (!fs.lstatSync(sessions).isDirectory()) throw new Error("The Codex sessions path is not a regular directory");
+  const queue = [{ directory: sessions, depth: 0 }];
+  const matches = [];
+  let entries = 0;
+  let directories = 0;
+  while (queue.length) {
+    const { directory, depth } = queue.pop();
+    if (++directories > MAX_DIRECTORIES) throw new Error("The bounded Codex sessions scan exceeded its directory limit");
+    const children = fs.readdirSync(directory, { withFileTypes: true });
+    entries += children.length;
+    if (entries > MAX_ENTRIES) throw new Error("The bounded Codex sessions scan exceeded its entry limit");
+    for (const child of children) {
+      const candidate = path.join(directory, child.name);
+      if (depth < 3 && (depth === 0 ? /^\d{4}$/ : /^\d{2}$/).test(child.name)) {
+        if (child.isSymbolicLink()) throw new Error("The Codex sessions scan encountered a linked date directory");
+        if (child.isDirectory()) queue.push({ directory: candidate, depth: depth + 1 });
+      }
+      if (depth === 3 && child.name.startsWith("rollout-") && child.name.endsWith(`-${threadId}.jsonl`)) {
+        if (!child.isFile() || child.isSymbolicLink()) throw new Error("The sender rollout is not a regular file");
+        matches.push(candidate);
+      }
+    }
+  }
+  if (matches.length !== 1) throw new Error(matches.length ? "Multiple rollouts match the calling Codex task" : "No rollout matches the calling Codex task");
+  return matches[0];
+}
+
+function readState(file, maxBytes) {
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = fs.fstatSync(descriptor);
+    if (!before.isFile() || before.size === 0 || before.size > maxBytes) throw new Error("The sender rollout is empty or exceeds the bounded read limit");
+    const data = Buffer.alloc(before.size);
+    let offset = 0;
+    while (offset < data.length) {
+      const count = fs.readSync(descriptor, data, offset, data.length - offset, offset);
+      if (!count) throw new Error("The sender rollout changed while reading");
+      offset += count;
+    }
+    const after = fs.fstatSync(descriptor);
+    const current = fs.lstatSync(file);
+    if (!current.isFile() || current.isSymbolicLink() || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ino !== current.ino || before.dev !== current.dev) throw new Error("The sender rollout changed while reading");
+    const text = data.toString("utf8");
+    if (!text.endsWith("\n")) throw new Error("The sender rollout has an incomplete final record");
+    let session;
+    let context;
+    let lifecycle;
+    for (const line of text.split("\n")) {
+      if (!line) continue;
+      const record = JSON.parse(line);
+      if (!object(record) || !object(record.payload)) throw new Error("The sender rollout contains an invalid record");
+      if (record.type === "session_meta") {
+        if (session) throw new Error("The sender rollout repeats its session identity");
+        session = record.payload;
+      } else if (record.type === "turn_context") {
+        context = record.payload;
+      } else if (record.type === "event_msg" && LIFECYCLE.has(record.payload.type)) {
+        lifecycle = record.payload;
+      }
+    }
+    return { session, context, lifecycle };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function permissionClass(context, metadata) {
+  for (const field of ["auto_review_enabled", "node_repl_auto_review_required"]) {
+    if (!Object.hasOwn(metadata, field) || typeof metadata[field] !== "boolean") throw new Error(`The caller's ${field} review evidence is ${reviewFlag(metadata, field)}; the host must supply an explicit boolean`);
+  }
+  if (context.approvals_reviewer !== "user") throw new Error("The caller's effective approval reviewer is unverified");
+  if (!exactObject(context.permission_profile, ["type"]) || context.permission_profile.type !== "disabled") throw new Error("The caller's permission profile is restricted or unsupported; no permission class was inferred");
+  if (!exactObject(context.sandbox_policy, ["type"]) || context.sandbox_policy.type !== "danger-full-access") throw new Error("The caller's effective sandbox policy does not match its disabled permission profile");
+  if (!["never", "on-request", "on-failure", "untrusted"].includes(context.approval_policy)) throw new Error("The caller's effective approval policy is unsupported");
+  return context.approval_policy === "never" && !metadata.auto_review_enabled && !metadata.node_repl_auto_review_required ? "bypass" : "prompting";
+}
+
+export function readCodexSenderContext(meta, { env = process.env, maxRolloutBytes = MAX_ROLLOUT_BYTES } = {}) {
+  const metadata = object(meta) ? meta[METADATA_KEY] : undefined;
+  if (!object(metadata) || typeof metadata.thread_id !== "string" || typeof metadata.turn_id !== "string" || !UUID.test(metadata.thread_id) || !UUID.test(metadata.turn_id)) return unavailable("This MCP call has no valid host-supplied Codex task and turn identity");
+  const identity = { threadId: metadata.thread_id, turnId: metadata.turn_id,
+    review: { autoReview: reviewFlag(metadata, "auto_review_enabled"), nodeReplReview: reviewFlag(metadata, "node_repl_auto_review_required") } };
+  try {
+    if (!Number.isSafeInteger(maxRolloutBytes) || maxRolloutBytes < 1) throw new Error("The sender rollout read limit is invalid");
+    if (metadata.thread_source !== "user") throw new Error("This MCP call is not from a user-owned Codex task");
+    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 file = findRollout(sessions, identity.threadId);
+    const state = readState(file, Math.min(MAX_ROLLOUT_BYTES, maxRolloutBytes));
+    const { session, context, lifecycle } = state;
+    if (session?.id !== identity.threadId || session.originator !== "Codex Desktop" || session.source !== "vscode") throw new Error("The caller rollout does not confirm a root Codex Desktop task");
+    if (context?.turn_id !== identity.turnId || lifecycle?.turn_id !== identity.turnId || !STARTED.has(lifecycle?.type)) throw new Error("The calling turn is no longer the latest active Codex turn");
+    if (typeof context.cwd !== "string" || !path.isAbsolute(context.cwd) || typeof session.cwd !== "string" || !path.isAbsolute(session.cwd)) throw new Error("The caller's workspace is missing or invalid");
+    const cwd = fs.realpathSync.native(context.cwd);
+    if (!fs.statSync(cwd).isDirectory() || path.relative(fs.realpathSync.native(session.cwd), cwd)) throw new Error("The caller's workspace changed from its Desktop session identity");
+    const mode = permissionClass(context, metadata);
+    return { status: "verified", ...identity, mode, cwd, source: file, approvalPolicy: context.approval_policy, reason: "Host-supplied calling task and active turn match the Desktop rollout's effective permission settings" };
+  } catch (error) {
+    return unavailable(error?.code ? `Caller evidence could not be read (${error.code}); no sender permission class was inferred` : error.message, identity);
+  }
+}

package/src/index.mjs

@@ -25,10 +25,11 @@ import { BridgeSecurityPolicy } from "./security-policy.mjs";
 import { DesktopTaskDelivery, DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
+import { createRuntimeState } from "./runtime-state.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.13.3";
+const VERSION = "1.13.5";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -48,6 +49,7 @@ const TERMINAL_TURN_STATUSES = new Set(["completed", "interrupted", "failed"]);
 const RELEASE_TURN_STATUSES = TERMINAL_TURN_STATUSES;
 const security = new BridgeSecurityPolicy();
 const desktopTasksEnabled = desktopTasksConfigured();
+const runtime = createRuntimeState({ configuration: desktopTasksConfigured });
 const desktopTasks = new DesktopTaskDelivery({ security });
 
 const client = desktopTasksEnabled ? null : new CodexAppServerClient({
@@ -279,7 +281,8 @@ const server = new McpServer(
   { name: "codex-bridge", version: VERSION },
   {
     instructions:
-      "Bridge Claude work into Codex. Prefer delegate_to_codex: it creates a named Codex thread at the " +
+      "Bridge Claude work into Codex. Prefer an existing task: inspect its exact threadId and project, then use send_to_codex_thread. " +
+      "Only use delegate_to_codex or start_codex_thread when the user explicitly requests a new task at the " +
       "requested cwd. With Desktop tasks enabled it assigns the exact saved project and starts visibly in " +
       "Codex Desktop using Desktop permissions. Otherwise it releases the bridge writer lock and opens the exact thread in " +
       "Codex Desktop. Use send_to_codex_thread only when an existing threadId is intentional; use " +
@@ -287,7 +290,26 @@ const server = new McpServer(
   },
 );
 
-server.registerTool(
+function registerTool(name, definition, handler) {
+  server.registerTool(name, definition, async (...args) => {
+    try {
+      if (!definition.annotations?.readOnlyHint) runtime.assertCurrent();
+      if (name === "codex_bridge_status") {
+        const state = runtime.status();
+        if (!state.current) return { ...failure(new Error(`${state.reason}; reconnect this MCP server in the existing task.`)), structuredContent: { runtime: state } };
+        const result = await handler(...args);
+        result.content.push({ type: "text", text: `runtime pid: ${state.pid}\nloaded source: ${state.revision}\nruntime state: current` });
+        result.structuredContent = { ...result.structuredContent, runtime: state };
+        return result;
+      }
+      return await handler(...args);
+    } catch (err) {
+      return failure(err);
+    }
+  });
+}
+
+registerTool(
   "delegate_to_codex",
   {
     title: "Delegate work to a new Codex session",
@@ -378,7 +400,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "send_to_codex_thread",
   {
     title: "Send a prompt to a Codex thread",
@@ -503,7 +525,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "list_codex_threads",
   {
     title: "List Codex threads",
@@ -589,7 +611,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "start_codex_thread",
   {
     title: "Start a new Codex thread",
@@ -631,7 +653,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "read_codex_thread",
   {
     title: "Read a Codex thread",
@@ -678,7 +700,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "interrupt_codex_turn",
   {
     title: "Interrupt a Codex turn",
@@ -712,7 +734,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "open_codex_thread",
   {
     title: "Open a Codex thread in the desktop app",
@@ -755,7 +777,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "stop_codex_app_server",
   {
     title: "Stop the shared Codex app-server",
@@ -789,7 +811,7 @@ server.registerTool(
   },
 );
 
-server.registerTool(
+registerTool(
   "codex_bridge_status",
   {
     title: "Check the Codex bridge environment",

package/src/native-relay-companion.mjs

@@ -23,7 +23,7 @@ import { exitForVersionRequest } from "./cli-version.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.13.3";
+const VERSION = "1.13.5";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {

package/src/peer-protocol.mjs

@@ -117,7 +117,7 @@ function readProcessStart(pid) {
   try {
     if (IS_WINDOWS) {
       const shell = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
-      return execFileSync(shell, ["-NoProfile", "-Command", `(Get-Process -Id ${Number(pid)}).StartTime.ToUniversalTime().ToFileTimeUtc().ToString()`], { timeout: 3000, windowsHide: true }).toString().trim();
+      return execFileSync(shell, ["-NoProfile", "-NonInteractive", "-Command", `[System.Diagnostics.Process]::GetProcessById(${Number(pid)}).StartTime.ToUniversalTime().ToFileTimeUtc().ToString()`], { timeout: 3000, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }).toString().trim();
     }
     return execFileSync(PS_BIN, ["-o", "lstart=", "-p", String(pid)], { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: 3000 }).toString().trim();
   } catch {
@@ -176,10 +176,12 @@ export function listClaudeSessions({ includeDead = false, includeBridges = false
       pid: entry.pid,
       name: entry.name ?? null,
       sessionId: entry.sessionId ?? null,
+      bridgeSessionId: entry.bridgeSessionId ?? null,
       cwd: entry.cwd ?? null,
       kind: entry.kind ?? null,
       entrypoint: entry.entrypoint ?? null,
       startedAt: entry.startedAt ?? null,
+      processStart: (IS_WINDOWS ? entry.procStartFt : entry.procStart) ?? null,
       socket: entry.messagingSocketPath,
       alive,
     });
@@ -187,9 +189,21 @@ export function listClaudeSessions({ includeDead = false, includeBridges = false
   return rows.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
 }
 
-export function findClaudeSession(target) {
+export function findClaudeSession(target, { desktopOnly = false, expectedCwd } = {}) {
   const sessions = listClaudeSessions();
   const needle = String(target).trim();
+  if (desktopOnly) {
+    const byId = sessions.filter((session) => String(session.pid) === needle || session.sessionId === needle);
+    const matches = byId.length ? byId : sessions.filter((session) => session.name === needle);
+    if (!needle || matches.length === 0) return null;
+    if (matches.length !== 1) throw new Error(`Desktop-only mode requires an unambiguous sessionId or pid; "${needle}" matches multiple sessions. No message was sent.`);
+    const session = matches[0];
+    if (session.entrypoint !== "claude-desktop") {
+      throw new Error(`Desktop-only mode refuses Claude session ${session.sessionId ?? session.pid} with entrypoint ${session.entrypoint ?? "unknown"}. Open or reconnect an existing Code session in Claude Desktop for the intended project. Do not launch a replacement CLI session. No message was sent.`);
+    }
+    if (expectedCwd !== undefined) assertClaudeSessionCwd(session, expectedCwd);
+    return session;
+  }
   return (
     sessions.find((s) => String(s.pid) === needle) ??
     sessions.find((s) => s.sessionId === needle) ??
@@ -199,6 +213,31 @@ export function findClaudeSession(target) {
   );
 }
 
+export function assertClaudeSessionCwd(session, expectedCwd) {
+  if (typeof expectedCwd !== "string" || !path.isAbsolute(expectedCwd) || !session.cwd || !path.isAbsolute(session.cwd)) {
+    throw new Error("Desktop delivery requires an explicit absolute expectedCwd and an absolute session cwd. No message was sent.");
+  }
+  let expected;
+  let actual;
+  try {
+    expected = fs.realpathSync.native(expectedCwd);
+    actual = fs.realpathSync.native(session.cwd);
+  } catch {
+    throw new Error("The intended project directory or the Claude session cwd no longer exists. No message was sent.");
+  }
+  const normalize = (value) => IS_WINDOWS ? value.toLowerCase() : value;
+  if (normalize(expected) !== normalize(actual)) {
+    throw new Error(`Claude session cwd ${actual} does not match expectedCwd ${expected}. No message was sent.`);
+  }
+}
+
+export function assertClaudeSessionProcess(session) {
+  if (!session.alive || typeof session.processStart !== "string" || !session.processStart ||
+      readProcessStart(session.pid) !== session.processStart) {
+    throw new Error("The live Claude process identity is missing or changed. No message was sent; reopen the existing Desktop task and inspect its session again.");
+  }
+}
+
 /**
  * Claude Code stores a transcript at ~/.claude/projects/<slug>/<sessionId>.jsonl
  * where the slug rewrites more than just path separators (/mnt/dev_disk ->
@@ -292,6 +331,7 @@ export class PeerEndpoint {
     this.peerToken = null;
     this.permissionMode = process.env.CLAUDE_BRIDGE_PERMISSION_MODE;
     this.deliveryReceipts = new Map();
+    this.sentMessages = new Map();
     this.pendingMessages = new Map();
     this.responsePoll = null;
   }
@@ -432,7 +472,18 @@ export class PeerEndpoint {
   #receiveMessage(message) {
     const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
     this.inbox.push(record);
-    this.#removePendingReply(record.fromSocket, record.inReplyTo);
+    const key = record.inReplyTo ?? [...this.pendingMessages].find(([, entry]) => entry.targetSocket === record.fromSocket)?.[0];
+    const pending = this.pendingMessages.get(key);
+    const correlated = pending && (!pending.transcriptSession || (record.source === "transcript" && record.inReplyTo === key));
+    if (key && correlated && pending.targetSocket === record.fromSocket) {
+      const sent = this.sentMessages.get(key);
+      if (sent) {
+        record.inReplyTo = key;
+        record.replyThreadId = sent.replyThreadId ?? null;
+        sent.reply = record;
+      }
+      this.#removePendingReply(record.fromSocket, key);
+    }
     this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.slice(0, 120)}`);
     for (const listener of [...this.listeners]) {
       try { listener(record); }
@@ -480,12 +531,13 @@ export class PeerEndpoint {
     return () => this.listeners.delete(listener);
   }
 
-  async send(targetSocket, text, { priority = "next", msgId } = {}) {
-    const frame = buildFrame({ text, fromSocket: this.socketPath, priority, permissionMode: this.permissionMode });
+  async send(targetSocket, text, { priority = "next", msgId, permissionMode = this.permissionMode, beforeSend } = {}) {
+    const frame = buildFrame({ text, fromSocket: this.socketPath, priority, permissionMode });
     if (msgId) frame.uuid = frame.msg_id = msgId;
     const token = readPeerToken(targetSocket);
     const line = (token ? JSON.stringify({ type: "auth", token }) + "\n" : "") + JSON.stringify(frame) + "\n";
     for (let attempt = 1; attempt <= PEER_SEND_ATTEMPTS; attempt += 1) {
+      await beforeSend?.();
       try {
         await new Promise((resolve, reject) => {
           const client = net.connect({ path: targetSocket });
@@ -503,22 +555,30 @@ export class PeerEndpoint {
             settled = true;
             globalThis.clearTimeout(timer);
             if (error) {
+              if (writeStarted) error.deliveryUncertain = true;
               reject({ error, retryable: !connected && !writeStarted });
             } else {
               resolve();
             }
           };
-          client.once("connect", () => {
+          client.once("connect", async () => {
             connected = true;
-            writeStarted = true;
-            client.write(line, (error) => {
-              if (error) {
-                finish(error);
-                return;
-              }
-              client.end();
-              finish();
-            });
+            try {
+              await beforeSend?.();
+              if (settled) return;
+              writeStarted = true;
+              client.write(line, (error) => {
+                if (error) {
+                  finish(error);
+                  return;
+                }
+                client.end();
+                finish();
+              });
+            } catch (error) {
+              finish(error);
+              client.destroy();
+            }
           });
           client.once("error", finish);
         });
@@ -534,14 +594,15 @@ export class PeerEndpoint {
     return frame.msg_id;
   }
 
-  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession } = {}) {
+  async sendAndWait(targetSocket, text, { timeoutMs = 120000, priority = "next", transcriptSession, beforeSend, permissionMode = this.permissionMode, replyThreadId, senderReview } = {}) {
     const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
     const pending = previous.catch(() => {}).then(async () => {
+      await beforeSend?.();
       const unconfirmed = this.unconfirmedReplies.get(targetSocket) ?? 0;
-      if (timeoutMs > 0 && unconfirmed > 0) {
+      if (unconfirmed > 0) {
         const error = new Error(
           `${unconfirmed} earlier message(s) to ${targetSocket} still await a reply; this message was not sent. `
-          + "Wait for Claude's outstanding replies and check read_claude_inbox, or set waitSec to 0 to send without matching a reply.",
+          + "Inspect read_claude_delivery and wait for Claude's outstanding replies. Changing waitSec or starting another bridge must not be used to bypass a pending message.",
         );
         error.code = "PEER_REPLY_PENDING";
         throw error;
@@ -551,22 +612,33 @@ export class PeerEndpoint {
       this.unconfirmedReplies.set(targetSocket, unconfirmed + 1);
       let msgId = crypto.randomUUID();
       this.pendingMessages.set(msgId, { targetSocket, transcriptSession });
+      this.sentMessages.set(msgId, { targetSocket, transcriptSession, sentAt: since, replyThreadId, permissionMode, ...(senderReview ? { senderReview: { ...senderReview } } : {}) });
+      if (transcriptSession && !this.responsePoll) {
+        this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
+        this.responsePoll.unref();
+      }
       try {
-        const sentId = await this.send(targetSocket, text, { priority, msgId });
+        const sentId = await this.send(targetSocket, text, { priority, msgId, permissionMode, beforeSend });
         if (sentId !== msgId) {
           const pendingMessage = this.pendingMessages.get(msgId);
+          const earlyReply = this.sentMessages.get(msgId)?.reply;
+          if (earlyReply?.inReplyTo === msgId) earlyReply.inReplyTo = sentId;
           this.pendingMessages.delete(msgId);
+          this.sentMessages.set(sentId, this.sentMessages.get(msgId));
+          this.sentMessages.delete(msgId);
           msgId = sentId;
           if (pendingMessage) this.pendingMessages.set(msgId, pendingMessage);
         }
       } catch (err) {
-        this.#removePendingReply(targetSocket, msgId);
+        const sent = this.sentMessages.get(msgId);
+        if (sent) sent.error = err.message;
+        if (!err.deliveryUncertain) {
+          this.#removePendingReply(targetSocket, msgId);
+          if (sent) sent.failed = true;
+        }
+        err.msgId = msgId;
         throw err;
       }
-      if (transcriptSession && !this.responsePoll && this.pendingMessages.has(msgId)) {
-        this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
-        this.responsePoll.unref();
-      }
       const reply = timeoutMs > 0
         ? await this.waitForReply(targetSocket, { timeoutMs, since, afterSequence, msgId })
         : null;
@@ -584,7 +656,8 @@ export class PeerEndpoint {
 
   #removePendingReply(fromSocket, msgId) {
     const key = msgId ?? [...this.pendingMessages].find(([, entry]) => entry.targetSocket === fromSocket)?.[0];
-    if (key) this.pendingMessages.delete(key);
+    if (!key || this.pendingMessages.get(key)?.targetSocket !== fromSocket) return;
+    this.pendingMessages.delete(key);
     const pending = this.unconfirmedReplies.get(fromSocket) ?? 0;
     if (pending > 1) this.unconfirmedReplies.set(fromSocket, pending - 1);
     else this.unconfirmedReplies.delete(fromSocket);
@@ -595,7 +668,10 @@ export class PeerEndpoint {
    * reply is matched by origin socket and arrival time.
    */
   waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now(), afterSequence = null, msgId } = {}) {
+    const expectsTranscript = Boolean(msgId && this.sentMessages.get(msgId)?.transcriptSession);
     const matches = (record) => record.fromSocket === fromSocket
+      && (!expectsTranscript || (record.source === "transcript" && record.inReplyTo === msgId))
+      && (!record.inReplyTo || !msgId || record.inReplyTo === msgId)
       && (afterSequence === null ? record.receivedAt >= since : record.sequence > afterSequence);
     const existing = this.inbox.find(matches);
     if (existing) return Promise.resolve(existing);
@@ -619,9 +695,31 @@ export class PeerEndpoint {
   }
 
   drainInbox(limit = 20) {
-    const messages = this.inbox.slice(-limit);
-    this.inbox = [];
-    return messages;
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("Inbox limit must be a positive integer");
+    return this.inbox.splice(0, limit);
+  }
+
+  readDelivery(msgId) {
+    const sent = this.sentMessages.get(msgId);
+    if (!sent) return null;
+    const delivery = this.deliveryReceipts.get(msgId);
+    const session = sent.transcriptSession;
+    return {
+      msgId,
+      status: sent.reply ? "reply_received" : sent.failed ? "send_failed" : delivery?.status ?? "sent_unconfirmed",
+      reason: delivery?.reason ?? sent.error ?? null,
+      sentAt: sent.sentAt,
+      sessionId: session?.sessionId ?? null,
+      cwd: session?.cwd ?? null,
+      entrypoint: session?.entrypoint ?? null,
+      taskId: session?.desktop?.taskId ?? null,
+      title: session?.desktop?.title ?? null,
+      senderMode: sent.permissionMode ?? null,
+      ...(sent.senderReview ? { senderReview: { ...sent.senderReview } } : {}),
+      replyThreadId: sent.replyThreadId ?? null,
+      pending: this.pendingMessages.has(msgId),
+      ...(sent.reply ? { reply: sent.reply.text, source: sent.reply.source ?? "peer", ...(sent.reply.forwardingError ? { forwardingError: { ...sent.reply.forwardingError } } : {}) } : {}),
+    };
   }
 
   stop() {

package/src/platform.mjs

@@ -20,7 +20,8 @@ export const PLATFORM_LABEL = IS_MACOS
       : process.platform;
 
 const CODEX_DESKTOP_APP_MACOS = "/Applications/ChatGPT.app";
-const CODEX_DESKTOP_BIN_MACOS = `${CODEX_DESKTOP_APP_MACOS}/Contents/Resources/codex`;
+const CODEX_DESKTOP_RESOURCES_MACOS = `${CODEX_DESKTOP_APP_MACOS}/Contents/Resources`;
+const CODEX_DESKTOP_BIN_MACOS = `${CODEX_DESKTOP_RESOURCES_MACOS}/codex`;
 const CODEX_THREAD_URL_PREFIX = "codex://threads/";
 
 /**
@@ -176,6 +177,59 @@ export function resolveCodexBin(explicit) {
   return "codex";
 }
 
+/**
+ * Codex Desktop authenticates the code-signing identity of whatever process
+ * connects to its native tools pipe, and closes the connection before reading
+ * a single byte when that identity is not the vendor's - the app records
+ * `dynamic_app_tools_peer_rejected`. A companion launched by the user's own
+ * Node build carries the Node.js Foundation signature rather than OpenAI's,
+ * so the relay still reports itself installed and still creates its socket
+ * while every delivery fails; the symptom surfaces nowhere near the cause.
+ * The runtime therefore has to be the one the app ships, which is also the
+ * one the app hands its own bundled plugin through CODEX_MCP_NODE_PATH.
+ *
+ * The vendor's launcher additionally falls back to a cached runtime under
+ * ~/.cache/codex-runtimes and to a bare PATH lookup. Both are deliberately
+ * absent here: the cached binary measured on a real install is the same
+ * version and within 1.3 KB of the bundled one, yet carries the Node.js
+ * Foundation signature, so copying that list wholesale would reproduce the
+ * rejection this resolves under a different file name. For the same reason
+ * the runtime is never taken from PATH or from a version match.
+ *
+ * Only macOS ships this bundle and only macOS was measured to enforce the
+ * check, so the vendor-owned rungs are gated by platform. Every other
+ * platform keeps the runtime it has always used, and the last rung is an
+ * unconditional real path rather than a bare command name because the caller
+ * writes the result straight into client configuration.
+ */
+export function resolveCodexDesktopNodeBin(
+  explicit,
+  { env = process.env, platform = process.platform, resourcesDir = CODEX_DESKTOP_RESOURCES_MACOS } = {},
+) {
+  const bundledNode = (dir) => path.join(dir, "cua_node", "bin", platform === "win32" ? "node.exe" : "node");
+  const vendorRungs =
+    platform === "darwin"
+      ? [
+          [env.CODEX_MCP_NODE_PATH, "CODEX_MCP_NODE_PATH"],
+          [env.CODEX_BROWSER_USE_NODE_PATH, "CODEX_BROWSER_USE_NODE_PATH"],
+          [
+            env.CODEX_ELECTRON_RESOURCES_PATH && bundledNode(env.CODEX_ELECTRON_RESOURCES_PATH),
+            "CODEX_ELECTRON_RESOURCES_PATH",
+          ],
+          [bundledNode(resourcesDir), "Codex Desktop bundle"],
+        ]
+      : [];
+
+  for (const [candidate, source] of [
+    [explicit, "explicit"],
+    [env.CODEX_NATIVE_RELAY_NODE, "CODEX_NATIVE_RELAY_NODE"],
+    ...vendorRungs,
+  ]) {
+    if (candidate && isRunnable(candidate)) return { path: candidate, source };
+  }
+  return { path: process.execPath, source: "process.execPath" };
+}
+
 /**
  * The macOS and Linux `codex` launcher is a Node script with a
  * `#!/usr/bin/env node` shebang, so the spawned child needs a PATH that