@minhspark/codex-mcp-bridge 1.13.2 → 1.13.4

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+## [1.13.4] - 2026-09-06
+
+### Fixed
+
+- Latch queued Desktop delivery deadlines when they expire, so a timed-out prompt cannot dispatch later or release the lock owned by an active send.
+- Require and revalidate the exact intended workspace for Claude Desktop sends, expose pending recipient receipts through `read_claude_delivery`, and block no-wait retries of held or uncertain messages. Preserve pending ownership after an uncertain socket write.
+- Detect source and Desktop-policy changes in loaded bridge processes and refuse new sends until reconnect. Diagnostics identify their separate MCP process instead of implying the Desktop connection was refreshed.
+- Preserve the Codex MCP registration environment on upgrade, pin Desktop routing explicitly, disable its external autostart, and refuse to reset custom access or transport settings. Prefer existing Desktop tasks in MCP instructions.
+- Enforce Desktop task mode for Claude destinations as well as Codex delivery. Exclude non-Desktop sessions from discovery, refuse CLI or unknown entrypoints before connecting, and require a unique exact target. Status reports eligible and excluded sessions; receipts identify the actual entrypoint, workspace, and session. Legacy CLI mode remains available when Desktop task mode is disabled.
+- Register the native relay companion under a runtime Codex Desktop trusts instead of whichever Node happens to run the installer. The app authenticates the code-signing identity of any process connecting to its native tools pipe and closes the connection before reading a byte when that identity is not its own, so a companion started by a user-installed Node still created its socket and still reported itself installed while every delivery failed as `NATIVE_DELIVERY_UNCONFIRMED` — the refusal is only visible in the app's own log as `dynamic_app_tools_peer_rejected`. On macOS the installer now resolves the runtime the app ships, honours the variables the app declares for its own bundled plugin, and prints the runtime and its source; `CODEX_NATIVE_RELAY_NODE` overrides it. Windows and Linux keep the runtime running the installer, since neither was measured to enforce the check.
+
+### Upgrade notes
+
+- Reconnect the MCP connections in both Desktop clients after upgrading. Reinstall an existing native relay companion with the updated installer to apply runtime selection. Updating package files alone does not replace running processes or add the stale-runtime guard to an older process.
+- In Desktop task mode, provide the independently verified absolute `expectedCwd` when sending to Claude. A held receipt still requires the recipient's approval; inspect its `msgId` with `read_claude_delivery` instead of resending. Receipt history is in memory and is not restored after a bridge restart.
+
+## [1.13.3] - 2026-09-05
+
+### Fixed
+
+- Verify the current saved project's identity, canonical directory, and task membership before reusing a Desktop creation receipt. Project drift is rejected; omitted recent/pinned metadata reports unverified assignment while preserving the task ID without resending or creating a duplicate.
+- Support `--version` and `-v` on every packaged command without starting servers, opening sockets, or mutating client configuration.
+- Preserve PowerShell's `$?` and conditional `&&`/`||` behavior as well as `$LASTEXITCODE` by invoking its footer through a script alias.
+
+### Added
+
+- Opt-in Bash, Zsh, and PowerShell installation footers for `npm install -g @minhspark/codex-mcp-bridge@latest`: first installation, changed version, unchanged version, failure, dry run, and unverifiable metadata are distinguished after npm's final output while preserving its exit code.
+- `codex-npm-footer-install` backs up and updates shell profiles idempotently, refuses unmanaged npm wrappers, supports removal, and explains how to reload an already-open terminal. Package installation does not change profiles automatically.
+
+### Verification
+
+- Regression coverage includes same-workspace project moves, deleted/repointed/replaced projects, incomplete Desktop snapshots, deadlines and authorization, shell argument boundaries, dry-run configuration, failure exit codes, metadata validation, and profile preservation.
+
 ## [1.13.2] - 2026-09-05
 
 ### Fixed

package/README.md

