@lyupro/codex-bridge 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.8] - 2026-09-25
+
+### Added
+
+- Every session records the version of the host that runs its hooks, read from the `version` the
+  host writes into its own transcript, in `state/host-observations.json`. `doctor` prints a
+  `sessionHost` line and one `otherHost:<version>` line for each other host seen in the last 30
+  days. Sessions ran in the VS Code extension 2.1.282 while `claude` on PATH was 2.1.281, and the
+  extension's `CLAUDE_CODE_EXECPATH` and `CLAUDE_AGENT_SDK_VERSION` are inherited by every `claude`
+  it starts, so neither PATH nor the environment names the host.
+- A subagent stop that carries an `agent_id` but no `agent_type` records a witness alarm and tells
+  the session that the dispatcher gate cannot recognise dispatchers. That was the one host change the
+  gate would otherwise have passed silently.
+
+### Changed
+
+- `.host-contract.json` and `state/dispatcher-contract.json` keep one verdict per host version, so a
+  CLI session and an extension session on different versions no longer overwrite each other's
+  measurement. Existing single-version files are read as the record of their own version.
+- `doctor --probe-contract` measures the executable of the newest observed host. `claude` on PATH
+  and `CLAUDE_CODE_EXECPATH` are used only when their own `--version` matches it;
+  `--probe-executable <path>` names one explicitly. A host that completes the probe but writes
+  another version into its transcript records nothing.
+
+### Fixed
+
+- `doctor` and `install` judge the hosts sessions actually ran on instead of `claude` on PATH. A
+  machine whose sessions run in an editor extension had its contracts reported as verified for a
+  different program, and a permanent `handbackWitness` warning asked for a dispatcher run that could
+  never clear it. With no session observed yet, `doctor` says so rather than falling back to PATH.
+- The handback witness records the host version from the transcript and compares it exactly. It had
+  matched an SDK version to a CLI version by patch number, which accepted unrelated versions sharing
+  a patch. An older SDK-based witness file reads as "not seen yet" and keeps its alarms.
+- `uninstall` names the host observations among the files it leaves in the package home.
+
+After installing 0.6.8, run `codex-bridge update` once so the home receives the observation code,
+then run any shell command in a session. If `doctor` reports the session host as probed on another
+version, run `codex-bridge doctor --probe-contract` once (about two minutes of Claude quota).
+
 ## [0.6.7] - 2026-09-25
 
 ### 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 **1636 automated tests: 1635 passing and 1 skipped**.
+The current suite contains **1667 automated tests: 1666 passing and 1 skipped**.
 
 ## Verify
 
