@minhspark/codex-mcp-bridge 1.22.15 → 1.22.16

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.22.16] - 2026-10-22
+
+### Fixed
+
+- Start the Codex Desktop native relay on its own after Codex Desktop opens, instead of only when a send fails. In 1.22.14 the relay woke only inside a failing Desktop request, so `codex_bridge_status` (which has no calling task) could never wake it, and a wake that took longer than its 20-second window left the request failed with the relay-down guidance. Each bridge process now checks the relay socket every 30 seconds. When the relay is missing and Codex Desktop is running, it opens a recent Codex Desktop task in the background and waits up to 60 seconds for the relay. Codex Desktop is checked at most once a minute while it is closed.
+- Coordinate wakes across bridge processes. Every Claude Code session runs its own bridge, so several of them could open tasks at the same moment. Wakes now share a state file (`~/.codex/bridge-relay-wake.json`) and a lock beside it. Only one process opens a task at a time; an on-demand request that finds the lock held waits for the relay instead of opening another task. Failed background wakes, including those that find no Codex Desktop task to open, back off from one minute up to 30 minutes and reset after a success. A stale lock is reclaimed.
+- Fall back to the most recent Codex Desktop task of any project when neither the destination task nor a task of the sender's project is available, so a status call or a session in a new project can still wake the relay. The internal Native Relay executor task is still never opened.
+- `CODEX_BRIDGE_RELAY_KEEPER=0` turns off the background check; `CODEX_BRIDGE_RELAY_WAKE=0` still turns off every wake.
+- A request that arrives while a background wake is in progress waits only until its own deadline instead of the background wake's 60 seconds.
+- `codex-sites-connector` runs `whoami.exe` and `icacls.exe` from `%SystemRoot%\System32` instead of looking them up on `PATH`. Started from Git Bash, it ran GNU `whoami`, could not read the Windows user SID and refused to protect its files.
+- `npm test` runs the suite without the caller's `CLAUDE*`, `CODEX_*`, `ANTHROPIC_*` and `MCP_*` variables. Inside a Claude Code session they pointed tests at the live Claude Desktop data, messaging socket and bridge configuration, so tests that pass in CI failed locally.
+
+### Limitations
+
+- Opening a task through `codex://threads/<id>` makes Codex Desktop show that task. The keeper opens only while the relay is missing and picks the most recent task, which is usually the one already on screen.
+- The keeper runs only while a Claude client keeps a bridge process alive. With no Claude session open, the relay still starts when a task is opened in Codex Desktop.
+
 ## [1.22.15] - 2026-10-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.15",
