@lyupro/codex-bridge 0.6.12 → 0.6.14

package/CHANGELOG.md

@@ -4,6 +4,111 @@ 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).
 
+## [0.6.14] - 2026-10-11
+
+### Added
+
+- Install and update place an always-loaded delegation core in the Claude Code host's
+  `rules/codex-bridge/core.md`: under `~/.claude/` for user scope or `<project>/.claude/` for
+  project scope. It has no `paths` frontmatter and stays within 2,400 characters, so the short
+  contract reaches every session without loading all the detailed guidance. This is separate
+  from the Codex execpolicy file. Uninstall removes package or recorded core bytes and the empty
+  package subfolder; edited or unknown files and links are kept and named, and the host's own
+  `rules/` folder stays.
+- The `doctor` row `claudeRules` checks the installed core against the package: missing or
+  differing bytes are `fail`, with `codex-bridge update --force` as the remedy; before installation
+  it is `warn`. A deleted or edited core previously left the installation looking healthy.
+- An observing `InstructionsLoaded` hook records session-start core paths and hashes in
+  `<home>/state/load-witness.json` without blocking host actions. The `doctor` rows
+  `claudeRulesLoad:<host version>` require the latest load at this owner's exact core path to
+  match the package hash, using the version from that same session's transcript. Missing, stale,
+  unreadable or oversized evidence is `warn`, never proof of a load failure; open a new Claude
+  Code session and rerun `doctor`. A newer differing or oversized load cannot be cleared by an
+  older match, and core reads are bounded to 7,200 bytes plus one overflow byte.
+- Each run row in `codex-bridge projects <project> --json` includes `path`, the absolute run
+  folder, so orchestrators can find earlier artifacts and write an `advice:` address without
+  deriving the run store from the package's installation directory.
+- Maintainers prove before a release, with
+  `npm run release-check:rules-load-claude -- --model <model>`, that both `claude` on `PATH` and
+  the VS Code extension's binary load a real project install's core. The script lives in the
+  repository and is not part of the npm package. Each target gets an isolated throwaway project; its exact core path, frozen hash and session host
+  version must match, and the check guards the operator's installation and cleans up its trees.
+  Attempts are saved to `docs/audits/release-checks/rules-load-claude.json` by default. Exit 0
+  means both targets verified, 1 means a failure, and 2 means inconclusive without a failure;
+  missing evidence blocks the release, and an oversized core fails it. The check does not start
+  Codex, because the earlier manual check raised a UAC prompt while trying to measure Claude.
+- `doctor` probes `sandbox:read-only` and `sandbox:workspace-write` sequentially before an
+  order first discovers a dead Codex sandbox: `ok` means alive, `fail` means dead with exit 1,
+  and inconclusive or unsupported checks are `warn`. Both a dead-sandbox row and an order's
+  pre-start refusal print the diagnosis from Codex's sandbox log and `setup_error.json`, because
+  the TradeForge refusal said only "setup refresh had errors" while the log named a locked
+  runtime file. Only lines attributed to the probe justify a repair signature for a locked
+  runtime file or corrupt deny-read state; other evidence stays raw with "No verified repair
+  signature". Unreadable logs do not change the verdict, and the package does not repair the host.
+
+- `codex-bridge guidance [<topic>]` prints the package's detailed rules for one topic; without a
+  topic it lists `order`, `advisor`, `budget`, `records` and `concurrency`. The rules core sends
+  the orchestrator here before it writes a task file and tells it to stop and show the output if
+  the command fails, so orchestrator prompts need no change. Text comes from the installed home
+  rather than the clone, because the seeded-config incident exposed that difference; unknown
+  topics or extra arguments exit 2, and an unreadable topic exits 1 and names `codex-bridge update`.
+
+### Changed
+
+- **Breaking for orchestrator prompts:** `UNAVAILABLE` now means a measured sign-out, not a
+  missing `codex` on `PATH`. A lookup miss is checked again after about a second; a second miss
+  is a free pre-start refusal starting "Codex CLI readiness unconfirmed", with exit 1 and no
+  run folder. Migration cost: replace the missing-CLI skip rule with checks of `codex --version`
+  for up to about two minutes, then repeat the same order exactly once if it answers. Otherwise,
+  or if that repeat gets the same refusal, hand the order to the next executor and name the
+  handoff in the summary; no second repeat. An npm update briefly rewrote the Codex shim and
+  caused an orchestrator to drop the bridge for the whole session.
+
+### Fixed
+
+- **Breaking for operators:** update refuses an unrecorded file at a newly planned path instead
+  of silently overwriting operator text, including the host rules core. The refusal names the
+  `unowned` path. Migration cost: review that file and use `--force` only if replacement is
+  intended; identical bytes are adopted without it. The existing migration for the package's
+  Codex rules file remains available to records from before rules were recorded.
+- Sandbox checks are bounded, and an inconclusive read-only check skips the workspace-write
+  check so a timed-out setup cannot race another probe. `codex --version` is also bounded.
+  Diagnosis reads only regular files in a real `.sandbox` folder, rejecting linked folders,
+  linked logs and special files that could redirect evidence or hang before a probe starts.
+
+## [0.6.13] - 2026-10-08
+
+### Added
+
+- `codex-bridge runs move [--dry-run]` moves run records from `~/.claude/codex-runs/` to
+  `~/.lyupro/.codex-bridge/runs/`. It refuses while a run is live, copies every record, verifies
+  each file by SHA-256, imports the old repository's `codex-runs` git history, and writes
+  `state/runs-root.json` last. Only this command writes the move record. It offers to remove the
+  old folder only when every file in it has an identical copy in the new store. Like
+  `uninstall --purge --dry-run`, a dry run names every refusal and still shows the counts, since
+  some project is nearly always running when the operator plans the move.
+- A finished run autocommits its own folder and the project marker when the git repository top
+  is the run store or package home. It never commits into a foreign repository such as
+  `~/.claude`, and a commit failure does not change the run verdict. On 2026-10-07 run records
+  left thousands of uncommitted files in that foreign repository; a session-close gate listed
+  each one.
+- Paths under a retired run root are refused before anything is opened or created, including
+  `advice:`, `codex-bridge read`, `stop`, and a stale `CODEX_RUNS_ROOT` in the launcher. The refusal
+  names the equivalent new path; nothing is remapped and no quota is spent.
+- The `repository:` task header must name an existing absolute directory without any path
+  segment ending in a dot or space.
+
+### Changed
+
+- The default run root is now `~/.lyupro/.codex-bridge/runs/` after a move or on a fresh install
+  where `~/.claude/codex-runs/` does not exist. A trimmed, non-empty `CODEX_RUNS_ROOT` takes
+  precedence; otherwise an existing old folder remains the root while the move is pending.
+- The `doctor` `runsRoot` line shows the selected root, its source, and warnings for a pending
+  move, an old folder still present, or a root inside a foreign git repository. `.git` is not
+  counted as a project.
+- Run records are user data. Uninstall and `--purge` preserve the package home's `runs/` folder
+  and the old `~/.claude/codex-runs/` folder.
+
 ## [0.6.12] - 2026-10-07
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # codex-bridge
 
