@lyupro/codex-bridge 0.6.10 → 0.6.11

package/CHANGELOG.md

@@ -4,6 +4,87 @@ 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.11] - 2026-10-07
+
+### Changed
+
+- **Breaking for orchestrator prompts:** the order gate refuses an explicit `model` on a dispatcher
+  call, even one matching the installed pin or `inherit`. Migration cost: drop `model` from dispatcher
+  calls in orchestrator prompts; the installed agent definition owns that setting. It also refuses a
+  foreign-family `CLAUDE_CODE_SUBAGENT_MODEL` on hosts where the environment overrides the pin
+  (before 2.1.251, or with `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1` from 2.1.257). Unknown host versions or
+  unparseable families are left to the stop observation. These checks precede prompt and grant exits,
+  so a continuation cannot bypass them.
+
+- **Breaking for orchestrator prompts:** a dispatcher call is exactly one line, `task file: <absolute
+  path>`. The order — `order id`, `scope`, `scope new`, `phase`, `continue`/`retry`, `slug`, `effort`,
+  `changeset`, `repository` — goes in the header at the top of that file, and the dispatcher runs
+  `codex-bridge run --agent <type> --task-file "<path>"`. Any former label in the call is refused for
+  free with "moved to the task-file header" and the agent's header template. Migration cost: move the
+  label lines from the call into the task file's first lines. A task-file path containing `$`, `\\` or a
+  final `\` is refused, because the shell would rewrite it inside the command's double quotes and the
+  runner would open a different file than the one the gate checked; write it with forward slashes.
+
+- The four dispatcher prompts share one protocol section rendered at install from the same command
+  assembler the order gate uses: the call is `task file:` only and the command is
+  `codex-bridge run --agent <type> --task-file "<path>"`. The hand-written label-to-flag tables and the
+  instruction to add a continuation flag are gone; the header labels are listed in each agent's
+  description. Migration cost: none beyond `codex-bridge update`, which reinstalls the prompts. A
+  first call that prints no `RUN=` line (a refusal or `UNAVAILABLE`) is itself the dispatcher's answer.
+
+- A dispatcher call contains only exact `label: value` lines from the agent's input registry, in any
+  order, with blank lines allowed. Prose, unknown or another agent's labels, decorated or hyphenated
+  spellings, `--flag value` lines, duplicates, empty values, missing required labels, placeholders,
+  relative task-file paths and shell-unsafe values are refused for free before the dispatcher starts.
+  The refusal names the line, the exact spelling and every label of the agent, and says "Free text
+  belongs in the task file." Of 405 measured past calls, 47 began with prose, 112 carried lines outside
+  the registry, 18 passed values as `--order-id x`, and 1 duplicated a label.
+  Migration cost: a call written in an older form gets one free refusal naming the fix.
+
+### Added
+
+- The reply guard observes `message.model` in the dispatcher's assistant transcript entries at
+  `SubagentStop`, before its handback exits, and compares model families against the installed
+  contract agreed by every recorded owner. On 2026-09-25 a hook's `(inherit)` label was mistaken for
+  the model used, and the VS Code panel showed the parent model while transcripts showed the pinned
+  family; neither display is model evidence. A mismatch raises an alarm in the same turn and enters
+  `state/dispatcher-model.json`.
+  The order gate warns on every later call of that dispatcher type until a later match on any host;
+  uncertainty does not clear the warning. It warns rather than refusing work for a leak whose cause
+  may be another hook or the host.
+- `doctor` reports `dispatcherModel:<type>` rows for the current observed session host: the latest
+  violation is `fail` with exit 1, an undetermined observation is `warn`, and a match is `ok`, including
+  recovery after a violation. No observations is `ok`; recovered incidents and other hosts remain
+  history, without a permanent warning. An incomplete, unreadable or disagreeing installed contract
+  makes the comparison undetermined, rather than guessing which agent definition the host selected.
+
+### Fixed
+
+- The handback witness keeps per-cause observations and violation history without a permanent
+  warning. Only later evidence disproving that cause clears it, and only the current observed session
+  host contributes active warnings. Intercepted handbacks, including refused attempts, are not proof
+  of recovery. Existing witness files migrate on their next write: old untyped alarms become
+  `legacy-untyped-unverified` history, not confirmed violations; `doctor` reads them without rewriting
+  the file. This fixes the 2026-09-27 case where clean handbacks on a newer host still left an old alarm
+  as the only visible signal.
+- A subagent stop without `agent_type` alarms only with dispatcher evidence bound to that stop:
+  healthy, active dispatcher-gate state or an assistant Bash call running the standalone runner command
+  for a registered role. The 13 older alarms across nine host versions lacked that evidence. Without
+  it, a stop is undetermined, neither an accusation nor recovery, and a command's `--agent` does not
+  invent the missing host type.
+
+- The reply guard identifies a dispatcher's run by a receipt — the run folder the runner itself
+  printed to that dispatcher, recorded once by the dispatcher gate — instead of the order id in the
+  call or the newest run on disk. A reply naming another folder, a reply with a verdict but no
+  receipt, and two different folders reported to one dispatcher are blocked; the last one also turns
+  the handback into a `FAIL`.
+- `changeset:` reaches the runner, so `base:<branch>` and `commit:<sha>` review the requested changes
+  instead of silently reviewing uncommitted work.
+- `scope-new:` is refused with the exact `scope new:` spelling; it can no longer be dropped or read as
+  `scope`.
+- A `Repository root:` line is refused before the haiku dispatcher starts. It used to make the
+  dispatcher prepend `cd … &&` and leave without delegating.
+
 ## [0.6.10] - 2026-10-04
 
 ### Added

package/README.md

@@ -62,7 +62,7 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **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 **2848 automated tests: 2847 passing and 1 skipped**.
+The current suite contains **3199 automated tests: 3198 passing and 1 skipped**.
 
 ## Verify
 
@@ -93,12 +93,23 @@ Output on a healthy host (trimmed):
 
 `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. It judges contracts against the newest host version observed in a session transcript, not `claude` on `PATH`: on 2026-09-25 the VS Code extension ran sessions on 2.1.282 while `PATH` resolved to 2.1.281, and the extension's `CLAUDE_CODE_EXECPATH` and `CLAUDE_AGENT_SDK_VERSION` were inherited by every descendant `claude`. The transcript entry's `version` identifies the host. The dispatcher gate records it once per session in `state/host-observations.json` (sessions kept 7 days, hosts 30); `doctor` and `install` judge the newest observed host. `doctor` prints `sessionHost` and one `otherHost:<version>` line for each other observed version, with `ok`, `warn` and a probe command, or `fail` with exit 1. If no session has been observed, they say so instead of using `PATH`. Refusal and dispatcher contract records keep one verdict per host version, so a measurement of version V applies to every host of version V; older single-version records count only for their recorded version.
 
