@minhspark/codex-mcp-bridge 1.24.0 → 1.25.0

package/src/peer-protocol.mjs

@@ -875,9 +875,7 @@ export class PeerEndpoint {
       this.log(`ignored uncorrelated inbound peer message from ${message.fromSocket ?? "?"} in hardened mode`);
       return;
     }
-    this.activityRevision += 1;
-    const record = { ...message, receivedAt: Date.now(), sequence: ++this.messageSequence };
-    this.inbox.push(record);
+    const record = { ...message };
     if (key && correlated && pending.targetSocket === record.fromSocket) {
       const sent = this.sentMessages.get(key);
       if (sent) {
@@ -891,6 +889,13 @@ export class PeerEndpoint {
       }
       this.#removePendingReply(record.fromSocket, key);
     }
+    this.#publishMessage(record);
+  }
+
+  #publishMessage(record) {
+    this.activityRevision += 1;
+    Object.assign(record, { receivedAt: Date.now(), sequence: ++this.messageSequence });
+    this.inbox.push(record);
     this.log(`inbox <- ${record.fromSocket ?? "?"}: ${record.text.length} characters`);
     for (const listener of [...this.listeners]) {
       try { listener(record); }
@@ -911,9 +916,22 @@ export class PeerEndpoint {
       const outcome = readTranscriptOutcome(sessionId, cwd, msgId);
       if (outcome?.reply) this.#receiveMessage({ ...outcome.reply, fromSocket: pending.targetSocket });
       else if (outcome?.status === "interrupted") {
-        this.activityRevision += 1;
         this.deliveryReceipts.set(msgId, { ...outcome, fromSocket: pending.targetSocket, observedAt: Date.now() });
         this.#removePendingReply(pending.targetSocket, msgId);
+        const sent = this.sentMessages.get(msgId);
+        // A terminal observation is a bridge notification, never a Claude reply.
+        // Retain the send's original routing and scope for inbox filtering and
+        // forwarding; do not infer either from the currently active task.
+        this.#publishMessage({
+          kind: "delivery_status", source: "bridge", status: "interrupted",
+          msgId: `interrupted:${msgId}`, inReplyTo: msgId, fromSocket: pending.targetSocket,
+          replyThreadId: sent?.replyThreadId ?? null, accountContext: sent?.accountContext ?? null,
+          cwd: sent?.transcriptSession?.cwd ?? null, senderCwd: sent?.scopeBindings?.sender?.path ?? null,
+          scopeBindings: sent?.scopeBindings ?? null,
+          outcome: "unknown", waitEnded: true, taskCancelled: false, retrySafe: false,
+          reasonCode: outcome.reasonCode, interruptedBy: outcome.interruptedBy, backgroundTaskIds: outcome.backgroundTaskIds,
+          text: `[Bridge delivery status: ${outcome.reasonCode}]\nMessage id: ${msgId}\n${outcome.reason}`,
+        });
         this.log(`reply observation interrupted for ${msgId}; task outcome remains unknown`);
       }
     }
