@minhspark/codex-mcp-bridge 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [1.15.1] - 2026-09-14
+
+### Fixed
+
+- Allow bounded cold startup time for the Windows snapshot identity test on slower CI hosts while preserving the production five-second inspection deadline and the real MCP caller check.
+- Discover the native tools pipe on current Windows Codex Desktop builds that load app tools through a plugin instead of an inline app-server override. Validate the Desktop process ancestry and pipe owner before connecting, so the relay can start without a pinned pipe address.
+- Keep native relay reloads usable when another companion takes over a shared listener during the handoff, while still rejecting a missing endpoint.
+- Migrate legacy Desktop installations explicitly with `install-claude-desktop.mjs --desktop-tasks`, disable external app-server autostart, and leave automatic routing unpinned so a later relay installation can take effect.
+- Reload effective shared routing changes on the existing MCP connection when safely idle. Allow legacy-to-Desktop upgrades while preserving confirmed receipts without replay; reject automatic downgrades to the external app-server. Clarify that open Desktop tasks are valid native destinations.
+- Reuse validated dependency hashes for unchanged files when preparing cached runtimes, avoiding repeated content reads that can delay MCP initialization during Windows startup. Changed source dependencies and modified cached copies still require verification; missing or invalid hash metadata falls back to reading file contents.
+- Log runtime preparation start and elapsed time before the MCP worker launches, so startup delays can be distinguished from worker initialization failures.
+
 ## [1.15.0] - 2026-09-07
 
 ### Added

package/README.md

@@ -32,6 +32,8 @@ Reusing a receipt also verifies that the saved project still has the same identi
 
 The updated companion exposes a separate `-desktop-tasks` endpoint so a previous companion holding the legacy reply socket need not be killed during an upgrade. `codex_bridge_status` verifies the native connection through Desktop's local project list; `native_relay_status` reports both endpoints. Reconnect the companion after upgrading so it accepts the current native operations.
 
+On Windows, the companion supports both legacy inline app-server configuration and current Codex Desktop plugin startup. When no native pipe is inherited, discovery checks the companion's Desktop process ancestry and the named pipe's server process, then uses a read-only project-list probe to distinguish app tools from browser-only pipes. A running companion alone does not establish readiness: verify that `native_relay_status` reports its account relay listening and that `codex_bridge_status` can read Desktop projects.
+
 Desktop mode never contacts, starts, or falls back to an external app-server, including during status checks and thread discovery. The Claude Desktop installer records `CODEX_BRIDGE_AUTOSTART=0` in this mode. If Desktop or its companion is unavailable, the bridge reports the failure and leaves existing tasks in Desktop. `stop_codex_app_server` is a no-op in Desktop mode; stop an obsolete external service through its own launcher after confirming it has no active work.
 
 `list_codex_threads` filters Desktop's recent/pinned task snapshot by authorization, workspace/title, and result limit. The snapshot can omit agent-created tasks visible in the sidebar and does not cover the complete archive. Absence from this list does not mean creation failed: read the returned task ID directly. Desktop does not expose the external server's `loadedOnly` state; requesting it returns an explanation without contacting that server.
@@ -142,12 +144,18 @@ Install the new files with `npm install -g @minhspark/codex-mcp-bridge@latest`.
 
 After this one-time migration, the stable supervisor keeps the client's MCP stdio connection open while it starts each worker from an immutable source snapshot. The installers prepare this snapshot before changing the registration, avoiding a slow first copy during MCP initialization. Compatible installed-source changes become candidates after the tree stabilizes. A candidate must initialize successfully before it can replace an idle worker. Active calls, pending deliveries, late replies, and relay work defer the switch; an update never silently resends a prompt. A failed candidate leaves the existing worker and its delivery state available.
 
+Snapshot verification reuses previously calculated dependency hashes when file identity, size, modification time, and change time still match. Changed files are read and hashed again; directory inventories still detect additions and deletions. Missing or invalid hash metadata falls back to reading file contents. This reduces repeated disk reads during simultaneous MCP startup, especially just after Windows boots. Supervisor stderr logs show when runtime preparation starts and how long it takes.
+
 Call `codex_bridge_status`, `claude_bridge_status`, or `native_relay_status` from the actual app task to inspect `autoReload`, the loaded version, and any pending update or blocker. Reading an old message receipt still refers to the worker that accepted that message. Pending or uncertain messages can keep an update deferred until they are resolved; a new process or an unknown message ID is never evidence that a send failed. If the supervisor protocol itself changes incompatibly, reconnect that MCP server once again.
 
 Auto-reload watches the **installed source at the configured path**. It does not poll npm, download a release, run `git pull`, or upgrade Claude/Codex themselves. Keep the normal package update mechanism to install new versions. Changes to environment variables or access settings supplied by the MCP client require a client MCP reload to pass the new configuration to the supervisor. Subsequent account switches remain detectable per call without this configuration reload.
 
 The installers preserve existing environment and access settings; explicit supported environment variables override their stored values. Claude's `--reset` explicitly returns to defaults. Codex entries with custom access, timeout, or transport settings are left intact with the exact command and arguments to update in place. `CLAUDE_DESKTOP_USER_DATA` pins only the data directory, never an account identity. Re-running an installer is unnecessary for later compatible source updates. The global install path remains stable across package versions.
 