@@ -28,6 +28,8 @@ Desktop calls share a maximum 40-second budget across creation, opening, queuein
 
 Creation receipts persist in `$CODEX_HOME/bridge-task-receipts` (default `~/.codex/bridge-task-receipts`). The same canonical workspace and explicit title reuse the existing task, including after completion or a bridge restart; an edited brief is not resent. Use `send_to_codex_thread` to continue it, or a distinct title for separate work. Without an explicit title, the key uses the exact prompt hash. Receipts store hashes rather than prompt text and never grant thread permissions: `owned` policy still requires authorization after restart. Pending or uncertain receipts and abandoned creation locks fail closed without automatic expiry; inspect the actual task before repairing them.
 
+Reusing a receipt also verifies that the saved project still has the same identity and exact directory, then checks the task's current project membership in Desktop's recent/pinned listing. A moved task or deleted/repointed project is rejected before sending or creating anything. A task omitted from that listing keeps its known ID and reports `project assignment: unverified`; stored receipt metadata is not presented as current membership. If a checkout has moved, edit the existing project's folder in Desktop, then inspect the existing task's workspace. Do not add another project or append the obsolete directory merely to satisfy a match.
+
 The updated companion exposes a separate `-desktop-tasks` endpoint so a previous companion holding the legacy reply socket need not be killed during an upgrade. `codex_bridge_status` verifies the native connection through Desktop's local project list; `native_relay_status` reports both endpoints. Reconnect the companion after upgrading so it accepts the current native operations.
 
 Desktop mode never contacts, starts, or falls back to an external app-server, including during status checks and thread discovery. The Claude Desktop installer records `CODEX_BRIDGE_AUTOSTART=0` in this mode. If Desktop or its companion is unavailable, the bridge reports the failure and leaves existing tasks in Desktop. `stop_codex_app_server` is a no-op in Desktop mode; stop an obsolete external service through its own launcher after confirming it has no active work.
@@ -122,7 +124,7 @@ Installing straight from the repository works the same way and needs no registry
 npm install -g git+https://github.com/buidangminh23/codex-mcp-bridge.git
 ```
 
-Either route puts four commands on your PATH — `codex-mcp-bridge` and `claude-mcp-bridge` are the two servers, `codex-mcp-bridge-install` and `claude-mcp-bridge-install` do the wiring in the steps below. Wherever this README runs `node scripts/install-claude-desktop.mjs`, an installed copy runs `codex-mcp-bridge-install` instead.
+Either route puts the bridge servers, configuration installers, native relay, and `codex-npm-footer-install` on your PATH. Wherever this README runs `node scripts/install-claude-desktop.mjs`, an installed copy runs `codex-mcp-bridge-install` instead. Every packaged command supports `--version` and `-v` without starting a server or changing configuration.
 
 #### Upgrading an install you already have
 
@@ -130,6 +132,33 @@ Either route puts four commands on your PATH — `codex-mcp-bridge` and `claude-
 
 Re-running `codex-mcp-bridge-install` is **not** required to upgrade, and before 1.11.1 it actively hurt: it replaced the whole entry, discarding `CODEX_BRIDGE_ALLOWED_THREADS`, any hand-added `CODEX_BRIDGE_THREAD_POLICY`, and resetting `CODEX_BRIDGE_ALLOWED_ROOTS` to the install directory. From 1.11.1 it keeps what is already there — an environment variable you pass wins, the existing value is the fallback, and `--reset` gives you the defaults back.
 
