@minhspark/codex-mcp-bridge 1.26.0 → 1.26.2

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,43 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.26.2] - 2026-11-01
+
+### Upgrade
+
+Install or update the global package and all managed client and background-service settings with one command, including upgrades from 1.26.0 or 1.26.1:
+
+```sh
+npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
+```
+
+Use `npm.cmd` in Windows PowerShell. npm downloads the latest updater without running setup in its cache; the updater installs that exact resolved version globally with managed setup enabled and verifies the global installation. No second installation command is required.
+
+### Added
+
+- Automatic `codex-bridge-update` orchestration for package replacement, all managed client settings and background-service configuration. Before replacing a Windows installation held by an owned legacy relay, it moves only that service to newer code using private relay storage as its working directory, waits for work to drain and verifies replacement readiness. The temporary runtime points to the downloaded updater package. It reports a pending migration instead of killing processes or interrupting jobs.
+- Preserve disabled services, provider authentication, custom project grants and permission denials throughout the update. Setup does not open apps or chats, and a deliberately disabled service is not reported as ready.
+
+### Fixed
+
+- New background service and daemon launches use private relay storage as their working directory instead of the npm installation directory, preventing those processes from locking the package on Windows. The updater migrates owned legacy instances before package replacement. Worker jobs continue using their explicitly authorized project directories.
+
+## [1.26.1] - 2026-11-01
+
+### Upgrade
+
+Update the package and reapply all managed client and background-service settings with the same command:
+
+```sh
+npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+```
+
+Use `npm.cmd` in Windows PowerShell. Setup does not open apps or chats.
+
+### Fixed
+
+- Read-only background-service checks validate the installed runtime environment. A normal terminal no longer reports a healthy service as unconfigured merely because npm added temporary entries to `PATH` during installation. Package, startup ownership and running-runtime identity checks remain in place.
+
 ## [1.26.0] - 2026-11-01
 
 ### Upgrade

package/README.md

@@ -23,23 +23,27 @@ https://github.com/user-attachments/assets/98b23989-826f-4d7d-9dcb-ad7dd2739095
 
 ## Installation
 
-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.
+One npm command installs or updates the global package, applies all managed Claude, Codex and Antigravity settings, and configures 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 --foreground-scripts
+npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
 **Windows PowerShell**
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+npm.cmd exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
-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.
+Requires **Node.js 22.13+**. Use `.cmd` for this package's commands in Windows PowerShell. **Use this same single command for a fresh install and every update**, including upgrades from 1.26.0 or 1.26.1. npm fetches the latest updater into its cache without running setup there. The updater installs that exact resolved version globally, runs the managed setup hook, and verifies the global version, saved settings and service activation separately. A second installation command is not required.
+
+For an enabled legacy Windows relay from 1.26.0 or 1.26.1, the updater moves only this package's owned service to newer code using private relay storage as its working directory before replacing the global package. The temporary service runtime points to the downloaded updater package; changing the working directory releases the old package lock. It waits for active work to drain and the replacement transport to become ready without killing processes or opening apps or chats. If migration is still pending after its bounded wait, it reports `UPDATE_RELAY_PENDING`; keep the existing jobs and receipts and rerun the same command after they finish. Intentionally disabled services stay disabled and are not reported as ready.
+
+Managed 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.
 
 ### Independent background workers
 
@@ -61,7 +65,7 @@ Keep the same request UUID for retries and read its durable receipt. Queued work
 
 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.
+The recommended command's `--ignore-scripts` applies only to downloading the updater into npm's cache. The updater explicitly enables this package's setup hook for the global installation and displays its progress. This avoids client MCP registrations pointing into a temporary npm cache directory. A direct global npm install remains an advanced alternative, but it skips the updater's migration of an old service that can lock the package on Windows.
 
 | Client | Installed entry | Purpose |
 | --- | --- | --- |
@@ -75,11 +79,11 @@ Worker delegation is bounded. `WORKER_DELEGATION_CAPACITY` means the destination
 
 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.
+Automatic setup runs during the updater's **global npm installation**. Local `npm install` and `npm ci` do not change app settings. For a deliberate package-only installation, use a direct global npm install with `CODEX_BRIDGE_SKIP_SETUP=1` or `--ignore-scripts`; that opt-out is separate from the cache-only `--ignore-scripts` in the recommended updater command. 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, 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:
+If service migration, installation or managed setup fails, the updater returns a nonzero exit and reports the failed step. Inspect that component and the installed version, correct the reported cause, and rerun the same update command above. npm can roll back package files while settings already written remain changed. For configuration-only repair of an already installed package, the following is an optional alternative:
 
 ```bash
 codex-bridge-setup
@@ -545,12 +549,12 @@ 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 --foreground-scripts
+npm.cmd exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
-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.
+This runs the latest updater outside the global package directory, handles an owned legacy service that can lock that directory, and installs the exact resolved package with its setup hook enabled. `--ignore-scripts` suppresses setup only for the temporary cached updater. If a previous direct install printed `1 package had install scripts blocked`, use this same updater command to install and apply the managed settings together. Intentional setup opt-outs and disabled-service choices are not silently removed.
 
-For an already-installed package, preview and apply setup explicitly:
+For an already-installed package, these optional commands preview or repair configuration without updating package files:
 
 ```powershell
 codex-bridge-setup.cmd --dry-run
