npm - @minhspark/codex-mcp-bridge - Versions diffs - 1.22.3 → 1.22.4 - Mend

@minhspark/codex-mcp-bridge 1.22.3 → 1.22.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/.codex-plugin/plugin.json +1 -1
package/CHANGELOG.md +18 -0
package/README.md +77 -380
package/docs/daily-handoffs.md +18 -0
package/package.json +1 -1
package/plugin.json +1 -1
package/scripts/install-native-relay.mjs +1 -1
package/src/claude-bridge.mjs +30 -19
package/src/claude-project-discovery.mjs +25 -0
package/src/claude-session-creation.mjs +43 -7
package/src/index.mjs +1 -1
package/src/native-relay-companion.mjs +1 -1
package/src/platform.mjs +7 -3
package/src/project-policy.mjs +9 -0

package/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.22.3",
+  "version": "1.22.4",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,24 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 ## [Unreleased]
+## [1.22.4] - 2026-10-19
+### Fixed
+- Discover moved Claude project directories for authorized new Desktop conversations using the workspace resolver and shared project policy. Report candidates separately from live sessions and resumable tasks; preserve original task IDs, account checks, directory bindings, revocations and exact new-session verification.
+- Reject ambiguous workspace replacements during Claude project discovery and recheck the saved project before opening, trusting and submitting, including restored requests. Preserve original-path revocations across ancestor junction changes.
+- Retain creation scope bindings when an error occurs after opening the native composer, so the original request remains inspectable without reopening or resending.
+### Verification
+- CI passed on Windows, macOS and Linux with Node 22 and 24, including project revocation, source replacement, restored-request and receipt-binding regressions.
+- A live Windows Desktop peer message received its correlated Claude reply, and the reverse Claude message arrived in the originating Codex chat with the same nonce. Account, process, task, project and permission checks remained enabled.
+### Upgrade notes
+- Existing supervisors load updated source when safe. Relocation discovery requires the shared project policy and does not make a dormant or moved task a verified live recipient.
+- Peer sender attribution requires a verified live Claude Code task. Native composer creation remains a separate operation; it does not substitute for a peer message or its native sender label. This release does not establish Cowork or Dispatch connectivity.
 ## [1.22.3] - 2026-10-15
 ### Fixed

package/README.md CHANGED Viewed

@@ -4,8 +4,6 @@
 <h1 align="center">codex-mcp-bridge</h1>
-Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [Windows setup](docs/new-windows-setup.md), [macOS setup](docs/new-macos-setup.md), and [project onboarding](docs/project-onboarding.md).
 <p align="center">
   <a href="https://www.npmjs.com/package/@minhspark/codex-mcp-bridge"><img src="https://img.shields.io/npm/v/@minhspark/codex-mcp-bridge?logo=npm&amp;color=CB3837" height="20" alt="npm" /></a>
   <a href="https://www.npmjs.com/package/@minhspark/codex-mcp-bridge"><img src="https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads.svg" height="20" alt="npm downloads" /></a>
@@ -21,117 +19,23 @@ Send prompts and replies between **Claude and Codex**, keeping each conversation
 https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
