@lyupro/codex-bridge 0.6.5 → 0.6.7

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-runs.mjs

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

package/cli/doctor.mjs

@@ -17,6 +17,12 @@ import {
 } from './doctor-installation.mjs';
 import { hookChecks } from './doctor-hooks.mjs';
 import { contractStatus, detectHostVersion, 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 { liveRunsCheck, projectRunsCheck, retentionCheck } from './doctor-runs.mjs';
 
 export { renderDoctor };
@@ -52,12 +58,28 @@ export function probeCodexBridge() {
   return { available: true, value: (result.stdout || result.stderr).trim() };
 }
 
+// Plan_62 D19: `changed` fails because the dispatcher gate rests on that contract; everything short of a
+// measured break only warns. A corrupt record gets one line: the probe refuses to overwrite it.
+const DISPATCHER_CONTRACT_STATUS = { verified: 'ok', changed: 'fail' };
+
+function dispatcherContractChecks({ record, version, stateDir }) {
+  if (record?.corrupt) {
+    return [check('dispatcherContract', 'warn',
+      `The dispatcher contract record is unreadable; delete ${path.join(stateDir, DISPATCHER_CONTRACT_FILE)}, then run ${PROBE_COMMAND}.`)];
+  }
+  return dispatcherContractStatus({ record, version }).map(({ contract, state, message }) =>
+    check(`dispatcherContract:${contract}`, DISPATCHER_CONTRACT_STATUS[state] ?? 'warn', message));
+}
+
 export async function diagnose({
   host,
   codexProbe = probeCodex,
   bridgeProbe = probeCodexBridge,
+  launcherProbe,
   currentPackage,
   contractRecord,
+  handbackWitnessRecord,
+  dispatcherContractRecord,
   hostVersion,
 } = {}) {
   const checks = [sourceCheck()];
@@ -101,15 +123,28 @@ export async function diagnose({
   checks.push(await permissionsCheck(host));
   const bridge = bridgeProbe();
   checks.push(bridgeCommandCheck(bridge));
-  checks.push(...await hookChecks(host, record, () => bridge, ownPackage, packageSource().kind));
+  checks.push(...await hookChecks(host, record, launcherProbe));
+  const detectedHostVersion = hostVersion === undefined ? detectHostVersion() : hostVersion;
   const hostContract = contractStatus({
     record: contractRecord === undefined ? await readHostContract(host) : contractRecord,
-    version: hostVersion === undefined ? detectHostVersion() : hostVersion,
+    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));
+  checks.push(...dispatcherContractChecks({
+    record: dispatcherContractRecord === undefined ? readDispatcherContract({ stateDir }) : dispatcherContractRecord,
+    version: detectedHostVersion,
+    stateDir,
+  }));
   const retention = retentionCheck(host);
   checks.push(retention);
   const conventions = await conventionsCheck(host);
@@ -127,7 +162,8 @@ export async function diagnose({
   return {
     exitCode: !record || recordBroken || missingFiles.length || agents.status === 'fail' || rules.status === 'fail'
       || hostContractStatus === 'fail' || retention.status === 'fail' || conventions.status === 'fail'
-      || projectRuns.status === 'fail' ? 1 : 0,
+      || projectRuns.status === 'fail'
+      || checks.some((item) => /^(hook|dispatcherContract):/.test(item.key) && item.status === 'fail') ? 1 : 0,
     checks,
     record,
     missingFiles,

package/cli/handback-witness-check.mjs

@@ -0,0 +1,39 @@
+/** Surfaces handback drift because the 2026-09-17..24 contract break went unnoticed for a week. */
+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.` };
+  }
+  if (record?.alarms?.length > 0) {
+    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.`,
+    };
+  }
+  if (!record?.lastSeen) {
+    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) {
+    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.`,
+    };
+  }
+  return {
+    state: 'seen',
+    message: `Handback contract last seen on SDK ${record.lastSeen.sdkVersion} (host ${hostVersion}) at ${record.lastSeen.at}.`,
+  };
+}

package/cli/hook-targets.mjs

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

package/cli/hook.mjs

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