@minhspark/codex-mcp-bridge 1.13.0 → 1.13.2

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.13.2] - 2026-09-05
+
+### Fixed
+
+- Prevent duplicate Desktop tasks across concurrent MCP processes and restarts with durable creation receipts. The same workspace and explicit title reuse the verified existing task even after completion or an edited brief; continuations remain explicit sends to its ID.
+- Bound the entire Desktop tool call to 40 seconds, including creation, opening, observation, and queued sends. Expired queued prompts are never sent later, and an accepted task keeps running with its ID available to the caller.
+- Preserve confirmed task IDs when the first turn fails or needs attention; block uncertain creation retries without automatically expiring receipts or abandoned locks. Reusing a receipt cannot expand thread authorization.
+- Keep project selection restricted to exact existing local projects. Explain that Desktop's recent-task snapshot can omit visible agent-created tasks, so absence is not evidence that a retry should create another one.
+
+### Verification
+
+- Windows suite: 322 passed, 0 failed, 8 platform-specific skips. Includes real concurrent MCP processes, restart reuse, lost acknowledgements, persisted receipt validation, strict owned-policy checks, and call deadlines.
+- Archived two completed duplicate tasks and retained the latest task in its existing project. A direct native read verified its exact workspace before recording the existing creation receipt.
+
+## [1.13.1] - 2026-09-05
+
+### Fixed
+
+- Make Desktop task mode independent of the external app-server for status, thread discovery, diagnostics, and fallback delivery. A missing native relay reports an actionable failure without starting another process or taking a task's writer lock.
+- Verify native connectivity through Desktop projects and list its authorized local recent/pinned Codex tasks. Explain the snapshot coverage and reject unsupported `loadedOnly` queries instead of returning external-server state.
+- Persist external autostart off when installing Claude Desktop in Desktop task mode, while preserving explicit legacy mode and existing permission settings. Reconnect the native companion after upgrading to enable the new allowlisted thread-list operation.
+
+### Verification
+
+- Windows suite: 300 passed, 0 failed, 8 platform-specific skips. Added absent-relay, zero-external-connection, native-list authorization, and overlapping-send regressions.
+- Live Windows checks returned bridge 1.13.1, eight native local projects, recent Desktop tasks, and an existing task's history while port 8791 remained stopped.
+
 ## [1.13.0] - 2026-09-05
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ The bridge preserves task history and working directories across messages. Enabl
 
 ### Visible tasks in the correct Desktop project
 
-Install the native companion, add the exact checkout directory as a local project in Codex Desktop, and enable Desktop task delivery:
+Install the native companion, choose an existing local project in Codex Desktop, and enable Desktop task delivery:
 
 ```bash
 codex-native-relay-install --desktop-tasks
@@ -20,11 +20,19 @@ codex-native-relay-install --desktop-tasks
 
 Reload the native companion and the Claude MCP client after upgrading. The installer stores the opt-in in the existing `~/.codex/native-relay.json`; `CODEX_BRIDGE_DESKTOP_TASKS=1` also enables it, and an explicit `0` overrides the shared setting. Desktop mode uses **Codex Desktop permissions**, while the bridge's workspace and thread authorization checks still apply. Existing installations keep their app-server permission settings unless they opt in.
 
-Call `delegate_to_codex` with `cwd`, `prompt`, and optionally `name`. The bridge resolves the real directory, selects the saved local project with that exact path, starts in its existing checkout, and opens the task immediately while it runs. `openInApp: false` suppresses page navigation; project assignment still happens. It never selects a parent directory, remote namesake, or a new worktree. An unsaved worktree must first be saved as its own local project; missing or ambiguous project matches return an error before creating a task.
+Call `delegate_to_codex` with `cwd`, `prompt`, and optionally `name`. The bridge resolves the real directory, selects the saved local project with that exact path, starts in its existing checkout, and opens the task immediately while it runs. `openInApp: false` suppresses page navigation; project assignment still happens. It never creates projects or selects a parent directory, remote namesake, or a new worktree. Missing or ambiguous project matches return an error before creation; choose an existing project's directory or continue a task already in the requested workspace.
 
 `start_codex_thread` requires `prompt` in Desktop mode and returns after acceptance. Use `delegate_to_codex` to also wait for the reply. `send_to_codex_thread` continues the existing Desktop task without attaching another writer; its cwd cannot be changed. On timeout, the task continues. Inspect it in Desktop and use its Stop button to interrupt it. Quota failures and approval/input requests remain visible; delivery does not bypass them. An uncertain creation or send is never automatically repeated through another backend.
 
-The updated companion exposes a separate `-desktop-tasks` endpoint so a previous companion holding the legacy reply socket need not be killed during an upgrade. `codex_bridge_status` reports the selected mode; `native_relay_status` reports both endpoints.
+Desktop calls share a maximum 40-second budget across creation, opening, queueing, and observation, so a slow task returns its confirmed ID before the caller's usual 60-second timeout. The task keeps running in Desktop. If creation itself cannot be confirmed, the bridge reports uncertainty and blocks another creation instead of inventing an ID.
+
+Creation receipts persist in `$CODEX_HOME/bridge-task-receipts` (default `~/.codex/bridge-task-receipts`). The same canonical workspace and explicit title reuse the existing task, including after completion or a bridge restart; an edited brief is not resent. Use `send_to_codex_thread` to continue it, or a distinct title for separate work. Without an explicit title, the key uses the exact prompt hash. Receipts store hashes rather than prompt text and never grant thread permissions: `owned` policy still requires authorization after restart. Pending or uncertain receipts and abandoned creation locks fail closed without automatic expiry; inspect the actual task before repairing them.
+
+The updated companion exposes a separate `-desktop-tasks` endpoint so a previous companion holding the legacy reply socket need not be killed during an upgrade. `codex_bridge_status` verifies the native connection through Desktop's local project list; `native_relay_status` reports both endpoints. Reconnect the companion after upgrading so it accepts the current native operations.
+
+Desktop mode never contacts, starts, or falls back to an external app-server, including during status checks and thread discovery. The Claude Desktop installer records `CODEX_BRIDGE_AUTOSTART=0` in this mode. If Desktop or its companion is unavailable, the bridge reports the failure and leaves existing tasks in Desktop. `stop_codex_app_server` is a no-op in Desktop mode; stop an obsolete external service through its own launcher after confirming it has no active work.
+
+`list_codex_threads` filters Desktop's recent/pinned task snapshot by authorization, workspace/title, and result limit. The snapshot can omit agent-created tasks visible in the sidebar and does not cover the complete archive. Absence from this list does not mean creation failed: read the returned task ID directly. Desktop does not expose the external server's `loadedOnly` state; requesting it returns an explanation without contacting that server.
 
 ## Architecture
 
@@ -46,7 +54,7 @@ both bridges ───────┤ named pipe / unix socket
                      └────────────────────────────────────────────────────────────────────┘
 ```
 
