@lyupro/codex-bridge 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-08-12
+
+### Fixed
+
+- Installing or uninstalling no longer fails over a rules-registry lock that is busy for one more
+  millisecond. Windows answers a taken lock with three codes, and only one of them is `EEXIST`: a
+  lock file whose delete is still pending comes back `EPERM`, and a file another process still
+  holds comes back `EBUSY` — the acquisition loop treated both as fatal instead of waiting. All
+  three now mean "not yours yet", and the decision lives in one exported check, `isLockTaken()`.
+
+### Changed
+
+- The README's first screen names the problem the package solves, keeps the install command inside
+  the first 30 lines, adds a second badge row, and shows `doctor` output from a healthy host in
+  place of a screenshot.
+- The reference documentation under `docs/` is English-only now (`overview.ru.md` became
+  `overview.md`), and the working folders — plans, checklists and audits — left the repository and
+  its history: a fresh clone contains the five reference documents and nothing else.
+
+## [0.5.0] - 2026-08-11
+
+### Added
+
+- A fifth host guard now catches `TaskStop` while a live Codex run is still writing to the
+  repository, names the run and points to `codex-bridge stop <run>` before allowing a repeated
+  request. `doctor` and `projects` also surface active runs, so stopping a dispatcher wrapper is
+  no longer mistaken for stopping its detached worker.
+- `codex-bridge hook <name>` gives Claude Code a stable way to invoke each installed guard, and
+  `meta.json` now records the package version that produced a run. The usage report can therefore
+  separate historical runs made outside this runner from runs that should satisfy its sandbox
+  contract.
+
+### Changed
+
+- **Breaking:** the installed package layout now uses `agents/codex-bridge/` instead of
+  `agents/codex/`, `commands/codex-bridge/` instead of `commands/codex/`, and
+  `~/.lyupro/.codex-bridge/lib/` for the runner and guards. Slash commands are now
+  `/codex-bridge:usage` and `/codex-bridge:env`, and hooks in `settings.json` use
+  `codex-bridge hook <name>` when the matching package version is available. Run
+  `codex-bridge update` to migrate an existing installation and retire the old layout.
+- Runs started without an explicit `--slug` now derive a readable folder name from the required
+  order id instead of grouping unrelated work under the dispatcher name. Existing run folders
+  remain discoverable by their order id and task fingerprint.
+- The README now leads with the package's guarantees, verification and update guidance, and
+  limitations before the command reference, and the repository now publishes a security policy
+  and private vulnerability-reporting route.
+
+### Fixed
+
+- Guards invoked through a global-install symlink no longer exit successfully without running;
+  the direct-invocation check now compares resolved files, so a silent guard cannot allow every
+  operation while `doctor` reports it healthy. Hook registration also chooses the short command
+  form only when the command on `PATH` is this package's exact version, rather than merely present.
+- Retiring the previous layout no longer removes the shared Claude Code `agents/` and `commands/`
+  directories. Seeded operator files are moved only after byte verification, and an interrupted
+  migration is retried by the next `update` even when the new files are already current.
+- A continuation grant that loses its `--continue` flag is now refused before attachment instead
+  of replaying an older run's verdict as though new work ran. Attachment output also states
+  explicitly that no new work was started.
+- The test suite now isolates both installation roots, preventing tests from writing fixtures or
+  seeded configuration into the operator's real `~/.lyupro/.codex-bridge/` directory. Migration
+  dry runs also name the hook event and matcher instead of printing `undefined`.
+
 ## [0.4.0] - 2026-08-09
 
 ### Added

package/README.md

@@ -1,119 +1,135 @@
 # codex-bridge
 
