@lyupro/codex-bridge 0.6.6 → 0.6.8

package/cli/doctor-runs.mjs

@@ -1,55 +1,55 @@
-/** Reports the state of run storage on this machine: location, live count, retention. */
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
-import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
-import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
-import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
-import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/stop-contract.mjs';
-import { check } from './doctor-format.mjs';
-
-export function retentionCheck(host) {
-  try {
-    const notice = retentionNotice(readRunConfig(host.brandConfigPath));
-    return check('retention', notice.enabled ? 'warn' : 'ok', notice.text);
-  } catch (err) {
-    return check('retention', 'fail', `invalid configuration: ${err.message}`);
-  }
-}
-
-/**
- * The runner asks git for the repository root before it picks a runs folder, so doctor has to
- * ask the same question: run from `src/home/lib/runner`, a plain cwd would name the folder `runner` and
- * report a location no run will ever use.
- */
-function repoRoot(cwd) {
-  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
-  return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : cwd;
-}
-
-/**
- * A marker that cannot be read is exactly what doctor exists to report, so it is caught here.
- * Left to propagate it would kill the whole diagnosis and hide the seven checks around it.
- */
-export function projectRunsCheck() {
-  let resolved;
-  try {
-    resolved = resolveProjectRunsDir(runsRoot(), repoRoot(process.cwd()), { create: false });
-  } catch (err) {
-    return check('projectRuns', 'fail', err.message);
-  }
-  const note = resolved.reason === 'created' ? 'not created yet' : resolved.reason;
-  return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
-}
-
-export function liveRunsCheck() {
-  let count;
-  try {
-    count = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true }).length;
-  } catch (err) {
-    return check('liveRuns', 'warn', `working-run count unavailable: ${err.message}`);
-  }
-  if (!count) return check('liveRuns', 'ok', '0 runs working right now');
-  const noun = count === 1 ? 'run' : 'runs';
-  return check('liveRuns', 'warn', `${count} ${noun} working right now; stop with ${STOP_COMMAND_TEMPLATE}`);
-}
+/** Reports the state of run storage on this machine: location, live count, retention. */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
+import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
+import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
+import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
+import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/stop-contract.mjs';
+import { check } from './doctor-format.mjs';
+
+export function retentionCheck(host) {
+  try {
+    const notice = retentionNotice(readRunConfig(host.brandConfigPath));
+    return check('retention', notice.enabled ? 'warn' : 'ok', notice.text);
+  } catch (err) {
+    return check('retention', 'fail', `invalid configuration: ${err.message}`);
+  }
+}
+
+/**
+ * The runner asks git for the repository root before it picks a runs folder, so doctor has to
+ * ask the same question: run from `src/home/lib/runner`, a plain cwd would name the folder `runner` and
+ * report a location no run will ever use.
+ */
+function repoRoot(cwd) {
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', windowsHide: true });
+  return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : cwd;
+}
+
+/**
+ * A marker that cannot be read is exactly what doctor exists to report, so it is caught here.
+ * Left to propagate it would kill the whole diagnosis and hide the seven checks around it.
+ */
+export function projectRunsCheck() {
+  let resolved;
+  try {
+    resolved = resolveProjectRunsDir(runsRoot(), repoRoot(process.cwd()), { create: false });
+  } catch (err) {
+    return check('projectRuns', 'fail', err.message);
+  }
+  const note = resolved.reason === 'created' ? 'not created yet' : resolved.reason;
+  return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
+}
+
+export function liveRunsCheck() {
+  let count;
+  try {
+    count = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true }).length;
+  } catch (err) {
+    return check('liveRuns', 'warn', `working-run count unavailable: ${err.message}`);
+  }
+  if (!count) return check('liveRuns', 'ok', '0 runs working right now');
+  const noun = count === 1 ? 'run' : 'runs';
+  return check('liveRuns', 'warn', `${count} ${noun} working right now; stop with ${STOP_COMMAND_TEMPLATE}`);
+}

package/cli/doctor.mjs

