@minhspark/codex-mcp-bridge 1.13.1 → 1.13.3

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.3] - 2026-09-05
+
+### Fixed
+
+- Verify the current saved project's identity, canonical directory, and task membership before reusing a Desktop creation receipt. Project drift is rejected; omitted recent/pinned metadata reports unverified assignment while preserving the task ID without resending or creating a duplicate.
+- Support `--version` and `-v` on every packaged command without starting servers, opening sockets, or mutating client configuration.
+- Preserve PowerShell's `$?` and conditional `&&`/`||` behavior as well as `$LASTEXITCODE` by invoking its footer through a script alias.
+
+### Added
+
+- Opt-in Bash, Zsh, and PowerShell installation footers for `npm install -g @minhspark/codex-mcp-bridge@latest`: first installation, changed version, unchanged version, failure, dry run, and unverifiable metadata are distinguished after npm's final output while preserving its exit code.
+- `codex-npm-footer-install` backs up and updates shell profiles idempotently, refuses unmanaged npm wrappers, supports removal, and explains how to reload an already-open terminal. Package installation does not change profiles automatically.
+
+### Verification
+
+- Regression coverage includes same-workspace project moves, deleted/repointed/replaced projects, incomplete Desktop snapshots, deadlines and authorization, shell argument boundaries, dry-run configuration, failure exit codes, metadata validation, and profile preservation.
+
+## [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

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,15 +20,21 @@ 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.
 
+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.
+
+Reusing a receipt also verifies that the saved project still has the same identity and exact directory, then checks the task's current project membership in Desktop's recent/pinned listing. A moved task or deleted/repointed project is rejected before sending or creating anything. A task omitted from that listing keeps its known ID and reports `project assignment: unverified`; stored receipt metadata is not presented as current membership. If a checkout has moved, edit the existing project's folder in Desktop, then inspect the existing task's workspace. Do not add another project or append the obsolete directory merely to satisfy a match.
+
 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.
+`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
 
@@ -118,7 +124,7 @@ Installing straight from the repository works the same way and needs no registry
 npm install -g git+https://github.com/buidangminh23/codex-mcp-bridge.git
 ```
 
-Either route puts four commands on your PATH — `codex-mcp-bridge` and `claude-mcp-bridge` are the two servers, `codex-mcp-bridge-install` and `claude-mcp-bridge-install` do the wiring in the steps below. Wherever this README runs `node scripts/install-claude-desktop.mjs`, an installed copy runs `codex-mcp-bridge-install` instead.
+Either route puts the bridge servers, configuration installers, native relay, and `codex-npm-footer-install` on your PATH. Wherever this README runs `node scripts/install-claude-desktop.mjs`, an installed copy runs `codex-mcp-bridge-install` instead. Every packaged command supports `--version` and `-v` without starting a server or changing configuration.
 
 #### Upgrading an install you already have
 