@@ -558,7 +562,7 @@ codex-bridge-setup.cmd
 codex-bridge-setup.cmd --check
 ```
 
-`--dry-run` does not write settings or download tools. Setup resolves an existing Codex CLI or installs its managed official copy; `--no-download` requires one to be available already. A failed postinstall configuration step retains the npm package so it can be repaired. Explicit setup and `--check` return a nonzero exit code for incomplete configuration. Read the named component's error; running the same command cannot resolve a deliberate opt-out or an unrelated conflicting registration.
+`--dry-run` does not write settings or download tools. Setup resolves an existing Codex CLI or installs its managed official copy; `--no-download` requires one to be available already. Failed setup or update returns a nonzero exit; inspect the reported component and installed version, correct the cause, then rerun the same updater command. Package rollback does not guarantee that settings or command shims return to their previous state. Explicit setup and `--check` also return a nonzero exit code for incomplete configuration. Running the same command cannot resolve a deliberate opt-out or an unrelated conflicting registration.
 
 ### Missing module, stale source path, or a different running version
 

package/docs/new-macos-setup.md

@@ -12,26 +12,28 @@ 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:
+Use the same command for a fresh installation and every update:
 
 ```bash
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
-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. `--foreground-scripts` displays setup progress.
-If npm reports `1 package had install scripts blocked`, rerun the command above
-or run `codex-bridge-setup` explicitly.
+npm downloads the latest updater into its cache. `--ignore-scripts` suppresses
+setup only in that temporary location. The updater installs its exact resolved
+version globally, enables this package's managed setup hook, displays progress
+and verifies the global version and configuration. No second installation or
+setup command is required. Existing disabled choices, authentication and custom
+project grants are preserved; the updater does not open apps or chats or kill
+processes. A pending service migration is reported instead of interrupting work.
 
 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 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.
+If setup or update exits nonzero, inspect the reported component and installed
+version, correct the cause, and rerun the same updater command. npm can roll back
+package files without restoring settings already written or command shims.
 
 The command also installs an independent per-user LaunchAgent for separate
 Claude, Codex and Antigravity CLI workers and updates its managed settings on
@@ -89,6 +91,7 @@ codex-bridge-setup --dry-run
 codex-bridge-setup
 ```
 
+These are optional configuration-only checks and repairs after installation.
 `--check` inspects registrations; `--dry-run` previews components and paths
 without downloads or writes; the plain command applies setup again. Add
 `--json` for structured output or `--no-download` to require an existing Codex
@@ -96,10 +99,12 @@ CLI. `codex-mcp-bridge setup` runs the same setup. An incomplete result identifi
 the component to correct before rerunning. Explicit setup and `--check` return
 a nonzero exit status while configuration is incomplete.
 
-Local `npm install` and `npm ci` do not change app settings. Set
-`CODEX_BRIDGE_SKIP_SETUP=1` or use `--ignore-scripts` to skip setup during a
-global install. For Homebrew, run `codex-bridge-setup` after installing the
-formula. A pinned source checkout can use `node scripts/setup.mjs`.
+Local `npm install` and `npm ci` do not change app settings. For a deliberate
+package-only installation, a direct global npm install can use
+`CODEX_BRIDGE_SKIP_SETUP=1` or `--ignore-scripts`; this differs from the cache-only
+script suppression in the recommended updater command. For Homebrew, run
+`codex-bridge-setup` after installing the formula. A pinned source checkout can
+use `node scripts/setup.mjs`.
 
 The [manual macOS commands](../README.md#macos-terminal) and
 [Claude Code registration commands](../README.md#register-claude-code) remain

package/docs/new-windows-setup.md

@@ -3,25 +3,38 @@
 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:
+does not require the Desktop apps to be open. Use this one PowerShell command
+for a fresh installation or an update, including from 1.26.0 or 1.26.1:
 
 ```powershell
