@lyupro/codex-bridge 0.5.2 → 0.5.4

package/cli/doctor-runs.mjs

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

package/cli/doctor.mjs

@@ -1,79 +1,24 @@
 /** Diagnoses a Claude Code host without modifying it. */
-import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawn, spawnSync } from 'node:child_process';
-import {
-  buildInstallPlan,
-  contentFingerprint,
-  fileFingerprint,
-  HOOK_DEFINITIONS,
-  readInstallRecord,
-  packageInfo,
-} from './manifest.mjs';
-import { plannedContent } from './copy.mjs';
+import { spawnSync } from 'node:child_process';
+import { readInstallRecord, packageInfo } from './manifest.mjs';
 import { recordTarget } from './install-record.mjs';
-import { inspectPermissions } from './permissions.mjs';
-import { commandFor, inspectHook } from './settings-merge.mjs';
-import { readRulesRegistry } from './rules-owners.mjs';
-import { parseFrontmatter } from './frontmatter.mjs';
-import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 import { runsRoot } from '../src/home/lib/runner/runs-root.mjs';
-import { resolveProjectRunsDir } from '../src/home/lib/runner/project-dir.mjs';
-import { allLiveRuns } from '../src/home/hooks/live-runs.mjs';
-import { STOP_COMMAND_TEMPLATE } from '../src/home/lib/stop-contract.mjs';
-
-const WARNING = '\u001b[33m';
-const RESET = '\u001b[0m';
-
-async function exists(target) {
-  try {
-    await fs.access(target);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isFile(target) {
-  try {
-    return (await fs.stat(target)).isFile();
-  } catch {
-    return false;
-  }
-}
-
-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`);
-}
+import { check, renderDoctor } from './doctor-format.mjs';
+import {
+  agentsCheck,
+  conventionsCheck,
+  exists,
+  isFile,
+  permissionsCheck,
+  rulesCheck,
+} from './doctor-installation.mjs';
+import { hookChecks } from './doctor-hooks.mjs';
+import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
+import { liveRunsCheck, projectRunsCheck, retentionCheck } from './doctor-runs.mjs';
+
+export { renderDoctor };
 
 function bridgeCommandCheck(result) {
   return result.available
@@ -81,33 +26,6 @@ function bridgeCommandCheck(result) {
     : check('command', 'warn', `codex-bridge does not resolve on PATH (${result.value}); run npm i -g @lyupro/codex-bridge`);
 }
 
-function check(key, status, value) {
-  return { key, status, value };
-}
-
-function retentionCheck(host) {
-  try {
-    const notice = retentionNotice(readRunConfig(host.brandConfigPath));
-    return check('retention', notice.enabled ? 'warn' : 'ok', notice.text);
-  } catch (err) {
-    return check('retention', 'fail', `invalid configuration: ${err.message}`);
-  }
-}
-
-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)`);
-}
-
 /**
  * Which copy of the package is answering. Plan_19 gives the CLI a second name, and a global install
  * puts a second copy of the package on the machine beside any clone. `update` copies host files
@@ -129,43 +47,6 @@ function sourceCheck() {
   return check('source', 'ok', `${source.root} (${source.kind === 'installed copy' ? 'installed package' : source.kind})`);
 }
 
-/**
- * The runner asks git for the repository root before it picks a runs folder, so doctor has to
- * ask the same question: run from `src/home/lib/runner`, a plain cwd would name the folder `runner` and
- * report a location no run will ever use.
- */
-function repoRoot(cwd) {
-  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
-  return top.status === 0 && top.stdout.trim() ? top.stdout.trim() : cwd;
-}
-
-/**
- * A marker that cannot be read is exactly what doctor exists to report, so it is caught here.
- * Left to propagate it would kill the whole diagnosis and hide the seven checks around it.
- */
-function projectRunsCheck() {
-  let resolved;
-  try {
-    resolved = resolveProjectRunsDir(runsRoot(), repoRoot(process.cwd()), { create: false });
-  } catch (err) {
-    return check('projectRuns', 'fail', err.message);
-  }
-  const note = resolved.reason === 'created' ? 'not created yet' : resolved.reason;
-  return check('projectRuns', 'ok', `${path.resolve(resolved.dir)} (${note})`);
-}
-
-function liveRunsCheck() {
-  let count;
-  try {
-    count = allLiveRuns(runsRoot(), { requireConfirmedIdentity: true }).length;
-  } catch (err) {
-    return check('liveRuns', 'warn', `working-run count unavailable: ${err.message}`);
-  }
-  if (!count) return check('liveRuns', 'ok', '0 runs working right now');
-  const noun = count === 1 ? 'run' : 'runs';
-  return check('liveRuns', 'warn', `${count} ${noun} working right now; stop with ${STOP_COMMAND_TEMPLATE}`);
-}
-
 export function probeCodex() {
   const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
   const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'codex --version'] : ['--version'];
