@minhspark/codex-mcp-bridge 1.19.0 → 1.19.2

package/CHANGELOG.md

@@ -4,6 +4,24 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.19.2] - 2026-09-29
+
+### Fixed
+
+- Start both bridges from project-local npm installations. When npm hoists the bridge's dependencies into the project's `node_modules`, the package has no `node_modules` of its own, and preparing the immutable runtime failed with `ENOENT` (`scandir …node_modules`) since 1.15.0; only global installs, which keep a nested `node_modules`, started. The runtime now copies the dependency tree Node resolves from the package (hoisted, nested, scoped, aliased, linked and peer dependencies) and nothing else from the project, so it stays isolated from later installation changes. Its revision also covers the project's npm lock, so an `npm install` that changes those dependencies reloads the bridge.
+- Stop the Codex bridge cleanly when its MCP client disconnects. The bridge ends the Windows PowerShell caller checks it started and waits for them to close, and the supervisor gives its worker up to 6 seconds to exit before stopping it. Before, the supervisor stopped the worker after 1 second without waiting, which left those checks running with the bridge's working directory in use. On Windows, deleting that directory right after a test closed its bridge then failed with `EPERM`; the tests no longer retry that deletion.
+
+## [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.2",
   "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.2";
 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.2";
 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,42 @@ import { readClaudeDesktopContext } from "./claude-desktop-context.mjs";
 
 const execute = promisify(execFile);
 const MAX_ANCESTORS = 8;