-npm.cmd install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+npm.cmd exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
-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. `--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.
+npm downloads the latest updater into its cache. `--ignore-scripts` prevents
+setup from running in that temporary location; the updater then installs its
+exact resolved version globally with this package's managed setup hook enabled.
+It displays progress and verifies the global version and saved settings.
+No second installation or setup command is required.
+
+An older Windows background service can keep the global npm package directory
+locked as its working directory. Before replacing the package, the updater
+moves only this package's owned legacy service to newer code using private relay
+storage as its working directory when needed. The temporary runtime points to
+the downloaded updater package. It waits for active work to drain and the
+replacement transport to become ready, without killing processes or opening
+apps or chats. If that migration
+remains pending, `UPDATE_RELAY_PENDING` leaves jobs and receipts intact; rerun
+the same command after the active work finishes. Deliberately disabled services
+remain disabled and are not reported as ready.
 
 The global installation configures the bridges and verifies their saved
 registrations. It reuses an available native Codex CLI, or installs a pinned
 official package in the current user's `.config\GptClaudeBridge\tools`
 directory. It also configures native pipe forwarding and bootstraps the relay
-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.
+executor. A failed component is reported as incomplete rather than ready. If
+setup or update exits nonzero, inspect the reported component and installed
+version, correct the cause, and rerun the same updater command. npm can roll back
+package files without restoring settings already written or command shims.
 
 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
@@ -78,6 +91,7 @@ codex-bridge-setup.cmd --dry-run
 codex-bridge-setup.cmd
 ```
 
+These are optional configuration-only checks and repairs after installation.
 The first command inspects configuration; the second previews components and
 paths without writes or downloads; the third applies setup again. Add `--json`
 for structured output or `--no-download` to require an existing Codex CLI.
@@ -87,8 +101,12 @@ incomplete.
 has no bridge tools, inspect and reconnect `codex-bridge` using `/mcp` before
 attempting delivery.
 
-Local `npm install` and `npm ci` do not configure apps. To opt out during a
-global install, set `CODEX_BRIDGE_SKIP_SETUP=1` or use `--ignore-scripts`.
+Local `npm install` and `npm ci` do not configure apps. For a deliberate
+package-only installation, a direct global npm install can use
+`CODEX_BRIDGE_SKIP_SETUP=1` or `--ignore-scripts`. This differs from the
+recommended updater command, which suppresses setup only in its temporary cache
+and enables it for the final global installation. A direct install skips the
+updater's migration of legacy Windows services that can lock the package.
 The optional card extension, hosted ChatGPT pairing, and VS Code preview have
 separate installation steps.
 

package/docs/project-onboarding.md

@@ -1,18 +1,20 @@
 # Project onboarding and shared authorization
 
-The recommended global installation registers the bridges and configures the
-independent worker relay automatically:
+One command installs or updates the global package, registers the bridges and
+configures the independent worker relay automatically:
 
 ```sh
-npm install -g @minhspark/codex-mcp-bridge@latest --allow-scripts=@minhspark/codex-mcp-bridge --foreground-scripts
+npm exec --yes --ignore-scripts --package=@minhspark/codex-mcp-bridge@latest -- codex-bridge-update
 ```
 
-In Windows PowerShell use `npm.cmd`. The script allowance authorizes only this
-package's setup hook; npm versions that block install scripts by default need
-it. A plain install runs setup only when the hook is allowed.
-`--foreground-scripts` displays progress. If npm prints
-`1 package had install scripts blocked`, rerun the recommended command or run
-`codex-bridge-setup` explicitly. The setup creates
+In Windows PowerShell use `npm.cmd`. npm fetches the latest updater into its
+cache with setup disabled there. The updater moves an owned legacy service to
+newer code using private relay storage as its working directory when needed,
+temporarily using the downloaded updater package. It waits for active work to
+drain, then installs its exact resolved version globally with the setup hook
+enabled. It verifies the global installation and managed settings. No second
+installation command is required. It does not open apps or chats or kill
+processes. The setup creates
 `codex-bridge` for Claude Code and the separate `codex-bridge-desktop` shared
 Claude connector, configures Codex and Antigravity, and initializes the native
 relay on Windows/macOS. It also installs the per-user background service and
@@ -32,11 +34,15 @@ display results. Use a terminal or another responsive client, subject to the
 `codex-bridge-setup --check` inspects all saved registrations. Use
 `codex-bridge-setup --dry-run` to preview or rerun `codex-bridge-setup` to apply
 setup after correcting an incomplete component. Add `.cmd` on Windows and
