@lyupro/codex-bridge 0.5.3 → 0.5.5

package/bin/codex-bridge.mjs

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

package/cli/doctor-format.mjs

@@ -0,0 +1,23 @@
+/** Shapes how one diagnosis line looks. */
+
+// Built from a character code rather than written as an escape: an escape sequence in this file
+// survives every editor, but not every tool that has rewritten it — a literal escape byte landed
+// here once during the Plan_52 split and is invisible in diffs and greps, which is exactly the kind
+// of character a source file should not carry silently.
+const ESC = String.fromCharCode(27);
+const WARNING = `${ESC}[33m`;
+const RESET = `${ESC}[0m`;
+
+export function check(key, status, value) {
+  return { key, status, value };
+}
+
+export function renderDoctor(result) {
+  return result.checks.map(({ key, status, value }) => {
+    if ((key === 'agents' || key === 'command') && status !== 'ok') return value;
+    const rendered = `[${status}] ${key}: ${value}`;
+    return ['retention', 'conventions', 'permissions', 'liveRuns', 'hostContract'].includes(key) && status === 'warn'
+      ? `${WARNING}${rendered}${RESET}`
+      : rendered;
+  }).join('\n');
+}

package/cli/doctor-hooks.mjs

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

package/cli/doctor-installation.mjs

@@ -0,0 +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 { 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 allow/deny${shadow})`);
+  } catch (err) {
+    return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
+  }
+}