@lyupro/codex-bridge 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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
+
+- Scope patterns are checked before Codex starts. A pattern that cannot match anything — an
+  absolute or drive-qualified path, backslash separators, a `..` segment, or a spelling no
+  repository file answers to — is refused with no run folder and no quota spent, for all three
+  dispatchers. The file list comes from `git ls-files --cached --others --exclude-standard`, so
+  ignored output does not count as repository content. A file the run is meant to create is
+  declared with `--scope-new`, accepted only by `codex-build` and recorded in `worker.json`.
+- `codex-bridge permissions` reports, adds, and removes the optional shell permission rules for
+  both CLI names and the clone entry point. The exact allow and deny strings merge into
+  `settings.json`, preserve foreign rules, and are also removed by `uninstall`; `doctor` reports
+  an absent or partial set as an optional warning.
+
+### Changed
+
+- `codex-bridge sweep` is now `codex-bridge unlock`. The default scope is the current repository;
+  a bare project name remains addressable, and `--all` is now required for the whole store. The
+  report shows age, silence, and `alive` / `dead` / `foreign` / `unverified` identity verdicts;
+  confirmed-alive records are refused with `codex-bridge stop <run>` instead of being closed.
+
+### Fixed
+
+- Run records now verify that a pid still belongs to the process that started the run, using the
+  process start time and a fresh heartbeat before falling back to an OS probe. A reused or
+  unverified pid is never signalled by `stop`; `codex-bridge unlock` remains the non-killing way to
+  close a record whose process identity cannot be confirmed.
+- JSON files written by PowerShell with a UTF-8 BOM are now read consistently by the CLI and
+  installed hooks, and one command run creates at most one settings backup without deleting older
+  backups.
+- A run a guard refused before Codex ever started no longer costs the next attempt a round trip. Such a folder now closes as `aborted_pre_start` instead of the same `failed` a twenty-minute paid run gets, and the chain gate, the continuation limit and the tree baseline all skip it: the same order id starts as a first run, silently, with no `continue:` grant. Reported from a parallel `codex-build` launch — the second run was correctly refused with "two writing runs in one tree are prohibited", and its one-millisecond folder then made the retry demand a grant for work that never happened. Folders written before this release are recognised by what `meta.json` records — `exit`, `session_id`, `events_bytes`, `stderr_bytes`, `tokens_reported` — rather than by whether `events.jsonl` is still on disk, because retention deletes that file from paid runs too. The folder itself is kept: it is the audit trail of who was refused and why.
+- `chainBaseline()` takes the first run of the chain that actually started, so a pre-start folder sorting first no longer leaves the next pass without the `state-before.txt` its work is measured against.
+- `uninstall --dry-run` names each hook by its own matcher. Three of the four hooks are PreToolUse,
+  and a lookup by event alone reported `Agent|Task` for the worktree lock and the prune guard too —
+  in the one line an operator reads to see what a removal is about to touch. The removal itself was
+  never affected: hooks are found by command, not by matcher.
+- The order gate's refusal now shows the line it found. A caller who wrote
+  `scope (you may create/modify ONLY these):` was told scope was missing, re-read their own prompt,
+  saw it written there, and had nothing to act on; an autonomous run rewrites the same text forever.
+  The refusal names the candidate line under the input it belongs to and says why it was not
+  accepted — a qualifier between the label and the colon, a value that is still a placeholder, or no
+  separator at all — and stays silent when no candidate exists, because then "the input is missing"
+  is the truth. The parser accepts exactly what it accepted before: deriving scope from prose would
+  give away the only guarantee that a run cannot touch files nobody listed.
+
 ## [0.3.1] - 2026-08-07
 
 ### Added

package/README.md

@@ -1,106 +1,110 @@
 # 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)
+
+## 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.
+
+The current suite contains **603 automated tests: 602 passing and 1 skipped**.
+
+## 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
 
 ## Install
 