-`--json` for structured output. Local package installs do not run setup;
-`CODEX_BRIDGE_SKIP_SETUP=1` and npm `--ignore-scripts` opt out of global setup.
-If app configuration is incomplete, npm retains the package for repair; its
-success exit alone does not verify setup. Explicit setup and `--check` return
-a nonzero status until the saved configuration passes verification.
+`--json` for structured output. Local package installs do not run setup.
+For a deliberate package-only direct global installation,
+`CODEX_BRIDGE_SKIP_SETUP=1` or npm `--ignore-scripts` opts out of setup; this is
+separate from the cache-only script suppression in the recommended updater.
+Failed setup or update returns a nonzero exit. Inspect the reported component
+and installed version, correct the cause, then rerun the same updater command.
+npm can roll back package files without restoring settings or command shims.
+Explicit setup and `--check` also return a nonzero status until the saved
+configuration passes verification.
 
 ## Shared project policy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.26.0",
+  "version": "1.26.2",
   "description": "Connect Claude, Codex, and Antigravity through MCP, with native Desktop handoffs and bridge-owned Antigravity CLI sessions.",
   "keywords": [
     "mcp",
@@ -30,6 +30,7 @@
     "codex-mcp-bridge-install": "scripts/install-claude-desktop.mjs",
     "codex-bridge-code-install": "scripts/install-claude-code.mjs",
     "codex-bridge-setup": "scripts/setup.mjs",
+    "codex-bridge-update": "scripts/update.mjs",
     "worker-relay": "scripts/worker-relay.mjs",
     "bridge-projects": "scripts/bridge-projects.mjs",
     "claude-mcp-bridge-install": "scripts/install-codex-mcp.mjs",

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.26.0",
+  "version": "1.26.2",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/background-relay-hidden.vbs

@@ -8,4 +8,5 @@ relayService = WScript.Arguments(1)
 If InStr(relayNode, Chr(34)) > 0 Or InStr(relayNode, "%") > 0 Then WScript.Quit 2
 If InStr(relayService, Chr(34)) > 0 Or InStr(relayService, "%") > 0 Then WScript.Quit 2
 relayEnvironment("AGENT_RELAY_DIRECTORY") = WScript.Arguments(2)
+relayShell.CurrentDirectory = WScript.Arguments(2)
 WScript.Quit relayShell.Run(Chr(34) & relayNode & Chr(34) & " " & Chr(34) & relayService & Chr(34), 0, True)

package/scripts/install-background-relay.mjs

@@ -12,6 +12,7 @@ import { isMainModule, stableNodeBin } from "../src/install-paths.mjs";
 import { readRegularConfigFile } from "../src/project-policy.mjs";
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const RUNTIME_ENVIRONMENT_KEYS = ["HOME", "PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME"];
 const TASK_SCRIPT = String.raw`$ErrorActionPreference = 'Stop'
 $relayRequest = [Console]::In.ReadToEnd() | ConvertFrom-Json
 try {
@@ -178,7 +179,7 @@ function taskXml({ command, args, user, enabled }) {
 
 function savedEnvironment(env, config) {
   const result = { AGENT_RELAY_DIRECTORY: config.paths.root, AGENT_RELAY_SERVICE_OWNER: RELAY_SERVICE_OWNER };
-  for (const name of ["HOME", "PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME"]) {
+  for (const name of RUNTIME_ENVIRONMENT_KEYS) {
     if (typeof env[name] === "string" && env[name] && !/[\u0000-\u001f\u007f]/.test(env[name])) result[name] = env[name];
   }
   return result;
@@ -359,25 +360,33 @@ export async function installBackgroundRelay({ env = process.env, platform = pro
       return { status: result?.status ?? result?.exitCode ?? 0, stdout: String(result?.stdout ?? "") };
     };
     const runtimeFile = path.join(config.paths.root, "service-runtime.json");
-    const desiredRuntime = { schemaVersion: 1, owner: RELAY_SERVICE_OWNER, packageRoot: root, nodeExecutable: node, packageVersion,
-      environment: Object.fromEntries(Object.entries(savedEnvironment(env, config)).filter(([name]) => !name.startsWith("AGENT_RELAY_"))) };
-    const expectedRuntimeId = relayServiceRuntimeId(desiredRuntime);
     const readRuntime = () => {
       const raw = readRegularConfigFile(runtimeFile, { missing: true, maxBytes: 64 * 1024 });
       if (raw === null) return null;
       let value;
       try { value = JSON.parse(raw); } catch { throw installFailure("SERVICE_RUNTIME_INVALID"); }
       if (value?.schemaVersion !== 1 || value.owner !== RELAY_SERVICE_OWNER) throw installFailure("SERVICE_CONFIGURATION_CONFLICT");
+      if (value.environment !== undefined && (!value.environment || typeof value.environment !== "object" || Array.isArray(value.environment)
+          || Object.entries(value.environment).some(([name, entry]) => !RUNTIME_ENVIRONMENT_KEYS.includes(name)
+            || typeof entry !== "string" || !entry || /[\u0000-\u001f\u007f]/.test(entry)))) throw installFailure("SERVICE_RUNTIME_INVALID");
       return value;
     };
     const previousRuntime = readRuntime();
+    const installedEnv = check && previousRuntime ? {
+      ...Object.fromEntries(Object.entries(env).filter(([name]) => !RUNTIME_ENVIRONMENT_KEYS.includes(name))),
+      ...previousRuntime.environment,
+    } : env;
+    const desiredRuntime = { schemaVersion: 1, owner: RELAY_SERVICE_OWNER, packageRoot: root, nodeExecutable: node, packageVersion,
+      environment: check && previousRuntime ? previousRuntime.environment ?? {}
+        : Object.fromEntries(Object.entries(savedEnvironment(env, config)).filter(([name]) => !name.startsWith("AGENT_RELAY_"))) };
+    const expectedRuntimeId = relayServiceRuntimeId(desiredRuntime);
     const runtimeChanged = JSON.stringify(previousRuntime) !== JSON.stringify(desiredRuntime);
     const prepareRuntime = async () => {
       if (JSON.stringify(readRuntime()) !== JSON.stringify(previousRuntime)) throw installFailure("SERVICE_CONFIGURATION_CHANGED");
       if (runtimeChanged) writeRelayJson(runtimeFile, desiredRuntime);
       if (JSON.stringify(readRuntime()) !== JSON.stringify(desiredRuntime)) throw installFailure("SERVICE_READBACK_FAILED");
     };
-    const context = { env, config, root, node, service, label, invoke, mutate: !dryRun && !check, uid, nativeRun: run === execute, prepareRuntime };
+    const context = { env: installedEnv, config, root, node, service, label, invoke, mutate: !dryRun && !check, uid, nativeRun: run === execute, prepareRuntime };
     const installed = await ({ win32: installWindows, darwin: installMac, linux: installLinux })[platform](context);
     installed.configured = installed.configured && JSON.stringify(readRuntime()) === JSON.stringify(desiredRuntime);
     const result = { ...base, ...installed, dryRun, deliveryEnabled: installed.enabled, 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.26.0";
+const VERSION = "1.26.2";
 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"];

package/scripts/update.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { installBackgroundRelay } from "./install-background-relay.mjs";
+import { readRelayConfiguration } from "../src/background-relay-config.mjs";
+import { readRelayServiceRuntime, RELAY_SERVICE_OWNER } from "../src/background-relay-service.mjs";
+import { assertPrivateRelayFile } from "../src/background-relay-storage.mjs";
+import { isMainModule } from "../src/install-paths.mjs";
+import { readRegularConfigFile } from "../src/project-policy.mjs";
+import { exitForVersionRequest } from "../src/cli-version.mjs";
+import { bridgeDiagnostic, withBridgeDiagnostic } from "../src/recipient-preflight.mjs";
+
+const PACKAGE = "@minhspark/codex-mcp-bridge";
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MANAGED_ENV = new Set(["HOME", "PATH", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "XDG_CONFIG_HOME"]);
+const RETRY = "Run the same codex-bridge-update command again after inspecting this report. Existing work and receipts were preserved.";
+const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+function failure(code, message, phase, cause) {
+  return Object.assign(new Error(message), { code, phase, deliveryState: "not_applicable", ...(cause ? { cause } : {}) });
+}
+
+function packageVersion(root, missing = false) {
+  const raw = readRegularConfigFile(path.join(root, "package.json"), { missing, maxBytes: 128 * 1024 });
+  if (raw === null) return null;
+  let value;
+  try { value = JSON.parse(raw); } catch {}
+  if (value?.name !== PACKAGE || typeof value.version !== "string" || value.version.length > 96 || !/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.+-]+)?$/.test(value.version)) {
+    throw failure("UPDATE_PACKAGE_INVALID", "The bridge package identity or version could not be verified.", "preflight");
+  }
+  return value.version;
+}
+
+function newerVersion(left, right) {
+  const split = value => { const [core, ...suffix] = value.split("+")[0].split("-"); return { core: core.split(".").map(BigInt), suffix: suffix.join("-") }; };
+  const a = split(left);
+  const b = split(right);
+  for (let index = 0; index < 3; index++) if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index];
+  if (!a.suffix || !b.suffix) return !a.suffix && Boolean(b.suffix);
+  const parts = [a.suffix.split("."), b.suffix.split(".")];
+  for (let index = 0; index < Math.max(...parts.map(part => part.length)); index++) {
+    const [x, y] = parts.map(part => part[index]);
+    if (x === y) continue;
+    if (x === undefined || y === undefined) return y === undefined;
+    const numeric = [x, y].map(value => /^\d+$/.test(value));
+    return numeric.every(Boolean) ? BigInt(x) > BigInt(y) : numeric[0] !== numeric[1] ? numeric[1] : x > y;
+  }
+  return false;
+}
+
+export function resolveUpdateNpm(env = process.env) {
+  for (const candidate of [env.npm_execpath, path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")]) {
+    try {
+      if (typeof candidate !== "string" || !path.isAbsolute(candidate)) continue;
+      const resolved = fs.realpathSync.native(candidate);
+      if (!/^(?:npm-cli|npm)\.js$/.test(path.basename(resolved)) || !fs.statSync(resolved).isFile()) continue;
+      const metadata = JSON.parse(readRegularConfigFile(path.resolve(path.dirname(resolved), "..", "package.json"), { maxBytes: 128 * 1024 }));
+      if (metadata.name === "npm") return resolved;
+    } catch {}
+  }
+  throw failure("UPDATE_NPM_NOT_FOUND", "A supported npm CLI could not be located. Run this updater through npm exec.", "preflight");
+}
+
+function execute(command, args, options) {
+  return new Promise(resolve => {
+    execFile(command, args, options, (error, stdout, stderr) => resolve({ status: error ? 1 : 0, error, stdout, stderr }));
+  });
+}
+
+function inside(directory, root) {
+  const relative = path.relative(root, directory);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function neutralDirectory(roots, env) {
+  for (const candidate of [os.tmpdir(), env.USERPROFILE, env.HOME, os.homedir()]) {
+    try {
+      if (typeof candidate !== "string" || !path.isAbsolute(candidate)) continue;
+      const directory = fs.realpathSync.native(candidate);
+      if (fs.statSync(directory).isDirectory() && roots.every(root => !inside(directory, root))) return directory;
+    } catch {}
+  }
+  throw failure("UPDATE_DIRECTORY_UNAVAILABLE", "No working directory outside the package installation is available.", "preflight");
+}
+
+function childFailure(result, phase) {
+  const match = /npm\s+(?:ERR!|error)\s+code\s+([A-Z][A-Z0-9_]{0,79})\b/.exec(String(result?.stderr ?? ""));
+  const code = match?.[1] ?? (/^[A-Z][A-Z0-9_]{0,79}$/.test(result?.error?.code ?? "") ? result.error.code : null);
+  const cause = code ? Object.assign(new Error("The child command reported a failure."), { code }) : undefined;
+  return failure(code === "EBUSY" ? "UPDATE_PACKAGE_BUSY" : phase === "verification" ? "UPDATE_SETUP_INCOMPLETE" : "UPDATE_NPM_FAILED",
+    code === "EBUSY" ? `The installed package is still held open by another process. No process was stopped. ${RETRY}`
+      : `The ${phase === "verification" ? "installed setup verification" : "npm command"} did not complete. ${RETRY}`, phase, cause);
+}
+
+function serviceQuiescent(config) {
+  for (const name of ["service.lock", "service-status.json"]) {
+    const file = path.join(config.paths.root, name);
+    if (!assertPrivateRelayFile(file, { missing: true })) continue;
+    let state;
+    try { state = JSON.parse(readRegularConfigFile(file, { maxBytes: 64 * 1024 })); } catch { return false; }
+    if (state?.schemaVersion !== 1 || state.owner !== RELAY_SERVICE_OWNER || !Number.isSafeInteger(state.pid) || state.pid < 1) return false;
+    if (state.status === "running" && (!Number.isSafeInteger(state.daemonPid) || state.daemonPid < 1)) return false;
+    for (const pid of [state.pid, state.daemonPid].filter(Number.isSafeInteger)) {
+      try { process.kill(pid, 0); return false; }
+      catch (error) { if (error.code !== "ESRCH") return false; }
+    }
+  }
+  return true;
+}
+
+export async function runUpdate({ args = [], env = process.env, platform = process.platform, root = ROOT, run = execute,
+  installService = installBackgroundRelay, readConfig = readRelayConfiguration, readRuntime = readRelayServiceRuntime,
+  quiescent = serviceQuiescent, now = Date.now, sleep = pause, waitMs = 120000, onProgress = () => {} } = {}) {
+  if (args.some(arg => !["--help", "--json"].includes(arg))) throw failure("UPDATE_ARGUMENT_INVALID", "Usage: codex-bridge-update [--json] [--help]", "preflight");
+  if (args.includes("--help")) return { help: "Usage: codex-bridge-update [--json]\nSafely update the global bridge and all managed settings. Legacy Windows relays migrate when existing work finishes; pending migrations can be retried with the same command." };
+  if (env.CODEX_BRIDGE_SKIP_SETUP === "1") throw failure("UPDATE_SETUP_DISABLED", "CODEX_BRIDGE_SKIP_SETUP=1 disables managed setup. Remove that explicit opt-out before requesting this complete update.", "preflight");
+  if (!Number.isSafeInteger(waitMs) || waitMs < 1 || waitMs > 600000) throw failure("UPDATE_ARGUMENT_INVALID", "The update readiness deadline is invalid.", "preflight");
+  root = fs.realpathSync.native(root);
+  const version = packageVersion(root);
+  const npm = resolveUpdateNpm(env);
+  let cwd = neutralDirectory([root], env);
+  let childEnv = Object.fromEntries(Object.entries(env).filter(([name]) => !/^AGENT_RELAY_(?!DIRECTORY$)/i.test(name)));
+  const command = async (arguments_, phase, timeout = 600000) => {
+    let result;
+    try {
+      result = await run(process.execPath, arguments_, { env: childEnv, cwd, encoding: "utf8", windowsHide: true,
+        shell: false, timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) { throw childFailure({ error, stderr: error.stderr }, phase); }
+    if (result?.error || (result?.status ?? result?.exitCode ?? 0) !== 0) throw childFailure(result, phase);
+    return String(result?.stdout ?? "");
+  };
+  const modules = (await command([npm, "root", "--global"], "preflight", 30000)).trim();
+  if (!path.isAbsolute(modules) || /[\u0000-\u001f\u007f]/.test(modules)) throw failure("UPDATE_GLOBAL_ROOT_INVALID", "npm returned an invalid global installation directory.", "preflight");
+  const prefix = (await command([npm, "prefix", "--global"], "preflight", 30000)).trim();
+  if (!path.isAbsolute(prefix) || /[\u0000-\u001f\u007f]/.test(prefix)
+      || path.relative(modules, path.join(prefix, ...(platform === "win32" ? [] : ["lib"]), "node_modules")) !== "") {
+    throw failure("UPDATE_GLOBAL_ROOT_INVALID", "npm returned inconsistent global prefix and installation directories.", "preflight");
+  }
+  const globalRoot = path.join(modules, "@minhspark", "codex-mcp-bridge");
+  cwd = neutralDirectory([root, globalRoot], env);
+  const previousVersion = packageVersion(globalRoot, true);
+  if (previousVersion && newerVersion(previousVersion, version)) throw failure("UPDATE_DOWNGRADE_REFUSED", "The global bridge is newer than this updater. Run the update command with the latest published package.", "preflight");
+  const config = readConfig({ env: childEnv, platform, missing: true });
+  let runtime;
+  if (config) {
+    runtime = readRuntime(config.paths.root, { root: globalRoot, nodeExecutable: process.execPath });
+    if (runtime.packageVersion && newerVersion(runtime.packageVersion, version)) throw failure("UPDATE_DOWNGRADE_REFUSED", "The owned relay runtime is newer than this updater. Run the update command with the latest published package.", "preflight");
+    if (runtime.environment !== undefined) childEnv = { ...Object.fromEntries(Object.entries(childEnv).filter(([name]) => !MANAGED_ENV.has(name.toUpperCase()))), ...runtime.environment };
+    childEnv.AGENT_RELAY_DIRECTORY = config.paths.root;
+  }
+  const awaitService = async (target, mutate, phase, expectedVersion = version) => {
+    const deadline = now() + waitMs;
+    let check = !mutate;
+    for (;;) {
+      const service = await installService({ env: childEnv, platform, root: target, check, pollAttempts: 1 });
+      check = true;
+      if (service.configured !== true) throw failure("UPDATE_SERVICE_UNVERIFIED", `The owned relay service could not be verified. ${RETRY}`, phase,
+        service.code ? Object.assign(new Error("The service installer reported a failure."), { code: service.code }) : undefined);
+      if (service.enabled === false) {
+        if (phase === "migration" && !quiescent(config)) throw Object.assign(failure("UPDATE_RELAY_PENDING", `The disabled relay still has an owned process whose release could not be verified. ${RETRY}`, phase), { pending: true });
+        return { enabled: false, ready: false, liveVerified: false };
+      }
+      if (service.enabled === true && service.liveVerified === true && service.ready === true && service.version === expectedVersion
+          && Number.isSafeInteger(service.pid) && service.pid > 0) return { enabled: true, ready: true, liveVerified: true, version: expectedVersion, pid: service.pid };
+      if (now() >= deadline) throw Object.assign(failure("UPDATE_RELAY_PENDING", `The relay is still completing its owned runtime transition. ${RETRY}`, phase), { pending: true });
+      await sleep(Math.min(1000, Math.max(1, deadline - now())));
+    }
+  };
+  let migrated = false;
+  const legacy = value => ["1.26.0", "1.26.1"].includes(value);
+  if (platform === "win32" && config && (legacy(previousVersion) || legacy(runtime.packageVersion))) {
+    if (config.enabled === false) {
+      if (!quiescent(config)) throw Object.assign(failure("UPDATE_RELAY_PENDING", `The disabled relay still has an owned process whose release could not be verified. ${RETRY}`, "migration"), { pending: true });
+    } else {
+      onProgress("Waiting for the legacy relay to finish existing work and activate the update runtime.");
+      const staged = runtime.packageVersion && !legacy(runtime.packageVersion) && !newerVersion("1.26.2", runtime.packageVersion);
+      const service = await awaitService(staged ? runtime.packageRoot : root, !staged, "migration", staged ? runtime.packageVersion : version);
+      migrated = !staged && service.enabled;
+    }
+  }
+  onProgress(`Installing bridge ${version} and applying managed settings.`);
+  await command([npm, "install", "--global", "--prefix", prefix, `${PACKAGE}@${version}`, "--ignore-scripts=false", `--allow-scripts=${PACKAGE}`, "--foreground-scripts"], "installation");
+  if (packageVersion(globalRoot) !== version) throw failure("UPDATE_VERSION_MISMATCH", "The global package version does not match the updater version. Rerun the same update command.", "verification");
+  onProgress("Verifying the global bridge settings and owned relay runtime.");
+  let setup;
+  try { setup = JSON.parse(await command([path.join(globalRoot, "scripts", "setup.mjs"), "--check", "--json"], "verification")); }
+  catch (error) { if (error?.code) throw error; throw failure("UPDATE_SETUP_INCOMPLETE", `Global setup did not return a verifiable result. ${RETRY}`, "verification"); }
+  if (setup?.configured !== true) throw failure("UPDATE_SETUP_INCOMPLETE", `The global bridge settings are incomplete. ${RETRY}`, "verification");
+  const service = await awaitService(globalRoot, false, "verification");
+  return { updated: true, configured: true, version, previousVersion, migrated, service, opensApps: false, opensChats: false };
+}
+
+if (isMainModule(process.argv[1], import.meta.url)) {
+  exitForVersionRequest(import.meta.url);
+  const args = process.argv.slice(2);
+  try {
+    process.chdir(neutralDirectory([ROOT], process.env));
+    const result = await runUpdate({ args, onProgress: message => process.stderr.write(`${message}\n`) });
+    process.stdout.write(result.help ? `${result.help}\n` : args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n`
+      : `Bridge ${result.version} updated; managed settings verified. Background relay ${result.service.ready ? "ready" : "remains intentionally disabled"}.\n`);
+  } catch (error) {
+    const options = { component: "bridge-update", operation: "update", deliveryState: "not_applicable" };
+    if (args.includes("--json")) process.stdout.write(JSON.stringify({ updated: false, pending: error.pending === true, diagnostic: bridgeDiagnostic(error, options) }, null, 2) + "\n");
+    else process.stderr.write(withBridgeDiagnostic({ isError: true, content: [] }, error, options).content.map(item => item.text ?? "").join("\n") + "\n");
+    process.exitCode = 1;
+  }
+}

