@minhspark/codex-mcp-bridge 1.22.5 → 1.22.7

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.22.5",
+  "version": "1.22.7",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,52 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.7] - 2026-10-20
+
+### Added
+
+- Install with Homebrew: `brew install buidangminh23/tap/codex-mcp-bridge`. The formula in [buidangminh23/homebrew-tap](https://github.com/buidangminh23/homebrew-tap) follows each npm release.
+
+### Fixed
+
+- Record Homebrew's stable `opt` paths instead of a versioned Cellar keg when the Claude Desktop, Codex and native relay installers and `bridge-projects register-manager` write a client configuration, for both the bridge and Homebrew's Node.js. A keg path broke every registration as soon as `brew upgrade` removed the old keg. Paths outside a Homebrew keg are written exactly as before.
+- Start the supervisor when its path reaches the installation through a symbolic link, such as Homebrew's `opt` alias. The direct-execution check compared the unresolved command-line path with the resolved module path, so the process exited at once without serving MCP.
+- Follow a Homebrew upgrade in a running supervisor: it watches the `opt` alias, reloads the new keg like any other installed update, and forks workers with the stable Node.js path, instead of reporting "Installation is not ready" after the old keg is removed.
+
+### Verification
+
+- 9 new regression tests: Cellar to `opt` mapping, a custom `HOMEBREW_PREFIX`, the main-module check through a symlink and a respelled path, a running supervisor following a bridge keg switch, and one following a Node.js keg replacement. The supervisor tests fail on v1.22.6 and pass here.
+- End to end on macOS with a local tap: two packed versions installed with brew, the three installers run against an isolated home, and every recorded path was `opt/codex-mcp-bridge` and `opt/node` (the relay keeps Codex Desktop's Node). A bridge launched from the recorded Claude Desktop entry kept its supervisor through `brew upgrade` and `brew cleanup` and reloaded the new keg; fresh launches from the recorded paths answered `initialize`.
+- An independent adversarial review confirmed two defects in the first draft, a main-module regression for respelled paths and a worker Node path resolved too late, and both were fixed before merge.
+
+### Limitations
+
+- Registrations written from a Homebrew keg by an earlier version still name that keg; run the installers once after upgrading. `codex-native-relay-install` still refuses to rewrite an entry that has `env_vars`, so edit that entry's path by hand.
+
+## [1.22.6] - 2026-10-20
+
+### Fixed
+
+- Keep a confirmed Desktop creation identifiable when post-creation verification fails. `delegate_to_codex` and `start_codex_thread` now return the task's threadId, its deliveryId and "Task was accepted; do not resend" instead of a bare allowed-roots error that read as if nothing had been created. The confirmed threadId is kept even when a later account, receipt or scope check fails after the bridge waited for the task's workspace.
+- Treat a filesystem root that Codex Desktop briefly reports as a newly created task's workspace, observed as `/` right after creation following an account switch, as "workspace not yet assigned" when it is not the expected project. Creation keeps observing until its deadline and then returns a pending receipt that keeps the accepted threadId; reply observation keeps polling. The tolerance lasts at most 120 seconds from creation, or from the first such report during reply observation, and the bridge acts on nothing at that path and grants no task access from it during that time.
+- Report a pending creation whose task Desktop already confirmed as `deliveryStatus: accepted` instead of `unconfirmed`.
+
+### Security
+
+- A root report that outlasts the grace period, any other workspace outside the allowed roots, a different project, an account change or a sender mismatch still fails closed. Sends and plain thread inspection keep the normal allowed-roots refusal for a root workspace; nothing is sent.
+
+### Verification
+
+- 10 regression tests reproduce the defect on v1.22.5 and pass with the fix: creation confirmation with a brief `/` report, a pending result at the deadline, grace expiry, an outside-root workspace, a later account change, reply observation in both the wait and snapshot paths, and two MCP-level `delegate_to_codex` tests through the relay companion.
+- The full CI matrix passed on Windows, macOS and Linux with Node 22 and 24. A local run outside the sandbox passed 1406 tests with 0 failures.
+- An independent adversarial review found no security regression; its four confirmed correctness findings were fixed before merge.
+
+### Upgrade notes
+
+- Reconnect the MCP server after updating and confirm the loaded version from the actual runtime before relying on the fix.
+- A creation that is pending because Desktop has not reported its workspace continues with `wait_codex_reply` and the returned deliveryId. Do not resend the prompt or create the task again.
+- Not yet exercised against a live Desktop account switch. A placeholder workspace other than a filesystem root still fails closed as before.
+
 ## [1.22.5] - 2026-10-19
 
 ### Fixed

package/README.md

@@ -27,6 +27,14 @@ npm install -g @minhspark/codex-mcp-bridge@latest
 
 Requires **Node.js 22+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
 
+On macOS or Linux you can install with [Homebrew](https://github.com/buidangminh23/homebrew-tap) instead, which brings its own Node.js:
+
+```bash
+brew install buidangminh23/tap/codex-mcp-bridge
+```
+
+Update with `brew upgrade codex-mcp-bridge`. The installers record Homebrew's stable `opt` paths, so registrations keep working after an upgrade and running bridges reload the new version. Keep one install channel: whichever of npm or Homebrew comes first on `PATH` provides the commands.
+
 [Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [ChatGPT plugin](#chatgpt-plugin)
 
 ### Windows (PowerShell)
@@ -93,6 +101,15 @@ claude mcp add --scope user codex-bridge \
   -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
 ```
 
+For a Homebrew install, use the stable paths instead of `npm root -g` and `command -v node`:
+
+```bash
+bridge_root="$(brew --prefix)/opt/codex-mcp-bridge/libexec/lib/node_modules/@minhspark/codex-mcp-bridge"
+node_bin="$(brew --prefix)/opt/node/bin/node"
+```
+
+and end the command with `-- "$node_bin" "$bridge_root/src/mcp-supervisor.mjs" index.mjs`.
+
 </details>
 
 Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
@@ -178,7 +195,7 @@ Dispatch expires after two minutes; operation history remains stored. Disconnect
 
 ## Troubleshooting
 
-- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory on PATH.
+- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory (or Homebrew's `bin`) on PATH.
 - **PowerShell blocks scripts:** use `npm.cmd`, installer `.cmd` launchers, and `codex.exe`.
 - **No sessions or wrong project:** open the intended Claude **Code** session and use the exact project directory saved in Codex Desktop.
 - **Relay unavailable:** check [pipe forwarding](#native-relay-pipe-forwarding), reconnect, and run `native_relay_status` in the task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.5",
+  "version": "1.22.7",
   "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/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.22.5",
+  "version": "1.22.7",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-claude-desktop.mjs

@@ -9,10 +9,11 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(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");
@@ -29,7 +30,7 @@ if (fullAccess) enableCodexFullAccess();
  */
 const defaultRoots = "*";
 
-const nodeBin = process.env.NODE_EXE ?? process.execPath;
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 
 if (!fs.existsSync(nodeBin)) throw new Error(`node executable not found: ${nodeBin}`);

package/scripts/install-codex-mcp.mjs

@@ -10,10 +10,12 @@ import { desktopTasksConfigured } from "../src/native-relay.mjs";
 import { codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath, stableNodeBin } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const nodeBin = process.env.NODE_EXE ?? stableNodeBin();
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
 const serverName = process.env.CLAUDE_BRIDGE_NAME ?? "claude-bridge";
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
@@ -39,13 +41,13 @@ const servers = JSON.parse(run(["mcp", "list", "--json"]));
 if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
 const existing = servers.some((server) => server.name === serverName)
   ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
-const registration = codexMcpRegistration({ name: serverName, existing, node: process.execPath, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
+const registration = codexMcpRegistration({ name: serverName, existing, node: nodeBin, entry, entryArgs, env: process.env, desktopOnly: desktopTasksConfigured() });
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...registration.environment }) });
 run(registration.args);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`registered MCP server "${serverName}" with Codex:`);
-console.log(`command: ${process.execPath} ${entry} ${entryArgs.join(" ")}`);
+console.log(`command: ${nodeBin} ${entry} ${entryArgs.join(" ")}`);
 console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
 console.log("\nReconnect claude-bridge once in the existing Codex Desktop task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle. Do not create a replacement task.");
 console.log("Verify claude_bridge_status from that task: autoReload must be enabled, runtime state must be current, and the session policy must match this installation. A separate diagnostic process does not verify the app's loaded MCP process.");

package/scripts/install-native-relay.mjs

@@ -20,11 +20,12 @@ import { exitForVersionRequest } from "../src/cli-version.mjs";
 import { stdioMcpRegistration } from "../src/codex-mcp-registration.mjs";
 import { createReleaseSnapshot, snapshotRoot } from "../src/release-snapshot.mjs";
 import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-access.mjs";
+import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.5";
-const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = "1.22.7";
+const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.5";
+const VERSION = "1.22.7";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.5";
+const VERSION = "1.22.7";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -211,6 +211,25 @@ function threadNameFor({ cwd, prompt, name }) {
   );
 }
 
+/**
+ * Once a Desktop creation was dispatched, a later verification failure must
+ * never read like a refusal: the caller keeps the task and receipt identity
+ * and is told not to resend. Verification still fails closed; only the report
+ * changes.
+ */
+function creationVerificationFailure({ created, deliveryId, requestId, err }) {
+  const threadId = created.threadId ?? err?.threadId ?? null;
+  const lines = threadId
+    ? ["Codex Desktop accepted the task, but post-creation verification failed.", `threadId: ${threadId}`]
+    : ["Codex Desktop creation was dispatched, but its outcome is not yet confirmed."];
+  lines.push(...(requestId ? [`requestId: ${requestId}`] : []), `cwd: ${created.cwd}`, ...(deliveryId ? [`deliveryId: ${deliveryId}`] : []), `error: ${err?.message ?? String(err)}`,
+    threadId ? "Task was accepted; do not resend. Resolve the verification error, then continue observing with wait_codex_reply and this deliveryId." : "Do not resend or create again. Continue observing with wait_codex_reply and this deliveryId.");
+  return {
+    ...textResult(lines.join("\n"), true),
+    structuredContent: { ...failure(err).structuredContent, threadId, deliveryStatus: threadId ? "accepted" : "unconfirmed", ...(deliveryId ? { deliveryId } : {}), nextAction: deliveryId ? "wait_codex_reply" : "none" },
+  };
+}
+
 async function delegateDesktopTask({ cwd, prompt, name, requestId, model, effort, timeoutSec, openInApp, waitForReply = true }) {
   const deadline = desktopOperation.getStore()?.deadline ?? Date.now() + Math.min((timeoutSec ?? 40) * 1000, DESKTOP_TOOL_BUDGET_MS);
   const workspace = resolveWorkspacePath(cwd);
@@ -222,8 +241,17 @@ async function delegateDesktopTask({ cwd, prompt, name, requestId, model, effort
   const deliveryId = created.deliveryId;
   let delivered = deliveryId ? replyReceipts.read(deliveryId, desktopOperation.getStore()) : null;
   if (delivered?.creationObservation) {
-    const resolved = await desktopTasks.resolveCreation(delivered, { deadline });
-    if (!resolved) return replyResult(delivered, deliveryId, { threadId: null, status: "timeout", responseStatus: "unavailable", text: "" }, ["Creation acknowledgement pending; do not create again."]);
+    let resolved;
+    try {
+      resolved = await desktopTasks.resolveCreation(delivered, { deadline });
+    } catch (err) {
+      return creationVerificationFailure({ created, deliveryId, requestId, err });
+    }
+    if (!resolved) {
+      const threadId = created.threadId ?? null;
+      return replyResult({ ...delivered, threadId, ...(threadId ? { deliveryStatus: "accepted" } : {}) }, deliveryId, { threadId, status: "timeout", responseStatus: "unavailable", text: "" },
+        [...(threadId ? [`threadId: ${threadId}`, "Task was accepted; Codex Desktop has not yet confirmed its workspace or creation receipt."] : []), "Creation acknowledgement pending; do not create again."]);
+    }
     delivered = resolved;
     created.threadId = resolved.threadId;
   }

package/src/install-paths.mjs

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KEG_PATH = /^(\/.*?)\/Cellar\/([^/]+)\/[^/]+(\/.*)?$/;
+
+function resolved(target) {
+  try { return fs.realpathSync.native(target); } catch { return null; }
+}
+
+/**
+ * Homebrew installs every version of a formula into its own Cellar keg and
+ * deletes the old keg on upgrade, while <prefix>/opt/<formula> is retargeted to
+ * the current one. A path that outlives this process - written into a client
+ * configuration, or watched for an upgrade - therefore has to name the opt
+ * alias. A keg path is rewritten only when the alias resolves to the same file
+ * right now; every other path is returned unchanged.
+ */
+export function stableInstallPath(target, env = process.env) {
+  if (process.platform === "win32" || typeof target !== "string") return target;
+  const match = KEG_PATH.exec(target);
+  if (!match) return target;
+  const real = resolved(target);
+  if (!real) return target;
+  const [, base, formula, rest = ""] = match;
+  const prefixes = [...new Set([env.HOMEBREW_PREFIX, base].filter((prefix) => prefix && path.isAbsolute(prefix)))];
+  for (const prefix of prefixes) {
+    const alias = path.join(prefix, "opt", formula) + rest;
+    if (resolved(alias) === real) return alias;
+  }
+  return target;
+}
+
+/** The node binary to record for later launches. */
+export function stableNodeBin(env = process.env) {
+  return stableInstallPath(process.execPath, env);
+}
+
+/**
+ * True when `entry` names the running main module, however it was reached.
+ * Node resolves the main module with the JavaScript realpath, which follows
+ * symlinks but keeps the spelling of the path as typed (case, 8.3 names,
+ * substituted drives), so that is the form compared first.
+ */
+export function isMainModule(entry, moduleUrl) {
+  if (!entry) return false;
+  const file = path.resolve(entry);
+  const module = fileURLToPath(moduleUrl);
+  let typed;
+  try { typed = fs.realpathSync(file); } catch { typed = file; }
+  if (typed === module) return true;
+  const canonical = resolved(file);
+  return canonical !== null && canonical === resolved(module);
+}

package/src/mcp-supervisor.mjs

@@ -5,7 +5,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createReleaseSnapshot, sourceRevision } from "./release-snapshot.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
+import { isMainModule, stableInstallPath } from "./install-paths.mjs";
 
+const WORKER_NODE = stableInstallPath(process.execPath);
 const ENTRIES = new Set(["index.mjs", "claude-bridge.mjs", "native-relay-companion.mjs"]);
 const MAX_FRAME_BYTES = 16 * 1024 * 1024;
 const MAX_QUEUE = 256;
@@ -40,7 +42,7 @@ class Worker {
     this.retiring = false;
     this.closed = false;
     this.process = fork(path.join(release.directory, "src", entry), [], {
-      execPath: process.execPath, execArgv: [], cwd: process.cwd(), windowsHide: true,
+      execPath: WORKER_NODE, execArgv: [], cwd: process.cwd(), windowsHide: true,
       env: { ...env, CODEX_BRIDGE_WORKER: "1", CODEX_BRIDGE_STAGED: "1" },
       stdio: ["pipe", "pipe", "pipe", "ipc"], serialization: "json",
     });
@@ -133,14 +135,16 @@ class Worker {
 
 export async function runSupervisor(entry, options = {}) {
   if (!ENTRIES.has(entry)) throw new Error("Expected index.mjs, claude-bridge.mjs, or native-relay-companion.mjs");
-  const root = fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const installRoot = stableInstallPath(fs.realpathSync.native(options.root ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")));
+  const currentRoot = () => fs.realpathSync.native(installRoot);
+  const root = currentRoot();
   if (process.argv.includes("--version") || process.argv.includes("-v")) {
     process.stdout.write(`${JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version}\n`);
     return;
   }
   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 env = { ...process.env, CODEX_BRIDGE_SOURCE_ROOT: installRoot };
   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");
@@ -226,9 +230,10 @@ export async function runSupervisor(entry, options = {}) {
   };
   const check = async () => {
     if (switching || !ready || stopping || failure) return;
+    let source;
     let revision;
     let routing;
-    try { revision = sourceRevision(root); routing = routingConfiguration(); }
+    try { source = currentRoot(); revision = sourceRevision(source); routing = routingConfiguration(); }
     catch (error) { reason = `Installation is not ready: ${error.message}`; 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; }
@@ -241,7 +246,7 @@ export async function runSupervisor(entry, options = {}) {
     try {
       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 });
+      const release = createReleaseSnapshot(source, { expectedRevision: revision });
       candidate = spawn(release, routing);
       const initialized = await candidate.rpc("initialize", initializeParams);
       if (initialized.protocolVersion !== initializeResult.protocolVersion || JSON.stringify(initialized.capabilities) !== JSON.stringify(initializeResult.capabilities)) {
@@ -251,7 +256,7 @@ export async function runSupervisor(entry, options = {}) {
       const catalog = await candidate.rpc("tools/list", {});
       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 (sourceRevision(currentRoot()) !== 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");
@@ -339,6 +344,6 @@ export async function runSupervisor(entry, options = {}) {
   log(`supervising ${entry}; installed updates activate after pending work completes`);
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+if (isMainModule(process.argv[1], import.meta.url)) {
   await runSupervisor(process.argv[2]);
 }

package/src/native-relay-companion.mjs

@@ -38,7 +38,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.5";
+const VERSION = "1.22.7";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {

package/src/platform.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
+import { stableNodeBin } from "./install-paths.mjs";
+
 const execFileAsync = promisify(execFile);
 
 export const IS_MACOS = process.platform === "darwin";
@@ -230,7 +232,7 @@ export function resolveCodexDesktopNodeBin(
   ]) {
     if (candidate && isRunnable(candidate)) return { path: candidate, source };
   }
-  return { path: process.execPath, source: "process.execPath" };
+  return { path: stableNodeBin(env), source: "process.execPath" };
 }
 
 /**
@@ -393,7 +395,7 @@ export function spawnEnv(extra = {}) {
   const systemDirs = IS_WINDOWS
     ? []
     : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
-  const merged = [path.dirname(process.execPath), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
+  const merged = [path.dirname(stableNodeBin()), ...systemDirs, ...(process.env.PATH ?? "").split(separator)]
     .filter(Boolean)
     .filter((dir, index, all) => all.indexOf(dir) === index)
     .join(separator);

package/src/project-manager-registration.mjs

@@ -4,15 +4,16 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { readRegularConfigFile, backupRegularConfigFile } from "./project-policy.mjs";
+import { stableInstallPath, stableNodeBin } from "./install-paths.mjs";
 
 // Optional UI adapter discovery. Neither bridge startup nor policy evaluation reads
 // this file. Removing the card extension or this descriptor cannot stop messaging.
-export function registerProjectManager({ policyFile, env = process.env, executable = process.execPath } = {}) {
+export function registerProjectManager({ policyFile, env = process.env, executable = stableNodeBin(env) } = {}) {
   if (!path.isAbsolute(policyFile ?? "")) throw new Error("Manager policy path must be absolute");
   const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
   const file = path.join(home, ".config", "GptClaudeBridge", "management.json");
   const value = { version: 1, node: executable,
-    script: fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)),
+    script: stableInstallPath(fileURLToPath(new URL("../scripts/bridge-projects.mjs", import.meta.url)), env),
     policyFile, configFile: env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, ".claude.json") : path.join(home, ".claude.json") };
   if (!Object.values(value).filter(v => typeof v === "string").every(v => path.isAbsolute(v))) throw new Error("Manager paths must be absolute");
   fs.mkdirSync(path.dirname(file), { recursive: true });

package/src/thread-delivery.mjs

@@ -26,6 +26,8 @@ import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
 export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
 export const DESKTOP_TOOL_BUDGET_MS = 40000;
+export const WORKSPACE_UNASSIGNED = "DESKTOP_WORKSPACE_UNASSIGNED";
+export const UNASSIGNED_WORKSPACE_GRACE_MS = 120000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 const METADATA_READ_OPTIONS = { includeOutputs: false, maxOutputCharsPerItem: 1 };
 
@@ -35,6 +37,17 @@ function unavailableWaitRenderer(error) {
     /^(Codex app tool request failed\.?|The app tool call ended before producing a result\.?)$/.test(cause.message);
 }
 
+function isFilesystemRoot(value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) return false;
+  const resolved = path.resolve(value);
+  return path.parse(resolved).root === resolved;
+}
+
+function acceptedCreationError(threadId, error) {
+  if (error.acceptedCreation) return error;
+  return Object.assign(new Error(`Codex Desktop created task ${threadId}, but its post-creation verification failed: ${error.message}. threadId: ${threadId}. Task was accepted; do not resend. Its reply was withheld until the verification error is resolved.`, { cause: error }), { code: "DESKTOP_CREATION_VERIFICATION_FAILED", threadId, acceptedCreation: true });
+}
+
 function sameAccountContext(expected, current) {
   return Boolean(expected && current && ["claude", "codex"].every((provider) =>
     typeof expected[provider] === "string" && expected[provider] === current[provider]));
@@ -75,6 +88,8 @@ export class DesktopTaskDelivery {
     this.threadOperations = new Map();
   }
 
+  #unassignedSince = new Map();
+
   senderProjectScope(cwd) {
     if (!this.senderContext) return null;
     const sender = requireClaudeSenderContext(this.senderContext());
@@ -329,6 +344,15 @@ export class DesktopTaskDelivery {
   async resolveCreation(delivered, { deadline = this.now() + DESKTOP_TOOL_BUDGET_MS } = {}) {
     const binding = delivered.creationObservation;
     if (!binding) return delivered;
+    let confirmedThreadId = null;
+    try {
+      return await this.#resolveCreationLoop(delivered, binding, deadline, (threadId) => { confirmedThreadId = threadId; });
+    } catch (error) {
+      throw confirmedThreadId ? acceptedCreationError(confirmedThreadId, error) : error;
+    }
+  }
+
+  async #resolveCreationLoop(delivered, binding, deadline, onConfirmed) {
     for (;;) {
       if (this.now() >= deadline) return null;
       this.security.assertCwd(delivered.cwd);
@@ -345,17 +369,29 @@ export class DesktopTaskDelivery {
         const response = row.result, threadId = response?.threadId;
         if (typeof threadId !== "string" || !threadId.trim() || response.hostId !== "local" || response.status === "outcome-unknown" ||
             response.firstTurn && response.firstTurn.status !== "accepted" || receipt.threadId && receipt.threadId !== threadId) throw new Error("Native creation is not confirmed; do not resend");
+        onConfirmed(threadId);
         let inspected;
-        try { inspected = await this.#inspectMetadata(threadId, delivered.cwd, { deadline }); }
-        catch (error) { if (this.now() >= deadline && /deadline|within \d+ms/.test(error.message)) return null; throw error; }
-        if (inspected.executorThreadId !== envelope.executorThreadId) throw new Error("Native creation executor changed");
-        if (!sameAccountContext(binding.accountContext, this.accountContext?.())) throw new Error("Creation receipt account changed");
-        this.security.assertCwd(delivered.cwd);
-        this.senderProjectScope(delivered.cwd);
-        if (this.security.hardenedRoots?.mode === "project-policy") this.security.hardenedRoots.recheck(inspected.scopeBinding);
-        if (inspected.projectScope) recheckProjectScope(inspected.projectScope);
-        this.security.registerThread(threadId);
-        this.security.assertThread(threadId, inspected.thread.cwd);
+        try { inspected = await this.#inspectMetadata(threadId, delivered.cwd, { deadline, tolerance: { since: receipt.startedAt } }); }
+        catch (error) {
+          if (error.code === WORKSPACE_UNASSIGNED) {
+            await this.sleep(Math.min(1000, Math.max(0, deadline - this.now())));
+            continue;
+          }
+          if (this.now() >= deadline && /deadline|within \d+ms/.test(error.message)) return null;
+          throw acceptedCreationError(threadId, error);
+        }
+        try {
+          if (inspected.executorThreadId !== envelope.executorThreadId) throw new Error("Native creation executor changed");
+          if (!sameAccountContext(binding.accountContext, this.accountContext?.())) throw new Error("Creation receipt account changed");
+          this.security.assertCwd(delivered.cwd);
+          this.senderProjectScope(delivered.cwd);
+          if (this.security.hardenedRoots?.mode === "project-policy") this.security.hardenedRoots.recheck(inspected.scopeBinding);
+          if (inspected.projectScope) recheckProjectScope(inspected.projectScope);
+          this.security.registerThread(threadId);
+          this.security.assertThread(threadId, inspected.thread.cwd);
+        } catch (error) {
+          throw acceptedCreationError(threadId, error);
+        }
         return { threadId, cwd: delivered.cwd, previousTurnId: null, deliveryStatus: "accepted",
           responseObservation: { operation: "create_thread", threadId, previousTurnId: null, expectedCwd: delivered.cwd,
             executorThreadId: envelope.executorThreadId, prompt: binding.args.prompt, accountContext: binding.accountContext } };
@@ -366,18 +402,18 @@ export class DesktopTaskDelivery {
     }
   }
 
-  async inspect(threadId, cwd, { deadline } = {}) {
-    const inspected = await this.#inspectMetadata(threadId, cwd, { deadline });
+  async inspect(threadId, cwd, { deadline, tolerateUnassigned = false } = {}) {
+    const inspected = await this.#inspectMetadata(threadId, cwd, { deadline, ...(tolerateUnassigned ? { tolerance: {} } : {}) });
     this.security.assertThread(threadId, inspected.thread.cwd);
     return inspected;
   }
 
-  async #inspectMetadata(threadId, cwd, { deadline } = {}) {
+  async #inspectMetadata(threadId, cwd, { deadline, tolerance } = {}) {
     const envelope = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline, includeRelayContext: true });
     const response = envelope.result;
     const thread = response?.thread;
     if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the task's local workspace.");
-    this.security.assertCwd(thread.cwd);
+    this.#assertReportedWorkspace(threadId, thread.cwd, cwd, tolerance);
     const projectScope = this.senderProjectScope(thread.cwd);
     if (cwd && path.relative(realpathSync.native(cwd), realpathSync.native(thread.cwd))) {
       throw new Error("Native Desktop delivery cannot change an existing task's workspace; create a new task at the requested cwd.");
@@ -386,6 +422,39 @@ export class DesktopTaskDelivery {
     return { thread, latestTurnId: response.turns?.[0]?.id ?? null, projectScope, scopeBinding, executorThreadId: envelope.executorThreadId ?? null };
   }
 
+  /**
+   * Codex Desktop can briefly report a filesystem root as a task's workspace
+   * before it finishes assigning the task's saved project (observed as "/"
+   * right after creation, following an account switch). Only observers that
+   * pass a tolerance - creation confirmation and reply observation, both of
+   * which already know the expected workspace - treat a root that differs from
+   * that workspace as "not yet assigned", and only for a bounded grace period
+   * measured from creation or from the first such report. During it the bridge
+   * acts on nothing at that path, grants no access and keeps observing. After
+   * it, and for every other caller or path, the normal fail-closed
+   * allowed-roots check applies.
+   */
+  #assertReportedWorkspace(threadId, reported, expected, tolerance) {
+    if (!isFilesystemRoot(reported)) this.#unassignedSince.delete(threadId);
+    else if (tolerance && expected && !this.#isExpectedWorkspace(reported, expected)) {
+      const now = this.now();
+      if (tolerance.since === undefined && !this.#unassignedSince.has(threadId)) this.#unassignedSince.set(threadId, now);
+      const since = tolerance.since ?? this.#unassignedSince.get(threadId);
+      if (now - since < UNASSIGNED_WORKSPACE_GRACE_MS) {
+        throw Object.assign(new Error(`Codex Desktop has not yet reported task ${threadId}'s project workspace (it currently reports ${reported}); the bridge did not act on that path.`), { code: WORKSPACE_UNASSIGNED, threadId });
+      }
+    }
+    this.security.assertCwd(reported);
+  }
+
+  #isExpectedWorkspace(reported, expected) {
+    try {
+      return path.relative(realpathSync.native(expected), realpathSync.native(reported)) === "";
+    } catch {
+      return false;
+    }
+  }
+
   async send({ threadId, prompt, cwd, model, effort, name, deadline, onPrepared }) {
     const inspected = await this.inspect(threadId, cwd, { deadline });
     const scopeBinding = this.security.hardenedRoots?.mode === "project-policy" ? this.security.hardenedRoots.capture(inspected.thread.cwd) : undefined;
@@ -445,12 +514,12 @@ export class DesktopTaskDelivery {
       if (realpathSync.native(expectedCwd) !== expectedCwd) throw new Error("The selected native task workspace changed while its response was being observed");
     };
     await recheck();
-    const initial = await this.inspect(threadId, expectedCwd, { deadline });
+    const initial = await this.inspect(threadId, expectedCwd, { deadline, tolerateUnassigned: true });
     if (!resolveDispatch && initial.latestTurnId !== turnId) throw new Error("The selected native task changed before its response could be read; reply content was withheld");
     const read = resolveDispatch ? this.resolveResponse : responseObservation.operation === "create_thread" ? readCodexNativeCreationResponse : this.readResponse;
     const observed = read({ ...responseObservation, threadId, turnId, desktopEvidence: initial });
     await recheck();
-    const inspected = await this.inspect(threadId, expectedCwd, { deadline });
+    const inspected = await this.inspect(threadId, expectedCwd, { deadline, tolerateUnassigned: true });
     if (inspected.latestTurnId !== (resolveDispatch ? initial.latestTurnId : turnId)) throw new Error("The selected native task changed before its response could be confirmed; reply content was withheld");
     await recheck();
     return observed;
@@ -485,7 +554,7 @@ export class DesktopTaskDelivery {
       const result = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline: startedAt + timeoutMs });
       const thread = result?.thread;
       if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the observed task's local workspace.");
-      this.security.assertCwd(thread.cwd);
+      this.#assertReportedWorkspace(threadId, thread.cwd, responseObservation?.expectedCwd, {});
       this.security.assertThread(threadId, thread.cwd);
       this.senderProjectScope(thread.cwd);
       if (responseObservation?.expectedCwd && realpathSync.native(thread.cwd) !== responseObservation.expectedCwd) throw new Error("The selected native task workspace changed during observation");
@@ -497,14 +566,17 @@ export class DesktopTaskDelivery {
       return this.now() - startedAt >= timeoutMs && (["DESKTOP_RESPONSE_DEADLINE", "RELAY_TIMEOUT"].includes(cause.code) ||
         cause.code === "RELAY_UNREACHABLE" && cause.message === "The Codex Desktop relay send deadline elapsed before dispatch");
     };
+    const unassigned = Symbol("workspace-unassigned");
     const observe = async (selectedTurnId, resolveDispatch = false) => {
       try {
         return await this.observeNativeResponse(threadId, selectedTurnId, responseObservation, { deadline: startedAt + timeoutMs, resolveDispatch });
       } catch (error) {
         if (deadlineError(error)) return null;
+        if (error.code === WORKSPACE_UNASSIGNED) return unassigned;
         throw error;
       }
     };
+    const pause = () => this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
     for (;;) {
       if (this.now() - startedAt >= timeoutMs) return expired();
       let response;
@@ -514,13 +586,19 @@ export class DesktopTaskDelivery {
         }, { deadline: startedAt + timeoutMs });
       } catch (err) {
         if (deadlineError(err)) return expired();
+        if (err.code === WORKSPACE_UNASSIGNED) {
+          await pause();
+          continue;
+        }
         if (readSnapshots || !unavailableWaitRenderer(err)) throw err;
         readSnapshots = true;
         try {
           response = await readSnapshot();
         } catch (readError) {
           if (deadlineError(readError)) return expired();
-          throw readError;
+          if (readError.code !== WORKSPACE_UNASSIGNED) throw readError;
+          await pause();
+          continue;
         }
       }
       const poll = response?.polls?.find((item) => item.thread?.id === threadId && item.thread?.hostId === "local");
@@ -533,6 +611,10 @@ export class DesktopTaskDelivery {
       if (this.resolveResponse && responseObservation?.watermark?.status === "available" && responseObservation.operation !== "create_thread") {
         const observed = await observe(null, true);
         if (!observed) return expired();
+        if (observed === unassigned) {
+          await pause();
+          continue;
+        }
         turnId = observed.turnId ?? null;
         if (observed.status !== "pending") {
           return {
@@ -559,6 +641,10 @@ export class DesktopTaskDelivery {
         if (RELEASE_STATUSES.has(status)) {
           const observed = await observe(turn.id);
           if (!observed) return expired();
+          if (observed === unassigned) {
+            await pause();
+            continue;
+          }
           const responseStatus = observed.status;
           if (existingTurn && !observed.dispatchObserved && !["completed", "completed_no_reply"].includes(responseStatus)) {
             turnId = null;