-- The app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits.
+- In app-server mode, the app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; with autostart enabled, if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits. Desktop mode does not use this path.
 - Every client pointed at the same URL shares **one app-server**, so `thread/resume` with a `threadId` rejoins the running thread instead of opening a new session.
 - The bridge keeps exactly one WebSocket, calls `initialize` once, and routes notifications by `threadId`, so parallel threads never bleed into each other.
 - In app-server mode, `delegate_to_codex` starts the thread at the supplied `cwd`, names it, sends the prompt, and unsubscribes that thread after a terminal turn. It opens `codex://threads/<id>` only after unload is confirmed; other threads on the shared app-server keep running. Desktop mode instead creates and assigns the task through the app immediately.
@@ -314,7 +322,7 @@ On macOS and Linux the `codex` launcher is a Node script with a `#!/usr/bin/env
 |---|---|---|
 | `delegate_to_codex` | Creates a named Codex thread at the requested project `cwd`, sends Claude's prompt, returns the reply, releases the bridge writer lock, and opens the exact session in Codex Desktop when enabled. | destructive |
 | `send_to_codex_thread` | Sends a prompt as a user turn into `threadId`, waits for `turn/completed`, returns Codex's reply plus an activity trail (commands run, files changed). | destructive |
-| `list_codex_threads` | Lists threads (id, title, cwd, last update, status) so you can pick the **exact** `threadId`. `loadedOnly: true` shows only threads live inside the app-server. Windows and macOS rows carry a `codex://threads/<id>` deep link. | read-only |
+| `list_codex_threads` | Lists threads (id, title, cwd, last update, status) so you can pick the **exact** `threadId`. Desktop mode uses recent/pinned authorized local tasks; app-server mode supports `loadedOnly: true`. Windows and macOS rows carry a `codex://threads/<id>` deep link. | read-only |
 | `start_codex_thread` | Opens a new Codex thread at a permitted `cwd`, optionally names it, and returns its `threadId`; the bridge applies its configured safe sandbox and approval policy. | writes |
 | `read_codex_thread` | Reads the recent conversation without sending anything. | read-only |
 | `interrupt_codex_turn` | Stops a turn that is still running. | destructive |
@@ -506,7 +514,7 @@ python3 -c "import json;[print(v['properties']['method'].get('const') or v['prop
 
 A path counts as coming from elsewhere when it names a drive letter (`D:\project`), a UNC share (`\\server\share\project`), or an attached volume (`/Volumes/<label>/project`, `/mnt/<label>/project`, `/media/<user>/<label>/project`). No particular letter, share, or label is blessed, so any dual-boot or external-disk layout works without configuration. The bridge then looks for that project under `$HOME`, then under **its own parent directory** — a bridge checked out at `~/code/codex-mcp-bridge` makes `~/code` the obvious place to find a sibling project. Override the list with `CODEX_BRIDGE_WORKSPACE_ROOTS`, provide deterministic source/target pairs with `CODEX_BRIDGE_PATH_MAP='{"L:\\project":"C:\\project"}'`, or set `CODEX_BRIDGE_REMAP=0` to switch heuristic rewriting off entirely.
 
-Note: Codex Desktop does **not** group threads by directory — the sidebar has `Pinned` and everything else, and the protocol exposes no API to file a thread under a section (`thread/start` takes no `sectionId`; `thread/metadata/update` only patches gitInfo). What ties a thread to a project is its `cwd`.
+Desktop task mode assigns tasks to the existing saved project through Desktop's native API. The separate app-server protocol does not provide that project assignment; a thread's `cwd` alone is not evidence that it appears under the expected Desktop project.
 
 **Connection errors or a silent stall on the first call after rebooting.** The app-server does not survive a restart, so the first call after boot has to bring it back. Since 1.5.0 `connect()` retries once for boot-time transients, `onclose` only tears down its own socket (a late close from the previous one used to wipe the freshly established connection), and **a turn interrupted by a dropped connection ends immediately with status `disconnected`** instead of waiting out `timeoutSec` (240s by default). Verify with `npm test`. No LaunchAgent is needed for this — the bridge spawns an app-server on demand, and running a LaunchAgent alongside Codex Desktop only contends for the `~/.codex` state.
 
@@ -520,7 +528,7 @@ The bridge reads these from the environment its MCP client hands it — there is
 |---|---|---|
 | `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:8791` | Shared **loopback-only** app-server endpoint. Non-loopback endpoints are rejected because this bridge does not implement remote WebSocket authentication. |
 | `CODEX_BIN` | auto-detected | Path to `codex` used for autostart. |