+const INSPECTION_OUTPUT_LIMIT = 16384;
+const activeInspectors = new Set();
+let inspectorsStopping = false;
+
+export async function stopProcessInspectors() {
+  inspectorsStopping = true;
+  await Promise.all([...activeInspectors].map((inspector) => inspector.stop()));
+}
+
+/**
+ * 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 +113,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 +146,101 @@ 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 } = {}) {
+  if (inspectorsStopping) return Promise.reject(Object.assign(new Error("Process inspection is shutting down"), { code: "ABORT_ERR" }));
+  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;
+    let failure;
+    let killTimer;
+    let closeTimer;
+    let resolveClosed;
+    const closed = new Promise((resolve) => { resolveClosed = resolve; });
+    const inspector = { stop: () => {
+      fail(Object.assign(new Error("Process inspection cancelled during shutdown"), { code: "ABORT_ERR" }));
+      return closed.then((error) => { if (error) throw error; });
+    } };
+    activeInspectors.add(inspector);
+    const text = (stream) => Buffer.concat(output[stream]).toString("utf8");
+    const settle = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      clearTimeout(closeTimer);
+      activeInspectors.delete(inspector);
+      resolveClosed(error?.cleanupFailed ? error : null);
+      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 fail = (error) => {
+      if (settled || failure) return;
+      failure = error;
+      clearTimeout(timer);
+      closeTimer = setTimeout(() => settle(Object.assign(failure, { cleanupFailed: true, message: `${failure.message}; helper ${child.pid} did not close within 5000 ms after termination` })), 5000);
+      if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+        child.kill();
+        killTimer = setTimeout(() => child.kill("SIGKILL"), 250);
+      }
+    };
+    const arm = (phase, ms) => {
+      clearTimeout(timer);
+      timer = setTimeout(() => fail(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 || failure) return;
+        output[stream].push(chunk);
+        size[stream] += chunk.length;
+        if (size[stream] > maxBuffer) return fail(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", fail);
+    child.on("close", (code, signal) => settle(failure ?? (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 +256,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

@@ -29,12 +29,12 @@ import { exitForVersionRequest } from "./cli-version.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
 import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
 import { accountIdentity, assertAccountIdentity, publicAccountState, readBridgeAccounts, requireBridgeAccounts } from "./bridge-account-context.mjs";
-import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSenderContext } from "./claude-sender-context.mjs";
+import { assertClaudeSenderContext, readClaudeSenderContext, requireClaudeSenderContext, stopProcessInspectors } from "./claude-sender-context.mjs";
 import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.19.0";
+const VERSION = "1.19.2";
 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);
   },
 );
 
@@ -1000,5 +1011,13 @@ registerTool(
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+let shutdownPromise;
+const shutdown = () => shutdownPromise ??= (async () => {
+  client?.close();
+  await server.close();
+  await stopProcessInspectors();
+})();
+process.stdin.once("end", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
+process.once("disconnect", () => { void shutdown().catch((error) => log(`shutdown failed: ${error.message}`)); });
 reload.listen();
 log(desktopTasksEnabled ? `ready on ${PLATFORM_LABEL} (Codex Desktop only; external app-server disabled)` : `ready on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);

package/src/mcp-supervisor.mjs

@@ -44,6 +44,7 @@ class Worker {
       env: { ...env, CODEX_BRIDGE_WORKER: "1", CODEX_BRIDGE_STAGED: "1" },
       stdio: ["pipe", "pipe", "pipe", "ipc"], serialization: "json",
     });
+    this.exited = new Promise((resolve) => this.process.once("exit", resolve));
     this.process.stderr.on("data", (data) => process.stderr.write(data));
     this.process.stdin.on("error", (error) => this.fail(error));
     this.process.on("error", (error) => this.fail(error));
@@ -110,13 +111,23 @@ class Worker {
 
   async stop() {
     this.retiring = true;
-    if (this.process.exitCode !== null || this.process.signalCode) return;
-    await new Promise((resolve) => {
-      const timer = setTimeout(() => { this.process.kill(); resolve(); }, 1000);
-      this.process.once("exit", () => { clearTimeout(timer); resolve(); });
+    if (this.stopping) return this.stopping;
+    this.stopping = (async () => {
+      let timer;
+      const wait = async (ms) => {
+        try {
+          return await Promise.race([this.exited.then(() => true), new Promise((resolve) => { timer = setTimeout(() => resolve(false), ms); })]);
+        } finally { clearTimeout(timer); }
+      };
       this.process.stdin.end();
       if (this.process.connected) this.process.disconnect();
-    });
+      if (await wait(6000)) return;
+      if (this.process.exitCode === null && this.process.signalCode === null) {
+        this.process.kill("SIGKILL");
+      }
+      if (!await wait(5000)) throw new Error(`Bridge worker ${this.process.pid} did not close after termination`);
+    })();
+    return this.stopping;
   }
 }
 
@@ -248,13 +259,16 @@ export async function runSupervisor(entry, options = {}) {
       reloads++;
       reason = null;
       if (JSON.stringify(catalog) !== JSON.stringify(oldCatalog)) output({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
-      await previous.stop();
+      await previous.stop().catch((error) => log(`retired ${entry} worker: ${error.message}`));
       workers.delete(previous);
       log(`activated ${entry} revision ${revision.slice(0, 12)}; client connection retained`);
     } catch (error) {
       reason = `Update deferred: ${error.message}`;
       retryAt = Date.now() + Math.max(pollMs, 5000);
-      if (candidate) { await candidate.stop(); workers.delete(candidate); }
+      if (candidate) {
+        await candidate.stop().catch((stopError) => log(`rejected ${entry} candidate: ${stopError.message}`));
+        workers.delete(candidate);
+      }
       if (quiesced && active === previous && !previous.closed) {
         try { await previous.control("resume"); }
         catch (resumeError) { failure = `Previous runtime could not resume: ${resumeError.message}`; }

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

package/src/release-snapshot.mjs

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 
 function digestFiles(root, files) {
   const hash = createHash("sha256");
@@ -49,14 +50,14 @@ function digestMetadata(cache) {
     }
   };
   return {
-    digest(directory, files) {
+    digest(directory, files, sources) {
       const previous = directories.get(directory) ?? load(directory);
       const records = new Map();
       const hash = createHash("sha256");
       if (previous.size !== files.length) dirty.add(directory);
       for (const file of files) {
         if (!safeRelativePath(file)) throw new Error(`Unsafe release file: ${file}`);
-        const fullPath = path.join(directory, file);
+        const fullPath = sources?.get(file) ?? path.join(directory, file);
         const before = fs.statSync(fullPath, { bigint: true });
         if (!before.isFile()) throw new Error(`Unsupported release file: ${file}`);
         const current = signature(before);
@@ -105,25 +106,101 @@ function digestMetadata(cache) {
   };
 }
 
-function inventory(root, prefix = "") {
+function inventory(root, prefix = "", omitModules = false) {
   const files = [];
   for (const entry of fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"))) {
     if (entry.name === ".bin") continue;
+    if (omitModules && !prefix && entry.name === "node_modules") continue;
     const relative = path.join(prefix, entry.name);
     const stat = entry.isSymbolicLink() ? fs.statSync(path.join(root, relative)) : entry;
-    if (stat.isDirectory()) files.push(...inventory(root, relative));
+    if (stat.isDirectory()) files.push(...inventory(root, relative, omitModules));
     else if (stat.isFile()) files.push(relative);
     else throw new Error(`Unsupported release file: ${relative}`);
   }
   return files;
 }
 
+const INSTALLATION_LOCKS = ".bridge-installation-locks.json";
+const dependencySearchPaths = (root, name) => createRequire(path.join(root, "package.json")).resolve.paths(name) ?? [];
+
+function installationLocks(root) {
+  const saved = path.join(root, INSTALLATION_LOCKS);
+  if (fs.existsSync(saved)) return fs.readFileSync(saved, "utf8");
+  const local = path.join(root, "node_modules");
+  const hashes = [];
+  for (const directory of dependencySearchPaths(root, "bridge-dependency-lock")) {
+    if (directory === local) continue;
+    const lock = path.join(directory, ".package-lock.json");
+    if (fs.existsSync(lock)) hashes.push(createHash("sha256").update(fs.readFileSync(lock)).digest("hex"));
+  }
+  return JSON.stringify(hashes);
+}
+
+function dependencyFiles(root) {
+  const files = new Map();
+  if (fs.existsSync(path.join(root, "node_modules"))) {
+    for (const file of inventory(root, "node_modules")) files.set(file, path.join(root, file));
+  }
+  const queue = [{ source: root, destination: "" }];
+  const visited = new Set();
+  const packageSources = new Map();
+  const packageAt = (directory) => {
+    if (packageSources.has(directory)) return packageSources.get(directory);
+    const manifest = files.get(path.join(directory, "package.json"));
+    if (!manifest) return null;
+    const source = fs.realpathSync.native(path.dirname(manifest));
+    packageSources.set(directory, source);
+    return source;
+  };
+  for (let index = 0; index < queue.length; index++) {
+    const { source, destination } = queue[index];
+    if (visited.has(destination)) continue;
+    visited.add(destination);
+    const manifest = JSON.parse(fs.readFileSync(path.join(source, "package.json"), "utf8"));
+    const names = new Set([...Object.keys(manifest.dependencies ?? {}), ...Object.keys(manifest.optionalDependencies ?? {}), ...Object.keys(manifest.peerDependencies ?? {})]);
+    for (const name of [...names].sort()) {
+      if (!/^(?:@[a-zA-Z0-9._~-]+\/)?[a-zA-Z0-9._~-]+$/.test(name) || name === "." || name === "..") throw new Error(`Unsafe dependency name: ${name}`);
+      let resolved;
+      for (const modules of dependencySearchPaths(source, name)) {
+        const candidate = path.join(modules, name);
+        if (fs.existsSync(path.join(candidate, "package.json"))) { resolved = fs.realpathSync.native(candidate); break; }
+      }
+      if (!resolved) {
+        if (Object.hasOwn(manifest.optionalDependencies ?? {}, name) || manifest.peerDependenciesMeta?.[name]?.optional) continue;
+        throw new Error(`Cannot resolve required dependency ${name} from ${source}`);
+      }
+      let placement;
+      let current = destination;
+      while (true) {
+        if (path.basename(current) !== "node_modules") {
+          const candidate = path.join(current, "node_modules", name);
+          const installed = packageAt(candidate);
+          if (installed) { if (installed === resolved) placement = candidate; break; }
+        }
+        if (!current) break;
+        const parent = path.dirname(current);
+        current = parent === "." ? "" : parent;
+      }
+      if (!placement) {
+        const hoisted = path.join("node_modules", name);
+        placement = packageAt(hoisted) ? path.join(destination, "node_modules", name) : hoisted;
+        const occupied = packageAt(placement);
+        if (occupied && occupied !== resolved) throw new Error(`Conflicting dependency resolution for ${name}`);
+        for (const file of inventory(resolved, "", true)) files.set(path.join(placement, file), path.join(resolved, file));
+        packageSources.set(placement, resolved);
+      }
+      queue.push({ source: resolved, destination: placement });
+    }
+  }
+  return new Map([...files].sort(([left], [right]) => left.localeCompare(right, "en")));
+}
+
 export function sourceRevision(root) {
   const files = ["package.json", ...inventory(root, "src")];
   for (const file of ["package-lock.json", "node_modules/.package-lock.json"]) {
     if (fs.existsSync(path.join(root, file))) files.push(file);
   }
-  return digestFiles(root, files);
+  return createHash("sha256").update(digestFiles(root, files)).update(installationLocks(root)).digest("hex");
 }
 
 export function snapshotRoot(env = process.env) {
@@ -153,31 +230,36 @@ export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRe
   if (fs.lstatSync(cache).isSymbolicLink()) throw new Error("The runtime cache cannot be a symbolic link");
   cache = fs.realpathSync.native(cache);
   const metadata = digestMetadata(cache);
-  const dependencies = inventory(root, "node_modules");
-  const dependencyRevision = metadata.digest(root, dependencies);
+  const dependencies = dependencyFiles(root);
+  const dependencyRevision = metadata.digest(root, [...dependencies.keys()], dependencies);
   const key = createHash("sha256").update(expectedRevision).update(dependencyRevision).digest("hex");
   const target = path.join(cache, key);
   const validate = (directory) => {
     if (fs.lstatSync(directory).isSymbolicLink()) throw new Error("The release directory cannot be a symbolic link");
-    return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules")) === dependencyRevision;
+    return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules").sort((left, right) => left.localeCompare(right, "en"))) === dependencyRevision;
   };
   if (fs.existsSync(target)) {
     if (!validate(target)) throw new Error("An existing immutable runtime failed integrity verification");
-    if (sourceRevision(root) !== expectedRevision) throw new Error("The installation changed during snapshot verification");
+    const currentDependencies = dependencyFiles(root);
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision) {
+      throw new Error("The installation changed during snapshot verification");
+    }
     metadata.flush();
     return { directory: target, revision: expectedRevision, key };
   }
   const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
   try {
     fs.mkdirSync(temporary, { mode: 0o700 });
-    const files = ["package.json", ...inventory(root, "src"), ...dependencies];
+    const files = ["package.json", ...inventory(root, "src"), ...dependencies.keys()];
     if (fs.existsSync(path.join(root, "package-lock.json"))) files.push("package-lock.json");
     const directories = new Set(["src", "node_modules", ...files.map((file) => path.dirname(file))]);
     for (const directory of directories) fs.mkdirSync(path.join(temporary, directory), { recursive: true, mode: 0o700 });
     for (const file of files) {
-      fs.copyFileSync(path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
+      fs.copyFileSync(dependencies.get(file) ?? path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
     }
-    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, inventory(root, "node_modules")) !== dependencyRevision || !validate(temporary)) {
+    fs.writeFileSync(path.join(temporary, INSTALLATION_LOCKS), installationLocks(root), { flag: "wx", mode: 0o600 });
+    const currentDependencies = dependencyFiles(root);
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, [...currentDependencies.keys()], currentDependencies) !== dependencyRevision || !validate(temporary)) {
       throw new Error("The installation changed while its immutable runtime was being prepared");
     }
     try {

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);
     }