-Delegate implementation, reconnaissance and code review from Claude Code to the
-[Codex CLI](https://developers.openai.com/codex/cli), so the work runs on a Codex
-subscription instead of the Claude one.
+**Delegate implementation, reconnaissance and review from Claude Code to Codex — five 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
-npx @lyupro/codex-bridge install        # one-off, into ~/.claude
-npm i -g @lyupro/codex-bridge           # install both command names globally
-codex-bridge install                    # full name, from any directory
-codexb install                          # short name, same command
-node bin/codex-bridge.mjs install       # from a clone, same thing
-node bin/codex-bridge.mjs install --scope project   # into <repo>/.claude
-node bin/codex-bridge.mjs update        # bring an installation up to the current version
-node bin/codex-bridge.mjs permissions   # show optional shell permission rules
-node bin/codex-bridge.mjs permissions add # add the complete allow/deny rule set
-node bin/codex-bridge.mjs permissions remove # remove only codex-bridge's rule strings
-node bin/codex-bridge.mjs doctor        # what is installed, where it points, is codex alive
-node bin/codex-bridge.mjs uninstall     # removes exactly what was installed
-node bin/codex-bridge.mjs stop <run>    # close a hanging run by hand, without hunting for a pid
-node bin/codex-bridge.mjs read <run>   # read a run: its events rendered as text, on demand
-node bin/codex-bridge.mjs projects     # what the run store holds: projects, runs, weight, tokens
-node bin/codex-bridge.mjs prune <project>   # reclaim disk space, transport only unless told otherwise
-node bin/codex-bridge.mjs unlock [<project>|--all] # close records whose runner is gone
+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
 ```
 
-When a global install and a clone coexist, there are two copies of the package. `codex-bridge update`
-and `codexb update` copy host files from whichever copy launched the command, so `codexb update`
-from `PATH` can silently revert a host that `npm run dev:install` from the clone just updated.
-
-`install` copies the package into the host's `agents/codex/`, its slash commands into
-`commands/codex/`, and registers its four hooks in `settings.json` — **merged**, so hooks that
-are already there survive, and the file is backed up before every write. Run it twice and the
-second run does nothing. `--dry-run` prints the plan and touches nothing.
-
-`update` moves an existing installation to the current version. It knows the sha256 of every file
-as it was installed, so it can tell a file you edited on the host from one left over by an older
-version: outdated files are refreshed silently, files you changed by hand stop the run and are
-named, and `--force` is what overwrites them. A file the package no longer ships is removed only
-if you never touched it.
-
-`permissions` manages the optional shell rules in the selected host's `settings.json`. `add`
-merges the exact allow and deny strings for both CLI names, the clone entry point, Bash and
-PowerShell; it preserves foreign rules and is safe to repeat. `remove` takes back those exact
-strings from `allow`, `deny`, or `ask`, so an operator-authored lookalike is left alone. With no
-action it reports whether the rule set is installed, partial, or absent. The command accepts the
-same `--scope` and `--host` selectors as `install`, and `uninstall` removes the same strings too.
-
-`uninstall` removes only what the install recorded: a file you put in `agents/codex/` yourself
-stays, and `codex-runs/` is never touched — those are your run artifacts, not the package.
-
-`stop` takes a run folder — a full path or a bare name from the current project's runs directory —
-kills that run's whole process tree and closes the folder the way an abandoned run is closed: a
-`FAIL` verdict naming what the run left in the worktree. A run that already has a verdict is left
-alone. Runs end on their own time budget now, so this is for the case where something wedged
-anyway.
-
-Run artifacts live in `codex-runs/<project>/`, one folder per repository, marked with a
-`.project.json` holding that repository's path. Two checkouts that share a directory name — two
-different `api` — therefore get `api` and `api-2` instead of one mixed history. `doctor` prints
-which folder the current repository writes to.
-
-`projects` reads that store back: without an argument, one line per project — runs, weight, tokens
-spent, how many are running right now; with a project name, one line per run. `prune` is the only
-command in the package that destroys data, and it is built to be hard to fire by accident: without
-`-f` it prints a plan and deletes nothing, `-f` still asks before each step, and with no terminal
-it refuses outright, because deletion is an operator action and there is no flag around it.
-By default it removes transport only — event streams and stderr, the megabytes — and leaves
-accounting, reports and worktree snapshots alone; `--purge` is what takes a folder whole.
-The same transport is dropped automatically from runs older than 30 days when a new run starts,
-which the reply says out loud; `retention` in `run-config.json` changes the age or turns it off.
-
-`unlock` is housekeeping for records left by a dead runner. With no argument it acts on the current
-repository; a bare project name limits the scan to that folder, and `--all` explicitly scans the
-whole store. It uses the same process-identity decision as start-of-run cleanup, closes only
-`dead` or `foreign` records, and reports each record's age, silence duration, and identity verdict.
-A confirmed `alive` record is refused rather than closed and is named with the exact
-`codex-bridge stop <run>` command needed to end it; `unverified` records stay untouched with the
-reason visible. The command never deletes run artifacts. The old spelling `sweep` is recognized and
-refused with the rename to `unlock`, rather than treated as an unknown 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.
 
-## What it gives you
+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/`.
+
+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.
 
-- **Three dispatcher agents** for Claude Code — reconnaissance (read-only), implementation
-  (write access limited to a declared scope), and an independent review by a second model.
-- **A runner that survives a dropped call.** The launcher hands the run to a detached
-  worker, so a killed dispatcher no longer leaves the work unexplainable: the run folder is
-  closed with artifacts either way.
-- **A verdict that checks the report against the worktree.** The agent's own account of what
-  it changed is compared with what git says actually changed, and a mismatch is a failed run
-  rather than a nicer-sounding summary.
-- **Four hooks that hold the rules the prompts only ask for**: a reply is refused when it does not
-  match the recorded state of the run, a dispatcher call is refused when it carries no order id, a
-  file edit is refused inside a repository a live run holds, and deletion of the run store is
-  refused when an agent is the one asking.
+`codex-runs/` contains operator data. Uninstall never removes it.
 
 ## Requirements
 
-- Node.js >= 24 (the file-size gate uses `fs.glob`, the test runner uses directory globs)
-- The `codex` CLI, authenticated (`codex --version`, `codex login`)
-- Claude Code, for the agents and the hook to be registered in
+- 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
 
-No runtime dependencies: everything here is plain `.mjs` on the Node standard library, and
-that is deliberate — installing from a clone stays one command, with no build step.
+## 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.
+- **5 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping.
+- **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.
 
-## Development
+The current suite contains **604 automated tests: 603 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.
+
+## 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>]` | Diagnose the selected host and Codex connection. |
+| `projects [<name>] [--json]` | List projects or runs in the run store. |
+| `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup. |
+| `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   # pre-commit file-size gate, 400 lines per source file
-npm test                              # node --test, no dependencies to install
+git config core.hooksPath .githooks
+npm test
 ```
 
+The Git hook enforces the 400-line source-file limit.
+
 ## License
 
-MIT
+[MIT](LICENSE)

package/bin/codex-bridge.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /** Dispatches codex-bridge CLI arguments to focused command modules. */
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { diagnose, renderDoctor } from '../cli/doctor.mjs';
+import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
+import { hook } from '../cli/hook.mjs';
 import { resolveHost } from '../cli/hosts.mjs';
 import { install } from '../cli/install.mjs';
 import { projects } from '../cli/projects.mjs';
@@ -29,6 +29,7 @@ Usage:
   codex-bridge unlock [<project>|--all]
   codex-bridge read <run>
   codex-bridge stop <run>
+  codex-bridge hook <name>
   codexb <same command forms as codex-bridge>
   codex-bridge --help
   codex-bridge --version
@@ -43,7 +44,12 @@ Commands:
   prune     Remove archived transport, or purge selected run folders
   unlock    Close running records whose runner is gone
   read      Render a run's structured event stream
-  stop      Stop a running Codex run and record FAIL`;
+  stop      Stop a running Codex run and record FAIL
+
+Hook dispatch:
+  codex-bridge hook <name>  Dispatch a registered guard with stdin unchanged`;
+
+const HOOK_COMMAND = 'hook';
 
 function commandOptions(command, argv) {
   const options = {};
@@ -93,6 +99,7 @@ export async function main(argv, io = console) {
     io.log(result.output);
     return result.exitCode;
   }
+  if (command === HOOK_COMMAND) return hook(rest, io);
   if (command === 'read') {
     if (rest.length !== 1) {
       io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
@@ -153,10 +160,7 @@ export async function main(argv, io = console) {
   return 2;
 }
 
-const invokedDirectly =
-  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
-
-if (invokedDirectly) {
+if (isInvokedDirectly(process.argv[1], import.meta.url)) {
   main(process.argv.slice(2))
     .then((exitCode) => { process.exitCode = exitCode; })
     .catch((err) => {

package/cli/copy.mjs

@@ -4,17 +4,18 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { replacePlaceholders } from './manifest.mjs';
 
-export async function plannedContent(item, agentsDir) {
+export async function plannedContent(item, installationRoot) {
+  const replacementRoot = item.installationRoot ?? installationRoot;
   const source = await fs.readFile(item.source);
   if (item.processing === 'copy') return source;
   if (item.processing === 'placeholders') {
-    return Buffer.from(replacePlaceholders(source.toString('utf8'), agentsDir));
+    return Buffer.from(replacePlaceholders(source.toString('utf8'), replacementRoot));
   }
   throw new Error(`unknown install processing "${item.processing}"`);
 }
 
-export async function targetMatches(item, agentsDir) {
-  const expected = await plannedContent(item, agentsDir);
+export async function targetMatches(item, installationRoot) {
+  const expected = await plannedContent(item, installationRoot);
   try {
     const actual = await fs.readFile(item.target);
     return actual.equals(expected);
@@ -24,8 +25,8 @@ export async function targetMatches(item, agentsDir) {
   }
 }
 
-export async function copyPlannedFile(item, agentsDir) {
-  const content = await plannedContent(item, agentsDir);
+export async function copyPlannedFile(item, installationRoot) {
+  const content = await plannedContent(item, installationRoot);
   await fs.mkdir(path.dirname(item.target), { recursive: true });
   const temporary = path.join(path.dirname(item.target), `.${path.basename(item.target)}.${randomUUID()}.tmp`);
   try {

package/cli/doctor.mjs

@@ -9,12 +9,15 @@ import {
   readInstallRecord,
   packageInfo,
 } from './manifest.mjs';
+import { recordTarget } from './install-record.mjs';
 import { inspectPermissions } from './permissions.mjs';
 import { commandFor, inspectHook } from './settings-merge.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
 import { readRunConfig, retentionNotice } from '../src/run-config.mjs';
 import { runsRoot } from '../src/runner/runs-root.mjs';
 import { resolveProjectRunsDir } from '../src/runner/project-dir.mjs';
+import { allLiveRuns } from '../src/hooks/live-runs.mjs';
+import { STOP_COMMAND_TEMPLATE } from '../src/stop-contract.mjs';
 
 const WARNING = '\u001b[33m';
 const RESET = '\u001b[0m';
@@ -42,7 +45,7 @@ function check(key, status, value) {
 
 function retentionCheck(host) {
   try {
-    const notice = retentionNotice(readRunConfig(path.join(host.agentsDir, 'run-config.json')));
+    const notice = retentionNotice(readRunConfig(host.brandConfigPath));
     return check('retention', notice.enabled ? 'warn' : 'ok', notice.text);
   } catch (err) {
     return check('retention', 'fail', `invalid configuration: ${err.message}`);
@@ -50,7 +53,7 @@ function retentionCheck(host) {
 }
 
 async function conventionsCheck(host) {
-  const file = path.join(host.agentsDir, 'conventions.md');
+  const file = host.brandConventionsPath;
   let content;
   try {
     content = await fs.readFile(file, 'utf8');
@@ -102,6 +105,18 @@ function projectRunsCheck() {
   return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
 }
 
+function liveRunsCheck() {
+  let count;
+  try {
+    count = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true }).length;
+  } catch (err) {
+    return check('liveRuns', 'warn', `working-run count unavailable: ${err.message}`);
+  }
+  if (!count) return check('liveRuns', 'ok', '0 runs working right now');
+  const noun = count === 1 ? 'run' : 'runs';
+  return check('liveRuns', 'warn', `${count} ${noun} working right now; stop with ${STOP_COMMAND_TEMPLATE}`);
+}
+
 export function probeCodex() {
   const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
   const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'];
@@ -112,7 +127,25 @@ export function probeCodex() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
-async function hookChecks(host, record) {
+export function probeCodexBridge() {
+  const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex-bridge';
+  const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex-bridge --version'] : ['--version'];
+  const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) {
+    return { available: false, value: (result.stderr || result.error?.message || 'not found').trim() };
+  }
+  return { available: true, value: (result.stdout || result.stderr).trim() };
+}
+
+function hookVersion(command, record, bridgeProbe) {
+  if (command.startsWith('codex-bridge hook ')) {
+    const result = bridgeProbe();
+    return result.available ? `global command ${result.value}` : `global command unavailable (${result.value})`;
+  }
+  return `installed copy ${record.name}@${record.version}`;
+}
+
+async function hookChecks(host, record, bridgeProbe) {
   return Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
     const key = `hook:${definition.event}`;
     if (!record) return check(key, 'warn', 'cannot check before installation');
@@ -125,17 +158,27 @@ async function hookChecks(host, record) {
     if (!recorded) {
       return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
     }
-    const expected = path.resolve(host.root, recorded.path);
+    const expected = recordTarget(host, recorded);
+    const fullCommand = commandFor(expected);
+    const shortCommand = `codex-bridge hook ${definition.name}`;
     try {
       const state = await inspectHook(host.settingsPath, {
         event: definition.event,
         matcher: definition.matcher,
-        command: commandFor(expected),
+        command: recorded.command || fullCommand,
+        alternateCommands: [fullCommand, shortCommand],
       });
       if (state.present) {
-        return check(key, 'ok', `${definition.event} matcher ${definition.matcher} -> ${expected}`);
+        const command = state.matchedCommand || recorded.command || fullCommand;
+        const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
+        const reason = form === 'short'
+          ? 'PATH command uses the globally installed package'
+          : 'full path uses the copy placed by the last install';
+        return check(key, 'ok', `${definition.event} matcher ${definition.matcher} -> ${expected} (${form} command; ${reason}; ${hookVersion(command, record, bridgeProbe)})`);
       }
-      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file}`);
+      const command = recorded.command || fullCommand;
+      const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
+      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file} (${form} command; ${hookVersion(command, record, bridgeProbe)})`);
     } catch (err) {
       const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
       return check(key, 'warn', `${definition.event} hook: ${value}`);
@@ -178,7 +221,7 @@ async function permissionsCheck(host) {
   }
 }
 
-export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
+export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = probeCodexBridge, currentPackage } = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
   checks.push(check('host', hostExists ? 'ok' : 'warn', `${host.root} (${host.scope}, ${hostExists ? 'exists' : 'absent'})`));
@@ -204,8 +247,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 
   const missingFiles = [];
   if (record) {
-    for (const relative of record.files) {
-      if (!(await isFile(path.join(host.root, relative)))) missingFiles.push(relative);
+    for (const file of record.files) {
+      if (!(await isFile(recordTarget(host, file)))) missingFiles.push(`${file.root}/${file.path}`);
     }
   }
   checks.push(check(
@@ -216,7 +259,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   const rules = await rulesCheck(host, record);
   checks.push(rules);
   checks.push(await permissionsCheck(host));
-  checks.push(...await hookChecks(host, record));
+  checks.push(...await hookChecks(host, record, bridgeProbe));
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -228,6 +271,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   checks.push(check('node', nodeMajor >= 24 ? 'ok' : 'fail', `${process.versions.node} (requires >=24)`));
   checks.push(check('runsRoot', 'ok', path.resolve(runsRoot())));
   const projectRuns = projectRunsCheck();
+  checks.push(liveRunsCheck());
   checks.push(projectRuns);
 
   return {
@@ -242,7 +286,7 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
 export function renderDoctor(result) {
   return result.checks.map(({ key, status, value }) => {
     const rendered = `[${status}] ${key}: ${value}`;
-    return ['retention', 'conventions', 'permissions'].includes(key) && status === 'warn'
+    return ['retention', 'conventions', 'permissions', 'liveRuns'].includes(key) && status === 'warn'
       ? `${WARNING}${rendered}${RESET}`
       : rendered;
   }).join('\n');

package/cli/hook-targets.mjs

@@ -0,0 +1,39 @@
+/** Describes where each guard is installed and how its registration will be spelled. */
+import path from 'node:path';
+import { HOOK_DEFINITIONS, installedHookPath } from './manifest.mjs';
+import { commandFor, hookRegistration } from './settings-merge.mjs';
+
+/**
+ * install.mjs and update.mjs each carried their own copy of this, and the copies had already
+ * drifted: one returned `root: 'brand'` on every entry and the other did not. Two copies of the
+ * list that decides what goes into the operator's settings.json is the same shape of defect
+ * Plan_19 had to reconcile between the installer and the hooks.
+ *
+ * `packageVersion` is what keeps the registration honest: the short command form is only chosen
+ * when the codex-bridge on PATH reports this exact version, because on 2026-08-11 an install from
+ * the clone wrote `codex-bridge hook <name>` against a global 0.4.0 that has no such subcommand
+ * and took every guard on the machine down with it.
+ */
+export function hookTargets(host, env = process.env, packageVersion = null) {
+  return HOOK_DEFINITIONS.map((definition) => {
+    const target = installedHookPath(host, definition);
+    const registration = hookRegistration(definition.name, target, env, packageVersion);
+    const fallback = commandFor(target);
+    const alternate = registration.command === fallback
+      ? `codex-bridge hook ${definition.name}`
+      : fallback;
+    return {
+      definition,
+      target,
+      root: 'brand',
+      relative: path.relative(host.brandRoot, target).split(path.sep).join('/'),
+      registration,
+      spec: {
+        event: definition.event,
+        matcher: definition.matcher,
+        command: registration.command,
+        alternateCommands: [alternate],
+      },
+    };
+  });
+}

package/cli/hook.mjs

@@ -0,0 +1,34 @@
+/** Dispatches a named host hook without changing the guard's stdin or process lifecycle. */
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+
+const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'hooks');
+const VALID_NAMES = HOOK_DEFINITIONS.map(({ name }) => name);
+
+function validNames() {
+  return VALID_NAMES.join(', ');
+}
+
+function usageError(io, message) {
+  io.error(`codex-bridge hook ${message} Valid hook names: ${validNames()}.`);
+  return 2;
+}
+
+export async function hook(args = [], io = console) {
+  if (!Array.isArray(args) || args.length !== 1) {
+    const detail = Array.isArray(args) && args.length
+      ? `accepts exactly one hook name; received ${args.length}.`
+      : 'requires exactly one hook name.';
+    return usageError(io, detail);
+  }
+
+  const definition = HOOK_DEFINITIONS.find(({ name }) => name === args[0]);
+  if (!definition) return usageError(io, `unknown hook name "${args[0]}".`);
+
+  // Plan_25 replaces absolute paths in foreign settings.json with this command. Importing the
+  // proven top-level script keeps its stdin reader and process.exit() contract intact; exporting
+  // guard functions would be a second implementation of the live hook boundary.
+  await import(pathToFileURL(path.join(HOOKS_DIR, definition.file)).href);
+  return typeof process.exitCode === 'number' ? process.exitCode : 0;
+}