+#### Show the final npm installation result
+
+Enable the optional shell integration once after installing the package:
+
+```sh
+codex-npm-footer-install --shell zsh
+```
+
+Use `--shell bash` on Bash or `--shell powershell` in PowerShell 7. A source checkout can run `npm run install:footer -- --shell zsh`. The installer backs up existing profiles, preserves unrelated content, and prints a command to load the integration into the current terminal. New login and interactive Bash/Zsh shells load it automatically; PowerShell uses its current-user all-hosts profile. A terminal started before setup must run the printed reload command or open a new shell. Existing unmanaged `npm` functions are refused for review rather than overwritten. Use `--profile /absolute/path` to select a custom profile or `--remove` to remove the managed loader.
+
+The integration leaves the command unchanged:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest
+```
+
+| Measured result | Final line |
+| --- | --- |
+| No previous installation | `Successfully installed: @minhspark/codex-mcp-bridge v<version>` |
+| Version changed | `Successfully updated: @minhspark/codex-mcp-bridge v<before> -> v<after>` |
+| Same version after reinstalling | `Already up to date: @minhspark/codex-mcp-bridge v<version>` |
+| npm failed | `Failed to install: ... (exit code <code>). See npm error above.` |
+| Dry run | `Dry run completed: ... (no changes applied).` |
+| Mode or installed metadata cannot be verified | A warning instead of a success claim |
+
+The footer runs after npm finishes and keeps npm's output and exit code. It supports `install`/`i`, explicit global installation, one bridge package, dry-run flags, common install booleans, and a single `--prefix`. Other commands, multiple packages, unknown options, and machine-readable or silent output modes pass through without a footer. Installing the package itself does not alter shell profiles. A successful install confirms files on disk; restart the MCP client separately to load the new bridge code.
+
 **Clone it** — right if you intend to read, test or change the code:
 
 ```bash
@@ -229,7 +258,7 @@ claude mcp remove codex-bridge --scope user
 node scripts/install-codex-mcp.mjs
 ```
 
-This runs `codex mcp add claude-bridge -- <node> src/claude-bridge.mjs`, writing to `~/.codex/config.toml`. The equivalent by hand:
+The installer updates the named entry through `codex mcp add`, preserves existing environment settings, pins the configured Desktop policy, and disables external autostart in Desktop mode. It refuses to reset custom access, timeout, or transport settings. It never infers the sender permission class from the recipient. The basic registration by hand is:
 
 ```bash
 codex mcp add claude-bridge --env CLAUDE_BRIDGE_PEER_NAME=codex-desktop -- "$(command -v node)" "$PWD/src/claude-bridge.mjs"
