@minhspark/codex-mcp-bridge 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+### Fixed
+
+- **A tag is not a release, and nothing was creating the release.** Pushing `v1.10.1`, `v1.11.0` and
+  `v1.11.1` published all three to npm, while the Releases page still showed `v1.10.0` as *Latest* -
+  the one release that had been created by hand. Anyone reading the repository saw a project that had
+  not shipped in days, and the three versions people were actually installing had no notes anywhere
+  except this file.
+
+  The publish workflow now creates the release from the changelog entry, in a separate job that is the
+  only one granted `contents: write` - the job that talks to npm keeps the read-only default. Generated
+  commit lists say what changed; the entry says why it mattered, so the entry is what ships. Re-running
+  a tag is safe: an existing release is left alone.
+
+- `scripts/release-notes.mjs` prints one version's changelog section, and a test asserts the version in
+  `package.json` has an entry substantial enough to be a release note - so forgetting to write it fails
+  before the tag is pushed rather than at the end of a release.
+
+### Added
+
+- `delegate_to_codex` now gives Claude a single contract for handing work to Codex: it creates the thread
+  at the requested project directory, names it through `thread/name/set`, returns the exact `threadId` and
+  `cwd`, releases the bridge writer lock after a terminal turn, and opens the Windows or macOS `codex://`
+  deep link when configured. Windows app-server shutdown uses `netstat` and `taskkill` instead of the Unix-only
+  `lsof` path, which removes the lock that previously left Codex Desktop showing "open in another app".
+
+## [1.11.2] - 2026-08-28
+
+### Fixed
+
+- Thread workspaces are normalized through the cross-machine path resolver before authorization, attaching,
+  reading, interrupting, or opening. A stale drive letter, mount point, or UNC path can therefore be mapped to
+  the writable checkout on the current machine instead of sending Codex into the wrong directory.
+- `CODEX_BRIDGE_ALLOWED_ROOTS=*` now explicitly means every usable workspace, and the installer uses that
+  cross-machine default together with `CODEX_BRIDGE_THREAD_POLICY=roots`, so a thread opened by a human is not
+  rejected because its id or the install directory belongs to another machine. A workspace still has to resolve
+  to an existing writable directory before a turn acts on it.
+- `scripts/check.mjs` now forwards `CODEX_BRIDGE_THREAD_POLICY`, so validation checks the same authorization mode
+  as the MCP server.
+
+## [1.11.1] - 2026-08-23
+
+### Fixed
+
+- **Re-running `codex-mcp-bridge-install` deleted settings it does not write.** It assigned a whole new
+  entry over the old one, so `CODEX_BRIDGE_ALLOWED_THREADS`, a hand-added `CODEX_BRIDGE_THREAD_POLICY`
+  and any key from a later version were dropped, and `CODEX_BRIDGE_ALLOWED_ROOTS` was reset to the
+  install directory. Upgrading is exactly when people re-run it, so the command you reach for to keep
+  the bridge current was the command that silently broke it. Measured on a config carrying four custom
+  values: all four gone, roots narrowed from two projects to the install directory, other MCP servers
+  untouched.
+
+  Existing values are now the fallback rather than the casualty. Precedence, highest first: a variable
+  passed to this run, what the config already says, then the default. `command`, `args` and `CODEX_BIN`
+  are still resolved fresh — pointing the entry at the code installed now is the reason to re-run at
+  all. `--reset` discards inherited values for the rare case of wanting the defaults back.
+
+### Added
+
+- The installer now writes `CODEX_BRIDGE_THREAD_POLICY` explicitly, and when it is left at `owned` it
+  says what that means: a thread opened in the Codex app or the VS Code extension will answer
+  `NOT AUTHORIZED`, because its id is assigned as it opens and cannot be allowlisted in advance. Shipping
+  1.11.0 without this left the fix reachable only by reading the environment table — and the symptom
+  points nowhere near the setting responsible.
+
 ## [1.11.0] - 2026-08-23
 
 ### Added

package/README.md

@@ -29,6 +29,7 @@ Codex TUI  ──codex --remote ws://127.0.0.1:8791──> same app-server, same
 - The app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits.
 - Every client pointed at the same URL shares **one app-server**, so `thread/resume` with a `threadId` rejoins the running thread instead of opening a new session.
 - The bridge keeps exactly one WebSocket, calls `initialize` once, and routes notifications by `threadId`, so parallel threads never bleed into each other.
+- `delegate_to_codex` is the one-call Claude → Codex hand-off: it starts the thread at the supplied `cwd`, names it, sends the prompt, stops the bridge app-server after a terminal turn, and opens `codex://threads/<id>` in Codex Desktop when enabled.
 
 ## Requirements
 
@@ -80,6 +81,12 @@ Two ways in. Pick by what you intend to do with it.
 npm install -g @minhspark/codex-mcp-bridge
 ```
 
+Already installed? The same command with `@latest` upgrades it in place — then restart the client. Details in [Upgrading an install you already have](#upgrading-an-install-you-already-have):
+
+```bash
+npm install -g @minhspark/codex-mcp-bridge@latest
+```
+
 Installing straight from the repository works the same way and needs no registry account:
 
 ```bash
@@ -88,6 +95,12 @@ 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.
 
+#### Upgrading an install you already have
+
+`npm install -g @minhspark/codex-mcp-bridge@latest`, then restart Claude Desktop or Claude Code — an MCP server only loads its code when the client spawns it. Check `codex_bridge_status` reports the version you expect. The global install path carries no version number, so the entry keeps pointing at the right file. If the existing entry still has `CODEX_BRIDGE_THREAD_POLICY=owned`, pass `CODEX_BRIDGE_THREAD_POLICY=roots` once when re-running the installer to enable human-opened threads.
+
+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.
+
 **Clone it** — right if you intend to read, test or change the code:
 
 ```bash
@@ -96,6 +109,8 @@ cd codex-mcp-bridge
 npm install
 ```
 
+A clone upgrades with `git pull && npm ci`, then the same restart.
+
 Confirm the tree is healthy before wiring it into anything:
 
 ```bash
@@ -116,14 +131,20 @@ The script detects the platform, creates the config file if it does not exist, b
 | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Linux | `${XDG_CONFIG_HOME:-~/.config}/Claude/claude_desktop_config.json` |
 
-Tell it which projects the bridge may drive. The default is the checkout when you cloned, and the directory you ran the installer from when you installed the package — neither is a sensible guess for more than one project, so name them:
+The v1.11.2 installer accepts threads from every usable workspace by default, so it does not bake one machine's clone path into the config. Narrow the scope to named projects when you want that:
 
 ```bash
 # macOS and Linux separate entries with ":", Windows with ";"
 CODEX_BRIDGE_ALLOWED_ROOTS="/path/to/project-a:/path/to/project-b" codex-mcp-bridge-install
 ```
 
-Skip this and the bridge still starts cleanly, then answers every `list_codex_threads` with `No workspace roots are configured`. It is the most common way an otherwise correct install refuses to do anything, so the installer now prints a warning when the roots it wrote point inside an install directory.
+On an older config, existing values are preserved. To migrate that entry to the cross-machine behaviour explicitly, run:
+
+```bash
+CODEX_BRIDGE_ALLOWED_ROOTS="*" CODEX_BRIDGE_THREAD_POLICY=roots codex-mcp-bridge-install
+```
+
+The wildcard means every usable workspace; the bridge still resolves the thread's reported `cwd` and refuses a path that does not exist or cannot be written.
 
 Pass defaults through the environment if you want them written into the entry:
 
@@ -251,27 +272,30 @@ On macOS and Linux the `codex` launcher is a Node script with a `#!/usr/bin/env
 
 | Tool | What it does | Hints |
 |---|---|---|
+| `delegate_to_codex` | Creates a named Codex thread at the requested project `cwd`, sends Claude's prompt, returns the reply, releases the bridge writer lock, and opens the exact session in Codex Desktop when enabled. | destructive |
 | `send_to_codex_thread` | Sends a prompt as a user turn into `threadId`, waits for `turn/completed`, returns Codex's reply plus an activity trail (commands run, files changed). | destructive |