@@ -16,7 +16,15 @@ import {
   rulesCheck,
 } from './doctor-installation.mjs';
 import { hookChecks } from './doctor-hooks.mjs';
-import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
+import { contractStatus, readHostContract } from './host-contract.mjs';
+import { handbackWitnessStatus } from './handback-witness-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 { 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';
 import { liveRunsCheck, projectRunsCheck, retentionCheck } from './doctor-runs.mjs';
 
 export { renderDoctor };
@@ -52,13 +60,30 @@ export function probeCodexBridge() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
+// Plan_62 D19: `changed` fails because the dispatcher gate rests on that contract; everything short of a
+// measured break only warns. A corrupt record gets one line: the probe refuses to overwrite it.
+const DISPATCHER_CONTRACT_STATUS = { verified: 'ok', changed: 'fail' };
+
+function dispatcherContractChecks({ record, version, stateDir }) {
+  if (record?.corrupt) {
+    return [check('dispatcherContract', 'warn',
+      `The dispatcher contract record is unreadable; delete ${path.join(stateDir, DISPATCHER_CONTRACT_FILE)}, then run ${PROBE_COMMAND}.`)];
+  }
+  return dispatcherContractStatus({ record, version }).map(({ contract, state, message }) =>
+    check(`dispatcherContract:${contract}`, DISPATCHER_CONTRACT_STATUS[state] ?? 'warn', message));
+}
+
 export async function diagnose({
   host,
   codexProbe = probeCodex,
   bridgeProbe = probeCodexBridge,
+  launcherProbe,
   currentPackage,
   contractRecord,
+  handbackWitnessRecord,
+  dispatcherContractRecord,
   hostVersion,
+  observations,
 } = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
@@ -101,15 +126,36 @@ export async function diagnose({
   checks.push(await permissionsCheck(host));
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
-  checks.push(...await hookChecks(host, record, () => bridge, ownPackage, packageSource().kind));
+  checks.push(...await hookChecks(host, record, launcherProbe));
+  const stateDir = brandStateDir(host.brandRoot);
+  const hostObservations = observations === undefined ? readHostObservations({ stateDir }) : observations;
+  const observedVersions = sessionHostVersions(hostObservations);
+  const detectedHostVersion = hostVersion === undefined ? observedVersions[0] ?? null : hostVersion;
+  checks.push(sessionHostCheck(observedVersions, hostObservations));
+  const refusalRecord = contractRecord === undefined ? await readHostContract(host) : contractRecord;
   const hostContract = contractStatus({
-    record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
-    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+    record: refusalRecord,
+    version: detectedHostVersion,
   });
   const hostContractStatus = hostContract.state === 'verified'
     ? 'ok'
     : hostContract.state === 'ignored' ? 'fail' : 'warn';
   checks.push(check('hostContract', hostContractStatus, hostContract.message));
+  const witness = handbackWitnessStatus({
+    record: handbackWitnessRecord === undefined ? readHandbackWitness({ stateDir }) : handbackWitnessRecord,
+    hostVersion: detectedHostVersion,
+    stateDir,
+  });
+  checks.push(check('handbackWitness', ['seen', 'unobserved'].includes(witness.state) ? 'ok' : 'warn', witness.message));
+  const dispatcherRecord = dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord;
+  checks.push(...dispatcherContractChecks({
+    record: dispatcherRecord,
+    version: detectedHostVersion,
+    stateDir,
+  }));
+  for (const version of observedVersions.filter((item) => item !== detectedHostVersion)) {
+    checks.push(otherHostCheck({ version, contractRecord: refusalRecord, dispatcherRecord }));
+  }
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -127,7 +173,9 @@ export async function diagnose({
   return {
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
       || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
-      || projectRuns.status === 'fail' ? 1 : 0,
+      || projectRuns.status === 'fail'
+      || checks.some((item) => /^(hook|dispatcherContract):/.test(item.key) && item.status === 'fail')
+      || checks.some((item) => item.key.startsWith('otherHost:') && item.status === 'fail') ? 1 : 0,
     checks,
     record,
     missingFiles,

package/cli/handback-witness-check.mjs

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

package/cli/hook-targets.mjs

@@ -1,6 +1,7 @@
 /** Describes where each guard is installed and how its registration will be spelled. */
 import path from 'node:path';
 import { HOOK_DEFINITIONS, installedHookPath } from './manifest.mjs';
+import { probeHookLauncher } from './launcher-probe.mjs';
 import { commandFor, hookRegistration } from './settings-merge.mjs';
 
 /**
@@ -9,15 +10,15 @@ import { commandFor, hookRegistration } from './settings-merge.mjs';
  * list that decides what goes into the operator's settings.json is the same shape of defect
  * Plan_19 had to reconcile between the installer and the hooks.
  *
- * `packageVersion` is what keeps the registration honest: the short command form is only chosen
- * when the codex-bridge on PATH reports this exact version, because on 2026-08-11 an install from
- * the clone wrote `codex-bridge hook <name>` against a global 0.4.0 that has no such subcommand
- * and took every guard on the machine down with it.
+ * The short command form requires proof that the PATH launcher dispatches from this home. On
+ * 2026-08-11, checking only that a command existed registered hooks against a release without the
+ * hook subcommand; on 2026-09-24, matching versions also failed for unreleased clone code.
  */
-export function hookTargets(host, env = process.env, packageVersion = null) {
+export function hookTargets(host, env = process.env) {
+  const probe = probeHookLauncher({ env, brandRoot: host.brandRoot });
   return HOOK_DEFINITIONS.map((definition) => {
     const target = installedHookPath(host, definition);
-    const registration = hookRegistration(definition.name, target, env, packageVersion);
+    const registration = hookRegistration(definition.name, target, probe);
     const fallback = commandFor(target);
     const alternate = registration.command === fallback
       ? `codex-bridge hook ${definition.name}`
@@ -37,3 +38,10 @@ export function hookTargets(host, env = process.env, packageVersion = null) {
     };
   });
 }
+
+export function recordHasHooks(record, targets) {
+  return Boolean(record)
+    && targets.every(({ definition, relative, spec }) => record.hooks?.some((hook) =>
+      hook.event === definition.event && hook.root === 'brand' && hook.path === relative
+        && hook.command === spec.command));
+}

package/cli/hook.mjs

@@ -1,34 +1,43 @@
-/** Dispatches a named host hook without changing the guard's stdin or process lifecycle. */
+/** Dispatches a named host hook from the installed brand home. */
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
+import { pathToFileURL } from 'node:url';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
 
-const HOOKS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'src', 'home', 'hooks');
-const VALID_NAMES = HOOK_DEFINITIONS.map(({ name }) => name);
+export const HOOK_LAUNCHER_PROTOCOL = 1;
 
-function validNames() {
-  return VALID_NAMES.join(', ');
-}
-
-function usageError(io, message) {
-  io.error(`codex-bridge hook ${message} Valid hook names: ${validNames()}.`);
-  return 2;
+function reportFailure(io, name, reason) {
+  io.error(`codex-bridge hook: guard "${name}" did not run: ${reason}. Run codex-bridge doctor.`);
+  return 1;
 }
 
 export async function hook(args = [], io = console) {
   if (!Array.isArray(args) || args.length !== 1) {
-    const detail = Array.isArray(args) && args.length
-      ? `accepts exactly one hook name; received ${args.length}.`
-      : 'requires exactly one hook name.';
-    return usageError(io, detail);
+    io.error('Usage: codex-bridge hook <name> | codex-bridge hook --home');
+    return 1;
   }
 
-  const definition = HOOK_DEFINITIONS.find(({ name }) => name === args[0]);
-  if (!definition) return usageError(io, `unknown hook name "${args[0]}".`);
+  const home = resolveBrandHome({ homedir: os.homedir(), env: process.env });
+  if (args[0] === '--home') {
+    io.log(JSON.stringify({ protocol: HOOK_LAUNCHER_PROTOCOL, dispatch: 'home', homeRoot: home.root }));
+    return 0;
+  }
+  if (!args[0] || args[0].startsWith('-')) {
+    io.error('Usage: codex-bridge hook <name> | codex-bridge hook --home');
+    return 1;
+  }
 
-  // Plan_25 replaces absolute paths in foreign settings.json with this command. Importing the
-  // proven top-level script keeps its stdin reader and process.exit() contract intact; exporting
-  // guard functions would be a second implementation of the live hook boundary.
-  await import(pathToFileURL(path.join(HOOKS_DIR, definition.file)).href);
-  return typeof process.exitCode === 'number' ? process.exitCode : 0;
+  const name = args[0];
+  const entry = path.join(home.root, 'lib', 'hook-entry.mjs');
+  if (!fs.existsSync(entry)) {
+    io.error(`codex-bridge hook: guard "${name}" did not run: codex-bridge is not installed in ${home.root}. Run codex-bridge install.`);
+    return 1;
+  }
+  try {
+    const { runHook } = await import(pathToFileURL(entry).href);
+    return await runHook(name, io);
+  } catch (error) {
+    return reportFailure(io, name, error?.message ?? String(error));
+  }
 }

package/cli/host-contract.mjs

@@ -1,135 +1,145 @@
-/**
- * Records whether the installed Claude Code host still honours hook refusals.
- *
- * Every guard here refuses work with `permissionDecision: "deny"`, and the sibling key of that same
- * object died quietly: a neighbouring package established that `"allow"` stopped being honoured
- * somewhere between host 2.1.119 and 2.1.231, with no error printed on the way. Nothing in this
- * package would notice `deny` going the same way — the suite checks that a hook RETURNED a refusal,
- * never that the host APPLIED it. The record is bound to a host version because that is what
- * changes underneath an installation: the host updates itself, the package does not.
- */
-import { spawnSync } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { CLI_NAMES } from '../src/home/lib/cli-names.mjs';
-import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
-import { readJsonFile } from '../src/home/lib/json-file.mjs';
-
-export const HOST_CONTRACT_RECORD_NAME = '.host-contract.json';
-
-/**
- * The command that runs the probe, kept here so every message gains it in one edit.
- *
- * It stayed unnamed in the messages until the command existed: a package that sends an operator to
- * a command answering `unknown doctor option` has spent its credibility on the first line they
- * read. The advice arrived in the same change as the command, and only in the states a probe can
- * actually change — a message that advises a run which would tell you nothing new is noise.
- *
- * Derived rather than spelled out: Plan_17 §5 found installer and hook lists drifting apart once
- * the same name lived in two places. `CLI_NAMES[0]` is the canonical spelling.
- */
-export const PROBE_COMMAND = `${CLI_NAMES[0]} doctor --probe-contract`;
-
-export function hostContractPath(host) {
-  if (!host?.brandRoot) throw new Error('host has no brand installation root');
-  return path.join(host.brandRoot, HOST_CONTRACT_RECORD_NAME);
-}
-
-export async function readHostContract(host) {
-  const target = hostContractPath(host);
-  try {
-    const record = await readJsonFile(target);
-    if (!record || typeof record !== 'object' || Array.isArray(record)
-      || typeof record.version !== 'string' || !record.version) return null;
-    return {
-      version: record.version,
-      checkedAt: record.checkedAt,
-      result: record.result,
-    };
-  } catch {
-    return null;
-  }
-}
-
-export async function writeHostContract(host, { version, result, now = new Date() }) {
-  if (typeof version !== 'string' || !version) {
-    throw new Error('host contract version must be a non-empty string');
-  }
-  if (result !== 'honored' && result !== 'ignored') {
-    throw new Error('host contract result must be honored or ignored');
-  }
-
-  const target = hostContractPath(host);
-  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
-  const record = { version, result, checkedAt: now.toISOString() };
-  await fs.mkdir(host.brandRoot, { recursive: true });
-  try {
-    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
-    await fs.rename(temporary, target);
-  } finally {
-    await fs.rm(temporary, { force: true });
-  }
-}
-
-export function parseHostVersion(text) {
-  if (typeof text !== 'string') return null;
-  return text.trim().match(/^(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
-}
-
-export function detectHostVersion({ run = spawnSync } = {}) {
-  try {
-    const result = run('claude', ['--version'], {
-      encoding: 'utf8',
-      shell: false,
-      timeout: 5000,
-    });
-    if (!result || result.error || result.status !== 0) return null;
-    return parseHostVersion(result.stdout);
-  } catch {
-    return null;
-  }
-}
-
-export function contractStatus({ record, version }) {
-  // Loose equality on purpose: a caller that forgot the field hands over `undefined`, and the
-  // stale branch below would then report "the current host is undefined" as if it had measured it.
-  if (version == null) {
-    return {
-      state: 'unknown-host',
-      message: 'The host version could not be read, so the refusal contract cannot be judged.',
-    };
-  }
-  if (!record) {
-    return {
-      state: 'unverified',
-      message: `The refusal contract has never been probed on this machine (host ${version}); run ${PROBE_COMMAND}.`,
-    };
-  }
-  if (record.version !== version) {
-    return {
-      state: 'stale',
-      message: `The refusal contract was probed on host ${record.version}, but the current host is ${version}; run ${PROBE_COMMAND}.`,
-    };
-  }
-  if (record.result === 'ignored') {
-    const guards = HOOK_DEFINITIONS
-      .filter((definition) => definition.event === 'PreToolUse')
-      .map((definition) => definition.name)
-      .join(', ');
-    return {
-      state: 'ignored',
-      message: `DANGER: Host ${version} does not honour hook refusals, so every guard is inert: ${guards}. Re-run ${PROBE_COMMAND} once the host updates.`,
-    };
-  }
-  if (record.result === 'honored') {
-    return {
-      state: 'verified',
-      message: `Host ${version} honours hook refusals (verified ${record.checkedAt}).`,
-    };
-  }
-  return {
-    state: 'unverified',
-    message: `The refusal contract record is invalid (host ${version}); run ${PROBE_COMMAND}.`,
-  };
-}
+/**
+ * Records whether the installed Claude Code host still honours hook refusals.
+ *
+ * Every guard here refuses work with `permissionDecision: "deny"`, and the sibling key of that same
+ * object died quietly: a neighbouring package established that `"allow"` stopped being honoured
+ * somewhere between host 2.1.119 and 2.1.231, with no error printed on the way. Nothing in this
+ * package would notice `deny` going the same way — the suite checks that a hook RETURNED a refusal,
+ * never that the host APPLIED it. The record is bound to a host version because that is what
+ * changes underneath an installation: the host updates itself, the package does not. The
+ * 2026-09-25 incident ran VS Code host 2.1.282 beside CLI host 2.1.281, so each version keeps
+ * its own verdict and probing either must preserve the other.
+ */
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CLI_NAMES } from '../src/home/lib/cli-names.mjs';
+import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
+import { readJsonFile } from '../src/home/lib/json-file.mjs';
+
+export const HOST_CONTRACT_RECORD_NAME = '.host-contract.json';
+
+/**
+ * The command that runs the probe, kept here so every message gains it in one edit.
+ *
+ * It stayed unnamed in the messages until the command existed: a package that sends an operator to
+ * a command answering `unknown doctor option` has spent its credibility on the first line they
+ * read. The advice arrived in the same change as the command, and only in the states a probe can
+ * actually change — a message that advises a run which would tell you nothing new is noise.
+ *
+ * Derived rather than spelled out: Plan_17 §5 found installer and hook lists drifting apart once
+ * the same name lived in two places. `CLI_NAMES[0]` is the canonical spelling.
+ */
+export const PROBE_COMMAND = `${CLI_NAMES[0]} doctor --probe-contract`;
+
+export function hostContractPath(host) {
+  if (!host?.brandRoot) throw new Error('host has no brand installation root');
+  return path.join(host.brandRoot, HOST_CONTRACT_RECORD_NAME);
+}
+
+export async function readHostContract(host) {
+  const target = hostContractPath(host);
+  try {
+    const record = await readJsonFile(target);
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+    if (record.hosts && typeof record.hosts === 'object' && !Array.isArray(record.hosts)) return record;
+    if (typeof record.version === 'string' && record.version) {
+      return { hosts: { [record.version]: { result: record.result, checkedAt: record.checkedAt } } };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeHostContract(host, { version, result, now = new Date() }) {
+  if (typeof version !== 'string' || !version) {
+    throw new Error('host contract version must be a non-empty string');
+  }
+  if (result !== 'honored' && result !== 'ignored') {
+    throw new Error('host contract result must be honored or ignored');
+  }
+
+  const target = hostContractPath(host);
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  const previous = await readHostContract(host);
+  const cutoff = now.getTime() - 180 * 24 * 60 * 60 * 1000;
+  const hosts = Object.fromEntries(Object.entries(previous?.hosts ?? {}).filter(([, entry]) =>
+    Number.isFinite(Date.parse(entry?.checkedAt)) && Date.parse(entry.checkedAt) >= cutoff));
+  hosts[version] = { result, checkedAt: now.toISOString() };
+  const record = { hosts };
+  await fs.mkdir(host.brandRoot, { recursive: true });
+  try {
+    await fs.writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    await fs.rename(temporary, target);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+
+export function parseHostVersion(text) {
+  if (typeof text !== 'string') return null;
+  return text.trim().match(/^(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
+}
+
+export function detectHostVersion({ run = spawnSync, executable = 'claude' } = {}) {
+  try {
+    const result = run(executable, ['--version'], {
+      encoding: 'utf8',
+      shell: false,
+      timeout: 5000,
+      windowsHide: true,
+    });
+    if (!result || result.error || result.status !== 0) return null;
+    return parseHostVersion(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+export function contractStatus({ record, version }) {
+  // Loose equality on purpose: a caller that forgot the field hands over `undefined`, and the
+  // stale branch below would then report "the current host is undefined" as if it had measured it.
+  if (version == null) {
+    return {
+      state: 'unknown-host',
+      message: 'The host version could not be read, so the refusal contract cannot be judged.',
+    };
+  }
+  if (!record) {
+    return {
+      state: 'unverified',
+      message: `The refusal contract has never been probed on this machine (host ${version}); run ${PROBE_COMMAND}.`,
+    };
+  }
+  const entry = record.hosts?.[version];
+  if (!entry && Object.keys(record.hosts ?? {}).length) {
+    const [otherVersion] = Object.entries(record.hosts).sort((a, b) => Date.parse(b[1]?.checkedAt) - Date.parse(a[1]?.checkedAt))[0];
+    return {
+      state: 'stale',
+      message: `The refusal contract was probed on host ${otherVersion}, but the current host is ${version}; run ${PROBE_COMMAND}.`,
+    };
+  }
+  if (!entry) return { state: 'unverified', message: `The refusal contract has never been probed on this machine (host ${version}); run ${PROBE_COMMAND}.` };
+  if (entry.result === 'ignored') {
+    const guards = HOOK_DEFINITIONS
+      .filter((definition) => definition.event === 'PreToolUse')
+      .map((definition) => definition.name)
+      .join(', ');
+    return {
+      state: 'ignored',
+      message: `DANGER: Host ${version} does not honour hook refusals, so every guard is inert: ${guards}. Re-run ${PROBE_COMMAND} once the host updates.`,
+    };
+  }
+  if (entry.result === 'honored') {
+    return {
+      state: 'verified',
+      message: `Host ${version} honours hook refusals (verified ${entry.checkedAt}).`,
+    };
+  }
+  return {
+    state: 'unverified',
+    message: `The refusal contract record is invalid (host ${version}); run ${PROBE_COMMAND}.`,
+  };
+}