@minhspark/codex-mcp-bridge 1.13.3 → 1.13.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [1.13.4] - 2026-09-06
+
+### Fixed
+
+- Latch queued Desktop delivery deadlines when they expire, so a timed-out prompt cannot dispatch later or release the lock owned by an active send.
+- Require and revalidate the exact intended workspace for Claude Desktop sends, expose pending recipient receipts through `read_claude_delivery`, and block no-wait retries of held or uncertain messages. Preserve pending ownership after an uncertain socket write.
+- Detect source and Desktop-policy changes in loaded bridge processes and refuse new sends until reconnect. Diagnostics identify their separate MCP process instead of implying the Desktop connection was refreshed.
+- Preserve the Codex MCP registration environment on upgrade, pin Desktop routing explicitly, disable its external autostart, and refuse to reset custom access or transport settings. Prefer existing Desktop tasks in MCP instructions.
+- Enforce Desktop task mode for Claude destinations as well as Codex delivery. Exclude non-Desktop sessions from discovery, refuse CLI or unknown entrypoints before connecting, and require a unique exact target. Status reports eligible and excluded sessions; receipts identify the actual entrypoint, workspace, and session. Legacy CLI mode remains available when Desktop task mode is disabled.
+- Register the native relay companion under a runtime Codex Desktop trusts instead of whichever Node happens to run the installer. The app authenticates the code-signing identity of any process connecting to its native tools pipe and closes the connection before reading a byte when that identity is not its own, so a companion started by a user-installed Node still created its socket and still reported itself installed while every delivery failed as `NATIVE_DELIVERY_UNCONFIRMED` — the refusal is only visible in the app's own log as `dynamic_app_tools_peer_rejected`. On macOS the installer now resolves the runtime the app ships, honours the variables the app declares for its own bundled plugin, and prints the runtime and its source; `CODEX_NATIVE_RELAY_NODE` overrides it. Windows and Linux keep the runtime running the installer, since neither was measured to enforce the check.
+
+### Upgrade notes
+
+- Reconnect the MCP connections in both Desktop clients after upgrading. Reinstall an existing native relay companion with the updated installer to apply runtime selection. Updating package files alone does not replace running processes or add the stale-runtime guard to an older process.
+- In Desktop task mode, provide the independently verified absolute `expectedCwd` when sending to Claude. A held receipt still requires the recipient's approval; inspect its `msgId` with `read_claude_delivery` instead of resending. Receipt history is in memory and is not restored after a bridge restart.
+
 ## [1.13.3] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -258,7 +258,7 @@ claude mcp remove codex-bridge --scope user
 node scripts/install-codex-mcp.mjs
 ```
 
-This runs `codex mcp add claude-bridge -- <node> src/claude-bridge.mjs`, writing to `~/.codex/config.toml`. The equivalent by hand:
+The installer updates the named entry through `codex mcp add`, preserves existing environment settings, pins the configured Desktop policy, and disables external autostart in Desktop mode. It refuses to reset custom access, timeout, or transport settings. It never infers the sender permission class from the recipient. The basic registration by hand is:
 
 ```bash
 codex mcp add claude-bridge --env CLAUDE_BRIDGE_PEER_NAME=codex-desktop -- "$(command -v node)" "$PWD/src/claude-bridge.mjs"
@@ -272,11 +272,7 @@ codex mcp get claude-bridge
 node scripts/install-codex-mcp.mjs --remove
 ```
 
-Restart the Codex app (or open a new Codex session) to load it. If a shared app-server is already running under launchd, reload its config with:
-
-```bash
-launchctl kickstart -k gui/$UID/com.codex-mcp-bridge.app-server
-```
+Reconnect the MCP server in the existing Codex Desktop task, or restart the app and reopen that same task. Verify `claude_bridge_status` **from that task**: `runtime state` must be `current` and `session policy` must match the intended mode. Do not create a replacement task. `npm run check:claude` starts a separate diagnostic process and cannot prove that the app's existing MCP connection reloaded.
 
 `CLAUDE_BRIDGE_PEER_NAME` sets the name Claude shows for this bridge in its agent list.
 
@@ -288,7 +284,7 @@ Optional, and only worth installing if you keep the bound thread **open in Codex
 node scripts/install-native-relay.mjs
 ```
 