@@ -243,11 +272,7 @@ codex mcp get claude-bridge
 node scripts/install-codex-mcp.mjs --remove
 ```
 
-Restart the Codex app (or open a new Codex session) to load it. If a shared app-server is already running under launchd, reload its config with:
-
-```bash
-launchctl kickstart -k gui/$UID/com.codex-mcp-bridge.app-server
-```
+Reconnect the MCP server in the existing Codex Desktop task, or restart the app and reopen that same task. Verify `claude_bridge_status` **from that task**: `runtime state` must be `current` and `session policy` must match the intended mode. Do not create a replacement task. `npm run check:claude` starts a separate diagnostic process and cannot prove that the app's existing MCP connection reloaded.
 
 `CLAUDE_BRIDGE_PEER_NAME` sets the name Claude shows for this bridge in its agent list.
 
@@ -259,7 +284,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 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.
+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 `<node>` is resolved rather than inherited: Codex Desktop authenticates the code-signing identity of any process that connects to its native tools pipe, so on macOS the installer registers the runtime the app ships and prints the `relay runtime:` line naming it and where it came from. `CODEX_NATIVE_RELAY_NODE` overrides that on any platform; Windows and Linux keep the Node running the installer, as before. 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
@@ -355,6 +380,7 @@ Under `owned`, a thread a human opened is **unreachable rather than merely restr
 |---|---|---|
 | `list_claude_sessions` | Lists Claude Code sessions running on this machine (name, pid, sessionId, cwd, entrypoint). | read-only |
 | `send_to_claude_session` | Sends to a Claude inbox and waits for a correlated reply. Receipt statuses distinguish `reply_received`, `sent_unconfirmed`, `reply_timeout`, and receiver policy outcomes such as `held` or `refused`. `waitSec: 0` sends without waiting for confirmation. Prefer an exact `sessionId` because session names can change. | destructive |
+| `read_claude_delivery` | Inspects the latest recipient receipt or correlated reply by original message ID without resending or clearing the inbox. Receipts belong to this MCP process; an unknown ID after reconnect never proves non-delivery. | read-only |
 | `read_claude_inbox` | Reads **and clears** messages Claude pushed over on its own, including replies that arrived late. | destructive |
 | `read_claude_transcript` | Reads a Claude session's recent conversation without sending anything. | read-only |
 | `bind_codex_thread` | Binds a Codex thread so every message from Claude is relayed into it, **visible in the Codex desktop app**. Pass an empty string to stop. | writes |
@@ -362,7 +388,15 @@ 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.
+Desktop task mode (`CODEX_BRIDGE_DESKTOP_TASKS=1` or the shared setting written by `codex-native-relay-install --desktop-tasks`) applies in both directions. `list_claude_sessions` only offers sessions advertised by Claude Desktop (`entrypoint: claude-desktop`), and sending refuses CLI or unknown entrypoints before connecting. Targets must match a unique exact session ID, PID, or name; partial names are not accepted. Open or reconnect an existing Code session in Claude Desktop at the intended project when none is available. Do not launch a replacement CLI session: CLI and Desktop have separate conversation histories. Legacy mode still supports CLI sessions.
+
+`claude_bridge_status` reports the destination policy, eligible session count, and excluded non-Desktop count. Send receipts include the destination's `entrypoint`, `cwd`, and `sessionId`. A correlated reply confirms receipt in that session; it does not independently prove that its conversation is visible in the Desktop UI. Desktop sends require `expectedCwd`, an absolute independently verified project directory. The bridge resolves both paths and refuses a missing, nonexistent, parent, or different directory before sending; it rechecks the destination after queueing. Reconnect the bridge's MCP connection after upgrading to load the enforcement code.
+
+Sends to the same Claude session run in order. An outstanding message blocks all further sends to that session, including `waitSec: 0`; changing wait time must not bypass a held or uncertain delivery. Use `read_claude_delivery` with the original message ID to observe `held`, `expired`, `refused`, or a late reply. A transport error after writing began also retains pending ownership. Different destination sessions remain independent. A process restart loses in-memory receipts: retain the original ID and inspect the existing recipient conversation before any resend; never treat an unknown ID as permission to retry.
+
+Both bridge status tools report the loaded source fingerprint and process identity. Source or Desktop-routing configuration changes make the running process stale and block new sends until reconnect, while Claude inbox/receipt reads remain available. This guard applies only after the version containing it has loaded; upgrading files cannot retrofit the guard into an older process already running.
+
+Claude's [inbound permission controls](https://code.claude.com/docs/en/cross-session-messaging#control-inbound-messages) remain authoritative. A missing sender permission class can cause a bypassing recipient to hold the message. Do not change `CLAUDE_BRIDGE_PERMISSION_MODE` or recipient settings merely to bypass a hold/refusal. Configure a sender class only when it truthfully represents every session using that MCP entry. If the Desktop UI does not expose the pending approval, report that boundary and keep the original receipt rather than creating a CLI session.
 
 Claude Desktop disables the CLI-native `SendMessage` tool. For Desktop targets, the bridge requests an ordinary answer in the destination conversation and reads only a completed assistant turn descended from the injected message UUID. Unrelated human prompts and sidechains are excluded. Late answers remain available through the inbox while the bridge process is running. This does not change Desktop tool permissions or the receiver's inbound policy.
 
@@ -506,6 +540,8 @@ python3 -c "import json;[print(v['properties']['method'].get('const') or v['prop
 
 **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.
 
+**Desktop delivery fails on macOS while the relay reports itself installed.** The companion still creates its socket and `native_relay_status` still reports the native pipe, because Codex Desktop accepts the connection and only then closes it: it authenticates the connecting process's code-signing identity first, and a companion running under a Node build signed by anyone other than the vendor is refused. Every send then fails hard as `NATIVE_DELIVERY_UNCONFIRMED` rather than falling back, since the companion was reached. The app records the refusal as `dynamic_app_tools_peer_rejected reason=untrusted-code-signing-identity` (`~/Library/Logs/com.openai.codex/<date>/`; a process the app did not spawn is logged as `missing-code-signing-identity` instead). Re-run `scripts/install-native-relay.mjs` and check its `relay runtime:` line — it must not say `process.execPath` when Codex Desktop is installed. Point `CODEX_NATIVE_RELAY_NODE` at the runtime inside the app bundle if discovery misses it, and restart Codex Desktop so it relaunches the companion.
+
 **`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.
