@minhspark/codex-mcp-bridge 1.12.5 → 1.13.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [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
+
+- Opt-in Desktop task delivery: `delegate_to_codex` creates a task in the exact saved local project and opens it while running. `send_to_codex_thread` continues through Desktop without a second writer. `start_codex_thread` accepts an initial prompt and requires it in Desktop mode.
+- Enable with `codex-native-relay-install --desktop-tasks` or `CODEX_BRIDGE_DESKTOP_TASKS=1`. Desktop mode uses Desktop permissions and preserves bridge workspace/thread authorization. Missing, ambiguous, remote, or parent-only project matches fail before creation; the requested checkout is preserved.
+- Strictly allowlisted native operations and a separate Desktop task socket allow upgrades alongside an older legacy relay owner. Read/open operations use Desktop too; timed-out native tasks point to Desktop's Stop control.
+
+### Fixed
+
+- Distinguish task acceptance, model failure, attention requests, and observation timeout. Follow-up polling ignores the previous completed turn; unconfirmed creation or sending is never automatically retried through another backend.
+- Mark prompt-bearing task creation as potentially destructive in MCP annotations, and preserve the shared Desktop opt-in when bootstrapping a relay executor.
+
+### Verification
+
+- Added project matching, authorization, protocol validation, socket transport, uncertain acknowledgement, attention, timeout, and full MCP creation/opening tests.
+- A real Windows Desktop task appeared under PCC4SH and completed with `cwd=C:\PCC4SH`, `HEAD=74ed553`. A subsequent native message reached that same task and reported an account usage-limit failure; a second successful model response was not claimed.
+
 ## [1.12.5] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -8,7 +8,27 @@
 
 A **two-way** bridge between Claude and Codex: Claude pushes prompts into a **live Codex thread**, and Codex messages back into a **running Claude Code session**. Each side sees the other's sessions and follows the conversation inside its own app. Runs on **macOS, Windows and Linux** (the Codex → Claude direction uses unix sockets on macOS/Linux and named pipes on Windows).
 
-This is not `codex exec`, which starts a fresh session every time. The bridge speaks JSON-RPC to the real Codex app-server, so the thread keeps its history, its `cwd`, its model and its rollout file — and a human can watch it run in the Codex desktop app instead of reading the transcript afterwards.
+The bridge preserves task history and working directories across messages. Enable **Desktop tasks** to create, assign, and watch work directly in Codex Desktop. The separate app-server backend remains available for CLI use; it cannot provide live Desktop viewing while it owns the task's writer lock.
+
+### 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:
+
+```bash
+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.
+
+`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` 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` lists authorized local Codex tasks from Desktop's latest 50 non-pinned tasks and all pinned tasks, then applies workspace/title filters and the requested result limit. This snapshot does not cover the complete archive. Desktop does not expose the external server's `loadedOnly` state; requesting it returns an explanation without contacting that server.
 
 ## Architecture
 
@@ -16,7 +36,7 @@ Two MCP servers, one living inside each agent:
 
 ```
                      ┌──────────────── codex-mcp-bridge (runs inside Claude) ──────────────┐
-Claude Desktop ──────┤ stdio                                    WebSocket                  ├──> codex app-server ──> thread shows in Codex Desktop
+Claude Desktop ──────┤ stdio                                    WebSocket                  ├──> separate codex app-server
                      └────────────────────────────────────────────────────────────────────┘
 
                      ┌──────────────── claude-bridge (runs inside Codex) ──────────────────┐
@@ -26,14 +46,14 @@ Codex ───────────────┤ stdio             unix so
 Codex TUI  ──codex --remote ws://127.0.0.1:8791──> same app-server, same live thread
 
                      ┌── codex-native-relay (launched by Codex Desktop, Windows/macOS) ────┐
-claude-bridge ───────┤ named pipe / unix socket                         native tools       ├──> the thread already open in Codex Desktop
+both bridges ───────┤ named pipe / unix socket                         native tools       ├──> visible project tasks in Codex Desktop
                      └────────────────────────────────────────────────────────────────────┘
 ```
 
-- 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.
-- `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.
+- 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.
 - The **native relay** (Windows/macOS, optional) is the third line: a thread the human is watching in Codex Desktop belongs to the app, and a second app-server cannot write to it. Instead of taking the thread away, `claude-bridge` hands the message to a companion the app itself launched, and the app delivers it. See [Codex Desktop native relay](#codex-desktop-native-relay).
 
 ## Requirements
@@ -298,7 +318,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 |
@@ -504,7 +524,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.12.5",
+  "version": "1.13.1",
   "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/check.mjs

@@ -13,6 +13,8 @@ const bridgeEnvNames = [
   "CODEX_BRIDGE_AUTO_APPROVE_ACK",
   "CODEX_BRIDGE_APPROVAL_POLICY",
   "CODEX_BRIDGE_AUTOSTART",
+  "CODEX_BRIDGE_DESKTOP_TASKS",
+  "CODEX_NATIVE_RELAY_SOCKET",
   "CODEX_BRIDGE_EFFORT",
   "CODEX_BRIDGE_MODEL",
   "CODEX_BRIDGE_PATH_MAP",

package/scripts/install-claude-desktop.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
+import { desktopTasksConfigured } from "../src/native-relay.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
@@ -49,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",
@@ -85,6 +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: 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

@@ -5,10 +5,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { CodexAppServerClient } from "../src/app-server-client.mjs";
-import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath } from "../src/native-relay.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.12.5";
+const VERSION = "1.13.1";
 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";
@@ -81,5 +81,9 @@ if (existing) {
 }
 
 console.log(`\nrelay socket: ${relaySocketPath()}`);
+if (process.argv.includes("--desktop-tasks")) {
+  writeRelayConfig({ ...readRelayConfig(), desktopTasks: true });
+  console.log("Desktop task creation enabled: exact saved local projects, immediate visibility, Codex Desktop permissions.");
+}
 console.log("Restart Codex Desktop so it launches the companion, then check with native_relay_status.");
 console.log("remove: node scripts/install-native-relay.mjs --remove");

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.12.5";
+const VERSION = "1.13.1";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/index.mjs

@@ -22,8 +22,10 @@ import {
 } from "./platform.mjs";
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
+import { DesktopTaskDelivery } from "./thread-delivery.mjs";
+import { desktopTasksConfigured } from "./native-relay.mjs";
 
-const VERSION = "1.12.5";
+const VERSION = "1.13.1";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -42,8 +44,10 @@ const DEFAULT_RELEASE_AFTER_TURN = process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN
 const TERMINAL_TURN_STATUSES = new Set(["completed", "interrupted", "failed"]);
 const RELEASE_TURN_STATUSES = TERMINAL_TURN_STATUSES;
 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,
 });
@@ -106,6 +110,36 @@ function threadNameFor({ cwd, prompt, name }) {
   );
 }
 
+async function delegateDesktopTask({ cwd, prompt, name, model, effort, timeoutSec, openInApp, waitForReply = true }) {
+  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,
+  });
+  const notes = [];
+  if (workspace.note) notes.push(workspace.note);
+  if (openInApp ?? DEFAULT_OPEN_IN_APP) {
+    try {
+      await desktopTasks.open(created.threadId);
+      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}`,
+    `cwd: ${created.cwd}`, `projectId: ${created.projectId}`, `project: ${created.projectName}`,
+    "permissions: Codex Desktop settings; no external app-server writer", ...notes,
+  ];
+  if (!waitForReply) return textResult([...lines, "status: accepted; the task is running in Desktop"].join("\n"));
+  try {
+    const result = await desktopTasks.wait(created.threadId, { timeoutMs: (timeoutSec ?? 240) * 1000 });
+    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);
+  }
+}
+
 async function createCodexThread({ cwd, model, name, prompt }) {
   const workspace = resolveWorkspacePath(cwd);
   security.assertCwd(workspace.path);
@@ -178,9 +212,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)
     ? ""