-This registers the companion with Codex (`codex mcp add codex-native-relay -- <node> src/native-relay-companion.mjs`) and bootstraps the executor thread the native dispatch needs, writing its id to `~/.codex/native-relay.json`. The bootstrap creates one thread, unsubscribes it, and closes its connection. It leaves other clients and threads running; an idle server may retain the executor until its configured unload delay expires.
+This registers the companion with Codex (`codex mcp add codex-native-relay -- <node> src/native-relay-companion.mjs`) and bootstraps the executor thread the native dispatch needs, writing its id to `~/.codex/native-relay.json`. The `<node>` is resolved rather than inherited: Codex Desktop authenticates the code-signing identity of any process that connects to its native tools pipe, so on macOS the installer registers the runtime the app ships and prints the `relay runtime:` line naming it and where it came from. `CODEX_NATIVE_RELAY_NODE` overrides that on any platform; Windows and Linux keep the Node running the installer, as before. The bootstrap creates one thread, unsubscribes it, and closes its connection. It leaves other clients and threads running; an idle server may retain the executor until its configured unload delay expires.
 
 ```bash
 codex mcp get codex-native-relay
@@ -384,6 +380,7 @@ Under `owned`, a thread a human opened is **unreachable rather than merely restr
 |---|---|---|
 | `list_claude_sessions` | Lists Claude Code sessions running on this machine (name, pid, sessionId, cwd, entrypoint). | read-only |
 | `send_to_claude_session` | Sends to a Claude inbox and waits for a correlated reply. Receipt statuses distinguish `reply_received`, `sent_unconfirmed`, `reply_timeout`, and receiver policy outcomes such as `held` or `refused`. `waitSec: 0` sends without waiting for confirmation. Prefer an exact `sessionId` because session names can change. | destructive |
+| `read_claude_delivery` | Inspects the latest recipient receipt or correlated reply by original message ID without resending or clearing the inbox. Receipts belong to this MCP process; an unknown ID after reconnect never proves non-delivery. | read-only |
 | `read_claude_inbox` | Reads **and clears** messages Claude pushed over on its own, including replies that arrived late. | destructive |
 | `read_claude_transcript` | Reads a Claude session's recent conversation without sending anything. | read-only |
 | `bind_codex_thread` | Binds a Codex thread so every message from Claude is relayed into it, **visible in the Codex desktop app**. Pass an empty string to stop. | writes |
@@ -391,7 +388,15 @@ Under `owned`, a thread a human opened is **unreachable rather than merely restr
 
 Every tool declares MCP annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), because a client decides whether a call needs a human in the loop from those hints and a missing one reads as "unknown". Two are worth naming: `read_claude_inbox` empties the inbox as it reads it, so it is **not** read-only despite the name, and `claude_bridge_status` registers the peer endpoint on first call, so it writes too.
 
-Waited sends to the same Claude session run in order. If an earlier send timed out or used `waitSec: 0` and its reply has not arrived, a new waited send returns `PEER_REPLY_PENDING` before delivering another message. Wait for the earlier reply and inspect `read_claude_inbox`, or use `waitSec: 0` if another asynchronous message is intended. Different destination sessions remain independent.
+Desktop task mode (`CODEX_BRIDGE_DESKTOP_TASKS=1` or the shared setting written by `codex-native-relay-install --desktop-tasks`) applies in both directions. `list_claude_sessions` only offers sessions advertised by Claude Desktop (`entrypoint: claude-desktop`), and sending refuses CLI or unknown entrypoints before connecting. Targets must match a unique exact session ID, PID, or name; partial names are not accepted. Open or reconnect an existing Code session in Claude Desktop at the intended project when none is available. Do not launch a replacement CLI session: CLI and Desktop have separate conversation histories. Legacy mode still supports CLI sessions.
+
+`claude_bridge_status` reports the destination policy, eligible session count, and excluded non-Desktop count. Send receipts include the destination's `entrypoint`, `cwd`, and `sessionId`. A correlated reply confirms receipt in that session; it does not independently prove that its conversation is visible in the Desktop UI. Desktop sends require `expectedCwd`, an absolute independently verified project directory. The bridge resolves both paths and refuses a missing, nonexistent, parent, or different directory before sending; it rechecks the destination after queueing. Reconnect the bridge's MCP connection after upgrading to load the enforcement code.
+
+Sends to the same Claude session run in order. An outstanding message blocks all further sends to that session, including `waitSec: 0`; changing wait time must not bypass a held or uncertain delivery. Use `read_claude_delivery` with the original message ID to observe `held`, `expired`, `refused`, or a late reply. A transport error after writing began also retains pending ownership. Different destination sessions remain independent. A process restart loses in-memory receipts: retain the original ID and inspect the existing recipient conversation before any resend; never treat an unknown ID as permission to retry.
+
+Both bridge status tools report the loaded source fingerprint and process identity. Source or Desktop-routing configuration changes make the running process stale and block new sends until reconnect, while Claude inbox/receipt reads remain available. This guard applies only after the version containing it has loaded; upgrading files cannot retrofit the guard into an older process already running.
+
+Claude's [inbound permission controls](https://code.claude.com/docs/en/cross-session-messaging#control-inbound-messages) remain authoritative. A missing sender permission class can cause a bypassing recipient to hold the message. Do not change `CLAUDE_BRIDGE_PERMISSION_MODE` or recipient settings merely to bypass a hold/refusal. Configure a sender class only when it truthfully represents every session using that MCP entry. If the Desktop UI does not expose the pending approval, report that boundary and keep the original receipt rather than creating a CLI session.
 
 Claude Desktop disables the CLI-native `SendMessage` tool. For Desktop targets, the bridge requests an ordinary answer in the destination conversation and reads only a completed assistant turn descended from the injected message UUID. Unrelated human prompts and sidechains are excluded. Late answers remain available through the inbox while the bridge process is running. This does not change Desktop tool permissions or the receiver's inbound policy.
 
@@ -535,6 +540,8 @@ python3 -c "import json;[print(v['properties']['method'].get('const') or v['prop
 
 **The Codex app says a thread is "open in another application".** The app-server holds a writer lock while the thread is loaded. With `releaseAfterTurn: true`, the bridge unsubscribes after completion; unload can still wait for the server's idle delay or another subscriber. Open the thread after it unloads. Use `stop_codex_app_server` only when all work on that shared server may be stopped. A thread held by a different Codex window must be released there. To keep a thread open in Codex Desktop while Claude messages into it, use the [native relay](#codex-desktop-native-relay), which never takes a second writer lock.
 
+**Desktop delivery fails on macOS while the relay reports itself installed.** The companion still creates its socket and `native_relay_status` still reports the native pipe, because Codex Desktop accepts the connection and only then closes it: it authenticates the connecting process's code-signing identity first, and a companion running under a Node build signed by anyone other than the vendor is refused. Every send then fails hard as `NATIVE_DELIVERY_UNCONFIRMED` rather than falling back, since the companion was reached. The app records the refusal as `dynamic_app_tools_peer_rejected reason=untrusted-code-signing-identity` (`~/Library/Logs/com.openai.codex/<date>/`; a process the app did not spawn is logged as `missing-code-signing-identity` instead). Re-run `scripts/install-native-relay.mjs` and check its `relay runtime:` line — it must not say `process.execPath` when Codex Desktop is installed. Point `CODEX_NATIVE_RELAY_NODE` at the runtime inside the app bundle if discovery misses it, and restart Codex Desktop so it relaunches the companion.
+
 **`claude_bridge_status` says the delivery backend is `app-server` on Windows or macOS with the relay installed.** The `delivery:` line carries the reason: *"no companion socket at …"* means Codex Desktop has not launched the companion, so restart the app after `install-native-relay.mjs` and check `codex mcp get codex-native-relay`; *"disabled by CODEX_BRIDGE_NATIVE_RELAY=0"* means it was switched off in the MCP server's `env`; *"unavailable on Linux"* means the native relay is not supported there. A relay that is reachable but has no executor thread fails at send time instead, with `RELAY_THREAD_UNCONFIGURED` naming both `CODEX_RELAY_ID` and the file to bootstrap.
 
 **A thread opens against the wrong directory.** The same project sits at a different absolute path on each machine: on the shared drive's letter under Windows, under its mount point when that drive is visible from macOS (**read-only** there), and in a native checkout otherwise. Since 1.4.0 the bridge picks the candidate that both **exists and is writable** on the current machine and prints a `note: cwd remapped …` line whenever it rewrites one. If nothing usable exists it fails immediately instead of opening a thread somewhere wrong. Handing Codex a read-only cwd is a reliable way to hit the freeze above: it runs a few reads, then asks for write permission and stalls.
@@ -578,6 +585,7 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `CODEX_NATIVE_RELAY_SOCKET` | Windows named pipe or `$CODEX_HOME/native-relay.sock` on macOS | Override the companion endpoint on both halves of the relay. |
 | `CODEX_NATIVE_RELAY_METHOD` | `tools/call` | The undocumented Codex Desktop JSON-RPC method the companion dispatches through; override only for a verified protocol change. |
 | `CODEX_NATIVE_RELAY_NAME` | `codex-native-relay` | The MCP server name `scripts/install-native-relay.mjs` registers with Codex. |
+| `CODEX_NATIVE_RELAY_NODE` | the runtime Codex Desktop ships on macOS, otherwise `process.execPath` | Node runtime `scripts/install-native-relay.mjs` registers the companion under. Codex Desktop rejects a peer whose code-signing identity is not its own, so the companion has to run under a runtime the app trusts. |
 | `CLAUDE_BRIDGE_PEER_NAME` | `codex-<pid>` | The name Claude shows for this bridge in its agent list. |
 | `CLAUDE_BRIDGE_CWD` | the process cwd | The working directory the peer advertises. |
 | `CLAUDE_DESKTOP_CONFIG` | auto-detected | Override the config path used by `install-claude-desktop.mjs`. |
@@ -641,7 +649,7 @@ The Codex → Claude direction has its own live check:
 
 ```bash
 npm run check:claude                                    # list the Claude sessions Codex can see
