@minhspark/codex-mcp-bridge 1.12.1 → 1.12.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [1.12.2] - 2026-09-05
+
+### Fixed
+
+- **Use the native protocol measured by Seb in [#23](https://github.com/buidangminh23/codex-mcp-bridge/issues/23#issuecomment-5547163688).** The companion uses the native pipe inherited from Codex Desktop, separately from MCP stdio. Dispatch is `tools/call` with distinct executor and destination thread IDs, fresh call/turn IDs, and a UInt32LE length prefix. A response must explicitly report `success: true`. The companion recovers when a configured native pipe appears after startup.
+- **Do not kill other delegations when one finishes.** Automatic handoff unsubscribes only the completed thread. It confirms unload before opening Desktop, reports pending idle unload honestly, and fails safely on servers without `thread/unsubscribe`. Explicit shared-server shutdown remains a separate destructive tool.
+- **Keep RPC and turn state consistent across failures.** Failed sends settle their pending promise, concurrent calls wait for initialization, and disconnects clean up listeners and requests. Same-thread transactions are serialized while other threads remain independent; timed-out or disconnected turns require state reconciliation before another turn starts.
+- **Prevent duplicate or misattributed messages.** A native request with an unconfirmed outcome is never retried through another backend, and invalid messages cannot bypass validation through fallback. Claude requests are queued per destination; unresolved earlier replies block new waited sends instead of assigning a late reply to the wrong request. Fire-and-forget and late responses remain accessible through the inbox.
+- **Preserve Unicode across fragmented pipe traffic.** Both relay protocols and Claude peer messages retain complete UTF-8 characters when stream chunks split a character.
+- **Validate the workspace actually used.** Relative input becomes absolute, regular files are refused as directories, and a created thread must report the requested workspace within allowed roots. A path map cannot disguise an unexpected server-created cwd.
+- **List loaded threads correctly.** The bridge reads the IDs returned by `thread/loaded/list`, applies workspace/title filters, and follows pagination to find matching threads.
+- **Keep diagnostics and installer settings truthful.** The Desktop installer honors both enabling and revoking `CODEX_BRIDGE_AUTO_APPROVE_ACK`. Check commands fail on MCP tool errors, and the live continuity smoke test requires two completed turns to preserve a unique codeword.
+
+### Tests
+
+- Added regressions for connection and turn lifecycle, authorization, concurrent handoffs, late replies, fragmented/malformed native frames, missing/late native pipes, fallback boundaries, configuration preservation, and diagnostic exit status. Native wire tests run a real MCP child against isolated mock pipes without sending messages to user sessions.
+
 ## [1.12.1] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -33,7 +33,7 @@ claude-bridge ───────┤ named pipe / unix socket
 - The app-server is a **singleton per port**. The bridge probes `http://127.0.0.1:8791/readyz`; if nothing answers it spawns a detached `codex app-server --listen ws://127.0.0.1:8791`, which keeps running after the bridge exits.
 - 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.
+- `delegate_to_codex` starts the thread at the supplied `cwd`, names it, sends the prompt, and unsubscribes that thread after a terminal turn. It opens `codex://threads/<id>` only after unload is confirmed; other threads on the shared app-server keep running.
 - 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
@@ -235,7 +235,7 @@ Optional, and only worth installing if you keep the bound thread **open in Codex
 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.
+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 creates one thread, unsubscribes it, and closes its connection. It leaves other clients and threads running; an idle server may retain the executor until its configured unload delay expires.
 
 ```bash
 codex mcp get codex-native-relay
@@ -308,6 +308,10 @@ On macOS and Linux the `codex` launcher is a Node script with a `#!/usr/bin/env
 
 `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`.
 
+`releaseAfterTurn` uses `thread/unsubscribe`, never an automatic process stop. The server may keep a thread loaded during its idle grace period or while another client subscribes. The bridge reports that state and defers Desktop opening rather than claiming the writer lock is released. Older servers without `thread/unsubscribe` return an explicit release failure. `stop_codex_app_server` remains a separate, destructive operation that affects every client on that endpoint.
+
+Concurrent sends to the same Codex thread are serialized; different threads can run in parallel. After a timeout or disconnect, the bridge checks unresolved turn state before allowing another turn. `loadedOnly` resolves the server's thread IDs and searches subsequent pages before applying workspace and title filters.
+
 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 checked before the bridge attaches, and `CODEX_BRIDGE_THREAD_POLICY` decides what counts as permission:
@@ -334,6 +338,8 @@ Under `owned`, a thread a human opened is **unreachable rather than merely restr
 
 Every tool declares MCP annotation hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), because a client decides whether a call needs a human in the loop from those hints and a missing one reads as "unknown". Two are worth naming: `read_claude_inbox` empties the inbox as it reads it, so it is **not** read-only despite the name, and `claude_bridge_status` registers the peer endpoint on first call, so it writes too.
 