-| `CODEX_BRIDGE_AUTOSTART` | `1` | `0` = never spawn an app-server; one must already be running. |
+| `CODEX_BRIDGE_AUTOSTART` | `1` in app-server mode | `0` = never spawn an external app-server. Always off in Desktop mode, which does not need one. |
 | `CODEX_BRIDGE_THREAD_POLICY` | `owned` in the direct server; installer writes `roots` for new v1.11.2 entries | What authorizes a thread: `owned` (created by this bridge, or listed in `CODEX_BRIDGE_ALLOWED_THREADS`) or `roots` (working inside `CODEX_BRIDGE_ALLOWED_ROOTS`). Existing config values are preserved on upgrade. |
 | `CODEX_BRIDGE_ALLOWED_THREADS` | empty | Exact comma-separated thread IDs permitted for read/send/interrupt/open/list; `*` explicitly permits every thread ID. Under `roots`, the workspace check still runs. |
 | `CODEX_BRIDGE_ALLOWED_ROOTS` | `*` in the v1.11.2 installer | Absolute project directories permitted for `cwd`, separated by `:` (`;` on Windows); `*` means every usable workspace. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",

package/scripts/install-claude-desktop.mjs

@@ -50,6 +50,7 @@ cfg.mcpServers = cfg.mcpServers ?? {};
  */
 const previousEnv = (reset ? {} : cfg.mcpServers["codex-bridge"]?.env) ?? {};
 const settled = (name, fallback) => process.env[name] ?? previousEnv[name] ?? fallback;