@@ -91,7 +91,9 @@ 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. 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.
+`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.
 
 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 +130,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, 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. |
+| `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. |
 | `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

@@ -2,6 +2,8 @@
 /** Dispatches codex-bridge CLI arguments to focused command modules. */
 import { diagnose, renderDoctor } from '../cli/doctor.mjs';
 import { probeContract } from '../cli/probe-contract.mjs';
+import { resolveProbeTarget } from '../cli/probe-target.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
 import { hook } from '../cli/hook.mjs';
 import { resolveHost } from '../cli/hosts.mjs';
@@ -25,7 +27,7 @@ Usage:
   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 doctor [--scope user|project] [--host <path>] [--probe-contract] [--probe-executable <path>]
   codex-bridge run <runner options> --task-file <path>
   codex-bridge model [list]
   codex-bridge projects [<name>] [--json]
@@ -74,10 +76,10 @@ export function commandOptions(command, argv) {
       options[flagNames.get(arg)] = true;
       continue;
     }
-    if (arg !== '--scope' && arg !== '--host') throw new Error(`unknown ${command} option "${arg}"`);
+    if (arg !== '--scope' && arg !== '--host' && !(command === 'doctor' && arg === '--probe-executable')) throw new Error(`unknown ${command} option "${arg}"`);
     const value = argv[index + 1];
     if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
-    options[arg === '--scope' ? 'scope' : 'host'] = value;
+    options[arg === '--scope' ? 'scope' : arg === '--host' ? 'host' : 'probeExecutable'] = value;
     index += 1;
   }
   return options;
@@ -96,13 +98,16 @@ export async function main(argv, io = console) {
   if (command === 'run') return runCodex(rest);
   if (command === 'doctor') {
     const options = commandOptions(command, rest);
+    if (options.probeExecutable && !options.probeContract) throw new Error('--probe-executable requires --probe-contract');
     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 });
+      const target = resolveProbeTarget({ stateDir: brandStateDir(host.brandRoot), executable: options.probeExecutable });
+      if (!target.error) io.log(`probe: target ${target.version} at ${target.executable} (${target.source})`);
+      probe = await probeContract({ host, target });
       io.log(`probe: ${probe.message}`);
       for (const [name, verdict] of Object.entries(probe.dispatcher ?? {})) {
         io.log(`probe: ${name} ${verdict.result} — ${verdict.detail}`);

package/cli/dispatcher-contract-record.mjs

@@ -1,7 +1,8 @@
 /**
- * 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.
+ * Keeps the latest conclusive verdict per dispatcher host contract, per host version: on 2026-09-25 the
+ * VS Code host 2.1.282 ran beside the CLI host 2.1.281, and probing either must keep the other's verdict.
+ * Its own file rather than a field of .host-contract.json (Plan_62 D14, D19), and an inconclusive probe
+ * must never erase an earlier verdict.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,9 +20,17 @@ export function readDispatcherContract({ stateDir }) {
   }
   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;
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return { corrupt: true };
+    if (record.hosts && typeof record.hosts === 'object' && !Array.isArray(record.hosts)) return record;
+    if (!record.contracts || typeof record.contracts !== 'object' || Array.isArray(record.contracts)) return { corrupt: true };
+    const hosts = {};
+    for (const [name, item] of Object.entries(record.contracts)) {
+      if (!item || typeof item.version !== 'string' || !item.version) continue;
+      hosts[item.version] ??= { contracts: {} };
+      const { version: _version, ...entry } = item;
+      hosts[item.version].contracts[name] = entry;
+    }
+    return { hosts };
   } catch { return { corrupt: true }; }
 }
 
@@ -29,14 +38,14 @@ export function writeDispatcherContract({ stateDir, version, verdicts, now = new
   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 ?? {}) };
+  const contracts = { ...(previous?.hosts?.[version]?.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 };
+      contracts[name] = { result, checkedAt: new Date(now).toISOString(), detail: verdicts[name].detail };
     }
   }
-  const record = { contracts };
+  const record = { hosts: { ...(previous?.hosts ?? {}), [version]: { contracts } } };
   writeJsonAtomic(file, record);
   return record;
 }

package/cli/dispatcher-contract.mjs

@@ -1,4 +1,4 @@
-/** Judges dispatcher host behaviour so a silent regression cannot leave the Plan_62 D19 gate trusted. */
+/** Judges dispatcher host behaviour per version: the 2026-09-25 incident ran VS Code 2.1.282 beside CLI 2.1.281. */
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { PROBE_COMMAND } from './host-contract.mjs';
 
@@ -68,15 +68,16 @@ export function judgeDispatcherContracts({ entries, hostHealthy, okCommand, fail
 
 export function dispatcherContractStatus({ record, version }) {
   return DISPATCHER_CONTRACTS.map((contract) => {
-    const item = record?.contracts?.[contract];
+    const item = record?.hosts?.[version]?.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}.`;
+      const other = Object.entries(record?.hosts ?? {}).filter(([, host]) => host?.contracts?.[contract])
+        .sort((a, b) => Date.parse(b[1].contracts[contract].checkedAt) - Date.parse(a[1].contracts[contract].checkedAt))[0];
+      if (other) { state = 'stale'; message = `Dispatcher contract ${contract} was recorded for host ${other[0]}; run ${PROBE_COMMAND}.`; }
+      else { state = 'unverified'; message = `Dispatcher contract ${contract} has never been probed on host ${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') {

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 './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

@@ -16,13 +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 };
@@ -81,6 +83,7 @@ export async function diagnose({
   handbackWitnessRecord,
   dispatcherContractRecord,
   hostVersion,
+  observations,
 } = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
@@ -124,27 +127,35 @@ export async function diagnose({
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
   checks.push(...await hookChecks(host, record, launcherProbe));
-  const detectedHostVersion = hostVersion === undefined ? detectHostVersion() : hostVersion;
+  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,
+    record: refusalRecord,
     version: detectedHostVersion,
   });
   const hostContractStatus = hostContract.state === 'verified'
     ? 'ok'
     : hostContract.state === 'ignored' ? 'fail' : 'warn';
   checks.push(check('hostContract', hostContractStatus, hostContract.message));
-  const stateDir = brandStateDir(host.brandRoot);
   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: dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord,
+    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);
@@ -163,7 +174,8 @@ 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') ? 1 : 0,
+      || 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

@@ -1,13 +1,7 @@
-/** Surfaces handback drift because the 2026-09-17..24 contract break went unnoticed for a week. */
+/** 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';
 
-function versionParts(value) {
-  if (typeof value !== 'string') return null;
-  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:\s|$)/);
-  return match ? { version: match[0].trim(), patch: match[3] } : null;
-}
-
 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.` };
