@lyupro/codex-bridge 0.6.1 → 0.6.4

package/README.md

@@ -1,155 +1,155 @@
-# codex-bridge
-
-**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
-
-[![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[![npm downloads](https://img.shields.io/npm/dm/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![npm unpacked size](https://img.shields.io/npm/unpacked-size/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
-
-Agentic coding spends one model subscription on everything, and implementation is the expensive part. codex-bridge moves that work to a separate [Codex CLI](https://developers.openai.com/codex/cli) subscription: Claude Code plans, dispatches and accepts, Codex executes — and every delegated run is guarded, verified and audited on disk.
-
-## Install
-
-```bash
-npm i -g @lyupro/codex-bridge   # puts both command names on PATH
-codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
-codexb install                  # the short name, same command
-```
-
-Two other entry points reach the same command: `npx @lyupro/codex-bridge install` for a one-off run without a global install, and `node bin/codex-bridge.mjs install` from a clone. Every command below works through all three.
-
-Shipped agents invoke delegated runs through `codex-bridge run`. This is a permission contract,
-not a style choice: the stable package command lets host permission rules match the invocation
-without exposing an installation-specific absolute path and prompting on every delegation.
-
-Installing optional permission rules now adds `model speed` rules to `ask`, previously left to the operator, alongside `allow` and `deny`. These narrow prompts outrank the broad command allow rules and are checked before hooks, so an agent must ask the operator before switching tiers even when acting in good faith. Removing the rules takes back these exact strings while preserving other operator settings.
-
-Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
-
-Installation has two roots:
-
-- `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
-- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
-
-The repository's `src/home/` directory is the literal image copied into the branded root: its
-`hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
-Only npm's `package.json` is copied into that root from outside the image.
-
-Before every `settings.json` write, the existing file is backed up. Existing settings and foreign hooks are preserved. `--dry-run` prints the plan without writing.
-
-If a global install and a clone coexist, you have two package copies. `codex-bridge update`, `codexb update`, and the clone entry point copy files from whichever copy launched the command; using the wrong one can replace a newer host installation with older files.
-
-`codex-runs/` contains operator data. Uninstall never removes it.
-
-## Requirements
-
-- Node.js >= 24
-- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
-- Claude Code, which hosts the agents, commands, and guards
-
-## What it gives you
-
-- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
-- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
-- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
-- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
-- **6 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway.
-- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
-- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
-- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
-
-The current suite contains **963 automated tests: 962 passing and 1 skipped**.
-
-## Verify
-
-```bash
-codex-bridge doctor
-```
-
-Output on a healthy host (trimmed):
-
-```text
-[ok] host: ~/.claude (user, exists)
-[ok] installation: @lyupro/codex-bridge@0.5.1 (matches package)
-[ok] files: 53 installed file(s) present
-[ok] rules: ~/.codex/rules/codex-bridge.rules (matches record)
-[ok] permissions: installed (24/24 own strings in allow/deny)
-[ok] hook:SubagentStop: matcher * -> ~/.lyupro/.codex-bridge/hooks/reply-guard.mjs
-[ok] hook:PreToolUse: matcher Agent|Task -> ~/.lyupro/.codex-bridge/hooks/order-gate.mjs
-[ok] hook:PreToolUse: matcher Write|Edit|MultiEdit|NotebookEdit -> ~/.lyupro/.codex-bridge/hooks/worktree-lock.mjs
-[ok] hook:PreToolUse: matcher Bash|PowerShell -> ~/.lyupro/.codex-bridge/hooks/prune-guard.mjs
-[ok] hook:PreToolUse: matcher TaskStop -> ~/.lyupro/.codex-bridge/hooks/stop-guard.mjs
-[warn] retention: Automatic cleanup is ON — run transport older than 30 days is removed to reclaim disk space.
-[ok] conventions: ~/.lyupro/.codex-bridge/conventions.md (found)
-[ok] codex: codex-cli 0.146.1
-[ok] node: 24.18.0 (requires >=24)
-[ok] runsRoot: ~/.claude/codex-runs
-[ok] liveRuns: 0 runs working right now
-```
-
-`doctor` reports the selected host, package source, installed files and guards, Codex availability, retention policy, permissions, live runs, and the current repository's run folder. The `agents` line is a read, not a file count: each installed definition is parsed and its `name` checked against the dispatcher it claims to be, because a definition the host cannot read is a dispatcher that does not exist while every other line still says `[ok]`. Content that drifts from the packaged definition is a failure, not a warning: `doctor` exits 1 and names `codex-bridge update --force`, because a host running someone else's agent files may be calling the runner in a form no permission rule matches.
-
-If a session answers `Agent type 'codex-build' not found`, a run can still be started without the dispatcher — the agent is a wrapper that types one command:
-
-```bash
-codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
-```
-
-The trade-off is explicit: `order-gate` and `reply-guard` sit on the dispatcher call, so a direct run is unguarded and its result is judged by the worktree and the suite.
-
-## Update
-
-Update the global package, then refresh the selected host installation:
-
-```bash
-npm i -g @lyupro/codex-bridge
-codex-bridge update
-```
-
-`update` refreshes unchanged package files, refuses to overwrite operator edits unless `--force` is supplied, and removes obsolete files only when their installed fingerprint is unchanged.
-
-## Limitations
-
-- **Runs are not isolated from one another.** They share one worktree; guards prevent concurrent writers instead of creating sandboxes.
-- **A build run has a 25-minute deadline.** Work and artifacts survive a timeout, but the run may need an explicit continuation.
-- **A dispatcher verdict is not the work outcome.** Judge completion from the worktree and tests as well as the recorded verdict.
-
-Transport files from runs at least **30 days** old are pruned automatically when a new run starts. Configuration can change or disable that retention policy; reports, accounting, and worktree snapshots are retained.
-
-## Command reference
-
-| Command | Purpose |
-| --- | --- |
-| `install [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Install into a Claude Code host. |
-| `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
-| `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
-| `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
-| `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection. `--probe-contract` measures on a live host whether it still honours a hook refusal, and records the answer. |
-| `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
-| `model [list\|set\|unset\|speed]` | Show the model, effort, pinned speed tier and provenance of each role, with the config path; `model list` prints the live catalogue from Codex, hidden models included and marked; `model set <role> <model> [effort]` checks the pair and any retained speed tier against that model's catalogue entry, and `model unset <role>` removes the profile. `model speed <role> <tier>` previews a live accelerated tier and its quoted cost description; repeat with trailing `confirm` to pin it. `model speed <role> unset` removes only speed, without confirmation. The profile is machine-wide, shared by every project on this machine. |
-| `projects [<name>] [--json]` | List projects or runs in the run store. |
-| `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
-| `unlock [<project>\|--all]` | Close records whose runner is gone. |
-| `read <run>` | Render a run's structured event stream. |
-| `stop <run>` | Stop a run and record a `FAIL` verdict. |
-
-Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms.
-
-### Development
-
-```bash
-git clone https://github.com/lyupro/codex-bridge.git
-cd codex-bridge
-git config core.hooksPath .githooks
-npm test
-```
-
-The Git hook enforces the 400-line source-file limit.
-
-## License
-
-[MIT](LICENSE)
+# codex-bridge
+
+**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
+
+[![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[![npm downloads](https://img.shields.io/npm/dm/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![npm unpacked size](https://img.shields.io/npm/unpacked-size/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
+
+Agentic coding spends one model subscription on everything, and implementation is the expensive part. codex-bridge moves that work to a separate [Codex CLI](https://developers.openai.com/codex/cli) subscription: Claude Code plans, dispatches and accepts, Codex executes — and every delegated run is guarded, verified and audited on disk.
+
+## Install
+
+```bash
+npm i -g @lyupro/codex-bridge   # puts both command names on PATH
+codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
+codexb install                  # the short name, same command
+```
+
+Two other entry points reach the same command: `npx @lyupro/codex-bridge install` for a one-off run without a global install, and `node bin/codex-bridge.mjs install` from a clone. Every command below works through all three.
+
+Shipped agents invoke delegated runs through `codex-bridge run`. This is a permission contract,
+not a style choice: the stable package command lets host permission rules match the invocation
+without exposing an installation-specific absolute path and prompting on every delegation.
+
+Installing optional permission rules now adds `model speed` rules to `ask`, previously left to the operator, alongside `allow` and `deny`. These narrow prompts outrank the broad command allow rules and are checked before hooks, so an agent must ask the operator before switching tiers even when acting in good faith. Removing the rules takes back these exact strings while preserving other operator settings.
+
+Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
+
+Installation has two roots:
+
+- `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
+- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
+
+The repository's `src/home/` directory is the literal image copied into the branded root: its
+`hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
+Only npm's `package.json` is copied into that root from outside the image.
+
+Before every `settings.json` write, the existing file is backed up. Existing settings and foreign hooks are preserved. `--dry-run` prints the plan without writing.
+
+If a global install and a clone coexist, you have two package copies. `codex-bridge update`, `codexb update`, and the clone entry point copy files from whichever copy launched the command; using the wrong one can replace a newer host installation with older files.
+
+`codex-runs/` contains operator data. Uninstall never removes it.
+
+## Requirements
+
+- Node.js >= 24
+- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
+- Claude Code, which hosts the agents, commands, and guards
+
+## What it gives you
+
+- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
+- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
+- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
+- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
+- **6 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway.
+- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
+- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
+- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
+
+The current suite contains **1177 automated tests: 1176 passing and 1 skipped**.
+
+## Verify
+
+```bash
+codex-bridge doctor
+```
+
+Output on a healthy host (trimmed):
+
+```text
+[ok] host: ~/.claude (user, exists)
+[ok] installation: @lyupro/codex-bridge@0.5.1 (matches package)
+[ok] files: 53 installed file(s) present
+[ok] rules: ~/.codex/rules/codex-bridge.rules (matches record)
+[ok] permissions: installed (24/24 own strings in allow/deny)
+[ok] hook:SubagentStop: matcher * -> ~/.lyupro/.codex-bridge/hooks/reply-guard.mjs
+[ok] hook:PreToolUse: matcher Agent|Task -> ~/.lyupro/.codex-bridge/hooks/order-gate.mjs
+[ok] hook:PreToolUse: matcher Write|Edit|MultiEdit|NotebookEdit -> ~/.lyupro/.codex-bridge/hooks/worktree-lock.mjs
+[ok] hook:PreToolUse: matcher Bash|PowerShell -> ~/.lyupro/.codex-bridge/hooks/prune-guard.mjs
+[ok] hook:PreToolUse: matcher TaskStop -> ~/.lyupro/.codex-bridge/hooks/stop-guard.mjs
+[warn] retention: Automatic cleanup is ON — run transport older than 30 days is removed to reclaim disk space.
+[ok] conventions: ~/.lyupro/.codex-bridge/conventions.md (found)
+[ok] codex: codex-cli 0.146.1
+[ok] node: 24.18.0 (requires >=24)
+[ok] runsRoot: ~/.claude/codex-runs
+[ok] liveRuns: 0 runs working right now
+```
+
+`doctor` reports the selected host, package source, installed files and guards, Codex availability, retention policy, permissions, live runs, and the current repository's run folder. The `agents` line is a read, not a file count: each installed definition is parsed and its `name` checked against the dispatcher it claims to be, because a definition the host cannot read is a dispatcher that does not exist while every other line still says `[ok]`. Content that drifts from the packaged definition is a failure, not a warning: `doctor` exits 1 and names `codex-bridge update --force`, because a host running someone else's agent files may be calling the runner in a form no permission rule matches.
+
+If a session answers `Agent type 'codex-build' not found`, a run can still be started without the dispatcher — the agent is a wrapper that types one command:
+
+```bash
+codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
+```
+
+The trade-off is explicit: `order-gate` and `reply-guard` sit on the dispatcher call, so a direct run is unguarded and its result is judged by the worktree and the suite.
+
+## Update
+
+Update the global package, then refresh the selected host installation:
+
+```bash
+npm i -g @lyupro/codex-bridge
+codex-bridge update
+```
+
+`update` refreshes unchanged package files, refuses to overwrite operator edits unless `--force` is supplied, and removes obsolete files only when their installed fingerprint is unchanged.
+
+## Limitations
+
+- **Runs are not isolated from one another.** They share one worktree; guards prevent concurrent writers instead of creating sandboxes.
+- **A build run has a 25-minute deadline.** Work and artifacts survive a timeout, but the run may need an explicit continuation.
+- **A dispatcher verdict is not the work outcome.** Judge completion from the worktree and tests as well as the recorded verdict.
+
+Transport files from runs at least **30 days** old are pruned automatically when a new run starts. Configuration can change or disable that retention policy; reports, accounting, and worktree snapshots are retained.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `install [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Install into a Claude Code host. |
+| `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
+| `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
+| `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
+| `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection. `--probe-contract` measures on a live host whether it still honours a hook refusal, and records the answer. |
+| `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
+| `model [list\|set\|unset\|speed]` | Show the model, effort, pinned speed tier and provenance of each role, with the config path; `model list` prints the live catalogue from Codex, hidden models included and marked; `model set <role> <model> [effort]` checks the pair and any retained speed tier against that model's catalogue entry, and `model unset <role>` removes the profile. `model speed <role> <tier>` previews a live accelerated tier and its quoted cost description; repeat with trailing `confirm` to pin it. `model speed <role> unset` removes only speed, without confirmation. The profile is machine-wide, shared by every project on this machine. |
+| `projects [<name>] [--json]` | List projects or runs in the run store. |
+| `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
+| `unlock [<project>\|--all]` | Close records whose runner is gone. |
+| `read <run>` | Render a run's structured event stream. |
+| `stop <run>` | Stop a run and record a `FAIL` verdict. |
+
+Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms.
+
+### Development
+
+```bash
+git clone https://github.com/lyupro/codex-bridge.git
+cd codex-bridge
+git config core.hooksPath .githooks
+npm test
+```
+
+The Git hook enforces the 400-line source-file limit.
+
+## License
+
+[MIT](LICENSE)

package/cli/runs-inventory.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { liveRuns } from '../src/home/hooks/live-runs.mjs';
 import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
 
 const record = (value) => value && typeof value === 'object' && !Array.isArray(value);
@@ -108,7 +109,7 @@ function readRun(runDir, livePaths) {
   return {
     run: path.basename(runDir),
     agent: text(facts?.agent),
-    verdict: live ? 'running' : text(meta ? meta.status : status?.state),
+    verdict: live ? 'running' : text(meta ? meta.status : runLiveness({ runDir, status }).state),
     tokens: meta ? number(meta.tokens) : null,
     size: recursiveSize(runDir),
     timestamp: runTimestamp(path.basename(runDir), meta, status),
@@ -131,8 +132,9 @@ function publicRun(run) {
 
 function buildProject(projectDir) {
   const runDirs = directoryEntries(projectDir).map((entry) => path.join(projectDir, entry.name));
-  // live-runs owns PID and status interpretation after the 2026-08-05 live probe incident;
-  // this module only maps its result back to the corresponding inventory row.
+  // live-runs owns the `live` column (a fresh heartbeat) after the 2026-08-05 live probe incident.
+  // A row without a verdict shows what closing it would write — the judge's `abandoned` rather than
+  // the raw `running` a dead run keeps in status.json forever (Plan_57 D27).
   const livePaths = new Set(liveRuns(projectDir).map(({ dir }) => pathKey(dir)));
   const details = runDirs.map((runDir) => readRun(runDir, livePaths));
   // Sum what is known instead of blanking the column. One archived run without accounting used to

package/cli/settings-merge.mjs

@@ -18,24 +18,34 @@ export function shortCommandFor(name) {
   return `codex-bridge hook ${name}`;
 }
 
-function pathValue(env) {
-  const key = Object.keys(env).find((entry) => entry.toLowerCase() === 'path');
+function envValue(env, name) {
+  const key = Object.keys(env).find((entry) => entry.toLowerCase() === name);
   return key ? env[key] : '';
 }
 
-export function commandReachable(name = 'codex-bridge', env = process.env) {
+function pathValue(env) {
+  return envValue(env, 'path');
+}
+
+function resolveCommand(name, env) {
   const extensions = process.platform === 'win32'
     ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')
     : [''];
-  return pathValue(env).split(path.delimiter).filter(Boolean).some((directory) =>
-    extensions.some((extension) => {
-      const candidate = path.join(directory, `${name}${extension}`);
+  for (const directory of pathValue(env).split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(path.resolve(directory), `${name}${extension}`);
       try {
-        return existsSync(candidate) && statSync(candidate).isFile();
+        if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
       } catch {
-        return false;
+        continue;
       }
-    }));
+    }
+  }
+  return null;
+}
+
+export function commandReachable(name = 'codex-bridge', env = process.env) {
+  return Boolean(resolveCommand(name, env));
 }
 
 /**
@@ -47,14 +57,23 @@ export function commandReachable(name = 'codex-bridge', env = process.env) {
  * could decide anything, and the host refused Bash, PowerShell, file edits and agent launches.
  */
 export function reachableCommandVersion(name = 'codex-bridge', env = process.env) {
-  if (!commandReachable(name, env)) return null;
-  const result = spawnSync(name, ['--version'], {
-    encoding: 'utf8',
-    env,
-    // The launcher npm writes on Windows is a .cmd shim, which spawn cannot execute without a
-    // shell. The name is a constant of this module, never operator input.
-    shell: process.platform === 'win32',
-  });
+  const shimPath = resolveCommand(name, env);
+  if (!shimPath) return null;
+  // Node 24 warned with DEP0190 during update (2026-09-07): invoke cmd explicitly for npm shims.
+  // Live probes covered plain, bin with space, Program Files (x86), weird & name, and caret^dir.
+  // /d /s /c with path and --version as separate arguments only passed the plain directory:
+  // Node adds quotes, then cmd's /s strips the first and last quote of the whole command line.
+  // /d /c without /s failed on & and ^. This single, double-wrapped verbatim command passed all
+  // five. Keep native path separators: forward-slash Windows paths do not work through cmd.
+  // The interpreter is a property of the machine, not of the PATH handed in: resolving cmd.exe
+  // through the caller's PATH would return null on any env whose PATH omits System32, and a null
+  // version is exactly the silent failure this function exists to prevent.
+  const shell = envValue(env, 'comspec') || process.env.ComSpec || 'cmd.exe';
+  const result = process.platform === 'win32'
+    ? spawnSync(shell, ['/d', '/s', '/c', `""${shimPath}" --version"`], {
+      encoding: 'utf8', env, shell: false, windowsVerbatimArguments: true,
+    })
+    : spawnSync(shimPath, ['--version'], { encoding: 'utf8', env, shell: false });
   if (result.error || result.status !== 0) return null;
   return String(result.stdout || '').trim().split(/\r?\n/).pop()?.trim() || null;
 }

package/cli/stop.mjs

@@ -2,12 +2,12 @@
 import path from 'node:path';
 import { stopCodex } from '../src/home/lib/runner/codex-cmd.mjs';
 import { git, worktreeSnapshot } from '../src/home/lib/runner/git-state.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_FOREIGN,
   IDENTITY_UNVERIFIED,
   processAlive,
-  processIdentity,
 } from '../src/home/lib/process-identity.mjs';
 import { markAbandoned, readJson } from '../src/home/lib/write-meta.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
@@ -72,7 +72,7 @@ export async function stop({
     return result(1, `Run ${runDir} has no valid recorded pid; it was not changed.`);
   }
 
-  const identity = processIdentity({ runDir, status, commandRunner });
+  const { identity } = runLiveness({ runDir, status, commandRunner });
   if (identity === IDENTITY_UNVERIFIED || identity === IDENTITY_FOREIGN) {
     return result(
       1,

package/cli/unlock.mjs

@@ -3,11 +3,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { formatSilence, heartbeatAge, HEARTBEAT_STALE_MS } from '../src/home/lib/heartbeat.mjs';
+import { runLiveness } from '../src/home/lib/meta/run-liveness.mjs';
 import { markAbandoned } from '../src/home/lib/meta/run-state.mjs';
 import {
   IDENTITY_ALIVE,
   IDENTITY_UNVERIFIED,
-  processIdentity,
 } from '../src/home/lib/process-identity.mjs';
 import { git } from '../src/home/lib/runner/git-state.mjs';
 import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
@@ -144,7 +144,7 @@ function inspectRuns(project, options) {
       age: runAge(status.started_at, now),
       silence: formatSilence(silenceAge),
       silenceAge,
-      identity: processIdentity(identityOptions(dir, status, options, now)),
+      identity: runLiveness(identityOptions(dir, status, options, now)).identity,
       state: status.state,
     });
   }

package/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "@lyupro/codex-bridge",
-  "version": "0.6.1",
-  "description": "Claude Code-to-Codex delegation with 6 guards, 963 tests, zero runtime dependencies, and zero build steps.",
-  "keywords": [
-    "claude-code",
-    "codex",
-    "codex-cli",
-    "subagent",
-    "ai-agents",
-    "orchestration",
-    "hooks"
-  ],
-  "license": "MIT",
-  "author": "Lyu Pro <lyupro.dev@gmail.com> (https://lyupro.com)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lyupro/codex-bridge.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lyupro/codex-bridge/issues"
-  },
-  "homepage": "https://github.com/lyupro/codex-bridge#readme",
-  "type": "module",
-  "bin": {
-    "codex-bridge": "./bin/codex-bridge.mjs",
-    "codexb": "./bin/codex-bridge.mjs"
-  },
-  "engines": {
-    "node": ">=24.0.0"
-  },
-  "files": [
-    "bin",
-    "cli",
-    "src",
-    "scripts",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "dev:install": "node bin/codex-bridge.mjs update --force",
-    "test": "node scripts/run-tests.mjs",
-    "check:size": "node scripts/check-file-size.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@lyupro/codex-bridge",
+  "version": "0.6.4",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 1177 tests, zero runtime dependencies, and zero build steps.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "codex-cli",
+    "subagent",
+    "ai-agents",
+    "orchestration",
+    "hooks"
+  ],
+  "license": "MIT",
+  "author": "Lyu Pro <lyupro.dev@gmail.com> (https://lyupro.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lyupro/codex-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lyupro/codex-bridge/issues"
+  },
+  "homepage": "https://github.com/lyupro/codex-bridge#readme",
+  "type": "module",
+  "bin": {
+    "codex-bridge": "./bin/codex-bridge.mjs",
+    "codexb": "./bin/codex-bridge.mjs"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "bin",
+    "cli",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev:install": "node bin/codex-bridge.mjs update --force",
+    "test": "node scripts/run-tests.mjs",
+    "check:size": "node scripts/check-file-size.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}