+const desktopMode = settled("CODEX_BRIDGE_DESKTOP_TASKS", desktopTasksConfigured() ? "1" : "0");
 
 const kept = Object.keys(previousEnv).filter(
   (name) => process.env[name] === undefined && name !== "CODEX_BIN",
@@ -86,7 +87,8 @@ cfg.mcpServers["codex-bridge"] = {
     CODEX_BRIDGE_SANDBOX: settled("CODEX_BRIDGE_SANDBOX", "workspace-write"),
     CODEX_BRIDGE_OPEN_IN_APP: settled("CODEX_BRIDGE_OPEN_IN_APP", IS_WINDOWS ? "1" : "0"),
     CODEX_BRIDGE_RELEASE_AFTER_TURN: settled("CODEX_BRIDGE_RELEASE_AFTER_TURN", IS_WINDOWS ? "1" : "0"),
-    CODEX_BRIDGE_DESKTOP_TASKS: settled("CODEX_BRIDGE_DESKTOP_TASKS", desktopTasksConfigured() ? "1" : "0"),
+    CODEX_BRIDGE_DESKTOP_TASKS: desktopMode,
+    CODEX_BRIDGE_AUTOSTART: desktopMode === "1" ? "0" : settled("CODEX_BRIDGE_AUTOSTART", "1"),
     ...(process.env.CODEX_BRIDGE_ALLOWED_THREADS !== undefined
       ? { CODEX_BRIDGE_ALLOWED_THREADS: process.env.CODEX_BRIDGE_ALLOWED_THREADS }
       : {}),

package/scripts/install-native-relay.mjs

@@ -8,7 +8,7 @@ import { CodexAppServerClient } from "../src/app-server-client.mjs";
 import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
 import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
 
-const VERSION = "1.13.0";
+const VERSION = "1.13.2";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "native-relay-companion.mjs");
 const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";

package/src/claude-bridge.mjs

@@ -8,7 +8,7 @@ import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
 
-const VERSION = "1.13.0";
+const VERSION = "1.13.2";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/desktop-task-receipts.mjs

@@ -0,0 +1,133 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { homeDir } from "./platform.mjs";
+
+const HASH = /^[a-f0-9]{64}$/;
+const FIELDS = new Set(["version", "key", "cwd", "promptHash", "state", "startedAt", "threadId", "projectId", "projectName", "name"]);
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const normalizedName = (name) => name?.normalize("NFC").trim().replace(/\s+/g, " ");
+const canonicalCwd = (cwd) => process.platform === "win32" ? path.normalize(cwd).toLowerCase() : path.normalize(cwd);
+const nonemptyString = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 8192 && !/[\u0000-\u001f]/.test(value);
+
+function assertKey(key) {
+  if (typeof key !== "string" || !HASH.test(key)) throw new Error("Invalid Desktop task receipt key; refusing unsafe filesystem access.");
+}
+
+function unsafeReceipt(key, cause) {
+  return new Error(`Desktop task receipt ${key} is unsafe or corrupt. Do not resend creation; inspect the existing Desktop task and repair the receipt first.`, { cause });
+}
+
+function validateReceipt(key, receipt) {
+  const valid = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+    && Object.keys(receipt).every((field) => FIELDS.has(field))
+    && receipt.version === 1 && receipt.key === key && HASH.test(receipt.promptHash)
+    && nonemptyString(receipt.cwd) && path.isAbsolute(receipt.cwd)
+    && ["pending", "unknown", "known"].includes(receipt.state)
+    && Number.isSafeInteger(receipt.startedAt) && receipt.startedAt >= 0
+    && ["threadId", "projectId", "projectName", "name"].every((field) => receipt[field] === undefined || nonemptyString(receipt[field]))
+    && (receipt.state !== "known" || nonemptyString(receipt.threadId));
+  if (!valid) throw unsafeReceipt(key);
+  const expected = digest(JSON.stringify([canonicalCwd(receipt.cwd), normalizedName(receipt.name) || receipt.promptHash]));
+  if (expected !== key) throw unsafeReceipt(key);
+  return receipt;
+}
+
+export class DesktopTaskReceipts {
+  constructor({ directory = path.join(process.env.CODEX_HOME ?? path.join(homeDir(), ".codex"), "bridge-task-receipts") } = {}) {
+    this.directory = path.resolve(directory);
+  }
+
+  key({ cwd, prompt, name }) {
+    if (!nonemptyString(cwd) || !path.isAbsolute(cwd) || typeof prompt !== "string" || (name !== undefined && typeof name !== "string")) {
+      throw new Error("Desktop task receipts require an absolute validated cwd, a prompt string, and an optional name string.");
+    }
+    const promptHash = digest(prompt);
+    return { key: digest(JSON.stringify([canonicalCwd(cwd), normalizedName(name) || promptHash])), promptHash };
+  }
+
+  async ensureDirectory(create = false) {
+    if (create) await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+    try {
+      const info = await fs.lstat(this.directory);
+      if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Desktop task receipt directory is unsafe; refusing creation or resend.");
+      return true;
+    } catch (err) {
+      if (!create && err.code === "ENOENT") return false;
+      throw err;
+    }
+  }
+
+  async read(key) {
+    assertKey(key);
+    if (!await this.ensureDirectory()) return null;
+    const file = path.join(this.directory, `${key}.json`);
+    let handle;
+    try {
+      const info = await fs.lstat(file);
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw unsafeReceipt(key);
+      handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      const opened = await handle.stat();
+      if (!opened.isFile() || opened.nlink !== 1 || opened.size > 65536) throw unsafeReceipt(key);
+      return validateReceipt(key, JSON.parse(await handle.readFile("utf8")));
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw unsafeReceipt(key, err);
+    } finally {
+      await handle?.close();
+    }
+  }
+
+  async write(key, receipt) {
+    assertKey(key);
+    validateReceipt(key, receipt);
+    await this.ensureDirectory(true);
+    await this.read(key);
+    const temporary = path.join(this.directory, `${key}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+      handle = await fs.open(temporary, "wx", 0o600);
+      await handle.writeFile(`${JSON.stringify(receipt)}\n`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await fs.rename(temporary, path.join(this.directory, `${key}.json`));
+      if (process.platform !== "win32") {
+        const directory = await fs.open(this.directory, "r");
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+      }
+    } finally {
+      await handle?.close();
+      await fs.unlink(temporary).catch((err) => { if (err.code !== "ENOENT") throw err; });
+    }
+  }
+
+  async withLock(key, callback) {
+    assertKey(key);
+    await this.ensureDirectory(true);
+    const file = path.join(this.directory, `${key}.lock`);
+    const token = randomUUID();
+    let handle;
+    try {
+      handle = await fs.open(file, "wx", 0o600);
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        throw new Error(`Desktop task creation ${key} is already in progress or a previous process left its lock. Do not resend; inspect the existing task. Locks never expire automatically.`, { cause: err });
+      }
+      throw err;
+    }
+    try {
+      await handle.writeFile(token, "utf8");
+      await handle.sync();
+      return await callback();
+    } finally {
+      await handle.close();
+      if (await fs.readFile(file, "utf8") === token) await fs.unlink(file);
+    }
+  }
+}

package/src/index.mjs

@@ -22,10 +22,10 @@ import {
 } from "./platform.mjs";
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
-import { DesktopTaskDelivery } from "./thread-delivery.mjs";
+import { DesktopTaskDelivery, DESKTOP_TOOL_BUDGET_MS } from "./thread-delivery.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 
-const VERSION = "1.13.0";
+const VERSION = "1.13.2";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -47,7 +47,7 @@ const security = new BridgeSecurityPolicy();
 const desktopTasksEnabled = desktopTasksConfigured();
 const desktopTasks = new DesktopTaskDelivery({ security });
 
-const client = new CodexAppServerClient({
+const client = desktopTasksEnabled ? null : new CodexAppServerClient({
   clientInfo: { name: "codex-mcp-bridge", title: "Codex MCP Bridge", version: VERSION },
   log,
 });
@@ -111,29 +111,31 @@ function threadNameFor({ cwd, prompt, name }) {
 }
 
 async function delegateDesktopTask({ cwd, prompt, name, model, effort, timeoutSec, openInApp, waitForReply = true }) {
+  const deadline = Date.now() + Math.min((timeoutSec ?? 40) * 1000, DESKTOP_TOOL_BUDGET_MS);
   const workspace = resolveWorkspacePath(cwd);
   const created = await desktopTasks.create({
     cwd: workspace.path, prompt, name: threadNameFor({ cwd: workspace.path, prompt, name }),
-    model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT,
+    dedupeName: name ?? "", model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT, deadline,
   });
   const notes = [];
   if (workspace.note) notes.push(workspace.note);
   if (openInApp ?? DEFAULT_OPEN_IN_APP) {
     try {
-      await desktopTasks.open(created.threadId);
+      await desktopTasks.open(created.threadId, { deadline });
       notes.push("opened in Codex Desktop while the task runs");
     } catch (err) {
       notes.push(`task was accepted; opening its page failed: ${err.message}`);
     }
   }
   const lines = [
-    "Delegated through Codex Desktop", `threadId: ${created.threadId}`, `name: ${created.name}`,
+    created.reused ? "Reused the existing Codex Desktop task; the prompt was not resent" : "Delegated through Codex Desktop", `threadId: ${created.threadId}`, `name: ${created.name}`,
     `cwd: ${created.cwd}`, `projectId: ${created.projectId}`, `project: ${created.projectName}`,
-    "permissions: Codex Desktop settings; no external app-server writer", ...notes,
+    "permissions: Codex Desktop settings; no external app-server writer",
+    ...(created.promptChanged ? ["The edited brief was not sent. Use send_to_codex_thread with this threadId for a continuation, or a distinct title for separate work."] : []), ...notes,
   ];
-  if (!waitForReply) return textResult([...lines, "status: accepted; the task is running in Desktop"].join("\n"));
+  if (!waitForReply) return textResult([...lines, created.reused ? "status: existing task; read it to check its current progress" : "status: accepted; the task is running in Desktop"].join("\n"));
   try {
-    const result = await desktopTasks.wait(created.threadId, { timeoutMs: (timeoutSec ?? 240) * 1000 });
+    const result = await desktopTasks.wait(created.threadId, { timeoutMs: Math.max(0, deadline - Date.now()) });
     return textResult([...lines, "", formatTurn(result, { desktop: true })].join("\n"), result.status === "failed" || result.status === "systemError");
   } catch (err) {
     return textResult([...lines, `Task was accepted; observation failed: ${err.message}`, "Do not resend the prompt. Inspect the existing task."].join("\n"), true);
@@ -212,9 +214,9 @@ async function finishDesktopHandoff({ threadId, result, openInApp, releaseAfterT
 }
 
 function formatThreadRow(t) {
-  const title = t.name || (t.preview ?? "").replace(/\s+/g, " ").slice(0, 70) || "(no title)";
+  const title = t.title || t.name || (t.preview ?? "").replace(/\s+/g, " ").slice(0, 70) || "(no title)";
   const updated = t.updatedAt ? new Date(t.updatedAt * 1000).toISOString().replace("T", " ").slice(0, 16) : "?";
-  const status = t.status?.type ?? "?";
+  const status = typeof t.status === "string" ? t.status : t.status?.type ?? "?";
   const deepLink = supportsCodexThreadLinks() ? `\n    open: ${codexThreadUrl(t.id)}` : "";
   const authorized = security.isThreadAuthorized(t.id, t.cwd)
     ? ""
@@ -293,7 +295,7 @@ server.registerTool(
         .min(10)
         .max(3600)
         .optional()
-        .describe("How long to wait for the turn to finish (default 240s)"),
+        .describe("How long to observe the task (Desktop caps the entire call, including creation, at 40s; the task continues and its threadId is returned)"),
       model: z.string().optional().describe("Model override, e.g. gpt-5.6-luna"),
       effort: z
         .enum(["minimal", "low", "medium", "high", "xhigh", "ultra"])
@@ -383,7 +385,7 @@ server.registerTool(
         .min(10)
         .max(3600)
         .optional()
-        .describe("How long to wait for the turn to finish (default 240s)"),
+        .describe("How long to observe the task (Desktop caps the entire call at 40s; the task continues and its threadId is returned)"),
       cwd: z.string().optional().describe("Override the working directory for this turn"),
       model: z.string().optional().describe("Override the model for this turn"),
       effort: z
@@ -408,7 +410,8 @@ server.registerTool(
     },
   },
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
-    return client.withThread(threadId, async () => {
+    const deadline = desktopTasksEnabled ? Date.now() + Math.min((timeoutSec ?? 40) * 1000, DESKTOP_TOOL_BUDGET_MS) : undefined;
+    return (desktopTasksEnabled ? desktopTasks : client).withThread(threadId, async () => {
       const notes = [];
       const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
       const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
@@ -416,18 +419,18 @@ server.registerTool(
         if (desktopTasksEnabled) {
           const workspace = cwd ? resolveWorkspacePath(cwd) : null;
           if (workspace) security.assertCwd(workspace.path);
-          const delivered = await desktopTasks.send({ threadId, prompt, cwd: workspace?.path, model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT, name });
+          const delivered = await desktopTasks.send({ threadId, prompt, cwd: workspace?.path, model: model ?? DEFAULT_MODEL, effort: effort ?? DEFAULT_EFFORT, name, deadline });
           notes.push("sent through Codex Desktop; no external app-server writer", `cwd: ${delivered.cwd}`);
           if (shouldOpen) {
             try {
-              await desktopTasks.open(threadId);
+              await desktopTasks.open(threadId, { deadline });
               notes.push("opened in Codex Desktop while the task runs");
             } catch (err) {
               notes.push(`task was accepted; opening its page failed: ${err.message}`);
             }
           }
           try {
-            const result = await desktopTasks.wait(threadId, { timeoutMs: (timeoutSec ?? 240) * 1000, previousTurnId: delivered.previousTurnId });
+            const result = await desktopTasks.wait(threadId, { timeoutMs: Math.max(0, deadline - Date.now()), previousTurnId: delivered.previousTurnId });
             return textResult([...notes, formatTurn(result, { desktop: true })].join("\n"), result.status === "failed" || result.status === "systemError");
           } catch (err) {
             return textResult([...notes, `threadId: ${threadId}`, `Task was accepted; observation failed: ${err.message}. Do not resend.`].join("\n"), true);
@@ -487,7 +490,7 @@ server.registerTool(
       } catch (err) {
         return failure(err);
       }
-    });
+    }, { deadline }).catch(failure);
   },
 );
 
@@ -513,6 +516,11 @@ server.registerTool(
   },
   async ({ limit, cwd, searchTerm, loadedOnly }) => {
     try {
+      if (desktopTasksEnabled) {
+        const workspace = cwd ? resolveWorkspacePath(cwd) : null;
+        const { rows, coverage } = await desktopTasks.list({ limit, cwd: workspace?.path, searchTerm, loadedOnly });
+        return textResult(`${rows.length} Codex thread(s) via Codex Desktop:\n${coverage}\n\n${rows.length ? rows.map(formatThreadRow).join("\n") : "No matching authorized local Codex tasks in this snapshot."}`);
+      }
       const params = { limit: limit ?? 15 };
       if (cwd) {
         const workspace = resolveWorkspacePath(cwd);
@@ -631,8 +639,9 @@ server.registerTool(
   async ({ threadId, limit }) => {
     try {
       if (desktopTasksEnabled) {
-        await desktopTasks.inspect(threadId);
-        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10) });
+        const deadline = Date.now() + DESKTOP_TOOL_BUDGET_MS;
+        await desktopTasks.inspect(threadId, undefined, { deadline });
+        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10) }, { deadline });
         return textResult(JSON.stringify(response, null, 2));
       }
       await assertThreadAccess(threadId);
@@ -718,9 +727,10 @@ server.registerTool(
   async ({ threadId, background }) => {
     try {
       if (desktopTasksEnabled) {
-        await desktopTasks.inspect(threadId);
+        const deadline = Date.now() + DESKTOP_TOOL_BUDGET_MS;
+        await desktopTasks.inspect(threadId, undefined, { deadline });
         if (background) await openThreadInCodexApp(threadId, { activate: false });
-        else await desktopTasks.open(threadId);
+        else await desktopTasks.open(threadId, { deadline });
         return textResult(`Opened ${codexThreadUrl(threadId)} in Codex Desktop.`);
       }
       await assertThreadAccess(threadId);
@@ -754,6 +764,7 @@ server.registerTool(
   },
   async () => {
     try {
+      if (desktopTasksEnabled) return textResult("Desktop-only mode does not manage an external app-server. Codex Desktop and its running tasks were left unchanged.");
       const result = await client.stopServer();
       if (result.stillListening) {
         return textResult("The app-server is still listening after the stop request; its thread writer locks are not confirmed released.", true);
@@ -784,6 +795,22 @@ server.registerTool(
   },
   async () => {
     const summary = security.summary();
+    if (desktopTasksEnabled) {
+      const native = await desktopTasks.status();
+      return textResult([
+        `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
+        `bridge version: ${VERSION}`,
+        `node:           ${process.version} at ${process.execPath}`,
+        "desktop tasks:  enabled; Desktop permissions, exact saved project, immediate visibility",
+        `native relay:   ${native.available ? "available; verified through Codex Desktop" : "unavailable"}`,
+        `native endpoint: ${native.socketPath}`,
+        ...(native.available ? [`local projects: ${native.localProjects}`] : [`reason: ${native.reason}`]),
+        "app-server:     disabled in Desktop-only mode; no external endpoint is contacted",
+        "autostart:      off; external app-server fallback is disabled",
+        `security:       thread policy ${security.threadPolicy}, ${summary.allowAllRoots ? "all directories" : `${summary.allowedRoots.length} allowed root(s)`}; task permissions belong to Codex Desktop`,
+        `claude desktop config: ${claudeDesktopConfigPath()}`,
+      ].join("\n"), !native.available);
+    }
     const up = await client.isServerUp();
     let liveThreads = null;
     if (up) {
@@ -836,4 +863,4 @@ server.registerTool(
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-log(`ready on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);
+log(desktopTasksEnabled ? `ready on ${PLATFORM_LABEL} (Codex Desktop only; external app-server disabled)` : `ready on ${PLATFORM_LABEL} (app-server endpoint: ${client.url}, codex: ${client.codexBin})`);

package/src/native-relay-companion.mjs

@@ -20,7 +20,7 @@ import {
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 
-const VERSION = "1.13.0";
+const VERSION = "1.13.2";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {

package/src/native-relay.mjs

@@ -178,6 +178,9 @@ export function validateDesktopOperation(operation, args) {
     case "list_projects":
       valid = exactObject(args, []);
       break;
+    case "list_threads":
+      valid = exactObject(args, ["limit"]) && optionalInteger(args.limit, 1, 50);
+      break;
     case "create_thread":
       valid = exactObject(args, ["prompt", "target", "model", "thinking", "title"]) &&
         nonempty(args.prompt) && optionalText(args.title) && modelSettings() &&

package/src/thread-delivery.mjs

@@ -1,7 +1,8 @@
-import { NativeDesktopRelay, desktopTaskSocketPath } from "./native-relay.mjs";
+import { NativeDesktopRelay, desktopTaskSocketPath, desktopTasksConfigured } from "./native-relay.mjs";
 import { runTurn } from "./turn.mjs";
 import { realpathSync } from "node:fs";
 import path from "node:path";
+import { DesktopTaskReceipts } from "./desktop-task-receipts.mjs";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -19,6 +20,7 @@ import path from "node:path";
  */
 export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
+export const DESKTOP_TOOL_BUDGET_MS = 40000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 
 export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
@@ -34,49 +36,146 @@ export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync
   if (matches.length !== 1) {
     throw new Error(matches.length
       ? `Multiple Codex Desktop projects match ${cwd}; keep one saved project for this directory before delegating.`
-      : `No saved local Codex Desktop project exactly matches ${cwd}. Add that directory as a project in Codex Desktop first.`);
+      : `No saved local Codex Desktop project exactly matches ${cwd}. Choose an existing saved project's directory or continue an existing task in this workspace. The bridge will not create a project or substitute a different directory.`);
   }
   return matches[0];
 }
 
 export class DesktopTaskDelivery {
-  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now } = {}) {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, receipts = new DesktopTaskReceipts() } = {}) {
     this.relay = relay;
     this.security = security;
     this.sleep = sleep;
     this.now = now;
+    this.receipts = receipts;
+    this.threadOperations = new Map();
   }
 
