@minhspark/codex-mcp-bridge 1.25.2 → 1.25.3

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,33 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [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

@@ -30,18 +30,18 @@ One global npm command installs the package and configures the local Claude, Cod
 **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, and verifies the saved registrations. 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, permissions, project grants and unrelated custom registrations remain unchanged. 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.
+`--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 |
 | --- | --- | --- |
@@ -52,19 +52,19 @@ Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows P
 | 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 |
 
-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
@@ -146,7 +146,7 @@ The `agy` CLI must be installed and signed in separately. CLI sessions are start
 
 | 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. |
@@ -161,6 +161,8 @@ The installer also registers **agent-bridge inside Antigravity Desktop** in `~/.
 
 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.
 
+If a caller says the bridge only supports one-way messaging, reload its `antigravity-bridge` MCP server after updating: older initialization instructions incorrectly denied the separate outbound route. An unavailable inbound sidecar does not prove that the App is closed or that outbound messaging is unsupported. If the App is already running, inspect its `codex-bridge` sidecar; check `agent_bridge_status` from Antigravity to verify outbound readiness independently.
+
 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.
 
 ### Windows (PowerShell)
@@ -276,7 +278,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
 
@@ -444,7 +446,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 |
 |---|---|
@@ -667,11 +669,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.
 
-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 +687,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 +753,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.25.2",
+  "version": "1.25.3",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.25.2",
+  "version": "1.25.3",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-antigravity-bridge.mjs

@@ -17,7 +17,7 @@ function object(value, label) {
   return value;
 }
 
-function snapshot(file) {
+function snapshot(file, jsonLabel) {
   let descriptor;
   try { descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); }
   catch (error) {
@@ -41,7 +41,13 @@ function snapshot(file) {
     }
     if (length !== opened.size || !matches(opened, fs.fstatSync(descriptor)) || !matches(opened, fs.lstatSync(file))) throw new Error(`Configuration changed while reading: ${file}`);
     const text = buffer.subarray(0, length).toString("utf8");
-    return { file, text, value: object(JSON.parse(text), file), mode: opened.mode & 0o777, dev: opened.dev, ino: opened.ino };
+    let value;
+    try { value = object(JSON.parse(text), file); }
+    catch (error) {
+      if (jsonLabel) throw new Error(`Invalid ${jsonLabel}: expected a JSON object.`);
+      throw error;
+    }
+    return { file, text, value, ...(jsonLabel ? { jsonLabel } : {}), mode: opened.mode & 0o777, dev: opened.dev, ino: opened.ino };
   } finally { fs.closeSync(descriptor); }
 }
 
@@ -79,7 +85,7 @@ function changed(original, value) {
   return { ...original, next: text };
 }
 
-export function planAntigravityInstallation({ home = homeDir(), codeConfigDir = process.env.CLAUDE_CONFIG_DIR || home, root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, setup = false, codexExisting = null } = {}) {
+export function planAntigravityInstallation({ home = homeDir(), codeConfigDir = process.env.CLAUDE_CONFIG_DIR || home, root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."), node = stableNodeBin(), targets = ["codex", "claude", "desktop"], remove = false, setup = false, codexExisting = null, platform = process.platform, appData = process.env.APPDATA } = {}) {
   if (!path.isAbsolute(home) || !path.isAbsolute(codeConfigDir) || !path.isAbsolute(root) || !path.isAbsolute(node)) throw new Error("Installer paths must be absolute");
   if (!targets.length || targets.some((target) => !["codex", "claude", "desktop"].includes(target))) throw new Error("Unknown installation target");
   const entry = path.join(root, "src", "antigravity-bridge.mjs");
@@ -87,6 +93,7 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
   const outboundEntry = path.join(root, "src", "antigravity-outbound-bridge.mjs");
   const edits = [];
   const notices = [];
+  let backgroundPreference = null;
   const retarget = setup && !remove;
   let codex = null;
   if (targets.includes("codex")) {
@@ -154,12 +161,30 @@ export function planAntigravityInstallation({ home = homeDir(), codeConfigDir =
     const configEdit = changed(originalConfig, config);
     if (sidecarEdit) edits.push(sidecarEdit);
     if (configEdit) edits.push(configEdit);
+    if (setup && !remove) {
+      backgroundPreference = { setting: "runInBackground", status: "unavailable", liveVerified: false };
+      if (platform !== "win32") {
+        backgroundPreference.detail = "Automatic Antigravity background preferences are not verified on this platform; native settings were preserved.";
+      } else if (typeof appData !== "string" || !path.isAbsolute(appData)) {
+        backgroundPreference.detail = "Antigravity background preferences were not applied because an absolute APPDATA path is unavailable.";
+      } else {
+        const storage = snapshot(path.join(appData, "Antigravity", "app_storage.json"), "Antigravity native preferences");
+        if (storage.text === null) {
+          backgroundPreference.detail = "Antigravity app_storage.json was not found; no native preferences file was created and background operation is unverified.";
+        } else {
+          const storageEdit = changed(storage, { ...storage.value, runInBackground: "true" });
+          if (storageEdit) edits.push(storageEdit);
+          backgroundPreference.status = storageEdit ? "planned" : "configured";
+        }
+      }
+      if (backgroundPreference.detail) notices.push(backgroundPreference.detail);
+    }
   }
-  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry };
+  return { name: NAME, targets: [...new Set(targets)], remove, edits, notices, codex, entry, sidecarEntry, outboundEntry, backgroundPreference };
 }
 
 function assertCurrent(edit) {
-  const current = snapshot(edit.file);
+  const current = snapshot(edit.file, edit.jsonLabel);
   if (current.text !== edit.text || current.dev !== edit.dev || current.ino !== edit.ino) throw new Error(`Configuration changed while preparing installation: ${edit.file}`);
 }
 
@@ -180,11 +205,11 @@ export function applyJsonEdits(edits) {
         } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
       }
       completed.push(edit);
-      if (snapshot(edit.file).text !== edit.next) throw new Error(`Configuration readback did not match the saved update: ${edit.file}`);
+      if (snapshot(edit.file, edit.jsonLabel).text !== edit.next) throw new Error(`Configuration readback did not match the saved update: ${edit.file}`);
     }
   } catch (error) {
     for (const edit of completed.reverse()) {
-      if (snapshot(edit.file).text !== edit.next) continue;
+      if (snapshot(edit.file, edit.jsonLabel).text !== edit.next) continue;
       if (edit.text === null) fs.unlinkSync(edit.file);
       else fs.writeFileSync(edit.file, edit.text, { mode: edit.mode ?? 0o600 });
     }
@@ -224,7 +249,7 @@ export function runAntigravityInstaller(args = process.argv.slice(2)) {
     }
   }
   if (options.dryRun) {
-    console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
+    console.log(JSON.stringify({ dryRun: true, remove: plan.remove, targets: plan.targets, files: plan.edits.map((edit) => ({ path: edit.file, action: edit.next === null ? "remove" : "write" })), notices: plan.notices, backgroundPreference: plan.backgroundPreference, codex: plan.codex ? { name: NAME, action: options.remove ? "remove" : "register" } : null }, null, 2));
     return plan;
   }
   for (const edit of plan.edits) assertCurrent(edit);
@@ -233,10 +258,15 @@ export function runAntigravityInstaller(args = process.argv.slice(2)) {
     else applyStdioMcpRegistration({ name: NAME, registration: plan.codex, existing: codexExisting, run, configPath: path.join(process.env.CODEX_HOME ?? path.join(home, ".codex"), "config.toml") });
   }
   applyJsonEdits(plan.edits);
+  if (plan.backgroundPreference?.status === "planned") plan.backgroundPreference.status = "configured";
+  if (options.setup) {
+    console.log(JSON.stringify({ action: options.remove ? "remove" : "install", targets: plan.targets, configured: true, liveVerified: false,
+      changedFiles: plan.edits.length, notices: plan.notices, backgroundPreference: plan.backgroundPreference }));
+    return plan;
+  }
   console.log(`${options.remove ? "Removed" : "Installed"} Antigravity bridge: ${plan.targets.join(", ")}.`);
   for (const notice of plan.notices) console.log(notice);
-  if (!options.remove && options.targets.includes("desktop")) console.log("In Antigravity Customizations > Installed, find agent-bridge and choose More actions > Restart. If it is absent, reopen the App to load its new registration. In the CLI, use /mcp to reload server configurations.");
-  if (!options.remove) console.log("Reload the selected clients to load the bridge. Antigravity Desktop must launch its sidecar; installation alone does not prove a live connection. Native permissions were preserved.");
+  if (!options.remove) console.log("Bridge configuration saved; running clients and native permissions were preserved. Installation does not prove a live connection or load new settings into existing processes. This installer does not start apps or open conversations.");
   return plan;
 }
 