-| `list_codex_threads` | Lists threads (id, title, cwd, last update, status) so you can pick the **exact** `threadId`. `loadedOnly: true` shows only threads live inside the app-server. On macOS each row carries a `codex://threads/<id>` deep link. | read-only |
-| `start_codex_thread` | Opens a new Codex thread at a permitted `cwd` and returns its `threadId`; the bridge applies its configured safe sandbox and approval policy. | writes |
+| `list_codex_threads` | Lists threads (id, title, cwd, last update, status) so you can pick the **exact** `threadId`. `loadedOnly: true` shows only threads live inside the app-server. Windows and macOS rows carry a `codex://threads/<id>` deep link. | read-only |
+| `start_codex_thread` | Opens a new Codex thread at a permitted `cwd`, optionally names it, and returns its `threadId`; the bridge applies its configured safe sandbox and approval policy. | writes |
 | `read_codex_thread` | Reads the recent conversation without sending anything. | read-only |
 | `interrupt_codex_turn` | Stops a turn that is still running. | destructive |
-| `open_codex_thread` | **macOS**: brings a thread to the front in the Codex desktop app via `codex://threads/<id>` so a human can watch it work. Pass `background: true` to open without stealing focus. | writes |
+| `open_codex_thread` | **Windows or macOS**: brings a thread to the front in the Codex desktop app via `codex://threads/<id>` so a human can watch it work. Pass `background: true` to open without stealing focus. | writes |
 | `stop_codex_app_server` | Stops the shared app-server once a hand-off is done, so it stops competing with Codex Desktop for the `~/.codex` state. The bridge starts a new one when it next needs it. | destructive |
 | `codex_bridge_status` | Reports the environment: platform, resolved `codex` binary, whether the app-server endpoint is live, plus the macOS integrations (LaunchAgent, desktop app), and **warns when two app-servers are running**. Start here when something misbehaves. | read-only |
 
-`send_to_codex_thread` also accepts `timeoutSec` (default 240), `cwd`, `model`, `effort`, and `openInApp` (macOS — surface the thread in the desktop app before sending). A timeout does **not** cancel the turn: the bridge returns what it collected plus the `turnId`; keep reading with `read_codex_thread` or stop it with `interrupt_codex_turn`.
+`delegate_to_codex` accepts `cwd`, `prompt`, an optional `name`, `timeoutSec` (default 240), `model`, `effort`, `openInApp`, and `releaseAfterTurn`. `send_to_codex_thread` accepts the same hand-off controls plus an existing `threadId`. On Windows, the installer defaults `openInApp` and `releaseAfterTurn` to `1`; explicit tool arguments override them. A timeout does **not** cancel the turn: the bridge returns what it collected plus the `turnId`; keep reading with `read_codex_thread` or stop it with `interrupt_codex_turn`.
+
+For the normal Claude → Codex workflow, Claude should call `delegate_to_codex` with the exact project directory in `cwd`. The response always includes the Codex `threadId`, visible session `name`, exact `cwd`, rollout path, and the desktop deep link or the reason it could not be opened. The bridge sets the protocol-supported `thread/name/set` before the first turn, so the session is not an unnamed entry in Recents.
 
-Thread operations are deny-by-default, and `CODEX_BRIDGE_THREAD_POLICY` decides what counts as permission:
+Thread operations are checked before the bridge attaches, and `CODEX_BRIDGE_THREAD_POLICY` decides what counts as permission:
 
 | Policy | A thread is reachable when | Use it when |
 |---|---|---|
-| `owned` *(default)* | the bridge created it with `start_codex_thread`, or its exact ID is listed in `CODEX_BRIDGE_ALLOWED_THREADS` | the bridge drives threads it opens itself |
-| `roots` | it is working inside a directory named in `CODEX_BRIDGE_ALLOWED_ROOTS` | you open threads in the Codex app or VS Code and want Claude to talk to them |
+| `owned` *(runtime default)* | the bridge created it with `start_codex_thread`, or its exact ID is listed in `CODEX_BRIDGE_ALLOWED_THREADS` | the bridge drives only threads it opens itself |
+| `roots` *(v1.11.2 installer default)* | it is working inside a directory allowed by `CODEX_BRIDGE_ALLOWED_ROOTS` | you open threads in the Codex app or VS Code and want Claude to talk to them |
 
 Under `owned`, a thread a human opened is **unreachable rather than merely restricted**: Codex assigns its ID at the moment it opens, so the ID cannot have been allowlisted beforehand, and the bridge-owned set lives in memory and empties whenever the MCP server restarts. If every live thread answers `NOT AUTHORIZED`, that is the cause — switch to `roots`.
 
-`roots` does not remove a gate; it moves it from the ID to the workspace, which is the containment every tool already applies to the `cwd` it is handed. The bridge resolves a thread's workspace with a read **before** attaching, so a thread outside every root is refused without ever taking its writer lock. Set `CODEX_BRIDGE_ALLOWED_ROOTS` to the absolute project directories the bridge may use — the installer defaults that root to this repository, so change it when delegating into another project. A root as broad as `/` or `C:\` makes `roots` mean *every thread on this machine*.
+`roots` does not remove a gate; it moves it from the ID to the workspace, which is the containment every tool already applies to the `cwd` it is handed. The bridge resolves a thread's workspace with a read **before** attaching, so a thread outside every root is refused without ever taking its writer lock. `CODEX_BRIDGE_ALLOWED_ROOTS=*` means every usable workspace. Otherwise set it to absolute project directories, separated by `:` (`;` on Windows). A root as broad as `/` or `C:\` has the same all-directories meaning, but `*` is portable across operating systems and machines.
 
 ## Tools — `claude-bridge` (runs inside Codex)
 
@@ -327,7 +351,7 @@ This is how a human watches Codex work in real time instead of reading the rollo
 
 - The Codex desktop app runs its own app-server over stdio (`ChatGPT.app/Contents/Resources/codex … app-server`, **no** `--listen`), so nothing external can attach to it. `~/.codex/ipc/ipc.sock` is the Electron app's internal IPC, not an app-server. Threads opened there can still be driven through the bridge, but by resuming from the rollout `.jsonl` rather than attaching live.
 - **A thread currently open in the desktop app cannot be written to** — Codex holds a per-thread writer lock (`~/.codex/thread-writer-locks/`) and returns `thread <id> already has an active writer`. That error is the guard working, not data loss. Check `status` with `list_codex_threads` first and only send when it is `idle` or `notLoaded` and not open in the app.
-- **Threads created by the bridge do not show a title in the app.** The app lists from `~/.codex/session_index.jsonl`, and entries land there only once a thread has been named — naming is done by the app, not the app-server. The thread still exists in `~/.codex/state_5.sqlite` and opens via the `codex://threads/<id>` deep link.
+- **Bridge-created threads are named before they are opened.** The bridge calls the app-server's `thread/name/set` with the requested title, or derives `[project] first line of prompt`, then opens the exact `codex://threads/<id>` link. This gives Codex Desktop a visible session title and preserves the precise `cwd` in the thread metadata.
 - A repo living on the NTFS partition of a dual-boot machine (`/Volumes/<label>/...`) is **read-only** under macOS. Keep a separate checkout on an APFS volume to run and edit it.
 - `codex app-server daemon start` uses the `unix://` transport with a control socket at `~/.codex/app-server-control/app-server-control.sock`. The bridge does **not** use that path (different framing, no public API) — it always talks over `ws://`.
 
@@ -350,13 +374,13 @@ python3 -c "import json;[print(v['properties']['method'].get('const') or v['prop
 
 **The bridge disappears from Claude after sending into a busy thread.** Fixed in 1.6.0. A rejected `turn/start` — which is exactly what a thread locked by the desktop app produces — also rejected an internal promise nothing was awaiting. Node treats that as an unhandled rejection and, by default, exits the process, so the MCP server died while the tool handler was still formatting a tidy error message for a client that no longer had a server. Pinned by a test that runs the failure in a real child process and asserts it exits 0.
 
-**The Codex app says a thread is "open in another application".** That is the per-thread writer lock, and the other application is usually this bridge: the shared app-server takes the lock when it loads a thread and keeps it until it exits, so the desktop app cannot write to the same thread. `open_codex_thread` and `openInApp` now say so at the moment they open a thread the bridge is holding, instead of leaving the app's message to be decoded. Release it with `stop_codex_app_server` once the hand-off is done — the bridge starts a new app-server the next time it needs one. A thread held by a *different* Codex window is the app's own lock; close it there.
+**The Codex app says a thread is "open in another application".** That is the per-thread writer lock, and the other application is usually this bridge: the shared app-server takes the lock when it loads a thread and keeps it until it exits, so the desktop app cannot write to the same thread. `delegate_to_codex` releases the bridge server before opening the final desktop link when `releaseAfterTurn` is enabled. For an existing thread, pass `releaseAfterTurn: true` or call `stop_codex_app_server` once the hand-off is done — the bridge starts a new app-server the next time it needs one. A thread held by a *different* Codex window is the app's own lock; close it there.
 
 **A thread opens against the wrong directory.** The same project sits at a different absolute path on each machine: on the shared drive's letter under Windows, under its mount point when that drive is visible from macOS (**read-only** there), and in a native checkout otherwise. Since 1.4.0 the bridge picks the candidate that both **exists and is writable** on the current machine and prints a `note: cwd remapped …` line whenever it rewrites one. If nothing usable exists it fails immediately instead of opening a thread somewhere wrong. Handing Codex a read-only cwd is a reliable way to hit the freeze above: it runs a few reads, then asks for write permission and stalls.
 
