@minhspark/codex-mcp-bridge 1.13.0 → 1.13.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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

package/README.md

@@ -24,7 +24,11 @@ Call `delegate_to_codex` with `cwd`, `prompt`, and optionally `name`. The bridge
 
 `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.
+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
 
@@ -46,7 +50,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 +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 |
@@ -520,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.13.0",
+  "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/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.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";

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.1";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/index.mjs

@@ -25,7 +25,7 @@ import { BridgeSecurityPolicy } from "./security-policy.mjs";
 import { DesktopTaskDelivery } from "./thread-delivery.mjs";
 import { desktopTasksConfigured } from "./native-relay.mjs";
 
-const VERSION = "1.13.0";
+const VERSION = "1.13.1";
 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,
 });
@@ -212,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)
     ? ""
@@ -408,7 +408,7 @@ 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;
@@ -513,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);
@@ -754,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);
@@ -784,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) {
@@ -836,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

@@ -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.1";
 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,4 +1,4 @@
-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";
@@ -45,11 +45,59 @@ export class DesktopTaskDelivery {
     this.security = security;
     this.sleep = sleep;
     this.now = now;
+    this.threadOperations = new Map();
   }
 
   async request(operation, args) {
-    const response = await this.relay.requestDesktop(operation, args);
-    return response.result;
+    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 }) {
@@ -144,6 +192,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 +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) {
@@ -175,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);
@@ -200,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 };