@lyupro/codex-bridge 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,7 +4,110 @@ 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.2] - 2026-08-16
+
+### Fixed
+
+- The guard punished the very refusal the package demands. A dispatcher whose command the host
+  denies is told by its own prompt to answer `FAIL`, name its order id and name `codex-bridge
+  install`; the guard knew only `RUN=` and `ATTACH=`, so that honest answer read as "no run
+  exists" and was blocked three times before the exhausted try budget let it through. A probe on
+  2026-08-16 with `Bash(codex-bridge:*)` denied spent 31.5k tokens on an answer worth ten, and the
+  counter recorded `{"state": 3}` against it. A host refusal is now a recognised shape beside the
+  two run lines: a reply that declares failure, names its order id and names the remedy passes on
+  the first try, before any check that looks for a folder on disk. A reply that declares failure and
+  names the remedy but omits the order id is blocked with that exact part named — the prompt asked
+  for it in prose, and prose is a request a model can silently skip.
+
+- No Claude Code host had registered the three dispatchers since 2026-08-10. The stop-guidance
+  sentence added that day — `` before `TaskStop`: TaskStop removes the wrapper … `` — was
+  substituted into the `description:` line of each agent's frontmatter, and an unquoted YAML scalar
+  cannot contain a colon followed by a space: the frontmatter did not parse, so the agents did not
+  exist as far as the host was concerned. `doctor` reported every file present the whole time,
+  because it counted files instead of reading them. Installation now re-emits frontmatter as valid
+  YAML — any value a reader would not take as a plain scalar is quoted, the sentence survives
+  verbatim — `doctor` parses each installed definition and checks its `name`, and the suite parses
+  everything the installer would write.
+
+- A run ordered under another run's order id is no longer answered with that run's verdict. On
+  2026-08-15 a build ordered as `plan42-run3` carried the id of `plan42-run2`, and the runner
+  printed run2's `OK`, run2's file list and run2's suite over a worktree where nothing had been
+  done — only a manual `git status` stopped a commit of work that did not exist. An order id names
+  one task: when the id already belongs to a run whose task text differs, the runner now refuses
+  with exit code `2` before printing anything, naming the folder that owns the id and the two
+  remedies (a new `--order-id`, or `--continue`). Repeats of the same task, continuations, and runs
+  recorded before the `task_hash` field attach exactly as before.
+- The same collision is now refused one step earlier and checked one step later. `order-gate` denies
+  the dispatcher call itself when the ordered id already belongs to a run with a different task —
+  before any quota is spent — and `reply-guard` blocks a reply whose run records a different
+  `order_id` than the one the orchestrator ordered, read from the dispatcher's own transcript. Both
+  read the single definition of "the same task" the runner uses; a second copy of that rule would
+  drift silently, which is the failure this change exists to end. Every uncertain disk state — an
+  unreadable task file, a missing runs directory, a run folder written before its `status.json` —
+  passes, because a guard nobody can predict is a guard everyone works around.
+- Delegating to a dispatcher no longer stops on a permission prompt. The shipped agent definitions
+  started a run by absolute path — `node "<installed dir>/run-codex.mjs" --agent … \ …` — and a host
+  matches permission rules against the beginning of a command line, so a rule written for this
+  package could never match it. The only way to start a run is now the package command,
+  `codex-bridge run`, on a single line: no interpreter, no path, no line continuation. The task
+  statement travels as `--task-file`, because a heredoc forces the invocation back into the
+  multi-line form that no rule can cover; stdin remains supported for the direct call, and giving
+  both channels is a refusal rather than a silent precedence.
+- Installed hooks could not run at all. The installer reshaped the source tree — hooks to one
+  directory, their modules to another — so every hook's relative import was correct in the clone and
+  false on the host, and all five guards died on `ERR_MODULE_NOT_FOUND` from the day the package
+  moved to its branded folder. The suite stayed green because it exercises the clone, and `doctor`
+  called a hook healthy on the strength of a line in `settings.json` without ever starting the file.
+  The source now contains a literal image of the installed home, `src/home/`, and installation
+  copies it one to one.
+- The reply guard no longer sends a refused dispatcher down the one road the host cannot allow.
+  Seven of its block texts said "Run run-codex.mjs and return its stdout verbatim" — the sentence
+  removed from every prompt in this release, because a command line naming a file can match no
+  permission rule. They were the worst place for it to survive: a dispatcher reads them at the one
+  moment it is looking for what to do next, having just had its answer rejected. All seven name
+  `codex-bridge run`. The invariant behind them was the actual defect and is now stated as a rule
+  rather than as a shape: no line of code in a hook may name the runner file, whole-line comments
+  excepted. The earlier expression-bound check could not see the text a session is shown when its
+  turn is ended, which is where the same sentence would have survived a fourth cleanup.
+- `doctor` no longer calls a host healthy when an installed agent definition is not this package's.
+  Drift was advisory — a message, exit code 0 — while an unreadable definition was already fatal. A
+  checklist run planted the pre-0.5.2 invocation, a file path instead of the package command, in an
+  installed agent: `doctor` printed the drift and still exited 0, so a script or a CI step would
+  have called that host healthy while every delegation on it stopped at a permission prompt. Any
+  definition that differs from the package now exits 1 and names `codex-bridge update --force`.
+
+### Added
+
+- `codex-bridge run` — the public entry point for starting a delegated run, with the same flags,
+  stdout and exit codes as the historical file invocation.
+- Both lines that identify a run to its caller carry the order they belong to:
+  `RUN=<path> order-id=<id>` and `ATTACH=<path> order-id=<id> started=<time>`. A reply naming a run
+  cannot be checked against the order that was placed unless the id travels with the folder.
+- Two structural guards that make the above regressions loud instead of silent: the install plan
+  must stay isomorphic to the shipped home image, and every registered hook must actually start as
+  a child process with its imports resolved.
+- `doctor` compares the version answering a hook against the installed copy, verifies the installed
+  agent definitions against the repository, and downgrades to a warning instead of reporting code it
+  never ran as healthy.
+
+## [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
 