-  async request(operation, args) {
-    const response = await this.relay.requestDesktop(operation, args);
-    return response.result;
+  async request(operation, args, { deadline } = {}) {
+    try {
+      const remaining = deadline === undefined ? undefined : deadline - this.now();
+      if (remaining !== undefined && remaining <= 0) throw new Error("The bridge's response deadline has elapsed; this operation was not sent");
+      const response = await this.relay.requestDesktop(operation, args, remaining === undefined ? undefined : { timeoutMs: remaining });
+      return response.result;
+    } catch (err) {
+      throw new Error(`Codex Desktop operation ${operation} failed: ${err.message}. Desktop-only mode will not start or use an external app-server. Open Codex Desktop and reconnect its native relay, then inspect the existing task before retrying a send.`, { cause: err });
+    }
+  }
+
+  async withThread(threadId, operation, { deadline } = {}) {
+    const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
+    const current = previous.catch(() => {}).then(() => {
+      if (deadline !== undefined && this.now() >= deadline) throw new Error("The response deadline elapsed while another operation held this thread. No new prompt was sent.");
+      return operation();
+    });
+    this.threadOperations.set(threadId, current);
+    const cleanup = () => { if (this.threadOperations.get(threadId) === current) this.threadOperations.delete(threadId); };
+    current.then(cleanup, cleanup);
+    if (deadline === undefined) return current;
+    let timer;
+    try {
+      return await Promise.race([current, new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("The Desktop response deadline elapsed. A previous operation may still be running; inspect the existing task before sending anything again.")), Math.max(1, deadline - this.now()));
+      })]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async status() {
+    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: this.relay.socketPath, localProjects: response.projects.filter((project) => project.projectKind === "local" && project.hostId === "local").length };
+    } catch (err) {
+      return { available: false, socketPath: this.relay.socketPath, reason: err.message };
+    }
+  }
+
+  async list({ limit = 15, cwd, searchTerm, loadedOnly = false } = {}) {
+    if (loadedOnly) throw new Error("Codex Desktop does not expose a loaded-only thread list. Omit loadedOnly to list its recent and pinned local tasks; no external app-server was contacted.");
+    if (cwd) this.security.assertCwd(cwd);
+    const response = await this.request("list_threads", { limit: 50 });
+    if (!Array.isArray(response?.threads) || !Array.isArray(response?.pinnedThreads)) throw new Error("Codex Desktop returned an invalid thread list");
+    if (response.unavailableHosts?.some((host) => host === "local" || host?.hostId === "local")) throw new Error("The local Codex Desktop host is unavailable; its thread list could not be confirmed");
+    const seen = new Set();
+    const rows = [...response.pinnedThreads, ...response.threads].filter((thread) => {
+      if (thread.kind !== "codex" || thread.hostId !== "local" || !thread.id || !thread.cwd || seen.has(thread.id)) return false;
+      seen.add(thread.id);
+      if (!this.security.isThreadAuthorized(thread.id, thread.cwd)) return false;
+      try {
+        this.security.assertCwd(thread.cwd);
+        if (cwd && path.relative(realpathSync.native(cwd), realpathSync.native(thread.cwd))) return false;
+      } catch {
+        return false;
+      }
+      return !searchTerm || String(thread.title ?? "").toLowerCase().includes(searchTerm.toLowerCase());
+    }).slice(0, limit);
+    return { rows, coverage: "Codex Desktop's recent/pinned snapshot; local Codex workspaces only. Agent-created tasks visible in the sidebar can be omitted; read a known task ID directly before assuming creation failed." };
+  }
+
+  async reuseReceipt(receipt, { cwd, promptHash, deadline }) {
+    if (!receipt) return null;
+    if (path.relative(cwd, realpathSync.native(receipt.cwd))) throw new Error("The stored Desktop creation receipt belongs to another workspace. No prompt was sent.");
+    if (receipt.state !== "known") throw new Error(`An earlier Desktop creation is ${receipt.state} and may already have started. ${receipt.threadId ? `threadId: ${receipt.threadId}. ` : ""}Do not resend or create another task; inspect the existing Desktop task and resolve its creation receipt first.`);
+    let response;
+    try {
+      this.security.assertThread(receipt.threadId, cwd);
+      response = await this.request("read_thread", { threadId: receipt.threadId, hostId: "local", turnLimit: 1 }, { deadline });
+    } catch (err) {
+      throw new Error(`Existing Desktop task ${receipt.threadId} could not be verified. No prompt was resent and no duplicate task was created: ${err.message}`, { cause: err });
+    }
+    const thread = response?.thread;
+    if (thread?.id !== receipt.threadId || thread.hostId !== "local" || !thread.cwd || path.relative(cwd, realpathSync.native(thread.cwd))) throw new Error(`Existing Desktop task ${receipt.threadId} did not confirm the requested local workspace. No prompt was sent.`);
+    this.security.assertCwd(thread.cwd);
+    this.security.assertThread(thread.id, thread.cwd);
+    return { threadId: receipt.threadId, name: thread.title ?? receipt.name ?? "(unnamed)", cwd, projectId: receipt.projectId, projectName: receipt.projectName, backend: NATIVE_BACKEND, reused: true, promptChanged: receipt.promptHash !== promptHash };
   }
 