-CLAUDE_TARGET=<sessionId> CLAUDE_WAIT=150 npm run check:claude   # deliver a message and wait for the answer
+CLAUDE_TARGET=<sessionId> CLAUDE_EXPECTED_CWD=/absolute/project CLAUDE_WAIT=150 npm run check:claude   # deliver a message and wait for the answer
 ```
 
 A reply coming back proves both directions work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.13.3",
+  "version": "1.13.4",
   "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/scripts/check-claude-bridge.mjs

@@ -12,6 +12,7 @@ const transport = new StdioClientTransport({
 });
 const client = new Client({ name: "claude-bridge-check", version: "1.0.0" });
 try {
+  console.log("This diagnostic starts a separate MCP process; it does not reload or verify an existing Desktop task's MCP connection.");
   await client.connect(transport);
 
   const tools = await client.listTools();
@@ -32,7 +33,7 @@ try {
     console.log(`\nsending to "${target}" (waiting ${waitSec}s)...`);
     const sent = await client.callTool({
       name: "send_to_claude_session",
-      arguments: { target, message, waitSec },
+      arguments: { target, message, waitSec, expectedCwd: process.env.CLAUDE_EXPECTED_CWD },
     });
     console.log("\n--- send_to_claude_session ---\n" + sent.content[0].text);
     if (sent.isError) throw new Error("Claude message roundtrip failed; receipt or outcome is unconfirmed");

package/scripts/install-codex-mcp.mjs

@@ -6,6 +6,8 @@ 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";
 
 exitForVersionRequest(import.meta.url);
 
@@ -29,22 +31,17 @@ if (remove) {
   process.exit(0);
 }
 
-try {
-  run(["mcp", "remove", serverName]);
-} catch {
-  // not registered yet
-}
-
-const args = ["mcp", "add", serverName];
-const peerName = process.env.CLAUDE_BRIDGE_PEER_NAME;
-if (peerName) args.push("--env", `CLAUDE_BRIDGE_PEER_NAME=${peerName}`);
-if (permissionMode) args.push("--env", `CLAUDE_BRIDGE_PERMISSION_MODE=${permissionMode}`);
-args.push("--", process.execPath, entry);
-
-run(args);
+const servers = JSON.parse(run(["mcp", "list", "--json"]));
+if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
+const existing = servers.some((server) => server.name === serverName)
+  ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
+const registration = codexMcpRegistration({ name: serverName, existing, node: process.execPath, entry, env: process.env, desktopOnly: desktopTasksConfigured() });
+run(registration.args);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`registered MCP server "${serverName}" with Codex:`);
-console.log(run(["mcp", "get", serverName]));
-console.log("\nRestart the Codex app (or start a new Codex session) to load the bridge.");
+console.log(`command: ${process.execPath} ${entry}`);
+console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
+console.log("\nReconnect the MCP server in the existing Codex Desktop task, or restart the app and reopen that same task. Do not create a replacement task.");
+console.log("Verify claude_bridge_status from that task: 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(`remove: node scripts/install-codex-mcp.mjs --remove`);

package/scripts/install-native-relay.mjs

@@ -6,12 +6,21 @@ import { fileURLToPath } from "node:url";
 
 import { CodexAppServerClient } from "../src/app-server-client.mjs";
 import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
-import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import {
+  IS_MACOS,
+  IS_WINDOWS,
+  PLATFORM_LABEL,
+  hasCodexDesktopApp,
+  homeDir,
+  resolveCodexBin,
+  resolveCodexDesktopNodeBin,
+  spawnEnv,
+} from "../src/platform.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.13.3";
+const VERSION = "1.13.4";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "native-relay-companion.mjs");
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";
@@ -56,9 +65,32 @@ try {
 } catch {
   // not registered yet
 }
-run(["mcp", "add", serverName, "--", process.execPath, entry]);
+/**
+ * Registering under whichever Node happens to run this installer is what made
+ * the companion unreachable on macOS: Codex Desktop rejects a peer whose
+ * code-signing identity is not the vendor's, so the relay reported itself
+ * installed while every delivery failed. Resolve a runtime the app trusts
+ * instead, and print it - a mismatch has to be visible here rather than
+ * inferred later from a delivery that never confirms.
+ */
+const runtime = resolveCodexDesktopNodeBin();
+
+run(["mcp", "add", serverName, "--", runtime.path, entry]);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
+console.log(`relay runtime: ${runtime.path} (${runtime.source})`);
+if (runtime.source === "process.execPath" && hasCodexDesktopApp()) {
+  console.log(
+    "\nNOTE: no Codex Desktop runtime was found, so the companion is registered under this Node.",
+  );
+  console.log(
+    "Codex Desktop rejects peers whose code-signing identity is not its own (untrusted-code-signing-identity),",
+  );
+  console.log(
+    "so delivery can fail while the relay still reports itself installed. Set CODEX_NATIVE_RELAY_NODE to the",
+  );
+  console.log("runtime shipped inside Codex Desktop if that happens.");
+}
 console.log(`registered MCP server "${serverName}" with Codex:`);
 console.log(run(["mcp", "get", serverName]));
 

package/src/claude-bridge.mjs

@@ -5,19 +5,23 @@ import { z } from "zod";
 
 import { CodexAppServerClient } from "./app-server-client.mjs";
 import { PLATFORM_LABEL } from "./platform.mjs";
-import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
+import { PeerEndpoint, assertClaudeSessionCwd, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
+import { desktopTasksConfigured } from "./native-relay.mjs";
+import { createRuntimeState } from "./runtime-state.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.13.3";
+const VERSION = "1.13.4";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 
 const log = (msg) => process.stderr.write(`[claude-bridge] ${msg}\n`);
 
 const defaultPeerName = process.env.CLAUDE_BRIDGE_PEER_NAME ?? `codex-${process.pid}`;
+const desktopOnly = desktopTasksConfigured();
+const runtime = createRuntimeState({ configuration: desktopTasksConfigured });
 
 const peer = new PeerEndpoint({
   name: defaultPeerName,
@@ -36,7 +40,7 @@ const codex = new CodexAppServerClient({
  * other thread through the shared one. `claude-bridge` never picks between
  * them - see `thread-delivery.mjs`.
  */
-const delivery = createThreadDelivery({ codex, log });
+const delivery = createThreadDelivery({ codex, log, desktopOnly });
 
 const forwarding = {
   threadId: process.env.CODEX_THREAD_ID ?? null,
@@ -49,7 +53,12 @@ const textResult = (text, isError = false) => ({
   ...(isError ? { isError: true } : {}),
 });
 
-const failure = (err) => textResult(`Claude bridge error: ${err?.message ?? String(err)}`, true);
+const failure = (err) => ({
+  ...textResult(`Claude bridge error: ${err?.message ?? String(err)}${err?.msgId ? `\nMessage id: ${err.msgId}; inspect read_claude_delivery before any resend.` : ""}`, true),
+  ...(err?.msgId ? { structuredContent: { receipt: peer.readDelivery(err.msgId) } } : {}),
+});
+
+const missingDesktopSession = "No live Claude Desktop session with an exact matching ID or name and a messaging endpoint. Open or reconnect an existing Code session in Claude Desktop for the intended project. CLI sessions are excluded; do not launch a replacement CLI session.";
 
 function formatSessionRow(s) {
   const started = s.startedAt ? new Date(s.startedAt).toISOString().replace("T", " ").slice(0, 16) : "?";
@@ -75,6 +84,7 @@ async function forwardToCodexThread(record) {
   forwarding.lastAt = now;
   forwarding.count += 1;
   try {
+    runtime.assertCurrent();
     const { backend } = await delivery.deliver(
       forwarding.threadId,
       `[message from Claude session ${record.fromSocket ?? "?"}]\n\n${record.text}`,
@@ -96,7 +106,10 @@ const server = new McpServer(
       "Talk to a live Claude Code session from Codex. list_claude_sessions finds the session, " +
       "send_to_claude_session sends to its peer transport and waits for a reply to confirm receipt. " +
       "This bridge registers itself as a peer, so Claude sees it in its own agent list and can " +
-      "message back; bind_codex_thread relays those messages into a Codex thread.",
+      "message back; bind_codex_thread relays those messages into a Codex thread. " +
+      "In Desktop-only mode, both destinations must belong to their Desktop apps. " +
+      "Use an existing session with the exact project directory and sessionId; never launch a CLI session " +
+      "or an external app-server as a substitute. A receipt confirms a reply, not visual verification in the app.",
   },
 );
 
@@ -106,7 +119,7 @@ server.registerTool(
     title: "List live Claude Code sessions",
     description:
       "List Claude Code sessions running on this machine (name, pid, sessionId, cwd, how it was started). " +
-      "Use it to pick the session to talk to.",
+      "In Desktop-only mode, only Claude Desktop Code sessions are listed. Match the exact project cwd and sessionId before sending.",
     inputSchema: {
       includeDead: z.boolean().optional().describe("Also list sessions whose process is gone (default false)"),
     },
@@ -118,10 +131,10 @@ server.registerTool(
   async ({ includeDead }) => {
     try {
       const sessions = listClaudeSessions({ includeDead: includeDead ?? false }).filter(
-        (s) => s.pid !== process.pid,
+        (s) => s.pid !== process.pid && (!desktopOnly || s.entrypoint === "claude-desktop"),
       );
-      if (!sessions.length) return textResult("No live Claude Code session found.");
-      return textResult(`${sessions.length} Claude session(s):\n\n${sessions.map(formatSessionRow).join("\n")}`);
+      if (!sessions.length) return textResult(desktopOnly ? missingDesktopSession : "No live Claude Code session found.");
+      return textResult(`${sessions.length} Claude${desktopOnly ? " Desktop" : ""} session(s):\n\n${sessions.map(formatSessionRow).join("\n")}`);
     } catch (err) {
       return failure(err);
     }
@@ -135,11 +148,13 @@ server.registerTool(
     description:
       "Send a message to a running Claude Code session's peer transport and wait for its reply. " +
       "A socket write alone does not confirm that Claude received the message. Set waitSec to 0 to send without confirmation. " +
-      "A waited send is refused while earlier messages to that session still await replies; " +
-      "wait for those replies and read_claude_inbox before trying again.",
+      "Every send is refused while earlier messages to that session still await replies, including waitSec 0; " +
+      "wait for those replies and read_claude_inbox before trying again. Desktop-only mode refuses CLI or unknown " +
+      "entrypoints, partial names, ambiguous targets, and a missing or mismatched expectedCwd before sending. It never creates a replacement session.",
     inputSchema: {
       target: z.string().describe("Session name, pid or sessionId from list_claude_sessions"),
       message: z.string().describe("The message text to deliver"),
+      expectedCwd: z.string().optional().describe("Exact absolute project directory independently verified by the caller; required in Desktop-only mode"),
       waitSec: z
         .number()
         .int()
@@ -155,26 +170,36 @@ server.registerTool(
       openWorldHint: true,
     },
   },
-  async ({ target, message, waitSec }) => {
+  async ({ target, message, waitSec, expectedCwd }) => {
     try {
+      runtime.assertCurrent();
+      const session = findClaudeSession(target, { desktopOnly });
+      if (!session) return textResult(desktopOnly ? missingDesktopSession : `No live Claude session matches "${target}".`, true);
+      if (desktopOnly || expectedCwd !== undefined) assertClaudeSessionCwd(session, expectedCwd);
       await peer.start();
-      const session = findClaudeSession(target);
-      if (!session) return textResult(`No live Claude session matches "${target}".`, true);
 
       const wait = waitSec ?? 180;
       const desktop = session.entrypoint === "claude-desktop";
       const text = desktop ? `${message}\n\n[Bridge response routing: reply with ordinary text in this conversation. The bridge reads the response associated with this message from the local transcript; no cross-session reply tool is needed.]` : message;
       const { msgId, reply, delivery } = await peer.sendAndWait(session.socket, text, {
         timeoutMs: wait * 1000,
+        beforeSend: () => {
+          runtime.assertCurrent();
+          const current = findClaudeSession(session.sessionId ?? String(session.pid), { desktopOnly });
+          if (!current || current.pid !== session.pid || current.socket !== session.socket) {
+            throw new Error("The Claude destination changed while this message was queued. No message was sent; inspect the existing Desktop session.");
+          }
+          if (desktopOnly || expectedCwd !== undefined) assertClaudeSessionCwd(current, expectedCwd);
+        },
         ...(desktop ? { transcriptSession: session } : {}),
       });
       const status = reply ? "reply_received" : delivery?.status ?? (wait === 0 ? "sent_unconfirmed" : "reply_timeout");
-      const receipt = { status, msgId, target: session.name ?? String(session.pid), sessionId: session.sessionId, waitSec: wait, ...(reply ? { source: reply.source ?? "peer" } : {}) };
+      const receipt = { status, msgId, target: session.name ?? String(session.pid), sessionId: session.sessionId, cwd: session.cwd, entrypoint: session.entrypoint, waitSec: wait, ...(reply ? { source: reply.source ?? "peer" } : {}) };
       const result = (text, isError = false) => ({ ...textResult(text, isError), structuredContent: { receipt } });
-      const targetLabel = `${session.name ?? session.pid} (pid ${session.pid}, session ${session.sessionId ?? "?"})`;
+      const targetLabel = `${session.name ?? session.pid} (pid ${session.pid}, session ${session.sessionId ?? "?"}, via ${session.entrypoint ?? "unknown"}, cwd ${session.cwd ?? "?"})`;
 
       if (!reply && delivery && delivery.status !== "delivered") {
-        return result(`Claude inbox reported ${delivery.status} for ${targetLabel}.\n${delivery.reason}\nMessage id: ${msgId}`, true);
+        return result(`Claude inbox reported ${delivery.status} for ${targetLabel}.\n${delivery.reason}\nMessage id: ${msgId}\nInspect read_claude_delivery with this message ID. Do not resend, change the sender permission class, or alter recipient permissions to bypass this receipt.`, true);
       }
 
       if (wait === 0) {
@@ -195,6 +220,21 @@ server.registerTool(
   },
 );
 
+server.registerTool(
+  "read_claude_delivery",
+  {
+    title: "Inspect a Claude message receipt without resending",
+    description: "Read the latest recipient control receipt or correlated reply for a message sent by this MCP process. Unknown IDs do not prove non-delivery; retain the original receipt after a reconnect and inspect the existing Claude session before any resend.",
+    inputSchema: { msgId: z.string().describe("The original message ID returned by send_to_claude_session") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  async ({ msgId }) => {
+    const receipt = peer.readDelivery(msgId);
+    if (!receipt) return textResult("This MCP process has no receipt for that message ID. It may belong to a previous process; do not infer failure or resend. Inspect the original Claude Desktop session.", true);
+    return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { receipt } };
+  },
+);
+
 server.registerTool(
   "read_claude_inbox",
   {
@@ -310,18 +350,25 @@ server.registerTool(
     try {
       await peer.start();
       const sessions = listClaudeSessions().filter((s) => s.pid !== process.pid);
+      const eligible = sessions.filter((session) => !desktopOnly || session.entrypoint === "claude-desktop");
       const lines = [
         `platform:      ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
         `bridge:        claude-bridge ${VERSION}`,
         `peer name:     ${peer.name}   (Claude sees this in its agent list)`,
         `peer socket:   ${peer.socketPath}`,
         `sender mode:   ${peer.permissionMode ?? "unknown (recipient may hold messages for approval)"}`,