package/README.md

@@ -6,29 +6,14 @@
 [![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**.
+[![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)
 
-## 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
+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
 
-For a one-off user installation, global access, or a clone entry point:
-
 ```bash
 npm i -g @lyupro/codex-bridge   # puts both command names on PATH
 codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
@@ -37,6 +22,10 @@ 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.
+
 Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
 
 Installation has two roots:
@@ -44,19 +33,71 @@ 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.
+- **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 **705 automated tests: 704 passing and 1 skipped**.
+
 ## Verify
 
 ```bash
 codex-bridge doctor
 ```
 
-`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.
+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
 
@@ -86,6 +127,7 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `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. |
+| `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. |
 | `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. |

package/bin/codex-bridge.mjs

@@ -7,6 +7,7 @@ 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 { runCodexCommand } from '../src/home/lib/run-codex.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
 import { permissions } from '../cli/permissions.mjs';
 import { prune } from '../cli/prune.mjs';
@@ -23,6 +24,7 @@ Usage:
   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 run <runner options> --task-file <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]
@@ -40,6 +42,7 @@ Commands:
   permissions Show, add, or remove optional shell permission rules
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host
+  run       Start or attach to a delegated Codex run
   projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
   unlock    Close running records whose runner is gone
@@ -84,6 +87,7 @@ export async function main(argv, io = console) {
     io.log((await packageInfo()).version);
     return 0;
   }
+  if (command === 'run') return runCodexCommand(rest);
   if (command === 'doctor') {
     const host = resolveHost(commandOptions(command, rest));
     const result = await diagnose({ host });

package/cli/doctor.mjs

@@ -2,22 +2,26 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import {
+  buildInstallPlan,
+  contentFingerprint,
   fileFingerprint,
   HOOK_DEFINITIONS,
   readInstallRecord,
   packageInfo,
 } from './manifest.mjs';
+import { plannedContent } from './copy.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';
+import { parseFrontmatter } from './frontmatter.mjs';
+import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
+import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/stop-contract.mjs';
 
 const WARNING = '\u001b[33m';
 const RESET = '\u001b[0m';
@@ -39,6 +43,44 @@ async function isFile(target) {
   }
 }
 
+async function agentsCheck(host, record) {
+  if (!record) return check('agents', 'warn', 'Agent definitions were not checked; run codex-bridge install');
+  const plan = await buildInstallPlan(host);
+  const agents = plan.filter((item) => /[\\/]src[\\/]agents[\\/][^\\/]+\.md$/.test(item.source));
+  const mismatches = [];
+  const unreadable = [];
+  for (const item of agents) {
+    const expected = contentFingerprint(await plannedContent(item, host.brandRoot));
+    if (await fileFingerprint(item.target) !== expected) mismatches.push(path.basename(item.target));
+    const expectedName = path.basename(item.source, '.md');
+    try {
+      const frontmatter = parseFrontmatter(await fs.readFile(item.target, 'utf8'));
+      if (!frontmatter) throw new Error('frontmatter is missing');
+      if (frontmatter.name !== expectedName) {
+        throw new Error(`name is ${JSON.stringify(frontmatter.name)}, expected ${JSON.stringify(expectedName)}`);
+      }
+    } catch (err) {
+      unreadable.push(`${path.basename(item.target)} (${err.message})`);
+    }
+  }
+  // The 2026-08-10 registration failure left files present but unreadable by Claude Code. Drift was
+  // advisory until a 2026-08-16 checklist run planted the pre-Plan_41 invocation — a path instead of
+  // the package command — in an installed definition: doctor kept exit 0 while every delegation
+  // would stop on a permission prompt. A definition that is not this package's is not judged healthy.
+  if (unreadable.length) {
+    return check('agents', 'fail', `Installed agent definitions cannot be read: ${unreadable.join(', ')}; run codex-bridge update --force`);
+  }
+  return mismatches.length
+    ? check('agents', 'fail', `Installed agent definitions differ from this package: ${mismatches.join(', ')}; run codex-bridge update --force`)
+    : check('agents', 'ok', `${agents.length} installed agent definition(s) match this package`);
+}
+
+function bridgeCommandCheck(result) {
+  return result.available
+    ? check('command', 'ok', `codex-bridge resolves on PATH (${result.value})`)
+    : check('command', 'warn', `codex-bridge does not resolve on PATH (${result.value}); run npm i -g @lyupro/codex-bridge`);
+}
+
 function check(key, status, value) {
   return { key, status, value };
 }
@@ -74,15 +116,22 @@ async function conventionsCheck(host) {
  * the host as seen by THIS copy. An operator comparing two diagnoses has no other way to tell them
  * apart.
  */
-function sourceCheck() {
+function packageSource() {
   const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-  const installed = root.split(/[\\/]/).includes('node_modules');
-  return check('source', 'ok', `${root} (${installed ? 'installed package' : 'clone'})`);
+  return {
+    root,
+    kind: root.split(/[\\/]/).includes('node_modules') ? 'installed copy' : 'clone',
+  };
+}
+
+function sourceCheck() {
+  const source = packageSource();
+  return check('source', 'ok', `${source.root} (${source.kind === 'installed copy' ? 'installed package' : source.kind})`);
 }
 
 /**
  * The runner asks git for the repository root before it picks a runs folder, so doctor has to
- * ask the same question: run from `src/runner`, a plain cwd would name the folder `runner` and
+ * ask the same question: run from `src/home/lib/runner`, a plain cwd would name the folder `runner` and
  * report a location no run will ever use.
  */
 function repoRoot(cwd) {
@@ -137,16 +186,52 @@ export function probeCodexBridge() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
-function hookVersion(command, record, bridgeProbe) {
+function hookVersion(command, record, bridgeResult) {
   if (command.startsWith('codex-bridge hook ')) {
-    const result = bridgeProbe();
-    return result.available ? `global command ${result.value}` : `global command unavailable (${result.value})`;
+    return bridgeResult.available
+      ? `global command ${bridgeResult.value}`
+      : `global command unavailable (${bridgeResult.value})`;
   }
   return `installed copy ${record.name}@${record.version}`;
 }
 
-async function hookChecks(host, record, bridgeProbe) {
-  return Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
+function probedVersion(result) {
+  return result.available ? result.value.match(/(\d+\.\d+\.\d+(?:[-+][^\s]+)?)\s*$/)?.[1] : null;
+}
+
+function startHook(target) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [target], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+      windowsHide: true,
+    });
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => resolve({ status: null, stderr: error.message }));
+    child.on('close', (status) => resolve({ status, stderr }));
+  });
+}
+
+function startFailure(definition, result) {
+  if (result.status === 0) return null;
+  const lines = result.stderr.trim().split(/\r?\n/);
+  const resolver = lines.find((line) => /^Error \[ERR_MODULE_NOT_FOUND\]|Cannot find module/.test(line));
+  return `${definition.file} did not start: ${resolver || lines.find(Boolean) || `exit code ${result.status}`}`;
+}
+
+async function hookChecks(host, record, bridgeProbe, ownPackage) {
+  let bridgeResult;
+  const bridge = () => {
+    bridgeResult ??= bridgeProbe();
+    return bridgeResult;
+  };
+  const starts = record ? await Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
+    return recorded ? startHook(recordTarget(host, recorded)) : null;
+  })) : [];
+  return Promise.all(HOOK_DEFINITIONS.map(async (definition, index) => {
     const key = `hook:${definition.event}`;
     if (!record) return check(key, 'warn', 'cannot check before installation');
     // The file, not just the event: PreToolUse carries two hooks of this package, and matching
@@ -174,11 +259,20 @@ async function hookChecks(host, record, bridgeProbe) {
         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)})`);
+        const problems = [startFailure(definition, starts[index])].filter(Boolean);
+        const commandVersion = form === 'short' ? bridge() : null;
+        const globalVersion = probedVersion(commandVersion || { available: false });
+        if (globalVersion && globalVersion !== ownPackage.version) {
+          problems.push(`global PATH package version ${globalVersion} differs from ${packageSource().kind} version ${ownPackage.version}`);
+        }
+        const health = problems.length ? `; ${problems.join('; ')}` : '';
+        return check(key, problems.length ? 'warn' : 'ok', `${definition.event} matcher ${definition.matcher} -> ${expected} (${form} command; ${reason}; ${hookVersion(command, record, commandVersion)}${health})`);
       }
       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)})`);
+      const failure = startFailure(definition, starts[index]);
+      const commandVersion = form === 'short' ? bridge() : null;
+      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file} (${form} command; ${hookVersion(command, record, commandVersion)}${failure ? `; ${failure}` : ''})`);
     } 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}`);
@@ -256,10 +350,14 @@ export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = pr
     !record ? 'warn' : missingFiles.length ? 'fail' : 'ok',
     !record ? 'not checked' : missingFiles.length ? `missing: ${missingFiles.join(', ')}` : `${record.files.length} installed file(s) present`,
   ));
+  const agents = await agentsCheck(host, record);
+  checks.push(agents);
   const rules = await rulesCheck(host, record);
   checks.push(rules);
   checks.push(await permissionsCheck(host));
-  checks.push(...await hookChecks(host, record, bridgeProbe));
+  const bridge = bridgeProbe();
+  checks.push(bridgeCommandCheck(bridge));
+  checks.push(...await hookChecks(host, record, () => bridge, ownPackage));
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -275,7 +373,7 @@ export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = pr
   checks.push(projectRuns);
 
   return {
-    exitCode: !record || recordBroken || missingFiles.length || rules.status === 'fail'
+    exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
       || retention.status === 'fail' || conventions.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
     checks,
     record,
@@ -285,6 +383,7 @@ export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = pr
 
 export function renderDoctor(result) {
   return result.checks.map(({ key, status, value }) => {
+    if ((key === 'agents' || key === 'command') && status !== 'ok') return value;
     const rendered = `[${status}] ${key}: ${value}`;
     return ['retention', 'conventions', 'permissions', 'liveRuns'].includes(key) && status === 'warn'
       ? `${WARNING}${rendered}${RESET}`

package/cli/frontmatter.mjs

@@ -0,0 +1,137 @@
+/**
+ * Reads and normalizes the flat frontmatter shipped by this package.
+ *
+ * The 2026-08-10 agent-registration incident showed that placeholder text can turn a previously
+ * plain YAML value into invalid syntax. Keeping this boundary deliberately flat makes host
+ * readability testable without adding a general YAML parser or changing markdown bodies.
+ */
+
+const PLAIN_START = /^(?:[-?:](?:[ \t]|$)|[,\[\]{}#&*!|>'"%@`])/;
+
+function locateFrontmatter(content) {
+  const firstBreak = content.indexOf('\n');
+  if (firstBreak === -1 || content.slice(0, firstBreak).replace(/\r$/, '') !== '---') return null;
+
+  const blockStart = firstBreak + 1;
+  let lineStart = blockStart;
+  while (lineStart <= content.length) {
+    const nextBreak = content.indexOf('\n', lineStart);
+    const lineEnd = nextBreak === -1 ? content.length : nextBreak;
+    if (content.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      return { blockStart, blockEnd: lineStart };
+    }
+    if (nextBreak === -1) break;
+    lineStart = nextBreak + 1;
+  }
+  throw new Error('frontmatter closing delimiter is missing');
+}
+
+function blockLines(block) {
+  const lines = [];
+  let start = 0;
+  while (start < block.length) {
+    const nextBreak = block.indexOf('\n', start);
+    const end = nextBreak === -1 ? block.length : nextBreak;
+    const hasCarriageReturn = block[end - 1] === '\r';
+    lines.push({
+      text: block.slice(start, hasCarriageReturn ? end - 1 : end),
+      ending: nextBreak === -1 ? '' : hasCarriageReturn ? '\r\n' : '\n',
+    });
+    if (nextBreak === -1) break;
+    start = nextBreak + 1;
+  }
+  return lines;
+}
+
+function splitEntry(line) {
+  const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(line);
+  if (!match) throw new Error(`frontmatter line is not a flat key/value entry: ${line}`);
+  const remainder = match[2];
+  if (remainder && !/^[ \t]/.test(remainder)) {
+    throw new Error(`frontmatter value for ${match[1]} must follow YAML separator whitespace`);
+  }
+  return { key: match[1], rawValue: remainder ? remainder.slice(1) : '' };
+}
+
+function decodeDoubleQuoted(value) {
+  if (!value.endsWith('"')) return null;
+  let decoded = '';
+  for (let index = 1; index < value.length - 1; index += 1) {
+    const character = value[index];
+    if (character === '"') return null;
+    if (character !== '\\') {
+      decoded += character;
+      continue;
+    }
+    const escaped = value[index + 1];
+    if (escaped !== '\\' && escaped !== '"') return null;
+    decoded += escaped;
+    index += 1;
+  }
+  return decoded;
+}
+
+function decodeSingleQuoted(value) {
+  if (!value.endsWith("'")) return null;
+  const inner = value.slice(1, -1);
+  if (/(^|[^'])'(?:[^']|$)/.test(inner)) return null;
+  return inner.replaceAll("''", "'");
+}
+
+function quotedValue(value) {
+  if (value.startsWith('"')) return decodeDoubleQuoted(value);
+  if (value.startsWith("'")) return decodeSingleQuoted(value);
+  return undefined;
+}
+
+function plainScalarIsSafe(value) {
+  return value.length > 0
+    && value === value.trim()
+    && !PLAIN_START.test(value)
+    && !/:[ \t]/.test(value)
+    && !/[ \t]#/.test(value);
+}
+
+function parseValue(rawValue) {
+  const decoded = quotedValue(rawValue);
+  if (decoded !== undefined) {
+    if (decoded === null) throw new Error('frontmatter contains an invalid quoted value');
+    return decoded;
+  }
+  if (!plainScalarIsSafe(rawValue)) {
+    throw new Error(`frontmatter contains an invalid plain scalar: ${rawValue}`);
+  }
+  return rawValue;
+}
+
+function encodeValue(value) {
+  const decoded = quotedValue(value);
+  const intended = decoded === undefined || decoded === null ? value : decoded;
+  if (decoded === undefined && plainScalarIsSafe(value)) return value;
+  return `"${intended.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+export function parseFrontmatter(content) {
+  const bounds = locateFrontmatter(content);
+  if (!bounds) return null;
+  const values = {};
+  for (const { text } of blockLines(content.slice(bounds.blockStart, bounds.blockEnd))) {
+    const { key, rawValue } = splitEntry(text);
+    if (Object.hasOwn(values, key)) throw new Error(`frontmatter contains duplicate key: ${key}`);
+    values[key] = parseValue(rawValue);
+  }
+  return values;
+}
+
+export function normalizeFrontmatter(content) {
+  const bounds = locateFrontmatter(content);
+  if (!bounds) return content;
+  const keys = new Set();
+  const normalized = blockLines(content.slice(bounds.blockStart, bounds.blockEnd)).map(({ text, ending }) => {
+    const { key, rawValue } = splitEntry(text);
+    if (keys.has(key)) throw new Error(`frontmatter contains duplicate key: ${key}`);
+    keys.add(key);
+    return `${key}: ${encodeValue(rawValue)}${ending}`;
+  }).join('');
+  return `${content.slice(0, bounds.blockStart)}${normalized}${content.slice(bounds.blockEnd)}`;
+}

package/cli/hook.mjs

@@ -1,9 +1,9 @@
 /** 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';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 
-const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'hooks');
+const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'home', 'hooks');
 const VALID_NAMES = HOOK_DEFINITIONS.map(({ name }) => name);
 
 function validNames() {

package/cli/install-record.mjs

@@ -1,8 +1,8 @@
 /** Reads, validates, and writes the installation record shared by installer commands. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { readJsonFile } from '../src/json-file.mjs';
-import { HOOK_DEFINITIONS } from '../src/hook-definitions.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 
 export const INSTALL_RECORD_NAME = '.installed.json';
 export const LEGACY_INSTALL_RECORD_NAME = '.codex-bridge-install.json';