@minhspark/codex-mcp-bridge 1.25.2 → 1.26.0

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,64 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.26.0] - 2026-11-01
+
+### Upgrade
+
+The same single command updates the package, reapplies managed client settings and configures the independent background service:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+```
+
+Use `npm.cmd` in Windows PowerShell. Setup applies the managed client registrations, background startup and scoped worker communication settings, including Antigravity's four relay tool grants. CLI authentication and explicit project grants remain separate from installing configuration; no Desktop credentials are copied and no existing denials are removed. Setup supplies a missing Codex CLI; Claude Code and `agy` must be installed separately when those workers are needed.
+
+### Added
+
+- An independent per-user relay and separate Codex, Claude and Antigravity CLI workers, supporting all six worker-to-worker directions. Background jobs and cross-worker messages can continue without a responsive Desktop host. Native conversations retain their existing native routing and are never silently replaced by worker sessions.
+- Durable job receipts, authenticated local transport, same-project delegation, bounded queues and delegation depth, and persistent diagnostic reports. Interrupted sends stay unknown; only proven queued work resumes after daemon restart.
+- Background worker status, discovery, send and receipt tools plus the `worker-relay` command. Service readiness, CLI authentication and model execution evidence are reported separately.
+- Managed background startup and recovery on Windows, macOS and Linux, with hidden Windows launches and idle adoption of updated service code. Setup preserves disabled services and reports pending activation honestly.
+
+### Fixed
+
+- Antigravity MCP registrations use managed supervisors so future package updates can replace idle workers without reconnecting the host. Live CLI sessions and unconfirmed deliveries defer reload; crashed operations are never replayed.
+- Worker CLI launches isolate their session identity from native Desktop chats. Claude worker launches suppress optional user/plugin startup hooks without changing authentication or permission policy.
+- Antigravity worker discovery accepts the CLI's native MCP dispatcher when initialization does not enumerate individual server tools. Dispatcher availability is reported separately from verified relay-tool discovery; missing relay tools and permission failures still produce typed diagnostics.
+
+### Validation and limits
+
+- Live Windows checks completed all six directions between Codex, Claude and Antigravity workers with Antigravity CLI 1.4.12. A saturated delegation returned `WORKER_DELEGATION_CAPACITY` with `not_sent` instead of queuing behind waiting workers.
+- Closed or frozen Desktop apps do not host these workers. A frozen UI cannot accept new user input or display results until it responds; a terminal's `worker-relay` command or another responsive MCP client can submit authorized background work and read receipts.
+- Execution still requires a running operating system and per-user service, installed and authenticated provider CLIs, an authorized project, network/provider availability, quota and effective tool permissions. Saved configuration is not a guarantee of readiness or a live verification result on another machine.
+
+## [1.25.3] - 2026-11-01
+
+### Upgrade
+
+One command updates the package and reapplies managed settings for all clients:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+```
+
+On Windows PowerShell use `npm.cmd` in place of `npm`. Setup reports saved configuration separately from live host readiness and never opens apps or chats to load a relay.
+
+### Fixed
+
+- Normal Codex task creation and delivery no longer navigate or activate the Desktop window by default, including on Windows. Explicit `openInApp: true` remains available. Comprehensive install/update migrates historical automatic navigation settings to the silent default.
+- The native relay refuses navigation to its internal executor, which has no user conversation history and must not be opened as a task.
+- Claude endpoint rediscovery from Codex and Antigravity no longer opens apps or saved chats to load a relay. A dormant native task reports `CLAUDE_SESSION_NOT_READY` with `sent: false`; an endpoint that becomes available is revalidated against the current account, process, directory and native permission policy.
+- Antigravity inbound MCP instructions now describe the existing outbound `agent-bridge` instead of incorrectly claiming that Antigravity cannot send to Codex or Claude. Status reports distinguish supported Desktop routes from unverified outbound readiness and retain the CLI and automatic-reply-forwarding limits.
+- An unreachable Antigravity sidecar now reports a connectivity problem without assuming the App is closed, and points callers to the sidecar diagnostics when the App is already running.
+- Relay and tool failures include a readable diagnostic block and structured report with the exact error/cause codes, operation, phase, bridge/Node/platform versions, UTC time, report ID and safe request identifiers. Credential and private-path redaction applies to the report block. Uncertain sends remain uncertain and are never automatically replayed.
+- Antigravity IPC and durable delivery records preserve original failure codes and reports; failed or unknown receipt reads are surfaced as errors instead of successful-looking results. Supervisor crashes distinguish in-flight unknown delivery from a new request refused before dispatch.
+- The same one-command npm install/update applies managed settings for all clients, shows setup progress, and fails if configuration is incomplete. It enables supported native background preferences without changing accounts or permissions and distinguishes saved configuration from unverified running-client activation.
+
+### Limitations
+
+- Background delivery still requires the native host process and its loaded bridge. Closing a window can retain these processes; fully quitting a native host cannot provide an always-ready endpoint. An unloaded Codex MCP or dormant Claude Code process has no supported silent cold-start path in this bridge. Recovery never opens old, new, empty or failed chats, uses Computer Use, or launches a substitute CLI/app-server.
+
 ## [1.25.2] - 2026-10-31
 
 ### Fixed

package/README.md

@@ -15,33 +15,53 @@
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/@minhspark/codex-mcp-bridge" height="20" alt="license" /></a>
 </p>
 
-Connect **Claude, Codex, and Antigravity** through MCP, keeping work in each agent's own app and preserving native identity and permission checks. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
+Connect **Claude, Codex, and Antigravity** through MCP using native Desktop handoffs or independent CLI background workers. Native handoffs preserve each app's conversation identity and permission checks; workers have separate sessions and enforce provider permissions and project authorization. Supports Windows, macOS, and Linux; native Desktop integration supports Windows and macOS.
 