-**The path as given always goes first.** If this machine can already write there, nothing is rewritten — guessing over an explicit instruction would be the bug. Rewriting only happens for a path this machine cannot use, which is exactly the case it exists for: macOS mounts NTFS read-only, so the drive a Windows brief quotes is visible and useless at the same time.
+**A path from another machine is remapped before it can cause a wrong checkout.** An explicit `CODEX_BRIDGE_PATH_MAP` is checked first. Otherwise the bridge keeps a path that already exists and is writable, and only then tries portable candidates for foreign drive letters, mount points, or UNC shares. If nothing usable exists it fails with the paths it tried instead of opening Codex in a guessed directory.
 
-A path counts as coming from elsewhere when it names a drive letter (`D:\project`) or an attached volume (`/Volumes/<label>/project`, `/mnt/<label>/project`, `/media/<user>/<label>/project`). No particular letter or label is blessed, so any dual-boot or external-disk layout works without configuration. The bridge then looks for that project name 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, which is measured rather than configured. Override the list with `CODEX_BRIDGE_WORKSPACE_ROOTS`, or set `CODEX_BRIDGE_REMAP=0` to switch the rewriting off entirely.
+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`.
 
@@ -373,17 +397,20 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:8791` | Shared **loopback-only** app-server endpoint. Non-loopback endpoints are rejected because this bridge does not implement remote WebSocket authentication. |
 | `CODEX_BIN` | auto-detected | Path to `codex` used for autostart. |
 | `CODEX_BRIDGE_AUTOSTART` | `1` | `0` = never spawn an app-server; one must already be running. |
-| `CODEX_BRIDGE_THREAD_POLICY` | `owned` | What authorizes a thread: `owned` (created by this bridge, or listed in `CODEX_BRIDGE_ALLOWED_THREADS`) or `roots` (working inside `CODEX_BRIDGE_ALLOWED_ROOTS`). Default is unchanged on upgrade, so an existing install never widens by itself. |
-| `CODEX_BRIDGE_ALLOWED_THREADS` | empty | Exact comma-separated thread IDs permitted for read/send/interrupt/open/list. Empty means no pre-existing thread access. |
-| `CODEX_BRIDGE_ALLOWED_ROOTS` | empty (installer sets its repo root) | Absolute project directories permitted for `cwd`, separated by `:` (`;` on Windows). |
+| `CODEX_BRIDGE_THREAD_POLICY` | `owned` in the direct server; installer writes `roots` for new v1.11.2 entries | What authorizes a thread: `owned` (created by this bridge, or listed in `CODEX_BRIDGE_ALLOWED_THREADS`) or `roots` (working inside `CODEX_BRIDGE_ALLOWED_ROOTS`). Existing config values are preserved on upgrade. |
+| `CODEX_BRIDGE_ALLOWED_THREADS` | empty | Exact comma-separated thread IDs permitted for read/send/interrupt/open/list; `*` explicitly permits every thread ID. Under `roots`, the workspace check still runs. |
+| `CODEX_BRIDGE_ALLOWED_ROOTS` | `*` in the v1.11.2 installer | Absolute project directories permitted for `cwd`, separated by `:` (`;` on Windows); `*` means every usable workspace. |
 | `CODEX_BRIDGE_APPROVAL` | `deny` | How to answer approval requests from Codex. `approve` is ignored unless `CODEX_BRIDGE_AUTO_APPROVE_ACK=1` is also set. |
 | `CODEX_BRIDGE_AUTO_APPROVE_ACK` | empty | Explicit acknowledgement required to enable automatic command/file approval; set to `1` only after reviewing the risk. |
 | `CODEX_BRIDGE_APPROVAL_POLICY` | `on-request` | Policy applied to threads created by the bridge. It is no longer caller-controlled. |
 | `CODEX_BRIDGE_SANDBOX` | `workspace-write` | Sandbox applied to threads created by the bridge: `read-only` or `workspace-write`; unrestricted `danger-full-access` is rejected. |
 | `CODEX_BRIDGE_REMAP` | `1` | `0` disables cwd remapping between a shared drive and a local checkout. |
+| `CODEX_BRIDGE_PATH_MAP` | empty | Optional JSON object mapping absolute source paths to absolute target paths; use it when the same project has a known different path on another machine. |
 | `CODEX_BRIDGE_WORKSPACE_ROOTS` | `$HOME` and the bridge's parent directory | Where to look for a project by name, most preferred first, separated by `:` (`;` on Windows). Setting it replaces the derived roots rather than adding to them. |
 | `CODEX_BRIDGE_MODEL` | from `~/.codex/config.toml` | Default model for threads and turns the bridge creates, e.g. `gpt-5.6-luna`. |
 | `CODEX_BRIDGE_EFFORT` | from `~/.codex/config.toml` | Default reasoning effort: `minimal` · `low` · `medium` · `high` · `xhigh` · `ultra`. |
+| `CODEX_BRIDGE_OPEN_IN_APP` | `1` on Windows, `0` elsewhere | Open delegated or sent threads through the `codex://threads/<id>` desktop link. |
+| `CODEX_BRIDGE_RELEASE_AFTER_TURN` | `1` on Windows, `0` elsewhere | Stop the shared bridge app-server after a terminal turn so Codex Desktop can write the handed-off thread. |
 | `CLAUDE_BRIDGE_PEER_NAME` | `codex-<pid>` | The name Claude shows for this bridge in its agent list. |
 | `CLAUDE_BRIDGE_CWD` | the process cwd | The working directory the peer advertises. |
 | `CLAUDE_DESKTOP_CONFIG` | auto-detected | Override the config path used by `install-claude-desktop.mjs`. |

package/package.json

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

package/scripts/check.mjs

@@ -4,9 +4,32 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const bridgeEnvNames = [
+  "CODEX_APP_SERVER_URL",
+  "CODEX_BIN",
+  "CODEX_BRIDGE_ALLOWED_ROOTS",
+  "CODEX_BRIDGE_ALLOWED_THREADS",
+  "CODEX_BRIDGE_APPROVAL",
+  "CODEX_BRIDGE_AUTO_APPROVE_ACK",
+  "CODEX_BRIDGE_APPROVAL_POLICY",
+  "CODEX_BRIDGE_AUTOSTART",
+  "CODEX_BRIDGE_EFFORT",
+  "CODEX_BRIDGE_MODEL",
+  "CODEX_BRIDGE_PATH_MAP",
+  "CODEX_BRIDGE_REMAP",
+  "CODEX_BRIDGE_SANDBOX",
+  "CODEX_BRIDGE_THREAD_POLICY",
+  "CODEX_BRIDGE_WORKSPACE_ROOTS",
+];
+const bridgeEnv = Object.fromEntries(
+  bridgeEnvNames
+    .filter((name) => process.env[name] !== undefined)
+    .map((name) => [name, process.env[name]]),
+);
 const transport = new StdioClientTransport({
   command: process.execPath,
   args: [path.join(root, "src", "index.mjs")],
+  env: bridgeEnv,
   stderr: "inherit",
 });
 const client = new Client({ name: "bridge-check", version: "1.0.0" });

package/scripts/install-claude-desktop.mjs

@@ -3,19 +3,21 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
+import { IS_WINDOWS, PLATFORM_LABEL, claudeDesktopConfigPath, resolveCodexBin } from "../src/platform.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cfgPath = process.env.CLAUDE_DESKTOP_CONFIG ?? claudeDesktopConfigPath();
+const reset = process.argv.includes("--reset");
 
 /**
- * When the package is installed as a dependency its own directory is never a
- * workspace anybody wants to drive Codex in - defaulting to it produces an
- * entry that starts fine and then refuses every thread. Fall back to the
- * directory the operator ran the installer from instead, and say so out loud.
+ * This bridge is intentionally the local hand-off point between Claude and
+ * Codex. A thread can have been opened from any checkout on this machine (or
+ * report a checkout from another machine), so a machine-specific install path
+ * is the wrong default: it starts successfully and then refuses the useful
+ * thread. The bridge still resolves/remaps the reported cwd and requires a
+ * usable directory before it acts.
  */