-        `live sessions: ${sessions.length}`,
+        `session policy: ${desktopOnly ? "desktop-only" : "all Claude Code entrypoints"}`,
+        `live sessions: ${eligible.length}`,
+        `excluded:      ${sessions.length - eligible.length} non-Desktop session(s)`,
         `relay thread:  ${forwarding.threadId ?? "(none - use bind_codex_thread)"}`,
         `delivery:      ${delivery.describe()}`,
         `inbox:         ${peer.inbox.length} pending message(s)`,
+        `outstanding:   ${peer.pendingMessages.size} message(s) awaiting receipt or reply`,
+        ...[...peer.pendingMessages.keys()].map((id) => `pending message: ${id} (${peer.readDelivery(id)?.status ?? "sent_unconfirmed"})`),
       ];
-      return textResult(lines.join("\n"));
+      const state = runtime.status();
+      lines.push(`runtime pid:   ${state.pid}`, `loaded source: ${state.revision}`, `disk source:   ${state.diskRevision ?? "unreadable"}`, `runtime state: ${state.current ? "current" : `STALE - ${state.reason}; reconnect this MCP server in the existing task`}`);
+      return { ...textResult(lines.join("\n"), !state.current), structuredContent: { runtime: state } };
     } catch (err) {
       return failure(err);
     }