package/scripts/install-claude-code.mjs

@@ -68,7 +68,7 @@ try {
   if (args.includes("--install")) {
     if (args.includes("--check") || args.includes("--apply")) throw new Error("Use --install separately from --check or --apply");
     const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
-    const plan = planInitialCodeRegistration({ code, desktop, root, node: stableNodeBin(), environment: process.env });
+    const plan = planInitialCodeRegistration({ code, desktop, root, node: stableNodeBin(), environment: process.env, setup: args.includes("--setup") });
     const dryRun = args.includes("--dry-run");
     const writtenFiles = dryRun ? 0 : apply(plan);
     console.log(JSON.stringify({ action: dryRun ? "plan" : "install", configured: !dryRun, liveVerified: false,
@@ -86,7 +86,7 @@ try {
     if (args.includes("--apply")) {
       if (!args.includes("--clients-stopped")) throw new Error("Exit Claude and the configuration manager first, then pass --clients-stopped to avoid their overwriting the migration");
       apply(plan);
-      console.log("Reopen the original Code task and call codex_bridge_status with the intended project cwd. Update the configuration manager's matching entry to the same policy file. No new per-project MCP entry is needed.");
+      console.log("Shared policy migration applied. Loaded Code registrations have not been verified; codex_bridge_status reports the active configuration. The configuration manager's matching entry must use the same policy file.");
     }
   }
 } catch (error) { console.error(error.message); process.exitCode = 1; }

package/scripts/install-claude-desktop.mjs

@@ -20,10 +20,11 @@ const entryOption = process.argv.indexOf("--entry-name");
 const requestedEntryName = entryOption < 0 ? undefined : process.argv[entryOption + 1];
 if (entryOption >= 0 && !["codex-bridge", "codex-bridge-desktop"].includes(requestedEntryName)) throw new Error("--entry-name must be codex-bridge or codex-bridge-desktop");
 const quiet = process.argv.includes("--quiet");
+const setup = process.argv.includes("--setup");
 const log = (...values) => { if (!quiet) console.log(...values); };
 const reset = process.argv.includes("--reset");
 const forceDesktopTasks = process.argv.includes("--desktop-tasks");
-const fullAccess = process.argv.includes("--full-access") || requestedEntryName === undefined && fullAccessEnabled();
+const fullAccess = process.argv.includes("--full-access") || !setup && requestedEntryName === undefined && fullAccessEnabled();
 
 /**
  * This bridge is intentionally the local hand-off point between Claude and
@@ -80,6 +81,7 @@ const original = readConfig();
 const cfg = original ? JSON.parse(original.data.toString("utf8")) : {};
 if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) throw new Error("Desktop configuration must be a JSON object");
 if (cfg.mcpServers !== undefined && (!cfg.mcpServers || typeof cfg.mcpServers !== "object" || Array.isArray(cfg.mcpServers))) throw new Error("Desktop mcpServers must be a JSON object");
+if (setup && cfg.preferences !== undefined && (!cfg.preferences || typeof cfg.preferences !== "object" || Array.isArray(cfg.preferences))) throw new Error("Desktop preferences must be a JSON object");
 cfg.mcpServers = cfg.mcpServers ?? {};
 
 /**
@@ -108,7 +110,7 @@ if (bridgeEntries.length > 1 || requestedEntryName && bridgeEntries.some((name)
   throw new Error(`Claude Desktop already has several bridge entries (${bridgeEntries.join(", ")}); remove all but one and re-run. No configuration was changed.`);
 }
 const entryName = requestedEntryName ?? bridgeEntries[0] ?? "codex-bridge";
-if (requestedEntryName && cfg.mcpServers[entryName] !== undefined) {
+if ((requestedEntryName || setup) && cfg.mcpServers[entryName] !== undefined) {
   const existing = cfg.mcpServers[entryName];
   const script = existing?.args?.[0];
   const source = typeof script === "string" && path.isAbsolute(script) ? path.dirname(script) : null;
@@ -133,6 +135,7 @@ const desktopEnabled = desktopMode === undefined ? desktopTasksConfigured() : de
 
 const kept = Object.keys(previousEnv).filter(
   (name) => process.env[name] === undefined && name !== "CODEX_BIN" &&
+    !(setup && name === "CODEX_BRIDGE_OPEN_IN_APP") &&
     !(forceDesktopTasks && name === "CODEX_BRIDGE_DESKTOP_TASKS") &&
     !(desktopEnabled && name === "CODEX_BRIDGE_AUTOSTART"),
 );
@@ -168,7 +171,7 @@ cfg.mcpServers[entryName] = {
      */
     CODEX_BRIDGE_THREAD_POLICY: settled("CODEX_BRIDGE_THREAD_POLICY", "roots"),
     CODEX_BRIDGE_SANDBOX: fullAccess ? "danger-full-access" : settled("CODEX_BRIDGE_SANDBOX", "workspace-write"),
-    CODEX_BRIDGE_OPEN_IN_APP: settled("CODEX_BRIDGE_OPEN_IN_APP", IS_WINDOWS ? "1" : "0"),
+    CODEX_BRIDGE_OPEN_IN_APP: setup ? "0" : settled("CODEX_BRIDGE_OPEN_IN_APP", "0"),
     CODEX_BRIDGE_RELEASE_AFTER_TURN: settled("CODEX_BRIDGE_RELEASE_AFTER_TURN", IS_WINDOWS ? "1" : "0"),
     ...(desktopMode !== undefined ? { CODEX_BRIDGE_DESKTOP_TASKS: desktopMode } : {}),
     CODEX_BRIDGE_AUTOSTART: desktopEnabled ? "0" : settled("CODEX_BRIDGE_AUTOSTART", "1"),
@@ -185,6 +188,7 @@ cfg.mcpServers[entryName] = {
       : {}),
   },
 };
+if (setup) cfg.preferences = { ...cfg.preferences, menuBarEnabled: true };
 
 createReleaseSnapshot(root, { cache: snapshotRoot({ ...process.env, ...cfg.mcpServers[entryName].env }) });
 
@@ -255,7 +259,8 @@ if (entryName === "codex-bridge") {
   }
 }
 
-log(`\nReconnect ${entryName} once in the existing Claude task to load the supervisor. Subsequent compatible installed-source updates reload automatically when the worker is safely idle.`);
-log("Verify codex_bridge_status from that task: autoReload must be enabled and runtime state must be current. A separate diagnostic process does not verify the app's loaded MCP process.");
-if (desktopEnabled) log("Verify Desktop tasks are enabled and the native relay is available. Configuration changes require MCP reconnect even when source auto-reload is enabled; keep the destination task open in Codex Desktop.");
-if (quiet) console.log(JSON.stringify({ action: "install", entry: entryName, configured: true, liveVerified: false, changed, restartRequired: changed, desktopTasks: desktopEnabled }));
+log(`\nConfiguration saved for ${entryName}. Running MCP processes were not restarted and may still hold earlier settings.`);
+log("An existing compatible supervisor reloads installed source when the worker is safely idle. codex_bridge_status reports the loaded process; a separate diagnostic process cannot verify it.");
+if (desktopEnabled) log("Native delivery requires a loaded Desktop-owned relay. This installer does not start apps or open conversations, and saved configuration does not prove live readiness.");
+if (quiet) console.log(JSON.stringify({ action: "install", entry: entryName, configured: true, liveVerified: false, changed, restartRequired: changed, desktopTasks: desktopEnabled,
+  ...(setup ? { backgroundPreference: { setting: "preferences.menuBarEnabled", status: "configured", liveVerified: false } } : {}) }));

package/scripts/install-native-relay.mjs

@@ -25,7 +25,7 @@ import { removeRelayFile } from "../src/native-relay-files.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.25.2";
+const VERSION = "1.25.3";
 const root = stableInstallPath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."));
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];
@@ -136,5 +136,5 @@ if (process.argv.includes("--desktop-tasks")) {
   writeRelayConfig({ ...readRelayConfig(), desktopTasks: true });
   console.log("Desktop task creation enabled: exact saved local projects, immediate visibility, Codex Desktop permissions.");
 }