-const installedAsDependency = root.split(path.sep).includes("node_modules");
-const defaultRoots = installedAsDependency ? process.cwd() : root;
+const defaultRoots = "*";
 
 const nodeBin = process.env.NODE_EXE ?? process.execPath;
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
@@ -31,16 +33,63 @@ fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
 
 const cfg = fs.existsSync(cfgPath) ? JSON.parse(fs.readFileSync(cfgPath, "utf8")) : {};
 cfg.mcpServers = cfg.mcpServers ?? {};
+
+/**
+ * Re-running the installer used to assign a whole new entry over the old one,
+ * which silently deleted every setting the installer does not itself write -
+ * CODEX_BRIDGE_ALLOWED_THREADS and a hand-added CODEX_BRIDGE_THREAD_POLICY
+ * among them - and reset CODEX_BRIDGE_ALLOWED_ROOTS back to the install
+ * directory. Upgrading is the moment people re-run this, so the command they
+ * reach for to keep the bridge current was the command that broke it.
+ *
+ * Existing values are now the fallback rather than the casualty. Precedence,
+ * highest first: an environment variable passed to this run, what the config
+ * already says, then the default. `--reset` drops the middle one for the rare
+ * case of wanting the defaults back.
+ */
+const previousEnv = (reset ? {} : cfg.mcpServers["codex-bridge"]?.env) ?? {};
+const settled = (name, fallback) => process.env[name] ?? previousEnv[name] ?? fallback;
+
+const kept = Object.keys(previousEnv).filter(
+  (name) => process.env[name] === undefined && name !== "CODEX_BIN",
+);
+
 cfg.mcpServers["codex-bridge"] = {
   command: nodeBin,
   args: [path.join(root, "src", "index.mjs")],
   env: {
+    /**
+     * Keys this installer knows nothing about survive too - a setting added by
+     * a later version, or by hand, is not this script's to throw away.
+     */
+    ...previousEnv,
+    /**
+     * These three are the point of re-running: they name where the code and
+     * the codex binary actually live now, so they are resolved fresh rather
+     * than inherited.
+     */
     CODEX_BIN: codexBin,
-    CODEX_APP_SERVER_URL: process.env.CODEX_APP_SERVER_URL ?? "ws://127.0.0.1:8791",
-    CODEX_BRIDGE_ALLOWED_ROOTS: process.env.CODEX_BRIDGE_ALLOWED_ROOTS ?? defaultRoots,
-    CODEX_BRIDGE_APPROVAL: process.env.CODEX_BRIDGE_APPROVAL ?? "deny",
-    CODEX_BRIDGE_APPROVAL_POLICY: process.env.CODEX_BRIDGE_APPROVAL_POLICY ?? "on-request",
-    CODEX_BRIDGE_SANDBOX: process.env.CODEX_BRIDGE_SANDBOX ?? "workspace-write",
+    CODEX_APP_SERVER_URL: settled("CODEX_APP_SERVER_URL", "ws://127.0.0.1:8791"),
+    CODEX_BRIDGE_ALLOWED_ROOTS: settled("CODEX_BRIDGE_ALLOWED_ROOTS", defaultRoots),
+    CODEX_BRIDGE_APPROVAL: settled("CODEX_BRIDGE_APPROVAL", "deny"),
+    CODEX_BRIDGE_APPROVAL_POLICY: settled("CODEX_BRIDGE_APPROVAL_POLICY", "on-request"),
+    /**
+     * Written out even at its default so it is visible in the file. Left
+     * implicit, the one setting that decides whether the bridge can reach a
+     * thread a human opened is a variable you have to already know exists -
+     * and the symptom when you do not, every thread answering NOT AUTHORIZED,
+     * points nowhere near it.
+     */
+    CODEX_BRIDGE_THREAD_POLICY: settled("CODEX_BRIDGE_THREAD_POLICY", "roots"),
+    CODEX_BRIDGE_SANDBOX: settled("CODEX_BRIDGE_SANDBOX", "workspace-write"),
+    CODEX_BRIDGE_OPEN_IN_APP: settled("CODEX_BRIDGE_OPEN_IN_APP", IS_WINDOWS ? "1" : "0"),
+    CODEX_BRIDGE_RELEASE_AFTER_TURN: settled("CODEX_BRIDGE_RELEASE_AFTER_TURN", IS_WINDOWS ? "1" : "0"),
+    ...(process.env.CODEX_BRIDGE_ALLOWED_THREADS !== undefined
+      ? { CODEX_BRIDGE_ALLOWED_THREADS: process.env.CODEX_BRIDGE_ALLOWED_THREADS }
+      : {}),
+    ...(process.env.CODEX_BRIDGE_PATH_MAP !== undefined
+      ? { CODEX_BRIDGE_PATH_MAP: process.env.CODEX_BRIDGE_PATH_MAP }
+      : {}),
     ...(process.env.CODEX_BRIDGE_MODEL ? { CODEX_BRIDGE_MODEL: process.env.CODEX_BRIDGE_MODEL } : {}),
     ...(process.env.CODEX_BRIDGE_EFFORT ? { CODEX_BRIDGE_EFFORT: process.env.CODEX_BRIDGE_EFFORT } : {}),
   },
@@ -55,6 +104,14 @@ fs.writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`updated ${cfgPath}`);
 console.log(JSON.stringify(cfg.mcpServers["codex-bridge"], null, 2));