-**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — seven host guards, zero runtime dependencies, zero build steps.**
+**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — eight 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)
@@ -32,8 +32,8 @@ Use `--scope project` to install the Claude Code-facing files under `<repo>/.cla
 
 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 four agents (`codex-scout`, `codex-build`, `codex-review`, `codex-advisor`), two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
+- `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, the installation record, and run records under `runs/` as user data.
+- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the four agents (`codex-scout`, `codex-build`, `codex-review`, `codex-advisor`), two slash commands, and merged hook registrations in `settings.json`. Before the move, existing run records remain in `~/.claude/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.
@@ -43,7 +43,7 @@ Before every `settings.json` write, the existing file is backed up. Existing set
 
 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.
+Run records in `~/.lyupro/.codex-bridge/runs/` (or `~/.claude/codex-runs/` before the move) are user data. Uninstall, including `--purge`, never removes either folder.
 
 ## Requirements
 
@@ -57,12 +57,12 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **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.
-- **7 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway; `dispatcher-gate` lets a dispatcher run only the one runner command of its order and hands its caller the runner's own words.
+- **8 host guards enforce and witness the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway; `dispatcher-gate` lets a dispatcher run only the one runner command of its order and hands its caller the runner's own words; `load-witness` only observes — it records that the host loaded the package's rules core, the one proof `doctor` accepts that the rules are in context.
 - **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 **3267 automated tests: 3266 passing and 1 skipped**.
+The current suite contains **3654 automated tests: 3651 passing and 3 skipped**.
 
 ## Verify
 
@@ -87,7 +87,7 @@ Output on a healthy host (trimmed):
 [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] runsRoot: ~/.lyupro/.codex-bridge/runs (default)
 [ok] liveRuns: 0 runs working right now
 ```
 
