@lyupro/codex-bridge 0.6.6 → 0.6.8

package/cli/dispatcher-contract.mjs

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

package/cli/doctor-hooks.mjs

@@ -1,114 +1,104 @@
-/** Reports the health of every hook this package registered in the host. */
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { HOOK_DEFINITIONS } from './manifest.mjs';
-import { recordTarget } from './install-record.mjs';
-import { commandFor, inspectHook } from './settings-merge.mjs';
-import { check } from './doctor-format.mjs';
-
-function hookVersion(command, record, bridgeResult) {
-  if (command.startsWith('codex-bridge hook ')) {
-    return bridgeResult.available
-      ? `global command ${bridgeResult.value}`
-      : `global command unavailable (${bridgeResult.value})`;
-  }
-  return `installed copy ${record.name}@${record.version}`;
-}
-
-function probedVersion(result) {
-  return result.available ? result.value.match(/(\d+\.\d+\.\d+(?:[-+][^\s]+)?)\s*$/)?.[1] : null;
-}
-
-function startHook(target) {
-  return new Promise((resolve) => {
-    const child = spawn(process.execPath, [target], {
-      stdio: ['ignore', 'ignore', 'pipe'],
-      windowsHide: true,
-    });
-    let stderr = '';
-    child.stderr.setEncoding('utf8');
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.on('error', (error) => resolve({ status: null, stderr: error.message }));
-    child.on('close', (status) => resolve({ status, stderr }));
-  });
-}
-
-function startFailure(definition, result) {
-  if (result.status === 0) return null;
-  const lines = result.stderr.trim().split(/\r?\n/);
-  const resolver = lines.find((line) => /^Error \[ERR_MODULE_NOT_FOUND\]|Cannot find module/.test(line));
-  return `${definition.file} did not start: ${resolver || lines.find(Boolean) || `exit code ${result.status}`}`;
-}
-
-/**
- * `sourceKind` arrives as an argument rather than being read here, because the function that knows
- * which copy of the package is answering lives beside `diagnose`. Importing it back would make this
- * module and its caller depend on each other, and a cycle between a check and its orchestrator is
- * how one of them ends up half-initialised at import time.
- */
-export async function hookChecks(host, record, bridgeProbe, ownPackage, sourceKind) {
-  let bridgeResult;
-  const bridge = () => {
-    bridgeResult ??= bridgeProbe();
-    return bridgeResult;
-  };
-  const starts = record ? await Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
-    const recorded = record.hooks.find((hook) => hook.event === definition.event
-      && path.basename(hook.path) === definition.file);
-    return recorded ? startHook(recordTarget(host, recorded)) : null;
-  })) : [];
-  return Promise.all(HOOK_DEFINITIONS.map(async (definition, index) => {
-    const key = `hook:${definition.event}`;
-    if (!record) return check(key, 'warn', 'cannot check before installation');
-    // The file, not just the event: PreToolUse carries two hooks of this package, and matching
-    // by event alone reported the worktree lock's matcher as pointing at order-gate.mjs. The
-    // hook line is the only place an operator can see WHICH file a matcher was registered for,
-    // so a wrong name here is worse than no line at all.
-    const recorded = record.hooks.find((hook) => hook.event === definition.event
-      && path.basename(hook.path) === definition.file);
-    if (!recorded) {
-      return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
-    }
-    const expected = recordTarget(host, recorded);
-    const fullCommand = commandFor(expected);
-    const shortCommand = `codex-bridge hook ${definition.name}`;
-    try {
-      const state = await inspectHook(host.settingsPath, {
-        event: definition.event,
-        matcher: definition.matcher,
-        command: recorded.command || fullCommand,
-        alternateCommands: [fullCommand, shortCommand],
-      });
-      if (state.present) {
-        const recordedMatcher = state.matchedMatcher;
-        const command = state.matchedCommand || recorded.command || fullCommand;
-        const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
-        const reason = form === 'short'
-          ? 'PATH command uses the globally installed package'
-          : 'full path uses the copy placed by the last install';
-        const problems = [startFailure(definition, starts[index])].filter(Boolean);
-        // The matcher printed is the one the host recorded, never the one this package declares.
-        // Until 2026-08-23 the line stated the registry's own value, so a host stuck on the
-        // pre-shell matcher read as [ok] while the worktree lock never saw a Bash command — the
-        // same shape as the 2026-08-10 defect, where doctor counted files instead of
-        // reading them. A check that compares the package to itself cannot fail.
-        if (recordedMatcher !== definition.matcher) problems.push(`recorded matcher ${recordedMatcher} differs from expected ${definition.matcher}; run codex-bridge update --force`);
-        const commandVersion = form === 'short' ? bridge() : null;
-        const globalVersion = probedVersion(commandVersion || { available: false });
-        if (globalVersion && globalVersion !== ownPackage.version) {
-          problems.push(`global PATH package version ${globalVersion} differs from ${sourceKind} version ${ownPackage.version}`);
-        }
-        const health = problems.length ? `; ${problems.join('; ')}` : '';
-        return check(key, problems.length ? 'warn' : 'ok', `${definition.event} matcher ${recordedMatcher} -> ${expected} (${form} command; ${reason}; ${hookVersion(command, record, commandVersion)}${health})`);
-      }
-      const command = recorded.command || fullCommand;
-      const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
-      const failure = startFailure(definition, starts[index]);
-      const commandVersion = form === 'short' ? bridge() : null;
-      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file} (${form} command; ${hookVersion(command, record, commandVersion)}${failure ? `; ${failure}` : ''})`);
-    } catch (err) {
-      const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
-      return check(key, 'warn', `${definition.event} hook: ${value}`);
-    }
-  }));
-}
+/** Reports the health of every hook this package registered in the host. */
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { HOOK_DEFINITIONS } from './manifest.mjs';
+import { recordTarget } from './install-record.mjs';
+import { commandFor, inspectHook } from './settings-merge.mjs';
+import { check } from './doctor-format.mjs';
+import { probeHookLauncher } from './launcher-probe.mjs';
+
+function hookVersion(record) {
+  return `installed copy ${record.name}@${record.version}`;
+}
+
+function startHook(target) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [target], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+      windowsHide: true,
+    });
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => resolve({ status: null, stderr: error.message }));
+    child.on('close', (status) => resolve({ status, stderr }));
+  });
+}
+
+function startFailure(definition, result) {
+  if (result.status === 0) return null;
+  const lines = result.stderr.trim().split(/\r?\n/);
+  const resolver = lines.find((line) => /^Error \[ERR_MODULE_NOT_FOUND\]|Cannot find module/.test(line));
+  return `${definition.file} did not start: ${resolver || lines.find(Boolean) || `exit code ${result.status}`}`;
+}
+
+/**
+ * `sourceKind` arrives as an argument rather than being read here, because the function that knows
+ * which copy of the package is answering lives beside `diagnose`. Importing it back would make this
+ * module and its caller depend on each other, and a cycle between a check and its orchestrator is
+ * how one of them ends up half-initialised at import time.
+ */
+export async function hookChecks(host, record, launcherProbe = probeHookLauncher) {
+  const launcher = launcherProbe({ env: process.env, brandRoot: host.brandRoot });
+  const starts = record ? await Promise.all(HOOK_DEFINITIONS.map(async (definition) => {
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
+    return recorded ? startHook(recordTarget(host, recorded)) : null;
+  })) : [];
+  return Promise.all(HOOK_DEFINITIONS.map(async (definition, index) => {
+    const key = `hook:${definition.event}`;
+    if (!record) return check(key, 'warn', 'cannot check before installation');
+    // The file, not just the event: PreToolUse carries two hooks of this package, and matching
+    // by event alone reported the worktree lock's matcher as pointing at order-gate.mjs. The
+    // hook line is the only place an operator can see WHICH file a matcher was registered for,
+    // so a wrong name here is worse than no line at all.
+    const recorded = record.hooks.find((hook) => hook.event === definition.event
+      && path.basename(hook.path) === definition.file);
+    if (!recorded) {
+      return check(key, 'warn', `${definition.event} hook is not present in the installation record`);
+    }
+    const expected = recordTarget(host, recorded);
+    const fullCommand = commandFor(expected);
+    const shortCommand = `codex-bridge hook ${definition.name}`;
+    try {
+      const state = await inspectHook(host.settingsPath, {
+        event: definition.event,
+        matcher: definition.matcher,
+        command: recorded.command || fullCommand,
+        alternateCommands: [fullCommand, shortCommand],
+      });
+      if (state.present) {
+        const recordedMatcher = state.matchedMatcher;
+        const command = state.matchedCommand || recorded.command || fullCommand;
+        const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
+        const reason = form === 'short'
+          ? launcher.ok
+            ? 'codex-bridge on PATH launches guards from this home'
+            : `short command but ${launcher.reason}: the command on PATH runs its own package copy, not this home, and refuses names it does not know; run codex-bridge update`
+          : launcher.ok
+            ? 'a short command is now safe; run codex-bridge update'
+            : 'full path uses the copy placed by the last install';
+        const problems = [startFailure(definition, starts[index])].filter(Boolean);
+        // The matcher printed is the one the host recorded, never the one this package declares.
+        // Until 2026-08-23 the line stated the registry's own value, so a host stuck on the
+        // pre-shell matcher read as [ok] while the worktree lock never saw a Bash command — the
+        // same shape as the 2026-08-10 defect, where doctor counted files instead of
+        // reading them. A check that compares the package to itself cannot fail.
+        if (recordedMatcher !== definition.matcher) problems.push(`recorded matcher ${recordedMatcher} differs from expected ${definition.matcher}; run codex-bridge update --force`);
+        const health = problems.length ? `; ${problems.join('; ')}` : '';
+        const status = form === 'short' && !launcher.ok ? 'fail'
+          : form === 'path' && launcher.ok || problems.length ? 'warn' : 'ok';
+        return check(key, status, `${definition.event} matcher ${recordedMatcher} -> ${expected} (${form} command; ${reason}${form === 'path' ? `; ${hookVersion(record)}` : ''}${health})`);
+      }
+      const command = recorded.command || fullCommand;
+      const form = command.startsWith('codex-bridge hook ') ? 'short' : 'path';
+      const failure = startFailure(definition, starts[index]);
+      // An entry missing from settings is a registration problem whatever the launcher can do;
+      // update restores it in the form the proof allows.
+      return check(key, 'warn', `${definition.event} matcher ${definition.matcher} does not point to the installed ${definition.file} (${form} command${form === 'path' ? `; ${hookVersion(record)}` : ''}${failure ? `; ${failure}` : ''})`);
+    } catch (err) {
+      const value = err.code === 'ENOENT' ? 'settings.json is absent' : `settings.json is invalid: ${err.message}`;
+      return check(key, 'warn', `${definition.event} hook: ${value}`);
+    }
+  }));
+}

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}`);
+  }
+}