+
+if (reset) {
+  console.log("\n--reset: existing values were discarded in favour of the defaults.");
+} else if (kept.length) {
+  console.log(`\nkept from the existing entry: ${kept.join(", ")}`);
+  console.log("Pass the variable to override one, or --reset to drop them all.");
+}
+
 const writtenRoots = cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_ALLOWED_ROOTS;
 if (writtenRoots.split(path.delimiter).some((entry) => entry.split(path.sep).includes("node_modules"))) {
   console.log(
@@ -64,4 +121,14 @@ if (writtenRoots.split(path.delimiter).some((entry) => entry.split(path.sep).inc
   );
 }
 
+if (cfg.mcpServers["codex-bridge"].env.CODEX_BRIDGE_THREAD_POLICY === "owned") {
+  console.log(
+    "\nNOTE: thread policy is `owned` - this bridge may only act on threads it created itself.\n" +
+      "A thread you open in the Codex app or the VS Code extension will answer NOT AUTHORIZED,\n" +
+      "because its id is assigned as it opens and cannot be allowlisted in advance. To let the\n" +
+      "bridge reach any thread working inside CODEX_BRIDGE_ALLOWED_ROOTS, re-run with:\n" +
+      "  CODEX_BRIDGE_THREAD_POLICY=roots codex-mcp-bridge-install",
+  );
+}
+
 console.log("\nRestart Claude Desktop to load the bridge.");

package/scripts/release-notes.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Prints one version's section of the changelog, so a GitHub release carries
+ * the notes that were already written by hand rather than a generated list of
+ * commit subjects. Used by the publish workflow and runnable on its own when a
+ * release has to be created after the fact.
+ */
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function releaseNotes(changelog, version) {
+  const lines = changelog.split("\n");
+  const heading = lines.findIndex((line) => line.startsWith(`## [${version}]`));
+  if (heading === -1) return null;
+
+  const rest = lines.slice(heading + 1);
+  const next = rest.findIndex((line) => line.startsWith("## ["));
+  const body = (next === -1 ? rest : rest.slice(0, next)).join("\n").trim();
+  return body === "" ? null : body;
+}
+
+/**
+ * Only runs the CLI when invoked directly - importing this from a test must
+ * not read argv or exit the process.
+ */
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const version = process.argv[2] ?? JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  const notes = releaseNotes(fs.readFileSync(path.join(root, "CHANGELOG.md"), "utf8"), version);
+
+  if (!notes) {
+    process.stderr.write(`CHANGELOG.md has no entry for ${version}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`${notes}\n`);
+}

package/src/app-server-client.mjs

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { setTimeout as delay } from "node:timers/promises";
 
 import { PLATFORM_LABEL, resolveCodexBin, spawnEnv } from "./platform.mjs";
@@ -8,6 +8,45 @@ const DEFAULT_URL = "ws://127.0.0.1:8791";
 const CONNECT_ATTEMPTS = 2;
 const CONNECT_RETRY_DELAY_MS = 750;
 
+export function parseListeningPids(output, port) {
+  const suffix = `:${port}`;
+  return [
+    ...new Set(
+      String(output)
+        .split(/\r?\n/)
+        .map((line) => line.trim().split(/\s+/))
+        .filter((fields) => fields[0]?.toUpperCase() === "TCP")
+        .filter((fields) => fields.some((field) => field.toUpperCase() === "LISTENING"))
+        .filter((fields) => fields[1]?.endsWith(suffix))
+        .map((fields) => Number(fields.at(-1)))
+        .filter((pid) => Number.isInteger(pid) && pid > 0),
+    ),
+  ];
+}
+
+function appServerPort(url) {
+  return url.replace(/^wss?:\/\//, "").split("/")[0].split(":").pop();
+}
+
+function listeningPids(port) {
+  if (process.platform === "win32") {
+    return parseListeningPids(
+      execFileSync("netstat.exe", ["-ano", "-p", "tcp"], {
+        env: spawnEnv(),
+        windowsHide: true,
+      }),
+      port,
+    );
+  }
+  return execFileSync("/usr/sbin/lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+    env: spawnEnv(),
+  })
+    .toString()
+    .split("\n")
+    .map((line) => Number(line.trim()))
+    .filter(Boolean);
+}
+
 function httpBase(wsUrl) {
   return wsUrl.replace(/^ws:/, "http:").replace(/^wss:/, "https:").replace(/\/+$/, "");
 }
@@ -101,25 +140,32 @@ export class CodexAppServerClient {
    */
   async stopServer() {
     if (!(await this.isServerUp())) return { stopped: false, reason: "no app-server was listening" };
-    const port = this.url.replace(/^wss?:\/\//, "").split("/")[0].split(":").pop();
-    const { execFileSync } = await import("node:child_process");
-    const pids = execFileSync("/usr/sbin/lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
-      env: spawnEnv(),
-    })
-      .toString()
-      .split("\n")
-      .map((line) => Number(line.trim()))
-      .filter(Boolean);
+    const port = appServerPort(this.url);
+    const pids = listeningPids(port);
     if (!pids.length) return { stopped: false, reason: `nothing is listening on port ${port}` };
     this.ws?.close();
     for (const pid of pids) {
       try {
-        process.kill(pid, "SIGTERM");
+        if (process.platform === "win32") {
+          execFileSync("taskkill.exe", ["/PID", String(pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true,
+          });
+        } else {
+          process.kill(pid, "SIGTERM");
+        }
       } catch (err) {
         this.log(`could not stop pid ${pid}: ${err.message}`);
       }
     }
-    return { stopped: true, pids };
+    this.ws = null;
+    this.attachedThreads.clear();
+    this.threadCwds.clear();
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      if (!(await this.isServerUp())) return { stopped: true, pids };
+      await delay(100);
+    }
+    return { stopped: true, pids, stillListening: true };
   }
 
   /**

package/src/claude-bridge.mjs

@@ -8,7 +8,7 @@ import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
 import { runTurn } from "./turn.mjs";
 
-const VERSION = "1.11.0";
+const VERSION = "1.11.2";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 

package/src/index.mjs

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { CodexAppServerClient, writerLockWarning } from "./app-server-client.mjs";
 import {
   IS_MACOS,
+  IS_WINDOWS,
   PLATFORM_LABEL,
   claudeDesktopConfigPath,
   codexThreadUrl,
@@ -15,11 +16,12 @@ import {
   launchAgentPath,
   openThreadInCodexApp,
   resolveWorkspacePath,
+  supportsCodexThreadLinks,
 } from "./platform.mjs";
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 
-const VERSION = "1.11.0";
+const VERSION = "1.11.2";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -29,6 +31,13 @@ const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
  */
 const DEFAULT_MODEL = process.env.CODEX_BRIDGE_MODEL || null;
 const DEFAULT_EFFORT = process.env.CODEX_BRIDGE_EFFORT || null;
+const DEFAULT_OPEN_IN_APP = process.env.CODEX_BRIDGE_OPEN_IN_APP
+  ? process.env.CODEX_BRIDGE_OPEN_IN_APP === "1"
+  : IS_WINDOWS;
+const DEFAULT_RELEASE_AFTER_TURN = process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN
+  ? process.env.CODEX_BRIDGE_RELEASE_AFTER_TURN === "1"
+  : IS_WINDOWS;
+const TERMINAL_TURN_STATUSES = new Set(["completed", "interrupted", "failed"]);
 const security = new BridgeSecurityPolicy();
 
 const client = new CodexAppServerClient({
@@ -54,23 +63,120 @@ const failure = (err) => textResult(`Codex bridge error: ${err?.message ?? Strin
  * allowlisted skips the round-trip entirely: its answer cannot change.
  */
 async function assertThreadAccess(threadId) {
-  if (security.isThreadAuthorized(threadId)) return null;
+  if (security.threadPolicy !== "roots" && security.isThreadAuthorized(threadId)) return null;
   if (security.threadPolicy !== "roots") {
     security.assertThread(threadId);
     return null;
   }
   const res = await client.call("thread/read", { threadId });
-  const thread = res?.thread ?? res ?? {};
+  const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
   security.assertThread(threadId, thread.cwd);
   security.assertCwd(thread.cwd);
   return thread;
 }
 
+function normalizeThreadCwd(thread, { strict = false } = {}) {
+  if (!thread?.cwd) return thread;
+  try {
+    const workspace = resolveWorkspacePath(thread.cwd);
+    return workspace.path === thread.cwd ? thread : { ...thread, cwd: workspace.path };
+  } catch (err) {
+    if (strict) throw err;
+    return thread;
+  }
+}
+
+function projectLabel(cwd) {
+  return cwd.replace(/[\\/]+$/, "").split(/[\\/]/).filter(Boolean).at(-1) || cwd;
+}
+
+function threadNameFor({ cwd, prompt, name }) {
+  const explicit = name?.trim();
+  if (explicit) return explicit.slice(0, 200);
+  const summary = String(prompt ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return `[${projectLabel(cwd)}] ${(summary || "Claude delegation").replace(/\s+/g, " ").slice(0, 160)}`.slice(
+    0,
+    200,
+  );
+}
+
+async function createCodexThread({ cwd, model, name, prompt }) {
+  const workspace = resolveWorkspacePath(cwd);
+  security.assertCwd(workspace.path);
+  const res = await client.call("thread/start", {
+    cwd: workspace.path,
+    ...(model ?? DEFAULT_MODEL ? { model: model ?? DEFAULT_MODEL } : {}),
+    approvalPolicy: security.approvalPolicy,
+    sandbox: security.sandbox,
+  });
+  const thread = res?.thread ?? {};
+  if (!thread.id) throw new Error("Codex app-server created no thread id");
+  const threadName = name || prompt ? threadNameFor({ cwd: thread.cwd ?? workspace.path, prompt, name }) : null;
+  if (threadName) {
+    await client.call("thread/name/set", { threadId: thread.id, name: threadName });
+  }
+  client.markAttached(thread.id, thread);
+  security.registerThread(thread.id);
+  return {
+    threadId: thread.id,
+    name: threadName ?? thread.name ?? "(unnamed)",
+    cwd: thread.cwd ?? workspace.path,
+    rollout: thread.path ?? "(not written yet)",
+    workspace,
+  };
+}
+
+async function finishDesktopHandoff({ threadId, result, openInApp, releaseAfterTurn }) {
+  const notes = [];
+  let canOpenAfterRelease = true;
+  const terminal = TERMINAL_TURN_STATUSES.has(result.status);
+
+  if (releaseAfterTurn && terminal) {
+    try {
+      const released = await client.stopServer();
+      if (released.stopped) {
+        if (released.stillListening) {
+          canOpenAfterRelease = false;
+          notes.push(
+            `stop requested for app-server${released.pids?.length ? ` (pid ${released.pids.join(", ")})` : ""}, but it is still listening`,
+          );
+          notes.push("WARNING: the app-server is still listening, so the desktop thread was not opened to avoid another lock");
+        } else {
+          notes.push(
+            `released app-server${released.pids?.length ? ` (pid ${released.pids.join(", ")})` : ""}; Codex Desktop can write this thread`,
+          );
+        }
+      } else {
+        canOpenAfterRelease = false;
+        notes.push(`could not release app-server: ${released.reason}`);
+      }
+    } catch (err) {
+      canOpenAfterRelease = false;
+      notes.push(`could not release app-server: ${err.message}`);
+    }
+  }
+
+  if (openInApp && (terminal ? canOpenAfterRelease : !releaseAfterTurn)) {
+    try {
+      notes.push(`opened in Codex app: ${await openThreadInCodexApp(threadId)}`);
+    } catch (err) {
+      notes.push(`could not open the thread in the Codex app: ${err.message}`);
+    }
+  } else if (openInApp && releaseAfterTurn && !terminal) {
+    notes.push(`desktop open deferred because the turn status is ${result.status}; release it after the turn finishes`);
+  }
+
+  return notes;
+}
+
 function formatThreadRow(t) {
   const title = t.name || (t.preview ?? "").replace(/\s+/g, " ").slice(0, 70) || "(no title)";
   const updated = t.updatedAt ? new Date(t.updatedAt * 1000).toISOString().replace("T", " ").slice(0, 16) : "?";
   const status = t.status?.type ?? "?";
-  const deepLink = IS_MACOS && hasCodexDesktopApp() ? `\n    open: ${codexThreadUrl(t.id)}` : "";
+  const deepLink = supportsCodexThreadLinks() ? `\n    open: ${codexThreadUrl(t.id)}` : "";
   const authorized = security.isThreadAuthorized(t.id, t.cwd)
     ? ""
     : "\n    NOT AUTHORIZED: add this id to CODEX_BRIDGE_ALLOWED_THREADS, or set " +
@@ -122,10 +228,100 @@ const server = new McpServer(
   { name: "codex-bridge", version: VERSION },
   {
     instructions:
-      "Bridge into a live Codex session. Use list_codex_threads to find the right threadId, " +
-      "then send_to_codex_thread to push a prompt into that exact thread and read Codex's reply. " +
-      "On macOS, open_codex_thread (or openInApp) surfaces the thread in the Codex desktop app so a " +
-      "human can watch it run, and codex_bridge_status reports how the bridge is wired on this machine.",
+      "Bridge Claude work into Codex. Prefer delegate_to_codex: it creates a named Codex thread at the " +
+      "requested cwd, sends the prompt, releases the bridge writer lock, and opens the exact thread in " +
+      "Codex Desktop. Use send_to_codex_thread only when an existing threadId is intentional; use " +
+      "list_codex_threads or read_codex_thread to inspect sessions and codex_bridge_status to inspect wiring.",
+  },
+);
+
+server.registerTool(
+  "delegate_to_codex",
+  {
+    title: "Delegate work to a new Codex session",
+    description:
+      "Create a named Codex session at the requested project directory, send Claude's prompt into it, " +
+      "return Codex's reply, and hand the session to Codex Desktop without leaving the bridge writer lock behind.",
+    inputSchema: {
+      cwd: z.string().describe("Absolute project directory where Codex must work"),
+      prompt: z.string().describe("The complete task Claude is delegating to Codex"),
+      name: z.string().min(1).max(200).optional().describe("Optional Codex session title; otherwise one is derived from the prompt"),
+      timeoutSec: z
+        .number()
+        .int()
+        .min(10)
+        .max(3600)
+        .optional()
+        .describe("How long to wait for the turn to finish (default 240s)"),
+      model: z.string().optional().describe("Model override, e.g. gpt-5.6-luna"),
+      effort: z
+        .enum(["minimal", "low", "medium", "high", "xhigh", "ultra"])
+        .optional()
+        .describe(`Override reasoning effort (default ${DEFAULT_EFFORT ?? "whatever ~/.codex/config.toml says"})`),
+      openInApp: z
+        .boolean()
+        .optional()
+        .describe("Open the finished session in Codex Desktop on Windows or macOS"),
+      releaseAfterTurn: z
+        .boolean()
+        .optional()
+        .describe("Stop the bridge app-server after a terminal turn so Codex Desktop owns the writer lock"),
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+  },
+  async ({ cwd, prompt, name, timeoutSec, model, effort, openInApp, releaseAfterTurn }) => {
+    const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
+    const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
+    const notes = [];
+    try {
+      const created = await createCodexThread({ cwd, prompt, name, model });
+      if (created.workspace.note) notes.push(created.workspace.note);
+      if (shouldOpen && !shouldRelease) {
+        try {
+          notes.push(`opened in Codex app: ${await openThreadInCodexApp(created.threadId)}`);
+        } catch (err) {
+          notes.push(`could not open the thread in the Codex app: ${err.message}`);
+        }
+      }
+      const result = await runTurn(client, {
+        threadId: created.threadId,
+        input: [{ type: "text", text: prompt }],
+        timeoutMs: (timeoutSec ?? 240) * 1000,
+        turnOverrides: {
+          ...(model ?? DEFAULT_MODEL ? { model: model ?? DEFAULT_MODEL } : {}),
+          ...(effort ?? DEFAULT_EFFORT ? { effort: effort ?? DEFAULT_EFFORT } : {}),
+        },
+      });
+      notes.push(
+        ...(await finishDesktopHandoff({
+          threadId: created.threadId,
+          result,
+          openInApp: shouldOpen,
+          releaseAfterTurn: shouldRelease,
+        })),
+      );
+      const failed = result.status === "failed" || result.status === "disconnected";
+      return textResult(
+        [
+          "Delegated to Codex",
+          `threadId: ${created.threadId}`,
+          `name:     ${created.name}`,
+          `cwd:      ${created.cwd}`,
+          `rollout:  ${created.rollout}`,
+          ...notes,
+          "",
+          formatTurn(result),
+        ].join("\n"),
+        failed,
+      );
+    } catch (err) {
+      return failure(err);
+    }
   },
 );
 
@@ -152,10 +348,15 @@ server.registerTool(
         .enum(["minimal", "low", "medium", "high", "xhigh", "ultra"])
         .optional()
         .describe(`Override reasoning effort (default ${DEFAULT_EFFORT ?? "whatever ~/.codex/config.toml says"})`),
+      name: z.string().min(1).max(200).optional().describe("Optional title to show for this Codex session"),
       openInApp: z
         .boolean()
         .optional()
-        .describe("macOS only: open the thread in the Codex desktop app before sending so a human can watch it live"),
+        .describe("Open the thread in Codex Desktop on Windows or macOS so a human can watch it live"),
+      releaseAfterTurn: z
+        .boolean()
+        .optional()
+        .describe("Stop the bridge app-server after a terminal turn so Codex Desktop owns the writer lock"),
     },
     annotations: {
       readOnlyHint: false,
@@ -164,29 +365,40 @@ server.registerTool(
       openWorldHint: true,
     },
   },
-  async ({ threadId, prompt, timeoutSec, cwd, model, effort, openInApp }) => {
-    let openNote = null;
+  async ({ threadId, prompt, timeoutSec, cwd, model, effort, name, openInApp, releaseAfterTurn }) => {
+    const notes = [];
+    const shouldOpen = openInApp ?? DEFAULT_OPEN_IN_APP;
+    const shouldRelease = releaseAfterTurn ?? DEFAULT_RELEASE_AFTER_TURN;
     try {
-      await assertThreadAccess(threadId);
+      const authorizedThread = await assertThreadAccess(threadId);
       let resolvedCwd = null;
       if (cwd) {
         const workspace = resolveWorkspacePath(cwd);
         security.assertCwd(workspace.path);
         resolvedCwd = workspace.path;
-        if (workspace.note) openNote = openNote ? `${openNote}\n${workspace.note}` : workspace.note;
+        if (workspace.note) notes.push(workspace.note);
+      } else if (authorizedThread?.cwd) {
+        const workspace = resolveWorkspacePath(authorizedThread.cwd);
+        resolvedCwd = workspace.path;
+        if (workspace.note) notes.push(workspace.note);
       }
       const attached = await client.ensureThreadAttached(threadId, resolvedCwd ? { cwd: resolvedCwd } : {});
-      security.assertCwd(attached.thread?.cwd);
+      const attachedThread = normalizeThreadCwd(attached.thread ?? authorizedThread, { strict: true });
+      security.assertCwd(attachedThread?.cwd);
+      if (name) {
+        await client.call("thread/name/set", { threadId, name: name.trim().slice(0, 200) });
+        notes.push(`session name: ${name.trim().slice(0, 200)}`);
+      }
       /**
        * Opening the thread in the app comes after both gates. It ran first
        * once, which meant a thread this bridge was about to refuse still got
        * raised on screen - a refusal that leaked which threads exist.
        */
-      if (openInApp) {
+      if (shouldOpen && !shouldRelease) {
         try {
-          openNote = `opened in Codex app: ${await openThreadInCodexApp(threadId)}`;
+          notes.push(`opened in Codex app: ${await openThreadInCodexApp(threadId)}`);
         } catch (err) {
-          openNote = `could not open the thread in the Codex app: ${err.message}`;
+          notes.push(`could not open the thread in the Codex app: ${err.message}`);
         }
       }
       const result = await runTurn(client, {
@@ -201,8 +413,14 @@ server.registerTool(
       });
       const body = formatTurn(result);
       const failed = result.status === "failed" || result.status === "disconnected";
-      const held = openInApp && client.holdsThread(threadId) ? writerLockWarning(threadId) : "";
-      return textResult(`${openNote ? `${openNote}\n${body}` : body}${held}`, failed);
+      notes.push(...(await finishDesktopHandoff({
+        threadId,
+        result,
+        openInApp: shouldOpen,
+        releaseAfterTurn: shouldRelease,
+      })));
+      const held = shouldOpen && !shouldRelease && client.holdsThread(threadId) ? writerLockWarning(threadId) : "";
+      return textResult(`${notes.length ? `${notes.join("\n")}\n` : ""}${body}${held}`, failed);
     } catch (err) {
       return failure(err);
     }
@@ -240,7 +458,15 @@ server.registerTool(
       if (searchTerm) params.searchTerm = searchTerm;
       const method = loadedOnly ? "thread/loaded/list" : "thread/list";
       const res = await client.call(method, loadedOnly ? { limit: limit ?? 15 } : params);
-      const rows = security.filterThreads(res?.data ?? res?.threads ?? []);
+      const rows = security.filterThreads(
+        (res?.data ?? res?.threads ?? []).flatMap((thread) => {
+          try {
+            return [normalizeThreadCwd(thread, { strict: true })];
+          } catch {
+            return [];
+          }
+        }),
+      );
       if (!rows.length) {
         return textResult(
           security.summary().allowedRoots.length
@@ -266,6 +492,7 @@ server.registerTool(
     inputSchema: {
       cwd: z.string().describe("Absolute working directory for the new Codex session"),
       model: z.string().optional().describe("Model override, e.g. gpt-5.6-luna"),
+      name: z.string().min(1).max(200).optional().describe("Optional title to show for the new Codex session"),
     },
     annotations: {
       readOnlyHint: false,
@@ -274,28 +501,17 @@ server.registerTool(
       openWorldHint: true,
     },
   },
-  async ({ cwd, model }) => {
+  async ({ cwd, model, name }) => {
     try {
-      const workspace = resolveWorkspacePath(cwd);
-      security.assertCwd(workspace.path);
-      const res = await client.call("thread/start", {
-        cwd: workspace.path,
-        ...(model ?? DEFAULT_MODEL ? { model: model ?? DEFAULT_MODEL } : {}),
-        approvalPolicy: security.approvalPolicy,
-        sandbox: security.sandbox,
-      });
-      const thread = res?.thread ?? {};
-      if (thread.id) {
-        client.markAttached(thread.id, thread);
-        security.registerThread(thread.id);
-      }
+      const created = await createCodexThread({ cwd, model, name });
       return textResult(
         [
           "Created Codex thread",
-          `  threadId: ${thread.id}`,
-          `  cwd: ${thread.cwd}`,
-          `  rollout: ${thread.path ?? "(not written yet)"}`,
-          ...(workspace.note ? [`  note: ${workspace.note}`] : []),
+          `  threadId: ${created.threadId}`,
+          `  name: ${created.name}`,
+          `  cwd: ${created.cwd}`,
+          `  rollout: ${created.rollout}`,
+          ...(created.workspace.note ? [`  note: ${created.workspace.note}`] : []),
         ].join("\n"),
       );
     } catch (err) {
@@ -322,7 +538,7 @@ server.registerTool(
     try {
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId, includeTurns: true });
-      const thread = res?.thread ?? res ?? {};
+      const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
       security.assertCwd(thread.cwd);
       const items = (thread.turns ?? []).flatMap((t) => t.items ?? []);
       const msgs = items
@@ -364,8 +580,9 @@ server.registerTool(
   async ({ threadId, turnId }) => {
     try {
       await assertThreadAccess(threadId);
-      const thread = await client.call("thread/read", { threadId });
-      security.assertCwd((thread?.thread ?? thread)?.cwd);
+      const res = await client.call("thread/read", { threadId });
+      const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
+      security.assertCwd(thread.cwd);
       await client.call("turn/interrupt", { threadId, turnId });
       return textResult(`Interrupted turn ${turnId} in thread ${threadId}.`);
     } catch (err) {
@@ -379,7 +596,7 @@ server.registerTool(
   {
     title: "Open a Codex thread in the desktop app",
     description:
-      "macOS only: bring a Codex thread to the front in the Codex desktop app (codex://threads/<id>) " +
+      "Bring a Codex thread to the front on Windows or macOS using (codex://threads/<id>) " +
       "so a human can watch the work live instead of reading the transcript afterwards.",
     inputSchema: {
       threadId: z.string().describe("Codex thread id"),
@@ -398,8 +615,9 @@ server.registerTool(
   async ({ threadId, background }) => {
     try {
       await assertThreadAccess(threadId);
-      const thread = await client.call("thread/read", { threadId });
-      security.assertCwd((thread?.thread ?? thread)?.cwd);
+      const res = await client.call("thread/read", { threadId });
+      const thread = normalizeThreadCwd(res?.thread ?? res ?? {}, { strict: true });
+      security.assertCwd(thread.cwd);
       const url = await openThreadInCodexApp(threadId, { activate: !background });
       const held = client.holdsThread(threadId) ? writerLockWarning(threadId) : "";
       return textResult(`Opened ${url} in the Codex desktop app.${held}`);
@@ -445,7 +663,7 @@ server.registerTool(
     title: "Check the Codex bridge environment",
     description:
       "Report how this bridge is wired on the current machine: platform, resolved codex binary, " +
-      "app-server endpoint and whether it is live, plus the macOS integrations (LaunchAgent, desktop app).",
+      "app-server endpoint and whether it is live, plus desktop deep-link support and macOS integrations.",
     inputSchema: {},
     annotations: {
       readOnlyHint: true,
@@ -453,6 +671,7 @@ server.registerTool(
     },
   },
   async () => {
+    const summary = security.summary();
     const up = await client.isServerUp();
     let liveThreads = null;
     if (up) {
@@ -471,7 +690,8 @@ server.registerTool(
       `defaults:       model ${DEFAULT_MODEL ?? "(from ~/.codex/config.toml)"}, effort ${DEFAULT_EFFORT ?? "(from ~/.codex/config.toml)"}`,
       `app-server:     ${client.url} - ${up ? "live" : "not reachable"}`,
       `autostart:      ${client.autoStart ? "on" : "off"}   approvals: ${client.approval}`,
-      `security:       thread policy ${security.threadPolicy} (${security.summary().authorizedThreads} pre-authorized thread(s)), ${security.summary().allowedRoots.length} allowed root(s), sandbox ${security.sandbox}, approvals ${security.approvalPolicy}`,
+      `desktop links:  ${supportsCodexThreadLinks() ? "codex:// available" : "not available on this platform"}`,
+      `security:       thread policy ${security.threadPolicy} (${summary.allowAllThreads ? "all threads" : `${summary.authorizedThreads} pre-authorized thread(s)`}), ${summary.allowAllRoots ? "all directories" : `${summary.allowedRoots.length} allowed root(s)`}, sandbox ${security.sandbox}, approvals ${security.approvalPolicy}`,
       `live threads:   ${liveThreads ?? "(unknown)"}`,
       `claude desktop config: ${claudeDesktopConfigPath()}`,
     ];

package/src/platform.mjs

@@ -46,6 +46,7 @@ export const homeDir = () => process.env.HOME ?? process.env.USERPROFILE ?? os.h
  */
 const FOREIGN_ROOT_PATTERNS = [
   /^[A-Za-z]:\/(.+)$/,
+  /^\/\/[^/]+\/[^/]+\/(.+)$/,
   /^\/Volumes\/[^/]+\/(.+)$/,
   /^\/mnt\/[^/]+\/(.+)$/,
   /^\/media\/[^/]+\/[^/]+\/(.+)$/,
@@ -179,6 +180,55 @@ function normalizeSeparators(input) {
   return input.replace(/\\/g, "/").replace(/\/+$/, "") || input;
 }
 
+function isNetworkPath(input) {
+  return normalizeSeparators(input).startsWith("//");
+}
+
+function isSameOrWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+/**
+ * Absolute paths in a Claude session can refer to a stale mount or checkout
+ * that happens to remain as an empty directory on this machine. An explicit
+ * JSON map is the deterministic escape hatch: it is checked before the input
+ * path, while the normal workspace-root policy still validates the result.
+ *
+ * Example:
+ *   {"L:\\codex-mcp-bridge":"C:\\codex-mcp-bridge"}
+ */
+function configuredPathMaps() {
+  const raw = process.env.CODEX_BRIDGE_PATH_MAP;
+  if (!raw) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error("Invalid CODEX_BRIDGE_PATH_MAP: expected a JSON object of absolute source paths to targets");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Invalid CODEX_BRIDGE_PATH_MAP: expected a JSON object of absolute source paths to targets");
+  }
+
+  return Object.entries(parsed)
+    .map(([from, to]) => {
+      if (typeof from !== "string" || typeof to !== "string" || !path.isAbsolute(from) || !path.isAbsolute(to)) {
+        throw new Error("Invalid CODEX_BRIDGE_PATH_MAP: every source and target must be an absolute path");
+      }
+      return { from: path.resolve(from), to: path.resolve(to) };
+    })
+    .sort((a, b) => b.from.length - a.from.length);
+}
+
+function pathMapCandidates(input) {
+  const candidate = path.resolve(input);
+  return configuredPathMaps()
+    .filter(({ from }) => isSameOrWithin(from, candidate))
+    .map(({ from, to }) => path.join(to, path.relative(from, candidate)));
+}
+
 function foreignRootRelative(input) {
   const normalized = normalizeSeparators(input);
   for (const pattern of FOREIGN_ROOT_PATTERNS) {
@@ -203,16 +253,22 @@ function remapCandidates(input) {
  * looking at, or one the agent cannot write to - which then stalls the turn on
  * a permission request instead of failing outright.
  *
- * The path as given always goes first: if this machine can already write
- * there, no rewriting is warranted and guessing would be the bug. Rewriting
- * only happens for a path this machine cannot use, which is exactly the case
- * it was written for - macOS mounts NTFS read-only, so the drive a Windows
- * brief quotes is visible and useless at the same time.
+ * An explicit map takes precedence for a stale alias. Otherwise the path as
+ * given goes first: if this machine can already write there, no rewriting is
+ * warranted and guessing would be the bug. Rewriting only happens for a path
+ * this machine cannot use, which is exactly the case it was written for - a
+ * foreign drive, mount, or UNC share can be visible while the original
+ * 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) {
   if (!input) return { path: input, remapped: false, writable: false, note: null };
   const original = input;
-  const candidates = [input, ...(remapEnabled() ? remapCandidates(input) : [])];
+  const mapped = pathMapCandidates(input);
+  const remapped = remapEnabled() ? remapCandidates(input) : [];
+  const candidates = isNetworkPath(input)
+    ? [...mapped, ...remapped, input]
+    : [...mapped, input, ...remapped];
   const ordered = candidates.filter((candidate, index) => candidates.indexOf(candidate) === index);
 
   const writable = ordered.find((candidate) => existsSync(candidate) && isWritableDir(candidate));
@@ -223,7 +279,9 @@ export function resolveWorkspacePath(input) {
       writable: true,
       note:
         writable !== original
-          ? `cwd remapped for ${PLATFORM_LABEL}: ${original} -> ${writable}`
+          ? mapped.includes(writable)
+            ? `cwd mapped for ${PLATFORM_LABEL} via CODEX_BRIDGE_PATH_MAP: ${original} -> ${writable}`
+            : `cwd remapped for ${PLATFORM_LABEL}: ${original} -> ${writable}`
           : null,
     };
   }
@@ -282,6 +340,10 @@ export function hasCodexDesktopApp() {
   return IS_MACOS && existsSync(CODEX_DESKTOP_APP_MACOS);
 }
 
+export function supportsCodexThreadLinks() {
+  return IS_WINDOWS || hasCodexDesktopApp();
+}
+
 export function isLaunchAgentInstalled() {
   return IS_MACOS && existsSync(launchAgentPath());
 }
@@ -304,12 +366,17 @@ export function isDesktopAppServerRunning() {
 /**
  * Bring a thread to the foreground in the Codex desktop app so a human can
  * watch the turn run instead of only reading the transcript afterwards.
- * macOS registers the `codex://` scheme through /Applications/ChatGPT.app.
+ * Windows registers the `codex://` scheme through the packaged Codex app, and
+ * macOS registers it through /Applications/ChatGPT.app.
  */
 export async function openThreadInCodexApp(threadId, { activate = true } = {}) {
   const url = codexThreadUrl(threadId);
+  if (IS_WINDOWS) {
+    await execFileAsync("explorer.exe", [url], { windowsHide: true, timeout: 10000 });
+    return url;
+  }
   if (!IS_MACOS) {
-    throw new Error(`Opening a Codex thread in the desktop app is macOS-only. Open ${url} manually.`);
+    throw new Error(`Opening a Codex thread in the desktop app is supported on Windows and macOS. Open ${url} manually.`);
   }
   if (!hasCodexDesktopApp()) {
     throw new Error(`Codex desktop app not found at ${CODEX_DESKTOP_APP_MACOS}. Install it to use ${url}.`);

package/src/security-policy.mjs

@@ -4,6 +4,8 @@ import path from "node:path";
 const APPROVAL_POLICIES = new Set(["untrusted", "on-failure", "on-request", "never"]);
 const SANDBOXES = new Set(["read-only", "workspace-write"]);
 const THREAD_POLICIES = new Set(["owned", "roots"]);
+const ALLOW_ALL_ROOTS = "*";
+const ALLOW_ALL_THREADS = "*";
 
 /**
  * Resolves the deepest ancestor that exists and re-appends the rest, rather
@@ -49,11 +51,15 @@ function parseList(value) {
 }
 
 function parseRoots(value) {
-  return String(value ?? "")
+  const entries = String(value ?? "")
     .split(path.delimiter)
     .map((entry) => entry.trim())
-    .filter(Boolean)
-    .map(canonicalPath);
+    .filter(Boolean);
+
+  return {
+    allowAll: entries.includes(ALLOW_ALL_ROOTS),
+    roots: entries.filter((entry) => entry !== ALLOW_ALL_ROOTS).map(canonicalPath),
+  };
 }
 
 export function assertAllowedAppServerUrl(value) {
@@ -78,8 +84,12 @@ export function assertAllowedAppServerUrl(value) {
 
 export class BridgeSecurityPolicy {
   constructor(env = process.env) {
-    this.allowedThreadIds = parseList(env.CODEX_BRIDGE_ALLOWED_THREADS);
-    this.allowedRoots = parseRoots(env.CODEX_BRIDGE_ALLOWED_ROOTS);
+    const configuredThreads = parseList(env.CODEX_BRIDGE_ALLOWED_THREADS);
+    this.allowAllThreads = configuredThreads.has(ALLOW_ALL_THREADS);
+    this.allowedThreadIds = new Set([...configuredThreads].filter((threadId) => threadId !== ALLOW_ALL_THREADS));
+    const roots = parseRoots(env.CODEX_BRIDGE_ALLOWED_ROOTS ?? ALLOW_ALL_ROOTS);
+    this.allowAllRoots = roots.allowAll;
+    this.allowedRoots = roots.roots;
     this.ownedThreadIds = new Set();
 
     /**
@@ -130,7 +140,7 @@ export class BridgeSecurityPolicy {
    * inside a root is refused exactly like one placed outside it.
    */
   isThreadAuthorized(threadId, cwd) {
-    if (this.ownedThreadIds.has(threadId) || this.allowedThreadIds.has(threadId)) return true;
+    if (this.allowAllThreads || this.ownedThreadIds.has(threadId) || this.allowedThreadIds.has(threadId)) return true;
     if (this.threadPolicy !== "roots") return false;
     return cwd == null ? false : this.isCwdAuthorized(cwd);
   }
@@ -179,13 +189,15 @@ export class BridgeSecurityPolicy {
   }
 
   isCwdAuthorized(cwd) {
-    if (!this.allowedRoots.length || !cwd) return false;
+    if (!cwd) return false;
+    if (this.allowAllRoots) return true;
+    if (!this.allowedRoots.length) return false;
     const candidate = canonicalPath(cwd);
     return this.allowedRoots.some((root) => isWithin(root, candidate));
   }
 
   assertCwd(cwd) {
-    if (!this.allowedRoots.length) {
+    if (!this.allowAllRoots && !this.allowedRoots.length) {
       throw new Error(
         "No authorized workspace roots are configured. Set CODEX_BRIDGE_ALLOWED_ROOTS to one or more project directories.",
       );
@@ -197,7 +209,9 @@ export class BridgeSecurityPolicy {
   summary() {
     return {
       authorizedThreads: this.allowedThreadIds.size + this.ownedThreadIds.size,
-      allowedRoots: this.allowedRoots,
+      allowAllThreads: this.allowAllThreads,
+      allowedRoots: this.allowAllRoots ? [ALLOW_ALL_ROOTS] : this.allowedRoots,
+      allowAllRoots: this.allowAllRoots,
       threadPolicy: this.threadPolicy,
       approvalPolicy: this.approvalPolicy,
       sandbox: this.sandbox,