+To migrate a legacy Claude registration to native Desktop task delivery, run `codex-mcp-bridge-install --desktop-tasks` (from a checkout: `node scripts/install-claude-desktop.mjs --desktop-tasks`). This explicit flag overrides a stored or inherited `CODEX_BRIDGE_DESKTOP_TASKS=0` and disables external app-server autostart while preserving access settings. Without the flag or an explicit routing setting, the installer leaves routing automatic so a later native relay installation can enable Desktop tasks. Existing explicit `0` settings remain unchanged until the flag or an environment override is supplied.
+
+Reconnect `codex-bridge` in the existing Claude task after changing its registration; source auto-reload cannot replace environment variables inherited by a running MCP process. If the task has a separate Claude Code MCP registration, update that registration too. Verify `codex_bridge_status` from the actual sending task reports Desktop tasks enabled, the native relay available, and a current runtime. Keep the destination open in Codex Desktop. An earlier unconfirmed send must be inspected before sending again.
+
 #### Show the final npm installation result
 
 Enable the optional shell integration once after installing the package:
@@ -510,7 +518,9 @@ Claude
 
 Resolution order is `CODEX_RELAY_ID` → that file → an error naming both. Never a guess: an invented executor fails inside Codex with a message that says nothing about the configuration that actually caused it. The recorded thread works as an executor even if it has never been opened in the app.
 
-**It is a backend, not a replacement.** `claude-bridge` picks between two delivery backends and reports which one it used; the tools, the peer protocol, the routing, the rate limits and `CodexAppServerClient` are untouched. The native path is used only when all of these hold — otherwise the app-server path runs exactly as it did before:
+**Desktop-only delivery.** With Desktop tasks enabled, both `send_to_codex_thread` and correlated Claude replies use the native relay. Desktop keeps its writer lock throughout delivery. If the relay is unavailable, the bridge reports that failure and does not start or use an external app-server.
+
+**Legacy reply delivery.** When Desktop tasks are explicitly disabled, `claude-bridge` can choose between native and external app-server delivery. The native path requires:
 
 | Condition | Otherwise |
 |---|---|
@@ -518,7 +528,7 @@ Resolution order is `CODEX_RELAY_ID` → that file → an error naming both. Nev
 | `CODEX_BRIDGE_NATIVE_RELAY` is not `0` | switched off by hand |
 | the Windows named pipe or macOS unix socket exists | the companion is not installed, or Codex Desktop is not running |
 
-A companion that cannot be reached before sending falls back to the app-server path. Once a request has been written, a refusal, timeout, or lost acknowledgement does not trigger another delivery: the first attempt may already have succeeded. Invalid or oversized messages are also refused rather than passed to another backend.
+Only legacy reply delivery falls back to the app-server path when a companion cannot be reached before sending. Once a request has been written, a refusal, timeout, or lost acknowledgement does not trigger another delivery: the first attempt may already have succeeded. Invalid or oversized messages are also refused rather than passed to another backend.
 
 The companion uses `CODEX_APP_TOOLS_PIPE_PATH` when inherited. Desktop builds that supply it only to their bundled `codex_app` MCP are also supported: the companion reads the exact `mcp_servers.codex_app.env` override from its launching app-server. It never picks a pipe from another session or saves a restart-specific address. The native connection remains separate from MCP stdio. If neither source provides a valid pipe, the relay stays unavailable; if a configured pipe is late during startup, it retries in the background. When several MCP instances start, status identifies a reachable shared companion instead of reporting that the relay is down.
 
@@ -537,11 +547,11 @@ The native pipe uses a 4-byte UInt32LE payload length followed by UTF-8 JSON-RPC
 
 ### Caveats
 