-  async create({ cwd, prompt, name, model, effort }) {
+  async create({ cwd, prompt, name, dedupeName = name, model, effort, deadline = this.now() + DESKTOP_TOOL_BUDGET_MS }) {
+    this.security.assertCwd(cwd);
+    cwd = realpathSync.native(cwd);
     this.security.assertCwd(cwd);
-    const listed = await this.request("list_projects", {});
+    dedupeName = dedupeName?.normalize("NFC").trim().replace(/\s+/g, " ") || undefined;
+    const identity = this.receipts.key({ cwd, prompt, name: dedupeName });
+    const options = { cwd, promptHash: identity.promptHash, deadline };
+    const reused = await this.reuseReceipt(await this.receipts.read(identity.key), options);
+    if (reused) return reused;
+    const listed = await this.request("list_projects", {}, { deadline });
     if (!Array.isArray(listed?.projects)) throw new Error("Codex Desktop returned no project list; no task was created.");
     const project = matchDesktopProject(listed.projects, cwd);
-    const response = await this.request("create_thread", {
-      prompt,
-      title: name,
-      target: { type: "project", projectId: project.projectId, environment: { type: "local" } },
-      ...(model ? { model } : {}),
-      ...(effort ? { thinking: effort } : {}),
+    return this.receipts.withLock(identity.key, async () => {
+      const existing = await this.reuseReceipt(await this.receipts.read(identity.key), options);
+      if (existing) return existing;
+      if (this.now() >= deadline) throw new Error("The response deadline elapsed before Desktop creation. No task was created.");
+      const receipt = { version: 1, ...identity, cwd, state: "pending", startedAt: this.now(), ...(dedupeName ? { name: dedupeName } : {}), projectId: project.projectId, ...(project.label ? { projectName: project.label } : {}) };
+      await this.receipts.write(identity.key, receipt);
+      let threadId;
+      let creationConfirmed = false;
+      try {
+        const response = await this.request("create_thread", {
+          prompt, title: name,
+          target: { type: "project", projectId: project.projectId, environment: { type: "local" } },
+          ...(model ? { model } : {}), ...(effort ? { thinking: effort } : {}),
+        }, { deadline });
+        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)}`);
+        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)}`);
+        return { threadId, name, cwd, projectId: project.projectId, projectName: project.label, backend: NATIVE_BACKEND };
+      } catch (err) {
+        if (!creationConfirmed) await this.receipts.write(identity.key, { ...receipt, state: "unknown", ...(typeof threadId === "string" && threadId ? { threadId } : {}) }).catch(() => {});
+        throw new Error(`${err.message}. ${threadId ? `threadId: ${threadId}. ` : ""}Do not resend the prompt. The creation receipt blocks duplicate tasks even after a bridge restart.`, { cause: err });
+      }
     });
-    const threadId = response?.threadId ?? response?.conversationId;
-    if (!threadId || response?.status === "outcome-unknown" || response?.firstTurn?.status === "outcome-unknown") {
-      throw new Error(`Desktop creation is not confirmed. Do not resend the prompt: ${JSON.stringify(response)}`);
-    }
-    this.security.registerThread(threadId);
-    if (response.hostId !== "local" || (response.firstTurn && response.firstTurn.status !== "accepted")) {
-      throw new Error(`Desktop created task ${threadId}, but did not confirm a local running turn: ${JSON.stringify(response)}. Inspect this task before retrying.`);
-    }
-    return { threadId, name, cwd, projectId: project.projectId, projectName: project.label, backend: NATIVE_BACKEND };
   }
 