@@ -186,136 +67,14 @@ export function probeCodexBridge() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
-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}`}`;
-}
-
-async function hookChecks(host, record, bridgeProbe, ownPackage) {
-  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 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);
-        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 ${packageSource().kind} version ${ownPackage.version}`);
-        }
-        const health = problems.length ? `; ${problems.join('; ')}` : '';
-        return check(key, problems.length ? 'warn' : 'ok', `${definition.event} matcher ${definition.matcher} -> ${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}`);
-    }
-  }));
-}
-
-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})`);
-}
-
-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}`);
-  }
-}
-
-export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = probeCodexBridge, currentPackage } = {}) {
+export async function diagnose({
+  host,
+  codexProbe = probeCodex,
+  bridgeProbe = probeCodexBridge,
+  currentPackage,
+  contractRecord,
+  hostVersion,
+} = {}) {
   const checks = [sourceCheck()];
   const hostExists = await exists(host.root);
   checks.push(check('host', hostExists ? 'ok' : 'warn', `${host.root} (${host.scope}, ${hostExists ? 'exists' : 'absent'})`));
@@ -357,7 +116,15 @@ export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = pr
   checks.push(await permissionsCheck(host));
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
-  checks.push(...await hookChecks(host, record, () => bridge, ownPackage));
+  checks.push(...await hookChecks(host, record, () => bridge, ownPackage, packageSource().kind));
+  const hostContract = contractStatus({
+    record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
+    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+  });
+  const hostContractStatus = hostContract.state === 'verified'
+    ? 'ok'
+    : hostContract.state === 'ignored' ? 'fail' : 'warn';
+  checks.push(check('hostContract', hostContractStatus, hostContract.message));
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -374,19 +141,10 @@ export async function diagnose({ host, codexProbe = probeCodex, bridgeProbe = pr
 
   return {
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
-      || retention.status === 'fail' || conventions.status === 'fail' || projectRuns.status === 'fail' ? 1 : 0,
+      || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
+      || projectRuns.status === 'fail' ? 1 : 0,
     checks,
     record,
     missingFiles,
   };
 }
-
-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'].includes(key) && status === 'warn'
-      ? `${WARNING}${rendered}${RESET}`
-      : rendered;
-  }).join('\n');
-}

package/cli/host-contract.mjs

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

package/cli/hosts.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { resolveBrandHome } from '../src/home/lib/brand-home.mjs';
 
 function repositoryRoot(start) {
   let current = path.resolve(start);
@@ -35,9 +36,9 @@ export function resolveHost({
   // Plan_25 moves package-owned runtime files out of foreign Claude settings, whose absolute
   // hook paths caused the package-file-layout incident. Keep the brand root overrideable so tests
   // and later installation steps never need to know the operator's home directory.
-  const resolvedBrandRoot = path.resolve(
-    brandRoot || process.env.CODEX_BRIDGE_HOME || path.join(homedir, '.lyupro', '.codex-bridge'),
-  );
+  const resolvedBrandRoot = brandRoot
+    ? path.resolve(brandRoot)
+    : resolveBrandHome({ homedir, env: process.env }).root;
   const brandPaths = {
     brandRoot: resolvedBrandRoot,
     brandHooksDir: path.join(resolvedBrandRoot, 'hooks'),

package/cli/install.mjs

@@ -26,6 +26,7 @@ import {
 } from './settings-merge.mjs';
 import { addRulesOwner, readRulesRegistry } from './rules-owners.mjs';
 import { addPermissionRules } from './permissions.mjs';
+import { contractStatus, detectHostVersion, readHostContract } from './host-contract.mjs';
 import { readRunConfig, retentionNotice } from '../src/home/lib/run-config.mjs';
 
 const WARNING = '\u001b[33m';
@@ -56,6 +57,10 @@ function retentionOutput(line, output) {
   return `${output}\n${line}`;
 }
 
+function contractOutput(status, output) {
+  return status.state === 'verified' ? output : `${output}\n${status.message}`;
+}
+
 async function migrateLegacySeed(host, seed) {
   if (await targetExists(seed.target)) return;
   const legacyName = path.basename(seed.target) === 'config.json' ? 'run-config.json' : path.basename(seed.target);
@@ -73,10 +78,22 @@ async function migrateLegacySeed(host, seed) {
   await fs.rm(legacy, { force: true });
 }
 
-async function installInRun({ host, dryRun = false, force = false, packageRoot, env = process.env } = {}) {
+async function installInRun({
+  host,
+  dryRun = false,
+  force = false,
+  packageRoot,
+  env = process.env,
+  contractRecord,
+  hostVersion,
+} = {}) {
   // 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({
+    record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
+    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+  });
   const plan = await buildInstallPlan(host, packageRoot);
   const rule = { ...rulesPlan(host, packageRoot), processing: 'copy' };
   const currentPackage = await packageInfo(packageRoot);
@@ -112,7 +129,7 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
     const files = conflicts.map(({ item }) => `  ${item.relativeToRoot || item.name}`).join('\n');
     return {
       exitCode: 1,
-      output: retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`),
+      output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, `Conflicting files:\n${files}\nRun install again with --force to overwrite them.`)),
     };
   }
 