+Waited sends to the same Claude session run in order. If an earlier send timed out or used `waitSec: 0` and its reply has not arrived, a new waited send returns `PEER_REPLY_PENDING` before delivering another message. Wait for the earlier reply and inspect `read_claude_inbox`, or use `waitSec: 0` if another asynchronous message is intended. Different destination sessions remain independent.
+
 ### How each side sees the other
 
 - **Claude sees Codex:** `claude-bridge` registers itself as a *peer session* under `~/.claude/sessions/`. Claude lists it with `ListAgents` and messages it with `SendMessage` — not hidden, not an invisible background process. The default name is `codex-<pid>`; after `bind_codex_thread` it renames itself to `codex-<first 8 chars of threadId>`, which is what makes several bridges distinguishable (Codex starts **one bridge per session**, so a few peers usually advertise at once).
@@ -416,15 +422,21 @@ Resolution order is `CODEX_RELAY_ID` → that file → an error naming both. Nev
 | `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.
+A companion that cannot be reached before sending falls back to the app-server path. Once a request has been written, a refusal, timeout, or lost acknowledgement does not trigger another delivery: the first attempt may already have succeeded. Invalid or oversized messages are also refused rather than passed to another backend.
+
+Codex Desktop supplies `CODEX_APP_TOOLS_PIPE_PATH` to its companion. The companion keeps that native connection separate from MCP stdio. Without the inherited native pipe it does not advertise a working relay endpoint; if a configured pipe is late during startup, it retries in the background.
 
 > ⚠️ `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":"..."}}
+> {"jsonrpc":"2.0","id":1,"method":"tools/call",
+>  "params":{"arguments":{"threadId":"<destination>","prompt":"..."},
+>    "callId":"<unique call id>","namespace":"codex_app","threadId":"<relay thread>",
+>    "tool":"send_message_to_thread","turnId":"<unique turn id>"}}
 > ```
 
+The native pipe uses a 4-byte UInt32LE payload length followed by UTF-8 JSON-RPC, and delivery requires `response.result.success === true`. `callId` and `turnId` are fresh for each dispatch. The local bridge-to-companion protocol remains NDJSON. Both transports preserve Unicode across arbitrary stream chunk boundaries. This wire format follows [Seb's measured prototype in issue #23](https://github.com/buidangminh23/codex-mcp-bridge/issues/23#issuecomment-5547163688).
+
 **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
@@ -437,6 +449,8 @@ A companion that cannot be reached falls back to the app-server path, because an
 
 ## Troubleshooting
 
+**A turn fails with "model requires a newer version of Codex" after upgrading Desktop.** An app-server already listening at `CODEX_APP_SERVER_URL` keeps running its original executable. Resolving a newer `CODEX_EXE` does not replace that process. Check the listening process and its executable version, then restart that server with the current Codex binary when its active work has finished. An isolated server on another local port can verify the upgrade without interrupting shared work.
+
 **`readyz` never returns 200 after restarting the app-server.** The log says `failed to initialize sqlite state runtime under ~/.codex`. Cause: an older app-server is still alive and holding the sqlite state of `~/.codex` — only **one** process may hold it. Hard kills (`pkill -9`) or repeated `launchctl kickstart -k` leave zombies that `pkill -f "app-server --listen ws://…"` misses, because the process name is the vendored binary path.
 
 ```bash
@@ -454,7 +468,7 @@ 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. 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.
+**The Codex app says a thread is "open in another application".** The app-server holds a writer lock while the thread is loaded. With `releaseAfterTurn: true`, the bridge unsubscribes after completion; unload can still wait for the server's idle delay or another subscriber. Open the thread after it unloads. Use `stop_codex_app_server` only when all work on that shared server may be stopped. A thread held by a different Codex window must be released there. To keep a thread open in Codex Desktop while Claude messages into it, use the [native relay](#codex-desktop-native-relay), which never takes a second writer 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.
 
@@ -492,12 +506,12 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `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. |
+| `CODEX_BRIDGE_RELEASE_AFTER_TURN` | `1` on Windows, `0` elsewhere | Unsubscribe the completed thread without stopping other work; defer Desktop opening until unload is confirmed. |
 | `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_METHOD` | `tools/call` | The undocumented Codex Desktop JSON-RPC method the companion dispatches through; override only for a verified protocol change. |
 | `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. |
@@ -539,6 +553,8 @@ Runs the whole suite with `node --test`. It needs no Codex install, no login and
 | `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/app-server-lifecycle.test.mjs` | concurrent initialization, failed sends, per-thread serialization and unsubscribe, and reconciliation of turns after reconnect |
