@minhspark/codex-mcp-bridge 1.25.1 → 1.25.3

package/src/relay-wake.mjs

@@ -1,22 +1,6 @@
-import fs from "node:fs";
 import net from "node:net";
-import path from "node:path";
 
-import { codexHome, resolveRelayThreadId } from "./native-relay.mjs";
-import { isCodexDesktopRunning, openThreadInCodexApp } from "./platform.mjs";
-import { captureProjectScope } from "./project-scope.mjs";
-import { readRolloutFirstRecord } from "./rollout-reader.mjs";
-
-const THREAD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-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;
 
 export function relayWakeEnabled(env = process.env, platform = process.platform) {
   const value = (env.CODEX_BRIDGE_RELAY_WAKE ?? "").toLowerCase();
@@ -24,71 +8,14 @@ export function relayWakeEnabled(env = process.env, platform = process.platform)
   return platform === "darwin" || platform === "win32";
 }
 
-function dayDirectories(sessions) {
-  const directories = [];
-  const children = (directory, pattern) => {
-    try { return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && pattern.test(entry.name)).map((entry) => entry.name).sort().reverse(); }
-    catch { return []; }
-  };
-  for (const year of children(sessions, /^\d{4}$/)) {
-    for (const month of children(path.join(sessions, year), /^\d{2}$/)) {
-      for (const day of children(path.join(sessions, year, month), /^\d{2}$/)) {
-        directories.push(path.join(sessions, year, month, day));
-        if (directories.length >= MAX_DAY_DIRECTORIES) return directories;
-      }
-    }
-  }
-  return directories;
-}
-
-function sameProject(senderCwd, taskCwd) {
-  try { captureProjectScope(senderCwd, taskCwd); return true; }
-  catch { return false; }
-}
-
-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;
-  if (!relayWakeEnabled(env, platform)) return false;
-  if (platform === "win32") return ["1", "on", "true"].includes(value);
-  return true;
-}
-
-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)) {
-    let entries;
-    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { continue; }
-    for (const entry of entries) {
-      const match = entry.isFile() ? ROLLOUT.exec(entry.name) : null;
-      if (!match || excluded.has(match[1])) continue;
-      const file = path.join(directory, entry.name);
-      try { candidates.push({ file, threadId: match[1], mtimeMs: fs.lstatSync(file).mtimeMs }); } catch {}
-    }
-    if (candidates.length >= MAX_CANDIDATES) break;
-  }
-  candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
-  for (const candidate of candidates.slice(0, MAX_CANDIDATES)) {
-    let record;
-    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 (anyProject || sameProject(cwd, meta.cwd)) return candidate.threadId;
-  }
-  return null;
-}
-
 export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
   if (typeof socketPath !== "string" || !socketPath) return Promise.resolve(false);
   return new Promise((resolve) => {
     const probe = net.connect({ path: socketPath });
+    let settled = false;
     const done = (answer) => {
+      if (settled) return;
+      settled = true;
       globalThis.clearTimeout(timer);
       probe.destroy();
       resolve(answer);
@@ -96,163 +23,33 @@ export function endpointAnswers(socketPath, { timeoutMs = 1000 } = {}) {
     const timer = globalThis.setTimeout(() => done(false), timeoutMs);
     probe.once("connect", () => done(true));
     probe.once("error", () => done(false));
+    probe.once("close", () => done(false));
   });
 }
 
-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)),
   log = () => {},
 } = {}) {
-  let inFlight = null;
-  let failedAt = -Infinity;
-  const waitFor = async (socketPath, until) => {
+  return async ({ socketPath, deadline }) => {
+    if (!enabled || typeof socketPath !== "string" || !socketPath) return null;
+    const until = Math.min(now() + waitMs, deadline ?? Infinity);
     while (now() < until) {
-      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;
+      if (await answers(socketPath, { timeoutMs: Math.min(1000, until - now()) })) {
+        if (now() >= until) return null;
+        log("relay transport available; the original operation will verify native dispatch");
+        return { threadId: 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 };
-      }
-      return fail(`opened Codex task ${target}, but the native relay did not start within ${wait} ms`);
-    } finally {
-      release();
+      const remaining = until - now();
+      if (remaining > 0) await sleep(Math.min(pollMs, remaining));
     }
-  };
-  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);
-    },
+    log("native relay recovery timed out; no task or window was opened");
+    return null;
   };
 }

package/src/setup.mjs