+  "version": "1.22.16",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -37,6 +37,7 @@
   "files": [
     "src",
     "scripts",
+    "!scripts/run-tests.mjs",
     "skills",
     "assets",
     "plugin.json",
@@ -62,7 +63,7 @@
     "start": "node src/codex-bridge-launcher.mjs",
     "claude-bridge": "node src/claude-bridge-launcher.mjs",
     "app-server": "codex app-server --listen ws://127.0.0.1:8791",
-    "test": "node --test",
+    "test": "node scripts/run-tests.mjs",
     "check": "node scripts/check.mjs",
     "check:claude": "node scripts/check-claude-bridge.mjs",
     "smoke": "node scripts/smoke.mjs",

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.15",
+  "version": "1.22.16",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -24,7 +24,7 @@ import { stableInstallPath } from "../src/install-paths.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.15";
+const VERSION = "1.22.16";
 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"];

package/src/claude-bridge.mjs

@@ -30,7 +30,7 @@ import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.15";
+const VERSION = "1.22.16";
 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

@@ -37,11 +37,11 @@ import { captureProjectScope } from "./project-scope.mjs";
 import { DesktopReplyReceipts } from "./desktop-reply-receipts.mjs";
 import { registerDesktopReadTools } from "./desktop-read-tools.mjs";
 import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
-import { createRelayWake } from "./relay-wake.mjs";
+import { createRelayWake, relayKeeperEnabled, relayWakeStateFile, startRelayKeeper } from "./relay-wake.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.22.15";
+const VERSION = "1.22.16";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -76,7 +76,8 @@ const desktopTasksEnabled = desktopTasksConfigured();
 const runtime = createRuntimeState({ configuration: desktopTasksConfigured });
 const desktopOperation = new AsyncLocalStorage();
 const replyReceipts = new DesktopReplyReceipts();
-const desktopTasks = new DesktopTaskDelivery({ security, beforeRequest: beforeDesktopRequest, accountContext: () => desktopOperation.getStore()?.accounts, senderContext: () => desktopOperation.getStore()?.caller, wakeRelay: createRelayWake({ senderCwd: () => desktopOperation.getStore()?.caller?.cwd ?? null, log }) });
+const relayWake = createRelayWake({ senderCwd: () => desktopOperation.getStore()?.caller?.cwd ?? null, stateFile: relayWakeStateFile(), log });
+const desktopTasks = new DesktopTaskDelivery({ security, beforeRequest: beforeDesktopRequest, accountContext: () => desktopOperation.getStore()?.accounts, senderContext: () => desktopOperation.getStore()?.caller, wakeRelay: relayWake });
 
 async function assertDesktopOperation(context, { verifyProcess = false } = {}) {
   if (!context || context.diagnostic) return;
@@ -1094,6 +1095,7 @@ registerTool(
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+if (desktopTasksEnabled && relayKeeperEnabled()) startRelayKeeper({ wake: relayWake, socketPath: () => desktopTasks.relay.accountSocketPath, log });
 let shutdownPromise;
 const shutdown = () => shutdownPromise ??= (async () => {
   client?.close();

package/src/native-relay-companion.mjs

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

package/src/relay-wake.mjs

@@ -11,6 +11,10 @@ const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
 const ROLLOUT = /^rollout-.+-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl(?:\.zst)?$/i;
 export const RELAY_WAKE_WAIT_MS = 20000;
 export const RELAY_WAKE_COOLDOWN_MS = 60000;
+export const RELAY_KEEPER_INTERVAL_MS = 30000;
+export const RELAY_KEEPER_WAIT_MS = 60000;
+export const RELAY_KEEPER_MAX_BACKOFF_MS = 30 * 60000;
+export const DESKTOP_RECHECK_MS = 60000;
 const MAX_DAY_DIRECTORIES = 14;
 const MAX_CANDIDATES = 40;
 
@@ -42,8 +46,18 @@ function sameProject(senderCwd, taskCwd) {
   catch { return false; }
 }
 
-export async function recentDesktopTaskFor(cwd, { env = process.env, sessions = path.join(codexHome(env), "sessions"), exclude = [] } = {}) {
-  if (typeof cwd !== "string" || !cwd) return null;
+export function relayKeeperEnabled(env = process.env, platform = process.platform) {
+  const value = (env.CODEX_BRIDGE_RELAY_KEEPER ?? "").toLowerCase();
+  if (["0", "off", "false"].includes(value)) return false;
+  return relayWakeEnabled(env, platform);
+}
+
+export function relayWakeStateFile(env = process.env) {
+  return path.join(codexHome(env), "bridge-relay-wake.json");
+}
+
+export async function recentDesktopTaskFor(cwd, { env = process.env, sessions = path.join(codexHome(env), "sessions"), exclude = [], anyProject = false } = {}) {
+  if (!anyProject && (typeof cwd !== "string" || !cwd)) return null;
   const excluded = new Set(exclude.filter(Boolean));
   const candidates = [];
   for (const directory of dayDirectories(sessions)) {
@@ -63,7 +77,7 @@ export async function recentDesktopTaskFor(cwd, { env = process.env, sessions =
     try { record = await readRolloutFirstRecord(candidate.file, { maxBytes: 256 * 1024 }); } catch { continue; }
     const meta = record?.type === "session_meta" ? record.payload : null;
     if (meta?.id !== candidate.threadId || meta.originator !== "Codex Desktop" || typeof meta.cwd !== "string") continue;
-    if (sameProject(cwd, meta.cwd)) return candidate.threadId;
+    if (anyProject || sameProject(cwd, meta.cwd)) return candidate.threadId;
   }
   return null;
 }
@@ -83,17 +97,59 @@ export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
   });
 }
 
+function readWakeState(file) {
+  if (!file) return {};
+  try {
+    const state = JSON.parse(fs.readFileSync(file, "utf8"));
+    return state && typeof state === "object" && !Array.isArray(state) ? state : {};
+  } catch { return {}; }
+}
+
+function writeWakeState(file, state) {
+  if (!file) return;
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(state));
+    fs.renameSync(temporary, file);
+  } catch { try { fs.rmSync(temporary, { force: true }); } catch {} }
+}
+
+function acquireWakeLock(file, now, staleMs) {
+  if (!file) return () => {};
+  const lock = `${file}.lock`;
+  const claim = () => {
+    const descriptor = fs.openSync(lock, "wx");
+    try { fs.writeSync(descriptor, JSON.stringify({ pid: process.pid, at: now() })); } finally { fs.closeSync(descriptor); }
+    return () => { try { fs.rmSync(lock, { force: true }); } catch {} };
+  };
+  try { return claim(); }
+  catch (error) { if (error.code !== "EEXIST") return null; }
+  let heldSince;
+  try { heldSince = JSON.parse(fs.readFileSync(lock, "utf8")).at; } catch { heldSince = 0; }
+  if (Number.isFinite(heldSince) && now() - heldSince < staleMs) return null;
+  try { fs.rmSync(lock, { force: true }); return claim(); } catch { return null; }
+}
+
+export function keeperBackoffMs(failures, { baseMs = RELAY_WAKE_COOLDOWN_MS, maxMs = RELAY_KEEPER_MAX_BACKOFF_MS } = {}) {
+  const count = Number.isInteger(failures) && failures > 0 ? Math.min(failures, 16) : 0;
+  return count === 0 ? 0 : Math.min(baseMs * 2 ** (count - 1), maxMs);
+}
+
 export function createRelayWake({
   env = process.env,
   enabled = relayWakeEnabled(env),
   desktopRunning = () => isCodexDesktopRunning(),
   senderCwd = () => null,
   findTask = (cwd, exclude) => recentDesktopTaskFor(cwd, { env, exclude }),
+  findAnyTask = (exclude) => recentDesktopTaskFor(null, { env, exclude, anyProject: true }),
   executorThreadId = () => { try { return resolveRelayThreadId(env).threadId; } catch { return null; } },
   open = (threadId) => openThreadInCodexApp(threadId, { activate: false }),
   answers = endpointAnswers,
   waitMs = RELAY_WAKE_WAIT_MS,
+  backgroundWaitMs = RELAY_KEEPER_WAIT_MS,
   cooldownMs = RELAY_WAKE_COOLDOWN_MS,
+  desktopRecheckMs = DESKTOP_RECHECK_MS,
+  stateFile = null,
   pollMs = 250,
   now = Date.now,
   sleep = (ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)),
@@ -101,29 +157,100 @@ export function createRelayWake({
 } = {}) {
   let inFlight = null;
   let failedAt = -Infinity;
-  const attempt = async ({ socketPath, threadId, deadline }) => {
-    if (!enabled || now() - failedAt < cooldownMs || !await desktopRunning()) return null;
-    const executor = executorThreadId();
-    const target = typeof threadId === "string" && THREAD_ID.test(threadId) && threadId !== executor
-      ? threadId : await findTask(senderCwd(), [executor]);
-    if (!target) return null;
-    try { await open(target); }
-    catch (error) {
-      failedAt = now();
-      log(`could not open Codex task ${target} to start the native relay: ${error.message}`);
-      return null;
-    }
-    const until = Math.min(now() + waitMs, deadline ?? Infinity);
+  const waitFor = async (socketPath, until) => {
     while (now() < until) {
-      if (await answers(socketPath)) {
+      if (await answers(socketPath)) return true;
+      await sleep(pollMs);
+    }
+    return false;
+  };
+  const attempt = async ({ socketPath, threadId, deadline, background = false }) => {
+    if (!enabled) return null;
+    const state = readWakeState(stateFile);
+    if (background) {
+      if (state.desktopRunning === false && now() - (state.desktopCheckedAt ?? -Infinity) < desktopRecheckMs) return null;
+      if (now() - (state.attemptAt ?? -Infinity) < Math.max(keeperBackoffMs(state.failures), cooldownMs)) return null;
+    } else if (now() - failedAt < cooldownMs) return null;
+    const running = await desktopRunning();
+    if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), desktopCheckedAt: now(), desktopRunning: Boolean(running) });
+    if (!running) return null;
+    const wait = background ? backgroundWaitMs : waitMs;
+    const release = acquireWakeLock(stateFile, now, wait + 15000);
+    if (!release) {
+      if (background) return null;
+      return await waitFor(socketPath, Math.min(now() + wait, deadline ?? Infinity)) ? { threadId: null } : null;
+    }
+    try {
+      const executor = executorThreadId();
+      const target = typeof threadId === "string" && THREAD_ID.test(threadId) && threadId !== executor
+        ? threadId : (await findTask(senderCwd(), [executor])) ?? (await findAnyTask([executor]));
+      const startedAt = now();
+      const failures = Number.isInteger(state.failures) ? state.failures : 0;
+      if (!target) {
+        if (background && stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: failures + 1 });
+        return null;
+      }
+      const fail = (message) => {
+        failedAt = now();
+        if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: failures + 1 });
+        log(message);
+        return null;
+      };
+      try { await open(target); }
+      catch (error) { return fail(`could not open Codex task ${target} to start the native relay: ${error.message}`); }
+      if (await waitFor(socketPath, Math.min(now() + wait, deadline ?? Infinity))) {
+        if (stateFile) writeWakeState(stateFile, { ...readWakeState(stateFile), attemptAt: startedAt, failures: 0 });
         log(`started the Codex Desktop native relay by opening task ${target} in the background`);
         return { threadId: target };
       }
-      await sleep(pollMs);
+      return fail(`opened Codex task ${target}, but the native relay did not start within ${wait} ms`);
+    } finally {
+      release();
     }
-    failedAt = now();
-    log(`opened Codex task ${target}, but the native relay did not start within ${waitMs} ms`);
-    return null;
   };
-  return (request) => inFlight ??= attempt(request).finally(() => { inFlight = null; });
+  return (request) => {
+    if (!inFlight) return inFlight = attempt(request).finally(() => { inFlight = null; });
+    if (request.background || !request.socketPath) return inFlight;
+    const until = Math.min(now() + waitMs, request.deadline ?? Infinity);
+    return Promise.race([inFlight, waitFor(request.socketPath, until).then((ready) => ready ? { threadId: null } : null)]);
+  };
+}
+
+export function startRelayKeeper({
+  wake,
+  socketPath,
+  answers = endpointAnswers,
+  intervalMs = RELAY_KEEPER_INTERVAL_MS,
+  initialDelayMs = 3000,
+  timers = globalThis,
+  log = () => {},
+}) {
+  let busy = false;
+  let stopped = false;
+  const tick = async () => {
+    if (busy || stopped) return null;
+    busy = true;
+    try {
+      const target = socketPath();
+      if (await answers(target)) return null;
+      return await wake({ socketPath: target, background: true });
+    } catch (error) {
+      log(`relay keeper check failed: ${error.message}`);
+      return null;
+    } finally {
+      busy = false;
+    }
+  };
+  const first = timers.setTimeout(tick, initialDelayMs);
+  const repeat = timers.setInterval(tick, intervalMs);
+  first?.unref?.();
+  repeat?.unref?.();
+  return {
+    tick,
+    stop() {
+      stopped = true;
+      timers.clearTimeout(first);
+      timers.clearInterval(repeat);
+    },
+  };
 }

package/src/sites-connector.mjs

@@ -86,10 +86,11 @@ export function defaultSitesConfigPath(env = process.env) {
 async function protectPrivatePath(target, directory = false) {
   if (process.platform !== "win32") { await fs.chmod(target, directory ? 0o700 : 0o600); return; }
   const run = promisify(execFile);
-  const { stdout } = await run("whoami.exe", ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
+  const system32 = path.win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32");
+  const { stdout } = await run(path.win32.join(system32, "whoami.exe"), ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
   const sid = stdout.match(/S-1-\d+(?:-\d+)+/)?.[0];
   if (!sid) throw new Error("Current Windows user SID could not be verified");
-  await run("icacls.exe", [target, "/inheritance:r", "/grant:r", `*${sid}:${directory ? "(OI)(CI)" : ""}(F)`], { windowsHide: true });
+  await run(path.win32.join(system32, "icacls.exe"), [target, "/inheritance:r", "/grant:r", `*${sid}:${directory ? "(OI)(CI)" : ""}(F)`], { windowsHide: true });
 }
 
 export async function pairSitesConnector({ siteUrl, allowedRoots, configFile = defaultSitesConfigPath(), readAccounts = readBridgeAccounts, fetchImpl = fetch, allowLoopback = false }) {