@@ -16,24 +10,22 @@ export function handbackWitnessStatus({ record, hostVersion, stateDir }) {
     const alarm = record.alarms.at(-1);
     return {
       state: 'alarm',
-      message: `${record.alarms.length} dispatcher alarm(s); newest: ${alarm.detail} at ${alarm.at}; do not trust a dispatcher answer from that time; see Plan_62 D15.`,
+      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) {
+  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 seen = versionParts(record.lastSeen.sdkVersion);
-  const host = versionParts(hostVersion);
-  // Plan_62 D9 pairs observed SDK 0.3.281 inside Claude Code 2.1.281 hooks; matching patches are current.
-  if (seen && host && seen.patch !== host.patch) {
+  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: `Last seen on SDK ${record.lastSeen.sdkVersion} at ${record.lastSeen.at}; current host ${hostVersion}; run any dispatcher once in an interactive session to observe it again.`,
+      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: 'seen',
-    message: `Handback contract last seen on SDK ${record.lastSeen.sdkVersion} (host ${hostVersion}) at ${record.lastSeen.at}.`,
-  };
+  return { state: 'unobserved', message: 'Not observed yet — a handback is seen only when a dispatcher runs in an interactive session.' };
 }

package/cli/host-contract.mjs

@@ -6,7 +6,9 @@
  * 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.
+ * 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';
@@ -40,13 +42,12 @@ 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,
-    };
+    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;
   }