+| `test/bridge-integration.test.mjs` | real MCP children against isolated app-servers: workspace authorization, loaded-thread pagination, diagnostic exit status, and concurrent handoffs |
 | `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.12.1",
+  "version": "1.12.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",
@@ -54,7 +54,7 @@
     "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 src/native-relay-companion.mjs"
+    "version": "node scripts/sync-version.mjs && git add src/index.mjs src/claude-bridge.mjs src/native-relay-companion.mjs scripts/install-native-relay.mjs"
   },
   "engines": {
     "node": ">=22"

package/scripts/check-claude-bridge.mjs

@@ -10,28 +10,32 @@ const transport = new StdioClientTransport({
   stderr: "inherit",
 });
 const client = new Client({ name: "claude-bridge-check", version: "1.0.0" });
-await client.connect(transport);
+try {
+  await client.connect(transport);
 
-const tools = await client.listTools();
-console.log("tools:", tools.tools.map((t) => t.name).join(", "));
+  const tools = await client.listTools();
+  console.log("tools:", tools.tools.map((t) => t.name).join(", "));
 
-const status = await client.callTool({ name: "claude_bridge_status", arguments: {} });
-console.log("\n--- claude_bridge_status ---\n" + status.content[0].text);
+  const status = await client.callTool({ name: "claude_bridge_status", arguments: {} });
+  console.log("\n--- claude_bridge_status ---\n" + status.content[0].text);
+  if (status.isError) throw new Error("Claude bridge status failed");
 
-const listed = await client.callTool({ name: "list_claude_sessions", arguments: {} });
-console.log("\n--- list_claude_sessions ---\n" + listed.content[0].text);
+  const listed = await client.callTool({ name: "list_claude_sessions", arguments: {} });
+  console.log("\n--- list_claude_sessions ---\n" + listed.content[0].text);
+  if (listed.isError) throw new Error("Claude session listing failed");
 
-const target = process.env.CLAUDE_TARGET;
-if (target) {
-  const message = process.env.CLAUDE_MESSAGE ?? "Ping from the Codex side of the bridge.";
-  const waitSec = Number(process.env.CLAUDE_WAIT ?? 180);
-  console.log(`\nsending to "${target}" (waiting ${waitSec}s)...`);
-  const sent = await client.callTool({
-    name: "send_to_claude_session",
-    arguments: { target, message, waitSec },
-  });
-  console.log("\n--- send_to_claude_session ---\n" + sent.content[0].text);
+  const target = process.env.CLAUDE_TARGET;
+  if (target) {
+    const message = process.env.CLAUDE_MESSAGE ?? "Ping from the Codex side of the bridge.";
+    const waitSec = Number(process.env.CLAUDE_WAIT ?? 180);
+    console.log(`\nsending to "${target}" (waiting ${waitSec}s)...`);
+    const sent = await client.callTool({
+      name: "send_to_claude_session",
+      arguments: { target, message, waitSec },
+    });
+    console.log("\n--- send_to_claude_session ---\n" + sent.content[0].text);
+    if (sent.isError) throw new Error("Claude message delivery failed");
+  }
+} finally {
+  await client.close();
 }
-
-await client.close();
-process.exit(0);

package/scripts/check.mjs

@@ -34,10 +34,16 @@ const transport = new StdioClientTransport({
 });
 const client = new Client({ name: "bridge-check", version: "1.0.0" });
 
-await client.connect(transport);
-const tools = await client.listTools();
-console.log("tools:", tools.tools.map((t) => t.name).join(", "));
-const listed = await client.callTool({ name: "list_codex_threads", arguments: { limit: 3 } });
-console.log(listed.content[0].text.slice(0, 600));
-await client.close();
-process.exit(0);
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  console.log("tools:", tools.tools.map((t) => t.name).join(", "));
+  const listed = await client.callTool({ name: "list_codex_threads", arguments: { limit: 3 } });
+  console.log(listed.content[0].text.slice(0, 600));
+  if (listed.isError) process.exitCode = 1;
+} catch (err) {
+  console.error(err.message);
+  process.exitCode = 1;
+} finally {
+  await client.close();
+}

package/scripts/install-claude-desktop.mjs

@@ -72,6 +72,7 @@ cfg.mcpServers["codex-bridge"] = {
     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_AUTO_APPROVE_ACK: settled("CODEX_BRIDGE_AUTO_APPROVE_ACK", "0"),
     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

package/scripts/install-native-relay.mjs

@@ -8,17 +8,7 @@ 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 VERSION = "1.12.2";
 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";
@@ -76,22 +66,17 @@ if (existing) {
   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" },
+    clientInfo: { name: "native-relay-install", title: "Native Relay Install", version: VERSION },
     log: (msg) => console.log(`  ${msg}`),
   });
   console.log("\nbootstrapping the relay executor thread...");
   try {
-    const { threadId, configPath } = await bootstrapRelayThread(client, { cwd: homeDir() });
+    const { threadId, configPath, release } = await bootstrapRelayThread(client, { cwd: homeDir() });
     console.log(`relay thread: ${threadId}`);
     console.log(`written to:   ${configPath}`);
+    console.log(release.released ? "released the bootstrap thread" : `bootstrap thread release pending: ${release.reason ?? release.status}`);
   } 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}`);