@@ -89,7 +89,7 @@ export function setupEnvironment(env, paths, codex) {
 }
 
 function configurationCheck(label, check, components) {
-  try { check(); components.push({ name: label, status: "configured" }); }
+  try { const details = check(); components.push({ name: label, status: "configured", ...details }); }
   catch (error) { components.push({ name: label, status: "incomplete", detail: error.message }); }
 }
 
@@ -99,8 +99,9 @@ function assertEntry(entry, worker, root, { caller } = {}) {
   const expected = worker === "index.mjs" || worker === "claude-bridge.mjs" || worker === "native-relay-companion.mjs"
     ? [path.join(root, "src", "mcp-supervisor.mjs"), worker] : [path.join(root, "src", worker)];
   if (JSON.stringify(args) !== JSON.stringify(expected)) throw new Error("MCP entry points to a different installation or unsupported launcher");
-  if (entry.enabled === false || entry.disabled === true) throw new Error("MCP entry is disabled; the saved choice was preserved");
   if (caller && entry.env?.ANTIGRAVITY_BRIDGE_CALLER !== caller) throw new Error("Antigravity caller registration is missing or conflicting");
+  if (entry.enabled === false || entry.disabled === true) return { deliveryEnabled: false,
+    notices: ["This MCP registration is intentionally disabled. Its saved choice was preserved; delivery through this connector is disabled."] };
 }
 
 export function checkSetup({ env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
@@ -119,8 +120,9 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
       const item = inventory?.find((server) => server.name === name);
       if (!item) throw new Error("MCP registration is missing");
       const entry = JSON.parse(run(codex, ["mcp", "get", name, "--json"], setupEnvironment(env, paths, codex), 30000));
-      assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
+      const details = assertEntry({ ...entry.transport, enabled: entry.enabled }, worker, root, name === "antigravity-bridge" ? { caller: "codex" } : {});
       if (name === "codex-native-relay" && !entry.transport.env_vars?.includes("CODEX_APP_TOOLS_PIPE_PATH")) throw new Error("Native pipe forwarding is missing");
+      return details;
     }, components);
   }
   for (const [label, file, name, worker, caller] of [
@@ -130,14 +132,26 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
     ["Antigravity / agent-bridge", path.join(paths.gemini, "mcp_config.json"), "agent-bridge", "antigravity-outbound-bridge.mjs"],
   ]) configurationCheck(label, () => {
     const entry = readJson(file)?.mcpServers?.[name];
-    assertEntry(entry, worker, root, { caller });
+    const details = assertEntry(entry, worker, root, { caller });
+    if (worker === "index.mjs" && entry.env?.CODEX_BRIDGE_OPEN_IN_APP === "1") {
+      throw new Error("Managed bridge settings still allow opening Codex Desktop. Run codex-bridge-setup to apply the current silent configuration.");
+    }
     if (name === "codex-bridge-desktop" && entry.env?.CODEX_BRIDGE_DESKTOP_TASKS === "1") {
-      throw new Error("Shared Desktop chat cannot use native Code routing. Its saved choice was preserved; explicitly set CODEX_BRIDGE_DESKTOP_TASKS=0 for the local app-server route and CODEX_BRIDGE_AUTOSTART=1 if the bridge should start that server.");
+      return { ...details, nativeCodeOnly: true, sharedChatDelivery: "unsupported",
+        notices: [...(details?.notices ?? []), "The saved native Code-only policy was preserved. Ordinary Claude Desktop Chat cannot deliver through this connector; native delivery uses the registered Claude Desktop Code connector and remains unverified by setup."] };
     }
+    return details;
+  }, components);
+  configurationCheck("Claude Desktop / background preference", () => {
+    if (readJson(paths.desktop)?.preferences?.menuBarEnabled !== true) throw new Error("The managed Claude background preference is not enabled. Run codex-bridge-setup to apply it; live activation is verified separately.");
   }, components);
   configurationCheck("Antigravity / codex-bridge sidecar", () => {
-    assertEntry(readJson(path.join(paths.gemini, "sidecars", "codex-bridge", "sidecar.json")), "antigravity-sidecar.mjs", root);
-    if (readJson(path.join(paths.gemini, "config.json"))?.sidecars?.["codex-bridge"]?.enabled !== true) throw new Error("Antigravity sidecar is not enabled");
+    const details = assertEntry(readJson(path.join(paths.gemini, "sidecars", "codex-bridge", "sidecar.json")), "antigravity-sidecar.mjs", root);
+    const enabled = readJson(path.join(paths.gemini, "config.json"))?.sidecars?.["codex-bridge"]?.enabled;
+    if (typeof enabled !== "boolean") throw new Error("Antigravity sidecar enabled setting is missing or invalid");
+    if (!enabled) return { deliveryEnabled: false,
+      notices: [...(details?.notices ?? []), "The Antigravity bridge sidecar is intentionally disabled. Its saved choice was preserved; native Desktop delivery through this sidecar is disabled."] };
+    return details;
   }, components);
   if (native) configurationCheck("Native relay executor", () => {
     const relay = readJson(path.join(paths.codex, "native-relay.json"));
@@ -151,7 +165,7 @@ export function checkSetup({ env = process.env, platform = process.platform, roo
 
 export function runSetup({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
   const options = setupArguments(args);
-  if (options.help) return { help: "Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nGlobal npm installation configures Claude Desktop, Claude Code, Codex and Antigravity automatically. CODEX_BRIDGE_SKIP_SETUP=1 opts out." };
+  if (options.help) return { help: "Usage: codex-bridge-setup [--check|--dry-run] [--json] [--no-download]\nUpdate the package and apply managed settings with: npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge\nGlobal npm installation configures Claude Desktop, Claude Code, Codex and Antigravity automatically. CODEX_BRIDGE_SKIP_SETUP=1 opts out. Saved configuration and loaded app connections are verified separately." };
   if (options.postinstall && !automaticSetupEnabled(env)) return { skipped: true, reason: "Automatic configuration runs only for a global npm install; use codex-bridge-setup for manual setup." };
   if (options.check) return checkSetup({ env, platform, root, run, resolve });
   const native = platform === "win32" || platform === "darwin";
@@ -166,16 +180,18 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const install = (name, script, arguments_, environment = base) => {
     try {
       const output = run(process.execPath, [path.join(root, "scripts", script), ...arguments_], environment, 180000);
-      let notices = [];
-      try { notices = JSON.parse(output).notices ?? []; } catch {}
-      components.push({ name, status: "configured", ...(notices.length ? { notices } : {}) });
+      let details = {};
+      try { details = JSON.parse(output); } catch {}
+      const notices = details.notices ?? [];
+      components.push({ name, status: "configured", ...(notices.length ? { notices } : {}),
+        ...(details.backgroundPreference ? { backgroundPreference: details.backgroundPreference } : {}) });
       return true;
     } catch (error) { components.push({ name, status: "incomplete", detail: error.message }); return false; }
   };
-  const code = install(planned[0], "install-claude-code.mjs", ["--install", "--desktop-config", paths.desktop], {
+  const code = install(planned[0], "install-claude-code.mjs", ["--install", "--setup", "--desktop-config", paths.desktop], {
     ...base, CODEX_BRIDGE_DESKTOP_TASKS: native ? "1" : "0", CODEX_BRIDGE_AUTOSTART: native ? "0" : "1", CODEX_BRIDGE_THREAD_POLICY: "roots",
   });
-  if (code) install(planned[1], "install-claude-desktop.mjs", ["--entry-name", "codex-bridge-desktop", "--quiet"]);
+  if (code) install(planned[1], "install-claude-desktop.mjs", ["--entry-name", "codex-bridge-desktop", "--quiet", "--setup"]);
   if (native) {
     const relay = readJson(path.join(paths.codex, "native-relay.json"));
     install("Codex / codex-native-relay and executor", "install-native-relay.mjs", ["--setup", ...(relay?.desktopTasks === undefined ? ["--desktop-tasks"] : [])]);
@@ -185,20 +201,24 @@ export function runSetup({ args = [], env = process.env, platform = process.plat
   const inspection = checkSetup({ env: base, platform, root, run, resolve: () => runtime.binary });
   return { configured: components.every((item) => item.status === "configured") && inspection.configured, liveVerified: false,
     cliInstalled: runtime.installed, components, verification: inspection.components,
-    nextActions: ["Open or reconnect Claude, Codex and Antigravity after active work finishes so they load the new entries.",
-      "Use the same saved project in Claude Desktop Code and Codex Desktop. Keep the apps signed in.",
-      "Verify codex_bridge_status in Claude Code, native_relay_status in Codex, and agent_bridge_status in Antigravity. Shared Claude Desktop chat uses the local app-server route."] };
+    nextActions: ["Running MCP processes may still hold earlier settings. Setup does not start apps or open conversations.",
+      "Existing compatible supervisors reload installed source when idle; configuration changes are not proof of loaded-process readiness.",
+      "Native delivery uses the same saved project and signed-in accounts in Claude Desktop Code and Codex Desktop.",
+      "codex_bridge_status, native_relay_status and agent_bridge_status report live readiness separately from this configuration check."] };
 }
 
 export function printSetup(result, { json = false, output = console.log } = {}) {
   if (json) { output(JSON.stringify(result, null, 2)); return; }
   if (result.help) { output(result.help); return; }
   if (result.skipped) { output(result.reason); return; }
-  output(result.dryRun ? "Bridge setup preview (no changes)" : result.configured ? "Bridge configuration verified. Live connections still require the apps to load it." : "Bridge setup is incomplete. Fix the items below, then run codex-bridge-setup again.");
+  output(result.dryRun ? "Bridge setup preview (no changes)" : result.configured ? "Bridge configuration verified. Running app connections have not been verified." : "Bridge setup is incomplete. Fix the items below, then run codex-bridge-setup again.");
   for (const item of result.components ?? []) {
     output(`[${item.status}] ${item.name}${item.detail ? `: ${item.detail}` : ""}`);
     for (const notice of item.notices ?? []) output(`  ${notice}`);
   }
-  for (const item of result.verification ?? []) if (item.status !== "configured") output(`[${item.status}] ${item.name}: ${item.detail}`);
+  for (const item of result.verification ?? []) {
+    if (item.status !== "configured") output(`[${item.status}] ${item.name}: ${item.detail}`);
+    for (const notice of item.notices ?? []) output(`${item.name}: ${notice}`);
+  }
   for (const action of result.nextActions ?? []) output(action);
 }

package/src/thread-delivery.mjs

@@ -9,6 +9,7 @@ import { captureCodexRolloutWatermark, inspectCodexNativeTurn, readCodexNativeTu
 import { captureProjectScope, recheckProjectScope } from "./project-scope.mjs";
 import { isRolloutChangedDuringRead } from "./rollout-segments.mjs";
 import { requireClaudeSenderContext } from "./claude-sender-context.mjs";
+import { bridgeDiagnostic } from "./recipient-preflight.mjs";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -74,7 +75,7 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
   return matches[0];
 }
 
-export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening: Codex Desktop runs codex-native-relay only while a task has its MCP servers loaded. Open any regular project task (not the internal Native Relay executor task) and send it a turn or reconnect its MCP servers, then retry.";
+export const RELAY_DOWN_GUIDANCE = "The Codex Desktop native relay is not listening after waiting for silent recovery. Its Desktop-owned supervisor restarts crashed relay workers without replaying requests. An unloaded native host cannot be cold-started by this bridge. Inspect codex_bridge_status and include its diagnostic in a report. Never open an app or an old, new, empty or failed chat to load a relay.";
 
 function relayUnreachable(error) {
   return error?.code === "RELAY_UNREACHABLE" && error.sent === false;
@@ -126,23 +127,25 @@ export class DesktopTaskDelivery {
       if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
       const projectScope = expectedScope ?? await this.mutationProjectScope(operation, args, { deadline });
       if (expectedScope) recheckProjectScope(expectedScope, this.senderProjectScope(expectedScope.recipient.input));
-      const remaining = deadline === undefined ? undefined : deadline - this.now();
-      if (remaining !== undefined && remaining <= 0) throw Object.assign(new Error("The bridge's response deadline has elapsed; this operation was not sent"), { code: "DESKTOP_RESPONSE_DEADLINE" });
       const accountContext = this.accountContext?.();
-      const send = () => this.relay.requestDesktop(operation, args, {
-        ...(remaining === undefined ? {} : { timeoutMs: remaining }),
-        ...(this.beforeRequest || projectScope || scopeBinding ? { beforeSend: async () => {
-          await this.beforeRequest?.({ operation, args, phase: "write" });
-          if (projectScope) {
-            recheckProjectScope(projectScope);
-            recheckProjectScope(projectScope, await this.mutationProjectScope(operation, args, { deadline }));
-          }
-          await this.beforeRequest?.({ operation, args, phase: "dispatch" });
-          if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
-        } } : {}),
-        ...(accountContext ? { accountContext } : {}),
-        ...(creationReceiptId ? { creationReceiptId } : {}),
-      });
+      const send = () => {
+        const remaining = deadline === undefined ? undefined : deadline - this.now();
+        if (remaining !== undefined && remaining <= 0) throw Object.assign(new Error("The bridge's response deadline has elapsed; this operation was not sent"), { code: "DESKTOP_RESPONSE_DEADLINE" });
+        return this.relay.requestDesktop(operation, args, {
+          ...(remaining === undefined ? {} : { timeoutMs: remaining }),
+          ...(this.beforeRequest || projectScope || scopeBinding ? { beforeSend: async () => {
+            await this.beforeRequest?.({ operation, args, phase: "write" });
+            if (projectScope) {
+              recheckProjectScope(projectScope);
+              recheckProjectScope(projectScope, await this.mutationProjectScope(operation, args, { deadline }));
+            }
+            await this.beforeRequest?.({ operation, args, phase: "dispatch" });
+            if (scopeBinding) this.security.hardenedRoots.recheck(scopeBinding);
+          } } : {}),
+          ...(accountContext ? { accountContext } : {}),
+          ...(creationReceiptId ? { creationReceiptId } : {}),
+        });
+      };
       let response;
       try {
         response = await send();
@@ -194,13 +197,17 @@ export class DesktopTaskDelivery {
   async status() {
     const accountContext = this.accountContext?.();
     const socketPath = this.relay.status?.({ accountContext })?.socketPath ?? this.relay.socketPath;
-    if (this.accountContext && !accountContext) return { available: false, socketPath, reason: "The current Claude and Codex accounts could not both be verified. Finish signing in and inspect the account diagnostics before sending work." };
+    if (this.accountContext && !accountContext) {
+      const reason = "The current Claude and Codex accounts could not both be verified. Finish signing in and inspect the account diagnostics before sending work.";
+      return { available: false, socketPath, code: "BRIDGE_ACCOUNT_UNVERIFIED", reason, diagnostic: bridgeDiagnostic(new Error(reason), { component: "codex-bridge", operation: "codex_bridge_status", code: "BRIDGE_ACCOUNT_UNVERIFIED", readOnly: true }) };
+    }
     try {
       const response = await this.request("list_projects", {});
       if (!Array.isArray(response?.projects)) throw new Error("Desktop returned no project list");
       return { available: true, socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
     } catch (err) {
-      return { available: false, socketPath, reason: err.message };
+      const diagnostic = bridgeDiagnostic(err, { component: "codex-bridge", operation: "codex_bridge_status", readOnly: true });
+      return { available: false, socketPath, code: diagnostic.code, reason: err.message, diagnostic };
     }
   }
 
@@ -334,11 +341,11 @@ export class DesktopTaskDelivery {
         const confirmedId = response?.threadId ?? response?.conversationId;
         threadId = confirmedId;
         if (!threadId && (response?.status === "outcome-unknown" || response?.firstTurn?.status === "outcome-unknown")) threadId = response?.clientThreadId;
-        if (typeof confirmedId !== "string" || !confirmedId.trim() || response?.status === "outcome-unknown" || response.hostId !== "local") throw new Error(`Desktop creation is not confirmed: ${JSON.stringify(response)}`);
+        if (typeof confirmedId !== "string" || !confirmedId.trim() || response?.status === "outcome-unknown" || response.hostId !== "local") throw Object.assign(new Error("Desktop creation is not confirmed; inspect the original native receipt."), { code: "CODEX_CREATION_UNCONFIRMED", deliveryState: "unknown", phase: "creation" });
         await this.receipts.write(identity.key, { ...receipt, state: "known", threadId });
         creationConfirmed = true;
         this.security.registerThread(threadId);
-        if (response.firstTurn && response.firstTurn.status !== "accepted") throw new Error(`Desktop created task ${threadId}; its first turn reports ${response.firstTurn.status ?? "an unconfirmed state"}: ${JSON.stringify(response)}`);
+        if (response.firstTurn && response.firstTurn.status !== "accepted") throw Object.assign(new Error(`Desktop created task ${threadId}; its first turn reports ${["failed", "waitingOnApproval", "waitingOnUserInput", "outcome-unknown"].includes(response.firstTurn.status) ? response.firstTurn.status : "an unconfirmed state"}. Inspect the original native receipt.`), { code: "CODEX_FIRST_TURN_NOT_ACCEPTED", deliveryState: "sent", phase: "first_turn" });
         const created = { threadId, name, cwd, projectId: project.projectId, projectName: project.label, backend: NATIVE_BACKEND };
         const delivered = { ...created, previousTurnId: null, deliveryStatus: "accepted", responseObservation: {
             operation: "create_thread", threadId, previousTurnId: null, expectedCwd: cwd,