+For a one-off user installation, global access, or a clone entry point:
+
 ```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 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 sweep [<project>] # close running 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.
-
-`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.
-
-`sweep` is housekeeping for records left by a dead runner. With no project it scans the whole
-store; with one project it limits the scan to that folder. It uses the same dead-pid decision as
-start-of-run cleanup, never closes a live pid even when its heartbeat is stale, and never deletes
-run artifacts. A stale live-pid record is named with the exact `codex-bridge stop <run>` command
-needed to close it.
+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`.
 
-- **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.
+Installation has two roots:
 
-## Requirements
+- `~/.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.
+
+`codex-runs/` contains operator data. Uninstall never removes it.
+
+## Verify
 
-- 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
+```bash
+codex-bridge doctor
+```
 
-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.
+`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.
 
-## Development
+## 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,16 +1,17 @@
 #!/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';
 import { read } from '../cli/read.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
+import { permissions } from '../cli/permissions.mjs';
 import { prune } from '../cli/prune.mjs';
 import { stop } from '../cli/stop.mjs';
-import { sweep } from '../cli/sweep.mjs';
+import { unlock } from '../cli/unlock.mjs';
 import { uninstall } from '../cli/uninstall.mjs';
 import { update } from '../cli/update.mjs';
 
@@ -19,14 +20,16 @@ export const HELP = `codex-bridge — Claude Code dispatchers for Codex
 Usage:
   codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
   codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
   codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
   codex-bridge doctor [--scope user|project] [--host <path>]
   codex-bridge projects [<name>] [--json]
   codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
   codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
-  codex-bridge sweep [<project>]
+  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
@@ -34,13 +37,19 @@ Usage:
 Commands:
   install   Install codex-bridge into the selected Claude Code host
   update    Update a recorded codex-bridge installation
+  permissions Show, add, or remove optional shell permission rules
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host
   projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
-  sweep     Close running records whose runner is gone
+  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 = {};
@@ -90,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).');
@@ -110,7 +120,27 @@ export async function main(argv, io = console) {
     return result.exitCode;
   }
   if (command === 'sweep') {
-    const result = sweep(rest);
+    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+    return 2;
+  }
+  if (command === 'unlock') {
+    const result = unlock(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'permissions') {
+    let action;
+    let optionArgs = rest;
+    if (rest[0] && !rest[0].startsWith('-')) {
+      action = rest[0];
+      optionArgs = rest.slice(1);
+    }
+    if (action && !['add', 'remove'].includes(action)) {
+      throw new Error(`unknown permissions action "${action}"`);
+    }
+    const options = commandOptions(command, optionArgs);
+    const host = resolveHost(options);
+    const result = await permissions({ host, action });
     io.log(result.output);
     return result.exitCode;
   }
@@ -130,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,11 +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';
@@ -41,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}`);
@@ -49,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');
@@ -101,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'];
@@ -111,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');
@@ -124,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}`);
@@ -162,7 +206,22 @@ async function rulesCheck(host, record) {
     : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
 }
 
-export async function diagnose({ host, codexProbe = probeCodex, currentPackage } = {}) {
+async function permissionsCheck(host) {
+  try {
+    const status = await inspectPermissions(host.settingsPath);
+    // Permission rules are an optional operator action; Plan_22 keeps their absence a warning so
+    // doctor does not turn a healthy installation red merely because hardening was not requested.
+    // The ask count is part of the line because a full set shadowed by `ask` reads as working and
+    // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
+    const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
+    return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
+      `${status.state} (${status.present}/${status.total} own strings in allow/deny${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}
+
+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'})`));
@@ -188,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(
@@ -199,7 +258,8 @@ export async function diagnose({ host, codexProbe = probeCodex, currentPackage }
   ));
   const rules = await rulesCheck(host, record);
   checks.push(rules);
-  checks.push(...await hookChecks(host, record));
+  checks.push(await permissionsCheck(host));
+  checks.push(...await hookChecks(host, record, bridgeProbe));
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -211,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 {
@@ -225,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'].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],
+      },
+    };
+  });
+}