@lyupro/codex-bridge 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -4,6 +4,46 @@ 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.7] - 2026-09-25
+
+### Added
+
+- The dispatcher gate allows only the single `codex-bridge run …` command derived from its order, and
+  hands back the runner's own words. After a handback is delivered, the dispatcher cannot keep
+  working; its stop is audited for calls the gate missed, teammate launches are refused, and the
+  reply guard looks up runs for that order. A dispatcher had written code itself and returned its
+  own `OK`, while another writer started in the same tree.
+- `doctor --probe-contract` measures the four host behaviours the dispatcher gate relies on in one
+  host run. `doctor` prints four `dispatcherContract:` lines and a handback witness line, so a
+  changed or missing host contract is visible instead of silently weakening the gate.
+
+### Changed
+
+- Package state and hook diagnostics now live under `~/.lyupro/.codex-bridge/state/` instead of
+  `~/.claude/logs/`; `update` removes the three legacy files so one package no longer splits its
+  state across another product's logs directory.
+
+### Fixed
+
+- `codex-bridge hook` and `codex-bridge run` now launch the installed home copy. The installer uses
+  the short hook command only when PATH proves it serves that home, `update` rewrites registrations
+  in an unsafe form, and `doctor` fails them. Launcher failures exit 1, not 2: a global older
+  command once rejected newly registered guard names and refused every shell call on the machine.
+- Windows child processes no longer open console windows during delegated runs; visible windows had
+  flashed for each process used to snapshot or inspect the repository and host.
+- Advisor evidence now names locations as a list, and only an `OK` judged `advise` pass authorizes
+  a build. Real citations had failed because multiple addresses were folded into one string, while
+  a scope pass or an advice the judge had failed still counted as the second opinion a build needs.
+- The published `bin` entries use the spelling npm publishes. Publishing 0.6.6 logged both CLI entries
+  as invalid and removed; the registry kept them, but a release log saying so had to be checked by
+  hand every time.
+- `uninstall` now names every kind of file it leaves in the package home, including runtime state,
+  host refusal measurements and conventions; complete removal still requires deleting those files
+  by hand.
+
+After installing 0.6.7, run `codex-bridge update` once to rewrite hook registrations to the safe form
+and register the dispatcher gate; releases up to 0.6.6 cannot launch the new guard names.
+
 ## [0.6.6] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # codex-bridge
 
-**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
+**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — seven 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)
@@ -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.
-- **6 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.
+- **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.
 - **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 **1501 automated tests: 1500 passing and 1 skipped**.
+The current suite contains **1636 automated tests: 1635 passing and 1 skipped**.
 
 ## Verify
 
