@minhspark/codex-mcp-bridge 1.19.0 → 1.19.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.19.1] - 2026-09-29
+
+### Fixed
+
+- Recognize `codex_work_desktop` as a local Desktop sender while retaining exact host task/turn, workspace, and lifecycle checks (#84). Its permission profile is classified like that of any other Codex Desktop task, including the managed sandboxes supported since 1.19.0 (#83). Claude's inbound policy and permission parity checks are unchanged.
+- Read completed native replies from `codex_work_desktop` tasks and correlate both raw and XML-escaped Desktop dispatch envelopes to the exact sent prompt (#84). Task, workspace, turn, executor, and pre-send watermark checks remain required for automatic reply observation.
+- Preserve confirmed native send acceptance when the overall response deadline expires (#84). The timeout does not release the underlying operation's thread lock, retry a prompt, or turn an unconfirmed send into a successful delivery.
+- Avoid a Windows Node 24.13.0 native crash when preparing supervisor and MCP contract test fixtures from a Unicode checkout path by awaiting asynchronous directory copies (#84).
+- Stop refusing Claude → Codex callers on Windows because Windows PowerShell started slowly (#42). The caller check reads the process ancestry in a fresh Windows PowerShell that first compiles its Toolhelp helper, and the five-second fail-closed deadline covered that startup as well as the read. On a cold or contended machine the startup alone has taken 5 to 15 seconds: CI refused callers with `INSPECTION_TIMEOUT` before the script had begun (5,036 ms) and while the helper was still compiling (5,017 ms), although the read itself takes about 60 ms. The helper now reports when it is ready, and the five-second deadline starts there. Getting ready has its own 25-second ceiling, so a whole read still ends within the 30 seconds the bridge gives its other PowerShell identity reads. Either expiry still refuses the caller, and a slow start is reported as `INSPECTOR_START_TIMEOUT`. The helper also writes its JSON itself, so the timed read no longer loads PowerShell's JSON serializer.
+- Lock `ip-address` at 10.7.2 for development installs (#87). 10.5.0 misclassified IPv6 link-local and NAT64 local-use addresses. The bridge's stdio servers never load the rate-limiting code that uses it, and the published package ships no lockfile, so installs from npm resolve their own versions.
+
 ## [1.19.0] - 2026-09-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.19.0",
+  "version": "1.19.1",
   "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/install-native-relay.mjs

@@ -22,7 +22,7 @@ import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.0";
+const VERSION = "1.19.1";
 const root = 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

@@ -26,7 +26,7 @@ import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs"
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.0";
+const VERSION = "1.19.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/claude-sender-context.mjs

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
 import { listClaudeSessions } from "./peer-protocol.mjs";
@@ -6,12 +6,35 @@ import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
 
 const execute = promisify(execFile);
 const MAX_ANCESTORS = 8;
+const INSPECTION_OUTPUT_LIMIT = 16384;
+
+/**
+ * The five-second deadline is what keeps the caller check fail-closed: a read
+ * that cannot answer in time leaves the caller unverified. On Windows the read
+ * runs in a fresh Windows PowerShell that must first compile its Toolhelp
+ * helper, and the deadline used to cover that startup too. Starting is the
+ * machine's cost, not the read's: CI refused callers with INSPECTION_TIMEOUT
+ * both before the script had begun (5,036ms) and while the helper was still
+ * compiling (5,017ms), a cold start here has been measured between 5s and 15s,
+ * and the read itself takes milliseconds once the helper exists.
+ *
+ * The helper therefore reports on stderr when it is ready, and the five-second
+ * deadline starts there. Getting ready has its own ceiling, so a whole read
+ * still ends within the 30s the bridge gives its other PowerShell identity
+ * reads (peer-protocol.mjs). Either expiry kills the process and refuses the
+ * caller; nothing is read before the helper is ready, so the wait adds no
+ * staleness.
+ */
+const INSPECTION_TIMEOUT_MS = 5000;
+const INSPECTOR_START_TIMEOUT_MS = 25000;
+const INSPECTOR_READY_MARKER = "BRIDGE_ANCESTRY_READY";
 const WINDOWS_ANCESTRY_SOURCE = `
 using System;
 using System.Collections.Generic;
 using System.ComponentModel;
 using System.Globalization;
 using System.Runtime.InteropServices;
+using System.Text;
 
 public static class ClaudeProcessAncestry {
   [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
@@ -83,6 +106,17 @@ public static class ClaudeProcessAncestry {
     }
     return rows.ToArray();
   }
+
+  public static string ReadJson(uint firstPid, int limit) {
+    var json = new StringBuilder("[");
+    foreach (var row in Read(firstPid, limit)) {
+      if (json.Length > 1) json.Append(',');
+      json.Append(@"{""pid"":").Append(row.pid.ToString(CultureInfo.InvariantCulture))
+        .Append(@",""parentPid"":").Append(row.parentPid.ToString(CultureInfo.InvariantCulture))
+        .Append(@",""processStart"":""").Append(row.processStart).Append(@"""}");
+    }
+    return json.Append(']').ToString();
+  }
 }`;
 
 function parseWindowsAncestry(stdout, parentPid, limit) {
@@ -105,26 +139,77 @@ function parseWindowsAncestry(stdout, parentPid, limit) {
   return rows;
 }
 
-export async function readProcessAncestry({ parentPid = process.ppid, platform = process.platform, maxDepth = MAX_ANCESTORS, run = execute } = {}) {
+/**
+ * Runs a process the way execFile does - the same stdout and stderr strings,
+ * maxBuffer limit, and exit-code and spawn errors - except that `timeout`
+ * starts once `readyMarker` appears on stderr, and `startupTimeout` bounds the
+ * time before it. An expiry kills the process and rejects with ETIMEDOUT and
+ * the phase that ran out. The result also carries the pid, readyAfterMs and
+ * elapsedMs so tests can report where the time went.
+ */
+export function runProcessInspector(command, args, { timeout, startupTimeout, readyMarker, maxBuffer = Infinity, windowsHide = true } = {}) {
+  return new Promise((resolve, reject) => {
+    const started = performance.now();
+    const child = spawn(command, args, { windowsHide, stdio: ["ignore", "pipe", "pipe"] });
+    const output = { stdout: [], stderr: [] };
+    const size = { stdout: 0, stderr: 0 };
+    let readyAfterMs = null;
+    let settled = false;
+    let timer;
+    const text = (stream) => Buffer.concat(output[stream]).toString("utf8");
+    const settle = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error && child.pid !== undefined && child.exitCode === null && child.signalCode === null) child.kill();
+      const result = { stdout: text("stdout"), stderr: text("stderr"), pid: child.pid, readyAfterMs, elapsedMs: Math.round(performance.now() - started) };
+      if (error) reject(Object.assign(error, result));
+      else resolve(result);
+    };
+    const arm = (phase, ms) => {
+      clearTimeout(timer);
+      timer = setTimeout(() => settle(Object.assign(new Error(`Process inspection ${phase} deadline elapsed`), { code: "ETIMEDOUT", phase, killed: true, signal: "SIGTERM" })), ms);
+    };
+    if (readyMarker) arm("startup", startupTimeout);
+    else arm("inspection", timeout);
+    for (const stream of ["stdout", "stderr"]) {
+      child[stream].on("data", (chunk) => {
+        if (settled) return;
+        output[stream].push(chunk);
+        size[stream] += chunk.length;
+        if (size[stream] > maxBuffer) return settle(Object.assign(new RangeError(`${stream} maxBuffer length exceeded`), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }));
+        if (stream === "stderr" && readyMarker && readyAfterMs === null && text("stderr").includes(readyMarker)) {
+          readyAfterMs = Math.round(performance.now() - started);
+          arm("inspection", timeout);
+        }
+      });
+    }
+    child.on("error", settle);
+    child.on("close", (code, signal) => settle(code === 0 ? null : Object.assign(new Error(`Process inspection exited with ${signal ?? code}`), { code, signal })));
+  });
+}
+
+export async function readProcessAncestry({ parentPid = process.ppid, platform = process.platform, maxDepth = MAX_ANCESTORS, run } = {}) {
   if (!Number.isSafeInteger(parentPid) || parentPid <= 0 || parentPid > 0xffffffff) return [];
   const limit = Number.isInteger(maxDepth) && maxDepth > 0 ? Math.min(maxDepth, MAX_ANCESTORS) : MAX_ANCESTORS;
-  const options = { timeout: 5000, maxBuffer: 16384, windowsHide: true };
   if (platform === "win32") {
     const shell = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
-    const script = `$ErrorActionPreference='Stop'; $PSModuleAutoLoadingPreference='None'; Import-Module -Name ([IO.Path]::Combine($PSHOME,'Modules','Microsoft.PowerShell.Utility','Microsoft.PowerShell.Utility.psd1')) -ErrorAction Stop; Add-Type -TypeDefinition @'\n${WINDOWS_ANCESTRY_SOURCE}\n'@\nConvertTo-Json -InputObject @([ClaudeProcessAncestry]::Read(${parentPid},${limit})) -Compress`;
-    const { stdout } = await run(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], options);
+    const script = `$ErrorActionPreference='Stop'; $PSModuleAutoLoadingPreference='None'; Import-Module -Name ([IO.Path]::Combine($PSHOME,'Modules','Microsoft.PowerShell.Utility','Microsoft.PowerShell.Utility.psd1')) -ErrorAction Stop; Add-Type -TypeDefinition @'\n${WINDOWS_ANCESTRY_SOURCE}\n'@\n[Console]::Error.WriteLine('${INSPECTOR_READY_MARKER}')\n[Console]::Out.Write([ClaudeProcessAncestry]::ReadJson(${parentPid},${limit}))`;
+    const { stdout } = await (run ?? runProcessInspector)(shell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], {
+      timeout: INSPECTION_TIMEOUT_MS, startupTimeout: INSPECTOR_START_TIMEOUT_MS, readyMarker: INSPECTOR_READY_MARKER, maxBuffer: INSPECTION_OUTPUT_LIMIT, windowsHide: true,
+    });
     return parseWindowsAncestry(stdout, parentPid, limit);
   }
   const rows = [];
   const seen = new Set();
   let next = parentPid;
-  const deadline = Date.now() + 5000;
+  const deadline = Date.now() + INSPECTION_TIMEOUT_MS;
   while (next > 0 && !seen.has(next) && rows.length < limit) {
     seen.add(next);
     const remaining = deadline - Date.now();
     if (remaining <= 0) throw new Error("process inspection deadline elapsed");
-    const { stdout } = await run("/bin/ps", ["-p", String(next), "-o", "pid=,ppid=,lstart="], {
-      ...options, timeout: remaining, env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+    const { stdout } = await (run ?? execute)("/bin/ps", ["-p", String(next), "-o", "pid=,ppid=,lstart="], {
+      timeout: remaining, maxBuffer: INSPECTION_OUTPUT_LIMIT, windowsHide: true, env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
     });
     const match = stdout.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
     if (!match) break;
@@ -140,6 +225,7 @@ function senderResult(status, reason, values = {}) {
 }
 
 function senderFailureCode(error) {
+  if (error?.code === "ETIMEDOUT" && error.phase === "startup") return "INSPECTOR_START_TIMEOUT";
   if (error?.code === "ETIMEDOUT" || (error?.killed && ["SIGTERM", "SIGKILL"].includes(error.signal))) return "INSPECTION_TIMEOUT";
   if (error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return "OUTPUT_LIMIT";
   if (["ENOENT", "EACCES", "EPERM"].includes(error?.code)) return error.code;

package/src/codex-native-response.mjs

@@ -8,6 +8,7 @@ const MAX_ROLLOUT_BYTES = 16 * 1024 * 1024;
 const MAX_ENTRIES = 100000;
 const MAX_DIRECTORIES = 4096;
 const MAX_REPLY_BYTES = 1024 * 1024;
+const DESKTOP_ORIGINATORS = new Set(["Codex Desktop", "codex_work_desktop"]);
 const COMPLETED = new Set(["task_complete", "task_completed", "turn_complete", "turn_completed"]);
 const STARTED = new Set(["task_started", "turn_started"]);
 const FAILED = new Set(["task_aborted", "turn_aborted", "task_failed", "turn_failed"]);
@@ -155,12 +156,14 @@ function validateSession(records, threadId, expectedCwd) {
   const sessions = records.filter(({ record }) => record.type === "session_meta").map(({ record }) => record.payload);
   if (sessions.length !== 1) throw new Error("The Codex rollout has ambiguous session identity");
   const session = sessions[0];
-  if (session.id !== threadId || session.originator !== "Codex Desktop" || session.source !== "vscode") throw new Error("The rollout does not confirm the exact native Codex Desktop task");
+  if (session.id !== threadId || !DESKTOP_ORIGINATORS.has(session.originator) || session.source !== "vscode") throw new Error("The rollout does not confirm the exact native Codex Desktop task");
   if (canonicalDirectory(session.cwd, "The rollout workspace") !== expectedCwd) throw new Error("The rollout workspace does not match the selected native task");
 }
 
-function delegationOutput(executorThreadId, prompt) {
-  return `<codex_delegation>\n  <source_thread_id>${executorThreadId}</source_thread_id>\n  <input>${prompt}</input>\n</codex_delegation>`;
+function delegationOutputs(executorThreadId, prompt) {
+  const escaped = prompt.replace(/[&<>]/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[character]);
+  // Older Desktop rollouts stored raw text; current builds escape XML text content.
+  return [prompt, escaped].map((text) => `<codex_delegation>\n  <source_thread_id>${executorThreadId}</source_thread_id>\n  <input>${text}</input>\n</codex_delegation>`);
 }
 
 function normalizedText(value) {
@@ -214,7 +217,7 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
   if (requireDispatch) {
     const dispatches = turns.filter(({ record }) => record.type === "response_item" && record.payload.type === "function_call_output" &&
       record.payload.namespace === "codex_app" && record.payload.name === "send_message_to_thread");
-    if (dispatches.length !== 1 || dispatches[0].record.payload.output !== requireDispatch.output ||
+    if (dispatches.length !== 1 || !requireDispatch.outputs.includes(dispatches[0].record.payload.output) ||
         contexts[0].start >= dispatches[0].start || dispatches[0].start >= completions[0].start) {
       throw new Error("The newly observed turn is not correlated to the exact native dispatch");
     }
@@ -324,7 +327,7 @@ export function readCodexNativeTurnResponse({ threadId, turnId, previousTurnId,
     validateSession(records, threadId, cwd);
     const tail = records.filter(({ start }) => start >= watermark.size);
     const inspected = inspectTurnRecords(tail, threadId, turnId, cwd, {
-      requireDispatch: { output: delegationOutput(executorThreadId, prompt) },
+      requireDispatch: { outputs: delegationOutputs(executorThreadId, prompt) },
     });
     return { ...inspected, observationStatus: inspected.status };
   } catch (error) {

package/src/codex-sender-context.mjs

@@ -9,6 +9,7 @@ const STARTED = new Set(["task_started", "turn_started"]);
 const MAX_ROLLOUT_BYTES = 64 * 1024 * 1024;
 const MAX_ENTRIES = 100000;
 const MAX_DIRECTORIES = 4096;
+const DESKTOP_ORIGINATORS = new Set(["Codex Desktop", "codex_work_desktop"]);
 const PROMPTING_POLICIES = new Set(["on-request", "on-failure", "untrusted"]);
 const GRANULAR_CATEGORIES = ["sandbox_approval", "rules", "mcp_elicitations"];
 const MANAGED_REVIEWERS = new Set(["user", "auto_review"]);
@@ -213,7 +214,9 @@ export function readCodexSenderContext(meta, { env = process.env, maxRolloutByte
     const state = readState(file, Math.min(MAX_ROLLOUT_BYTES, maxRolloutBytes));
     const { session, context, lifecycle } = state;
     if (!["Codex Desktop", "codex_vscode"].includes(originator)) throw new Error("Unsupported calling host");
-    if (session?.id !== identity.threadId || session.originator !== originator || session.source !== "vscode") throw new Error(`The caller rollout does not confirm a root ${originator} task`);
+    const desktop = originator === "Codex Desktop";
+    const matchesOriginator = desktop ? DESKTOP_ORIGINATORS.has(session?.originator) : session?.originator === originator;
+    if (session?.id !== identity.threadId || !matchesOriginator || session.source !== "vscode") throw new Error(`The caller rollout does not confirm a root ${originator} 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);

package/src/index.mjs

@@ -34,7 +34,7 @@ import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs"
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.0";
+const VERSION = "1.19.1";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -538,6 +538,7 @@ registerTool(
   },
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
     const deadline = desktopTasksEnabled ? desktopOperation.getStore()?.deadline ?? Date.now() + Math.min((timeoutSec ?? 40) * 1000, DESKTOP_TOOL_BUDGET_MS) : undefined;
+    let acceptedDelivery;
     return (desktopTasksEnabled ? desktopTasks : client).withThread(threadId, async () => {
       const notes = [];
       const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
@@ -547,6 +548,7 @@ registerTool(
           const workspace = cwd ? resolveWorkspacePath(cwd) : null;
           if (workspace) security.assertCwd(workspace.path);
           const delivered = await desktopTasks.send({ threadId, prompt, cwd: workspace?.path, model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT, name, deadline });
+          acceptedDelivery = delivered;
           notes.push("sent through Codex Desktop; no external app-server writer", `cwd: ${delivered.cwd}`);
           if (shouldOpen) {
             try {
@@ -617,7 +619,16 @@ registerTool(
       } catch (err) {
         return failure(err);
       }
-    }, { deadline }).catch(failure);
+    }, {
+      deadline,
+      onDeadline(error) {
+        if (!acceptedDelivery) throw error;
+        return {
+          ...textResult(`sent through Codex Desktop; no external app-server writer\ncwd: ${acceptedDelivery.cwd}\nthreadId: ${threadId}\nstatus: timeout\nTask was accepted; the response deadline elapsed before a completed reply was observed. Inspect the existing task; do not resend.`),
+          structuredContent: { threadId, deliveryStatus: "accepted", status: "timeout", responseStatus: "unavailable" },
+        };
+      },
+    }).catch(failure);
   },
 );
 

package/src/native-relay-companion.mjs

@@ -34,7 +34,7 @@ import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.0";
+const VERSION = "1.19.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {

package/src/thread-delivery.mjs

@@ -79,7 +79,7 @@ export class DesktopTaskDelivery {
     }
   }
 
-  async withThread(threadId, operation, { deadline } = {}) {
+  async withThread(threadId, operation, { deadline, onDeadline } = {}) {
     const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
     let expired = false;
     const current = previous.catch(() => {}).then(() => {
@@ -98,6 +98,10 @@ export class DesktopTaskDelivery {
           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()));
       })]);
+    } catch (error) {
+      // Preserve confirmed dispatch state while the underlying operation retains its lock.
+      if (expired && onDeadline) return onDeadline(error);
+      throw error;
     } finally {
       clearTimeout(timer);
     }