@@ -62,7 +63,12 @@ export async function writeHostContract(host, { version, result, now = new Date(
 
   const target = hostContractPath(host);
   const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
-  const record = { version, result, checkedAt: now.toISOString() };
+  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');
@@ -77,9 +83,9 @@ export function parseHostVersion(text) {
   return text.trim().match(/^(\d+\.\d+\.\d+)(?:\s|$)/)?.[1] ?? null;
 }
 
-export function detectHostVersion({ run = spawnSync } = {}) {
+export function detectHostVersion({ run = spawnSync, executable = 'claude' } = {}) {
   try {
-    const result = run('claude', ['--version'], {
+    const result = run(executable, ['--version'], {
       encoding: 'utf8',
       shell: false,
       timeout: 5000,
@@ -107,13 +113,16 @@ export function contractStatus({ record, version }) {
       message: `The refusal contract has never been probed on this machine (host ${version}); run ${PROBE_COMMAND}.`,
     };
   }
-  if (record.version !== version) {
+  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 ${record.version}, but the current host is ${version}; run ${PROBE_COMMAND}.`,
+      message: `The refusal contract was probed on host ${otherVersion}, but the current host is ${version}; run ${PROBE_COMMAND}.`,
     };
   }
-  if (record.result === 'ignored') {
+  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)
@@ -123,10 +132,10 @@ export function contractStatus({ record, version }) {
       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') {
+  if (entry.result === 'honored') {
     return {
       state: 'verified',
-      message: `Host ${version} honours hook refusals (verified ${record.checkedAt}).`,
+      message: `Host ${version} honours hook refusals (verified ${entry.checkedAt}).`,
     };
   }
   return {

package/cli/install.mjs

@@ -25,7 +25,10 @@ import {
 } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { addPermissionRules, inspectPermissions } from './permissions.mjs';
-import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
+import { contractStatus, readHostContract } from './host-contract.mjs';
+import { readHostObservations } from '../src/home/lib/host-observations.mjs';
+import { brandStateDir } from '../src/home/lib/brand-home.mjs';
+import { sessionHostVersions } from './session-hosts.mjs';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 
 const WARNING = '\u001b[33m';
@@ -109,14 +112,22 @@ async function installInRun({
   env = process.env,
   contractRecord,
   hostVersion,
+  observations,
 } = {}) {
   // Validate the shared registry before writes; package removal on a broken registry left the host without its watchdog.
   await readRulesRegistry(host);
   const configuredRetentionLine = retentionLine(host);
-  const hostContract = contractStatus({
+  const hostObservations = observations === undefined
+    ? readHostObservations({ stateDir: brandStateDir(host.brandRoot) }) : observations;
+  const observedVersion = sessionHostVersions(hostObservations)[0] ?? null;
+  const currentHostVersion = hostVersion === undefined ? observedVersion : hostVersion;
+  let hostContract = contractStatus({
     record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
-    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+    version: currentHostVersion,
   });
+  const noObservedHostMessage = currentHostVersion === null
+    ? 'Host contracts are judged once a session has run a shell command; then run codex-bridge doctor.' : null;
+  if (noObservedHostMessage) hostContract = { ...hostContract, message: noObservedHostMessage };
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);

package/cli/probe-contract.mjs

@@ -7,13 +7,14 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { detectHostVersion, writeHostContract } from './host-contract.mjs';
+import { writeHostContract } from './host-contract.mjs';
 import { buildRig } from './probe-rig.mjs';
 import { DISPATCHER_CONTRACTS, judgeDispatcherContracts } from './dispatcher-contract.mjs';
 import { writeDispatcherContract } from './dispatcher-contract-record.mjs';
 import { brandStateDir } from '../src/home/lib/brand-home.mjs';
 import { parseJsonText } from '../src/home/lib/json-file.mjs';
 import { randomUUID } from 'node:crypto';
+import { transcriptHostVersion } from '../src/home/lib/host-version.mjs';
 
 export const PROBE_MARKER = 'codex-bridge-contract-probe';
 
@@ -60,17 +61,18 @@ export function judgeProbe({ markerExists, hookFired, hostResult }) {
 
 export async function probeContract({
   host,
-  version = detectHostVersion(),
+  target,
   runHost = spawnSync,
   rigRoot = os.tmpdir(),
   now = new Date(),
 }) {
-  if (version == null) {
+  if (target?.error || !target?.version || !target?.executable) {
+    const message = target?.error ?? 'The probe target is unavailable.';
     return {
       state: 'inconclusive',
       result: null,
       version: null,
-      message: 'The host version could not be read, so no contract probe was run.',
+      message,
       recorded: false,
       dispatcher: Object.fromEntries(DISPATCHER_CONTRACTS.map((name) => [name, { result: 'inconclusive', detail: 'Host version is unavailable.' }])),
     };
@@ -83,7 +85,7 @@ export async function probeContract({
     const rig = await buildRig(dir, token);
     let hostResult;
     try {
-      hostResult = runHost('claude', [
+      hostResult = runHost(target.executable, [
         '--setting-sources', 'project',
         '--allowedTools', 'Bash,Agent',
         '-p', rig.prompt,
@@ -106,6 +108,20 @@ export async function probeContract({
     } catch (error) {
       if (error.code !== 'ENOENT') malformed = true;
     }
+    // Only a host that completed the run can be asked who it was; a spawn failure or timeout keeps its own
+    // reason below instead of reading as "ran on host unknown".
+    const hostCompleted = !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0;
+    let seen = null;
+    const transcriptPath = entries.find((entry) => typeof entry?.payload?.transcript_path === 'string')?.payload.transcript_path;
+    if (transcriptPath) seen = await transcriptHostVersion(transcriptPath);
+    if (hostCompleted && seen !== target.version) {
+      return {
+        state: 'inconclusive', result: null, version: target.version,
+        message: `The probe ran on host ${seen ?? 'unknown'}, not on ${target.version}; nothing was recorded.`,
+        recorded: false,
+        dispatcher: Object.fromEntries(DISPATCHER_CONTRACTS.map((name) => [name, { result: 'inconclusive', detail: 'Probe host version did not match target.' }])),
+      };
+    }
     const verdict = judgeProbe({
       markerExists: await exists(rig.markerPath),
       hookFired: await exists(rig.journalPath),
@@ -118,25 +134,25 @@ export async function probeContract({
       failOutput: rig.failOutput, agentType: 'probe-agent', promptToken: token,
     });
     if (verdict.result == null) dispatcher = Object.fromEntries(Object.keys(dispatcher).map((name) => [name, { result: 'inconclusive', detail: 'Refusal probe did not complete.' }]));
-    if (verdict.result != null && version != null && !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0) {
-      await writeDispatcherContract({ stateDir: brandStateDir(host.brandRoot), version, verdicts: dispatcher, now });
+    if (verdict.result != null && !malformed && !hostResult?.error && !hostResult?.signal && hostResult?.status === 0) {
+      await writeDispatcherContract({ stateDir: brandStateDir(host.brandRoot), version: target.version, verdicts: dispatcher, now });
     }
     if (verdict.result == null) {
       return {
         state: 'inconclusive',
         result: null,
-        version,
+        version: target.version,
         message: verdict.reason,
         recorded: false,
         dispatcher: Object.fromEntries(Object.entries(dispatcher).map(([name, item]) => [name, { result: 'inconclusive', detail: 'Host did not complete the probe.' }])),
       };
     }
 
-    await writeHostContract(host, { version, result: verdict.result, now });
+    await writeHostContract(host, { version: target.version, result: verdict.result, now });
     return {
       state: 'probed',
       result: verdict.result,
-      version,
+      version: target.version,
       message: verdict.reason,
       recorded: true,
       dispatcher,

package/cli/probe-target.mjs

@@ -0,0 +1,33 @@
+/** Resolves the session host after the 2026-09-25 PATH host identity incident. */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { detectHostVersion } from './host-contract.mjs';
+import { readHostObservations } from '../src/home/lib/host-observations.mjs';
+
+export function resolveProbeTarget({ stateDir, executable, env = process.env, run = spawnSync, exists = fs.existsSync }) {
+  if (executable) {
+    const version = detectHostVersion({ run, executable });
+    return version === null
+      ? { error: `Could not read the version of ${executable}.` }
+      : { executable, version, source: 'flag' };
+  }
+
+  const observations = readHostObservations({ stateDir });
+  const newest = Object.entries(observations.hosts)
+    .filter(([, entry]) => Number.isFinite(Date.parse(entry?.lastSeen)))
+    .sort((a, b) => Date.parse(b[1].lastSeen) - Date.parse(a[1].lastSeen))[0];
+  if (!newest) {
+    return { error: 'No Claude Code session has been observed by this installation yet; run any shell command in a session first, or pass --probe-executable <path>.' };
+  }
+  const [version] = newest;
+  const candidates = [];
+  if (env.CLAUDE_CODE_EXECPATH && exists(env.CLAUDE_CODE_EXECPATH)) candidates.push(env.CLAUDE_CODE_EXECPATH);
+  candidates.push('claude');
+  const checked = [];
+  for (const candidate of candidates) {
+    const candidateVersion = detectHostVersion({ run, executable: candidate });
+    checked.push(`${candidate} (${candidateVersion ?? 'unknown'})`);
+    if (candidateVersion === version) return { executable: candidate, version, source: 'observed' };
+  }
+  return { error: `No executable of the observed host ${version} was found (checked: ${checked.join(', ')}); pass --probe-executable <path>.` };
+}

package/cli/session-hosts.mjs

@@ -0,0 +1,51 @@
+/** Judges every observed session host after the 2026-09-25 PATH host identity incident. */
+import { contractStatus, PROBE_COMMAND } from './host-contract.mjs';
+import { DISPATCHER_CONTRACTS, dispatcherContractStatus } from './dispatcher-contract.mjs';
+
+export function sessionHostVersions(observations) {
+  return Object.entries(observations?.hosts ?? {})
+    .map(([version, entry]) => ({ version, timestamp: Date.parse(entry?.lastSeen) }))
+    .filter(({ timestamp }) => Number.isFinite(timestamp))
+    .sort((a, b) => b.timestamp - a.timestamp)
+    .map(({ version }) => version);
+}
+
+export function sessionHostCheck(versions, observations) {
+  if (!versions.length) {
+    return {
+      key: 'sessionHost',
+      status: 'warn',
+      value: 'No Claude Code session has been observed by this installation yet; host contracts are judged once a session runs a shell command.',
+    };
+  }
+  const newest = versions[0];
+  const lastSeen = new Date(observations.hosts[newest].lastSeen).toISOString();
+  const others = versions.slice(1);
+  return {
+    key: 'sessionHost',
+    status: 'ok',
+    value: `Sessions run on host ${newest} (last seen ${lastSeen})${others.length ? `; also seen: ${others.join(', ')}` : ''}`,
+  };
+}
+
+export function otherHostCheck({ version, contractRecord, dispatcherRecord }) {
+  const refusal = contractStatus({ record: contractRecord, version });
+  const dispatchers = dispatcherContractStatus({ record: dispatcherRecord, version });
+  const key = `otherHost:${version}`;
+  if (refusal.state === 'ignored' || dispatchers.some(({ state }) => state === 'changed')) {
+    const changed = dispatchers.filter(({ state }) => state === 'changed').map(({ contract }) => contract);
+    return { key, status: 'fail', value: [refusal.state === 'ignored' ? 'refusal contract ignored' : '', ...changed].filter(Boolean).join('; ') };
+  }
+  if (refusal.state === 'verified' && dispatchers.every(({ state }) => state === 'verified')) {
+    return { key, status: 'ok', value: `Host ${version} refusal and dispatcher contracts are verified.` };
+  }
+  const missing = [];
+  if (refusal.state !== 'verified') missing.push('refusal');
+  missing.push(...dispatchers.filter(({ state }) => state !== 'verified').map(({ contract }) => contract));
+  const probe = `${PROBE_COMMAND} --probe-executable <path to a ${version} executable>`;
+  return {
+    key,
+    status: 'warn',
+    value: `Host ${version} contracts not yet measured: ${missing.join(', ')}; run ${probe}.`,
+  };
+}

package/cli/uninstall.mjs

@@ -42,8 +42,9 @@ function preservationText(host) {
   return `Run artifacts in ${path.join(host.root, 'codex-runs')} are preserved, and so is what the package `
     + `wrote into ${host.brandRoot} while working: the run configuration ${host.brandConfigPath}, the conventions `
     + `${host.brandConventionsPath}, the host measurement ${hostContractPath(host)} and runtime state in `
-    + `${brandStateDir(host.brandRoot)} (dispatcher state, guard counters, the handback witness, dispatcher `
-    + 'contract verdicts, and hook diagnostics that hold the full hook input). Delete them by hand for a complete removal.';
+    + `${brandStateDir(host.brandRoot)} (dispatcher state, guard counters, the handback witness, the host `
+    + 'observations, dispatcher contract verdicts, and hook diagnostics that hold the full hook input). Delete them by '
+    + 'hand for a complete removal.';
 }
 
 function displayFile(file) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.6.7",
-  "description": "Claude Code-to-Codex delegation with 7 guards, 1636 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.6.8",
+  "description": "Claude Code-to-Codex delegation with 7 guards, 1667 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/scripts/run-tests.mjs

@@ -21,6 +21,13 @@ import { spawnSync } from 'node:child_process';
 import { ISOLATED_ROOTS } from './isolated-roots.mjs';
 import { readmeText, suiteCountMismatch } from './suite-count.mjs';
 
+// One pattern only: on 2026-09-25 three files passed as three arguments ran just the first, and a
+// verification reported green for two files it never touched. Refuse before any root is created.
+if (process.argv.length > 3) {
+  console.error('run-tests: takes ONE pattern; pass a glob such as "tests/cli/{doctor,install}.test.mjs"');
+  process.exit(2);
+}
+
 const created = ISOLATED_ROOTS.map((name) => [
   name,
   fs.mkdtempSync(path.join(os.tmpdir(), `codex-bridge-test-${name.toLowerCase()}-`)),

package/src/home/hooks/dispatcher-gate.mjs

@@ -17,7 +17,8 @@ import {
   readDispatcherState,
   updateDispatcherState,
 } from '../lib/dispatcher-state.mjs';
-import { hostSdkVersion, recordHandbackWitness } from '../lib/handback-witness.mjs';
+import { recordHandbackWitness, witnessHostVersion } from '../lib/handback-witness.mjs';
+import { observeSessionHost } from '../lib/host-observations.mjs';
 
 function emit(decision, toolInput) {
   const hookSpecificOutput = {
@@ -43,6 +44,18 @@ async function main() {
     return;
   }
 
+  if (payload?.hook_event_name === 'PreToolUse'
+    && typeof payload.session_id === 'string' && payload.session_id.length > 0
+    && typeof payload.transcript_path === 'string' && payload.transcript_path.length > 0) {
+    try {
+      await observeSessionHost({
+        stateDir: BRAND_STATE_DIR,
+        sessionId: payload.session_id,
+        transcriptPath: payload.transcript_path,
+      });
+    } catch {}
+  }
+
   if (!payload || !Object.prototype.hasOwnProperty.call(AGENTS, payload.agent_type)
     || typeof payload.session_id !== 'string' || payload.session_id.length === 0
     || typeof payload.agent_id !== 'string' || payload.agent_id.length === 0) return;
@@ -87,7 +100,7 @@ async function main() {
         await recordHandbackWitness({
           stateDir: BRAND_STATE_DIR,
           kind: 'seen',
-          sdkVersion: hostSdkVersion(),
+          hostVersion: await witnessHostVersion(payload),
         });
       } catch {}
       try {

package/src/home/hooks/reply-guard.mjs

@@ -22,6 +22,7 @@
  * argument about EXTERNAL run state cannot be argued away by the model and ends the turn
  * with `continue: false` instead of a silent pass. See MAX_FORM_BLOCKS / MAX_STATE_BLOCKS.
  * In the handback era, SubagentHandback delivers the caller-visible answer before SubagentStop.
+ * Alarms name the host by its transcript version: on 2026-09-25 the SDK variable proved inherited.
  * Plan_62 makes this hook yield after delivery and audit every transcript tool call against gate receipts.
  *
  * Input is JSON on stdin. The fields used here (`agent_type`, `last_assistant_message`)
@@ -37,7 +38,7 @@ import { decideDispatcherStop, transcriptToolUses } from '../lib/dispatcher-stop
 import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
 import { readDispatcherState, updateDispatcherState } from '../lib/dispatcher-state.mjs';
-import { hostSdkVersion, recordHandbackWitness } from '../lib/handback-witness.mjs';
+import { recordHandbackWitness, witnessHostVersion } from '../lib/handback-witness.mjs';
 import { runLiveness } from '../lib/meta/run-liveness.mjs';
 import { resolveProjectRunsDir } from '../lib/runner/project-dir.mjs';
 import { runsRoot } from '../lib/runner/runs-root.mjs';
@@ -118,6 +119,25 @@ try {
   // Diagnostics are a convenience, never a reason to fail the turn.
 }
 
+// A host that stops sending agent_type would let every dispatcher past the gate and this
+// audit without a word (Plan_66 D2 (c)); say so instead of passing silently.
+if (typeof input.agent_id === 'string' && input.agent_id.length > 0
+  && !(typeof input.agent_type === 'string' && input.agent_type.length > 0)) {
+  try {
+    await recordHandbackWitness({
+      stateDir: BRAND_STATE_DIR,
+      kind: 'alarm',
+      hostVersion: await witnessHostVersion(input),
+      detail: `host omitted agent_type for agent ${input.agent_id}`,
+    });
+  } catch {
+    // Plan_66 H2: the 2026-09-17..24 handback break showed host contract loss must alarm, but never block work.
+  }
+  process.stdout.write(JSON.stringify({
+    systemMessage: 'codex-bridge: the host did not report agent_type for a subagent — the dispatcher gate cannot recognise dispatchers, so their answers are unchecked; run codex-bridge doctor.',
+  }));
+  process.exit(0);
+}
 // Only the Codex dispatchers have this contract. Every other agent is none of our
 // business — an earlier version inferred the agent from transcript text and blocked an
 // unrelated one, which cost a re-answer for nothing.
@@ -144,7 +164,7 @@ try {
       await recordHandbackWitness({
         stateDir: BRAND_STATE_DIR,
         kind: 'alarm',
-        sdkVersion: hostSdkVersion(),
+        hostVersion: await witnessHostVersion(input),
         detail: `${input.agent_type} ${input.agent_id}: ${names} outside the dispatcher gate`,
       });
     }

package/src/home/lib/handback-witness.mjs

@@ -1,27 +1,32 @@
-/** Records the 2026-09-17..24 silent SubagentHandback contract break before it can go unnoticed again. */
+/** Records the 2026-09-17..24 handback break; 2026-09-25 proved SDK env is inherited, so identify hosts from transcripts. */
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeJsonAtomic } from './atomic-json.mjs';
 import { parseJsonText } from './json-file.mjs';
 import { withFileLock } from './file-lock.mjs';
+import { transcriptHostVersion } from './host-version.mjs';
 
 export const WITNESS_FILE = 'handback-witness.json';
 
-export function hostSdkVersion(env = process.env) {
-  const version = env.CLAUDE_AGENT_SDK_VERSION;
-  if (typeof version !== 'string') return null;
-  return version.trim() || null;
+export async function witnessHostVersion(payload) {
+  return transcriptHostVersion(payload?.transcript_path);
 }
 
-function isWitness(record) {
-  const witnessEntry = (entry, alarm = false) => entry && typeof entry === 'object'
-    && !Array.isArray(entry)
-    && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string')
-    && typeof entry.at === 'string'
-    && (!alarm || typeof entry.detail === 'string');
-  return record && typeof record === 'object' && !Array.isArray(record)
-    && (record.lastSeen === null || witnessEntry(record.lastSeen))
-    && Array.isArray(record.alarms) && record.alarms.every((entry) => witnessEntry(entry, true));
+function normalizeWitness(record) {
+  const alarmEntry = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && (entry.hostVersion === null || typeof entry.hostVersion === 'string')
+    && typeof entry.at === 'string' && typeof entry.detail === 'string';
+  if (!record || typeof record !== 'object' || Array.isArray(record) || !Array.isArray(record.alarms)) return null;
+  if (record.alarms.every(alarmEntry) && record.lastSeen && typeof record.lastSeen === 'object'
+    && !Array.isArray(record.lastSeen) && !Object.hasOwn(record.lastSeen, 'sdkVersion')
+    && !Object.hasOwn(record.lastSeen, 'at') && Object.values(record.lastSeen).every((at) => typeof at === 'string')) return record;
+  const legacy = record.lastSeen === null || (record.lastSeen && typeof record.lastSeen === 'object'
+    && !Array.isArray(record.lastSeen) && typeof record.lastSeen.sdkVersion === 'string' && typeof record.lastSeen.at === 'string');
+  const legacyAlarm = (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && (entry.sdkVersion === null || typeof entry.sdkVersion === 'string') && typeof entry.at === 'string'
+    && typeof entry.detail === 'string';
+  if (legacy && record.alarms.every(legacyAlarm)) return { lastSeen: {}, alarms: record.alarms.map(({ at, detail }) => ({ hostVersion: null, at, detail })) };
+  return null;
 }
 
 export function readHandbackWitness({ stateDir }) {
@@ -30,12 +35,12 @@ export function readHandbackWitness({ stateDir }) {
   try {
     source = fs.readFileSync(file, 'utf8');
   } catch (error) {
-    if (error.code === 'ENOENT') return { lastSeen: null, alarms: [] };
+    if (error.code === 'ENOENT') return { lastSeen: {}, alarms: [] };
     return { corrupt: true };
   }
   try {
     const record = parseJsonText(file, source);
-    return isWitness(record) ? record : { corrupt: true };
+    return normalizeWitness(record) || { corrupt: true };
   } catch {
     return { corrupt: true };
   }
@@ -46,10 +51,10 @@ function timestamp(now) {
 }
 
 
-export async function recordHandbackWitness({ stateDir, kind, sdkVersion, detail = '', now = new Date() }) {
+export async function recordHandbackWitness({ stateDir, kind, hostVersion, detail = '', now = new Date() }) {
   if (kind !== 'seen' && kind !== 'alarm') throw new TypeError("kind must be 'seen' or 'alarm'");
-  if (sdkVersion !== null && typeof sdkVersion !== 'string') {
-    throw new TypeError('sdkVersion must be a string or null');
+  if (hostVersion !== null && typeof hostVersion !== 'string') {
+    throw new TypeError('hostVersion must be a string or null');
   }
   const file = path.join(stateDir, WITNESS_FILE);
   return withFileLock(`${file}.lock`, async () => {
@@ -57,8 +62,8 @@ export async function recordHandbackWitness({ stateDir, kind, sdkVersion, detail
     if (current.corrupt) throw new Error(`Cannot update corrupt handback witness: ${file}`);
     const at = timestamp(now);
     const record = kind === 'seen'
-      ? { ...current, lastSeen: { sdkVersion, at } }
-      : { ...current, alarms: [...current.alarms, { sdkVersion, at, detail }].slice(-20) };
+      ? { ...current, lastSeen: hostVersion === null ? current.lastSeen : { ...current.lastSeen, [hostVersion]: at } }
+      : { ...current, alarms: [...current.alarms, { hostVersion, at, detail }].slice(-20) };
     writeJsonAtomic(file, record);
     return record;
   }, { description: 'handback witness' });

package/src/home/lib/host-observations.mjs

@@ -0,0 +1,57 @@
+/** Records session host versions after the 2026-09-25 PATH host identity incident. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from './atomic-json.mjs';
+import { withFileLock } from './file-lock.mjs';
+import { parseJsonText } from './json-file.mjs';
+import { transcriptHostVersion } from './host-version.mjs';
+
+export const HOST_OBSERVATIONS_FILE = 'host-observations.json';
+
+export function readHostObservations({ stateDir }) {
+  const file = path.join(stateDir, HOST_OBSERVATIONS_FILE);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { hosts: {}, sessions: {} };
+    return { hosts: {}, sessions: {}, corrupt: true };
+  }
+  try {
+    const record = parseJsonText(file, raw);
+    if (!record || typeof record !== 'object' || Array.isArray(record)
+      || !record.hosts || typeof record.hosts !== 'object' || Array.isArray(record.hosts)
+      || !record.sessions || typeof record.sessions !== 'object' || Array.isArray(record.sessions)) {
+      return { hosts: {}, sessions: {}, corrupt: true };
+    }
+    return { hosts: record.hosts, sessions: record.sessions };
+  } catch {
+    return { hosts: {}, sessions: {}, corrupt: true };
+  }
+}
+
+export async function observeSessionHost({
+  stateDir, sessionId, transcriptPath, now = new Date(), readVersion = transcriptHostVersion,
+}) {
+  const file = path.join(stateDir, HOST_OBSERVATIONS_FILE);
+  if (readHostObservations({ stateDir }).sessions[sessionId]) return { recorded: false };
+  const version = await readVersion(transcriptPath);
+  if (version === null) return { recorded: false };
+  return withFileLock(`${file}.lock`, async () => {
+    const current = readHostObservations({ stateDir });
+    if (current.corrupt) throw new Error(`Cannot update corrupt host observations: ${file}`);
+    if (current.sessions[sessionId]) return { recorded: false };
+    const at = new Date(now).toISOString();
+    const cutoffSessions = Date.parse(at) - 7 * 24 * 60 * 60 * 1000;
+    const cutoffHosts = Date.parse(at) - 30 * 24 * 60 * 60 * 1000;
+    const sessions = Object.fromEntries(Object.entries(current.sessions)
+      .filter(([, entry]) => Date.parse(entry.at) >= cutoffSessions));
+    const hosts = Object.fromEntries(Object.entries(current.hosts)
+      .filter(([, entry]) => Date.parse(entry.lastSeen) >= cutoffHosts));
+    sessions[sessionId] = { version, at };
+    const existing = hosts[version];
+    hosts[version] = { firstSeen: existing?.firstSeen || at, lastSeen: at };
+    writeJsonAtomic(file, { hosts, sessions });
+    return { recorded: true };
+  }, { description: 'host observations' });
+}

package/src/home/lib/host-version.mjs

@@ -0,0 +1,27 @@
+/** Reads the host version from the transcript tail after the 2026-09-25 PATH host identity incident. */
+import fs from 'node:fs/promises';
+import { parseJsonText } from './json-file.mjs';
+
+export async function transcriptHostVersion(transcriptPath, { tailBytes = 65536 } = {}) {
+  try {
+    const handle = await fs.open(transcriptPath, 'r');
+    try {
+      const { size } = await handle.stat();
+      const length = Math.min(size, tailBytes);
+      const buffer = Buffer.alloc(length);
+      await handle.read(buffer, 0, length, size - length);
+      const lines = buffer.toString('utf8').split(/\r?\n/);
+      for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+          const entry = parseJsonText(transcriptPath, lines[index]);
+          if (typeof entry?.version === 'string' && /^\d+\.\d+\.\d+/.test(entry.version)) {
+            return entry.version;
+          }
+        } catch {}
+      }
+    } finally {
+      await handle.close();
+    }
+  } catch {}
+  return null;
+}