@@ -91,7 +91,7 @@ Output on a healthy host (trimmed):
 [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.
+`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 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. 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:
 
@@ -128,7 +128,7 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
 | `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
 | `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
-| `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection. `--probe-contract` measures on a live host whether it still honours a hook refusal, and records the answer. |
+| `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection, including the handback witness and four dispatcher contract lines. `--probe-contract` measures refusal and dispatcher contracts in one live host run and records them when the host completes it. |
 | `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. |
 | `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. |

package/bin/codex-bridge.mjs

@@ -1,138 +1,141 @@
-#!/usr/bin/env node
-/** Dispatches codex-bridge CLI arguments to focused command modules. */
-import { diagnose, renderDoctor } from '../cli/doctor.mjs';
-import { probeContract } from '../cli/probe-contract.mjs';
-import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
-import { hook } from '../cli/hook.mjs';
-import { resolveHost } from '../cli/hosts.mjs';
+#!/usr/bin/env node
+/** Dispatches codex-bridge CLI arguments to focused command modules. */
+import { diagnose, renderDoctor } from '../cli/doctor.mjs';
+import { probeContract } from '../cli/probe-contract.mjs';
+import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
+import { hook } from '../cli/hook.mjs';
+import { resolveHost } from '../cli/hosts.mjs';
 import { install } from '../cli/install.mjs';
 import { model } from '../cli/model.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';
-import { stop } from '../cli/stop.mjs';
-import { unlock } from '../cli/unlock.mjs';
-import { uninstall } from '../cli/uninstall.mjs';
-import { update } from '../cli/update.mjs';
-
-export const HELP = `codex-bridge — Claude Code dispatchers for Codex
-
-Usage:
-  codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
-  codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
-  codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
-  codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
-  codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract]
+import { read } from '../cli/read.mjs';
+import { runCodex } from '../cli/run-launcher.mjs';
+import { packageInfo } from '../cli/manifest.mjs';
+import { permissions } from '../cli/permissions.mjs';
+import { prune } from '../cli/prune.mjs';
+import { stop } from '../cli/stop.mjs';
+import { unlock } from '../cli/unlock.mjs';
+import { uninstall } from '../cli/uninstall.mjs';
+import { update } from '../cli/update.mjs';
+
+export const HELP = `codex-bridge — Claude Code dispatchers for Codex
+
+Usage:
+  codex-bridge install [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge update [--scope user|project] [--host <path>] [--dry-run] [--force]
+  codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
+  codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
+  codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract]
   codex-bridge run <runner options> --task-file <path>
   codex-bridge model [list]
   codex-bridge projects [<name>] [--json]
-  codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
-  codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
-  codex-bridge unlock [<project>|--all]
-  codex-bridge read <run>
-  codex-bridge stop <run>
-  codex-bridge hook <name>
-  codexb <same command forms as codex-bridge>
-  codex-bridge --help
-  codex-bridge --version
-
-Commands:
-  install   Install codex-bridge into the selected Claude Code host
-  update    Update a recorded codex-bridge installation
-  permissions Show, add, or remove optional shell permission rules
-  uninstall Remove installed files while preserving run artifacts
-  doctor    Diagnose the selected Claude Code host (--probe-contract measures on a live host)
+  codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
+  codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
+  codex-bridge unlock [<project>|--all]
+  codex-bridge read <run>
+  codex-bridge stop <run>
+  codex-bridge hook <name>
+  codexb <same command forms as codex-bridge>
+  codex-bridge --help
+  codex-bridge --version
+
+Commands:
+  install   Install codex-bridge into the selected Claude Code host
+  update    Update a recorded codex-bridge installation
+  permissions Show, add, or remove optional shell permission rules
+  uninstall Remove installed files while preserving run artifacts
+  doctor    Diagnose the selected Claude Code host (--probe-contract measures on a live host)
   run       Start or attach to a delegated Codex run
   model     Show machine-wide model profiles or list the live catalogue
   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
-  read      Render a run's structured event stream
-  stop      Stop a running Codex run and record FAIL
-
-Hook dispatch:
-  codex-bridge hook <name>  Dispatch a registered guard with stdin unchanged`;
-
-const HOOK_COMMAND = 'hook';
-
-export function commandOptions(command, argv) {
-  const options = {};
-  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
-    : command === 'uninstall' ? new Set(['--dry-run'])
-      : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
-  const flagNames = new Map([
-    ['--dry-run', 'dryRun'],
-    ['--force', 'force'],
-    ['--probe-contract', 'probeContract'],
-  ]);
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (booleanFlags.has(arg)) {
-      options[flagNames.get(arg)] = true;
-      continue;
-    }
-    if (arg !== '--scope' && arg !== '--host') throw new Error(`unknown ${command} option "${arg}"`);
-    const value = argv[index + 1];
-    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
-    options[arg === '--scope' ? 'scope' : 'host'] = value;
-    index += 1;
-  }
-  return options;
-}
-
-export async function main(argv, io = console) {
-  const [command, ...rest] = argv;
-  if (!command || command === '--help' || command === '-h') {
-    io.log(HELP);
-    return 0;
-  }
-  if (command === '--version' || command === '-v') {
-    io.log((await packageInfo()).version);
-    return 0;
-  }
-  if (command === 'run') return runCodexCommand(rest);
-  if (command === 'doctor') {
-    const options = commandOptions(command, rest);
-    const host = resolveHost(options);
-    // The probe runs BEFORE the diagnosis so the `hostContract` line below carries the verdict just
-    // measured. Printing the diagnosis first and the measurement after would answer one question
-    // twice in one output, with the older answer on top (Plan_52 D25).
-    let probe = null;
-    if (options.probeContract) {
-      probe = await probeContract({ host });
-      io.log(`probe: ${probe.message}`);
-    }
-    const result = await diagnose({ host });
-    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).
-    return probe && probe.state === 'inconclusive' ? 2 : result.exitCode;
-  }
-  if (command === 'stop') {
-    if (rest.length !== 1) {
-      io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
-      return 2;
-    }
-    const result = await stop({ run: rest[0] });
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === HOOK_COMMAND) return hook(rest, io);
-  if (command === 'read') {
-    if (rest.length !== 1) {
-      io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
-      return 2;
-    }
-    const result = read({ run: rest[0] });
-    io.log(result.output);
-    return result.exitCode;
-  }
+  prune     Remove archived transport, or purge selected run folders
+  unlock    Close running records whose runner is gone
+  read      Render a run's structured event stream
+  stop      Stop a running Codex run and record FAIL
+
+Hook dispatch:
+  codex-bridge hook <name>  Dispatch a registered guard with stdin unchanged`;
+
+const HOOK_COMMAND = 'hook';
+
+export function commandOptions(command, argv) {
+  const options = {};
+  const booleanFlags = command === 'install' || command === 'update' ? new Set(['--dry-run', '--force'])
+    : command === 'uninstall' ? new Set(['--dry-run'])
+      : command === 'doctor' ? new Set(['--probe-contract']) : new Set();
+  const flagNames = new Map([
+    ['--dry-run', 'dryRun'],
+    ['--force', 'force'],
+    ['--probe-contract', 'probeContract'],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (booleanFlags.has(arg)) {
+      options[flagNames.get(arg)] = true;
+      continue;
+    }
+    if (arg !== '--scope' && arg !== '--host') throw new Error(`unknown ${command} option "${arg}"`);
+    const value = argv[index + 1];
+    if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+    options[arg === '--scope' ? 'scope' : 'host'] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export async function main(argv, io = console) {
+  const [command, ...rest] = argv;
+  if (!command || command === '--help' || command === '-h') {
+    io.log(HELP);
+    return 0;
+  }
+  if (command === '--version' || command === '-v') {
+    io.log((await packageInfo()).version);
+    return 0;
+  }
+  if (command === 'run') return runCodex(rest);
+  if (command === 'doctor') {
+    const options = commandOptions(command, rest);
+    const host = resolveHost(options);
+    // The probe runs BEFORE the diagnosis so the `hostContract` line below carries the verdict just
+    // measured. Printing the diagnosis first and the measurement after would answer one question
+    // twice in one output, with the older answer on top (Plan_52 D25).
+    let probe = null;
+    if (options.probeContract) {
+      probe = await probeContract({ host });
+      io.log(`probe: ${probe.message}`);
+      for (const [name, verdict] of Object.entries(probe.dispatcher ?? {})) {
+        io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);
+      }
+    }
+    const result = await diagnose({ host });
+    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).
+    return probe && probe.state === 'inconclusive' ? 2 : result.exitCode;
+  }
+  if (command === 'stop') {
+    if (rest.length !== 1) {
+      io.error('codex-bridge stop requires exactly one run folder (full path or bare name).');
+      return 2;
+    }
+    const result = await stop({ run: rest[0] });
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === HOOK_COMMAND) return hook(rest, io);
+  if (command === 'read') {
+    if (rest.length !== 1) {
+      io.error('codex-bridge read requires exactly one run folder (full path or bare name).');
+      return 2;
+    }
+    const result = read({ run: rest[0] });
+    io.log(result.output);
+    return result.exitCode;
+  }
   if (command === 'projects') {
-    const result = projects(rest);
-    io.log(result.output);
+    const result = projects(rest);
+    io.log(result.output);
     return result.exitCode;
   }
   if (command === 'model') {
@@ -141,56 +144,56 @@ export async function main(argv, io = console) {
     return result.exitCode;
   }
   if (command === 'prune') {
-    const result = await prune(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'sweep') {
-    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
-    return 2;
-  }
-  if (command === 'unlock') {
-    const result = unlock(rest);
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'permissions') {
-    let action;
-    let optionArgs = rest;
-    if (rest[0] && !rest[0].startsWith('-')) {
-      action = rest[0];
-      optionArgs = rest.slice(1);
-    }
-    if (action && !['add', 'remove'].includes(action)) {
-      throw new Error(`unknown permissions action "${action}"`);
-    }
-    const options = commandOptions(command, optionArgs);
-    const host = resolveHost(options);
-    const result = await permissions({ host, action });
-    io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'install' || command === 'update' || command === 'uninstall') {
-    const options = commandOptions(command, rest);
-    const host = resolveHost(options);
-    const handlers = {
-      install: () => install({ host, dryRun: options.dryRun, force: options.force }),
-      update: () => update({ host, dryRun: options.dryRun, force: options.force }),
-      uninstall: () => uninstall({ host, dryRun: options.dryRun }),
-    };
-    const result = await handlers[command]();
-    io.log(result.output);
-    return result.exitCode;
-  }
-  io.error(`codex-bridge: unknown command "${command}"\nRun codex-bridge --help for usage.`);
-  return 2;
-}
-
-if (isInvokedDirectly(process.argv[1], import.meta.url)) {
-  main(process.argv.slice(2))
-    .then((exitCode) => { process.exitCode = exitCode; })
-    .catch((err) => {
-      console.error(`codex-bridge: ${err.message}`);
-      process.exitCode = 2;
-    });
-}
+    const result = await prune(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'sweep') {
+    io.error('codex-bridge sweep was renamed to codex-bridge unlock; use the new command.');
+    return 2;
+  }
+  if (command === 'unlock') {
+    const result = unlock(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'permissions') {
+    let action;
+    let optionArgs = rest;
+    if (rest[0] && !rest[0].startsWith('-')) {
+      action = rest[0];
+      optionArgs = rest.slice(1);
+    }
+    if (action && !['add', 'remove'].includes(action)) {
+      throw new Error(`unknown permissions action "${action}"`);
+    }
+    const options = commandOptions(command, optionArgs);
+    const host = resolveHost(options);
+    const result = await permissions({ host, action });
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'install' || command === 'update' || command === 'uninstall') {
+    const options = commandOptions(command, rest);
+    const host = resolveHost(options);
+    const handlers = {
+      install: () => install({ host, dryRun: options.dryRun, force: options.force }),
+      update: () => update({ host, dryRun: options.dryRun, force: options.force }),
+      uninstall: () => uninstall({ host, dryRun: options.dryRun }),
+    };
+    const result = await handlers[command]();
+    io.log(result.output);
+    return result.exitCode;
+  }
+  io.error(`codex-bridge: unknown command "${command}"\nRun codex-bridge --help for usage.`);
+  return 2;
+}
+
+if (isInvokedDirectly(process.argv[1], import.meta.url)) {
+  main(process.argv.slice(2))
+    .then((exitCode) => { process.exitCode = exitCode; })
+    .catch((err) => {
+      console.error(`codex-bridge: ${err.message}`);
+      process.exitCode = 2;
+    });
+}

package/cli/dispatcher-contract-record.mjs

@@ -0,0 +1,42 @@
+/**
+ * Keeps the latest conclusive verdict per dispatcher host contract, each bound to the host version it was
+ * measured on. Its own file rather than a field of .host-contract.json (Plan_62 D14, D19): the refusal
+ * record is replaced whole by its writer, and an inconclusive probe must never erase an earlier verdict.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from '../src/home/lib/atomic-json.mjs';
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+import { DISPATCHER_CONTRACTS } from './dispatcher-contract.mjs';
+
+export const DISPATCHER_CONTRACT_FILE = 'dispatcher-contract.json';
+
+export function readDispatcherContract({ stateDir }) {
+  const file = path.join(stateDir, DISPATCHER_CONTRACT_FILE);
+  let source;
+  try { source = fs.readFileSync(file, 'utf8'); } catch (error) {
+    return error.code === 'ENOENT' ? null : { corrupt: true };
+  }
+  try {
+    const record = parseJsonText(file, source);
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || !record.contracts || typeof record.contracts !== 'object' || Array.isArray(record.contracts)) return { corrupt: true };
+    return record;
+  } catch { return { corrupt: true }; }
+}
+
+export function writeDispatcherContract({ stateDir, version, verdicts, now = new Date() }) {
+  const file = path.join(stateDir, DISPATCHER_CONTRACT_FILE);
+  const previous = readDispatcherContract({ stateDir });
+  if (previous?.corrupt) throw new Error(`Cannot update corrupt dispatcher contract: ${file}`);
+  const contracts = { ...(previous?.contracts ?? {}) };
+  for (const name of DISPATCHER_CONTRACTS) {
+    const result = verdicts?.[name]?.result;
+    if (result === 'honored' || result === 'changed') {
+      contracts[name] = { result, version, checkedAt: new Date(now).toISOString(), detail: verdicts[name].detail };
+    }
+  }
+  const record = { contracts };
+  writeJsonAtomic(file, record);
+  return record;
+}

package/cli/dispatcher-contract.mjs

@@ -0,0 +1,89 @@
+/** Judges dispatcher host behaviour so a silent regression cannot leave the Plan_62 D19 gate trusted. */
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+import { PROBE_COMMAND } from './host-contract.mjs';
+
+export const DISPATCHER_CONTRACTS = ['agentIdentity', 'shellStdout', 'shellFailure', 'agentTranscript'];
+
+function inputOf(entry) {
+  const input = entry?.payload?.tool_input;
+  if (input && typeof input === 'object') return input;
+  if (typeof input === 'string') {
+    try { return parseJsonText('<hook tool_input>', input); } catch { return {}; }
+  }
+  return {};
+}
+
+function matching(entries, event, command) {
+  return entries.filter((entry) => entry?.event === event && inputOf(entry).command === command);
+}
+
+function verdict(result, detail) { return { result, detail }; }
+
+export function judgeDispatcherContracts({ entries, hostHealthy, okCommand, failCommand, okOutput, failOutput, agentType, promptToken }) {
+  const inconclusive = () => verdict('inconclusive', 'Host did not complete the probe.');
+  if (hostHealthy === false) return Object.fromEntries(DISPATCHER_CONTRACTS.map((name) => [name, inconclusive()]));
+  const list = Array.isArray(entries) ? entries : [];
+  const okPre = matching(list, 'PreToolUse', okCommand);
+  const okPost = matching(list, 'PostToolUse', okCommand);
+  const failPre = matching(list, 'PreToolUse', failCommand);
+  const failPost = matching(list, 'PostToolUse', failCommand);
+  const failures = matching(list, 'PostToolUseFailure', failCommand);
+  let transcriptVerdict;
+
+  const agentPre = list.filter((entry) => entry?.event === 'PreToolUse' && entry.payload?.agent_id);
+  if (!agentPre.length) transcriptVerdict = verdict('inconclusive', 'No agent_id was observed.');
+  else {
+    const first = agentPre[0];
+    if (first.transcript?.error) transcriptVerdict = verdict('changed', `First transcript read failed: ${first.transcript.error}`);
+    else {
+      let parsed;
+      try { parsed = parseJsonText(first.transcript?.path ?? '<transcript>', first.transcript?.firstLine ?? ''); } catch {}
+      const content = parsed?.message?.content;
+      const text = typeof content === 'string' ? content : Array.isArray(content)
+        ? content.filter((part) => part?.type === 'text').map((part) => part.text).join('\n') : '';
+      transcriptVerdict = parsed?.type === 'user' && text.includes(promptToken)
+        ? verdict('honored', 'First agent transcript line contains the caller prompt.')
+        : verdict('changed', 'First agent transcript line is not the caller user prompt.');
+    }
+  }
+
+  return {
+    agentIdentity: !okPre.length ? verdict('inconclusive', 'No delegated successful-command call was observed.')
+      : okPre.some((entry) => entry.payload.agent_type === agentType && typeof entry.payload.agent_id === 'string' && entry.payload.agent_id.trim())
+        ? verdict('honored', 'Agent type and non-empty agent_id were present.')
+        : verdict('changed', 'Successful-command PreToolUse lacked the expected agent_type or non-empty agent_id.'),
+    shellStdout: !okPre.length ? verdict('inconclusive', 'No delegated successful-command call was observed.')
+      : okPost.some((entry) => typeof entry.payload?.tool_response?.stdout === 'string' && entry.payload.tool_response.stdout.includes(okOutput))
+        ? verdict('honored', 'PostToolUse stdout contained the probe output.')
+        : verdict('changed', 'PostToolUse stdout did not contain the probe output.'),
+    shellFailure: !failPre.length ? verdict('inconclusive', 'No delegated failing-command call was observed.')
+      : !failPost.length && failures.some((entry) => typeof entry.payload?.error === 'string'
+        && entry.payload.error.startsWith('Exit code 2') && entry.payload.error.includes(failOutput)
+        && entry.payload.agent_type === agentType)
+        ? verdict('honored', 'Failure event carried the expected agent type and exit details without PostToolUse.')
+        : verdict('changed', 'Expected failure event contract was not observed.'),
+    agentTranscript: transcriptVerdict,
+  };
+}
+
+export function dispatcherContractStatus({ record, version }) {
+  return DISPATCHER_CONTRACTS.map((contract) => {
+    const item = record?.contracts?.[contract];
+    let state;
+    let message;
+    if (version == null) {
+      state = 'unknown-host'; message = 'Host version is unknown; dispatcher contracts cannot be judged.';
+    } else if (!item) {
+      state = 'unverified'; message = `Dispatcher contract ${contract} has never been probed on host ${version}; run ${PROBE_COMMAND}.`;
+    } else if (item.version !== version) {
+      state = 'stale'; message = `Dispatcher contract ${contract} was recorded for host ${item.version}; run ${PROBE_COMMAND}.`;
+    } else if (item.result === 'honored') {
+      state = 'verified'; message = `Dispatcher contract ${contract} is verified on host ${version}.`;
+    } else if (item.result === 'changed') {
+      state = 'changed'; message = `Dispatcher gate cannot be trusted on host ${version}: ${contract} changed; see Plan_62 D19.`;
+    } else {
+      state = 'unverified'; message = `Dispatcher contract ${contract} has no valid verdict; run ${PROBE_COMMAND}.`;
+    }
+    return { contract, state, message };
+  });
+}