-  async inspect(threadId, cwd) {
-    const response = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1 });
+  async inspect(threadId, cwd, { deadline } = {}) {
+    const response = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1 }, { deadline });
     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.assertThread(threadId, thread.cwd);
@@ -87,14 +186,14 @@ export class DesktopTaskDelivery {
     return { thread, latestTurnId: response.turns?.[0]?.id ?? null };
   }
 
-  async send({ threadId, prompt, cwd, model, effort, name }) {
-    const inspected = await this.inspect(threadId, cwd);
-    if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) });
+  async send({ threadId, prompt, cwd, model, effort, name, deadline }) {
+    const inspected = await this.inspect(threadId, cwd, { deadline });
+    if (name) await this.request("set_thread_title", { threadId, title: name.trim().slice(0, 200) }, { deadline });
     const response = await this.request("send_message_to_thread", {
       threadId, prompt,
       ...(model ? { model } : {}),
       ...(effort ? { thinking: effort } : {}),
-    });
+    }, { deadline });
     if (response?.threadId !== threadId || response?.success === false || response?.isError === true ||
         (response?.status !== undefined && !["accepted", "sent"].includes(response.status)) ||
         (response?.firstTurn && response.firstTurn.status !== "accepted")) {
@@ -103,8 +202,8 @@ export class DesktopTaskDelivery {
     return { threadId, cwd: inspected.thread.cwd, name: inspected.thread.title, previousTurnId: inspected.latestTurnId, backend: NATIVE_BACKEND };
   }
 
-  async open(threadId) {
-    const response = await this.request("navigate_to_codex_page", { threadId });
+  async open(threadId, { deadline } = {}) {
+    const response = await this.request("navigate_to_codex_page", { threadId }, { deadline });
     if (response?.navigated !== true) throw new Error(`Desktop did not confirm opening task ${threadId}`);
   }
 
@@ -113,10 +212,18 @@ export class DesktopTaskDelivery {
     let cursor;
     let turnId = null;
     let text = "";
+    const expired = () => ({ threadId, turnId, status: "timeout", text, activity: [], errors: [], durationMs: this.now() - startedAt });
     for (;;) {
-      const response = await this.request("wait_threads", {
-        targets: [{ threadId, hostId: "local", ...(cursor ? { afterCursor: cursor } : {}) }], timeoutMs: 0,
-      });
+      if (this.now() - startedAt >= timeoutMs) return expired();
+      let response;
+      try {
+        response = await this.request("wait_threads", {
+          targets: [{ threadId, hostId: "local", ...(cursor ? { afterCursor: cursor } : {}) }], timeoutMs: 0,
+        }, { deadline: startedAt + timeoutMs });
+      } catch (err) {
+        if (this.now() - startedAt >= timeoutMs) return expired();
+        throw err;
+      }
       const poll = response?.polls?.find((item) => item.thread?.id === threadId && item.thread?.hostId === "local");
       if (response?.errors?.length || !poll) throw new Error(`Could not observe task ${threadId}; it may still be running. Read it before retrying: ${JSON.stringify(response)}`);
       cursor = poll.cursor;
@@ -133,7 +240,7 @@ export class DesktopTaskDelivery {
           return { threadId, turnId, status, text, activity: [], errors: turn.error ? [turn.error] : [], durationMs: turn.durationMs ?? this.now() - startedAt };
         }
       }
-      if (this.now() - startedAt >= timeoutMs) return { threadId, turnId, status: "timeout", text, activity: [], errors: [], durationMs: this.now() - startedAt };
+      if (this.now() - startedAt >= timeoutMs) return expired();
       await this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
     }
   }
@@ -144,6 +251,7 @@ export function createThreadDelivery({
   relay = new NativeDesktopRelay(),
   log = () => {},
   timeoutMs = 240000,
+  desktopOnly = desktopTasksConfigured(),
   releaseAfterTurn =
     process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN !== undefined
       ? process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN === "1"
@@ -168,6 +276,7 @@ export function createThreadDelivery({
         return { backend: NATIVE_BACKEND, threadId, ack };
       } catch (err) {
         if (err.reachedCompanion || err.code !== "RELAY_UNREACHABLE") throw err;
+        if (desktopOnly) throw new Error(`Codex Desktop relay is unavailable: ${err.message}. Desktop-only mode will not start or use an external app-server.`);
         log(`native relay unreachable (${err.message}); falling back to the app-server path`);
       }
     } else if (status.reason !== reportedUnavailable) {
@@ -175,6 +284,7 @@ export function createThreadDelivery({
       log(`native relay not in use: ${status.reason}`);
     }
 
+    if (desktopOnly) throw new Error(`Codex Desktop relay is unavailable: ${status.reason ?? "no native acknowledgement"}. Desktop-only mode will not start or use an external app-server.`);
     if (!codex) throw new Error("No Codex app-server client is configured to deliver this message");
     const send = async () => {
       await codex.ensureThreadAttached(threadId);
@@ -200,7 +310,7 @@ export function createThreadDelivery({
     const status = relay.status();
     return status.enabled
       ? `${NATIVE_BACKEND} via ${status.socketPath}`
-      : `${APP_SERVER_BACKEND} (${status.reason})`;
+      : desktopOnly ? `${NATIVE_BACKEND} unavailable (${status.reason}); external app-server disabled` : `${APP_SERVER_BACKEND} (${status.reason})`;
   }
 
   return { deliver, describe };