-`doctor` also reports `handbackWitness` and the four dispatcher contract lines (`dispatcherContract:agentIdentity`, `dispatcherContract:shellStdout`, `dispatcherContract:shellFailure`, and `dispatcherContract:agentTranscript`): verified contracts are `ok`, unknown, unprobed, or stale contracts are `warn`, and a measured change is `fail` with exit 1. Handback sightings and alarms carry the transcript version, and sightings match only that exact version; an older SDK-based record counts as no sighting while preserving its alarms. If a subagent stop has an `agent_id` but no `agent_type`, the reply guard records an alarm and tells the session that the dispatcher gate cannot recognise dispatchers. 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.
+`doctor` also reports `handbackWitness`, `dispatcherModel:<type>` rows, and the four dispatcher contract lines (`dispatcherContract:agentIdentity`, `dispatcherContract:shellStdout`, `dispatcherContract:shellFailure`, and `dispatcherContract:agentTranscript`): verified contracts are `ok`, unknown, unprobed, or stale contracts are `warn`, and a measured change is `fail` with exit 1. The witness warns only for unresolved causes on the current observed session host; later disproving evidence clears the warning while retaining history. Intercepted handbacks are not recovery evidence, and old untyped alarms without dispatcher evidence remain unverified history. A stop missing `agent_type` alarms only with dispatcher evidence for that stop. Dispatcher model rows compare transcript-observed families with the installed contract: a latest violation is `fail` with exit 1, uncertainty is `warn`, and a match, including recovery, is `ok`; no observations is also `ok`. Other hosts and recovered incidents are history, not permanent warnings. See [Response guard](docs/overview.md#response-guard) for the evidence rules. 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:
 
+The task file starts with the order header, a blank line, and the task text:
+
+```text
+order id: order-42
+repository: /abs/path/to/repository
+scope: src/auth/**,tests/auth/**
+advice: mechanical
+
+Implement the authentication change and verify it with the tests named in the task.
+```
+
 ```bash
-codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
+codex-bridge run --agent codex-build --task-file "/abs/path/to/task.md"
 ```
 
 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.
@@ -131,7 +142,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] [--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)). |
 | `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 <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. |
+| `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. |
 | `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. |

package/cli/dispatcher-model-check.mjs

@@ -0,0 +1,59 @@
+/** turns the dispatcher-model ledger into doctor rows; Plan_67 D4/D8 and D8 clarification 2026-10-07. */
+import path from 'node:path';
+import { DISPATCHER_MODEL_FILE } from '../src/home/lib/dispatcher-model.mjs';
+import { entryState } from '../src/home/lib/observation-ledger.mjs';
+import { check } from './doctor-format.mjs';
+
+function observationSummary({ data, at }) {
+  return `${data.agentType}: observed families ${data.parsed.join(', ')}, pinned family ${data.pinFamily} at ${at}`;
+}
+
+function entryCheck(entry) {
+  const observation = entry.lastObservation;
+  const { data, verdict, at } = observation;
+  const key = `dispatcherModel:${data.agentType}`;
+  const state = entryState(entry);
+  // D4: only the latest confirmed violation fails; D8 keeps uncertainty from erasing history.
+  if (verdict === 'violation') {
+    return check(key, 'fail', `${observationSummary(observation)}; Claude quota was spent on this dispatcher; see Plan_67.`);
+  }
+  if (verdict === 'undetermined') {
+    const reason = data.pinReasons?.length
+      ? data.pinReasons.join('; ') : 'no model family could be read from the transcript';
+    const unresolved = state === 'violation'
+      ? `; earlier violation (${observationSummary(entry.lastViolation)}) is not yet disproved` : '';
+    return check(key, 'warn', `${data.agentType}: model observation undetermined at ${at}: ${reason}${unresolved}.`);
+  }
+  const history = state === 'recovered'
+    ? `; recovered from earlier violation (${observationSummary(entry.lastViolation)})` : '';
+  return check(key, 'ok', `${observationSummary(observation)}; matches the installed contract${history}.`);
+}
+
+export function dispatcherModelChecks({ record, hostVersion, stateDir }) {
+  if (record?.corrupt) {
+    return [check('dispatcherModel', 'warn',
+      `The dispatcher model record is unreadable; delete ${path.join(stateDir, DISPATCHER_MODEL_FILE)} to reset it.`)];
+  }
+  const entries = Object.values(record?.entries || {});
+  const current = entries.filter((entry) => entry.lastObservation.data.hostVersion === hostVersion);
+  const rows = current.map(entryCheck);
+  if (!rows.length) {
+    rows.push(check('dispatcherModel', 'ok', 'Not observed yet — recorded when a dispatcher stops on this host.'));
+  }
+  const hosts = new Map();
+  for (const entry of entries) {
+    const version = entry.lastObservation.data.hostVersion;
+    if (version === hostVersion) continue;
+    const counts = hosts.get(version) || { entries: 0, violations: 0 };
+    counts.entries += 1;
+    if (entryState(entry) === 'violation') counts.violations += 1;
+    hosts.set(version, counts);
+  }
+  // D8: other hosts are one history sentence, never additional active warning rows.
+  if (hosts.size) {
+    const history = [...hosts].map(([version, counts]) =>
+      `${version ?? 'unknown host'}: ${counts.entries} entries, ${counts.violations} unresolved violations`);
+    rows[0].value += ` History on other hosts (historical, not current): ${history.join('; ')}.`;
+  }
+  return rows;
+}

package/cli/doctor-host-side.mjs

@@ -10,7 +10,8 @@ import path from 'node:path';
 import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
 import { check } from './doctor-format.mjs';
 import { hasPackageMarks } from './host-inspection.mjs';
-import { imageFingerprint, isFormat2 } from './install-owners.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
+import { imageFingerprint } from './install-owners.mjs';
 
 // Format 1 is not migrated here: asFormat2 would record this host as the owner, and doctor only reads.
 export function ownerEntry(rawRecord, host) {

package/cli/doctor-installation.mjs

@@ -1,111 +1,111 @@
-/** 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 './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);
+  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}`);
+  }
+}