+    await client.close();
   }
 }
 

package/scripts/smoke.mjs

@@ -1,11 +1,12 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const cwdForTest = process.env.SMOKE_CWD ?? root;
-
+const codeword = "BRIDGE-" + randomUUID();
 const transport = new StdioClientTransport({
   command: process.execPath,
   args: [path.join(root, "src", "index.mjs")],
@@ -13,38 +14,40 @@ const transport = new StdioClientTransport({
   stderr: "inherit",
 });
 const client = new Client({ name: "smoke", version: "1.0.0" });
-await client.connect(transport);
-
-const tools = await client.listTools();
-console.log("TOOLS:", tools.tools.map((t) => t.name).join(", "));
-
-const listed = await client.callTool({ name: "list_codex_threads", arguments: { limit: 3 } });
-console.log("\n--- list_codex_threads ---\n" + listed.content[0].text.slice(0, 900));
-
-const created = await client.callTool({
-  name: "start_codex_thread",
-  arguments: { cwd: cwdForTest },
-});
-console.log("\n--- start_codex_thread ---\n" + created.content[0].text);
-const threadId = created.content[0].text.match(/threadId: ([0-9a-f-]+)/)?.[1];
-if (!threadId) throw new Error("could not parse threadId");
-
-const first = await client.callTool({
-  name: "send_to_codex_thread",
-  arguments: { threadId, prompt: "Remember the codeword PAPAYA. Reply with only: SAVED", timeoutSec: 180 },
-});
-console.log("\n--- send #1 ---\n" + first.content[0].text);
-
-const second = await client.callTool({
-  name: "send_to_codex_thread",
-  arguments: { threadId, prompt: "What codeword did I give you? Reply with only that word.", timeoutSec: 180 },
-});
-console.log("\n--- send #2 (same thread, must recall) ---\n" + second.content[0].text);
-
-const read = await client.callTool({ name: "read_codex_thread", arguments: { threadId, limit: 6 } });
-console.log("\n--- read_codex_thread ---\n" + read.content[0].text.slice(0, 900));
 
-const ok = /PAPAYA/i.test(second.content[0].text);
-console.log("\nRESULT:", ok ? "PASS - thread continuity works" : "FAIL - Codex did not recall the codeword");
-await client.close();
-process.exit(ok ? 0 : 1);
+async function call(name, args) {
+  const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 240000 });
+  const text = result.content.map(item => item.text ?? "").join("\n");
+  if (result.isError) throw new Error(text);
+  return text;
+}
+
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  console.log("TOOLS:", tools.tools.map(tool => tool.name).join(", "));
+  const created = await call("start_codex_thread", { cwd: cwdForTest, name: "Bridge continuity smoke test" });
+  console.log(created);
+  const threadId = created.match(/threadId: ([0-9a-f-]+)/)?.[1];
+  if (!threadId) throw new Error("could not parse threadId");
+  const options = { threadId, timeoutSec: 180, openInApp: false, releaseAfterTurn: false };
+  const first = await call("send_to_codex_thread", {
+    ...options,
+    prompt: "This is a transport smoke test. Do not run tools, commands, or change files. Remember this exact codeword: " + codeword + ". Reply with only: SAVED",
+  });
+  if (!/status: completed/.test(first) || first.split("--- Codex reply ---").at(-1).trim() !== "SAVED") {
+    throw new Error("The first smoke turn did not complete with SAVED: " + first);
+  }
+  const second = await call("send_to_codex_thread", {
+    ...options,
+    prompt: "What exact codeword did I give you? Do not use tools. Reply with only that codeword.",
+  });
+  if (!/status: completed/.test(second) || second.split("--- Codex reply ---").at(-1).trim() !== codeword) {
+    throw new Error("Codex did not recall the per-run codeword: " + second);
+  }
+  const read = await call("read_codex_thread", { threadId, limit: 6 });
+  if (!read.includes(codeword)) throw new Error("The saved thread did not contain the smoke reply");
+  console.log("RESULT: PASS - two completed turns preserved a unique codeword and its transcript");
+} finally {
+  await client.close();
+}

package/scripts/sync-version.mjs

@@ -19,6 +19,7 @@ const entries = [
   path.join("src", "index.mjs"),
   path.join("src", "claude-bridge.mjs"),
   path.join("src", "native-relay-companion.mjs"),
+  path.join("scripts", "install-native-relay.mjs"),
 ];
 const { version } = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));