@@ -124,7 +141,10 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   if (!changedFiles.length && !changedRule && inspectedHooks.every((state) => state.present)
     && recordHasHooks(record, targets) && sameRecord) {
     if (!dryRun) await addRulesOwner(host);
-    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.') };
+    return {
+      exitCode: 0,
+      output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, 'codex-bridge is already installed; nothing to do.')),
+    };
   }
 
   if (dryRun) {
@@ -140,7 +160,7 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
         : `Would register ${definition.event} hook for matcher ${definition.matcher} with ${registration.form} command.`);
     });
     lines.push('Would write installation record in the brand root.');
-    return { exitCode: 0, output: retentionOutput(configuredRetentionLine, lines.join('\n')) };
+    return { exitCode: 0, output: contractOutput(hostContract, retentionOutput(configuredRetentionLine, lines.join('\n'))) };
   }
 
   // Claim ownership of the shared rules file before writing anything. Claiming it last meant a
@@ -196,10 +216,13 @@ async function installInRun({ host, dryRun = false, force = false, packageRoot,
   });
   return {
     exitCode: 0,
-    output: retentionOutput(
-      configuredRetentionLine,
-      `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`
-        + `\nGranted ${permissionResult.added} permission rule(s) in ${host.settingsPath} so the host runs the package command without asking.`,
+    output: contractOutput(
+      hostContract,
+      retentionOutput(
+        configuredRetentionLine,
+        `Installed ${plan.length + 1} files and registered the ${targets.map(({ definition }) => definition.event).join(' and ')} hooks.`
+          + `\nGranted ${permissionResult.added} permission rule(s) in ${host.settingsPath} so the host runs the package command without asking.`,
+      ),
     ),
   };
 }