@@ -140,11 +140,13 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `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] [--purge]` | Remove recorded package files while preserving run artifacts; `--purge` also deletes your data and the home after one preflight and two consents (see [Uninstall and purge](docs/overview.md#uninstall-and-purge)). |
+| `uninstall [--scope user\|project] [--host <path>] [--dry-run] [--purge]` | Remove recorded package files while preserving run artifacts; `--purge` also deletes other operator data after one preflight and two consents, preserving `runs/` and its containing home (see [Uninstall and purge](docs/overview.md#uninstall-and-purge)). |
 | `inventory confirm [--scope user\|project] [--host <path>] [--dry-run]` | Confirm in a terminal that the recorded hosts are all the hosts using this home; until then the dispatcher model pin stays undetermined and `doctor` names this command. Changes only the inventory mark of the installation record. |
+| `runs move [--dry-run]` | Copy every run record from `~/.claude/codex-runs/` into `~/.lyupro/.codex-bridge/runs/`, verify each file by SHA-256, import the old repository's `codex-runs` git history, and write the move record last. Refused while a run is live (`--dry-run` names the refusal and still previews); offers to remove the old folder only when every file has an identical copy in the new store. |
 | `doctor [--scope user\|project] [--host <path>] [--probe-contract] [--probe-executable <path>]` | Diagnose the selected host and Codex connection, including the handback witness and four dispatcher contract lines. `--probe-contract` targets the newest observed host, accepting `CLAUDE_CODE_EXECPATH` or `claude` on `PATH` only when each reports that version with `--version`; use `--probe-executable <path>` to name an executable (`--host` selects the Claude Code configuration). The probe prints its target and records nothing if the completed host run reports another transcript version. |
 | `run --agent <type> --task-file "<abs path>" [--no-wait]` | Start or attach to a delegated run through the permission-stable package command. The task-file header carries the whole order; its body carries the statement, scout questions and verification command. Its path must be absolute and use forward slashes; `$`, doubled backslashes and a final backslash are refused. Every other runner flag is a free refusal; stdin is not an input channel. |
 | `model [list\|set\|unset\|speed]` | Show the model, effort, pinned speed tier and provenance of each role, with the config path; `model list` prints the live catalogue from Codex, hidden models included and marked; `model set <role> <model> [effort]` checks the pair and any retained speed tier against that model's catalogue entry, and `model unset <role>` removes the profile. `model speed <role> <tier>` previews a live accelerated tier and its quoted cost description; repeat with trailing `confirm` to pin it. `model speed <role> unset` removes only speed, without confirmation. The profile is machine-wide, shared by every project on this machine. |
+| `guidance [<topic>]` | Print the package's detailed rules for one topic from the installed home; without a topic, list the topics. The always-loaded rules core routes the orchestrator here. |
 | `projects [<name>] [--json]` | List projects or runs in the run store. |
 | `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
 | `unlock [<project>\|--all]`<br>`unlock --lifecycle [--clear]` | Close records whose runner is gone, or show who holds the lock that serializes install, update and uninstall of this home; `--clear` removes that lock only when it is a file left by a holder proven dead (macOS; Windows and Linux locks are released by the kernel). |

package/cli/command-registry.mjs

@@ -4,17 +4,21 @@
  * dispatch and usage had separate sources. One registry keeps invocation and help together.
  */
 import { diagnose, renderDoctor } from './doctor.mjs';
+import { sandboxChecks } from './doctor-sandbox.mjs';
 import { probeContract } from './probe-contract.mjs';
 import { resolveProbeTarget } from './probe-target.mjs';
 import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { hook } from './hook.mjs';
+import { guidance } from './guidance.mjs';
 import { resolveHost } from './hosts.mjs';
-import { install } from './install.mjs';
+import { install } from './install.mjs';
 import { inventoryConfirm } from './inventory-confirm.mjs';
 import { model } from './model.mjs';
 import { projects } from './projects.mjs';
 import { read } from './read.mjs';
 import { runCodex } from './run-launcher.mjs';
+import { runsMove } from './runs-move.mjs';
+import { removeOldStore } from './runs-move-remove.mjs';
 import { permissions } from './permissions.mjs';
 import { prune } from './prune.mjs';
 import { stop } from './stop.mjs';
@@ -26,8 +30,8 @@ import { update } from './update.mjs';
 export function commandOptions(command, argv) {
   const options = {};
   const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
-    : command === 'uninstall' ? new Set(['--dry-run', '--purge'])
-      : command === 'inventory' ? new Set(['--dry-run'])
+    : command === 'uninstall' ? new Set(['--dry-run', '--purge'])
+      : command === 'inventory' || command === 'runs' ? new Set(['--dry-run'])
       : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
   const flagNames = new Map([
     ['--dry-run', 'dryRun'],
@@ -41,6 +45,7 @@ export function commandOptions(command, argv) {
       options[flagNames.get(arg)] = true;
       continue;
     }
+    if (command === 'runs') throw new Error(`unknown runs option "${arg}"`);
     if (arg !== '--scope' && arg !== '--host' && !(command === 'doctor' && arg === '--probe-executable')) throw new Error(`unknown ${command} option "${arg}"`);
     const value = argv[index + 1];
     if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
@@ -125,20 +130,44 @@ export const COMMANDS = [
     },
   },
   {
-    name: 'inventory',
-    summary: 'Confirm that the recorded hosts are all the hosts using this home',
-    usage: ['codex-bridge inventory confirm [--scope user|project] [--host <path>] [--dry-run]'],
-    section: 'public',
-    async handler(argv, io) {
-      if (argv[0] !== 'confirm') throw new Error(`unknown inventory action "${argv[0] ?? ''}"`);
-      const options = commandOptions('inventory', argv.slice(1));
-      const host = resolveHost(options);
-      const result = await inventoryConfirm({ host, dryRun: options.dryRun });
-      io.log(result.output);
-      return result.exitCode;
-    },
-  },
-  {
+    name: 'inventory',
+    summary: 'Confirm that the recorded hosts are all the hosts using this home',
+    usage: ['codex-bridge inventory confirm [--scope user|project] [--host <path>] [--dry-run]'],
+    section: 'public',
+    async handler(argv, io) {
+      if (argv[0] !== 'confirm') throw new Error(`unknown inventory action "${argv[0] ?? ''}"`);
+      const options = commandOptions('inventory', argv.slice(1));
+      const host = resolveHost(options);
+      const result = await inventoryConfirm({ host, dryRun: options.dryRun });
+      io.log(result.output);
+      return result.exitCode;
+    },
+  },
+  {
+    name: 'runs',
+    summary: 'Move run records into the package home (Plan_77)',
+    usage: ['codex-bridge runs move [--dry-run]'],
+    section: 'public',
+    actions: {
+      move: {
+        summary: 'Move run records into the package home (Plan_77)',
+        usage: ['codex-bridge runs move [--dry-run]'],
+      },
+    },
+    async handler(argv, io) {
+      if (argv[0] !== 'move') throw new Error(`unknown runs action "${argv[0] ?? ''}"`);
+      const options = commandOptions('runs', argv.slice(1));
+      const result = runsMove({ dryRun: options.dryRun });
+      io.log(result.output);
+      if (result.exitCode === 0 && result.oldStore) {
+        const removal = await removeOldStore({ from: result.oldStore, to: result.homeRoot });
+        io.log(removal.output);
+        return removal.exitCode;
+      }
+      return result.exitCode;
+    },
+  },
+  {
     name: 'doctor',
     summary: 'Diagnose the selected Claude Code host (--probe-contract measures on a live host)',
     usage: ['codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract] [--probe-executable <path>]'],
@@ -160,7 +189,7 @@ export const COMMANDS = [
           io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);
         }
       }
-      const result = await diagnose({ host });
+      const result = await diagnose({ host, sandbox: sandboxChecks });
       io.log(renderDoctor(result));
       // An inconclusive probe wrote nothing and measured nothing; exiting 0 would let a failed
       // measurement pass silently in a script (Plan_52 D26).
@@ -248,6 +277,18 @@ export const COMMANDS = [
       return result.exitCode;
     },
   },
+  {
+    name: 'guidance',
+    summary: "Print the package's detailed rules for one topic",
+    usage: ['codex-bridge guidance [<topic>]'],
+    section: 'public',
+    async handler(argv, io) {
+      const result = guidance(argv);
+      if (result.exitCode === 2) io.error(result.output);
+      else io.log(result.output);
+      return result.exitCode;
+    },
+  },
   {
     name: 'read',
     summary: "Render a run's structured event stream",

package/cli/doctor-installation.mjs

@@ -1,111 +1,132 @@
-/** Reports whether what this package installed into the host still matches the package. */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import {
-  buildInstallPlan,
-  contentFingerprint,
-  fileFingerprint,
-} from './manifest.mjs';
-import { plannedContent } from './copy.mjs';
-import { RULE_LIST_NAMES, inspectPermissions } from './permissions.mjs';
-import { readRulesRegistry } from './rules-owners.mjs';
-import { parseFrontmatter } from '../src/home/lib/frontmatter.mjs';
-import { check } from './doctor-format.mjs';
-
-export async function exists(target) {
-  try {
-    await fs.access(target);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function isFile(target) {
-  try {
-    return (await fs.stat(target)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-export 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`);
-}
-
-export async function conventionsCheck(host) {
-  const file = host.brandConventionsPath;
-  let content;
-  try {
-    content = await fs.readFile(file, 'utf8');
-  } catch (err) {
-    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
-    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
-  }
-  return content.trim()
-    ? check('conventions', 'ok', `${file} (found)`)
-    : check('conventions', 'warn', `${file} (found but empty)`);
-}
-
-export async function rulesCheck(host, record) {
-  if (!record) return check('rules', 'warn', 'cannot check before installation');
-  if (!record.rules) {
-    return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
-  }
-  let registry;
-  try {
-    registry = await readRulesRegistry(host);
-  } catch (err) {
-    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
-    return check('rules', 'fail', err.message);
-  }
-  const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
-  const fingerprint = await fileFingerprint(record.rules.path);
-  if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
-  return fingerprint === record.rules.fingerprint
-    ? check('rules', 'ok', `${record.rules.path} (matches record${ownerNote})`)
-    : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
-}
-
-export 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 ${RULE_LIST_NAMES}${shadow})`);
-  } catch (err) {
-    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
-  }
-}
+/** Reports whether what this package installed into the host still matches the package. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  buildInstallPlan,
+  contentFingerprint,
+  fileFingerprint,
+} from './manifest.mjs';
+import { plannedContent } from './copy.mjs';
+import { RULE_LIST_NAMES, inspectPermissions } from './permissions.mjs';
+import { readRulesRegistry } from './rules-owners.mjs';
+import { parseFrontmatter } from '../src/home/lib/frontmatter.mjs';
+import { check } from './doctor-format.mjs';
+
+export async function exists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isFile(target) {
+  try {
+    return (await fs.stat(target)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export 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);
+  // Selected by where the file lands, not by where it comes from: Plan_64 B1 moved the sources
+  // under src/claude/, a source-path pattern matched nothing, and this check reported
+  // "0 installed agent definition(s) match" as ok.
+  const agents = plan.filter((item) => path.dirname(item.target) === host.agentsDir && item.target.endsWith('.md'));
+  if (agents.length === 0) return check('agents', 'fail', 'This package plans no agent definitions; the package tree is broken');
+  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`);
+}
+
+export async function claudeRulesCheck(host, record) {
+  if (!record) return check('claudeRules', 'warn', 'Host rules were not checked; run codex-bridge install');
+  const plan = await buildInstallPlan(host);
+  // Plan_64 B1: source-path selection hid an empty plan as a healthy installation.
+  const rules = plan.filter((item) => path.dirname(item.target) === host.rulesDir);
+  if (rules.length === 0) return check('claudeRules', 'fail', 'This package plans no host rules; the package tree is broken');
+  const mismatches = [];
+  for (const item of rules) {
+    const expected = contentFingerprint(await plannedContent(item, host.brandRoot));
+    if (await fileFingerprint(item.target) !== expected) mismatches.push(path.basename(item.target));
+  }
+  // Plan_64 B3: equal bytes imply no paths frontmatter; tests/claude-rules-core.test.mjs guards the package core.
+  return mismatches.length
+    ? check('claudeRules', 'fail', `Host rules differ from this package or are missing: ${mismatches.join(', ')}; run codex-bridge update --force`)
+    : check('claudeRules', 'ok', `${rules.length} host rules file(s) match this package`);
+}
+
+export async function conventionsCheck(host) {
+  const file = host.brandConventionsPath;
+  let content;
+  try {
+    content = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return check('conventions', 'ok', `${file} (not found; optional)`);
+    return check('conventions', 'fail', `cannot read ${file}: ${err.message}`);
+  }
+  return content.trim()
+    ? check('conventions', 'ok', `${file} (found)`)
+    : check('conventions', 'warn', `${file} (found but empty)`);
+}
+
+export async function rulesCheck(host, record) {
+  if (!record) return check('rules', 'warn', 'cannot check before installation');
+  if (!record.rules) {
+    return check('rules', 'warn', 'rules were not installed by this installation; install or update will add them');
+  }
+  let registry;
+  try {
+    registry = await readRulesRegistry(host);
+  } catch (err) {
+    // Keep every diagnostic visible: package removal on a broken registry left the host without its watchdog.
+    return check('rules', 'fail', err.message);
+  }
+  const ownerNote = registry?.owners.length > 1 ? `; ${registry.owners.length} owners` : '';
+  const fingerprint = await fileFingerprint(record.rules.path);
+  if (!fingerprint) return check('rules', 'fail', `${record.rules.path}${ownerNote ? ` (${registry.owners.length} owners)` : ''}`);
+  return fingerprint === record.rules.fingerprint
+    ? check('rules', 'ok', `${record.rules.path} (matches record${ownerNote})`)
+    : check('rules', 'warn', `${record.rules.path} (modified after installation${ownerNote})`);
+}
+
+export 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 ${RULE_LIST_NAMES}${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}