-console.log("One-time step: after active Codex work finishes, quit and reopen Codex Desktop once so it starts the supervisor. Then call native_relay_status in an existing task: it must report \"automatic reload: current\" with a supervisor pid. Later compatible installed updates reload automatically when the relay is idle.");
+console.log("Native relay configuration saved. Running MCP processes were not restarted; native_relay_status reports whether a Desktop-owned relay is loaded and current. Existing compatible supervisors reload installed source when idle, but saved configuration does not prove the running process has loaded new settings. This installer does not start Codex Desktop or open conversations.");
 console.log("remove: node scripts/install-native-relay.mjs --remove");

package/scripts/setup.mjs

@@ -6,9 +6,9 @@ exitForVersionRequest(import.meta.url);
 try {
   const result = runSetup({ args: process.argv.slice(2) });
   printSetup(result, { json: process.argv.includes("--json") });
-  if (result.configured === false && !result.dryRun && !process.argv.includes("--postinstall")) process.exitCode = 1;
+  if (result.configured === false && !result.dryRun) process.exitCode = 1;
 } catch (error) {
   process.stderr.write(`Bridge setup: ${error.message}\n`);
-  process.stderr.write("Run codex-bridge-setup to retry configuration; the installed package is retained.\n");
-  if (!process.argv.includes("--postinstall")) process.exitCode = 1;
+  process.stderr.write("Bridge configuration was not completed. Run codex-bridge-setup to retry after resolving the reported error.\n");
+  process.exitCode = 1;
 }