-- The Codex desktop app runs its own app-server over stdio (`ChatGPT.app/Contents/Resources/codex … app-server`, **no** `--listen`), so nothing external can attach to it. `~/.codex/ipc/ipc.sock` is the Electron app's internal IPC, not an app-server. Threads opened there can still be driven through the bridge, but by resuming from the rollout `.jsonl` rather than attaching live. The [native relay](#codex-desktop-native-relay) is not an exception to this: the companion never attaches to that app-server, it is *launched by* it as one of the app's own MCP servers.
-- **A thread currently open in the desktop app cannot be written to** through a second app-server — Codex holds a per-thread writer lock (`~/.codex/thread-writer-locks/`) and returns `thread <id> already has an active writer`. That error is the guard working, not data loss. Check `status` with `list_codex_threads` first and only send when it is `idle` or `notLoaded` and not open in the app. For the Claude → Codex relay specifically, the [native relay](#codex-desktop-native-relay) removes the second writer instead of waiting for the lock.
-- **Bridge-created threads are named before they are opened.** The bridge calls the app-server's `thread/name/set` with the requested title, or derives `[project] first line of prompt`, then opens the exact `codex://threads/<id>` link. This gives Codex Desktop a visible session title and preserves the precise `cwd` in the thread metadata.
+- Codex Desktop runs its own app-server. Its internal IPC endpoint is not an external app-server connection. The [native relay](#codex-desktop-native-relay), launched in Desktop's context, invokes Desktop's own tools to deliver into an existing task without resuming it through another server.
+- **The writer-lock limitation applies to the legacy external app-server path.** A second writer receives `thread <id> already has an active writer`; an `idle` task can still be owned by Desktop. Native Desktop delivery supports tasks open in the app. Check `codex_bridge_status` in the actual sending task and migrate a legacy registration with `--desktop-tasks`; do not delete lock files, stop Desktop, or ask for manual copying merely because Desktop owns the task.
+- **New Desktop tasks receive their saved project and title through Desktop's native creation tool.** Legacy bridge-created threads instead use the app-server's `thread/name/set` and an exact `codex://threads/<id>` link. Both paths preserve the requested workspace.
 - A repo living on the NTFS partition of a dual-boot machine (`/Volumes/<label>/...`) is **read-only** under macOS. Keep a separate checkout on an APFS volume to run and edit it.
-- `codex app-server daemon start` uses the `unix://` transport with a control socket at `~/.codex/app-server-control/app-server-control.sock`. The bridge does **not** use that path (different framing, no public API) — it always talks over `ws://`.
+- `codex app-server daemon start` uses the `unix://` transport with a control socket at `~/.codex/app-server-control/app-server-control.sock`. The legacy external bridge uses `ws://` instead; Desktop-only delivery uses the native relay.
 
 ## Troubleshooting
 

package/package.json

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

@@ -2,9 +2,12 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { desktopTasksConfigured } from "../src/native-relay.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const bridgeEnvNames = [
+  "CODEX_HOME",
+  "CLAUDE_DESKTOP_USER_DATA",
   "CODEX_APP_SERVER_URL",
   "CODEX_BIN",
   "CODEX_BRIDGE_ALLOWED_ROOTS",
@@ -40,7 +43,9 @@ try {
   await client.connect(transport);
   const tools = await client.listTools();
   console.log("tools:", tools.tools.map((t) => t.name).join(", "));
-  const listed = await client.callTool({ name: "list_codex_threads", arguments: { limit: 3 } });
+  const listed = await client.callTool(desktopTasksConfigured()
+    ? { name: "codex_bridge_status", arguments: {} }
+    : { name: "list_codex_threads", arguments: { limit: 3 } });
   console.log(listed.content[0].text.slice(0, 600));
   if (listed.isError) process.exitCode = 1;
 } catch (err) {

package/scripts/install-claude-desktop.mjs

@@ -13,6 +13,7 @@ exitForVersionRequest(import.meta.url);
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
 const reset = process.argv.includes("--reset");
+const forceDesktopTasks = process.argv.includes("--desktop-tasks");
 
 /**
  * This bridge is intentionally the local hand-off point between Claude and
@@ -55,10 +56,13 @@ cfg.mcpServers = cfg.mcpServers ?? {};
 const previousEntry = (reset ? {} : cfg.mcpServers["codex-bridge"]) ?? {};
 const previousEnv = previousEntry.env ?? {};
 const settled = (name, fallback) => process.env[name] ?? previousEnv[name] ?? fallback;
-const desktopMode = settled("CODEX_BRIDGE_DESKTOP_TASKS", desktopTasksConfigured() ? "1" : "0");
+const desktopMode = forceDesktopTasks ? "1" : settled("CODEX_BRIDGE_DESKTOP_TASKS");
+const desktopEnabled = desktopMode === undefined ? desktopTasksConfigured() : desktopMode === "1";
 
 const kept = Object.keys(previousEnv).filter(
-  (name) => process.env[name] === undefined && name !== "CODEX_BIN",
+  (name) => process.env[name] === undefined && name !== "CODEX_BIN" &&
+    !(forceDesktopTasks && name === "CODEX_BRIDGE_DESKTOP_TASKS") &&
+    !(desktopEnabled && name === "CODEX_BRIDGE_AUTOSTART"),
 );
 
 cfg.mcpServers["codex-bridge"] = {
@@ -93,8 +97,8 @@ cfg.mcpServers["codex-bridge"] = {
     CODEX_BRIDGE_SANDBOX: settled("CODEX_BRIDGE_SANDBOX", "workspace-write"),
     CODEX_BRIDGE_OPEN_IN_APP: settled("CODEX_BRIDGE_OPEN_IN_APP", IS_WINDOWS ? "1" : "0"),
     CODEX_BRIDGE_RELEASE_AFTER_TURN: settled("CODEX_BRIDGE_RELEASE_AFTER_TURN", IS_WINDOWS ? "1" : "0"),
-    CODEX_BRIDGE_DESKTOP_TASKS: desktopMode,
-    CODEX_BRIDGE_AUTOSTART: desktopMode === "1" ? "0" : settled("CODEX_BRIDGE_AUTOSTART", "1"),
+    ...(desktopMode !== undefined ? { CODEX_BRIDGE_DESKTOP_TASKS: desktopMode } : {}),
+    CODEX_BRIDGE_AUTOSTART: desktopEnabled ? "0" : settled("CODEX_BRIDGE_AUTOSTART", "1"),
     ...(process.env.CODEX_BRIDGE_ALLOWED_THREADS !== undefined
       ? { CODEX_BRIDGE_ALLOWED_THREADS: process.env.CODEX_BRIDGE_ALLOWED_THREADS }
       : {}),
@@ -120,6 +124,7 @@ fs.writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`updated ${cfgPath}`);
 console.log(JSON.stringify(cfg.mcpServers["codex-bridge"], null, 2));
+console.log(`Desktop tasks: ${desktopEnabled ? "enabled" : "disabled"} (${desktopMode === undefined ? "automatic relay configuration" : forceDesktopTasks ? "--desktop-tasks" : "explicit environment setting"}).`);
 
 if (reset) {
   console.log("\n--reset: existing values were discarded in favour of the defaults.");
@@ -149,3 +154,4 @@ if (cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_THREAD_POLICY === "owned") {
 
 console.log("\nReconnect codex-bridge once in the existing Claude task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle.");
 console.log("Verify codex_bridge_status from that task: autoReload must be enabled and runtime state must be current. A separate diagnostic process does not verify the app's loaded MCP process.");
+if (desktopEnabled) console.log("Verify Desktop tasks are enabled and the native relay is available. Configuration changes require MCP reconnect even when source auto-reload is enabled; keep the destination task open in Codex Desktop.");

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.15.0";
+const VERSION = "1.15.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

@@ -15,14 +15,14 @@ import { readClaudeInboundPolicy } from "./claude-inbound-policy.mjs";
 import { assertRecipientClass, preflightFailure } from "./recipient-preflight.mjs";
 import { readCodexSenderContext } from "./codex-sender-context.mjs";
 import { ReplyForwarder } from "./reply-forwarder.mjs";
-import { clientReloadReason, createReloadControl } from "./reload-control.mjs";
+import { assertRoutingReload, clientReloadReason, createReloadControl } from "./reload-control.mjs";
 import { readClaudeAccountContext } from "./desktop-account-context.mjs";
 import { assertAccountIdentity, bindUnsolicitedClaudeMessageAccount, publicAccountState, readBridgeAccounts, requireBridgeAccounts, sameAccountIdentity } from "./bridge-account-context.mjs";
 import { resolveClaudeDesktopSession } from "./claude-session-router.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.0";
+const VERSION = "1.15.1";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 
@@ -74,7 +74,8 @@ const reload = createReloadControl({
   quiesce: async () => { await peer.quiesce(); codex.close(); },
   exportState: () => ({ desktopOnly, peer: peer.exportReloadState(), forwarding: replyForwarder.exportReloadState(), threadId: forwarding.threadId }),
   restore: (state) => {
-    if (state.desktopOnly !== desktopOnly || state.threadId !== null && (typeof state.threadId !== "string" || !state.threadId.trim())) {
+    assertRoutingReload(state.desktopOnly, desktopOnly);
+    if (state.threadId !== null && (typeof state.threadId !== "string" || !state.threadId.trim())) {
       throw new Error("Invalid or incompatible Claude worker reload state");
     }
     peer.restoreReloadState(state.peer);

package/src/index.mjs

@@ -27,13 +27,13 @@ import { DesktopTaskDelivery, DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.m
 import { desktopTasksConfigured } from "./native-relay.mjs";
 import { exitForVersionRequest } from "./cli-version.mjs";
 import { createRuntimeState } from "./runtime-state.mjs";
-import { clientReloadReason, createReloadControl } from "./reload-control.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";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.0";
+const VERSION = "1.15.1";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -101,7 +101,8 @@ const reload = createReloadControl({
   quiesce: () => { client?.close(); },
   exportState: () => ({ desktopTasksEnabled, ownedThreadIds: [...security.ownedThreadIds] }),
   restore: (state) => {
-    if (state.desktopTasksEnabled !== desktopTasksEnabled || !Array.isArray(state.ownedThreadIds)
+    assertRoutingReload(state.desktopTasksEnabled, desktopTasksEnabled);
+    if (!Array.isArray(state.ownedThreadIds)
       || state.ownedThreadIds.some((id) => typeof id !== "string" || !id.trim())
       || new Set(state.ownedThreadIds).size !== state.ownedThreadIds.length) throw new Error("Invalid or incompatible Codex worker reload state");
     security.ownedThreadIds = new Set(state.ownedThreadIds);
@@ -480,7 +481,10 @@ registerTool(
     title: "Send a prompt to a Codex thread",
     description:
       "Send a prompt as a new user turn inside an existing Codex thread and wait for Codex to answer. " +
-      "The thread keeps its full history, cwd and model. Use list_codex_threads first if you do not know the threadId.",
+      "The thread keeps its full history, cwd and model. Use list_codex_threads first if you do not know the threadId. " +
+      "Desktop-owned tasks must use Desktop native delivery; an open task is a valid destination. " +
+      "If legacy delivery reports an active writer, inspect codex_bridge_status and repair the native relay/configuration. " +
+      "Do not close the task, create a replacement, or ask the user to copy the message manually.",
     inputSchema: {
       threadId: z.string().describe("Codex thread id (UUID) - get it from list_codex_threads"),
       prompt: z.string().describe("The message to send to Codex, exactly as a user would type it"),

package/src/mcp-supervisor.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createReleaseSnapshot, sourceRevision } from "./release-snapshot.mjs";
+import { desktopTasksConfigured } from "./native-relay.mjs";
 
 const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
@@ -129,6 +130,7 @@ export async function runSupervisor(entry, options = {}) {
   const log = (message) => process.stderr.write(`[bridge-supervisor] ${message}\n`);
   const output = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
   const env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: root };
+  const routingConfiguration = () => entry === "native-relay-companion.mjs" ? null : desktopTasksConfigured(env);
   if (entry === "native-relay-companion.mjs" && !env.CODEX_APP_TOOLS_PIPE_PATH) {
     const { resolveNativeToolsPipePath } = await import("./native-relay.mjs");
     const pipe = await resolveNativeToolsPipePath();
@@ -145,6 +147,7 @@ export async function runSupervisor(entry, options = {}) {
   let failure = null;
   let sequence = 0;
   let observed = null;
+  let observedRouting = null;
   let observedAt = 0;
   let retryAt = 0;
   let reason = null;
@@ -154,7 +157,9 @@ export async function runSupervisor(entry, options = {}) {
   const reverse = new Map();
   const workers = new Set();
   const diagnostics = () => ({ enabled: true, supervisorPid: process.pid, workerPid: active?.process.pid ?? null,
-    revision: active?.release.revision ?? null, availableRevision: observed, pending: Boolean(observed && observed !== active?.release.revision),
+    revision: active?.release.revision ?? null, availableRevision: observed,
+    routingConfiguration: active?.routingConfiguration ?? null, availableRoutingConfiguration: observedRouting,
+    pending: Boolean(observed && (observed !== active?.release.revision || observedRouting !== active?.routingConfiguration)),
     state: failure ? "failed" : switching ? "reloading" : reason ? "deferred" : "current", reason: failure ?? reason, reloads });
 
   const handlers = {
@@ -197,19 +202,21 @@ export async function runSupervisor(entry, options = {}) {
       if (worker === active && !worker.retiring && !stopping) { failure = `${error.message}; automatic replay is disabled because delivery state may be unknown`; log(failure); }
     },
   };
-  const spawn = (release) => {
+  const spawn = (release, routing) => {
     if (stopping) throw new Error("The MCP client disconnected before activation");
     const worker = new Worker(release, entry, env, handlers);
+    worker.routingConfiguration = routing;
     workers.add(worker);
     return worker;
   };
   const check = async () => {
     if (switching || !ready || stopping || failure) return;
     let revision;
-    try { revision = sourceRevision(root); }
+    let routing;
+    try { revision = sourceRevision(root); routing = routingConfiguration(); }
     catch (error) { reason = `Installation is not ready: ${error.message}`; return; }
-    if (observed !== revision) { observed = revision; observedAt = Date.now(); retryAt = 0; }
-    if (revision === active.release.revision) { reason = null; return; }
+    if (observed !== revision || observedRouting !== routing) { observed = revision; observedRouting = routing; observedAt = Date.now(); retryAt = 0; }
+    if (revision === active.release.revision && routing === active.routingConfiguration) { reason = null; return; }
     if (Date.now() - observedAt < settleMs || Date.now() < retryAt) { reason ??= "Waiting for a complete, stable installation"; return; }
     if (active.clientPending.size || reverse.size) { reason = "A request is still running; its worker is retained"; return; }
     switching = true;
@@ -220,7 +227,7 @@ export async function runSupervisor(entry, options = {}) {
       const state = await previous.control("inspect");
       if (!state.reloadable) { reason = state.reason ?? "Pending deliveries prevent a safe reload"; return; }
       const release = createReleaseSnapshot(root, { expectedRevision: revision });
-      candidate = spawn(release);
+      candidate = spawn(release, routing);
       const initialized = await candidate.rpc("initialize", initializeParams);
       if (initialized.protocolVersion !== initializeResult.protocolVersion || JSON.stringify(initialized.capabilities) !== JSON.stringify(initializeResult.capabilities)) {
         throw new Error("The new MCP protocol or capabilities require an explicit client reconnect");
@@ -230,6 +237,7 @@ export async function runSupervisor(entry, options = {}) {
       if (!Array.isArray(catalog.tools) || !catalog.tools.length || catalog.nextCursor) throw new Error("The candidate tool catalog is incomplete");
       const oldCatalog = await previous.rpc("tools/list", {});
       if (sourceRevision(root) !== revision) throw new Error("The installation changed before activation");
+      if (routingConfiguration() !== routing) throw new Error("The routing configuration changed before activation");
       quiesced = true;
       const exported = await previous.control("quiesce");
       await candidate.control("restore", exported.state);
@@ -296,9 +304,13 @@ export async function runSupervisor(entry, options = {}) {
     await Promise.allSettled([...workers].map((worker) => worker.stop()));
     process.stdin.pause();
   };
+  const preparationStarted = performance.now();
+  log(`preparing ${entry} runtime`);
   const initial = createReleaseSnapshot(root);
+  log(`prepared ${entry} runtime in ${Math.round(performance.now() - preparationStarted)} ms`);
   observed = initial.revision;
-  active = spawn(initial);
+  observedRouting = routingConfiguration();
+  active = spawn(initial, observedRouting);
   const timer = setInterval(() => { void check(); }, pollMs);
   lines(process.stdin, (message) => {
     if (!message || message.jsonrpc !== "2.0" || (!message.method && !hasId(message))) throw new Error("Invalid client JSON-RPC message");

package/src/native-relay-companion.mjs

@@ -30,7 +30,7 @@ import { createRuntimeState } from "./runtime-state.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.15.0";
+const VERSION = "1.15.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {
@@ -369,9 +369,10 @@ export function startRelayWhenAvailable({ nativeTools, relay, log: logFn = () =>
   let resolveReady;
   const ready = new Promise((resolve) => { resolveReady = resolve; });
   let pendingAttempt = null;
+  let nativeConnected = false;
   const attempt = async () => {
     if (stopped) return;
-    let nativeConnected = false;
+    nativeConnected = false;
     try {
       await nativeTools.connect();
       nativeConnected = true;
@@ -413,6 +414,7 @@ export function startRelayWhenAvailable({ nativeTools, relay, log: logFn = () =>
   return {
     ready,
     firstAttempt,
+    get connected() { return nativeConnected; },
     get busy() { return pendingAttempt !== null; },
     stop() {
       if (stopped) return pendingAttempt ?? Promise.resolve();
@@ -454,7 +456,9 @@ export function createNativeRelayLifecycle({ nativeTools, relays, log: logFn = (
     for (const relay of servers) relay.accepting = true;
     startups = servers.map((relay) => startRelayWhenAvailable({ nativeTools, relay, log: logFn }));
     await Promise.all(startups.map((startup) => startup.firstAttempt));
-    if (servers.some((relay) => ownedSockets.includes(relay.socketPath) && !relay.started)) {
+    const restoredListeners = await Promise.all(servers.map(async (relay, index) =>
+      !ownedSockets.includes(relay.socketPath) || startups[index].connected && await relay.isListening()));
+    if (restoredListeners.some((available) => !available)) {
       await stop();
       throw new Error("The replacement native relay could not reclaim its listening sockets");
     }

package/src/native-relay.mjs

@@ -418,18 +418,130 @@ async function readParentCommandLine(parentPid, platform) {
   return stdout.trim();
 }
 
+export function nativeToolsPipeCandidatesFromWindowsSnapshot(snapshot, { parentPid, localAppData = process.env.LOCALAPPDATA } = {}) {
+  if (!Number.isSafeInteger(parentPid) || parentPid <= 0 || !Array.isArray(snapshot?.ancestors)
+      || snapshot.ancestors.length < 2 || snapshot.ancestors.length > 4 || !Array.isArray(snapshot.pipes)) return null;
+  const ancestors = snapshot.ancestors;
+  let expectedPid = parentPid;
+  const visited = new Set();
+  for (const ancestor of ancestors) {
+    if (!Number.isSafeInteger(ancestor?.pid) || ancestor.pid !== expectedPid || visited.has(ancestor.pid)
+        || typeof ancestor.executablePath !== "string" || /[\r\n\0]/.test(ancestor.executablePath)) return null;
+    visited.add(ancestor.pid);
+    expectedPid = ancestor.parentPid;
+  }
+  const desktop = ancestors.at(-1);
+  const appServer = ancestors.at(-2);
+  const desktopPath = path.win32.normalize(desktop.executablePath);
+  if (!/^[a-z]:\\Program Files\\WindowsApps\\OpenAI\.Codex_[0-9.]+_(?:x64|arm64)__2p2nqsd0c76g0\\app\\ChatGPT\.exe$/i.test(desktopPath)) return null;
+  if (ancestors.slice(0, -2).some((ancestor) => path.win32.basename(ancestor.executablePath).toLowerCase() !== "node.exe")) return null;
+  const serverPath = path.win32.normalize(appServer.executablePath);
+  const bundledServer = path.win32.join(path.win32.dirname(desktopPath), "resources", "codex.exe");
+  const downloadedRoot = localAppData ? path.win32.join(localAppData, "OpenAI", "Codex", "bin") : null;
+  const downloadedRelative = downloadedRoot ? path.win32.relative(downloadedRoot, serverPath) : "";
+  if (serverPath.toLowerCase() !== bundledServer.toLowerCase() && !/^[a-f0-9]{8,64}\\codex\.exe$/i.test(downloadedRelative)) return null;
+  if (typeof appServer.commandLine !== "string" || /[\r\n\0]/.test(appServer.commandLine)) return null;
+  const args = splitDesktopCommandLine(appServer.commandLine, "win32");
+  if (!args.length || path.win32.normalize(args[0]).toLowerCase() !== serverPath.toLowerCase()) return null;
+  let command = null;
+  for (let index = 1; index < args.length; index++) {
+    if (args[index] === "-c" || args[index] === "--config") index++;
+    else if (!args[index].startsWith("-")) { command = args[index]; break; }
+  }
+  if (command !== "app-server") return null;
+  const candidates = snapshot.pipes.filter((pipe) => pipe?.serverPid === desktop.pid
+    && typeof pipe.path === "string" && /^\\\\\.\\pipe\\codex-browser-use-[a-z0-9-]+$/i.test(pipe.path));
+  const paths = [...new Set(candidates.map((pipe) => pipe.path))].sort();
+  return paths;
+}
+
+async function readWindowsNativePipeSnapshot(parentPid) {
+  if (!Number.isSafeInteger(parentPid) || parentPid <= 0) return null;
+  const powershell = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const script = String.raw`
+$ErrorActionPreference = 'Stop'
+$ancestors = @()
+$nextProcessId = ${parentPid}
+for ($depth = 0; $depth -lt 4; $depth++) {
+  $ancestor = Get-CimInstance Win32_Process -Filter "ProcessId=$nextProcessId"
+  if (!$ancestor) { break }
+  $ancestors += @{ pid = [int]$ancestor.ProcessId; parentPid = [int]$ancestor.ParentProcessId; executablePath = $ancestor.ExecutablePath; commandLine = $ancestor.CommandLine }
+  if ($ancestor.Name -ieq 'ChatGPT.exe') { break }
+  if ($ancestor.Name -ine 'node.exe' -and $ancestor.Name -ine 'codex.exe') { break }
+  $nextProcessId = [int]$ancestor.ParentProcessId
+}
+$pipes = @()
+if ($ancestors.Count -ge 2 -and $ancestor.Name -ieq 'ChatGPT.exe') {
+  Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
+public static class CodexNativePipeOwner {
+  [DllImport("kernel32.dll", SetLastError = true)]
+  public static extern bool GetNamedPipeServerProcessId(SafePipeHandle pipe, out uint serverProcessId);
+}
+'@
+  $names = @([System.IO.Directory]::GetFiles('\\.\pipe\') | Where-Object { $_ -match '^\\\\\.\\pipe\\codex-browser-use-[a-zA-Z0-9-]+$' } | Sort-Object | Select-Object -First 128)
+  foreach ($pipePath in $names) {
+      $client = $null
+      try {
+        $client = [System.IO.Pipes.NamedPipeClientStream]::new('.', $pipePath.Substring(9), [System.IO.Pipes.PipeDirection]::InOut, [System.IO.Pipes.PipeOptions]::Asynchronous)
+        $client.Connect(30)
+        $serverProcessId = [uint32]0
+        if ([CodexNativePipeOwner]::GetNamedPipeServerProcessId($client.SafePipeHandle, [ref]$serverProcessId) -and $serverProcessId -eq $ancestor.ProcessId) {
+          $pipes += @{ path = $pipePath; serverPid = [int]$serverProcessId }
+        }
+      } catch {} finally { if ($client) { $client.Dispose() } }
+  }
+}
+@{ ancestors = @($ancestors); pipes = @($pipes) } | ConvertTo-Json -Depth 4 -Compress
+`;
+  const { stdout } = await execFileAsync(powershell, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script], {
+    timeout: 5000, maxBuffer: 128 * 1024, windowsHide: true,
+  });
+  return stdout.trim() ? JSON.parse(stdout.trim()) : null;
+}
+
+async function probeWindowsNativeToolsPipe(socketPath, { env, timeoutMs }) {
+  const executorThreadId = resolveRelayThreadId(env).threadId;
+  const client = new NativeToolsClient({ env, socketPath, timeoutMs });
+  const timer = globalThis.setTimeout(() => client.close(), timeoutMs);
+  try {
+    const nativeResult = await client.dispatchDesktop({ executorThreadId, operation: "list_projects", arguments: {} });
+    return Array.isArray(decodeNativeToolResult(nativeResult)?.projects);
+  } finally {
+    globalThis.clearTimeout(timer);
+    client.close();
+  }
+}
+
 export async function resolveNativeToolsPipePath({
   env = process.env,
   parentPid = process.ppid,
   platform = process.platform,
   readParentCommandLine: readParent = readParentCommandLine,
+  readWindowsSnapshot = readWindowsNativePipeSnapshot,
+  probeWindowsPipe = probeWindowsNativeToolsPipe,
+  windowsDiscoveryTimeoutMs = 7000,
 } = {}) {
   if (env.CODEX_APP_TOOLS_PIPE_PATH) return env.CODEX_APP_TOOLS_PIPE_PATH;
   try {
-    return nativeToolsPipeFromCommandLine(await readParent(parentPid, platform), { platform });
-  } catch {
+    const inherited = nativeToolsPipeFromCommandLine(await readParent(parentPid, platform), { platform });
+    if (inherited) return inherited;
+  } catch {}
+  if (platform !== "win32") return null;
+  const deadline = Date.now() + Math.max(1, Math.min(7000, Number(windowsDiscoveryTimeoutMs) || 7000));
+  try {
+    const candidates = nativeToolsPipeCandidatesFromWindowsSnapshot(await readWindowsSnapshot(parentPid), { parentPid, localAppData: env.LOCALAPPDATA }) ?? [];
+    for (const candidate of candidates) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      try {
+        if (await probeWindowsPipe(candidate, { env, timeoutMs: Math.min(750, remaining) })) return candidate;
+      } catch {}
+    }
     return null;
-  }
+  } catch { return null; }
 }
 
 export class NativeToolsClient {

package/src/release-snapshot.mjs

@@ -9,6 +9,102 @@ function digestFiles(root, files) {
   return hash.digest("hex");
 }
 
+const DIGEST_FIELDS = ["dev", "ino", "size", "mtimeNs", "ctimeNs"];
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+
+function safeRelativePath(file) {
+  return typeof file === "string" && file.length > 0 && !file.includes("\0")
+    && !path.posix.isAbsolute(file) && !path.win32.parse(file).root
+    && path.normalize(file) === file && !file.split(/[\\/]/).some((part) => !part || part === "." || part === "..");
+}
+
+function digestMetadata(cache) {
+  const directories = new Map();
+  const dirty = new Set();
+  const metadataPath = (directory) => path.join(cache, `.digests-${createHash("sha256").update(directory).digest("hex")}.json`);
+  const signature = (stat) => Object.fromEntries(DIGEST_FIELDS.map((field) => [field, String(stat[field])]));
+  const matches = (left, right) => left && DIGEST_FIELDS.every((field) => left[field] === right[field]);
+  const load = (directory) => {
+    dirty.add(directory);
+    let descriptor;
+    try {
+      const file = metadataPath(directory);
+      const info = fs.lstatSync(file, { bigint: true });
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1n || info.size > 32n * 1024n * 1024n) return new Map();
+      descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+      const opened = fs.fstatSync(descriptor, { bigint: true });
+      if (!opened.isFile() || opened.nlink !== 1n || !matches(signature(info), signature(opened))) return new Map();
+      const metadata = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      if (metadata?.schema !== 1 || metadata.directory !== directory || !metadata.files || typeof metadata.files !== "object" || Array.isArray(metadata.files)) return new Map();
+      const entries = Object.entries(metadata.files);
+      if (entries.some(([file, record]) => !safeRelativePath(file) || !record || typeof record !== "object" || Array.isArray(record)
+        || typeof record.hash !== "string" || !DIGEST_PATTERN.test(record.hash)
+        || DIGEST_FIELDS.some((field) => typeof record[field] !== "string" || !/^-?\d+$/.test(record[field])))) return new Map();
+      dirty.delete(directory);
+      return new Map(entries);
+    } catch {
+      return new Map();
+    } finally {
+      if (descriptor !== undefined) fs.closeSync(descriptor);
+    }
+  };
+  return {
+    digest(directory, files) {
+      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 before = fs.statSync(fullPath, { bigint: true });
+        if (!before.isFile()) throw new Error(`Unsupported release file: ${file}`);
+        const current = signature(before);
+        let record = previous.get(file);
+        if (!matches(record, current)) {
+          dirty.add(directory);
+          const contentHash = createHash("sha256").update(fs.readFileSync(fullPath)).digest("hex");
+          const after = fs.statSync(fullPath, { bigint: true });
+          if (!after.isFile() || !matches(current, signature(after))) throw new Error("A release file changed during integrity verification");
+          record = { ...current, hash: contentHash };
+        }
+        records.set(file, record);
+        hash.update(file).update("\0").update(record.hash).update("\0");
+      }
+      directories.set(directory, records);
+      return hash.digest("hex");
+    },
+    relocate(from, to) {
+      if (directories.has(from)) {
+        directories.set(to, directories.get(from));
+        dirty.add(to);
+      }
+      directories.delete(from);
+      dirty.delete(from);
+    },
+    forget(directory) { directories.delete(directory); dirty.delete(directory); },
+    flush() {
+      for (const [directory, records] of directories) {
+        if (!dirty.has(directory)) continue;
+        const file = metadataPath(directory);
+        const temporary = path.join(cache, `.digests-${process.pid}-${randomUUID()}.tmp`);
+        try {
+          try {
+            const info = fs.lstatSync(file);
+            if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) continue;
+          } catch (error) { if (error.code !== "ENOENT") continue; }
+          fs.writeFileSync(temporary, JSON.stringify({ schema: 1, directory, files: Object.fromEntries(records) }), { flag: "wx", mode: 0o600 });
+          fs.renameSync(temporary, file);
+          dirty.delete(directory);
+        } catch {
+        } finally {
+          try { fs.rmSync(temporary, { force: true }); } catch {}
+        }
+      }
+    },
+  };
+}
+
 function inventory(root, prefix = "") {
   const files = [];
   for (const entry of fs.readdirSync(path.join(root, prefix), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"))) {
@@ -56,17 +152,19 @@ export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRe
   fs.mkdirSync(cache, { recursive: true, mode: 0o700 });
   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 = digestFiles(root, dependencies);
+  const dependencyRevision = metadata.digest(root, 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 && digestFiles(directory, inventory(directory, "node_modules")) === dependencyRevision;
+    return sourceRevision(directory) === expectedRevision && metadata.digest(directory, inventory(directory, "node_modules")) === 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");
+    metadata.flush();
     return { directory: target, revision: expectedRevision, key };
   }
   const temporary = path.join(cache, `.preparing-${process.pid}-${randomUUID()}`);
@@ -79,14 +177,19 @@ export function createReleaseSnapshot(root, { cache = snapshotRoot(), expectedRe
     for (const file of files) {
       fs.copyFileSync(path.join(root, file), path.join(temporary, file), fs.constants.COPYFILE_FICLONE);
     }
-    if (sourceRevision(root) !== expectedRevision || digestFiles(root, inventory(root, "node_modules")) !== dependencyRevision || !validate(temporary)) {
+    if (sourceRevision(root) !== expectedRevision || metadata.digest(root, inventory(root, "node_modules")) !== dependencyRevision || !validate(temporary)) {
       throw new Error("The installation changed while its immutable runtime was being prepared");
     }
-    try { fs.renameSync(temporary, target); }
+    try {
+      fs.renameSync(temporary, target);
+      metadata.relocate(temporary, target);
+    }
     catch (error) {
       if (!fs.existsSync(target) || !validate(target)) throw error;
       removeOwned(temporary, cache);
+      metadata.forget(temporary);
     }
+    metadata.flush();
     return { directory: target, revision: expectedRevision, key };
   } catch (error) {
     removeOwned(temporary, cache);

package/src/reload-control.mjs

@@ -1,3 +1,9 @@
+export function assertRoutingReload(previous, next) {
+  if (typeof previous !== "boolean" || typeof next !== "boolean" || previous && !next) {
+    throw new Error("Invalid routing reload or Desktop-to-app-server downgrade; reconnect explicitly to change to legacy mode");
+  }
+}
+
 export function cloneReloadState(value) {
   const encoded = JSON.stringify(value);
   if (typeof encoded !== "string" || Buffer.byteLength(encoded) > 16 * 1024 * 1024) {