@@ -126,6 +132,33 @@ Either route puts four commands on your PATH — `codex-mcp-bridge` and `claude-
 
 Re-running `codex-mcp-bridge-install` is **not** required to upgrade, and before 1.11.1 it actively hurt: it replaced the whole entry, discarding `CODEX_BRIDGE_ALLOWED_THREADS`, any hand-added `CODEX_BRIDGE_THREAD_POLICY`, and resetting `CODEX_BRIDGE_ALLOWED_ROOTS` to the install directory. From 1.11.1 it keeps what is already there — an environment variable you pass wins, the existing value is the fallback, and `--reset` gives you the defaults back.
 
+#### Show the final npm installation result
+
+Enable the optional shell integration once after installing the package:
+
+```sh
+codex-npm-footer-install --shell zsh
+```
+
+Use `--shell bash` on Bash or `--shell powershell` in PowerShell 7. A source checkout can run `npm run install:footer -- --shell zsh`. The installer backs up existing profiles, preserves unrelated content, and prints a command to load the integration into the current terminal. New login and interactive Bash/Zsh shells load it automatically; PowerShell uses its current-user all-hosts profile. A terminal started before setup must run the printed reload command or open a new shell. Existing unmanaged `npm` functions are refused for review rather than overwritten. Use `--profile /absolute/path` to select a custom profile or `--remove` to remove the managed loader.
+
+The integration leaves the command unchanged:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest
+```
+
+| Measured result | Final line |
+| --- | --- |
+| No previous installation | `Successfully installed: @minhspark/codex-mcp-bridge v<version>` |
+| Version changed | `Successfully updated: @minhspark/codex-mcp-bridge v<before> -> v<after>` |
+| Same version after reinstalling | `Already up to date: @minhspark/codex-mcp-bridge v<version>` |
+| npm failed | `Failed to install: ... (exit code <code>). See npm error above.` |
+| Dry run | `Dry run completed: ... (no changes applied).` |
+| Mode or installed metadata cannot be verified | A warning instead of a success claim |
+
+The footer runs after npm finishes and keeps npm's output and exit code. It supports `install`/`i`, explicit global installation, one bridge package, dry-run flags, common install booleans, and a single `--prefix`. Other commands, multiple packages, unknown options, and machine-readable or silent output modes pass through without a footer. Installing the package itself does not alter shell profiles. A successful install confirms files on disk; restart the MCP client separately to load the new bridge code.
+
 **Clone it** — right if you intend to read, test or change the code:
 
 ```bash
@@ -510,7 +543,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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -27,7 +27,8 @@
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
     "codex-native-relay": "src/native-relay-companion.mjs",
-    "codex-native-relay-install": "scripts/install-native-relay.mjs"
+    "codex-native-relay-install": "scripts/install-native-relay.mjs",
+    "codex-npm-footer-install": "scripts/install-npm-footer.mjs"
   },
   "files": [
     "src",
@@ -53,6 +54,8 @@
     "install:relay": "node scripts/install-native-relay.mjs",
     "uninstall:relay": "node scripts/install-native-relay.mjs --remove",
     "install:agent": "node scripts/install-launch-agent.mjs",
+    "install:footer": "node scripts/install-npm-footer.mjs",
+    "uninstall:footer": "node scripts/install-npm-footer.mjs --remove",
     "uninstall:agent": "node scripts/install-launch-agent.mjs --uninstall",
     "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs src/native-relay-companion.mjs scripts/install-native-relay.mjs"
   },

package/scripts/install-claude-desktop.mjs

@@ -5,6 +5,9 @@ import { fileURLToPath } from "node:url";
 
 import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
 import { desktopTasksConfigured } from "../src/native-relay.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();

package/scripts/install-codex-mcp.mjs

@@ -5,6 +5,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { PLATFORM_LABEL, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);

package/scripts/install-native-relay.mjs

@@ -7,8 +7,11 @@ import { fileURLToPath } from "node:url";
 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";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
 
-const VERSION = "1.13.1";
+exitForVersionRequest(import.meta.url);
+
+const VERSION = "1.13.3";
 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/scripts/install-npm-footer.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+
+exitForVersionRequest(import.meta.url);
+
+const begin = "# codex-mcp-bridge npm footer: begin";
+const end = "# codex-mcp-bridge npm footer: end";
+const args = process.argv.slice(2);
+let shell = process.platform === "win32" ? "powershell" : path.basename(process.env.SHELL || "/bin/bash");
+const profiles = [];
+let remove = false;
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index];
+  if (arg === "--remove") remove = true;
+  else if (["--shell", "--profile"].includes(arg) && args[index + 1]) {
+    const value = args[++index];
+    if (arg === "--shell") shell = value;
+    else profiles.push(path.resolve(value));
+  } else throw new Error(`Unsupported argument: ${arg}`);
+}
+if (!["bash", "zsh", "powershell"].includes(shell)) throw new Error("Choose --shell bash, zsh, or powershell.");
+const footerDirectory = path.join(os.homedir(), ".config", "codex-mcp-bridge");
+const footerName = shell === "powershell" ? "npm-footer.ps1" : "npm-footer.sh";
+const footerPath = path.join(footerDirectory, footerName);
+if (!profiles.length) {
+  if (shell === "powershell") {
+    profiles.push(execFileSync("pwsh", ["-NoProfile", "-Command", "$PROFILE.CurrentUserAllHosts"], { encoding: "utf8" }).trim());
+  } else if (shell === "zsh") {
+    const directory = process.env.ZDOTDIR || os.homedir();
+    profiles.push(path.join(directory, ".zshrc"), path.join(directory, ".zprofile"));
+  } else {
+    profiles.push(path.join(os.homedir(), ".bashrc"));
+    profiles.push([".bash_profile", ".bash_login", ".profile"].map((name) => path.join(os.homedir(), name)).find((file) => fs.existsSync(file)) || path.join(os.homedir(), ".profile"));
+  }
+}
+const quote = (value) => shell === "powershell" ? `'${value.replaceAll("'", "''")}'` : `'${value.replaceAll("'", `'\\''`)}'`;
+const loader = shell === "powershell"
+  ? `if (Test-Path -LiteralPath ${quote(footerPath)}) { . ${quote(footerPath)} }`
+  : `if [ -n "\${BASH_VERSION:-}\${ZSH_VERSION:-}" ] && [ -r ${quote(footerPath)} ]; then . ${quote(footerPath)}; fi`;
+const edits = [...new Set(profiles)].map((file) => {
+  if (!path.isAbsolute(file)) throw new Error(`Profile path must be absolute: ${file}`);
+  if (fs.existsSync(file) && (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink())) throw new Error(`Refusing to replace a non-regular profile: ${file}`);
+  const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const newline = before.includes("\r\n") || shell === "powershell" ? "\r\n" : "\n";
+  const normalized = before.replaceAll("\r\n", "\n");
+  const begins = normalized.split(begin).length - 1;
+  const ends = normalized.split(end).length - 1;
+  if (begins !== ends || begins > 1) throw new Error(`Ambiguous managed footer block: ${file}`);
+  let unmanaged = normalized;
+  if (begins) {
+    const start = normalized.indexOf(begin);
+    const finish = normalized.indexOf(end, start);
+    if (finish < start) throw new Error(`Malformed managed footer block: ${file}`);
+    unmanaged = normalized.slice(0, start) + normalized.slice(finish + end.length).replace(/^\n/, "");
+  }
+  if (!remove && /^\s*(?:function\s+(?:global:)?)?npm\s*(?:\(\s*\))?\s*\{/im.test(unmanaged)) {
+    throw new Error(`An existing npm wrapper must be reviewed before installing the footer: ${file}`);
+  }
+  const after = (remove ? unmanaged : `${begin}\n${loader}\n${end}\n${unmanaged}`).replaceAll("\n", newline);
+  return { file, before, after };
+});
+
+if (!remove) {
+  const source = fs.readFileSync(fileURLToPath(new URL(`./${footerName}`, import.meta.url)), "utf8");
+  fs.mkdirSync(footerDirectory, { recursive: true, mode: 0o700 });
+  if (fs.existsSync(footerPath) && (!fs.lstatSync(footerPath).isFile() || fs.lstatSync(footerPath).isSymbolicLink())) throw new Error(`Unsafe footer destination: ${footerPath}`);
+  if (!fs.existsSync(footerPath) || fs.readFileSync(footerPath, "utf8") !== source) {
+    fs.writeFileSync(footerPath, source, { mode: 0o600 });
+  }
+}
+for (const { file, before, after } of edits) {
+  if (before === after) { console.log(`Unchanged: ${file}`); continue; }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (current !== before) throw new Error(`Profile changed during installation; rerun after reviewing it: ${file}`);
+  if (fs.existsSync(file)) {
+    const backup = `${file}.bak-npm-footer-${Date.now()}-${process.pid}`;
+    fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+    console.log(`Backup: ${backup}`);
+  }
+  const temporary = `${file}.tmp-npm-footer-${process.pid}`;
+  let temporaryCreated = false;
+  try {
+    fs.writeFileSync(temporary, after, { mode: 0o600, flag: "wx" });
+    temporaryCreated = true;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (temporaryCreated && fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+  console.log(`${remove ? "Removed" : "Installed"}: ${file}`);
+}
+console.log(remove
+  ? "Open a new shell to use npm without the footer."
+  : `Reload the current shell with: . ${quote(footerPath)}`);

package/scripts/npm-footer.ps1

@@ -0,0 +1,140 @@
+if ($MyInvocation.InvocationName -eq '.') {
+    Set-Alias -Name npm -Value $PSCommandPath -Scope Global
+    return
+}
+
+$npmArguments = @($args)
+$nativeNpm = Get-Command npm -CommandType Application, ExternalScript -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $nativeNpm) {
+    throw [System.Management.Automation.CommandNotFoundException]::new('The npm executable was not found on PATH.')
+}
+
+$matchesInstall = $npmArguments.Count -ge 3 -and $npmArguments[0] -cin @('install', 'i')
+$isGlobal = $false
+$targetCount = 0
+$prefixArguments = @()
+$dryRunOverride = $null
+for ($argumentIndex = 1; $matchesInstall -and $argumentIndex -lt $npmArguments.Count; $argumentIndex++) {
+    $argument = [string]$npmArguments[$argumentIndex]
+    if ($argument -cin @('-g', '--global', '--global=true')) {
+        $isGlobal = $true
+    } elseif ($argument -cmatch '^@minhspark/codex-mcp-bridge(?:@[^\s]+)?$') {
+        $targetCount++
+    } elseif ($argument -cin @('--no-fund', '--no-audit', '--force', '--ignore-scripts', '--foreground-scripts')) {
+        continue
+    } elseif ($argument -cin @('--dry-run', '--dry-run=true')) {
+        $dryRunOverride = $true
+    } elseif ($argument -cin @('--no-dry-run', '--dry-run=false')) {
+        $dryRunOverride = $false
+    } elseif ($argument -ceq '--prefix') {
+        $argumentIndex++
+        if ($argumentIndex -ge $npmArguments.Count -or -not $npmArguments[$argumentIndex] -or [string]$npmArguments[$argumentIndex] -clike '-*' -or $prefixArguments.Count) {
+            $matchesInstall = $false
+        } else {
+            $prefixArguments = @('--prefix', [string]$npmArguments[$argumentIndex])
+        }
+    } elseif ($argument -cmatch '^--prefix=(.+)$' -and -not $prefixArguments.Count) {
+        $prefixArguments = @($argument)
+    } else {
+        $matchesInstall = $false
+    }
+}
+
+if (-not $matchesInstall -or -not $isGlobal -or $targetCount -ne 1) {
+    $global:LASTEXITCODE = 0
+    & $nativeNpm @npmArguments
+    exit $LASTEXITCODE
+}
+
+$PSNativeCommandUseErrorActionPreference = $false
+$readVersion = {
+    param([string]$PackageRoot)
+    try {
+        $metadataPath = Join-Path $PackageRoot '@minhspark/codex-mcp-bridge/package.json'
+        if (-not [System.IO.File]::Exists($metadataPath)) {
+            return @{ Status = 'missing'; Version = $null }
+        }
+        $metadata = [System.IO.File]::ReadAllText($metadataPath) | ConvertFrom-Json -ErrorAction Stop
+        if ($metadata.name -cne '@minhspark/codex-mcp-bridge' -or $metadata.version -isnot [string] -or $metadata.version -cnotmatch '^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$') {
+            return @{ Status = 'unknown'; Version = $null }
+        }
+        return @{ Status = 'known'; Version = $metadata.version }
+    } catch {
+        return @{ Status = 'unknown'; Version = $null }
+    }
+}
+$readRoot = {
+    try {
+        $global:LASTEXITCODE = 0
+        $rootOutput = @(& $nativeNpm root --global @prefixArguments 2>$null)
+        if ($LASTEXITCODE -ne 0 -or $rootOutput.Count -ne 1) {
+            return $null
+        }
+        $packageRoot = ([string]$rootOutput[0]).Trim()
+        if (-not $packageRoot -or -not [System.IO.Path]::IsPathRooted($packageRoot)) {
+            return $null
+        }
+        return $packageRoot
+    } catch {
+        return $null
+    }
+}
+
+$dryRun = $dryRunOverride
+if ($null -eq $dryRun) {
+    try {
+        $global:LASTEXITCODE = 0
+        $configOutput = @(& $nativeNpm config get dry-run --global @prefixArguments 2>$null)
+        if ($LASTEXITCODE -eq 0 -and $configOutput.Count -eq 1) {
+            $configValue = ([string]$configOutput[0]).Trim()
+            if ($configValue -ceq 'true') {
+                $dryRun = $true
+            } elseif ($configValue -ceq 'false') {
+                $dryRun = $false
+            }
+        }
+    } catch {
+        $dryRun = $null
+    }
+}
+
+$beforeRoot = & $readRoot
+$before = @{ Status = 'unknown'; Version = $null }
+if ($beforeRoot) {
+    $before = & $readVersion $beforeRoot
+}
+
+$global:LASTEXITCODE = 0
+& $nativeNpm @npmArguments
+$npmExitCode = $LASTEXITCODE
+try {
+    if ($npmExitCode -ne 0) {
+        Write-Host "Failed to install: @minhspark/codex-mcp-bridge (exit code $npmExitCode). See npm error above."
+        exit $npmExitCode
+    }
+    if ($null -eq $dryRun) {
+        Write-Host 'Warning: npm completed, but installation mode could not be verified.'
+        exit $npmExitCode
+    }
+    if ($dryRun) {
+        Write-Host 'Dry run completed: @minhspark/codex-mcp-bridge (no changes applied).'
+        exit $npmExitCode
+    }
+    $afterRoot = & $readRoot
+    $after = @{ Status = 'unknown'; Version = $null }
+    if ($afterRoot) {
+        $after = & $readVersion $afterRoot
+    }
+    if ($after.Status -ne 'known' -or $before.Status -eq 'unknown' -or $beforeRoot -cne $afterRoot) {
+        Write-Host 'Warning: npm completed, but the installed @minhspark/codex-mcp-bridge version could not be verified.'
+    } elseif ($before.Status -eq 'missing') {
+        Write-Host "Successfully installed: @minhspark/codex-mcp-bridge v$($after.Version)"
+    } elseif ($before.Version -ceq $after.Version) {
+        Write-Host "Already up to date: @minhspark/codex-mcp-bridge v$($after.Version)"
+    } else {
+        Write-Host "Successfully updated: @minhspark/codex-mcp-bridge v$($before.Version) -> v$($after.Version)"
+    }
+} finally {
+    $global:LASTEXITCODE = $npmExitCode
+}
+exit $npmExitCode

package/scripts/npm-footer.sh

@@ -0,0 +1,81 @@
+_codex_bridge_installed_version() {
+  command node --input-type=module -e 'import fs from "node:fs"; const value = JSON.parse(fs.readFileSync(process.argv[1], "utf8")); if (value.name !== "@minhspark/codex-mcp-bridge" || typeof value.version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value.version)) process.exit(1); process.stdout.write(value.version);' "$1/@minhspark/codex-mcp-bridge/package.json" 2>/dev/null
+}
+
+npm() {
+  if [ "$#" -eq 0 ]; then command npm; return $?; fi
+  local bridge_command="${1-}" bridge_global=0 bridge_packages=0 bridge_supported=1
+  local bridge_dry_run=auto bridge_root= bridge_before= bridge_after= bridge_install_status=0
+  local bridge_after_root= bridge_mode=unknown bridge_before_verified=1
+  local -a bridge_arguments bridge_context
+  bridge_arguments=("$@")
+  bridge_context=(--global)
+  case "$bridge_command" in
+    install|i) shift ;;
+    *) command npm "${bridge_arguments[@]}"; return $? ;;
+  esac
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -g|--global|--global=true) bridge_global=1 ;;
+      @minhspark/codex-mcp-bridge|@minhspark/codex-mcp-bridge@?*) bridge_packages=$((bridge_packages + 1)) ;;
+      --dry-run|--dry-run=true) bridge_dry_run=true ;;
+      --no-dry-run|--dry-run=false) bridge_dry_run=false ;;
+      --no-fund|--no-audit|--force|--ignore-scripts|--foreground-scripts) ;;
+      --prefix=*)
+        if [ "${#bridge_context[@]}" -ne 1 ] || [ "$1" = --prefix= ]; then bridge_supported=0; break; fi
+        bridge_context+=("$1")
+        ;;
+      --prefix)
+        if [ "$#" -lt 2 ] || [ "${#bridge_context[@]}" -ne 1 ] || [ -z "$2" ]; then bridge_supported=0; break; fi
+        case "$2" in -*) bridge_supported=0; break ;; esac
+        bridge_context+=("$1" "$2")
+        shift
+        ;;
+      *) bridge_supported=0 ;;
+    esac
+    shift
+  done
+  if [ "$bridge_supported" -ne 1 ] || [ "$bridge_global" -ne 1 ] || [ "$bridge_packages" -ne 1 ]; then
+    command npm "${bridge_arguments[@]}"
+    return $?
+  fi
+  if [ "$bridge_dry_run" = auto ]; then
+    bridge_mode="$(command npm config get dry-run "${bridge_context[@]}" 2>/dev/null)" || bridge_mode=unknown
+  else
+    bridge_mode="$bridge_dry_run"
+  fi
+  if [ "$bridge_mode" = false ]; then
+    bridge_root="$(command npm root "${bridge_context[@]}" 2>/dev/null)" || bridge_root=
+    case "$bridge_root" in
+      /*)
+        if [ -e "$bridge_root/@minhspark/codex-mcp-bridge/package.json" ]; then
+          bridge_before="$(_codex_bridge_installed_version "$bridge_root")" || bridge_before_verified=0
+        fi
+        ;;
+      *) bridge_before_verified=0 ;;
+    esac
+  fi
+  command npm "${bridge_arguments[@]}" || bridge_install_status=$?
+  if [ "$bridge_install_status" -ne 0 ]; then
+    printf 'Failed to install: @minhspark/codex-mcp-bridge (exit code %s). See npm error above.\n' "$bridge_install_status" >&2
+  elif [ "$bridge_mode" = true ]; then
+    printf 'Dry run completed: @minhspark/codex-mcp-bridge (no changes applied).\n'
+  elif [ "$bridge_mode" != false ]; then
+    printf 'Warning: npm completed, but installation mode could not be verified.\n' >&2
+  else
+    bridge_after_root="$(command npm root "${bridge_context[@]}" 2>/dev/null)" || bridge_after_root=
+    case "$bridge_after_root" in
+      /*) bridge_after="$(_codex_bridge_installed_version "$bridge_after_root")" || bridge_after= ;;
+    esac
+    if [ -z "$bridge_after" ] || [ "$bridge_before_verified" -ne 1 ] || [ "$bridge_after_root" != "$bridge_root" ]; then
+      printf 'Warning: npm completed, but the installed @minhspark/codex-mcp-bridge version could not be verified.\n' >&2
+    elif [ "$bridge_after_root" = "$bridge_root" ] && [ "$bridge_after" = "$bridge_before" ]; then
+      printf 'Already up to date: @minhspark/codex-mcp-bridge v%s\n' "$bridge_after"
+    elif [ "$bridge_after_root" = "$bridge_root" ] && [ -n "$bridge_before" ]; then
+      printf 'Successfully updated: @minhspark/codex-mcp-bridge v%s -> v%s\n' "$bridge_before" "$bridge_after"
+    else
+      printf 'Successfully installed: @minhspark/codex-mcp-bridge v%s\n' "$bridge_after"
+    fi
+  fi
+  return "$bridge_install_status"
+}

package/src/claude-bridge.mjs

@@ -7,8 +7,11 @@ import { CodexAppServerClient } from "./app-server-client.mjs";
 import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { createThreadDelivery } from "./thread-delivery.mjs";
+import { exitForVersionRequest } from "./cli-version.mjs";
 
-const VERSION = "1.13.1";
+exitForVersionRequest(import.meta.url);
+
+const VERSION = "1.13.3";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/cli-version.mjs

@@ -0,0 +1,20 @@
+import { readFileSync, realpathSync, writeSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function exitForVersionRequest(entrypointUrl) {
+  if (!process.argv.slice(2).some((arg) => arg === "--version" || arg === "-v")) return;
+  if (!process.argv[1]) return;
+
+  let entrypoint;
+  try {
+    entrypoint = realpathSync(process.argv[1]);
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return;
+    throw error;
+  }
+  if (entrypoint !== realpathSync(fileURLToPath(entrypointUrl))) return;
+
+  const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  writeSync(process.stdout.fd, `${version}\n`);
+  process.exit(0);
+}

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,13 @@ 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";
+import { exitForVersionRequest } from "./cli-version.mjs";
 
-const VERSION = "1.13.1";
+exitForVersionRequest(import.meta.url);
+
+const VERSION = "1.13.3";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -111,29 +114,37 @@ 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);
-      notes.push("opened in Codex Desktop while the task runs");
+      await desktopTasks.open(created.threadId, { deadline });
+      notes.push(created.reused ? "opened the existing task in Codex Desktop" : "opened in Codex Desktop while the task runs");
     } catch (err) {
-      notes.push(`task was accepted; opening its page failed: ${err.message}`);
+      notes.push(`${created.reused ? "existing task retained" : "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,
+    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}`,
+    ...(created.projectAssignmentStatus === "unverified"
+      ? [`expected projectId: ${created.expectedProjectId}`, `expected project: ${created.expectedProjectName ?? "(unnamed)"}`, "project assignment: unverified", created.projectAssignmentNote]
+      : [`projectId: ${created.projectId}`, `project: ${created.projectName ?? "(unnamed)"}`, ...(created.projectAssignmentStatus === "verified" ? ["project assignment: verified in Desktop's current listing"] : [])]),
+    "permissions: Codex Desktop settings; no external app-server writer",
+    ...(created.promptChanged ? [created.projectAssignmentStatus === "unverified"
+      ? "The edited brief was not sent. Inspect this task's project assignment before continuing it."
+      : "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 (created.projectAssignmentStatus === "unverified") return textResult([...lines, "status: existing task retained; project assignment needs inspection"].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);
@@ -293,7 +304,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 +394,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,6 +419,7 @@ server.registerTool(
     },
   },
   async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
+    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;
@@ -416,18 +428,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 +499,7 @@ server.registerTool(
       } catch (err) {
         return failure(err);
       }
-    });
+    }, { deadline }).catch(failure);
   },
 );
 
@@ -636,8 +648,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);
@@ -723,9 +736,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);

package/src/native-relay-companion.mjs

@@ -19,8 +19,11 @@ import {
   decodeNativeToolResult,
 } from "./native-relay.mjs";
 import { IS_WINDOWS, PLATFORM_LABEL } from "./platform.mjs";
+import { exitForVersionRequest } from "./cli-version.mjs";
 
-const VERSION = "1.13.1";
+exitForVersionRequest(import.meta.url);
+
+const VERSION = "1.13.3";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message) {

package/src/thread-delivery.mjs

@@ -2,6 +2,7 @@ import { NativeDesktopRelay, desktopTaskSocketPath, desktopTasksConfigured } fro
 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,37 +36,49 @@ 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) {
+  async request(operation, args, { deadline } = {}) {
     try {
-      const response = await this.relay.requestDesktop(operation, args);
+      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) {
+  async withThread(threadId, operation, { deadline } = {}) {
     const previous = this.threadOperations.get(threadId) ?? Promise.resolve();
-    const current = previous.catch(() => {}).then(operation);
+    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 current;
+      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 {
-      if (this.threadOperations.get(threadId) === current) this.threadOperations.delete(threadId);
+      clearTimeout(timer);
     }
   }
 
@@ -97,34 +111,109 @@ export class DesktopTaskDelivery {
       }
       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" };
+    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 create({ cwd, prompt, name, model, effort }) {
+  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);
+    const assignment = await this.receiptProjectAssignment(receipt, cwd, { deadline });
+    return { threadId: receipt.threadId, name: thread.title ?? receipt.name ?? "(unnamed)", cwd, ...assignment, backend: NATIVE_BACKEND, reused: true, promptChanged: receipt.promptHash !== promptHash };
+  }
+
+  async receiptProjectAssignment(receipt, cwd, { deadline }) {
+    let project;
+    try {
+      const listed = await this.request("list_projects", {}, { deadline });
+      if (!Array.isArray(listed?.projects)) throw new Error("Desktop returned no project list");
+      project = matchDesktopProject(listed.projects, cwd);
+      if (receipt.projectId && receipt.projectId !== project.projectId) throw new Error("The saved project identity changed for this directory");
+    } catch (err) {
+      throw new Error(`Existing Desktop task ${receipt.threadId}'s saved project could not be verified: ${err.message}. No prompt was resent and no duplicate task was created. Inspect this existing task and its project settings.`, { cause: err });
+    }
+    const unverified = (reason) => ({
+      expectedProjectId: project.projectId,
+      expectedProjectName: project.label,
+      projectAssignmentStatus: "unverified",
+      projectAssignmentNote: `${reason} The task's current project assignment is unverified. Its workspace and existing ID were retained; no prompt was resent and no duplicate task was created. Inspect this task in Codex Desktop.`,
+    });
+    let snapshot;
+    try {
+      snapshot = await this.request("list_threads", { limit: 50 }, { deadline });
+      if (!Array.isArray(snapshot?.threads) || !Array.isArray(snapshot?.pinnedThreads)) throw new Error("Desktop returned an invalid thread list");
+      if (snapshot.unavailableHosts?.some((host) => host === "local" || host?.hostId === "local")) throw new Error("The local Desktop host is unavailable");
+    } catch (err) {
+      return unverified(`Desktop's recent/pinned listing could not be confirmed: ${err.message}.`);
+    }
+    const observed = [...snapshot.pinnedThreads, ...snapshot.threads].filter((thread) => thread?.id === receipt.threadId && thread.kind === "codex" && thread.hostId === "local");
+    if (observed.length === 0) return unverified("This task is absent from Desktop's recent/pinned listing.");
+    for (const thread of observed) {
+      if (thread.projectId !== undefined && thread.projectId !== project.projectId) throw new Error(`Existing Desktop task ${receipt.threadId}'s project assignment changed. No prompt was resent and no duplicate task was created. Inspect its assignment in Codex Desktop.`);
+      if (thread.cwd) {
+        this.security.assertCwd(thread.cwd);
+        if (path.relative(cwd, realpathSync.native(thread.cwd))) throw new Error(`Existing Desktop task ${receipt.threadId}'s listed workspace changed. No prompt was resent and no duplicate task was created.`);
+      }
+    }
+    if (observed.some((thread) => thread.projectId === undefined || !thread.cwd)) return unverified("Desktop's listing omitted this task's project or workspace metadata.");
+    return { projectId: project.projectId, projectName: project.label, projectAssignmentStatus: "verified" };
+  }
+
+  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);
@@ -135,14 +224,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")) {
@@ -151,8 +240,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}`);
   }
 
@@ -161,10 +250,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;
@@ -181,7 +278,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)));
     }
   }