-The optional **Antigravity bridge** sends work both ways between existing Desktop conversations in the same project. Codex and Claude can also start and continue bridge-owned Antigravity CLI streaming sessions. Antigravity App replies remain in the App; outbound calls from Antigravity CLI are not supported. [Setup and current limits](#antigravity-app-and-cli).
+The **background worker relay** supports all six directions between Codex, Claude and Antigravity CLI workers, independently of Desktop responsiveness. The optional **native Antigravity bridge** connects existing Desktop conversations in the same project and offers separate bridge-owned CLI streaming sessions. Native App replies remain in the App. [Background workers](#independent-background-workers) · [Antigravity native and streaming-session limits](#antigravity-app-and-cli).
 
 https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
 
 ## Installation
 
-One global npm command installs the package and configures the local Claude, Codex, and Antigravity bridges. Install and sign in to the apps you intend to use first. Setup preserves existing project restrictions and custom settings; it does not sign in, grant workspace trust, change permission modes, or restart running apps.
+One global npm command installs the package, configures the local Claude, Codex and Antigravity bridges, and installs the independent worker relay. Native handoffs require the selected Desktop apps; background work requires the selected provider CLIs and their own authentication. Setup preserves existing project restrictions and custom settings; it does not sign in, grant workspace trust, change permission modes, or restart running apps.
 
 ### Package — npm
 
 **macOS / Linux / WSL**
 
 ```bash
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 **Windows PowerShell**
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
-Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. Run the same command to update. The global install runs setup automatically and verifies the saved registrations. If a native Codex CLI is missing, setup installs a pinned official `@openai/codex` package in the current user's `~/.config/GptClaudeBridge/tools` (or the corresponding `XDG_CONFIG_HOME` path); no separate CLI install command is needed.
+Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. **Every release uses this same single install/update command.** It updates the package, applies the managed bridge settings across Claude, Codex and Antigravity, configures the independent background worker relay, and verifies saved registrations and service activation separately. Comprehensive setup migrates historical automatic Codex navigation to `CODEX_BRIDGE_OPEN_IN_APP=0`, enables Claude's native background preference and updates Antigravity's existing Windows background preference where supported. Accounts, project grants, unrelated custom registrations and existing permission denials remain unchanged. Setup adds only the four worker-relay communication grants required by headless Antigravity; it does not enable broad permission bypasses. If a native Codex CLI is missing, setup installs a pinned official `@openai/codex` package in the current user's `~/.config/GptClaudeBridge/tools` (or the corresponding `XDG_CONFIG_HOME` path); no separate CLI install command is needed.
 
-`--allow-scripts=@minhspark/codex-mcp-bridge` authorizes only this package's setup hook. npm versions that block install scripts by default need this flag; a plain install works only when the hook is allowed. Add `--foreground-scripts` to the command to see setup progress because npm may hide lifecycle output. If npm prints `1 package had install scripts blocked`, rerun the recommended command or run `codex-bridge-setup` explicitly.
+### Independent background workers
+
+`worker_status`, `list_workers`, `send_to_worker` and `read_worker_delivery` address separate Codex, Claude and Antigravity CLI workers. The `worker-relay` command provides status, list, send and receipt-read operations from a terminal. All six worker directions are supported: Codex ↔ Claude, Codex ↔ Antigravity and Claude ↔ Antigravity. A native handoff still addresses its original native task; an uncertain native send is never silently replayed through a CLI worker.
+
+The service and worker processes run independently of Desktop hosts. Submitted background jobs and worker-to-worker communication can continue while those apps are closed or frozen. A frozen window cannot accept new user input or display new results until it responds again. Submit authorized background work or inspect its receipts through `worker-relay` in a terminal or another responsive MCP client; this does not repair or reopen the frozen UI.
+
+The operating system and per-user service must be running, the selected CLI must be installed and authenticated, and the project must be authorized. Provider access, network connectivity, quota and tool permissions still apply. Setup supplies a missing Codex CLI; install Claude Code and `agy` separately when those workers are needed. Sleep, shutdown, a disabled service or a provider failure can prevent execution.
+
+`authentication-unverified` with `canAcceptWork: true` is an informational state for a CLI without a supported authentication probe. It is not an authentication failure. Actual failed jobs have a durable diagnostic receipt. Keep the original request ID when inspecting or retrying an uncertain submission; after a terminal `failed` receipt confirms `not_sent`, fix the reported cause before creating a new authorized request.
+
+The package update configures per-user startup: Task Scheduler on Windows, a LaunchAgent on macOS and a systemd user service on Linux. It starts the service without opening apps or chats, preserves intentional disabled choices, and drains active jobs before adopting updated code. `worker-relay status` reports transport availability, provider authentication checks and recent errors separately. A saved configuration is not proof of live activation or model access.
+
+CLI authentication is separate from Desktop sign-in. Workers use each provider's official credential handling; the bridge does not copy Desktop tokens. Codex and Claude use ephemeral CLI sessions. Antigravity starts a fresh CLI-owned conversation and never resumes a Desktop conversation; its CLI may retain history according to provider behavior and uses its shared MCP inventory. Setup preserves other MCP entries and effective provider permissions. No worker opens or navigates that history.
+
+Background dispatch uses the existing shared project-policy file. Select a project explicitly with `bridge-projects allow-project <absolute-project-path>` if it is not already authorized; updates preserve grants and revocations. Each child delegation stays in the same canonical project. Existing provider permissions remain enforced, including denials that prevent unattended execution.
+
+Keep the same request UUID for retries and read its durable receipt. Queued work can survive relay restarts; work that might already have reached a worker is marked unknown and is never replayed automatically. Failure reports remain readable after the original window closes, with error/cause codes, delivery certainty and report IDs. Errors from tool calls appear in their Claude/Codex/Antigravity tool results; this package does not create a separate Desktop popup or reopen a chat to show them.
+
+Worker delegation is bounded. `WORKER_DELEGATION_CAPACITY` means the destination has no free execution slot and that delegation was not sent or queued behind waiting workers. Inspect or finish existing delegated work before retrying the same unsent request. Queue and delegation limits are reported explicitly.
+
+`--allow-scripts=@minhspark/codex-mcp-bridge` authorizes only this package's setup hook. npm versions that block install scripts by default need this flag; a plain install works only when the hook is allowed. `--foreground-scripts` displays configuration progress and failures that npm otherwise hides. If npm prints `1 package had install scripts blocked`, rerun the recommended command or run `codex-bridge-setup` explicitly.
 
 | Client | Installed entry | Purpose |
 | --- | --- | --- |
@@ -51,20 +71,21 @@ Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows P
 | Codex Desktop, Windows/macOS | `codex-native-relay` | Native delivery, pipe forwarding, and relay executor bootstrap |
 | Codex and Claude Code | `antigravity-bridge` | Send to Antigravity App or bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound agent messages and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
-After setup, open or reconnect the affected apps after active work finishes. For native Claude-to-Codex handoffs, use Claude Desktop's **Code tab** and the same local project saved in Codex Desktop. The shared `codex-bridge-desktop` connector has its own legacy route; it does not establish a native Code sender identity. Saved configuration is not proof of a live connection. Complete [verification](#verify-the-installation) in the actual clients.
+For native Claude-to-Codex handoffs, use an existing native Claude **Code** session and the same local project saved in Codex Desktop. The shared `codex-bridge-desktop` connector has its own legacy route; it does not establish a native Code sender identity. Setup applies saved configuration without opening or restarting apps. Saved configuration is not proof of a live connection; available supervisors reload compatible workers when idle. Complete [verification](#verify-the-installation) with the tools already available in the actual clients. If a native host is unloaded, report the diagnostic instead of opening chats to load a relay.
 
 Automatic setup runs only for a **global npm install**. Local `npm install` and `npm ci` do not change app settings. Set `CODEX_BRIDGE_SKIP_SETUP=1`, or pass `--ignore-scripts`, to install the package without configuring apps. The optional [workflow skill](#workflow-skill--npx-skills), VS Code preview, and hosted ChatGPT pairing retain their separate setup steps.
 
 ### Setup recovery and checks
 
-If an app configuration step fails, the npm install retains the package and its commands so setup can be repaired. A successful npm exit alone does not mean all registrations are configured. If setup reports an incomplete component, correct its reported issue and rerun:
+If an app configuration step fails, setup and the global install return a nonzero exit with the failing component. Correct its reported issue and rerun the update command above, or rerun configuration on an existing installation:
 
 ```bash
 codex-bridge-setup
 ```
 
-On Windows use `codex-bridge-setup.cmd`. `codex-mcp-bridge setup` is an equivalent entry point. Repeated setup keeps existing settings and reports conflicts rather than overwriting unrelated registrations.
+On Windows use `codex-bridge-setup.cmd`. `codex-mcp-bridge setup` is an equivalent entry point. Repeated setup reapplies managed bridge settings and reports conflicts rather than overwriting unrelated registrations. `configured: true` confirms saved configuration; `liveVerified: false` means running clients have not been verified to load it. Setup never opens an app or chat, uses Computer Use, or interrupts active work to load a relay. Missing or unsupported native background preferences are reported separately.
 
 ```bash
 codex-bridge-setup --check
@@ -99,18 +120,19 @@ Run `codex-bridge-setup` after installing through Homebrew. The installers recor
 | Codex → Claude Desktop Code | Automatic `claude-bridge` registration |
 | Codex / Claude Desktop Code → Antigravity App or CLI | Automatic Antigravity registrations |
 | Antigravity App → Codex / Claude Desktop Code | Automatic outbound registration and sidecar |
+| Codex ↔ Claude ↔ Antigravity CLI workers | Automatic independent relay setup; provider CLIs, authentication and project grants required |
 | Claude Code ↔ Codex inside VS Code | Separate Windows preview registrations below |
 | ChatGPT → paired Codex Desktop | Hosted plugin plus `codex-sites-connector --pair` |
 
 ### Antigravity App and CLI
 
-The global npm setup registers all Antigravity components. Install and sign in to the Antigravity App and/or `agy` CLI to use them. The following commands are optional for selective manual setup or repair:
+The global npm setup registers all Antigravity components, including the independent `worker-relay` MCP entry and its four scoped CLI communication grants. Install and sign in to the Antigravity App for native conversations or the `agy` CLI for CLI work. The following commands configure only the native bridge and its legacy streaming-session tools; use the global setup above to configure the independent worker service as well:
 
 ```bash
 antigravity-mcp-bridge-install --all
 ```
 
-**Windows PowerShell — all components**
+**Windows PowerShell — all native bridge components**
 
 ```powershell
 antigravity-mcp-bridge-install.cmd --all
@@ -140,28 +162,30 @@ antigravity-mcp-bridge-install --desktop
 antigravity-mcp-bridge-install --all --dry-run
 ```
 
-Use `.cmd` for each command on Windows. `--all` includes all three components; the individual commands are alternatives when only some clients are needed. The installer preserves unrelated configuration and native permissions. Reload Codex/Claude to load the new MCP server. Antigravity launches its own sidecar from `~/.gemini/config/sidecars/codex-bridge/sidecar.json`; do not run that sidecar manually or copy authentication environment variables between processes.
+Use `.cmd` for each command on Windows. `--all` includes the Codex, Claude and Antigravity native bridge components; the individual commands are alternatives when only some clients are needed. The installer preserves unrelated configuration and native permissions. Managed MCP supervisors adopt compatible updates when idle; an old direct process remains on its loaded version until the host reconnects normally. No app or chat is opened to force readiness. Antigravity launches its own sidecar from `~/.gemini/config/sidecars/codex-bridge/sidecar.json`; do not run that sidecar manually or copy authentication environment variables between processes.
 
-The `agy` CLI must be installed and signed in separately. CLI sessions are started through the `start_antigravity_cli_session` MCP tool; there is no separate `--cli` installer flag. Set `ANTIGRAVITY_CLI_BIN` to the absolute `agy` executable path in the MCP server environment if automatic discovery cannot find it.
+The `agy` CLI must be installed and signed in separately. The legacy `start_antigravity_cli_session` tool creates streaming sessions owned by the calling bridge process; independent background work instead uses `send_to_worker` with `agent: "antigravity"`. There is no separate `--cli` installer flag. Set `ANTIGRAVITY_CLI_BIN` to the absolute `agy` executable path in the MCP server environment if automatic discovery cannot find it.
 
 | Tool | Behavior |
 | --- | --- |
-| `antigravity_bridge_status` | Reports native sidecar connectivity and CLI capabilities. |
+| `antigravity_bridge_status` | Reports native sidecar connectivity, CLI capabilities, and the separate outbound Desktop route. Outbound readiness requires `agent_bridge_status` inside Antigravity. |
 | `list_antigravity_conversations` | Lists the selected surface in the verified sender's exact project directory. |
 | `send_to_antigravity_conversation` | Sends to an exact existing App conversation or a CLI session owned by this bridge. |
 | `start_antigravity_cli_session` | Starts an explicitly authorized CLI streaming session with its initial prompt. |
 | `read_antigravity_delivery` | Reads the original receipt without resending. |
 | `close_antigravity_cli_session` | Closes an idle CLI session owned by the sender. |
 
-Generate a new `requestId` UUID for each intentional delivery and reuse it only when inspecting or retrying that same delivery. A pending or unknown receipt must be inspected before further action. Receipts survive process restarts; live CLI processes do not. A CLI timeout retains its conversation identity for inspection. No mode or permission-bypass flag is added; headless tool requests requiring interaction may be denied by Antigravity.
+For these native bridge and legacy streaming-session tools, generate a new `requestId` UUID for each intentional delivery and reuse it only when inspecting or retrying that same delivery. A pending or unknown receipt must be inspected before further action. Receipts survive process restarts; live streaming CLI processes do not. A CLI timeout retains its conversation identity for inspection. No mode or permission-bypass flag is added; headless tool requests requiring interaction may be denied by Antigravity.
 
-The App adapter uses the official [sidecar `agentapi`](https://antigravity.google/docs/sidecars), verifies native workspace metadata, and refuses busy or ambiguous destinations. An App `accepted` receipt confirms native acceptance, not a completed agent reply. Open the exact App conversation to read its response. The CLI adapter uses the official [streaming JSON interface](https://antigravity.google/docs/cli/headless) and returns the agent's final result. It creates bridge-owned headless sessions; it does not attach to an already running interactive terminal. The two surfaces never substitute for one another.
+The App adapter uses the official [sidecar `agentapi`](https://antigravity.google/docs/sidecars), verifies native workspace metadata, and refuses busy or ambiguous destinations. An App `accepted` receipt confirms native acceptance, not a completed agent reply. Its response remains in the exact native App conversation and can be read when that UI is responsive. The CLI adapter uses the official [streaming JSON interface](https://antigravity.google/docs/cli/headless) and returns the agent's final result. It creates bridge-owned headless sessions; it does not attach to an already running interactive terminal. The two surfaces never substitute for one another.
 
-The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.gemini/config/mcp_config.json`. Reload the App after installation to discover it. From an Antigravity conversation, ask the agent to check `agent_bridge_status`, call `list_agent_tasks` for `codex` or `claude`, then use `send_to_agent_task` with the exact destination ID, project directory, prompt, and a fresh request UUID. Claude destinations also require their native `taskId`. Read `read_agent_delivery` without resending; `read_agent_task` reads the selected Codex task's response or Claude's native task metadata.
+The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.gemini/config/mcp_config.json`. Once the host has loaded that registration, use the tools available in the intended Antigravity conversation: check `agent_bridge_status`, call `list_agent_tasks` for `codex` or `claude`, then use `send_to_agent_task` with the exact destination ID, project directory, prompt, and a fresh request UUID. Claude destinations also require their native `taskId`. Read `read_agent_delivery` without resending; `read_agent_task` reads the selected Codex task's response or Claude's native task metadata.
 
-Outbound calls verify Antigravity's per-call MCP metadata, Desktop process ancestry, native workspace/project, and effective permission settings. The sender is attributed as Antigravity. Codex keeps its native task settings; Claude's inbound policy and permission-class checks remain in effect. A socket write to Claude is `sent_unconfirmed`, not acceptance or completion. After MCP restart, a saved receipt remains available but live Claude reply tracking may be unavailable; inspect the exact native task before further action.
+Native outbound calls verify Antigravity's per-call MCP metadata, Desktop process ancestry, native workspace/project, and effective permission settings. The sender is attributed as Antigravity. Codex keeps its native task settings; Claude's inbound policy and permission-class checks remain in effect. A socket write to Claude is `sent_unconfirmed`, not acceptance or completion. After MCP restart, a saved receipt remains available but live Claude reply tracking may be unavailable; inspect the exact native task before further action.
 
-Outbound support targets existing local Codex tasks and live Claude Desktop Code sessions in the same project. Nested Antigravity callers, outbound CLI callers, App conversation creation, and automatic App reply forwarding are not implemented. Windows Desktop is the live verification platform; macOS ancestry has unit coverage and Linux outbound host verification fails closed. The existing Codex↔Claude bridge remains separate. Use `antigravity-mcp-bridge-install --all --remove` to remove only these registrations; delivery receipts are retained.
+If a caller says the bridge only supports one-way messaging, compare its loaded version with the installed package: older initialization instructions incorrectly denied the separate native outbound route. A managed worker can reload when idle; an old direct MCP process requires a normal host reconnection. An unavailable inbound sidecar does not prove that the App is closed or that outbound messaging is unsupported. Use available `agent_bridge_status` diagnostics to verify the native outbound route independently, and `worker_status` for the independent workers.
+
+Native outbound support targets existing local Codex tasks and live Claude Desktop Code sessions in the same project. That route rejects nested Antigravity callers and CLI callers claiming Desktop identity; App conversation creation and automatic App reply forwarding are not implemented. These native limits do not restrict the separately authorized CLI workers, which communicate through `worker-relay` in all six directions. Windows Desktop is the native live verification platform; macOS ancestry has unit coverage and Linux native outbound host verification fails closed. The existing Codex↔Claude native bridge remains separate. Use `antigravity-mcp-bridge-install --all --remove` to remove only the native bridge registrations; independent worker configuration and delivery receipts are retained.
 
 ### Windows (PowerShell)
 
@@ -276,7 +300,7 @@ codex-mcp-bridge-install.cmd --entry-name codex-bridge-desktop
 CODEX_BRIDGE_DESKTOP_TASKS=0 CODEX_BRIDGE_AUTOSTART=1 codex-mcp-bridge-install --entry-name codex-bridge-desktop
 ```
 
-Close and reopen Claude after active work finishes to load changed shared configuration. A fresh `--entry-name codex-bridge-desktop` registration defaults to legacy mode even when the native relay is configured. Existing custom modes are preserved. `--desktop-tasks` does not make a shared Desktop chat server a verified Code sender.
+Running clients may retain their previously loaded configuration; setup reports live activation as unverified and does not interrupt them. A fresh `--entry-name codex-bridge-desktop` registration defaults to legacy mode even when the native relay is configured. Existing custom modes are preserved. `--desktop-tasks` does not make a shared Desktop chat server a verified Code sender.
 
 ### VS Code extensions — Windows preview
 
@@ -305,7 +329,7 @@ On Windows and macOS, `codex-native-relay-install` adds this to the relay's entr
 env_vars = ["CODEX_APP_TOOLS_PIPE_PATH"]
 ```
 
-If you register the relay by hand, add the same line and append the variable name if `env_vars` already exists. Only the name is saved, never the temporary pipe path. Restart Codex Desktop after active work finishes so it relaunches the relay.
+If you register the relay by hand, add the same line and append the variable name if `env_vars` already exists. Only the name is saved, never the temporary pipe path. The changed environment takes effect when the native host next reconnects that MCP process; setup does not restart the app or open a chat to force it.
 
 ### Linux / WSL (Bash)
 
@@ -444,7 +468,7 @@ This repository ships a hosted ChatGPT plugin and the skill above. It does not c
 
 Run `codex-bridge-setup --check` (`codex-bridge-setup.cmd --check` on Windows) to inspect saved registrations. An incomplete result names the component requiring attention; rerun setup after correcting it.
 
-Reconnect the affected MCP servers in the actual client tasks; Claude Code provides `/mcp`. If the app has not loaded the new registrations, close and reopen it after active work finishes. Setup does not kill or restart apps. Run these **MCP tools** inside the apps:
+Use the bridge tools already available in the actual clients. Configuration checks do not prove that a running client loaded new registrations. Setup does not open, kill or restart apps or chats. If a tool is unavailable, retain that exact failure for reporting. Run these **MCP tools** when available:
 
 | Client | Tool |
 |---|---|
@@ -453,6 +477,9 @@ Reconnect the affected MCP servers in the actual client tasks; Claude Code provi
 | Codex Desktop | `native_relay_status` |
 | Codex / Claude Desktop Code with Antigravity installed | `antigravity_bridge_status` |
 | Antigravity App | `agent_bridge_status` |
+| Any configured background relay client | `worker_status` |
+
+For the independent service, `worker-relay status` (`worker-relay.cmd status` on Windows) works from a terminal without a responsive Desktop app. Inspect transport, CLI authentication and recent execution errors separately. A CLI with unverified authentication still needs a successful authorized job before model access is established.
 
 To check CLI registrations without sending work:
 
@@ -463,7 +490,7 @@ claude mcp list
 
 These optional CLI checks require the respective CLI on PATH; the complete setup check can also use its managed Codex CLI. On Windows use `codex.exe mcp list`. An installed skill is listed separately with `npx skills list` (add `-g` for user-wide skills); it is not an MCP registration.
 
-Send a short message and confirm its reply **in both directions**. Registration alone does not prove delivery.
+For an authorized live check, send a short message and confirm its reply on each selected route. Check worker-to-worker routes separately from native conversations; registration alone does not prove delivery.
 
 ## Use
 
@@ -518,10 +545,10 @@ Node.js 22.13+ is required. If a command is missing, open a new terminal and che
 If the package or registrations are missing, use the complete installation command:
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
-On npm 12, `1 package had install scripts blocked` means the setup hook did not run. The scoped `--allow-scripts` flag authorizes this package's hook; it does not enable every package's scripts globally. Add `--foreground-scripts` to see lifecycle progress. A local `npm install`/`npm ci`, `--ignore-scripts`, or `CODEX_BRIDGE_SKIP_SETUP=1` intentionally skips automatic setup.
+On npm 12, `1 package had install scripts blocked` means the setup hook did not run. The scoped `--allow-scripts` flag authorizes this package's hook; it does not enable every package's scripts globally. `--foreground-scripts` displays lifecycle progress. A local `npm install`/`npm ci`, `--ignore-scripts`, or `CODEX_BRIDGE_SKIP_SETUP=1` intentionally skips automatic setup.
 
 For an already-installed package, preview and apply setup explicitly:
 
@@ -622,7 +649,7 @@ codex-bridge-setup.cmd --check
 
 1. Save the original task/delivery IDs and let active work finish before replacing its connection. A pending or uncertain delivery can intentionally defer automatic worker reload.
 2. In the affected Claude **Code** session, open `/mcp`, select `codex-bridge`, and reconnect. In ordinary Chat, inspect the separate `codex-bridge-desktop` connector. Reconnect the relevant Codex MCP entries in their actual task as needed.
-3. If the client cannot reload that connection, open a new Code session in the same saved project to verify the registration. Reopen the app only after active work is safe to stop. A window's **Reload** action may refresh its UI while retaining the old Code process and MCP failure state.
+3. If the client cannot reload that connection, retain its diagnostic until the host reconnects normally. Do not open or create a chat to bootstrap a relay. A window's **Reload** action may refresh its UI while retaining the old Code process and MCP failure state. Separately authorized background work remains available through the independent service when its own prerequisites are satisfied.
 4. Call the status tool from that client and compare its runtime version, registration and sender/relay state. A standalone process answering `initialize`, or printing `ready`, does not verify the app's connection.
 
 An old worker cannot learn a newly written client environment from a disk update alone. Compatible source changes can reload through the supervisor when idle, but changed launchers/environment or a blocked old connection may still require reconnecting. Do not restart active work merely to clear a receipt or make a status indicator green.
@@ -667,11 +694,15 @@ For a repeatable failure, capture the app/OS/Node versions, the version reported
 
 ### Relay unavailable, stale pipe, or an active writer
 
+Normal task creation and delivery run without navigating or focusing Codex Desktop. Use `openInApp: true` only when the user wants to see the target task. The comprehensive install/update command migrates older `CODEX_BRIDGE_OPEN_IN_APP=1` settings to `0`. The internal relay executor is not a user conversation and cannot be opened through the bridge.
+
+Closing an application window and quitting its native host have different effects. Antigravity's native `runInBackground` setting keeps its sidecar running after the last window closes; Windows defaults to quitting when this setting is off. On Windows, use Codex's native startup task for background startup instead of an additional foreground `shell:AppsFolder` launcher. A healthy loaded relay can recover its worker, but cannot cold-start an unloaded Codex MCP. No periodic task-opening loop is used to simulate readiness.
+
 **Symptoms:** `RELAY_UNAVAILABLE`, `connect ENOENT`, a missing native relay socket, or `thread ... already has an active writer`.
 
-Native Desktop handoffs require Codex Desktop to be installed, signed in and open on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. Recovery never navigates to a task, launches a window, or activates Codex. The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff; pending requests fail without replay, and later requests use the recovered worker. Inherited native pipe hints are rediscovered through the original Desktop process ancestry when they become stale. Requests that never reached the relay wait up to 20 seconds, within their original deadline, for its transport to recover. `CODEX_BRIDGE_RELAY_WAKE=0` disables that wait; the retired `CODEX_BRIDGE_RELAY_KEEPER` flag cannot enable UI navigation.
+Native Desktop handoffs require Codex Desktop to be installed, signed in and running on Windows/macOS. The app runs `codex-native-relay` while a regular task has its MCP servers loaded. These native-host requirements do not apply to [independent background workers](#independent-background-workers). Recovery never navigates to a task, launches a window, or activates Codex. The Desktop-owned supervisor restarts crashed native relay workers with bounded exponential backoff; pending requests fail without replay, and later requests use the recovered worker. Inherited native pipe hints are rediscovered through the original Desktop process ancestry when they become stale. Requests that never reached the relay wait up to 20 seconds, within their original deadline, for its transport to recover. `CODEX_BRIDGE_RELAY_WAKE=0` disables that wait; the retired `CODEX_BRIDGE_RELAY_KEEPER` flag cannot enable UI navigation.
 
-Check `native_relay_status` in a regular project task and `codex_bridge_status` in the sending Code session. Native status performs a read-only `list_projects` probe and reports native dispatch separately from socket availability. Recovery requires the original Desktop-owned supervisor to remain alive: it cannot cold-start MCP when Desktop has loaded no session, and it stops when the MCP client closes. After five unsuccessful worker replacements, reconnect MCP in a regular task. Do not open the internal **Native Relay** executor; it is not an interactive chat and may show a missing-rollout error. Rerun setup if registration/executor configuration is missing, and verify [native relay pipe forwarding](#native-relay-pipe-forwarding). Never persist a pipe address copied from a different app process. After upgrading from a supervisor without crash recovery, reconnect the relay MCP once to load the updated supervisor; worker hot reload alone cannot replace its parent.
+Use the available `native_relay_status` and `codex_bridge_status` tools without opening a chat to load them. Native status performs a read-only `list_projects` probe and reports native dispatch separately from socket availability. Recovery requires the original Desktop-owned supervisor to remain alive: it cannot cold-start an unloaded native MCP, and it stops when the MCP client closes. After five unsuccessful worker replacements, report the exact diagnostic. Never open an old, new, empty, failed or internal **Native Relay** chat to bootstrap readiness. Rerun setup if registration/executor configuration is missing, and verify [native relay pipe forwarding](#native-relay-pipe-forwarding). Never persist a pipe address copied from a different app process. Worker hot reload cannot replace a running supervisor from an older release; configuration success alone does not prove that process is upgraded.
 
 An active-writer error usually identifies the legacy app-server route attempting to attach to a thread already owned by Desktop. Use the registered native Code-to-Desktop route for that conversation. Do not start another app-server or terminate shared work to force access. The ordinary `codex-bridge-desktop` Chat connector remains a legacy app-server connection; it is not a substitute for the verified native sender. An unused `CODEX_APP_SERVER_URL` alongside `external app-server disabled` is not by itself a native connection failure.
 
@@ -681,13 +712,31 @@ Use native session discovery and peer delivery from the Codex task:
 
 1. Call `list_claude_sessions` with the exact absolute `expectedCwd`.
 2. Verify the returned `entrypoint: claude-desktop`, `sessionId`, native `desktop.taskId`, and project directory. Use `read_claude_transcript` with that session identity to confirm the intended unfinished work when needed; a title alone is insufficient.
-3. Call `send_to_claude_session` with the exact session identity as `target`, the independently verified `expectedCwd`, and the returned native ID as `expectedTaskId`. For an exact dormant saved task, `target: "auto"` plus its `expectedTaskId` lets the bridge reopen and rediscover that task without substituting another conversation.
+3. Call `send_to_claude_session` with the exact session identity as `target`, the independently verified `expectedCwd`, and the returned native ID as `expectedTaskId`. `target: "auto"` plus `expectedTaskId` rediscovers the exact live endpoint without opening the app or chat. A dormant saved task returns `CLAUDE_SESSION_NOT_READY`, `sent: false`.
 4. Preserve the returned `msgId`. After a timeout, inspect it with `read_claude_delivery`; read `read_claude_inbox` for late replies and correlated bridge-status notifications.
 
-If no eligible session appears, open the intended Claude **Code** task in the same project and check sign-in, data-root selection and sender status. A new ordinary Chat window or unrelated CLI session does not establish that native recipient. [1.25.0](CHANGELOG.md#1250---2026-10-30) clarifies the tool instructions to use this route; it cannot guarantee every model follows them. External Computer Use typing/clicking is not a delivery fallback for an already-open session.
+If no eligible session appears, inspect sign-in, data-root selection and sender status using available bridge diagnostics. Saved history does not prove that a native Code endpoint is running. There is no supported silent cold-start API for a dormant Claude task. The bridge reports this limitation instead of opening a chat, using Computer Use, or launching a substitute CLI. Closing a window can preserve native background work; fully quitting the native host removes its receiving endpoint.
+
+Antigravity's `list_agent_tasks` also reports verified dormant Claude tasks with `status: "dormant"`, `recoverable: false` and `code: "CLAUDE_SESSION_NOT_READY"`. Discovery and sends never open the application or a chat to load its endpoint. Archived tasks, changed accounts, mismatched directories and uncertain sends remain blocked.
 
 `PEER_REPLY_PENDING` protects an earlier unresolved message. A `held` receipt, `CLAUDE_RECIPIENT_INBOUND_POLICY`, or `CLAUDE_RECIPIENT_CLASS_MISMATCH` identifies an actual recipient policy/permission boundary. Inspect the original receipt and task; resolve the stated policy through the user's intended host settings. Installing a newer bridge does not authorize changing permissions. An `interrupted` bridge-status notification ends observation only: it is not Claude's answer, does not cancel background work, and does not make retrying the original action safe.
 
+### Screenshot-ready error reports
+
+Failures include a **Bridge diagnostic** block in the tool result and `structuredContent.diagnostic` for clients. Capture that block when filing an issue. It contains the exact error and cause codes, component, tool, phase, bridge/Node/platform versions, UTC timestamp, report ID and available request/message/delivery IDs. It excludes request prompts, tokens and account identities and redacts common credential, URL, email and private-path patterns from the error reason. Review any surrounding output before sharing it.
+
+| Diagnostic | Meaning |
+|---|---|
+| `RELAY_UNREACHABLE` | Native relay transport could not be reached; this alone does not prove the app is closed. |
+| `NATIVE_PIPE_UNAVAILABLE` | The native dispatch pipe could not be verified. |
+| `CLAUDE_SESSION_NOT_READY` | The exact saved task has no live native Code endpoint; silent cold-start is unavailable. |
+| `CLAUDE_RECIPIENT_INBOUND_POLICY` / `CLAUDE_RECIPIENT_CLASS_MISMATCH` | Native recipient policy or permission classes block the handoff. |
+| `CLAUDE_REPLY_TIMEOUT` | A send has no confirmed reply yet; retain its message ID. |
+| `MCP_WORKER_EXITED` | A worker exited while handling a request; its delivery may already have happened. |
+| `MCP_WORKER_UNAVAILABLE` | This new request was refused before dispatch while its worker was unavailable. |
+
+`deliveryState: not_sent` means this operation did not send a message. `unknown` means delivery remains uncertain; inspect the original receipt and never automatically resend. `not_applicable` marks a diagnostic read rather than a send. A diagnostic does not instruct an agent to create/open chats, use Computer Use, or change permissions to make the error disappear.
+
 ### Normal startup output labelled as an error
 
 Claude may label stderr as `ERR: Server stderr`, including ordinary `[bridge-supervisor] preparing`, `prepared`, and `[codex-mcp-bridge] ready` lines. The label alone is not a failure. Look for the actual connection result, exception, or timeout and verify the tool from the client. Keep diagnostics on stderr: stdout is reserved for MCP protocol messages, and redirecting logs there can break initialization.
@@ -729,7 +778,7 @@ The catalog below records user-visible failures fixed in earlier releases. It is
 | An account switch, a large task database or a concurrent metadata update hid an otherwise valid Claude task | [1.14.0](CHANGELOG.md#1140---2026-09-07): per-call account discovery, including Store data. [1.18.1](CHANGELOG.md#1181---2026-09-25): bounded discovery beyond 32 MiB. [1.22.3](CHANGELOG.md#1223---2026-10-15): retry changed metadata snapshots. | Check sign-in and [data-root selection](#microsoft-store-claude-or-multiple-data-directories), then rediscover. Conflicting, archived or persistently changing identities still fail closed; shared Chat still cannot prove Code ancestry. |
 | Windows ancestry checks expired while PowerShell was still starting | [1.19.1](CHANGELOG.md#1191---2026-09-29): separate startup/read deadlines. [1.25.0](CHANGELOG.md#1250---2026-10-30): coalesce identical simultaneous inspections. | Use the [timeout diagnostic steps](#connection-timeout-versus-sender-inspection-timeout). These changes do not establish a fix for every MCP initialization timeout. |
 | Ordinary managed Codex tasks were rejected as unverified senders; some review flags caused incorrect permission classification | [1.19.0](CHANGELOG.md#1190---2026-09-29): support verified managed prompting profiles. [1.13.6](CHANGELOG.md#1136---2026-09-06): correct human-review classification. | Upgrade and inspect `claude_bridge_status`. A real recipient class/inbound-policy mismatch remains a denial; do not change sandbox or approval settings merely to suppress it. |
-| Dormant Claude tasks could not resume; a new Windows conversation opened in “No folder”; an app update broke its URI launcher | [1.19.7](CHANGELOG.md#1197---2026-10-02): exact-task recovery, Windows folder/submission verification and launcher recovery. [1.22.4](CHANGELOG.md#1224---2026-10-19): moved-project discovery for authorized new conversations. | Resume the exact saved task with `target: "auto"` and `expectedTaskId`. A moved directory is a discovery candidate, not proof that an old task is safe to resume. Inspect an existing creation receipt before opening another composer. |
+| Dormant Claude tasks could not resume; a new Windows conversation opened in “No folder”; an app update broke its URI launcher | [1.19.7](CHANGELOG.md#1197---2026-10-02): exact-task recovery and composer verification. [1.25.3](CHANGELOG.md#1253---2026-11-01): removes implicit app/chat reopening from recovery. | `target: "auto"` rediscovers an existing live endpoint only. A dormant task reports `CLAUDE_SESSION_NOT_READY`; never open or create a chat to load a relay. A moved directory remains an unverified discovery candidate. |
 | A listed human-created thread returned `NOT AUTHORIZED`; a path from another computer resolved incorrectly | [1.11.0](CHANGELOG.md#1110---2026-08-23): explicit thread policy. [1.8.0](CHANGELOG.md#180---2026-08-19) / [1.11.2](CHANGELOG.md#1112---2026-08-28): usable cross-machine path resolution. | Verify the exact saved project and intended grant/thread policy. Listing and mutation have different authorization requirements; setup preserves existing restrictions and cannot authorize a different project. |
 | An Antigravity App restart could leave a sidecar attached to the retired parent | [1.24.0](CHANGELOG.md#1240---2026-10-28): sidecars track native parent identity and exit when that parent stops. | Use current setup and reconnect through the active App. An App receipt confirms native acceptance only; App reply forwarding and new App conversation creation remain unsupported. |
 

package/docs/new-macos-setup.md

@@ -1,35 +1,58 @@
 # New macOS setup
 
-Connect Claude Desktop's **Code tab** and Codex Desktop through local MCP
-processes and sockets. Both apps still authenticate with their providers and
-use hosted models; local bridge transport does not mean offline inference.
+Connect native Desktop conversations through local MCP processes and sockets,
+or use independent Claude, Codex and Antigravity CLI workers. Both routes use
+provider authentication and hosted models; local bridge transport does not mean
+offline inference.
 
 ## One-command local installation
 
 The [ChatGPT plugin setup](../README.md#chatgpt-plugin) uses a hosted Sites
-connector. For local Desktop use, install Node.js 22.13+ and sign in to the apps
-under the same macOS user. Save the intended local project in Codex Desktop and
-open it in Claude's Code tab, then run:
+connector. Install Node.js 22.13+ under the macOS account that will use the
+bridges. Native handoffs require signed-in apps and the same local project saved
+in Codex Desktop and Claude's Code tab. Independent background workers use
+separately authenticated provider CLIs and do not require open Desktop apps.
+Run:
 
 ```bash
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 The script allowance applies only to this package's setup hook. npm versions
 that block install scripts by default need it; a plain install is sufficient
-only when the hook is allowed. Append `--foreground-scripts` to see progress.
+only when the hook is allowed. `--foreground-scripts` displays setup progress.
 If npm reports `1 package had install scripts blocked`, rerun the command above
 or run `codex-bridge-setup` explicitly.
 
 Setup registers the local bridges, adds native pipe forwarding, and bootstraps
 the relay executor. It reuses an available Codex CLI or installs a pinned
 official package under `~/.config/GptClaudeBridge/tools` (or
-`XDG_CONFIG_HOME/GptClaudeBridge/tools`). No separate CLI install command is
-required. Run the install under the account that uses the apps, without `sudo`.
+`XDG_CONFIG_HOME/GptClaudeBridge/tools`). No separate Codex CLI install command
+is required. Run the install under the account that uses the apps, without `sudo`.
 The package remains installed if an app configuration step fails, preserving
 the setup command for repair. A successful npm exit does not verify that every
 component is configured.
 
+The command also installs an independent per-user LaunchAgent for separate
+Claude, Codex and Antigravity CLI workers and updates its managed settings on
+each release. It registers worker communication and adds only Antigravity's four
+relay tool grants, preserving existing denials, disabled choices and unrelated
+settings. Install Claude Code and `agy` separately when those workers are needed;
+CLI authentication is separate from Desktop sign-in.
+
+With authenticated CLIs and an authorized project, `send_to_worker` supports
+all six worker-to-worker directions independently of closed or frozen Desktop
+apps. The operating system and user service must be running; network/provider
+access, quota and tool permissions still apply. A frozen window cannot accept
+new user input or show results until it responds. Use `worker-relay` in a terminal
+or another responsive MCP client to submit authorized background work and read
+receipts. These workers do not resume native chats or launch Desktop windows.
+
+Use `worker-relay status` to inspect service and CLI readiness separately, and
+`read_worker_delivery` for durable results. Authorize a selected project with
+`bridge-projects allow-project <absolute-project-path>` before sending work if
+it has no existing grant.
+
 | Client | Entry | Route |
 | --- | --- | --- |
 | Claude Code | `codex-bridge` | Native Codex Desktop handoffs |
@@ -38,22 +61,25 @@ component is configured.
 | Codex | `codex-native-relay` | Native Desktop transport |
 | Codex and Claude Code | `antigravity-bridge` | Antigravity App and bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound messaging and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
 The shared `codex-bridge-desktop` connector cannot establish a native Code
 sender identity. The native route uses the actual Code session and the same
 saved local Codex project. Setup does not pair the hosted ChatGPT connector.
 
-The relay needs the trusted app-bundled Node runtime selected by setup; do not
-substitute an arbitrary Homebrew/nvm Node. Pipe forwarding saves only the
-`CODEX_APP_TOOLS_PIPE_PATH` variable name, never its temporary value.
-
-Open or reconnect the affected MCP servers in the actual Desktop conversations,
-or restart the app after active work finishes. Setup does not restart or kill
-apps. Check `codex_bridge_status` inside Claude Code, `claude_bridge_status` and
-`native_relay_status` in Codex, and `agent_bridge_status` in Antigravity. Complete
-[installation verification](../README.md#verify-the-installation), including
-a message and reply in each direction. Saved configuration is not a completed
-live exchange or a claim of verification on another Mac.
+The native Codex relay needs the trusted app-bundled Node runtime selected by
+setup; do not substitute an arbitrary Homebrew/nvm Node. Pipe forwarding saves
+only the `CODEX_APP_TOOLS_PIPE_PATH` variable name, never its temporary value.
+
+Managed MCP supervisors adopt compatible updates when idle. An old direct MCP
+process remains stale until its host reconnects normally; setup does not open
+or create chats, restart apps or interrupt active work to load a relay. When the
+tools are available, check `codex_bridge_status` inside Claude Code,
+`claude_bridge_status` and `native_relay_status` in Codex, and
+`agent_bridge_status` in Antigravity. Follow
+[installation verification](../README.md#verify-the-installation) for each
+selected native or background route. Saved configuration is not a completed live
+exchange or a claim of verification on another Mac.
 
 ## Checks, recovery, and manual alternatives
 

package/docs/new-windows-setup.md

@@ -1,16 +1,17 @@
 # Windows setup and initial permissions
 
-Install Node.js 22.13+ and sign in to the apps you intend to use. For native
-handoffs, save the local project in Codex Desktop and open the same directory
-in Claude Desktop's **Code tab**. Run one PowerShell command:
+Install Node.js 22.13+. Native handoffs use signed-in Desktop apps and the same
+local project saved in Codex Desktop and Claude Desktop's **Code tab**.
+Independent background work uses separately authenticated provider CLIs and
+does not require the Desktop apps to be open. Run one PowerShell command:
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge
+npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
 ```
 
 The `--allow-scripts` value permits only this package's setup hook. npm versions
 that block install scripts by default need it; a plain install runs setup only
-when scripts are allowed. Add `--foreground-scripts` to see setup progress. If
+when scripts are allowed. `--foreground-scripts` displays setup progress. If
 npm reports `1 package had install scripts blocked`, run the recommended command
 again or run `codex-bridge-setup.cmd` explicitly.
 
@@ -22,6 +23,27 @@ executor. A failed component is reported as incomplete rather than ready. The
 package stays installed when an app configuration step fails, so the setup
 command remains available for repair. npm success alone does not verify setup.
 
+The same command installs the independent worker relay as a hidden per-user
+scheduled task and applies its managed settings on every update. It registers
+worker communication and adds only the four Antigravity relay tool grants;
+existing disabled settings, permission denials and unrelated settings remain.
+Install Claude Code and `agy` separately when those workers are needed; setup
+supplies a missing Codex CLI. CLI authentication is separate from Desktop sign-in.
+
+Once the selected CLIs are authenticated and the project is authorized,
+`send_to_worker` supports all six directions between Claude, Codex and
+Antigravity workers, even while Desktop apps are closed or frozen. The operating
+system and user service must be running; network/provider access, quota and tool
+permissions still apply. A frozen window cannot accept new user input or show
+results until it responds. Use `worker-relay.cmd` in a terminal or another
+responsive MCP client to submit authorized work and read receipts. The relay
+does not open apps or resume native chats.
+
+Use `worker-relay.cmd status` to inspect service and CLI readiness separately,
+and `read_worker_delivery` for durable results and diagnostic reports. Authorize
+a selected project with `bridge-projects.cmd allow-project <absolute-project-path>`
+before sending work if it has no existing grant.
+
 ## Installed entries
 
 | Client | Entry | Purpose |
@@ -32,16 +54,19 @@ command remains available for repair. npm success alone does not verify setup.
 | Claude Desktop shared connectors | `codex-bridge-desktop` | Connect ordinary chat to local Codex app-server sessions |
 | Codex and Claude Code | `antigravity-bridge` | Send to Antigravity App or bridge-owned CLI sessions |
 | Antigravity | `agent-bridge` and `codex-bridge` sidecar | Outbound agent messages and native App connectivity |
+| Independent CLI workers | `worker-relay` | Authorized background jobs and all six worker-to-worker directions |
 
 The shared `codex-bridge-desktop` connector does not establish a native Code
 sender identity. Use the actual Code session for native Codex Desktop work.
 Existing project restrictions, permission modes, and custom settings are
 preserved. Setup does not sign in, grant workspace trust, or close applications.
 
-After active work finishes, open or reconnect the affected apps so they load
-the entries. A conversation refresh may leave the previous MCP process loaded.
-Check `codex_bridge_status` inside the sending Claude Code task,
-`claude_bridge_status` and `native_relay_status` in Codex, and
+Managed MCP supervisors adopt compatible updates when idle. An old direct MCP
+process remains stale until its host reconnects normally; setup does not open
+or create a chat to load it. A conversation refresh may leave the previous
+process loaded. When the tools are available, check `codex_bridge_status` inside
+the sending Claude Code task, `claude_bridge_status` and `native_relay_status`
+in Codex, and
 `agent_bridge_status` in Antigravity. Configuration verification is separate
 from a completed live exchange.