package/src/codex-mcp-registration.mjs

@@ -0,0 +1,25 @@
+export function codexMcpRegistration({ name, existing, node, entry, env, desktopOnly }) {
+  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. Keep that entry and update only its command/args using Codex settings; the installer will not remove or reset it.");
+    }
+  }
+  const values = { ...existing?.transport?.env };
+  for (const key of ["CLAUDE_BRIDGE_PEER_NAME", "CLAUDE_BRIDGE_PERMISSION_MODE", "CODEX_BRIDGE_DESKTOP_TASKS"]) {
+    if (env[key] !== undefined) values[key] = env[key];
+  }
+  values.CODEX_BRIDGE_DESKTOP_TASKS ??= desktopOnly ? "1" : "0";
+  if (!["0", "1"].includes(values.CODEX_BRIDGE_DESKTOP_TASKS)) throw new Error("CODEX_BRIDGE_DESKTOP_TASKS must be 0 or 1");
+  if (values.CLAUDE_BRIDGE_PERMISSION_MODE !== undefined && !["bypass", "prompting"].includes(values.CLAUDE_BRIDGE_PERMISSION_MODE)) {
+    throw new Error("CLAUDE_BRIDGE_PERMISSION_MODE must be bypass or prompting; never infer it from the recipient");
+  }
+  if (values.CODEX_BRIDGE_DESKTOP_TASKS === "1") values.CODEX_BRIDGE_AUTOSTART = "0";
+  const args = ["mcp", "add", name];
+  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
+    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], environmentKeys: Object.keys(values).sort() };
+}

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.4";
 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.4";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {

package/src/peer-protocol.mjs

@@ -187,9 +187,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 +211,24 @@ 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.`);
+  }
+}
+
 /**
  * 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 +322,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 +463,12 @@ 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];
+    if (key && this.pendingMessages.get(key)?.targetSocket === record.fromSocket) {
+      const sent = this.sentMessages.get(key);
+      if (sent) 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); }
@@ -503,6 +539,7 @@ export class PeerEndpoint {
             settled = true;
             globalThis.clearTimeout(timer);
             if (error) {
+              if (connected || writeStarted) error.deliveryUncertain = true;
               reject({ error, retryable: !connected && !writeStarted });
             } else {
               resolve();
@@ -534,14 +571,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 } = {}) {
     const previous = this.requestQueues.get(targetSocket) ?? Promise.resolve();
     const pending = previous.catch(() => {}).then(async () => {
+      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 +589,31 @@ 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 });
+      if (transcriptSession && !this.responsePoll) {
+        this.responsePoll = globalThis.setInterval(() => this.#refreshTranscriptReplies(), 250);
+        this.responsePoll.unref();
+      }
       try {
         const sentId = await this.send(targetSocket, text, { priority, msgId });
         if (sentId !== msgId) {
           const pendingMessage = this.pendingMessages.get(msgId);
           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 +631,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);
@@ -596,6 +644,7 @@ export class PeerEndpoint {
    */
   waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now(), afterSequence = null, msgId } = {}) {
     const matches = (record) => record.fromSocket === fromSocket
+      && (!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);
@@ -624,6 +673,24 @@ export class PeerEndpoint {
     return messages;
   }
 
+  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,
+      pending: this.pendingMessages.has(msgId),
+      ...(sent.reply ? { reply: sent.reply.text, source: sent.reply.source ?? "peer" } : {}),
+    };
+  }
+
   stop() {
     globalThis.clearInterval(this.responsePoll);
     this.responsePoll = null;

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

package/src/runtime-state.mjs

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+export function createRuntimeState({ directory = path.dirname(fileURLToPath(import.meta.url)), configuration = () => null } = {}) {
+  const fingerprint = () => {
+    const hash = createHash("sha256");
+    for (const file of ["../package.json", ...readdirSync(directory).filter((file) => file.endsWith(".mjs")).sort()]) {
+      hash.update(file).update("\0").update(readFileSync(path.join(directory, file))).update("\0");
+    }
+    return hash.digest("hex");
+  };
+  const revision = fingerprint();
+  const configured = JSON.stringify(configuration());
+  const startedAt = new Date().toISOString();
+  const status = () => {
+    let diskRevision = null;
+    let reason = null;
+    try {
+      diskRevision = fingerprint();
+      if (diskRevision !== revision) reason = "Bridge source changed after this MCP process started";
+      else if (JSON.stringify(configuration()) !== configured) reason = "Bridge routing configuration changed after this MCP process started";
+    } catch {
+      reason = "Bridge source or routing configuration can no longer be read";
+    }
+    return { pid: process.pid, startedAt, revision, diskRevision, current: reason === null, reason };
+  };
+  const assertCurrent = () => {
+    const state = status();
+    if (!state.current) throw new Error(`${state.reason}. Reconnect this MCP server in the existing Desktop task before sending. No message was sent; do not create a replacement task or use an external app-server.`);
+  };
+  return { status, assertCurrent };
+}

package/src/thread-delivery.mjs

@@ -64,8 +64,9 @@ export class DesktopTaskDelivery {
 
   async withThread(threadId, operation, { deadline } = {}) {
     const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
+    let expired = false;
     const current = previous.catch(() => {}).then(() => {
-      if (deadline !== undefined && this.now() >= deadline) throw new Error("The response deadline elapsed while another operation held this thread. No new prompt was sent.");
+      if (expired || (deadline !== undefined && this.now() >= deadline)) throw new Error("The response deadline elapsed while another operation held this thread. No new prompt was sent.");
       return operation();
     });
     this.threadOperations.set(threadId, current);
@@ -75,7 +76,10 @@ export class DesktopTaskDelivery {
     let timer;
     try {
       return await Promise.race([current, new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error("The Desktop response deadline elapsed. A previous operation may still be running; inspect the existing task before sending anything again.")), Math.max(1, deadline - this.now()));
+        timer = setTimeout(() => {
+          expired = true;
+          reject(new Error("The Desktop response deadline elapsed. A previous operation may still be running; inspect the existing task before sending anything again."));
+        }, Math.max(1, deadline - this.now()));
       })]);
     } finally {
       clearTimeout(timer);