-## Release notifications
-To receive new release notifications, open [this repository](https://github.com/buidangminh23/codex-mcp-bridge), select **Watch → Custom → Releases**, then click **Apply**. Choose GitHub or email delivery in your [notification settings](https://github.com/settings/notifications).
-Starring the repository or downloading/installing a package does not subscribe you to release notifications. Notifications do not update your installed copy; follow the installation instructions to update.
-[View release notes](https://github.com/buidangminh23/codex-mcp-bridge/releases).
 ## Installation
-### ChatGPT plugin
-[Open Codex Bridge](https://codex-mcp-bridge.buidangminh23.chatgpt.site) to connect ChatGPT to **your own computer**. Each ChatGPT account pairs its own connector and can access only the local project directories selected during setup. Native Desktop mode supports Windows and macOS. Keep Codex Desktop and the connector running.
-Install Node.js 22+, sign in to Codex Desktop and Claude Desktop, and save the intended project in Codex Desktop. The connector pins both local account identities and stops if either account changes. Install the native relay using the platform instructions below, then pair:
-Windows PowerShell:
-```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest
-codex-native-relay-install.cmd --desktop-tasks
-codex-sites-connector.cmd --pair --site https://codex-mcp-bridge.buidangminh23.chatgpt.site --roots "C:\Projects\YourProject"
-```
-macOS Terminal:
 ```bash
 npm install -g @minhspark/codex-mcp-bridge@latest
-codex-native-relay-install --desktop-tasks
-codex-sites-connector --pair --site https://codex-mcp-bridge.buidangminh23.chatgpt.site --roots "$HOME/YourProject"
-```
-Open the pairing URL printed in the terminal, sign in with the ChatGPT account that will use the plugin, and choose **Connect this computer**. The Site owner can install its provisioned plugin from **Plugins → Personal → Created by you**. To restart an already paired connector, run `codex-sites-connector` (`codex-sites-connector.cmd` on Windows). To replace the paired computer, use **Disconnect existing computer** on a fresh pairing page first.
-The public MCP endpoint is `https://codex-mcp-bridge.buidangminh23.chatgpt.site/mcp`; it uses Sign in with ChatGPT. A plugin compatibility ZIP is attached to the [1.21.0 release](https://github.com/buidangminh23/codex-mcp-bridge/releases/tag/v1.21.0) for manual import in clients that support plugin packages. ChatGPT personal accounts cannot share their Sites-provisioned plugin directly by invitation or share link. A public directory listing requires verified developer identity and OpenAI review; this release does not claim directory approval. See [OpenAI's Sites plugin access rules](https://help.openai.com/en/articles/20001547-hosting-a-plugin-with-chatgpt-sites).
-Use a semicolon between multiple Windows roots or a colon on macOS. The relay's executor must belong to an allowed project. Credentials and operation receipts stay in the current OS user's private `~/.codex/sites-bridge` directory. The connector uses outbound HTTPS; no public port or tunnel is required.
-The plugin can list projects, read conversations, create an authorized task, and continue an existing task. Requests return an operation ID; read its result before sending more work. An uncertain send is never automatically repeated. Disconnecting blocks future dispatch and cancels queued work; tasks already sent to Desktop keep running. Linux/WSL users can use the existing CLI bridge below; the hosted connector requires native Codex Desktop.
-The hosted Worker source and database migrations are in `sites/codex-bridge`. The portable `plugin.json`, `mcp.json`, compatibility manifest, and workflow skill are included in the npm package and this repository. The plugin ZIP has its portable manifest directly at the archive root.
-#### Hosted data
-The hosted service is operated by Bui Dang Minh and runs on OpenAI Sites. Sign in with ChatGPT supplies a Site-scoped user identifier; the Worker uses it to bind a connector and isolate each account's operation records. The Worker does not use profile names or email addresses. OpenAI handles sign-in and hosting independently.
-The database stores the account identifier, a connector identifier and token hash, connection timestamps, requested tool arguments (including task prompts), and the returned Desktop results. These records support polling and duplicate-send prevention. The service operator can access this database. Data is sent only to the paired computer and returned to the requesting account through the authenticated service. A local connector stores its credentials, account fingerprints and operation receipts in the OS user's private configuration directory.
-Requests expire for dispatch after two minutes. Expiry is not data deletion: operation records remain stored to preserve dispatch history. Disconnecting revokes the device token and cancels undispatched work; it does not erase operation history or stop tasks already running in Desktop. For deletion or privacy requests, contact the operator through the repository's support link, without posting private prompts, account credentials or conversation content in a public issue. No advertising or analytics collection is implemented by this hosted Worker.
-### GitHub Packages
-The repository-linked copy is [@buidangminh23/codex-mcp-bridge](https://github.com/buidangminh23/codex-mcp-bridge/packages)
-on npm.pkg.github.com. The npmjs.com package remains @minhspark/codex-mcp-bridge.
-GitHub's npm registry requires authentication with a classic token with read:packages,
-even for public packages. Authenticate locally and never commit a token:
-```bash
-npm login --scope=@buidangminh23 --registry=https://npm.pkg.github.com --auth-type=legacy
-npm install -g @buidangminh23/codex-mcp-bridge --registry=https://npm.pkg.github.com
-```
-Then follow the platform registration and verification instructions below.
-[Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [Claude Code registration](#register-claude-code) · [Verify](#verify-the-installation) · [Troubleshooting](#troubleshooting)
-Choose the mode for the conversations you want to connect:
-| Platform | Mode | Required clients |
-|---|---|---|
-| Windows / macOS | Native Desktop tasks | Signed-in Codex Desktop and a Claude **Code** session in Claude Desktop |
-| Linux / WSL | CLI / app-server | Signed-in Codex CLI and a running Claude Code CLI session |
-The bridge requires **Node.js 22+**; Node 24 LTS is a suitable starting point. If Node is already managed by a version manager, use that installation. Install the bridge under the same OS user as the clients. A global npm install does not require cloning this repository.
-To opt a machine you administer into **Full access + Never**, run `codex-mcp-bridge-install --full-access` when registering the bridge (`codex-mcp-bridge-install.cmd --full-access` in PowerShell). The installer sets global Codex defaults for old and new projects, repairs or creates the managed policy with both `read-only` and `danger-full-access`, and records the choice so the bridge can restore it if the files drift later. Windows UAC, macOS administrator authentication, or Linux polkit/sudo may be required for the system policy. Normal installation does not change Codex permissions. Run `codex doctor --summary --ascii` after setup; existing Desktop tasks may need to be reopened to load the new permissions.
-If the bridge is already registered, `codex-full-access` (`codex-full-access.cmd` in PowerShell) enables the same settings without replacing that registration. The bridge reads the saved choice when it starts.
-For Desktop mode, install [Codex Desktop](https://developers.openai.com/codex/app) and [Claude Desktop](https://claude.com/download), sign in, and save the intended local project in Codex Desktop. Open that same directory in Claude Desktop's Code tab. A normal Claude chat is not a Code session.
-#### Native relay pipe forwarding
-After running the native relay installer, add this setting to its **existing** entry in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`):
-```toml
-[mcp_servers.codex-native-relay]
-env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
 ```
-Keep the entry's `command`, `args`, and other settings; append the variable name if `env_vars` already contains names. Use your configured server name if you set `CODEX_NATIVE_RELAY_NAME`. This forwards the running Desktop app-server's pipe path without saving its temporary value. The installer uses `codex mcp add`, which does not provide an `env_vars` option, and refuses to reset entries with custom transport settings, including `env_vars`.
+Requires **Node.js 22+**. In Windows PowerShell, use `npm.cmd` instead of `npm`. Run the same command to update; reconnect MCP servers if their settings or installation paths changed.
-Reconnect `codex-native-relay` in the existing Desktop task, or restart Codex Desktop after active work finishes. Verify `native_relay_status` from that task. Without forwarding, Desktop setups whose pipe is absent from app-server command-line configuration can expose status tools while reporting native pipe unavailable and relay sockets not listening; a connected Claude bridge alone does not establish native delivery.
+[Windows](#windows-powershell) · [macOS](#macos-terminal) · [Linux / WSL](#linux--wsl-bash) · [ChatGPT plugin](#chatgpt-plugin)
 ### Windows (PowerShell)
-Install Node and a native Codex executable with WinGet:
+Install and sign in to [Codex Desktop](https://developers.openai.com/codex/app) and [Claude Desktop](https://claude.com/download). Save the project in Codex Desktop and open the same directory in Claude Desktop's **Code tab**. Have the Codex and Claude Code CLIs available.
-```powershell
-winget install --id OpenJS.NodeJS.LTS --exact
-winget install --id OpenAI.Codex --exact
-```
-Open a **new PowerShell window** so it receives the updated PATH, then run:
+If the Codex CLI is missing, run `winget install --id OpenAI.Codex --exact`, open a new terminal, then run `codex.exe login`.
 ```powershell
-node --version
-npm.cmd --version
-codex.exe --version
-codex.exe login
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest
 $env:CODEX_EXE = (Get-Command codex.exe).Source
 codex-native-relay-install.cmd --desktop-tasks
 codex-mcp-bridge-install.cmd --desktop-tasks
@@ -139,107 +43,44 @@ $env:CODEX_BRIDGE_DESKTOP_TASKS = "1"
 claude-mcp-bridge-install.cmd
 ```
-The `.cmd` suffix selects npm's Windows launchers without changing PowerShell's execution policy. `CODEX_EXE` must point to the real `codex.exe`, not an npm `.ps1` shim. If WinGet is unavailable, install [App Installer](https://learn.microsoft.com/en-us/windows/package-manager/winget/) or use the vendors' installers.
-Continue with [Claude Code registration](#register-claude-code), then [verification](#verify-the-installation).
+Next: [register Claude Code](#register-claude-code), add [relay pipe forwarding](#native-relay-pipe-forwarding), then [verify](#verify-the-installation).
 ### macOS (Terminal)
-With [Homebrew](https://brew.sh/) installed:
+Install and sign in to Codex Desktop and Claude Desktop. Save the project in Codex Desktop and open the same directory in Claude Desktop's **Code tab**.
 ```bash
-brew install node@24
-export PATH="$(brew --prefix node@24)/bin:$PATH"
-node --version
-npm --version
-npm install -g @openai/codex@latest @minhspark/codex-mcp-bridge@latest
-codex --version
+npm install -g @openai/codex@latest
 codex login
 codex-native-relay-install --desktop-tasks
 codex-mcp-bridge-install --desktop-tasks
 CODEX_BRIDGE_DESKTOP_TASKS=1 claude-mcp-bridge-install
 ```
-Add the same Node PATH line to `~/.zshrc` if this is your Node installation; use `~/.bashrc` for Bash. If Homebrew is not installed, the [Node.js installer](https://nodejs.org/en/download) is another option; skip the two Homebrew lines after installing it.
-Keep the bootstrap enabled on a first relay install: it creates the executor required by native delivery. `--no-bootstrap` is for an already configured executor. On macOS, the relay installer selects the runtime bundled with Codex Desktop for native app authentication.
-Continue with [Claude Code registration](#register-claude-code), then [verification](#verify-the-installation).
-### Linux / WSL (Bash)
-Use a Linux terminal with `curl`, `unzip`, and Bash available. This example uses [fnm](https://github.com/Schniz/fnm#installation) to install Node without system-wide npm permissions:
-```bash
-curl -fsSL https://fnm.vercel.app/install | bash
-```
-Open a new Bash terminal so fnm's shell setup loads, then run:
-```bash
-eval "$(fnm env --use-on-cd --shell bash)"
-fnm install 24
-fnm default 24
-fnm use 24
-node --version
-npm --version
-npm install -g @openai/codex@latest @minhspark/codex-mcp-bridge@latest
-codex login
-curl -fsSL https://claude.ai/install.sh | bash
-export PATH="$HOME/.local/bin:$PATH"
-claude --version
-CODEX_BRIDGE_DESKTOP_TASKS=0 claude-mcp-bridge-install
-```
-Start `claude` once and complete sign-in, then exit back to the shell. Register the forward bridge below, then reopen Claude or reconnect its MCP server:
-```bash
-bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
-claude mcp add --scope user codex-bridge \
-  -e CODEX_BIN="$(command -v codex)" \
-  -e CODEX_BRIDGE_DESKTOP_TASKS=0 \
-  -e CODEX_BRIDGE_AUTOSTART=1 \
-  -e CODEX_BRIDGE_THREAD_POLICY=roots \
-  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME" \
-  -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
-```
-Use an existing writable project under your home directory, or replace `$HOME` in the allowed roots with the intended project directories. Keep both CLI clients running under the same Linux user. The bridge starts its local app-server on demand; no native relay installer is needed. This mode does not provide native Desktop project assignment. WSL and Windows have separate paths and client registrations; use the Windows instructions to connect Windows Desktop tasks.
+Keep bootstrap enabled on the first relay install. Next: [register Claude Code](#register-claude-code), add [relay pipe forwarding](#native-relay-pipe-forwarding), then [verify](#verify-the-installation).
 ### Register Claude Code
-**Claude Desktop configuration and Claude Code's MCP registry are separate.** If the sending Code session does not have `codex-bridge`, register it below. These are first-registration commands; if `claude mcp get codex-bridge` already returns an entry, preserve its custom environment and access settings when updating it.
-Install the Claude Code CLI if `claude --version` is unavailable. The [official setup guide](https://code.claude.com/docs/en/setup) provides these native installers:
-**Windows PowerShell:**
-```powershell
-irm https://claude.ai/install.ps1 | iex
-```
-**macOS / Linux:**
-```bash
-curl -fsSL https://claude.ai/install.sh | bash
-```
+Claude Desktop and Claude Code have separate MCP registrations. If `claude --version` is unavailable, [install Claude Code](https://code.claude.com/docs/en/setup) first. For a new registration, replace the example project path below with the actual directory. Preserve custom settings if `codex-bridge` is already registered.
-Open a new terminal after installation. Linux users who completed the preceding section are already registered. For **Windows Desktop mode**:
+<details>
+<summary>Windows PowerShell</summary>
 ```powershell
 $bridgeRoot = Join-Path ((npm.cmd root -g).Trim()) '@minhspark/codex-mcp-bridge'
-$nodeBin = (Get-Command node.exe).Source
-$codexBin = (Get-Command codex.exe).Source
 claude mcp add --scope user codex-bridge `
-  -e "CODEX_BIN=$codexBin" `
+  -e "CODEX_BIN=$((Get-Command codex.exe).Source)" `
   -e CODEX_BRIDGE_DESKTOP_TASKS=1 `
   -e CODEX_BRIDGE_AUTOSTART=0 `
   -e CODEX_BRIDGE_THREAD_POLICY=roots `
-  -e "CODEX_BRIDGE_ALLOWED_ROOTS=$env:USERPROFILE" `
-  -- $nodeBin (Join-Path $bridgeRoot 'src/mcp-supervisor.mjs') index.mjs
+  -e "CODEX_BRIDGE_ALLOWED_ROOTS=C:\Projects\YourProject" `
+  -- (Get-Command node.exe).Source (Join-Path $bridgeRoot 'src/mcp-supervisor.mjs') index.mjs
 ```
-For **macOS Desktop mode**:
+</details>
+<details>
+<summary>macOS Terminal</summary>
 ```bash
 bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
@@ -248,249 +89,105 @@ claude mcp add --scope user codex-bridge \
   -e CODEX_BRIDGE_DESKTOP_TASKS=1 \
   -e CODEX_BRIDGE_AUTOSTART=0 \
   -e CODEX_BRIDGE_THREAD_POLICY=roots \
-  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME" \
+  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
   -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
 ```
-These examples allow projects under the current user's home. For projects elsewhere, supply their actual absolute directories, separated by `;` on Windows or `:` on macOS/Linux. `--scope user` makes the registration available across projects; it does not override the allowed roots.
-### Verify the installation
-For Desktop project onboarding, both MCP entry points expose `inspect_bridge_project` (read-only) and `prepare_bridge_project` (user-selected workspace trust plus shared messaging grant). Setup preserves unrelated settings, backs up changes, respects revocations, and resolves registered worktrees to their primary repository. It does not approve tools or claim live connectivity. `CODEX_BRIDGE_PROJECT_POLICY` must explicitly name the shared policy. See [project onboarding and independent optional native settings integration](docs/project-onboarding.md). `node scripts/bridge-projects.mjs register-card-settings` registers the optional card-extension native settings integration; the bridge never depends on that extension.
-Check registration from a terminal; on Windows use `codex.exe` if `codex` resolves to a blocked PowerShell shim:
-```bash
-node --version
-codex --version
-claude --version
-claude mcp get codex-bridge
-codex mcp get claude-bridge
-```
-For Windows/macOS Desktop mode, also run `codex mcp get codex-native-relay`. Reconnect the affected MCP servers in the **existing** client tasks; Claude Code exposes them through `/mcp`. If a client has no reconnect control, restart that client after its active work finishes.
-Ask the active tasks to run these **MCP tools**, not shell commands:
+</details>
-| Where | Tool | Expected result |
-|---|---|---|
-| Claude Code | `codex_bridge_status` | Current runtime; native relay and saved projects available in Desktop mode, or a working app-server in CLI mode |
-| Codex | `claude_bridge_status` | Current runtime and the intended Claude session policy |
-| Codex Desktop only | `native_relay_status` | Account relay listening and native tools available |
-The registered supervisor should report auto-reload enabled. Next, list the intended destination with `list_codex_threads` or `list_claude_sessions`, then send a short message and verify its reply. A package version or a running process alone does not establish successful delivery.
-## Use
-| Direction | Tools |
-|---|---|
-| Continue unfinished Codex work | Verify the original `threadId`, then `send_to_codex_thread` |
-| Receive a reply after a Desktop send times out | `wait_codex_reply` with the original `deliveryId`; repeat bounded waits without sending again |
-| Codex → Claude | `list_claude_sessions`, then `send_to_claude_session` |
-| Start independent Codex work | `delegate_to_codex` or `start_codex_thread` with `cwd`, initial `prompt`, and a fresh UUID `requestId` in Desktop mode |
+Separate multiple allowed directories with `;` on Windows or `:` on macOS/Linux.
-Example requests:
+### Native relay pipe forwarding
-- **In Claude:** “For each independent new task or feature, create a new Codex conversation and send the initial brief there. Continue unfinished work in its original conversation.”
-- **In Claude:** “Send this review request to my existing Codex task in this project and wait for its reply.”
-- **In Codex:** “Send this result to my Claude Desktop Code session in this project and confirm its reply.”
+Add this to the relay's **existing** entry in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`), keeping its `command`, `args`, and other settings:
-Use the exact project directory and destination task. If several Claude sessions match, specify the task ID. A `reply_received` receipt confirms a reply; a timeout does not mean the task stopped, so inspect it before retrying.
-Desktop sends and creation keep each call bounded to at most 40 seconds, including preflight and dispatch. Creation tools return a durable `deliveryId` once the fresh task is confirmed. `send_to_codex_thread` prepares its observation receipt before dispatch: a lost acknowledgement returns `deliveryStatus=unconfirmed`, not a claim of acceptance. On `nextAction=wait_codex_reply`, continue with that read-only tool until completion, a verification error, a request for user input, or cancellation. Reuse the same ID after reconnecting; do not resend the prompt. A receipt only permits observation and never grants access: original sender/accounts and current project permissions are checked again. An existing-thread receipt keeps the exact pre-send rollout boundary; a creation receipt requires the exact `create_thread` dispatch, executor, prompt and confirmed fresh thread ID. Unrelated turns cannot satisfy either receipt. Receipts live in `bridge-reply-receipts` under the configured Codex home and contain the prompt for correlation; keep them private. Creation deduplication receipts retain the original reply ID across retries, including edited briefs. Old creation receipts without a reply binding still prevent duplicates but require inspection; the bridge does not invent a binding retrospectively. This is continuation across bounded tool calls, not an unattended push service after Claude stops running.
-An explicit request for a new conversation, or standing user instructions such as the example above, authorizes creation for independent work. Keep fixes, clarifications and results for unfinished work in its original conversation. A completed assistant turn does not by itself mean the whole task is finished; matching a project or finding a recent task does not make it the right destination for new work.
-In Desktop mode, generate a fresh UUID `requestId` for each independent task and retain it on every retry of that creation. Different request IDs create separate tasks even with the same directory, title and prompt. The same ID recovers the original receipt after a bridge restart; an edited title or prompt is not resent. Continue that task with its returned `threadId`. Pending or uncertain creation remains blocked: inspect the original receipt/task instead of changing the ID to retry.
-For backward compatibility, calls without `requestId` retain the previous deduplication by directory and explicit title (or exact prompt when no title is supplied). They can return an older task with the same title. Use a fresh request ID for independent new work; keep the old call shape when recovering an earlier legacy creation. Legacy app-server mode rejects `requestId` before creating anything because durable creation deduplication is only supported through Desktop native delivery.
-The sending tools ask agents to write each prompt in English with these sections, dropping any that do not apply: `Goal`, `Context`, `Task`, `Scope`, `Constraints`, `Done when`, `Reply format`. The first line names the sender, the project and the purpose. Text the user supplied is sent unchanged.
-```text
-[From Claude Code · my-app · edit coordination]
-## Goal
-Avoid conflicting edits while Claude Code patches `src/export.ps1`.
-## Task
-1. Do not modify `src/export.ps1` or `README.txt` until told otherwise.
-2. Write any unsaved edits to those files to disk now.
-## Reply format
-Exactly one line: `DONE — changed: <files>` or `DONE — no changes`.
-```
-## Important behavior
-- Desktop mode uses the native relay and the apps' permissions; it does not fall back to an external app-server.
-- Account switches are checked before delivery. Missing identity or incompatible permissions block sending.
-- Access settings are preserved on reinstall. Review allowed workspaces before enabling the bridge.
-- CLI/app-server setup, all tools, and advanced settings are in the [reference](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md).
-## Update
-```bash
-npm install -g @minhspark/codex-mcp-bridge@latest
+```toml
+[mcp_servers.codex-native-relay]
+env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
 ```
-Supervisor-based installs reload compatible updates when idle. Older installs or changed MCP settings need a one-time reconnect; see [upgrade instructions](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#upgrading-an-install-you-already-have).
+Append the variable name if `env_vars` already exists. Reconnect the relay in Codex Desktop after editing.
-On Windows, use `npm.cmd` if PowerShell blocks `npm.ps1`. Upgrade the Codex CLI with the same manager used to install it: `winget upgrade --id OpenAI.Codex --exact` for the Windows path above, or `npm install -g @openai/codex@latest` for the macOS/Linux path. Updating the bridge does not update the clients.
-If Node moved or a registration still points at an old installation, rerun the corresponding platform registration steps and reconnect its MCP server. Preserve existing access settings. Use `--no-bootstrap` only when refreshing a relay that already has an executor.
-## Troubleshooting
-### Download or installation failed
+### Linux / WSL (Bash)
-| Error / symptom | What to check and how to fix it |
-|---|---|
-| `node`, `npm`, or a bridge command is not found | Open a new terminal. Check `node --version` and `npm --version`. On Windows run `Get-Command node.exe` and `npm.cmd prefix -g`; the global prefix must be on PATH. On macOS/Linux run `command -v node` and `npm prefix -g`; its `bin` directory must be on PATH. Reload your Node version manager's shell setup if used. |
-| `EBADENGINE`, missing `WebSocket`, or Node older than 22 | Switch to Node 24 with the installer/version manager above, reinstall the bridge under that Node, then refresh MCP registrations that reference an old executable. |
-| PowerShell says `npm.ps1` or an installer script cannot be loaded | Use `npm.cmd` and the bridge installer's `.cmd` command shown above. For Codex use `codex.exe`; keep machine execution policies unchanged. |
-| `EACCES` on macOS/Linux | Use a user-owned Node version manager, then reinstall globally under that Node. See npm's [permission error guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally/). |
-| `EPERM`, `EBUSY`, or a file is in use on Windows | Let active work finish, close the process named in the error if it owns the package files, and retry the same npm command. Check the reported path's permissions or security-software event if it persists. |
-| `E404` for the bridge | Check the exact package name `@minhspark/codex-mcp-bridge`. Run the registry checks below; a private mirror may not contain the package. |
-| `ETIMEDOUT`, `ECONNRESET`, DNS, proxy, or certificate errors | Run the registry checks below. Correct the configured proxy or use the CA certificate supplied by the network administrator. Keep TLS verification enabled. |
-| Claude installer returns HTML, `403`, or a curl error | Use the alternatives and error-specific fixes in [Claude Code installation troubleshooting](https://code.claude.com/docs/en/troubleshooting). |
+Use Node.js 22+ and signed-in Codex and Claude Code CLIs under the same Linux user. This mode uses a local app-server; native Desktop integration requires Windows or macOS.
-Run these registry and cache diagnostics; in PowerShell replace `npm` with `npm.cmd`:
+<details>
+<summary>CLI registration commands</summary>
 ```bash
-npm config get registry
-npm ping
-npm view @minhspark/codex-mcp-bridge version
-npm view @minhspark/codex-mcp-bridge version --registry=https://registry.npmjs.org/
-npm cache verify
+npm install -g @openai/codex@latest
+codex login
+CODEX_BRIDGE_DESKTOP_TASKS=0 claude-mcp-bridge-install
+bridge_root="$(npm root -g)/@minhspark/codex-mcp-bridge"
+claude mcp add --scope user codex-bridge \
+  -e CODEX_BIN="$(command -v codex)" \
+  -e CODEX_BRIDGE_DESKTOP_TASKS=0 \
+  -e CODEX_BRIDGE_AUTOSTART=1 \
+  -e CODEX_BRIDGE_THREAD_POLICY=roots \
+  -e CODEX_BRIDGE_ALLOWED_ROOTS="$HOME/YourProject" \
+  -- "$(command -v node)" "$bridge_root/src/mcp-supervisor.mjs" index.mjs
 ```
-If the public registry works but a configured mirror does not, update the mirror configuration or, where permitted, install once from the public registry:
+Replace `$HOME/YourProject` with the actual project directory. WSL and Windows use separate paths and registrations.
-```bash
-npm install -g @minhspark/codex-mcp-bridge@latest --registry=https://registry.npmjs.org/
-```
+</details>
-### Installed, but the bridge does not connect
+### Verify the installation
-Start with `codex doctor` for Codex installation problems and `claude doctor` for Claude Code. Then inspect the MCP registrations and the status tools in [verification](#verify-the-installation).
+Reconnect the affected MCP servers in the actual client tasks; Claude Code provides `/mcp`. Run these **MCP tools** inside the apps:
-| Error / symptom | Fix |
+| Client | Tool |
 |---|---|
-| Codex says `Organization settings could not be loaded`, or the bridge reports `INVALID_MANAGED_CONFIG` | On a machine you administer, rerun `codex-mcp-bridge-install --full-access` to repair the managed policy and global defaults. The policy must include `"read-only"` alongside `"danger-full-access"`; the former is required for Codex to load it, while the effective mode remains Full access. Complete any OS administrator prompt, then run `codex doctor --summary --ascii`. |
-| `codex binary not found`, `ENOENT`, or Windows `EINVAL` during registration | Locate the actual executable. Set `CODEX_EXE` before rerunning the installer: PowerShell `$env:CODEX_EXE = (Get-Command codex.exe).Source`; macOS/Linux `export CODEX_EXE="$(command -v codex)"`. On Windows, do not point it at `codex.ps1` or `codex.cmd`. |
-| Tools appear in Claude Desktop but not in its Code task | Complete the separate [Claude Code registration](#register-claude-code), then reconnect `/mcp` in that Code session. |
-| `This MCP process has no registered Claude Desktop Code session in its parent ancestry` | The shared Desktop entry may not belong to the calling Code task. Register the bridge in the intended existing Code project under a distinct name, such as `codex-bridge-code`, retaining its access settings. Check that `CODEX_BRIDGE_ALLOWED_ROOTS` includes the intended authorized target project; copied test registrations may still allow only test directories. Reload that task's MCP configuration. In the tested Windows Desktop version, View > Reload was insufficient: fully exit and reopen Claude after active work is stopped, then reopen the same task. Verify the dedicated entry and a new proactive send; receiving a reply to a Codex-originated message alone does not establish proactive sending. |
-| Installer refuses an entry with custom access/timeout settings | Keep those settings. Update only the existing entry's `command` and `args` to the values printed by the installer, then reconnect. |
-| Desktop task still reports `app-server` | Rerun `codex-mcp-bridge-install --desktop-tasks`; set `CODEX_BRIDGE_DESKTOP_TASKS=1` in the separate Claude Code registration too. Refresh the reverse registration with the same setting and reconnect the actual sending task. |
-| Relay is installed but unavailable | Check [native relay pipe forwarding](#native-relay-pipe-forwarding), then reconnect `codex-native-relay` or restart Codex Desktop after active work finishes. Check `codex mcp get codex-native-relay` and the in-task `native_relay_status`; a registered entry alone is insufficient. |
-| `RELAY_THREAD_UNCONFIGURED` | Rerun `codex-native-relay-install --desktop-tasks` without `--no-bootstrap` to create the missing executor. |
-| macOS `untrusted-code-signing-identity` or `NATIVE_DELIVERY_UNCONFIRMED` | Inspect the client logs and the installer's `relay runtime:` line. Rerun the relay installer with Codex Desktop installed; if runtime detection fails, set `CODEX_NATIVE_RELAY_NODE` to the actual app-bundled runtime. Relaunch the companion after active work finishes. Inspect any original delivery before retrying. |
-| Linux says native relay unavailable | Use the Linux CLI setup with `CODEX_BRIDGE_DESKTOP_TASKS=0` on both registrations. Native Desktop relay support is Windows/macOS only. |
-| No Claude sessions or no matching saved project | Keep the intended Code session open under the same OS user. In Desktop mode, use a Claude Desktop Code session and an existing saved Codex project with the exact local path. Check both clients are signed in. |
-| `NOT AUTHORIZED` / workspace refused | Inspect `CODEX_BRIDGE_ALLOWED_ROOTS` and `CODEX_BRIDGE_THREAD_POLICY`. Add the intended writable project path to the relevant registration and reconnect; retain unrelated restrictions. |
-| Account identity unavailable / changed | Complete sign-in in the intended clients and recheck their status. Desktop routing requires supported local account identity; API-key or unsupported credential storage is not a substitute. See [account requirements](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#switching-desktop-accounts). |
-| Runtime is stale or update pending | Check the configured installation path and `autoReload` status. Active calls and unresolved deliveries defer a reload. Let them finish; reconnect once for legacy registrations or changed environment variables. |
-| Task is “open in another application” | For Desktop tasks, use the native mode above. For CLI/app-server tasks, let the owning turn finish and release its subscription before opening elsewhere. |
-| CLI mode cannot connect after reboot | Check `codex_bridge_status`, the configured endpoint, and whether autostart is enabled. The CLI setup uses `ws://127.0.0.1:8791`. If manually starting `codex app-server --listen ws://127.0.0.1:8791`, first confirm no server already owns that endpoint. |
-| CLI server says the model needs a newer Codex | Update Codex, then restart the specific old app-server after its active work finishes. Updating files does not replace an already running process. |
-| Send timed out / reply unconfirmed | Read the original task or delivery receipt before retrying. A timeout does not cancel the task, and retrying can send it twice. |
-For unresolved failures, [open an issue](https://github.com/buidangminh23/codex-mcp-bridge/issues) with the OS, Node/bridge/client versions, the failing command, and the relevant redacted status/error. Leave out tokens, credentials, and private conversations. More detail is in the [technical reference](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#troubleshooting).
-## Repository analytics
-The live dashboard polls the aggregate API every 30 seconds. Installation counts reflect reports received by the server; this is not a count of currently online processes. Public GitHub/npm sources are refreshed with a short cache, but their own statistics may be delayed. GitHub Actions refreshes and archives statistics hourly through the `Repository analytics` workflow, including private GitHub traffic; scheduled runs may be delayed by GitHub. Data collection and publication to the `analytics` branch run independently of the Pages deployment environment, and a newer scheduled run replaces a stuck older run. That workflow reads GitHub traffic with the `ANALYTICS_TOKEN` repository secret, a token with push access to this repository (fine-grained: Administration read); the default workflow token cannot read GitHub traffic, so without it the views/clones sources are retained from the last successful run and the run is reported as incomplete. The `analytics` branch is written with the workflow's own token, so its commits come from `github-actions[bot]` and `ANALYTICS_TOKEN` needs no write access. The README view badge is an hourly snapshot and may be cached by GitHub; open the live dashboard for automatic updates. Each source keeps its own collection time and reporting window. Sources older than three hours are marked stale even when polling succeeds. Missing data is unavailable, not zero; an empty usage breakdown means no opted-in reports in that period. Only aggregate figures are published. Installation IDs stay in the private database.
-Repository owners can view [GitHub traffic](https://github.com/buidangminh23/codex-mcp-bridge/graphs/traffic) for recent views and clones. Downloads and clones include updates, reinstalls, and automation; they do not measure active users. GitHub traffic only covers the recent 14-day window, so collect it regularly to keep a longer history.
-From a source checkout with Node 22+ and GitHub CLI authenticated as an account with repository traffic access:
+| Claude Code | `codex_bridge_status` |
+| Codex | `claude_bridge_status` |
+| Codex Desktop | `native_relay_status` |
-```bash
-gh auth status
-npm run analytics
-```
+Send a short message and confirm its reply **in both directions**. Registration alone does not prove delivery.
-The collector saves `history.json` and a self-contained `index.html` dashboard privately:
-| Platform | Default directory |
-|---|---|
-| Windows | `%LOCALAPPDATA%\codex-mcp-bridge\analytics` |
-| macOS | `~/Library/Application Support/codex-mcp-bridge/analytics` |
-| Linux | `${XDG_DATA_HOME:-~/.local/share}/codex-mcp-bridge/analytics` |
+## Use
-Open `index.html` in a browser. Back up `history.json` to preserve the archive. Use `npm run analytics -- --output <directory>` to choose another private directory. Each run refreshes overlapping dates without double-counting, records per-source collection times, and preserves earlier successful data if a source fails. Daily unique visitors/cloners cannot be summed to estimate unique people across days. Release asset download counters are also retained in the JSON archive.
+- **Claude → Codex:** “Send this review to my Codex task in this project and wait for its reply.”
+- **Codex → Claude:** “Send this result to my Claude Desktop Code session in this project.”
+- **New work:** “Create a new Codex conversation for this feature and send the brief there.”
-Run this command daily through a local scheduler or Codex automation while the machine is available. Scheduling is not installed by the package. A missed interval longer than GitHub's retention window cannot be recovered. For collection errors, check `gh auth status`, repository permissions, network connectivity, and API limits; rerun after correcting the cause. Never commit the private output directory.
+Continue unfinished work with its original `threadId`. For an authorized new Desktop task, use `delegate_to_codex` or `start_codex_thread` with a fresh UUID `requestId`; retain that ID on retries. If a send times out, use `wait_codex_reply` with the original `deliveryId` before retrying the message.
-To refresh the public dashboard, run `npm run analytics:publish`. It publishes an allowlisted aggregate snapshot to the separate `analytics` data branch and leaves application source unchanged. To include installation metrics, run `scripts/usage-summary.sql` through the owner's Supabase SQL editor or connector, save the returned `summary` object privately as `usage-summary.json`, and pass `--usage <path-to-usage-summary.json>` to the publisher. The summary query returns counts only. Do not supply raw installation rows or service credentials.
+[Daily handoffs](docs/daily-handoffs.md) · [Project permissions](docs/project-onboarding.md) · [All tools and settings](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md)
-### Optional active-install statistics
+## ChatGPT plugin
-Usage reporting is **off by default**. Each end user must explicitly enable it:
+[Open Codex Bridge](https://codex-mcp-bridge.buidangminh23.chatgpt.site) to connect ChatGPT to a selected project on a Windows or macOS computer. After installing the package and native relay above, pair the connector:
 ```bash
-codex-mcp-bridge telemetry enable
-codex-mcp-bridge telemetry status
-codex-mcp-bridge telemetry disable
-```
-The equivalent `claude-mcp-bridge telemetry ...` commands share the same local consent. When enabled, the bridge checks at startup and hourly while running, sending at most one successful report per UTC day to the project's Supabase endpoint: a random installation ID, UTC day, bridge version, and operating system. No chat content, paths, account identity, or credentials are included. Network infrastructure may process normal request metadata; the application's statistics table does not store IP addresses. Reporting failures do not interrupt bridge operation. `DO_NOT_TRACK=1` or `CODEX_BRIDGE_TELEMETRY=0` overrides local consent and suppresses reporting.
-These counts represent voluntarily reporting installations, not unique people or all users. Disabling stops future reports and removes the local installation ID. Previously submitted records older than 90 days are removed during subsequent ingestion. Source checkouts containing this feature support these commands; older published package versions do not.
-The owner can query `public.bridge_usage_daily` in the Supabase SQL editor. Public and authenticated client roles cannot read the table or call its ingestion function. The endpoint validates the project's public publishable key, so counts are approximate and can include fabricated IDs; its 10,000-record daily storage cap does not prevent request spam. Apply the migration under `supabase/migrations` before deploying `bridge-usage` with the supplied function configuration (custom publishable-key validation; legacy JWT verification disabled). The client contains only a public publishable key; service credentials stay in the Edge Function environment.
-```sql
-SELECT day, count(*) AS reporting_installations
-FROM public.bridge_usage_daily
-GROUP BY day ORDER BY day DESC;
-SELECT count(DISTINCT install_id) AS reporting_installations_last_30_days
-FROM public.bridge_usage_daily
-WHERE day >= (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')::date - 29;
+codex-sites-connector --pair --site https://codex-mcp-bridge.buidangminh23.chatgpt.site --roots "/absolute/project/path"
 ```
-## Development
-### Glama directory
+In PowerShell use `codex-sites-connector.cmd` and a Windows path such as `C:\Projects\YourProject`. Open the printed pairing URL, sign in, and select **Connect this computer**. Keep Codex Desktop and the connector running; use `codex-sites-connector` to reconnect later.
-The repository includes [glama.json](glama.json) with the maintainer's GitHub username, using [Glama's server schema](https://glama.ai/mcp/schemas/server.json). After changing it, use the listing's **Sync Server** action or repeat the ownership claim to refresh Glama's copy. See [Glama's manifest documentation](https://glama.ai/blog/2025-07-08-what-is-glamajson).
+The MCP endpoint is `https://codex-mcp-bridge.buidangminh23.chatgpt.site/mcp`. Plugin availability follows [OpenAI's Sites access rules](https://help.openai.com/en/articles/20001547-hosting-a-plugin-with-chatgpt-sites); a public directory listing is not claimed.
-Glama's recent usage signal measures calls observed by Glama, independently of npm downloads and the bridge's opt-in installation analytics. Use **Try in Browser** and the read-only `codex_bridge_status` tool to check a hosted release. A cloud container cannot access the Codex Desktop app or signed-in sessions on a user's machine; run the bridge locally for those workflows. Related servers are managed separately in Glama's listing.
+<details>
+<summary>Hosted data and privacy</summary>
-If a Glama test reports `DockerBuildError` with HTTP `502 Bad Gateway` and an empty build log, the Docker service request failed without an application build log. Retry when that service recovers. If it persists, provide Glama support with the test ID, timestamp, and error details. Changing `npm ci` or the launcher cannot repair that upstream failure; investigate repository build steps only when their logs identify an application error.
+The service is operated by Bui Dang Minh on OpenAI Sites. It stores a Site-scoped account ID, connector ID and token hash, timestamps, tool arguments (including prompts), and returned Desktop results. The operator can access these records. Local credentials and receipts stay in `~/.codex/sites-bridge`.
-### Shared project scope for Desktop Code conversations
+Dispatch expires after two minutes; operation history remains stored. Disconnecting revokes the connector and cancels queued work, but does not erase history or stop dispatched tasks. For deletion requests, contact the operator through the repository's support link without posting private content publicly. The hosted Worker implements no advertising or analytics collection.
-See [Desktop handoff design and recovery](docs/desktop-handoff-design.md) for the failure cases, integration with current upstream, and validation limits.
+</details>
-For a source installation used by both desktops, set `CODEX_BRIDGE_PROJECT_POLICY` to the same absolute JSON file in both bridge entries. The opt-in policy is read on every operation. `bridge-projects` defaults to `~/.config/GptClaudeBridge/projects.json`; prefer a shared home-directory path over Windows AppData, whose view can differ between packaged applications.
-```sh
-bridge-projects allow-parent /absolute/projects
-bridge-projects allow-project /absolute/other-repository
-bridge-projects check /absolute/other-repository
-bridge-projects revoke /absolute/other-repository
-```
-A parent grant covers new projects inside it and their registered Git worktrees. A project grant covers that repository's registered worktrees even outside the parent. Canonical directory identities and Git's worktree registry are checked; a copied `.git` pointer does not establish membership. Explicit revocation takes precedence and applies to subsequent operations without restarting either bridge. It does not cancel work already dispatched. Missing or invalid policy files fail closed. This opt-in policy cannot replace the hardened profile's pinned roots.
-Project grants do not replace upstream's same-project requirement for Claude-to-Codex delivery: the verified sender and destination must still share a directory or registered Git repository. Authorizing two unrelated projects does not permit sending between them.
-Claude Code needs its own user-level `codex-bridge` process, whose ancestry identifies the sending Code session. A generic shared Desktop MCP process cannot supply that identity. `codex-bridge-code-install --policy /absolute/projects.json` previews migration of an existing supervised installation; `--apply --clients-stopped` backs up and writes it. Customized entries are refused for review. Synchronize the same entry in any external configuration manager such as CC Switch. `--check` diagnoses duplicate/shared registrations. Reconnect clients after changing registration; subsequent project-policy changes need no reconnect.
-Run `codex_bridge_status` in the actual Claude Code conversation with the intended `cwd`. It reports sender, target scope and relay readiness independently. A generic command-line connectivity check can report a reachable relay while returning nonzero because no Code caller was verified. Validate both a Codex-originated round trip and a Claude-originated round trip; neither proves the other. Account and sender permission checks remain mandatory. Client upgrades can still require compatibility updates.
+## Troubleshooting
-See the [project onboarding guide](docs/project-onboarding.md) for explicit setup and the optional settings adapter.
+- **Command missing:** open a new terminal and check Node.js 22+ and the global npm directory on PATH.
+- **PowerShell blocks scripts:** use `npm.cmd`, installer `.cmd` launchers, and `codex.exe`.
+- **No sessions or wrong project:** open the intended Claude **Code** session and use the exact project directory saved in Codex Desktop.
+- **Relay unavailable:** check [pipe forwarding](#native-relay-pipe-forwarding), reconnect, and run `native_relay_status` in the task.
+- **Timeout or unconfirmed send:** inspect the original task or receipt before sending again.
-Automatic handoff requires both user authorization for the collaboration and permission to use the messaging tools; a card extension's project grant does not approve this bridge. After explicitly opting in, run `node scripts/configure-message-automation.mjs --apply --approve-message-automation` once. It backs up Claude user settings, adds only the exact `send_to_codex_thread` and `wait_codex_reply` tool permissions, and installs scoped collaboration guidance in `~/.claude/rules/gpt-claude-bridge.md`. Without flags it previews; `--check` verifies the files. Existing conflicting ask/deny rules are refused, not removed. It does not approve shell/file operations, expand projects, change modes, or override host safeguards. A running conversation can require a one-time user acknowledgment of standing authorization; do not disguise peer messages as user consent. Validate consecutive real handoffs after setup, not just connectivity. `readiness.readyScope` explicitly excludes host tool permission evaluation.
+[More fixes](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md#troubleshooting) · [Report an issue](https://github.com/buidangminh23/codex-mcp-bridge/issues)
-```bash
-npm ci
-npm test
-```
+## Optional active-install statistics
-On Windows, use `node --test --test-concurrency=2` (also avoids npm versions that reject forwarded flags). CI tests Node 22 and 24 on Linux, macOS, and Windows. Tests use isolated fixtures and do not spend model quota. For the optional telemetry endpoint, also run `deno test --allow-env supabase/functions/bridge-usage/contract-check.ts`.
+Usage reporting is **off by default**. Manage it with `codex-mcp-bridge telemetry enable`, `telemetry status`, or `telemetry disable`. Reports contain a random installation ID, UTC day, version, and OS; no chat content, paths, account identity, or credentials. `DO_NOT_TRACK=1` or `CODEX_BRIDGE_TELEMETRY=0` disables reporting. Disabling removes the local ID; submitted records expire after 90 days during ingestion.
-[Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [MIT license](LICENSE)
+[Analytics dashboard](https://buidangminh23.github.io/codex-mcp-bridge/) · [Release notes](https://github.com/buidangminh23/codex-mcp-bridge/releases) · [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE)

package/docs/daily-handoffs.md CHANGED Viewed

@@ -27,6 +27,24 @@ session identity, Git root if applicable, and Remote Control state. Compare
 Pin `expectedCwd` and `expectedTaskId` before dispatching production work.
 Reuse this verified parent for subsequent handoffs.
+If a saved Claude project's directory has moved, discovery reports a separate
+`relocatedProjects` candidate when the old directory is missing and the workspace
+resolver finds one writable replacement authorized by the shared project policy.
+Revoked original paths, revoked targets, ambiguous replacements and existing old
+directories do not qualify. Hardened deployments do not remap projects.
+The candidate can establish the project for an explicitly authorized new Code
+conversation. It cannot resume the old task or authorize a live session: the
+new native task, account, process, actual cwd and initial message must still match.
+Discovery does not rewrite Claude metadata, create grants or clear revocations.
+The saved source and its authorization are rechecked before opening, trusting and
+submitting, including after a pending request is restored.
+Native composer creation submits an initial user prompt; it is not a peer
+message and does not establish a native sender label. If a handoff requires the
+recipient's peer sender attribution, use `send_to_claude_session` with a verified
+live task. Do not substitute composer submission or a text header for that route.
 If a link was already opened, retain its requestId and inspect its receipt.
 `promptSubmitted=false` with `submissionStatus=not_observed` means submission
 was not verified, not that nothing was delivered. A wrong-directory task can

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.22.3",
+  "version": "1.22.4",
   "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/plugin.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.22.3",
+  "version": "1.22.4",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs CHANGED Viewed

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 exitForVersionRequest(import.meta.url);
-const VERSION = "1.22.3";
+const VERSION = "1.22.4";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/claude-bridge.mjs CHANGED Viewed

@@ -26,10 +26,11 @@ import { submitClaudeCodeComposer, trustClaudeCodeComposer } from "./claude-comp
 import { createHardenedRootPolicy } from "./hardened-root-policy.mjs";
 import { AGENT_PROMPT_GUIDANCE, PROMPT_FIELD_HINT } from "./prompt-guidance.mjs";
 import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
+import { discoverClaudeProject } from "./claude-project-discovery.mjs";
 exitForVersionRequest(import.meta.url);
-const VERSION = "1.22.3";
+const VERSION = "1.22.4";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
@@ -71,7 +72,8 @@ const creations = new ClaudeSessionCreation({
   submit: submitClaudeCodeComposer,
   trust: trustClaudeCodeComposer,
   settle: () => delay(2500),
-  listTasks: (account) => readClaudeDesktopTasks({ account }).filter((task) => rootPolicy.allows(task.cwd)),
+  listTasks: (account) => readClaudeDesktopTasks({ account }),
+  resolveProject: (task) => discoverClaudeProject(task, { policy: rootPolicy })?.cwd ?? null,
   listSessions: () => listClaudeSessions().filter((session) => rootPolicy.allows(session.cwd)),
   readContext: (session, account) => readClaudeDesktopContext(session, { account }),
   readTranscript: (...args) => {
@@ -254,21 +256,25 @@ async function startClaudeCreation({ requestId, cwd, prompt, autoSubmit = proces
     sender: rootPolicy.capture(sender.cwd, "Codex sender working directory"),
     recipient: rootPolicy.capture(cwd, "Claude creation working directory"),
   } : null;
-  const receipt = await creations.start({ requestId, cwd, prompt, autoSubmit, trustProject, account: accounts.claude, senderThreadId: sender.threadId,
-    beforeOpen: async () => {
-      runtime.assertCurrent();
-      assertAccountIdentity(selectedAccounts);
-      recheckScopeBindings(scopeBindings);
-      if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
-      const current = await assertSender(meta);
-      if (JSON.stringify(current) !== JSON.stringify(sender)) throw new Error("The calling Codex turn changed before opening Claude Desktop");
-      runtime.assertCurrent();
-      assertAccountIdentity(selectedAccounts);
-      recheckScopeBindings(scopeBindings);
-      if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
-    },
-  });
-  if (rootPolicy.enabled) creationRootBindings.set(requestId, scopeBindings);
+  let receipt;
+  try {
+    receipt = await creations.start({ requestId, cwd, prompt, autoSubmit, trustProject, account: accounts.claude, senderThreadId: sender.threadId,
+      beforeOpen: async () => {
+        runtime.assertCurrent();
+        assertAccountIdentity(selectedAccounts);
+        recheckScopeBindings(scopeBindings);
+        if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
+        const current = await assertSender(meta);
+        if (JSON.stringify(current) !== JSON.stringify(sender)) throw new Error("The calling Codex turn changed before opening Claude Desktop");
+        runtime.assertCurrent();
+        assertAccountIdentity(selectedAccounts);
+        recheckScopeBindings(scopeBindings);
+        if (rootPolicy.enabled && !rootPolicy.same(cwd, scopeBindings.recipient.path)) throw new Error("The Claude creation working directory changed before opening Desktop");
+      },
+    });
+  } finally {
+    if (rootPolicy.enabled && creations.requests.has(requestId) && !creationRootBindings.has(requestId)) creationRootBindings.set(requestId, scopeBindings);
+  }
   return { ...textResult(JSON.stringify(receipt, null, 2)), structuredContent: { creation: receipt } };
 }
@@ -414,13 +420,18 @@ registerTool(
         if (expectedCwd !== undefined) { try { assertClaudeSessionCwd(task, expectedCwd); } catch { return false; } }
         return true;
       }).map(({ taskId, title, cwd }) => ({ taskId, title, cwd, alive: sessions.some((session) => session.desktop?.taskId === taskId) }));
+      const relocatedProjects = saved.flatMap(task => {
+        const candidate = discoverClaudeProject(task, { policy: rootPolicy });
+        if (!candidate?.relocated || (expectedCwd !== undefined && !rootPolicy.same(candidate.cwd, expectedCwd))) return [];
+        return [{ taskId: task.taskId, originalCwd: candidate.originalCwd, resolvedCwd: candidate.cwd, liveVerified: false, resumable: false }];
+      });
       const summary = sessions.length
         ? `${sessions.length} Claude${desktopOnly ? " Desktop" : ""} session(s):\n\n${sessions.map(formatSessionRow).join("\n")}`
         : discovery.excluded.length
           ? `Found ${discovery.candidateCount} registered Claude Desktop candidate(s) with messaging endpoints, but their Desktop task identities could not be verified. Delivery remains blocked.`
           : desktopOnly ? missingDesktopSession : "No live Claude Code session found.";
-      return { ...textResult([summary, ...discoveryDetails(discovery), ...(savedTasks.length ? [`Saved Desktop tasks (resume unfinished work with target auto and expectedTaskId):\n${JSON.stringify(savedTasks, null, 2)}`] : [])].join("\n")),
-        structuredContent: { account: publicAccountState(account), sessions: sessions.map(({ socket, bridgeSessionId, ...session }) => session), savedTasks, discovery } };
+      return { ...textResult([summary, ...discoveryDetails(discovery), ...(savedTasks.length ? [`Saved Desktop tasks (resume unfinished work with target auto and expectedTaskId):\n${JSON.stringify(savedTasks, null, 2)}`] : []), ...(relocatedProjects.length ? [`Relocated project candidates (new conversation only when authorized; old tasks are not verified or resumable at the new path):\n${JSON.stringify(relocatedProjects, null, 2)}`] : [])].join("\n")),
+        structuredContent: { account: publicAccountState(account), sessions: sessions.map(({ socket, bridgeSessionId, ...session }) => session), savedTasks, relocatedProjects, discovery } };
     } catch (err) {
       return failure(err);
     }

package/src/claude-project-discovery.mjs ADDED Viewed

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveWorkspacePath } from "./platform.mjs";
+export function discoverClaudeProject(task, { policy, resolveWorkspace = resolveWorkspacePath }) {
+  if (!task || task.isArchived !== false || typeof task.taskId !== "string" || !task.taskId || task.fileTaskId !== task.taskId ||
+      typeof task.cwd !== "string" || !path.isAbsolute(task.cwd) || task.cwd.includes("\0")) return null;
+  try {
+    let cwd;
+    let relocated = false;
+    try {
+      cwd = fs.realpathSync.native(task.cwd);
+    } catch (error) {
+      if (error.code !== "ENOENT" || policy.mode !== "project-policy") return null;
+      try { fs.lstatSync(task.cwd); return null; } catch (missing) { if (missing.code !== "ENOENT") return null; }
+      policy.assertDiscoverySource(task.cwd);
+      const candidate = resolveWorkspace(task.cwd, { requireUnique: true });
+      if (!candidate.remapped || !candidate.writable) return null;
+      cwd = fs.realpathSync.native(candidate.path);
+      relocated = true;
+    }
+    const binding = policy.capture(cwd, "Discovered Claude project directory");
+    return { cwd: binding.path, originalCwd: task.cwd, relocated, binding };
+  } catch { return null; }
+}

package/src/claude-session-creation.mjs CHANGED Viewed

@@ -60,7 +60,7 @@ function receipt(request) {
 }
 export class ClaudeSessionCreation {
-  constructor({ open, submit, trust, settle = async () => {}, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath = (directory) => {
+  constructor({ open, submit, trust, settle = async () => {}, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, resolveProject, realpath = (directory) => {
     const canonical = fs.realpathSync.native(directory);
     if (!fs.statSync(canonical).isDirectory()) throw new Error("Not a directory");
     return canonical;
@@ -68,7 +68,7 @@ export class ClaudeSessionCreation {
     for (const [name, dependency] of Object.entries({ open, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath })) {
       if (typeof dependency !== "function") throw new TypeError(`${name} must be a function`);
     }
-    Object.assign(this, { open, submit, trust, settle, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, realpath, platform });
+    Object.assign(this, { open, submit, trust, settle, listTasks, listSessions, readContext, readTranscript, readAccount, assertProcess, resolveProject, realpath, platform });
     this.requests = new Map();
     this.queue = Promise.resolve();
   }
@@ -83,6 +83,7 @@ export class ClaudeSessionCreation {
   }
   sameCwd(left, right) {
+    if (typeof left !== "string" || typeof right !== "string") return false;
     return this.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
   }
@@ -123,11 +124,14 @@ export class ClaudeSessionCreation {
       if (sameAccount(existing.account, identity) && PENDING.has(existing.status) && !composerReleased) fail("CLAUDE_CREATION_PENDING", "A creation request is already pending for this account; inspect or explicitly abandon that request before opening another project in the shared composer.");
     }
     const tasks = await this.listTasks(account);
-    if (!Array.isArray(tasks) || tasks.length > MAX_TASKS || tasks.some((task) => !string(task?.taskId, 256) || (task.fileTaskId !== undefined && task.fileTaskId !== task.taskId))) fail("CLAUDE_CREATION_TASKS_INVALID", "The existing native task baseline cannot be verified.");
-    let existingProject = false;
+    const validTasks = value => Array.isArray(value) && value.length <= MAX_TASKS && value.every(task => string(task?.taskId, 256) && (task.fileTaskId === undefined || task.fileTaskId === task.taskId)) && new Set(value.map(task => task.taskId)).size === value.length;
+    if (!validTasks(tasks)) fail("CLAUDE_CREATION_TASKS_INVALID", "The existing native task baseline cannot be verified.");
+    const baseline = new Set(tasks.map(task => task.taskId));
+    const projectCwd = async task => this.resolveProject ? this.resolveProject(task) : this.canonical(task.cwd);
+    let existingProject;
     for (const task of tasks) {
       if (task.isArchived !== false) continue;
-      try { if (this.sameCwd(await this.canonical(task.cwd), canonical)) existingProject = true; } catch {}
+      try { if (this.sameCwd(await projectCwd(task), canonical)) { existingProject = task; break; } } catch {}
     }
     if (!existingProject) fail("CLAUDE_CREATION_PROJECT_NOT_FOUND", "The canonical directory must already belong to a nonarchived Claude Desktop task.");
     if (autoSubmit && typeof this.submit !== "function") fail("CLAUDE_CREATION_SUBMIT_UNAVAILABLE", "Native composer submission is not available.");
@@ -139,7 +143,20 @@ export class ClaudeSessionCreation {
       if (typeof beforeOpen !== "function") fail("CLAUDE_CREATION_PREFLIGHT_INVALID", "beforeOpen must be a function.");
       await beforeOpen();
     }
-    const request = { requestId, cwd: canonical, prompt, initialMessage, account: identity, senderThreadId, baseline: [...new Set(tasks.map((task) => task.taskId))], status: "launch_uncertain", reason: "The Desktop launch outcome is uncertain; inspect this request before taking further action." };
+    if (this.resolveProject) {
+      const currentTasks = await this.listTasks(account);
+      if (!validTasks(currentTasks)) fail("CLAUDE_CREATION_TASKS_INVALID", "The current native task baseline cannot be verified.");
+      const matches = currentTasks.filter(task => task.taskId === existingProject.taskId && task.fileTaskId === existingProject.fileTaskId && task.cwd === existingProject.cwd && task.isArchived === false);
+      if (matches.length !== 1 || !this.sameCwd(await projectCwd(matches[0]), canonical)) {
+        fail("CLAUDE_CREATION_PROJECT_NOT_FOUND", "The saved project or its authorized current directory changed before opening Desktop.");
+      }
+      for (const task of currentTasks) baseline.add(task.taskId);
+      if (baseline.size > MAX_TASKS) fail("CLAUDE_CREATION_TASKS_INVALID", "The native task baseline exceeds the creation limit.");
+      if (beforeOpen) await beforeOpen();
+    }
+    const projectSource = this.resolveProject ? { taskId: existingProject.taskId, fileTaskId: existingProject.fileTaskId, cwd: existingProject.cwd } : undefined;
+    const request = { requestId, cwd: canonical, prompt, initialMessage, account: identity, senderThreadId, baseline: [...baseline], ...(projectSource ? { projectSource } : {}), status: "launch_uncertain", reason: "The Desktop launch outcome is uncertain; inspect this request before taking further action." };
+    await this.revalidateProjectSource(request, account);
     this.requests.set(requestId, request);
     try {
       await this.open(url);
@@ -155,11 +172,25 @@ export class ClaudeSessionCreation {
     return receipt(request);
   }
+  async revalidateProjectSource(request, account) {
+    if (!this.resolveProject) return;
+    const source = request.projectSource;
+    if (!source) fail("CLAUDE_CREATION_PROJECT_NOT_FOUND", "The original saved project source is unavailable; submission is not authorized.");
+    const tasks = await this.listTasks(account);
+    if (!Array.isArray(tasks) || tasks.length > MAX_TASKS) fail("CLAUDE_CREATION_TASKS_INVALID", "The saved project source cannot be verified.");
+    const matches = tasks.filter(task => task?.taskId === source.taskId);
+    if (matches.length !== 1 || matches[0].fileTaskId !== source.fileTaskId || matches[0].cwd !== source.cwd || matches[0].isArchived !== false ||
+        !this.sameCwd(await this.resolveProject(matches[0]), request.cwd)) {
+      fail("CLAUDE_CREATION_PROJECT_NOT_FOUND", "The original saved project or its authorization changed; submission is not authorized.");
+    }
+  }
   async completeRequest(request, { account, senderThreadId, beforeOpen, trustProject }) {
     if (typeof this.submit !== "function") fail("CLAUDE_CREATION_SUBMIT_UNAVAILABLE", "Native composer submission is not available.");
     if (trustProject && typeof this.trust !== "function") fail("CLAUDE_CREATION_TRUST_UNAVAILABLE", "Authorized project trust preparation is not available.");
     await this.checkAccount(account, request.account);
     if (beforeOpen) await beforeOpen();
+    await this.revalidateProjectSource(request, account);
     if (trustProject) {
       const trusted = await this.trust({ cwd: request.cwd, prompt: request.initialMessage });
       if (!["trusted", "absent"].includes(trusted?.status)) {
@@ -171,6 +202,7 @@ export class ClaudeSessionCreation {
     }
     await this.checkAccount(account, request.account);
     if (beforeOpen) await beforeOpen();
+    await this.revalidateProjectSource(request, account);
     request.submissionAttempted = true;
     request.status = "submission_uncertain";
     request.reason = "Native submission was attempted; inspect this request before retrying. The bridge will not press Send again.";
@@ -178,6 +210,7 @@ export class ClaudeSessionCreation {
       const submission = await this.submit({ prompt: request.initialMessage, cwd: request.cwd, beforeSubmit: async () => {
         await this.checkAccount(account, request.account);
         if (beforeOpen) await beforeOpen();
+        await this.revalidateProjectSource(request, account);
       } });
       if (submission?.status === "blocked" && submission.submissionAttempted === false) delete request.submissionAttempted;
       request.status = submission?.status === "submitted" ? "awaiting_session" : submission?.status === "blocked" ? "awaiting_user" : "submission_uncertain";
@@ -263,7 +296,10 @@ export class ClaudeSessionCreation {
       if ((request.status === "awaiting_project_confirmation" || request.observedCwd !== undefined) && (!string(request.observedCwd, 8192) || !paths.isAbsolute(request.observedCwd))) fail("CLAUDE_CREATION_STATE_INVALID", "A retained observed directory is invalid.");
       if (request.status === "awaiting_project_confirmation" && (request.submissionObserved !== true || this.sameCwd(request.cwd, request.observedCwd))) fail("CLAUDE_CREATION_STATE_INVALID", "A pending project confirmation is invalid.");
       if (request.ambiguitySeen !== undefined && typeof request.ambiguitySeen !== "boolean") fail("CLAUDE_CREATION_STATE_INVALID", "A retained ambiguity marker is invalid.");
-      restored.set(request.requestId, structuredClone({ requestId: request.requestId, cwd: request.cwd, prompt: request.prompt, initialMessage: request.initialMessage, account: { fingerprint: request.account.fingerprint, root: request.account.root }, senderThreadId: request.senderThreadId, baseline: request.baseline, status: request.status, reason: request.reason, ...(request.submissionAttempted ? { submissionAttempted: true } : {}), ...(request.ambiguitySeen || request.status === "ambiguous" ? { ambiguitySeen: true } : {}), ...(request.submissionObserved ? { submissionObserved: true } : {}), ...(request.observedCwd ? { observedCwd: request.observedCwd } : {}), ...(hasSession ? { sessionId: request.sessionId, taskId: request.taskId, title: request.title } : {}) }));
+      if (request.projectSource !== undefined && (!string(request.projectSource?.taskId, 256) || !request.baseline.includes(request.projectSource.taskId) ||
+          (request.projectSource.fileTaskId !== undefined && request.projectSource.fileTaskId !== request.projectSource.taskId) ||
+          !string(request.projectSource.cwd, 8192) || !paths.isAbsolute(request.projectSource.cwd))) fail("CLAUDE_CREATION_STATE_INVALID", "A retained project source is invalid.");
+      restored.set(request.requestId, structuredClone({ requestId: request.requestId, cwd: request.cwd, prompt: request.prompt, initialMessage: request.initialMessage, account: { fingerprint: request.account.fingerprint, root: request.account.root }, senderThreadId: request.senderThreadId, baseline: request.baseline, ...(request.projectSource ? { projectSource: { taskId: request.projectSource.taskId, fileTaskId: request.projectSource.fileTaskId, cwd: request.projectSource.cwd } } : {}), status: request.status, reason: request.reason, ...(request.submissionAttempted ? { submissionAttempted: true } : {}), ...(request.ambiguitySeen || request.status === "ambiguous" ? { ambiguitySeen: true } : {}), ...(request.submissionObserved ? { submissionObserved: true } : {}), ...(request.observedCwd ? { observedCwd: request.observedCwd } : {}), ...(hasSession ? { sessionId: request.sessionId, taskId: request.taskId, title: request.title } : {}) }));
     }
     this.requests = restored;
   }

package/src/index.mjs CHANGED Viewed

@@ -40,7 +40,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 exitForVersionRequest(import.meta.url);
-const VERSION = "1.22.3";
+const VERSION = "1.22.4";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);

package/src/native-relay-companion.mjs CHANGED Viewed

@@ -38,7 +38,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 exitForVersionRequest(import.meta.url);
-const VERSION = "1.22.3";
+const VERSION = "1.22.4";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 function errorResponse(code, message, sent, details) {

package/src/platform.mjs CHANGED Viewed

@@ -1,5 +1,5 @@
 import { execFile, execFileSync } from "node:child_process";
-import { accessSync, constants, existsSync, readdirSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -338,7 +338,7 @@ function remapCandidates(input) {
  * checkout is unavailable locally. UNC shares are tried after local remap
  * candidates so a disconnected network location cannot stall the bridge.
  */
-export function resolveWorkspacePath(input) {
+export function resolveWorkspacePath(input, { requireUnique = false } = {}) {
   if (!input) return { path: input, remapped: false, writable: false, note: null };
   const original = input;
   const mapped = pathMapCandidates(input);
@@ -348,7 +348,11 @@ export function resolveWorkspacePath(input) {
     : [...mapped, input, ...remapped];
   const ordered = candidates.filter((candidate, index) => candidates.indexOf(candidate) === index);
-  const writable = ordered.find((candidate) => existsSync(candidate) && isWritableDir(candidate));
+  const usable = requireUnique ? ordered.filter((candidate) => existsSync(candidate) && isWritableDir(candidate)) : null;
+  if (usable && new Set(usable.map(candidate => realpathSync.native(candidate))).size > 1) {
+    throw new Error("Multiple usable workspace directories match; select an unambiguous project path");
+  }
+  const writable = usable ? usable[0] : ordered.find((candidate) => existsSync(candidate) && isWritableDir(candidate));
   if (writable) {
     return {
       path: path.resolve(writable),

package/src/project-policy.mjs CHANGED Viewed

@@ -150,6 +150,15 @@ export function createProjectScope(file, options = {}) {
     assert: (candidate, label) => capture(candidate, label).path,
     allows(candidate) { try { capture(candidate); return true; } catch { return false; } },
     capture,
+    assertDiscoverySource(candidate) {
+      const original = canonicalPolicyPath(candidate);
+      const namespaces = [path.resolve(candidate), original];
+      const { policy } = readProjectPolicy(file);
+      if (policy.denies.some(entry => namespaces.some(source => inside(entry.path, source) || entry.worktrees?.some(root => inside(root.path, source))))) {
+        throw new Error("The original project path was revoked; relocation discovery is not authorized");
+      }
+      return original;
+    },
     recheck(binding, label = "Working directory") {
       if (!binding?.identity) throw new Error(`${label} has no original directory identity`);
       const now = capture(binding.path, label);