package/cli/doctor.mjs

@@ -19,11 +19,13 @@ import {
 } from './doctor-installation.mjs';
 import { hookChecks } from './doctor-hooks.mjs';
 import { contractStatus, readHostContract } from './host-contract.mjs';
-import { handbackWitnessStatus } from './handback-witness-check.mjs';
+import { handbackWitnessStatus } from './handback-witness-check.mjs';
+import { dispatcherModelChecks } from './dispatcher-model-check.mjs';
 import { dispatcherContractStatus } from './dispatcher-contract.mjs';
 import { DISPATCHER_CONTRACT_FILE, readDispatcherContract } from './dispatcher-contract-record.mjs';
 import { PROBE_COMMAND } from './host-contract.mjs';
-import { readHandbackWitness } from '../src/home/lib/handback-witness.mjs';
+import { readHandbackWitness } from '../src/home/lib/handback-witness.mjs';
+import { readDispatcherModel } from '../src/home/lib/dispatcher-model.mjs';
 import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { readHostObservations } from '../src/home/lib/host-observations.mjs';
 import { otherHostCheck, sessionHostCheck, sessionHostVersions } from './session-hosts.mjs';
@@ -82,7 +84,8 @@ export async function diagnose({
   launcherProbe,
   currentPackage,
   contractRecord,
-  handbackWitnessRecord,
+  handbackWitnessRecord,
+  dispatcherModelRecord,
   dispatcherContractRecord,
   hostVersion,
   observations,
@@ -162,7 +165,12 @@ export async function diagnose({
     hostVersion: detectedHostVersion,
     stateDir,
   });
-  checks.push(check('handbackWitness', ['seen', 'unobserved'].includes(witness.state) ? 'ok' : 'warn', witness.message));
+  checks.push(check('handbackWitness', ['violation', 'unreadable'].includes(witness.state) ? 'warn' : 'ok', witness.message));
+  checks.push(...dispatcherModelChecks({
+    record: dispatcherModelRecord === undefined ? readDispatcherModel({ stateDir }) : dispatcherModelRecord,
+    hostVersion: detectedHostVersion,
+    stateDir,
+  }));
   const dispatcherRecord = dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord;
   checks.push(...dispatcherContractChecks({
     record: dispatcherRecord,
@@ -190,7 +198,7 @@ export async function diagnose({
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
       || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
       || projectRuns.status === 'fail'
-      || checks.some((item) => /^(hook|dispatcherContract):/.test(item.key) && item.status === 'fail')
+      || checks.some((item) => /^(hook|dispatcherContract|dispatcherModel):/.test(item.key) && item.status === 'fail')
       || checks.some((item) => item.key.startsWith('otherHost:') && item.status === 'fail') ? 1 : 0,
     checks,
     record,

package/cli/handback-witness-check.mjs

@@ -1,31 +1,37 @@
 /** Surfaces handback drift; 2026-09-25 established exact host transcript versions as identity. */
 import path from 'node:path';
 import { WITNESS_FILE } from '../src/home/lib/handback-witness.mjs';
+import { entryState } from '../src/home/lib/observation-ledger.mjs';
 
 export function handbackWitnessStatus({ record, hostVersion, stateDir }) {
   if (record?.corrupt) {
     return { state: 'unreadable', message: `The handback witness is unreadable; delete ${path.join(stateDir, WITNESS_FILE)} to reset it.` };
   }
-  if (record?.alarms?.length > 0) {
-    const alarm = record.alarms.at(-1);
+  const entries = Object.values(record?.ledger?.entries || {});
+  const violations = entries.filter((entry) => entryState(entry) === 'violation'
+    && entry.lastObservation.data.hostVersion === hostVersion);
+  if (violations.length > 0) {
+    const details = violations.map((entry) => {
+      const { data, detail, at } = entry.lastViolation;
+      return `${data.cause}${data.agentType ? ` / ${data.agentType}` : ''}: ${detail} at ${at}`;
+    });
     return {
-      state: 'alarm',
-      message: `${record.alarms.length} dispatcher alarm(s); newest on ${alarm.hostVersion ?? 'unknown host'}: ${alarm.detail} at ${alarm.at}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
+      state: 'violation',
+      message: `Dispatcher violation(s) on host ${hostVersion ?? 'unknown host'}: ${details.join('; ')}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
     };
   }
-  if (!record?.lastSeen || Object.keys(record.lastSeen).length === 0) {
-    return { state: 'unobserved', message: 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.' };
+  const intercepted = record?.intercepted?.[hostVersion || 'unknown'];
+  let message = intercepted
+    ? `Newest intercepted handback on host ${hostVersion ?? 'unknown host'} at ${intercepted}.`
+    : 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.';
+  const recovered = entries.filter((entry) => entryState(entry) === 'recovered').length;
+  const historical = entries.filter((entry) => entryState(entry) === 'violation'
+    && entry.lastObservation.data.hostVersion !== hostVersion).length;
+  const legacy = record?.legacy || [];
+  if (recovered || historical || legacy.length) {
+    const untyped = legacy.filter((entry) => entry.disposition === 'legacy-untyped-unverified').length;
+    const unclassified = legacy.filter((entry) => entry.disposition === 'unclassified').length;
+    message += ` History: ${recovered} recovered entries; ${historical} unresolved entries on other hosts (historical, not current); ${untyped} older alarms without dispatcher evidence, kept for history (legacy-untyped-unverified); ${unclassified} unclassified legacy entries.`;
   }
-
-  if (record.lastSeen[hostVersion]) {
-    return { state: 'seen', message: `Handback contract last seen on host ${hostVersion} at ${record.lastSeen[hostVersion]}.` };
-  }
-  const [newest, iso] = Object.entries(record.lastSeen).sort((left, right) => right[1].localeCompare(left[1]))[0];
-  if (newest) {
-    return {
-      state: 'stale',
-      message: `Handback contract last seen on host ${newest} at ${iso}, not yet on host ${hostVersion}; it is recorded the next time a dispatcher runs in an interactive session on that host.`,
-    };
-  }
-  return { state: 'unobserved', message: 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.' };
+  return { state: 'ok', message };
 }

package/cli/hosts.mjs

@@ -2,7 +2,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
+import { claudePaths } from '../src/home/lib/claude-layout.mjs';
 
 function repositoryRoot(start) {
   let current = path.resolve(start);
@@ -14,15 +15,6 @@ function repositoryRoot(start) {
   }
 }
 
-function claudePaths(root) {
-  return {
-    agentsDir: path.join(root, 'agents', 'codex-bridge'),
-    commandsDir: path.join(root, 'commands', 'codex-bridge'),
-    legacyAgentsDir: path.join(root, 'agents', 'codex'),
-    legacyCommandsDir: path.join(root, 'commands', 'codex'),
-  };
-}
-
 export function resolveHost({
   scope = 'user',
   host,

package/cli/install-owners.mjs

@@ -11,6 +11,7 @@
  */
 import { createHash } from 'node:crypto';
 import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
 import {
   fileEntry,
   INSTALL_METHOD_COPY,
@@ -20,10 +21,6 @@ import {
 
 const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 
-export function isFormat2(parsed) {
-  return isObject(parsed) && parsed.format === 2;
-}
-
 export function imageFingerprint(image) {
   const brand = image.fingerprints?.brand;
   if (brand === undefined) return null;

package/cli/install-record.mjs

@@ -4,7 +4,8 @@ import { randomUUID } from 'node:crypto';
 import { createHomeWriter } from '../src/home/lib/home-write.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
-import { isFormat2, ownerView, validateFormat2, withOwner, withoutOwner } from './install-owners.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
+import { ownerView, validateFormat2, withOwner, withoutOwner } from './install-owners.mjs';
 
 /**
  * The record's own spelling of the field saying how the package was installed, and its one value.

package/cli/inventory-transition.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { askYesNo, isInteractive } from './terminal-question.mjs';
-import { isFormat2 } from './install-owners.mjs';
+import { isFormat2 } from '../src/home/lib/install-owner-roots.mjs';
 import { readInstallRecordFile } from './install-record.mjs';
 import { normalizedRulesOwner, readRulesRegistry } from './rules-owners.mjs';