@@ -1096,7 +1114,7 @@ export class PeerEndpoint {
    */
   waitForReply(fromSocket, { timeoutMs = 120000, since = Date.now(), afterSequence = null, msgId } = {}) {
     const expectsTranscript = Boolean(msgId && this.sentMessages.get(msgId)?.transcriptSession);
-    const matches = (record) => record.fromSocket === fromSocket
+    const matches = (record) => record.kind !== "delivery_status" && record.fromSocket === fromSocket
       && (!expectsTranscript || (record.source === "transcript" && record.inReplyTo === msgId))
       && (!record.inReplyTo || !msgId || record.inReplyTo === msgId)
       && (afterSequence === null ? record.receivedAt >= since : record.sequence > afterSequence);

package/src/platform.mjs

@@ -1,5 +1,6 @@
 import { execFile, execFileSync } from "node:child_process";
 import { accessSync, constants, existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -168,16 +169,67 @@ function pathCandidates() {
  * ~/.local/bin, ~/.npm-global/bin or Homebrew. Probe every known install
  * location for the running platform before giving up on PATH resolution.
  */
-export function resolveCodexBin(explicit) {
+export function resolvePackagedCodexBin({
+  platform = process.platform,
+  arch = process.arch,
+  resolvePackage = (specifier, from) => createRequire(from).resolve(specifier),
+  exists = isRunnable,
+} = {}) {
+  const packagePlatform = platform === "android" ? "linux" : platform;
+  const target = {
+    "linux-x64": "x86_64-unknown-linux-musl",
+    "linux-arm64": "aarch64-unknown-linux-musl",
+    "darwin-x64": "x86_64-apple-darwin",
+    "darwin-arm64": "aarch64-apple-darwin",
+    "win32-x64": "x86_64-pc-windows-msvc",
+    "win32-arm64": "aarch64-pc-windows-msvc",
+  }[`${packagePlatform}-${arch}`];
+  if (!target) return null;
+
+  let codexManifest;
+  try { codexManifest = resolvePackage("@openai/codex/package.json", import.meta.url); } catch {}
+  if (typeof codexManifest !== "string" || !path.isAbsolute(codexManifest)) codexManifest = null;
+  const packageName = `@openai/codex-${packagePlatform}-${arch}/package.json`;
+  const roots = [];
+  for (const anchor of [codexManifest, import.meta.url].filter(Boolean)) {
+    try {
+      const manifest = resolvePackage(packageName, anchor);
+      if (typeof manifest === "string" && path.isAbsolute(manifest)) roots.push(path.dirname(manifest));
+    } catch {}
+  }
+  if (codexManifest) roots.push(path.dirname(codexManifest));
+  for (const root of new Set(roots)) {
+    const candidate = path.join(root, "vendor", target, "bin", platform === "win32" ? "codex.exe" : "codex");
+    if (exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function resolveCodexBin(explicit, {
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  candidates: discovered,
+  runnable = isRunnable,
+  packaged = resolvePackagedCodexBin,
+} = {}) {
   const candidates = [
     explicit,
-    process.env.CODEX_BIN,
-    ...(IS_WINDOWS ? windowsCodexCandidates() : IS_MACOS ? macosCodexCandidates() : unixCodexCandidates()),
-    ...pathCandidates(),
+    env.CODEX_BIN,
+    ...(discovered ?? [
+      ...(IS_WINDOWS ? windowsCodexCandidates() : IS_MACOS ? macosCodexCandidates() : unixCodexCandidates()),
+      ...pathCandidates(),
+    ]),
   ].filter(Boolean);
 
+  const deferredShim = (candidate) => platform === "win32" && /\.(?:cmd|bat)$/i.test(candidate);
+  for (const candidate of candidates) {
+    if (!deferredShim(candidate) && runnable(candidate)) return candidate;
+  }
+  const bundled = packaged({ platform, arch });
+  if (bundled) return bundled;
   for (const candidate of candidates) {
-    if (isRunnable(candidate)) return candidate;
+    if (deferredShim(candidate) && runnable(candidate)) return candidate;
   }
   return "codex";
 }

package/src/setup.mjs

@@ -0,0 +1,204 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { resolveCodexBin, resolvePackagedCodexBin } from "./platform.mjs";
+import { readRegularConfigFile } from "./project-policy.mjs";
+import { stableInstallPath } from "./install-paths.mjs";
+import { resolveClaudeDesktopConfigRoot } from "./desktop-account-context.mjs";
+
+const ROOT = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
+const CODEX_PACKAGE = "@openai/codex@0.166.0";
+const MAX_CONFIG = 16 * 1024 * 1024;
+
+export function setupArguments(args) {
+  const allowed = new Set(["--postinstall", "--check", "--dry-run", "--json", "--no-download", "--help"]);
+  if (args.some((arg) => !allowed.has(arg))) throw new Error("Unknown setup option; use codex-bridge-setup --help");
+  if (args.includes("--check") && args.includes("--dry-run")) throw new Error("Use --check or --dry-run, not both");
+  return Object.fromEntries([...allowed].map((arg) => [arg.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()), args.includes(arg)]));
+}
+
+export function automaticSetupEnabled(env = process.env) {
+  return env.npm_config_global === "true" && env.CODEX_BRIDGE_SKIP_SETUP !== "1";
+}
+
+export function setupPaths(env = process.env, platform = process.platform) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const codeDirectory = env.CLAUDE_CONFIG_DIR || home;
+  const configRoot = env.XDG_CONFIG_HOME || path.join(home, ".config");
+  const desktop = env.CLAUDE_DESKTOP_CONFIG || path.join(resolveClaudeDesktopConfigRoot({ env, platform }), "claude_desktop_config.json");
+  return { home, code: path.join(codeDirectory, ".claude.json"), desktop,
+    codex: env.CODEX_HOME || path.join(home, ".codex"),
+    gemini: path.join(home, ".gemini", "config"), tools: path.join(configRoot, "GptClaudeBridge", "tools") };
+}
+
+function readJson(file) {
+  const text = readRegularConfigFile(file, { missing: true, maxBytes: MAX_CONFIG });
+  if (text === null) return null;
+  const value = JSON.parse(text.replace(/^\uFEFF/, ""));
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Expected a JSON object: ${file}`);
+  return value;
+}
+
+function execute(command, args, env, timeout = 120000) {
+  const result = spawnSync(command, args, { env, encoding: "utf8", windowsHide: true, shell: false, timeout,
+    maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  if (result.error || result.status !== 0) {
+    const lines = String(result.stderr || "").split(/\r?\n/).filter((line) => /^Error:|^(?:Expected|Refusing|Invalid|Unknown|Shared|Claude|Codex|Configuration|The existing|Missing|Unsafe)/.test(line)
+      && !/Command failed|--env|password|secret|token|authorization/i.test(line));
+    const detail = lines.slice(0, 3).join(" ") || result.error?.code || `exit ${result.status}`;
+    throw new Error(`${path.basename(command)} ${path.basename(args[0] ?? "")}: ${detail}`);
+  }
+  return result.stdout || "";
+}
+
+function usableBinary(binary, platform) {
+  return typeof binary === "string" && path.isAbsolute(binary) && fs.existsSync(binary)
+    && fs.statSync(binary).isFile() && (platform !== "win32" || /\.(exe|com)$/i.test(binary));
+}
+
+function managedBinary(paths, platform) {
+  return resolvePackagedCodexBin({ platform, resolvePackage: (specifier, from) => createRequire(
+    specifier === "@openai/codex/package.json" ? path.join(paths.tools, "package.json") : from,
+  ).resolve(specifier) });
+}
+
+export function ensureSetupCodex({ env, paths, platform, download = true, run = execute, resolve = resolveCodexBin }) {
+  const existing = resolve(env.CODEX_EXE, { env, platform });
+  if (usableBinary(existing, platform)) return { binary: existing, installed: false };
+  const managed = managedBinary(paths, platform);
+  if (usableBinary(managed, platform)) return { binary: managed, installed: false };
+  if (!download) throw new Error("Codex CLI was not found. Rerun setup without --no-download to install it automatically.");
+  const candidates = [env.npm_execpath, path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")];
+  const npm = candidates.find((file) => file && path.isAbsolute(file) && fs.existsSync(file) && /(?:npm-cli|npm)\.js$/i.test(file));
+  if (!npm) throw new Error("Codex CLI is missing and npm could not be located. Rerun the global npm install command to finish setup.");
+  fs.mkdirSync(paths.tools, { recursive: true, mode: 0o700 });
+  run(process.execPath, [npm, "install", "--global=false", "--prefix", paths.tools, "--ignore-scripts", "--no-audit", "--no-fund", "--no-package-lock", "--no-save", CODEX_PACKAGE],
+    { ...env, npm_config_global: "false", CODEX_BRIDGE_SKIP_SETUP: "1" }, 180000);
+  const binary = managedBinary(paths, platform);
+  if (!usableBinary(binary, platform)) throw new Error("The Codex CLI download did not provide a supported native executable. Check npm optional dependencies and rerun setup.");
+  return { binary, installed: true };
+}
+
+export function setupEnvironment(env, paths, codex) {
+  const result = Object.fromEntries(Object.entries(env).filter(([name]) => !/^(?:CODEX_BRIDGE_|CLAUDE_BRIDGE_|CODEX_NATIVE_RELAY_|CODEX_RELAY_ID$|CODEX_THREAD_ID$|CODEX_APP_TOOLS_PIPE_PATH$)/.test(name)));
+  return { ...result, HOME: paths.home, USERPROFILE: paths.home, CODEX_HOME: paths.codex,
+    CLAUDE_DESKTOP_CONFIG: paths.desktop, CODEX_EXE: codex, CODEX_BIN: codex };
+}
+
+function configurationCheck(label, check, components) {
+  try { check(); components.push({ name: label, status: "configured" }); }
+  catch (error) { components.push({ name: label, status: "incomplete", detail: error.message }); }
+}
+
+function assertEntry(entry, worker, root, { caller } = {}) {
+  if (!entry || typeof entry.command !== "string" || !fs.existsSync(entry.command)) throw new Error("MCP command is missing or unavailable");
+  const args = entry.args ?? [];
+  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");
+}
+
+export function checkSetup({ env = process.env, platform = process.platform, root = ROOT, run = execute, resolve = resolveCodexBin } = {}) {
+  const paths = setupPaths(env, platform);
+  const components = [];
+  let codex;
+  let inventory;
+  configurationCheck("Codex CLI", () => {
+    codex = ensureSetupCodex({ env, paths, platform, download: false, run, resolve }).binary;
+    inventory = JSON.parse(run(codex, ["mcp", "list", "--json"], setupEnvironment(env, paths, codex), 30000));
+    if (!Array.isArray(inventory)) throw new Error("Codex returned an invalid MCP inventory");
+  }, components);
+  const native = platform === "win32" || platform === "darwin";
+  for (const [name, worker] of [["claude-bridge", "claude-bridge.mjs"], ...(native ? [["codex-native-relay", "native-relay-companion.mjs"]] : []), ["antigravity-bridge", "antigravity-bridge.mjs"]]) {
+    configurationCheck(`Codex / ${name}`, () => {
+      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" } : {});
+      if (name === "codex-native-relay" && !entry.transport.env_vars?.includes("CODEX_APP_TOOLS_PIPE_PATH")) throw new Error("Native pipe forwarding is missing");
+    }, components);
+  }
+  for (const [label, file, name, worker, caller] of [
+    ["Claude Code / codex-bridge", paths.code, "codex-bridge", "index.mjs"],
+    ["Claude Desktop / codex-bridge-desktop", paths.desktop, "codex-bridge-desktop", "index.mjs"],
+    ["Claude Code / antigravity-bridge", paths.code, "antigravity-bridge", "antigravity-bridge.mjs", "claude"],
+    ["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 });
+    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.");
+    }
+  }, 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");
+  }, components);
+  if (native) configurationCheck("Native relay executor", () => {
+    const relay = readJson(path.join(paths.codex, "native-relay.json"));
+    if (!relay?.relayThreadId) throw new Error("Native relay executor has not been initialized");
+  }, components);
+  configurationCheck("Claude registration names", () => {
+    if (readJson(paths.desktop)?.mcpServers?.["codex-bridge"]) throw new Error("Shared codex-bridge shadows the Claude Code registration");
+  }, components);
+  return { configured: components.every((item) => item.status === "configured"), liveVerified: false, components };
+}
+
+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.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";
+  const paths = setupPaths(env, platform);
+  const planned = ["Claude Code / codex-bridge", "Claude Desktop / codex-bridge-desktop", ...(native ? ["Codex / codex-native-relay and executor"] : []), "Codex / claude-bridge", "Antigravity / all components"];
+  if (options.dryRun) return { dryRun: true, configured: false, liveVerified: false, components: planned.map((name) => ({ name, status: "planned" })), files: [paths.code, paths.desktop, path.join(paths.codex, "config.toml"), paths.gemini] };
+  if (env.SUDO_USER && env.SUDO_USER !== "root" && typeof process.getuid === "function" && process.getuid() === 0) throw new Error("Run the global install without sudo in the account that runs the apps; setup will not write another account's configuration.");
+  const runtime = ensureSetupCodex({ env, paths, platform, download: !options.noDownload, run, resolve });
+  fs.mkdirSync(paths.codex, { recursive: true, mode: 0o700 });
+  const base = setupEnvironment(env, paths, runtime.binary);
+  const components = [];
+  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 } : {}) });
+      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], {
+    ...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 (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"] : [])]);
+  }
+  install("Codex / claude-bridge", "install-codex-mcp.mjs", ["--setup"]);
+  if (code) install("Antigravity / all components", "install-antigravity-bridge.mjs", ["--all", "--setup"]);
+  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."] };
+}
+
+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.");
+  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 action of result.nextActions ?? []) output(action);
+}

package/src/thread-delivery.mjs

@@ -27,9 +27,11 @@ 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 OBSERVATION_UNAVAILABLE_GUIDANCE = "The response could not be verified; this does not establish that delivery or the task failed. Inspect the existing task and this receipt; do not resend the prompt.";
 export const WORKSPACE_UNASSIGNED = "DESKTOP_WORKSPACE_UNASSIGNED";
 export const UNASSIGNED_WORKSPACE_GRACE_MS = 120000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
+const UNMATCHED_REPLY_GRACE_MS = 3000;
 const METADATA_READ_OPTIONS = { includeOutputs: false, maxOutputCharsPerItem: 1 };
 
 function unavailableWaitRenderer(error) {
@@ -572,6 +574,7 @@ export class DesktopTaskDelivery {
     let readSnapshots = false;
     let deferredReason = null;
     let deferredTurn = null;
+    let unmatchedTerminal = null;
     const readSnapshot = async () => {
       const result = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline: startedAt + timeoutMs });
       const thread = result?.thread;
@@ -614,6 +617,7 @@ export class DesktopTaskDelivery {
       } catch (err) {
         if (deadlineError(err)) return expired();
         if (err.code === WORKSPACE_UNASSIGNED) {
+          unmatchedTerminal = null;
           await pause();
           continue;
         }
@@ -639,13 +643,15 @@ export class DesktopTaskDelivery {
         const observed = await observe(null, true);
         if (!observed) return expired();
         if (observed === observeLater) {
+          unmatchedTerminal = null;
           await pause();
           continue;
         }
         turnId = observed.turnId ?? null;
         if (observed.status !== "pending") {
+          const nativeFailure = turnId && turn?.id === turnId && ["failed", "interrupted"].includes(turn.status) ? turn.status : null;
           return {
-            threadId, turnId, status: observed.status === "unavailable" ? "failed" : "completed",
+            threadId, turnId, status: observed.status === "unavailable" ? nativeFailure ?? "observation_unavailable" : "completed",
             responseStatus: observed.status, observationStatus: observed.status,
             text: observed.status === "completed" ? observed.text : "",
             ...(observed.reason ? { observationReason: observed.reason } : {}),
@@ -656,6 +662,34 @@ export class DesktopTaskDelivery {
           };
         }
         if (needsAttention) return attention();
+        if (turnId === null && observed.dispatchObserved !== true && threadStatus === "idle" &&
+            typeof turn?.id === "string" && turn.id && turn.id !== previousTurnId && RELEASE_STATUSES.has(turn.status)) {
+          if (unmatchedTerminal?.id !== turn.id || unmatchedTerminal.status !== turn.status) {
+            unmatchedTerminal = { id: turn.id, status: turn.status, since: this.now(), polls: 1 };
+          } else unmatchedTerminal.polls++;
+          if (unmatchedTerminal.polls >= 3 && this.now() - unmatchedTerminal.since >= UNMATCHED_REPLY_GRACE_MS) {
+            let snapshot;
+            try { snapshot = (await readSnapshot()).polls[0]; }
+            catch (error) {
+              if (deadlineError(error)) return expired();
+              if (error.code === WORKSPACE_UNASSIGNED) {
+                unmatchedTerminal = null;
+                await pause();
+                continue;
+              }
+              throw error;
+            }
+            const status = typeof snapshot.thread.status === "string" ? snapshot.thread.status : snapshot.thread.status?.type;
+            if (status === "idle" && snapshot.latestTurn?.id === unmatchedTerminal.id && snapshot.latestTurn.status === unmatchedTerminal.status) {
+              return {
+                threadId, turnId: null, status: "observation_unavailable", responseStatus: "unavailable", observationStatus: "unavailable",
+                observationReason: "Codex Desktop reports an idle task, but its latest finished turn could not be correlated to this delivery after the rollout grace period. Inspect the existing task and receipt; do not resend the prompt.",
+                text: "", assistantItems: [], replySha256: null, responseSource: null, activity: [], errors: [], durationMs: this.now() - startedAt,
+              };
+            }
+            unmatchedTerminal = null;
+          }
+        } else unmatchedTerminal = null;
         if (this.now() - startedAt >= timeoutMs) return expired();
         await this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
         continue;