package/src/background-relay-service.mjs

@@ -233,7 +233,7 @@ export async function runBackgroundRelayService({ env = process.env, platform =
         signal?.addEventListener("abort", stop, { once: true });
         try {
           child = spawn(runtime.nodeExecutable, [path.join(root, "src", "background-relay-daemon.mjs")], {
-            cwd: root, env: childEnv, windowsHide: true, shell: false, stdio: ["ignore", "ignore", "pipe"],
+            cwd: config.paths.root, env: childEnv, windowsHide: true, shell: false, stdio: ["ignore", "ignore", "pipe"],
           });
           child.stderr?.on("error", () => {});
           child.stderr?.on("data", captureDiagnostic);
@@ -291,6 +291,7 @@ if (!new URL(import.meta.url).search && isMainModule(process.argv[1], import.met
   process.on("SIGINT", stop);
   process.on("SIGTERM", stop);
   try {
+    process.chdir(readRelayConfiguration().paths.root);
     let run = runBackgroundRelayService;
     while (true) {
       const result = await run({ signal: controller.signal });

package/src/claude-bridge.mjs

@@ -31,7 +31,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.0";
+const VERSION = "1.26.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/index.mjs

@@ -44,7 +44,7 @@ import { BACKGROUND_WORKER_GUIDANCE, registerBackgroundTools } from "./backgroun
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.0";
+const VERSION = "1.26.2";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 

package/src/native-relay-companion.mjs

@@ -43,7 +43,7 @@ import { remoteCodexSocketPath, remoteNativeAdapter, remoteRequestResponse } fro
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.26.0";
+const VERSION = "1.26.2";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent, details) {