@@ -189,7 +223,7 @@ function formatThreadRow(t) {
   return `- ${t.id}\n    title: ${title}\n    cwd: ${t.cwd ?? "?"}\n    updated: ${updated}  status: ${status}  source: ${t.source ?? "?"}${deepLink}${authorized}`;
 }
 
-function formatTurn(result) {
+function formatTurn(result, { desktop = false } = {}) {
   const lines = [];
   lines.push(`thread: ${result.threadId}`);
   lines.push(`turn:   ${result.turnId ?? "?"}  status: ${result.status}`);
@@ -214,8 +248,9 @@ function formatTurn(result) {
   if (result.status === "timeout") {
     lines.push(
       "",
-      "NOTE: the bridge stopped waiting, but the turn is still running inside Codex.",
-      `Read it later with read_codex_thread, or stop it with interrupt_codex_turn (turnId ${result.turnId}).`,
+      "NOTE: the bridge stopped waiting; it did not pause or cancel the task.",
+      desktop ? "Inspect the task in Codex Desktop; use its Stop button to stop the running turn. Do not resend the prompt." :
+        `Read it later with read_codex_thread, or stop it with interrupt_codex_turn (turnId ${result.turnId}).`,
     );
   }
   if (result.status === "disconnected") {
@@ -234,7 +269,8 @@ const server = new McpServer(
   {
     instructions:
       "Bridge Claude work into Codex. Prefer delegate_to_codex: it creates a named Codex thread at the " +
-      "requested cwd, sends the prompt, releases the bridge writer lock, and opens the exact thread in " +
+      "requested cwd. With Desktop tasks enabled it assigns the exact saved project and starts visibly in " +
+      "Codex Desktop using Desktop permissions. Otherwise it releases the bridge writer lock and opens the exact thread in " +
       "Codex Desktop. Use send_to_codex_thread only when an existing threadId is intentional; use " +
       "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring.",
   },
@@ -266,7 +302,7 @@ server.registerTool(
       openInApp: z
         .boolean()
         .optional()
-        .describe("Open the finished session in Codex Desktop on Windows or macOS"),
+        .describe("Show the task in Codex Desktop; native tasks open immediately while running"),
       releaseAfterTurn: z
         .boolean()
         .optional()
@@ -284,6 +320,7 @@ server.registerTool(
     const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
     const notes = [];
     try {
+      if (desktopTasksEnabled) return await delegateDesktopTask({ cwd, prompt, name, model, effort, timeoutSec, openInApp });
       const created = await createCodexThread({ cwd, prompt, name, model });
       if (created.workspace.note) notes.push(created.workspace.note);
       if (shouldOpen && !shouldRelease) {
@@ -371,11 +408,31 @@ server.registerTool(
     },
   },
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
-    return client.withThread(threadId, async () => {
+    return (desktopTasksEnabled ? desktopTasks : client).withThread(threadId, async () => {
       const notes = [];
       const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
       const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
       try {
+        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 });
+          notes.push("sent through Codex Desktop; no external app-server writer", `cwd: ${delivered.cwd}`);
+          if (shouldOpen) {
+            try {
+              await desktopTasks.open(threadId);
+              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 });
+            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);
+          }
+        }
         const authorizedThread = await assertThreadAccess(threadId);
         let resolvedCwd = null;
         if (cwd) {
@@ -456,6 +513,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);
@@ -519,21 +581,27 @@ server.registerTool(
   "start_codex_thread",
   {
     title: "Start a new Codex thread",
-    description: "Create a brand new Codex thread in the shared app-server and return its threadId.",
+    description: "Start a Codex task. In Desktop mode include the initial prompt to create and assign a visible task atomically; use delegate_to_codex to also wait for its reply.",
     inputSchema: {
       cwd: z.string().describe("Absolute working directory for the new Codex session"),
+      prompt: z.string().min(1).optional().describe("Initial task; required with CODEX_BRIDGE_DESKTOP_TASKS=1, starts immediately"),
       model: z.string().optional().describe("Model override, e.g. gpt-5.6-luna"),
       name: z.string().min(1).max(200).optional().describe("Optional title to show for the new Codex session"),
     },
     annotations: {
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       idempotentHint: false,
       openWorldHint: true,
     },
   },
-  async ({ cwd, model, name }) => {
+  async ({ cwd, model, name, prompt }) => {
     try {
+      if (desktopTasksEnabled) {
+        if (!prompt?.trim()) throw new Error("Desktop task creation requires the initial prompt. Use delegate_to_codex, or pass prompt to start_codex_thread. No task was created.");
+        return await delegateDesktopTask({ cwd, model, name, prompt, waitForReply: false });
+      }
+      if (prompt) throw new Error("Use delegate_to_codex to send an initial prompt in app-server mode.");
       const created = await createCodexThread({ cwd, model, name });
       return textResult(
         [
@@ -567,6 +635,11 @@ 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) });
+        return textResult(JSON.stringify(response, null, 2));
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId, includeTurns: true });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -610,6 +683,10 @@ server.registerTool(
   },
   async ({ threadId, turnId }) => {
     try {
+      if (desktopTasksEnabled) {
+        await desktopTasks.inspect(threadId);
+        return textResult("This task is owned by Codex Desktop. Use its Stop button; the separate app-server cannot interrupt a Desktop turn.", true);
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -645,6 +722,12 @@ server.registerTool(
   },
   async ({ threadId, background }) => {
     try {
+      if (desktopTasksEnabled) {
+        await desktopTasks.inspect(threadId);
+        if (background) await openThreadInCodexApp(threadId, { activate: false });
+        else await desktopTasks.open(threadId);
+        return textResult(`Opened ${codexThreadUrl(threadId)} in Codex Desktop.`);
+      }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId });
       const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
@@ -676,6 +759,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);
@@ -706,6 +790,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) {
@@ -726,6 +826,7 @@ server.registerTool(
       `autostart:      ${client.autoStart ? "on" : "off"}   approvals: ${client.approval}`,
       `desktop links:  ${supportsCodexThreadLinks() ? "codex:// available" : "not available on this platform"}`,
       `security:       thread policy ${security.threadPolicy} (${summary.allowAllThreads ? "all threads" : `${summary.authorizedThreads} pre-authorized thread(s)`}), ${summary.allowAllRoots ? "all directories" : `${summary.allowedRoots.length} allowed root(s)`}, sandbox ${security.sandbox}, approvals ${security.approvalPolicy}`,
+      `desktop tasks:  ${desktopTasksEnabled ? "enabled; Desktop permissions, exact saved project, immediate visibility" : "disabled; app-server permissions (enable CODEX_BRIDGE_DESKTOP_TASKS=1 to use Desktop permissions)"}`,
       `live threads:   ${liveThreads ?? "(unknown)"}`,
       `claude desktop config: ${claudeDesktopConfigPath()}`,
     ];
@@ -757,4 +858,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

@@ -14,10 +14,13 @@ import {
   RELAY_PROTOCOL_VERSION,
   relaySocketPath,
   resolveRelayThreadId,
+  desktopTaskSocketPath,
+  validateDesktopOperation,
+  decodeNativeToolResult,
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
 
-const VERSION = "1.12.5";
+const VERSION = "1.13.1";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {
@@ -40,8 +43,11 @@ function errorCode(err) {
  */
 export async function handleRelayRequest(
   payload,
-  { dispatch, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
+  { dispatch, dispatchDesktop, resolveExecutor = resolveRelayThreadId, env = process.env } = {},
 ) {
+  if (payload && typeof payload === "object" && Object.hasOwn(payload, "operation")) {
+    return handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env });
+  }
   if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
       Object.keys(payload).some((key) => !["v", "targetThreadId", "message"].includes(key)) ||
       (payload.v !== undefined && payload.v !== RELAY_PROTOCOL_VERSION)) {
@@ -85,6 +91,37 @@ export async function handleRelayRequest(
   }
 }
 
+async function handleDesktopRequest(payload, { dispatchDesktop, resolveExecutor, env }) {
+  if (Array.isArray(payload) || payload.v !== RELAY_PROTOCOL_VERSION ||
+      Object.keys(payload).some((key) => !["v", "operation", "arguments"].includes(key))) {
+    return errorResponse("RELAY_BAD_REQUEST", "expected an allowlisted Desktop operation");
+  }
+  try {
+    validateDesktopOperation(payload.operation, payload.arguments);
+    if (typeof dispatchDesktop !== "function") {
+      return errorResponse("NATIVE_OPERATION_UNAVAILABLE", "This companion does not support Desktop operations; reload the native relay");
+    }
+    const executorThreadId = resolveExecutor(env).threadId;
+    if (payload.operation === "send_message_to_thread" && payload.arguments.threadId === executorThreadId) {
+      return errorResponse("RELAY_BAD_REQUEST", "The relay executor cannot receive its own relayed message");
+    }
+    const nativeResult = await dispatchDesktop({
+      executorThreadId,
+      operation: payload.operation,
+      arguments: payload.arguments,
+    });
+    return {
+      ok: true,
+      v: RELAY_PROTOCOL_VERSION,
+      operation: payload.operation,
+      executorThreadId,
+      result: decodeNativeToolResult(nativeResult),
+    };
+  } catch (err) {
+    return errorResponse(errorCode(err), err?.message ?? String(err));
+  }
+}
+
 /**
  * Listens on a private local socket or Windows named pipe and answers one NDJSON line per request.
 *
@@ -95,6 +132,7 @@ export class RelaySocketServer {
   constructor({
     socketPath,
     dispatch,
+    dispatchDesktop,
     resolveExecutor = resolveRelayThreadId,
     restrictSocket = (target) => {
       if (!IS_WINDOWS) fs.chmodSync(target, 0o600);
@@ -103,6 +141,7 @@ export class RelaySocketServer {
   } = {}) {
     this.socketPath = socketPath;
     this.dispatch = dispatch;
+    this.dispatchDesktop = dispatchDesktop;
     this.resolveExecutor = resolveExecutor;
     this.restrictSocket = restrictSocket;
     this.log = logFn;
@@ -238,10 +277,11 @@ export class RelaySocketServer {
     }
     const response = await handleRelayRequest(payload, {
       dispatch: this.dispatch,
+      dispatchDesktop: this.dispatchDesktop,
       resolveExecutor: this.resolveExecutor,
     });
     if (!response.ok) this.log(`relay refused ${payload?.targetThreadId ?? "?"}: ${response.error.message}`);
-    else this.log(`relayed a message into thread ${response.targetThreadId}`);
+    else this.log(response.operation ? `completed Desktop operation ${response.operation}` : `relayed a message into thread ${response.targetThreadId}`);
     this.#reply(socket, response);
   }
 
@@ -338,7 +378,17 @@ if (invokedDirectly) {
   const nativeTools = new NativeToolsClient();
   const dispatch = (args) => nativeTools.dispatch(args);
 
-  const relay = new RelaySocketServer({ socketPath: relaySocketPath(), dispatch, log });
+  const relay = new RelaySocketServer({
+    socketPath: relaySocketPath(),
+    dispatch,
+    dispatchDesktop: (args) => nativeTools.dispatchDesktop(args),
+    log,
+  });
+  const desktopRelay = desktopTaskSocketPath() === relay.socketPath ? relay : new RelaySocketServer({
+    socketPath: desktopTaskSocketPath(),
+    dispatchDesktop: (args) => nativeTools.dispatchDesktop(args),
+    log,
+  });
 
   mcp.registerTool(
     "native_relay_status",
@@ -370,6 +420,7 @@ if (invokedDirectly) {
               `platform:       ${PLATFORM_LABEL} (${process.platform}/${process.arch})`,
               `companion:      codex-native-relay ${VERSION}`,
               `relay socket:   ${relay.started ? relay.socketPath : `${relay.socketPath} (${listening ? "shared companion listening" : "not listening"})`}`,
+              `desktop tasks:  ${desktopRelay.socketPath} (${await desktopRelay.isListening() ? "listening" : "not listening"})`,
               `executor:       ${executor}`,
               `dispatch:       ${process.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD}`,
               `native pipe:    ${nativeTools.socketPath ?? "unavailable (requires Codex Desktop)"}`,
@@ -381,7 +432,8 @@ if (invokedDirectly) {
   );
 
   const startup = startRelayWhenAvailable({ nativeTools, relay, log });
-  mcp.server.onclose = () => startup.stop();
+  const desktopStartup = desktopRelay === relay ? startup : startRelayWhenAvailable({ nativeTools, relay: desktopRelay, log });
+  mcp.server.onclose = () => { startup.stop(); desktopStartup.stop(); };
   await mcp.connect(new StdioServerTransport());
   log(`ready on ${PLATFORM_LABEL} (${relay.started ? relay.socketPath : "socket down"})`);
 }

package/src/native-relay.mjs

@@ -66,6 +66,16 @@ export function relaySocketPath(env = process.env) {
   return env.CODEX_NATIVE_RELAY_SOCKET ?? (IS_WINDOWS ? WINDOWS_RELAY_SOCKET : path.join(codexHome(env), RELAY_SOCKET_NAME));
 }
 
+export function desktopTaskSocketPath(env = process.env) {
+  return env.CODEX_NATIVE_RELAY_SOCKET ?? `${relaySocketPath(env)}-desktop-tasks`;
+}
+
+export function desktopTasksConfigured(env = process.env) {
+  return env.CODEX_BRIDGE_DESKTOP_TASKS !== undefined
+    ? env.CODEX_BRIDGE_DESKTOP_TASKS === "1"
+    : readRelayConfig(env)?.desktopTasks === true;
+}
+
 export function relayConfigPath(env = process.env) {
   return path.join(codexHome(env), RELAY_CONFIG_NAME);
 }
@@ -141,6 +151,111 @@ export function nativeDispatchParams({ executorThreadId, targetThreadId, message
   };
 }
 
+const DESKTOP_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
+
+function exactObject(value, keys) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) &&
+    Object.keys(value).every((key) => keys.includes(key));
+}
+
+function nonempty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function optionalText(value) {
+  return value === undefined || nonempty(value);
+}
+
+function optionalInteger(value, min, max) {
+  return value === undefined || Number.isSafeInteger(value) && value >= min && value <= max;
+}
+
+export function validateDesktopOperation(operation, args) {
+  let valid = false;
+  const modelSettings = () => optionalText(args.model) &&
+    (args.thinking === undefined || DESKTOP_EFFORTS.has(args.thinking));
+  switch (operation) {
+    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() &&
+        exactObject(args.target, ["type", "projectId", "environment"]) &&
+        args.target.type === "project" && nonempty(args.target.projectId) &&
+        exactObject(args.target.environment, ["type"]) && args.target.environment.type === "local";
+      break;
+    case "send_message_to_thread":
+      valid = exactObject(args, ["threadId", "prompt", "model", "thinking"]) &&
+        nonempty(args.threadId) && nonempty(args.prompt) && modelSettings();
+      break;
+    case "read_thread":
+      valid = exactObject(args, ["threadId", "hostId", "cursor", "turnLimit", "includeOutputs", "maxOutputCharsPerItem"]) &&
+        nonempty(args.threadId) && (args.hostId === undefined || args.hostId === "local") &&
+        optionalText(args.cursor) && optionalInteger(args.turnLimit, 1, 10) &&
+        (args.includeOutputs === undefined || typeof args.includeOutputs === "boolean") &&
+        optionalInteger(args.maxOutputCharsPerItem, 1, 16000);
+      break;
+    case "wait_threads":
+      valid = exactObject(args, ["targets", "timeoutMs"]) && args.timeoutMs === 0 &&
+        Array.isArray(args.targets) && args.targets.length >= 1 && args.targets.length <= 8 &&
+        args.targets.every((target) => exactObject(target, ["threadId", "hostId", "afterCursor"]) &&
+          nonempty(target.threadId) && (target.hostId === undefined || target.hostId === "local") &&
+          optionalText(target.afterCursor));
+      break;
+    case "navigate_to_codex_page":
+      valid = exactObject(args, ["threadId"]) && nonempty(args.threadId);
+      break;
+    case "set_thread_title":
+      valid = exactObject(args, ["threadId", "title"]) && nonempty(args.threadId) && nonempty(args.title);
+      break;
+  }
+  if (!valid) throw new NativeRelayError(`Unsupported or invalid Desktop operation: ${operation}`, "RELAY_BAD_REQUEST");
+  return args;
+}
+
+export function nativeDesktopOperationParams({ executorThreadId, operation, arguments: args }) {
+  validateDesktopOperation(operation, args);
+  return {
+    arguments: args,
+    callId: `codex-native-relay-${randomUUID()}`,
+    namespace: "codex_app",
+    threadId: executorThreadId,
+    tool: operation,
+    turnId: `codex-native-relay-turn-${randomUUID()}`,
+  };
+}
+
+export function decodeNativeToolResult(result) {
+  if (result?.success !== true || result?.isError === true) {
+    const detail = (result?.contentItems ?? result?.content ?? []).filter((item) => typeof item?.text === "string").map((item) => item.text).join("\n").slice(0, 2000);
+    throw new NativeRelayError(detail || "Codex Desktop did not confirm the requested operation", "NATIVE_DISPATCH_FAILED");
+  }
+  let decoded = result.structuredContent;
+  if (decoded === undefined) {
+    const items = result.contentItems ?? result.content;
+    if (Array.isArray(items)) {
+      const text = items.filter((item) => item?.type === "inputText" || item?.type === "text")
+        .map((item) => item.text).filter((value) => typeof value === "string").join("\n");
+      if (text) {
+        try {
+          decoded = JSON.parse(text);
+        } catch {
+          decoded = { text };
+        }
+      }
+    }
+  }
+  decoded ??= result;
+  if (decoded?.isError === true || decoded?.success === false) {
+    throw new NativeRelayError("Codex Desktop rejected the requested operation", "NATIVE_DISPATCH_FAILED");
+  }
+  return decoded;
+}
+
 const execFileAsync = promisify(execFile);
 
 function splitDesktopCommandLine(commandLine, platform) {
@@ -389,12 +504,20 @@ export class NativeToolsClient {
   }
 
   async dispatch(args) {
+    return this.#request(nativeDispatchParams(args));
+  }
+
+  async dispatchDesktop(args) {
+    return this.#request(nativeDesktopOperationParams(args));
+  }
+
+  async #request(params) {
     const id = this.nextId++;
     const payload = Buffer.from(JSON.stringify({
       jsonrpc: "2.0",
       id,
       method: this.env.CODEX_NATIVE_RELAY_METHOD ?? NATIVE_DISPATCH_METHOD,
-      params: nativeDispatchParams(args),
+      params,
     }));
     if (payload.length > MAX_FRAME_BYTES) {
       throw new NativeRelayError("Native dispatch exceeds the frame limit", "RELAY_MESSAGE_TOO_LARGE");
@@ -503,6 +626,15 @@ export class NativeDesktopRelay {
 
   async sendMessage(targetThreadId, message, { timeoutMs = this.timeoutMs } = {}) {
     const request = { v: RELAY_PROTOCOL_VERSION, targetThreadId, message };
+    return this.#request(request, timeoutMs);
+  }
+
+  async requestDesktop(operation, args, { timeoutMs = this.timeoutMs } = {}) {
+    validateDesktopOperation(operation, args);
+    return this.#request({ v: RELAY_PROTOCOL_VERSION, operation, arguments: args }, timeoutMs);
+  }
+
+  async #request(request, timeoutMs) {
     const line = `${JSON.stringify(request)}\n`;
     if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES) {
       throw new NativeRelayError(
@@ -512,7 +644,10 @@ export class NativeDesktopRelay {
     }
 
     const response = await this.#roundTrip(line, timeoutMs);
-    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) return response;
+    if (response?.ok === true && response.v === RELAY_PROTOCOL_VERSION) {
+      if (request.operation && response.operation !== request.operation) throw new NativeRelayError("The relay answered a different Desktop operation; do not retry this request", "RELAY_BAD_RESPONSE", { reachedCompanion: true });
+      return response;
+    }
     throw new NativeRelayError(
       response?.error?.message ?? "the Codex Desktop relay refused the message",
       response?.error?.code ?? "NATIVE_DISPATCH_FAILED",
@@ -613,7 +748,7 @@ export async function bootstrapRelayThread(client, { cwd = homeDir(), env = proc
     try {
       await client.call("thread/name/set", { threadId, name });
     } catch {}
-    writeRelayConfig({ relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
+    writeRelayConfig({ ...readRelayConfig(env), relayThreadId: threadId, createdAt: new Date().toISOString() }, env);
   } finally {
     release = await client.releaseThread(threadId);
   }

package/src/thread-delivery.mjs

@@ -1,5 +1,7 @@
-import { NativeDesktopRelay } 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";
 
 /**
  * Which backend puts a message into a Codex thread.
@@ -19,11 +21,178 @@ export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
 
+export function matchDesktopProject(projects, cwd, { canonicalize = realpathSync.native, paths = path } = {}) {
+  const requested = canonicalize(cwd);
+  const matches = projects.filter((project) => {
+    if (project.projectKind !== "local" || project.hostId !== "local" || !project.path || !project.projectId) return false;
+    try {
+      return paths.relative(requested, canonicalize(project.path)) === "";
+    } catch {
+      return false;
+    }
+  });
+  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.`);
+  }
+  return matches[0];
+}
+
+export class DesktopTaskDelivery {
+  constructor({ relay = new NativeDesktopRelay({ socketPath: desktopTaskSocketPath() }), security, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now } = {}) {
+    this.relay = relay;
+    this.security = security;
+    this.sleep = sleep;
+    this.now = now;
+    this.threadOperations = new Map();
+  }
+
+  async request(operation, args) {
+    try {
+      const response = await this.relay.requestDesktop(operation, args);
+      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) {
+    const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
+    const current = previous.catch(() => {}).then(operation);
+    this.threadOperations.set(threadId, current);
+    try {
+      return await current;
+    } finally {
+      if (this.threadOperations.get(threadId) === current) this.threadOperations.delete(threadId);
+    }
+  }
+
+  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 latest 50 non-pinned tasks and all pinned tasks; local Codex workspaces only" };
+  }
+
+  async create({ cwd, prompt, name, model, effort }) {
+    this.security.assertCwd(cwd);
+    const listed = await this.request("list_projects", {});
+    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 } : {}),
+    });
+    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 });
+    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);
+    this.security.assertCwd(thread.cwd);
+    if (cwd && path.relative(realpathSync.native(cwd), realpathSync.native(thread.cwd))) {
+      throw new Error("Native Desktop delivery cannot change an existing task's workspace; create a new task at the requested cwd.");
+    }
+    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) });
+    const response = await this.request("send_message_to_thread", {
+      threadId, prompt,
+      ...(model ? { model } : {}),
+      ...(effort ? { thinking: effort } : {}),
+    });
+    if (response?.threadId !== threadId || response?.success === false || response?.isError === true ||
+        (response?.status !== undefined && !["accepted", "sent"].includes(response.status)) ||
+        (response?.firstTurn && response.firstTurn.status !== "accepted")) {
+      throw new Error(`Desktop send is not confirmed for ${threadId}. Do not resend: ${JSON.stringify(response)}`);
+    }
+    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 });
+    if (response?.navigated !== true) throw new Error(`Desktop did not confirm opening task ${threadId}`);
+  }
+
+  async wait(threadId, { timeoutMs = 240000, previousTurnId = null } = {}) {
+    const startedAt = this.now();
+    let cursor;
+    let turnId = null;
+    let text = "";
+    for (;;) {
+      const response = await this.request("wait_threads", {
+        targets: [{ threadId, hostId: "local", ...(cursor ? { afterCursor: cursor } : {}) }], timeoutMs: 0,
+      });
+      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;
+      const turn = poll.latestTurn;
+      const threadStatus = poll.thread.status?.type;
+      if (["systemError", "waitingOnApproval", "waitingOnUserInput"].includes(threadStatus)) {
+        return { threadId, turnId: turn?.id !== previousTurnId ? turn?.id ?? null : null, status: threadStatus, text: "", activity: [], errors: [], durationMs: this.now() - startedAt };
+      }
+      if (turn?.id && turn.id !== previousTurnId) {
+        turnId = turn.id;
+        if (poll.latestAssistantMessage?.turnId === turnId && poll.latestAssistantMessage?.phase === "final_answer") text = poll.latestAssistantMessage.text ?? text;
+        const status = turn.status;
+        if (RELEASE_STATUSES.has(status)) {
+          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 };
+      await this.sleep(Math.min(1500, timeoutMs - (this.now() - startedAt)));
+    }
+  }
+}
+
 export function createThreadDelivery({
   codex,
   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"
@@ -48,6 +217,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) {
@@ -55,6 +225,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);
@@ -80,7 +251,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 };