@minhspark/codex-mcp-bridge 1.11.3 → 1.12.1

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.12.1] - 2026-09-05
+
+### Fixed
+
+- **Windows no longer loses the Codex Desktop native relay to a Unix-only transport.** The Claude peer endpoint
+  and the Codex Desktop companion now use local named pipes on Windows, while macOS and Linux keep their Unix
+  sockets. The same platform-aware endpoint detection is used by status checks and cleanup, so a live Windows
+  companion is not mistaken for a missing session or deleted as a stale file.
+- **Live Claude sessions no longer disappear intermittently while their registry file is being rewritten.** Session
+  metadata is read twice and retried until stable, and peer delivery retries the short startup window before the
+  named pipe is listening. A session that is alive but still bringing up its Windows pipe remains visible and
+  deliverable.
+- **A disconnected hand-off now releases the bridge app-server when release-after-turn is enabled.** This prevents
+  a dropped turn from leaving a writer lock behind and blocking Codex Desktop on the next open.
+- **Windows resolves the versioned Codex Desktop binary before older install locations.** The bridge and installers
+  therefore use the current desktop executable instead of silently attaching to an obsolete copy.
+
+## [1.12.0] - 2026-09-04
+
+### Added
+
+- **A thread open in Codex Desktop can now receive Claude's messages without being taken away from the app.**
+  Binding a thread with `bind_codex_thread` and then watching it in Codex Desktop was the workflow the relay
+  was built for, and it was the one case that could not work: Codex takes a per-thread writer lock when the
+  app loads a thread and holds it while the thread is open, so the relay's `thread/resume` was refused with
+  `thread <id> already has an active writer`. The only way through was to close the thread before every
+  message - which gives up the reason the thread was bound in the first place.
+
+  The fix is to stop bringing a second writer. `codex-native-relay` is a companion MCP process that Codex
+  Desktop launches itself, so it already sits inside the app's context and can ask the app's own app-server
+  to deliver the message. Nothing attaches, nothing resumes, no second app-server starts, and the desktop app
+  stays the single writer of the thread throughout. `claude-bridge` reaches it over a private mode-`0600`
+  unix socket at `~/.codex/native-relay.sock` and sends exactly `{ targetThreadId, message }`.
+
+  `codex_app.send_message_to_thread` runs against an *executor* thread, distinct from the destination and
+  validated by Codex - a synthetic UUID is rejected. A dedicated relay thread carries that role so the watched
+  thread never has to: `scripts/install-native-relay.mjs` creates it once, records it in
+  `~/.codex/native-relay.json`, and stops the app-server it borrowed so no lock is left held. Resolution is
+  `CODEX_RELAY_ID`, then that file, then an explicit error naming both - never an invented id, which Codex
+  would reject with a message that says nothing about the missing configuration behind it.
+
+- Delivery is now a **backend choice** rather than a call, in `src/thread-delivery.mjs`. Nothing else moves:
+  the Claude peer protocol, `list_claude_sessions`, `send_to_claude_session`, `bind_codex_thread`, the routing,
+  the ping-pong limits, `codex-mcp-bridge`, `CodexAppServerClient` and the thread authorization policies are
+  unchanged, and the app-server path stays the default for every thread Codex Desktop does not own. The native
+  path is macOS-only, feature-detected on the companion socket, and switched off entirely with
+  `CODEX_BRIDGE_NATIVE_RELAY=0`.
+
+  An unreachable companion falls back to the app-server path, because an absent relay says nothing about the
+  target thread. A companion that answered with a *refusal* does not: Codex has already been asked, and a
+  second app-server would only contend for the `~/.codex` state before failing on the very writer lock the
+  native path exists to avoid.
+
+- `claude_bridge_status` and `bind_codex_thread` report the backend in force, and carry the reason when it is
+  not the native one - a missing companion socket, an explicit `0`, and an unsupported platform are three
+  different problems that otherwise look identical from the outside.
+
+- `native_relay_status` on the companion reports its socket, its executor thread and the dispatch method.
+  `npm run install:relay` / `npm run uninstall:relay` register and remove it.
+
+### Security
+
+- The relay socket is created mode `0600` inside the Codex home and swept on exit; that file mode is the whole
+  boundary, exactly as it already is for the Claude peer protocol. The companion accepts one payload shape,
+  caps a frame at 128 KiB on both halves, and refuses a destination that is its own executor thread - otherwise
+  a mistaken bind would deliver into the invisible relay thread and report success. A socket already held by a
+  live companion is never stolen: an in-use path is probed before any leftover from a killed process is swept.
+
+### Notes
+
+- `codex_app.send_message_to_thread` and the Codex Desktop native tools pipe are **internals with no public
+  documentation**, on the same footing as the Claude peer protocol in `src/peer-protocol.mjs`. That is why this
+  path is optional, feature-detected and fallback-safe rather than the default. If Codex changes it, the two
+  places to fix are `NATIVE_DISPATCH_METHOD` and `nativeDispatchParams()` in `src/native-relay.mjs`, and
+  `CODEX_NATIVE_RELAY_METHOD` overrides the method name without a release.
+
 ## [1.11.3] - 2026-09-03
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge)](LICENSE)
 [![M8ven Verified](https://m8ven.ai/badge/mcp/buidangminh23-codex-mcp-bridge-1ke8t1?variant=verified)](https://m8ven.ai/mcp/buidangminh23-codex-mcp-bridge-1ke8t1)
 
-A **two-way** bridge between Claude and Codex: Claude pushes prompts into a **live Codex thread**, and Codex messages back into a **running Claude Code session**. Each side sees the other's sessions and follows the conversation inside its own app. Runs on **macOS, Windows and Linux** (the Codex → Claude direction needs unix sockets, so macOS/Linux only).
+A **two-way** bridge between Claude and Codex: Claude pushes prompts into a **live Codex thread**, and Codex messages back into a **running Claude Code session**. Each side sees the other's sessions and follows the conversation inside its own app. Runs on **macOS, Windows and Linux** (the Codex → Claude direction uses unix sockets on macOS/Linux and named pipes on Windows).
 
 This is not `codex exec`, which starts a fresh session every time. The bridge speaks JSON-RPC to the real Codex app-server, so the thread keeps its history, its `cwd`, its model and its rollout file — and a human can watch it run in the Codex desktop app instead of reading the transcript afterwards.
 
@@ -20,16 +20,21 @@ Claude Desktop ──────┤ stdio                                    We
                      └────────────────────────────────────────────────────────────────────┘
 
                      ┌──────────────── claude-bridge (runs inside Codex) ──────────────────┐
-Codex ───────────────┤ stdio                       unix socket /tmp/cc-socks/<pid>.sock    ├──> Claude Code session ──> message shows in Claude Desktop
+Codex ───────────────┤ stdio             unix socket / named pipe for the Claude session       ├──> Claude Code session ──> message shows in Claude Desktop
                      └────────────────────────────────────────────────────────────────────┘
 
 Codex TUI  ──codex --remote ws://127.0.0.1:8791──> same app-server, same live thread
+
+                     ┌── codex-native-relay (launched by Codex Desktop, Windows/macOS) ────┐
+claude-bridge ───────┤ named pipe / unix socket                         native tools       ├──> the thread already open in Codex Desktop
+                     └────────────────────────────────────────────────────────────────────┘
 ```
 
 - 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.
+- The **native relay** (Windows/macOS, optional) is the third line: a thread the human is watching in Codex Desktop belongs to the app, and a second app-server cannot write to it. Instead of taking the thread away, `claude-bridge` hands the message to a companion the app itself launched, and the app delivers it. See [Codex Desktop native relay](#codex-desktop-native-relay).
 
 ## Requirements
 
@@ -222,7 +227,25 @@ launchctl kickstart -k gui/$UID/com.codex-mcp-bridge.app-server
 
 `CLAUDE_BRIDGE_PEER_NAME` sets the name Claude shows for this bridge in its agent list.
 
-### 5. macOS only: keep the app-server alive with launchd
+### 5. Windows/macOS: the Codex Desktop native relay
+
+Optional, and only worth installing if you keep the bound thread **open in Codex Desktop** while Claude messages back. See [Codex Desktop native relay](#codex-desktop-native-relay) for what it does and why.
+
+```bash
+node scripts/install-native-relay.mjs
+```
+
+This registers the companion with Codex (`codex mcp add codex-native-relay -- <node> src/native-relay-companion.mjs`) and bootstraps the executor thread the native dispatch needs, writing its id to `~/.codex/native-relay.json`. The bootstrap starts a throwaway app-server, creates one thread, and stops the app-server again so nothing is left holding a lock.
+
+```bash
+codex mcp get codex-native-relay
+node scripts/install-native-relay.mjs --no-bootstrap   # register only; supply CODEX_RELAY_ID yourself
+node scripts/install-native-relay.mjs --remove         # unregister, and remove the relay config and thread id
+```
+
+Restart Codex Desktop so it launches the companion, then call its `native_relay_status` tool — or `claude_bridge_status`, whose `delivery:` line names the backend in force. Until both the companion and the executor thread are in place, `claude-bridge` keeps using the app-server path exactly as before.
+
+### 6. macOS only: keep the app-server alive with launchd
 
 > ⚠️ **Do not enable the LaunchAgent while using the Codex desktop app.** The app runs its **own** stdio app-server against the **same** `~/.codex` sqlite state. Two app-servers contend even while idle — measured here: the launchd one burned ~11% CPU doing nothing and **the Codex app UI stuttered**. Keep exactly one alive; `codex_bridge_status` detects and warns about this.
 >
@@ -240,20 +263,21 @@ tail -f ~/Library/Logs/codex-mcp-bridge/app-server.err.log            # logs
 node scripts/install-launch-agent.mjs --uninstall                     # remove
 ```
 
-### 6. Verify the install
+### 7. Verify the install
 
 ```bash
 npm run check          # boots the bridge, autostarts an app-server, lists threads
 npm run check:claude   # lists the live Claude Code sessions Codex can reach
 ```
 
-From inside Claude, call the `codex_bridge_status` tool; from inside Codex, call `claude_bridge_status`. Both print the resolved binary, the endpoint and whether anything is listening.
+From inside Claude, call the `codex_bridge_status` tool; from inside Codex, call `claude_bridge_status`. Both print the resolved binary, the endpoint and whether anything is listening. `claude_bridge_status` also prints a `delivery:` line naming the backend that would carry a relayed message, and the reason when it is not the native one.
 
-### 7. Uninstall everything
+### 8. Uninstall everything
 
 ```bash
 claude mcp remove codex-bridge --scope user
 node scripts/install-codex-mcp.mjs --remove
+node scripts/install-native-relay.mjs --remove
 node scripts/install-launch-agent.mjs --uninstall
 ```
 
@@ -334,6 +358,14 @@ There is no token in the frame — **the socket is mode `0600`, so owning the us
 
 The relay has two hard limits in `src/claude-bridge.mjs`: at most **one message every 5s** and **50 per bridge run**. Two agents left talking to each other unattended still come to a stop.
 
+## Tools — `codex-native-relay` (launched by Codex Desktop, macOS)
+
+| Tool | What it does | Hints |
+|---|---|---|
+| `native_relay_status` | Reports the local socket the companion listens on, the executor thread it dispatches through, and the dispatch method in force. | read-only |
+
+The companion carries no work of its own. Its job is the socket and the dispatch; everything a human asks for still goes through the two bridges above.
+
 ## macOS notes
 
 ### Watch a thread in the Codex desktop app
@@ -347,10 +379,58 @@ send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }
 
 This is how a human watches Codex work in real time instead of reading the rollout at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` after the fact.
 
+### Codex Desktop native relay
+
+`bind_codex_thread` relays every message Claude sends into a Codex thread. That works — until the thread is one **you are watching in Codex Desktop**, which is the case it was built for. Codex takes a per-thread writer lock when the app loads a thread and holds it for as long as the thread is open, so the app-server path, which has to `thread/resume` before it can send, is refused:
+
+```
+thread <id> already has an active writer
+```
+
+Closing the thread first is not a fix. It is the opposite of the point: Codex Desktop is meant to stay the permanent owner of the thread and the surface the human is looking at.
+
+The native relay removes the second writer rather than fighting it. A companion MCP process, **launched by Codex Desktop's own app-server**, already sits inside the app's context, so it can ask that app-server to deliver the message. Nothing attaches, nothing resumes, no second app-server starts, and the lock never changes hands:
+
+```
+Claude
+  → claude-bridge
+  → Windows named pipe / macOS ~/.codex/native-relay.sock (unix socket, mode 0600)
+  → codex-native-relay                  (launched by Codex Desktop's app-server)
+  → codex_app.send_message_to_thread    (over that same connection)
+  → the thread already open in Codex Desktop
+```
+
+**The executor thread.** `codex_app.send_message_to_thread` runs against an executor thread, and that thread is not the destination — it is validated, so a synthetic UUID is rejected with `NATIVE_DISPATCH_FAILED`. A dedicated relay thread keeps that requirement away from the thread you are watching. It is created once by `scripts/install-native-relay.mjs` and recorded in `~/.codex/native-relay.json`:
+
+```json
+{ "relayThreadId": "<uuid>" }
+```
+
+Resolution order is `CODEX_RELAY_ID` → that file → an error naming both. Never a guess: an invented executor fails inside Codex with a message that says nothing about the configuration that actually caused it. The recorded thread works as an executor even if it has never been opened in the app.
+
+**It is a backend, not a replacement.** `claude-bridge` picks between two delivery backends and reports which one it used; the tools, the peer protocol, the routing, the rate limits and `CodexAppServerClient` are untouched. The native path is used only when all of these hold — otherwise the app-server path runs exactly as it did before:
+
+| Condition | Otherwise |
+|---|---|
+| Windows or macOS, companion endpoint exists | the app-server path (`CODEX_BRIDGE_NATIVE_RELAY=1` forces the attempt anyway) |
+| `CODEX_BRIDGE_NATIVE_RELAY` is not `0` | switched off by hand |
+| the Windows named pipe or macOS unix socket exists | the companion is not installed, or Codex Desktop is not running |
+
+A companion that cannot be reached falls back to the app-server path, because an absent relay says nothing about the target thread. A companion that **answered with a refusal** does not: Codex has already been asked, and a second app-server would only contend for the `~/.codex` state and then fail on the very writer lock this backend exists to avoid.
+
+> ⚠️ `codex_app.send_message_to_thread` and the native tools pipe are **Codex Desktop internals with no public documentation**, on the same footing as the Claude peer protocol above. That is why the relay is Windows/macOS, feature-detected, optional and fallback-safe. If Codex changes it, the two places to fix are `NATIVE_DISPATCH_METHOD` and `nativeDispatchParams()` in `src/native-relay.mjs`; `CODEX_NATIVE_RELAY_METHOD` overrides the method name without a release. The request the companion sends is:
+>
+> ```json
+> {"jsonrpc":"2.0","id":1,"method":"codex_app.send_message_to_thread",
+>  "params":{"executorThreadId":"<relay thread>","threadId":"<destination>","message":"..."}}
+> ```
+
+**Security.** On macOS/Linux the relay socket is mode `0600` inside `~/.codex`; Windows uses the Claude-compatible local named-pipe namespace. Anything able to open the relay can put text into a Codex thread, so the endpoint is feature-detected and the companion accepts exactly one shape, `{ targetThreadId, message }`, caps a frame at 128 KiB, and refuses a destination that is its own executor thread — otherwise a mistaken bind would deliver into the invisible relay thread and report success.
+
 ### Caveats
 
-- 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.
+- 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. The [native relay](#codex-desktop-native-relay) is not an exception to this: the companion never attaches to that app-server, it is *launched by* it as one of the app's own MCP servers.
+- **A thread currently open in the desktop app cannot be written to** through a second app-server — 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. For the Claude → Codex relay specifically, the [native relay](#codex-desktop-native-relay) removes the second writer instead of waiting for the lock.
 - **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://`.
@@ -374,7 +454,9 @@ 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. `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.
+**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. If what you want is for Codex Desktop to **keep** the thread while Claude messages into it, that is what the [native relay](#codex-desktop-native-relay) is for — it never asks for the lock.
+
+**`claude_bridge_status` says the delivery backend is `app-server` on Windows or macOS with the relay installed.** The `delivery:` line carries the reason: *"no companion socket at …"* means Codex Desktop has not launched the companion, so restart the app after `install-native-relay.mjs` and check `codex mcp get codex-native-relay`; *"disabled by CODEX_BRIDGE_NATIVE_RELAY=0"* means it was switched off in the MCP server's `env`; *"unavailable on Linux"* means the native relay is not supported there. A relay that is reachable but has no executor thread fails at send time instead, with `RELAY_THREAD_UNCONFIGURED` naming both `CODEX_RELAY_ID` and the file to bootstrap.
 
 **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.
 
@@ -411,6 +493,12 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `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. |
+| `CODEX_BRIDGE_NATIVE_RELAY` | `auto` | Delivery backend for relayed Claude messages. `auto` uses the Codex Desktop native relay on Windows/macOS when its companion endpoint exists; `0` never does; `1` attempts it on any platform. |
+| `CODEX_RELAY_ID` | from `~/.codex/native-relay.json` | Executor thread for `codex_app.send_message_to_thread`. Not the destination — see [Codex Desktop native relay](#codex-desktop-native-relay). |
+| `CODEX_HOME` | `~/.codex` | Where `native-relay.json` lives; POSIX relay sockets also live here, while Windows uses a named pipe. |
+| `CODEX_NATIVE_RELAY_SOCKET` | Windows named pipe or `$CODEX_HOME/native-relay.sock` on macOS | Override the companion endpoint on both halves of the relay. |
+| `CODEX_NATIVE_RELAY_METHOD` | `codex_app.send_message_to_thread` | The undocumented Codex Desktop method the companion dispatches through; override it if Codex renames it. |
+| `CODEX_NATIVE_RELAY_NAME` | `codex-native-relay` | The MCP server name `scripts/install-native-relay.mjs` registers with Codex. |
 | `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`. |
@@ -448,15 +536,16 @@ Runs the whole suite with `node --test`. It needs no Codex install, no login and
 
 | File | Covers |
 |---|---|
-| `test/tool-contract.test.mjs` | both servers boot over stdio and every tool declares a title, a description, per-parameter descriptions and complete annotation hints |
+| `test/tool-contract.test.mjs` | all three servers boot over stdio and every tool declares a title, a description, per-parameter descriptions and complete annotation hints |
 | `test/server-requests.test.mjs` | all 10 app-server requests get a reply in the shape their schema declares — the regression test for "the turn pauses itself" |
 | `test/reconnect.test.mjs` | reconnect after a dropped socket, no leaked pending requests or listeners, an interrupted turn ending promptly, a refused first handshake being retried |
 | `test/turn.test.mjs` | the turn state machine: buffered notifications, terminal statuses, timeout, disconnect, retryable vs fatal errors, and that a failed `turn/start` cannot kill the process |
 | `test/peer-protocol.test.mjs` | frame round-trips, the session registry, transcript scanning, and a live peer endpoint over a real unix socket |
 | `test/platform.test.mjs` | binary resolution, the PATH handed to child processes, per-OS config paths and cwd remapping |
+| `test/native-relay.test.mjs` | the Codex Desktop relay: executor thread resolution, feature detection, Windows named-pipe and POSIX socket round trips, backend selection and fallback, and the companion answering a real MCP client that plays Codex Desktop |
 | `test/repo-hygiene.test.mjs` | no environment file or build output is ever tracked, versions do not drift, documentation stays in English |
 
-GitHub Actions runs the same command on every push and pull request, across Node 22 and 24 on Linux, macOS and Windows (`.github/workflows/ci.yml`). The Codex → Claude direction needs unix sockets, so those tests skip on Windows; the rest of the suite runs there like anywhere else.
+GitHub Actions runs the same command on every push and pull request, across Node 22 and 24 on Linux, macOS and Windows (`.github/workflows/ci.yml`). The Codex → Claude direction uses unix sockets on macOS/Linux and named pipes on Windows; the native relay has matching platform-specific coverage.
 
 Two checks need a real Codex and are not part of `npm test`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.11.3",
+  "version": "1.12.1",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -25,7 +25,9 @@
     "codex-mcp-bridge": "src/index.mjs",
     "claude-mcp-bridge": "src/claude-bridge.mjs",
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
-    "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs"
+    "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",
+    "codex-native-relay": "src/native-relay-companion.mjs",
+    "codex-native-relay-install": "scripts/install-native-relay.mjs"
   },
   "files": [
     "src",
@@ -48,9 +50,11 @@
     "install:desktop": "node scripts/install-claude-desktop.mjs",
     "install:codex": "node scripts/install-codex-mcp.mjs",
     "uninstall:codex": "node scripts/install-codex-mcp.mjs --remove",
+    "install:relay": "node scripts/install-native-relay.mjs",
+    "uninstall:relay": "node scripts/install-native-relay.mjs --remove",
     "install:agent": "node scripts/install-launch-agent.mjs",
     "uninstall:agent": "node scripts/install-launch-agent.mjs --uninstall",
-    "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs"
+    "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs src/native-relay-companion.mjs"
   },
   "engines": {
     "node": ">=22"

package/scripts/install-native-relay.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { CodexAppServerClient } from "../src/app-server-client.mjs";
+import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath } from "../src/native-relay.mjs";
+import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+
+/**
+ * Installs the Codex Desktop native relay: registers the companion as an MCP
+ * server so Codex Desktop launches it, and bootstraps the executor thread the
+ * native dispatch needs.
+ *
+ * The bootstrap is the one step that has to take a writer lock, and it takes it
+ * on a thread that belongs to nobody: a dedicated relay thread, created through
+ * an ordinary app-server which is then stopped so the lock is released. After
+ * this runs, no part of the relay ever attaches a thread again.
+ */
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = path.join(root, "src", "native-relay-companion.mjs");
+const serverName = process.env.CODEX_NATIVE_RELAY_NAME ?? "codex-native-relay";
+const remove = process.argv.includes("--remove");
+const skipBootstrap = process.argv.includes("--no-bootstrap");
+
+const codexBin = resolveCodexBin(process.env.CODEX_EXE);
+const run = (args) => execFileSync(codexBin, args, { env: spawnEnv(), stdio: "pipe" }).toString().trim();
+
+if (!fs.existsSync(entry)) throw new Error(`companion entry point missing: ${entry}`);
+if (!path.isAbsolute(codexBin) || !fs.existsSync(codexBin)) {
+  throw new Error(`codex binary not found (resolved to "${codexBin}"). Set CODEX_EXE to its absolute path.`);
+}
+
+if (remove) {
+  try {
+    console.log(run(["mcp", "remove", serverName]) || `removed ${serverName}`);
+  } catch (err) {
+    console.log(`${serverName} was not registered (${err.message.trim().split("\n").at(-1)})`);
+  }
+  for (const leftover of [relayConfigPath(), ...(IS_WINDOWS ? [] : [relaySocketPath()])]) {
+    if (fs.existsSync(leftover)) {
+      fs.rmSync(leftover, { force: true });
+      console.log(`removed ${leftover}`);
+    }
+  }
+  process.exit(0);
+}
+
+/**
+ * Not a hard failure on an unsupported platform: the companion is harmless and
+ * refusing to register it would make the install order depend on which machine
+ * runs it.
+ */
+if (!IS_MACOS && !IS_WINDOWS) {
+  console.log(`note: the native relay is unavailable on ${PLATFORM_LABEL}.`);
+  console.log("claude-bridge will keep using the app-server path here.");
+}
+
+try {
+  run(["mcp", "remove", serverName]);
+} catch {
+  // not registered yet
+}
+run(["mcp", "add", serverName, "--", process.execPath, entry]);
+
+console.log(`platform: ${PLATFORM_LABEL}`);
+console.log(`registered MCP server "${serverName}" with Codex:`);
+console.log(run(["mcp", "get", serverName]));
+
+const existing = readRelayConfig()?.relayThreadId;
+if (existing) {
+  console.log(`\nrelay thread already bootstrapped: ${existing} (${relayConfigPath()})`);
+} else if (skipBootstrap) {
+  console.log(`\nskipped the relay thread bootstrap; set CODEX_RELAY_ID or rerun without --no-bootstrap.`);
+} else {
+  const client = new CodexAppServerClient({
+    clientInfo: { name: "native-relay-install", title: "Native Relay Install", version: "1.12.1" },
+    log: (msg) => console.log(`  ${msg}`),
+  });
+  console.log("\nbootstrapping the relay executor thread...");
+  try {
+    const { threadId, configPath } = await bootstrapRelayThread(client, { cwd: homeDir() });
+    console.log(`relay thread: ${threadId}`);
+    console.log(`written to:   ${configPath}`);
+  } finally {
+    /**
+     * The bootstrap thread must not stay locked by this app-server: leaving it
+     * held would reintroduce, for the relay's own thread, exactly the writer
+     * conflict the relay exists to remove.
+     */
+    const stopped = await client.stopServer();
+    console.log(stopped.stopped ? "released the bootstrap app-server" : `app-server not stopped: ${stopped.reason}`);
+  }
+}
+
+console.log(`\nrelay socket: ${relaySocketPath()}`);
+console.log("Restart Codex Desktop so it launches the companion, then check with native_relay_status.");
+console.log("remove: node scripts/install-native-relay.mjs --remove");

package/scripts/sync-version.mjs

@@ -15,7 +15,11 @@ import { fileURLToPath } from "node:url";
  * claude-bridge sat at 1.3.0 while the package shipped 1.10.0.
  */
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const entries = [path.join("src", "index.mjs"), path.join("src", "claude-bridge.mjs")];
+const entries = [
+  path.join("src", "index.mjs"),
+  path.join("src", "claude-bridge.mjs"),
+  path.join("src", "native-relay-companion.mjs"),
+];
 const { version } = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
 
 for (const entry of entries) {

package/src/claude-bridge.mjs

@@ -6,9 +6,9 @@ import { z } from "zod";
 import { CodexAppServerClient } from "./app-server-client.mjs";
 import { PLATFORM_LABEL } from "./platform.mjs";
 import { PeerEndpoint, findClaudeSession, listClaudeSessions, readTranscript } from "./peer-protocol.mjs";
-import { runTurn } from "./turn.mjs";
+import { createThreadDelivery } from "./thread-delivery.mjs";
 
-const VERSION = "1.11.3";
+const VERSION = "1.12.1";
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;
 
@@ -27,6 +27,14 @@ const codex = new CodexAppServerClient({
   log,
 });
 
+/**
+ * Delivery is a backend choice, not a call: a thread the human is watching in
+ * Codex Desktop is written through the desktop's own app-server, and every
+ * other thread through the shared one. `claude-bridge` never picks between
+ * them - see `thread-delivery.mjs`.
+ */
+const delivery = createThreadDelivery({ codex, log });
+
 const forwarding = {
   threadId: process.env.CODEX_THREAD_ID ?? null,
   lastAt: 0,
@@ -64,18 +72,11 @@ async function forwardToCodexThread(record) {
   forwarding.lastAt = now;
   forwarding.count += 1;
   try {
-    await codex.ensureThreadAttached(forwarding.threadId);
-    await runTurn(codex, {
-      threadId: forwarding.threadId,
-      input: [
-        {
-          type: "text",
-          text: `[message from Claude session ${record.fromSocket ?? "?"}]\n\n${record.text}`,
-        },
-      ],
-      timeoutMs: 240000,
-    });
-    log(`forwarded a Claude message into thread ${forwarding.threadId}`);
+    const { backend } = await delivery.deliver(
+      forwarding.threadId,
+      `[message from Claude session ${record.fromSocket ?? "?"}]\n\n${record.text}`,
+    );
+    log(`forwarded a Claude message into thread ${forwarding.threadId} via ${backend}`);
   } catch (err) {
     log(`forward failed: ${err.message}`);
   }
@@ -245,7 +246,8 @@ server.registerTool(
     title: "Relay Claude messages into a Codex thread",
     description:
       "Bind a Codex thread so every message Claude pushes to this bridge is relayed into that thread, where it " +
-      "shows up in the Codex desktop app. Pass an empty threadId to stop relaying.",
+      "shows up in the Codex desktop app. On macOS a thread already open in Codex Desktop is written through " +
+      "the desktop's own app-server, so it keeps its writer lock and stays open. Pass an empty threadId to stop.",
     inputSchema: {
       threadId: z.string().describe("Codex thread id, or an empty string to unbind"),
     },
@@ -264,7 +266,7 @@ server.registerTool(
     peer.rename(name);
     return textResult(
       trimmed
-        ? `Relaying Claude messages into Codex thread ${trimmed} (max ${FORWARD_MAX_PER_SESSION} per bridge run, at most one every ${FORWARD_MIN_INTERVAL_MS / 1000}s).\nClaude now sees this bridge as "${name}".`
+        ? `Relaying Claude messages into Codex thread ${trimmed} (max ${FORWARD_MAX_PER_SESSION} per bridge run, at most one every ${FORWARD_MIN_INTERVAL_MS / 1000}s).\ndelivery: ${delivery.describe()}\nClaude now sees this bridge as "${name}".`
         : `Relay disabled. Messages stay in the inbox. Claude sees this bridge as "${name}".`,
     );
   },
@@ -296,6 +298,7 @@ server.registerTool(
         `peer socket:   ${peer.socketPath}`,
         `live sessions: ${sessions.length}`,
         `relay thread:  ${forwarding.threadId ?? "(none - use bind_codex_thread)"}`,
+        `delivery:      ${delivery.describe()}`,
         `inbox:         ${peer.inbox.length} pending message(s)`,
       ];
       return textResult(lines.join("\n"));

package/src/index.mjs

@@ -21,7 +21,7 @@ import {
 import { runTurn } from "./turn.mjs";
 import { BridgeSecurityPolicy } from "./security-policy.mjs";
 
-const VERSION = "1.11.3";
+const VERSION = "1.12.1";
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
 /**
@@ -38,6 +38,7 @@ 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 RELEASE_TURN_STATUSES = new Set([...TERMINAL_TURN_STATUSES, "disconnected"]);
 const security = new BridgeSecurityPolicy();
 
 const client = new CodexAppServerClient({
@@ -133,8 +134,9 @@ async function finishDesktopHandoff({ threadId, result, openInApp, releaseAfterT
   const notes = [];
   let canOpenAfterRelease = true;
   const terminal = TERMINAL_TURN_STATUSES.has(result.status);
+  const releasable = RELEASE_TURN_STATUSES.has(result.status);
 
-  if (releaseAfterTurn && terminal) {
+  if (releaseAfterTurn && releasable) {
     try {
       const released = await client.stopServer();
       if (released.stopped) {