@@ -549,6 +585,7 @@ The bridge reads these from the environment its MCP client hands it — there is
 | `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` | `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. |
+| `CODEX_NATIVE_RELAY_NODE` | the runtime Codex Desktop ships on macOS, otherwise `process.execPath` | Node runtime `scripts/install-native-relay.mjs` registers the companion under. Codex Desktop rejects a peer whose code-signing identity is not its own, so the companion has to run under a runtime the app trusts. |
 | `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`. |
@@ -612,7 +649,7 @@ The Codex → Claude direction has its own live check:
 
 ```bash
 npm run check:claude                                    # list the Claude sessions Codex can see
-CLAUDE_TARGET=<sessionId> CLAUDE_WAIT=150 npm run check:claude   # deliver a message and wait for the answer
+CLAUDE_TARGET=<sessionId> CLAUDE_EXPECTED_CWD=/absolute/project CLAUDE_WAIT=150 npm run check:claude   # deliver a message and wait for the answer
 ```
 
 A reply coming back proves both directions work.

package/package.json

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

package/scripts/check-claude-bridge.mjs

@@ -12,6 +12,7 @@ const transport = new StdioClientTransport({
 });
 const client = new Client({ name: "claude-bridge-check", version: "1.0.0" });
 try {
+  console.log("This diagnostic starts a separate MCP process; it does not reload or verify an existing Desktop task's MCP connection.");
   await client.connect(transport);
 
   const tools = await client.listTools();
@@ -32,7 +33,7 @@ try {
     console.log(`\nsending to "${target}" (waiting ${waitSec}s)...`);
     const sent = await client.callTool({
       name: "send_to_claude_session",
-      arguments: { target, message, waitSec },
+      arguments: { target, message, waitSec, expectedCwd: process.env.CLAUDE_EXPECTED_CWD },
     });
     console.log("\n--- send_to_claude_session ---\n" + sent.content[0].text);
     if (sent.isError) throw new Error("Claude message roundtrip failed; receipt or outcome is unconfirmed");

package/scripts/install-claude-desktop.mjs

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

package/scripts/install-codex-mcp.mjs

@@ -5,6 +5,11 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { PLATFORM_LABEL, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { desktopTasksConfigured } from "../src/native-relay.mjs";
+import { codexMcpRegistration } from "../src/codex-mcp-registration.mjs";
+
+exitForVersionRequest(import.meta.url);
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const codexBin = resolveCodexBin(process.env.CODEX_EXE);
@@ -26,22 +31,17 @@ if (remove) {
   process.exit(0);
 }
 
-try {
-  run(["mcp", "remove", serverName]);
-} catch {
-  // not registered yet
-}
-
-const args = ["mcp", "add", serverName];
-const peerName = process.env.CLAUDE_BRIDGE_PEER_NAME;
-if (peerName) args.push("--env", `CLAUDE_BRIDGE_PEER_NAME=${peerName}`);
-if (permissionMode) args.push("--env", `CLAUDE_BRIDGE_PERMISSION_MODE=${permissionMode}`);
-args.push("--", process.execPath, entry);
-
-run(args);
+const servers = JSON.parse(run(["mcp", "list", "--json"]));
+if (!Array.isArray(servers)) throw new Error("Codex returned an invalid MCP inventory; existing configuration was not changed");
+const existing = servers.some((server) => server.name === serverName)
+  ? JSON.parse(run(["mcp", "get", serverName, "--json"])) : null;
+const registration = codexMcpRegistration({ name: serverName, existing, node: process.execPath, entry, env: process.env, desktopOnly: desktopTasksConfigured() });
+run(registration.args);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
 console.log(`registered MCP server "${serverName}" with Codex:`);
-console.log(run(["mcp", "get", serverName]));
-console.log("\nRestart the Codex app (or start a new Codex session) to load the bridge.");
+console.log(`command: ${process.execPath} ${entry}`);
+console.log(`environment keys: ${registration.environmentKeys.join(", ")}`);
+console.log("\nReconnect the MCP server in the existing Codex Desktop task, or restart the app and reopen that same task. Do not create a replacement task.");
+console.log("Verify claude_bridge_status from that task: runtime state must be current and the session policy must match this installation. A separate diagnostic process does not verify the app's loaded MCP process.");
 console.log(`remove: node scripts/install-codex-mcp.mjs --remove`);

package/scripts/install-native-relay.mjs

@@ -6,9 +6,21 @@ import { fileURLToPath } from "node:url";
 
 import { CodexAppServerClient } from "../src/app-server-client.mjs";
 import { bootstrapRelayThread, readRelayConfig, relayConfigPath, relaySocketPath, writeRelayConfig } from "../src/native-relay.mjs";
-import { IS_MACOS, IS_WINDOWS, PLATFORM_LABEL, homeDir, resolveCodexBin, spawnEnv } from "../src/platform.mjs";
+import {
+  IS_MACOS,
+  IS_WINDOWS,
+  PLATFORM_LABEL,
+  hasCodexDesktopApp,
+  homeDir,
+  resolveCodexBin,
+  resolveCodexDesktopNodeBin,
+  spawnEnv,
+} from "../src/platform.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
 
-const VERSION = "1.13.2";
+exitForVersionRequest(import.meta.url);
+
+const VERSION = "1.13.4";
 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";
@@ -53,9 +65,32 @@ try {
 } catch {
   // not registered yet
 }
-run(["mcp", "add", serverName, "--", process.execPath, entry]);
+/**
+ * Registering under whichever Node happens to run this installer is what made
+ * the companion unreachable on macOS: Codex Desktop rejects a peer whose
+ * code-signing identity is not the vendor's, so the relay reported itself
+ * installed while every delivery failed. Resolve a runtime the app trusts
+ * instead, and print it - a mismatch has to be visible here rather than
+ * inferred later from a delivery that never confirms.
+ */
+const runtime = resolveCodexDesktopNodeBin();
+
+run(["mcp", "add", serverName, "--", runtime.path, entry]);
 
 console.log(`platform: ${PLATFORM_LABEL}`);
+console.log(`relay runtime: ${runtime.path} (${runtime.source})`);
+if (runtime.source === "process.execPath" && hasCodexDesktopApp()) {
+  console.log(
+    "\nNOTE: no Codex Desktop runtime was found, so the companion is registered under this Node.",
+  );
+  console.log(
+    "Codex Desktop rejects peers whose code-signing identity is not its own (untrusted-code-signing-identity),",
+  );
+  console.log(
+    "so delivery can fail while the relay still reports itself installed. Set CODEX_NATIVE_RELAY_NODE to the",
+  );
+  console.log("runtime shipped inside Codex Desktop if that happens.");
+}
 console.log(`registered MCP server "${serverName}" with Codex:`);
 console.log(run(["mcp", "get", serverName]));
 

package/scripts/install-npm-footer.mjs

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

package/scripts/npm-footer.ps1

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