@celilo/cli 1.13.0 → 2.0.0

package/src/cli/commands/console-get-chain.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The wiring, end to end: does `celilo console get` actually carry the chain?
+ *
+ * `orderFirewallChain` is unit-tested, `computeClosure` is unit-tested, and
+ * `loadClosureInputs` is unit-tested against real rows. None of that says the
+ * command joins them up. A dropped argument at this one call site returns a
+ * perfectly well-formed answer with an empty `chains` — which reads as a fleet
+ * with no delegation, and is the failure mode CLAUDE.md names.
+ *
+ * So this drives the REAL command against a REAL database and asserts on what
+ * it emits.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let testDir: string;
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'celilo-console-chain-'));
+  process.env.CELILO_DB_PATH = join(testDir, 'test.db');
+  process.env.CELILO_DATA_DIR = testDir;
+});
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  process.env.CELILO_DB_PATH = undefined;
+});
+
+/** The live fleet's firewall shape: caddy on iptables, iptables on the router. */
+async function seedFleet() {
+  const { getDb } = await import('../../db/client');
+  const db = getDb();
+  const consumer = JSON.stringify({ requires: { capabilities: [{ name: 'firewall' }] } });
+
+  db.$client.run(
+    `INSERT INTO modules (id, name, version, source_path, manifest_data, state)
+     VALUES ('caddy', 'Caddy', '1.0.0', '/p', '${consumer}', 'VERIFIED')`,
+  );
+  for (const id of ['iptables', 'axon']) {
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data, state)
+       VALUES ('${id}', '${id}', '1.0.0', '/p', '{}', 'VERIFIED')`,
+    );
+  }
+  db.$client.run(
+    `INSERT INTO capabilities (module_id, capability_name, version, data)
+     VALUES ('iptables', 'firewall', '1.0.0', '{"nat_ip":"192.168.0.253"}')`,
+  );
+  db.$client.run(
+    `INSERT INTO capabilities (module_id, capability_name, version, data)
+     VALUES ('axon', 'firewall', '1.0.0', '{"has_external":true}')`,
+  );
+}
+
+describe('celilo console get, and the delegation chain', () => {
+  test('--json carries the chain, in order', async () => {
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const result = handleConsoleGet(['caddy'], { json: true });
+
+    expect(result.success).toBe(true);
+    const payload = JSON.parse(result.success ? result.message : '{}');
+    expect(payload.chains).toEqual([{ capability: 'firewall', moduleIds: ['iptables', 'axon'] }]);
+  });
+
+  test('the router is in the closure, though no manifest mentions it', async () => {
+    // caddy requires `firewall` and nothing else. Walking manifests alone stops
+    // at the two registered providers and has no way to know one stands on the
+    // other — which is the whole reason the chain is derived.
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const payload = JSON.parse(
+      (() => {
+        const r = handleConsoleGet(['caddy'], { json: true });
+        return r.success ? r.message : '{}';
+      })(),
+    );
+
+    const axon = payload.nodes.find((n: { moduleId: string }) => n.moduleId === 'axon');
+    expect(axon).toBeDefined();
+  });
+
+  test('the human output prints it as a path, not as more rows', async () => {
+    // A list of two firewalls is exactly the claim being corrected. The arrow is
+    // the information.
+    await seedFleet();
+    const { handleConsoleGet } = await import('./console');
+    const result = handleConsoleGet(['caddy'], {});
+
+    expect(result.success).toBe(true);
+    expect(result.success ? result.message : '').toContain('iptables -> axon');
+  });
+});

package/src/cli/commands/console.ts

@@ -73,7 +73,7 @@ export function handleConsoleGet(
   const depth = parseDepth(flags.depth);
   if (depth instanceof Error) return { success: false, error: depth.message };
 
-  const { manifests, providerStates } = loadClosureInputs(db);
+  const { manifests, providerStates, chains } = loadClosureInputs(db);
 
   // Real bindings, for every module the walk might reach. The console draws what
   // the fleet IS doing, not what its manifests permit.
@@ -86,6 +86,7 @@ export function handleConsoleGet(
     providerStates,
     depth,
     bindings,
+    chains,
   });
 
   if (hasFlag(flags, 'json')) {
@@ -98,14 +99,21 @@ export function handleConsoleGet(
     return { success: true, message: `${moduleId} depends on nothing.` };
   }
 
+  // The chain is printed as a path rather than as more rows, because that is the
+  // whole claim: these providers are ordered, and a list of them is not.
+  const chainLines = result.chains.map(
+    (chain) => `${chain.capability}: ${chain.moduleIds.join(' -> ')}`,
+  );
+
   return {
     success: true,
-    message: result.nodes
-      .map(
+    message: [
+      ...result.nodes.map(
         (n) =>
           `hop ${n.hop}  ${n.moduleId.padEnd(24)} ${n.optional ? '(optional)' : '          '} via ${n.via.join(', ')}`,
-      )
-      .join('\n'),
+      ),
+      ...(chainLines.length > 0 ? ['', 'delegates upstream:', ...chainLines] : []),
+    ].join('\n'),
   };
 }
 

package/src/cli/commands/monitor.ts

@@ -6,10 +6,12 @@
  * and audit checks into the injectable deps `runOneMonitor` expects.
  */
 
+import { hostname } from 'node:os';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import { getEventBusPath } from '../../config/paths';
 import { getDb } from '../../db/client';
 import type { MonitorKind } from '../../db/schema';
+import { readJailMode } from '../../hooks/jail';
 import {
   isSchedulableBuiltin,
   runBuiltinCheckForMonitor,
@@ -17,6 +19,7 @@ import {
 import { loadModuleCoverage } from '../../services/alerting/coverage-source';
 import { loadModuleHealthCadences } from '../../services/alerting/health-cadence';
 import { HEALTH_COVERAGE_CHECK } from '../../services/alerting/health-coverage';
+import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
 import {
   createMonitor,
   ensureSweepSubscriber,
@@ -50,6 +53,7 @@ function buildDeps() {
       runModuleHealthCheck(moduleId, db, { unattended: true, noInteractive: true }),
     runBuiltinCheck: (category: DriftCategory) => runBuiltinCheckForMonitor(category, db),
     loadModuleCoverage: () => loadModuleCoverage(db),
+    loadJailState: () => ({ record: readJailMode(), host: hostname() }),
     now: () => new Date(),
     graceMs: DEFAULT_GRACE_MS,
   };
@@ -120,7 +124,10 @@ function handleAdd(args: string[], flags: Record<string, boolean | string>): Com
   // underscore heuristic alone would file it as a module hook against a module
   // that does not exist.
   const kind: MonitorKind =
-    target === HEALTH_COVERAGE_CHECK || isSchedulableBuiltin(target) || target.includes('_')
+    target === HEALTH_COVERAGE_CHECK ||
+    target === HOOK_JAIL_CHECK ||
+    isSchedulableBuiltin(target) ||
+    target.includes('_')
       ? 'builtin_check'
       : 'module_hook';
 
@@ -148,7 +155,13 @@ function handleAdd(args: string[], flags: Record<string, boolean | string>): Com
   const cadence = parseCadence(interval);
   const intervalMinutes = cadence !== null && cadence !== 'manual' ? cadence.minutes : 0;
 
-  createMonitor(db, { kind, target, intervalMinutes });
+  // The hook-jail check is a SELF-monitor: it watches celilo's own confinement
+  // of module hooks, and the alerting spec marks monitors watching the system
+  // itself unsuppressible. That is a property of the target, not an operator
+  // choice — losing the jail during a broad outage is exactly when no ancestor
+  // alert may silence it.
+  const suppressible = target === HOOK_JAIL_CHECK ? false : undefined;
+  createMonitor(db, { kind, target, intervalMinutes, suppressible });
 
   // Creating the first monitor is also what switches the sweep on. Registering
   // here rather than at install means a celilo with no monitors carries no

package/src/cli/commands/notify-config.test.ts

@@ -0,0 +1,79 @@
+/**
+ * `celilo person list --json` — the shape the web console maps an identity
+ * against.
+ *
+ * Worth its own test for a reason that is not obvious from the three lines it
+ * covers. The console server decides whether an authenticated browser subject
+ * corresponds to a real person, and it decides it by reading THIS. Its own
+ * tests answer that question against a fake celilo, so they prove the console
+ * parses what it was told to expect and say nothing about what celilo emits.
+ * This is the end that closes.
+ *
+ * If the payload ever stops being `[{ name, timezone }]`, the console does not
+ * error: it maps nobody, draws no acknowledge control, and reports every
+ * operator as unknown to the fleet. That reads as a configuration problem for
+ * as long as anyone is willing to believe it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../../db/client';
+import { createPerson } from '../../services/alerting/people';
+import { setupTestDatabaseAt } from '../../test-utils/database';
+import { handlePerson } from './notify-config';
+
+let dir: string;
+const previousDbPath = process.env.CELILO_DB_PATH;
+
+beforeEach(async () => {
+  dir = mkdtempSync(join(tmpdir(), 'celilo-person-'));
+  const dbPath = join(dir, 'test.db');
+  const db = await setupTestDatabaseAt(dbPath);
+  createPerson(db, { name: 'peter', timezone: 'America/Los_Angeles' });
+  createPerson(db, { name: 'ada', timezone: 'Europe/London' });
+  db.$client.close();
+  process.env.CELILO_DB_PATH = dbPath;
+});
+
+afterEach(() => {
+  closeDb();
+  if (previousDbPath === undefined) delete process.env.CELILO_DB_PATH;
+  else process.env.CELILO_DB_PATH = previousDbPath;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+/** Run `person list`, insisting it succeeded before reading what it said. */
+async function personList(flags: Record<string, boolean | string>): Promise<string> {
+  const result = await handlePerson('list', [], flags);
+  if (!result.success) throw new Error(`person list failed: ${result.error}`);
+  return result.message;
+}
+
+async function listJson(): Promise<{ name: string; timezone: string }[]> {
+  return JSON.parse(await personList({ json: true }));
+}
+
+describe('celilo person list --json', () => {
+  test('names every person, sorted the way listPeople sorts them', async () => {
+    expect((await listJson()).map((p) => p.name)).toEqual(['ada', 'peter']);
+  });
+
+  test('carries the timezone, which is the only other thing a person IS', async () => {
+    const ada = (await listJson()).find((p) => p.name === 'ada');
+    expect(ada?.timezone).toBe('Europe/London');
+  });
+
+  test('an empty fleet is an empty array, not a sentence about it', async () => {
+    // The human listing prints "Nobody configured." and a hint. A caller that
+    // parsed that would throw, which is a better failure than the one this
+    // avoids — but the console polls this, so it gets JSON either way.
+    getDb().$client.run('DELETE FROM people');
+    expect(await listJson()).toEqual([]);
+  });
+
+  test('without --json it stays the human table, and says how many', async () => {
+    expect(await personList({})).toContain('2 person');
+  });
+});

package/src/cli/commands/notify-config.ts

@@ -33,6 +33,7 @@ import {
   listRoutes,
 } from '../../services/alerting/people';
 import { parseClockTime } from '../../services/alerting/quiet-hours';
+import { hasFlag } from '../parser';
 import type { CommandResult } from '../types';
 
 const NO_SCHEMAS = defineEvents({});
@@ -109,8 +110,18 @@ function personAdd(args: string[], flags: Record<string, boolean | string>): Com
   return { success: true, message: `Added ${name} (${timezone}${quietNote})` };
 }
 
-function personList(): CommandResult {
+function personList(flags: Record<string, boolean | string> = {}): CommandResult {
   const people = listPeople(getDb());
+
+  // The web console's subject-to-person mapping reads this. It never invents a
+  // person and never lets celilo fall back to `people[0]`, so it has to be able
+  // to ASK who exists. `person:list` is already in the read-only grant set, so
+  // the flag adds a shape rather than an authority.
+  if (hasFlag(flags, 'json')) {
+    const payload = people.map((p) => ({ name: p.name, timezone: p.timezone }));
+    return { success: true, message: JSON.stringify(payload), rawOutput: true, data: payload };
+  }
+
   if (people.length === 0) {
     console.log('\nNobody configured.\n');
     console.log(
@@ -158,7 +169,7 @@ export async function handlePerson(
   switch (subcommand) {
     case undefined:
     case 'list':
-      return personList();
+      return personList(flags);
     case 'add':
       return personAdd(args, flags);
     case 'remove':

package/src/cli/commands/system-doctor.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from 'bun:test';
-import { compareVersions } from './system-doctor';
+import type { JailModeRecord } from '../../hooks/jail';
+import {
+  type HookExecutionInput,
+  compareVersions,
+  renderHookExecutionSection,
+} from './system-doctor';
 
 describe('compareVersions', () => {
   test('detects ascending major/minor/patch', () => {
@@ -34,3 +39,118 @@ describe('compareVersions', () => {
     expect(compareVersions('v1.2.3', '1.2.3')).toBe(0);
   });
 });
+
+describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
+  const HOST = 'celilo-mgr';
+  const jailedRecord: JailModeRecord = {
+    mode: 'jailed',
+    backend: 'bubblewrap',
+    host: HOST,
+    recordedAt: '2026-08-28T09:00:00.000Z',
+  };
+  const regressedRecord: JailModeRecord = {
+    mode: 'unjailed',
+    backend: 'none',
+    reason: 'bubblewrap is installed but could not build a namespace, so hooks run unjailed.',
+    host: HOST,
+    recordedAt: '2026-08-28T09:00:00.000Z',
+    lastJailed: { backend: 'bubblewrap', recordedAt: '2026-08-27T09:00:00.000Z' },
+  };
+
+  const render = (over: Partial<HookExecutionInput>) =>
+    renderHookExecutionSection({
+      availability: { backend: 'bubblewrap' },
+      policy: 'auto',
+      record: jailedRecord,
+      host: HOST,
+      monitored: true,
+      ...over,
+    });
+
+  const text = (r: { lines: string[] }) => r.lines.join('\n');
+
+  test('a jailing host is a ✔ and nothing more', () => {
+    const r = render({});
+    expect(text(r)).toContain('hooks run jailed (bubblewrap)');
+    expect(r.failCount).toBe(0);
+    expect(r.warnCount).toBe(0);
+  });
+
+  test('unjailed says why in the reason sentence, as a warning and not a failure', () => {
+    const r = render({
+      availability: {
+        backend: 'none',
+        reason:
+          'bubblewrap is not installed, so hooks run unjailed. Install it (`apt install bubblewrap`) and re-run.',
+      },
+      record: undefined,
+      monitored: null,
+    });
+    expect(text(r)).toContain('hooks run unjailed — bubblewrap is not installed');
+    expect(text(r)).toContain('no execution mode recorded yet');
+    expect(r.warnCount).toBe(1);
+    expect(r.failCount).toBe(0);
+  });
+
+  test('CELILO_HOOK_JAIL=off is reported as the operator’s own act', () => {
+    const r = render({ policy: 'off', record: undefined });
+    expect(text(r)).toContain('CELILO_HOOK_JAIL=off');
+    expect(r.warnCount).toBe(1);
+  });
+
+  test('auto deferral on sandbox-exec reads as unjailed, not jailed (ce-29z)', () => {
+    // The doctor and the executor share one predicate (autoJailDefers), so
+    // the doctor cannot report a jail the executor will not build. When D14
+    // lands and the flag flips, this goes back to ✔ with no code change here.
+    const r = render({ availability: { backend: 'sandbox-exec' }, record: undefined });
+    expect(text(r)).toContain('hooks run unjailed — macOS hooks run unjailed');
+    expect(text(r)).not.toContain('hooks run jailed');
+    expect(r.warnCount).toBe(1);
+    expect(r.failCount).toBe(0);
+  });
+
+  test('required with no backend is a failure, because every hook fails', () => {
+    const r = render({
+      policy: 'required',
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: undefined,
+    });
+    expect(text(r)).toContain('CELILO_HOOK_JAIL=required and no jail is available');
+    expect(r.failCount).toBe(1);
+  });
+
+  test('a host that used to jail and has stopped is a failure naming when', () => {
+    const r = render({
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: regressedRecord,
+    });
+    expect(text(r)).toContain('ran hooks jailed (bubblewrap) until 2026-08-27T09:00:00.000Z');
+    expect(r.failCount).toBe(1);
+  });
+
+  test('an unmonitored regression points at the self-monitor', () => {
+    const r = render({
+      availability: { backend: 'none', reason: 'the profile did not load' },
+      record: regressedRecord,
+      monitored: false,
+    });
+    expect(text(r)).toContain('celilo monitor add hook_jail');
+  });
+
+  test('a jailing but unmonitored host is told the transition alerts only if monitored', () => {
+    const r = render({ monitored: false });
+    expect(text(r)).toContain('celilo monitor add hook_jail');
+    expect(r.failCount).toBe(0);
+  });
+
+  test('a dev box with no DB gets no monitor hint', () => {
+    const r = render({ monitored: null });
+    expect(text(r)).not.toContain('monitor add');
+  });
+
+  test("another host's record reads as a move, not this host's history", () => {
+    const r = render({ record: { ...regressedRecord, host: 'old-box' } });
+    expect(text(r)).toContain('belongs to host "old-box"');
+    expect(r.failCount).toBe(0);
+  });
+});

package/src/cli/commands/system-doctor.ts

@@ -32,13 +32,27 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { resolveBrowser } from '@celilo/capabilities';
 import { defineEvents, openBus } from '@celilo/event-bus';
 import cliPkg from '../../../package.json' with { type: 'json' };
 import { getDbPath, getEventBusPath } from '../../config/paths';
 import { getDb } from '../../db/client';
+import {
+  JAIL_OFF_REASON,
+  type JailAvailability,
+  type JailModeRecord,
+  type JailPolicy,
+  SANDBOX_EXEC_AUTO_DEFERRED_REASON,
+  autoJailDefers,
+  detectJailBackend,
+  jailPolicy,
+  readJailMode,
+} from '../../hooks/jail';
 import type { ModuleManifest } from '../../manifest/schema';
+import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
+import { findMonitorByTarget } from '../../services/alerting/monitors';
 import {
   type FleetFinding,
   type FleetFindingStatus,
@@ -336,6 +350,112 @@ function provisionedBrowserFlavor(): string | null {
   }
 }
 
+export interface HookExecutionInput {
+  availability: JailAvailability;
+  policy: JailPolicy;
+  /** What the last real module-hook run recorded, if any. */
+  record: JailModeRecord | undefined;
+  host: string;
+  /**
+   * Whether a `hook_jail` monitor exists. `null` when there is no celilo DB to
+   * ask (a dev box), which also suppresses the add-the-monitor hint.
+   */
+  monitored: boolean | null;
+}
+
+/**
+ * The hook-execution section (hook-process-boundary task 4.6).
+ *
+ * Reports design D8's three states the way the design assigns them: jailed is
+ * a ✔ and nothing more; unjailed-and-always-was is reported with the reason in
+ * one actionable sentence and is a warning, not an event; a host that USED to
+ * jail and has stopped is a failure, and the self-monitor (`celilo monitor add
+ * hook_jail`) is what turns it into an alert.
+ *
+ * The headline is the LIVE answer — the probe runs bubblewrap the way a real
+ * spawn would — while the recorded mode says what the last hook actually did.
+ * They disagree exactly when the host changed since the last hook ran, which
+ * is worth seeing, not reconciling away.
+ *
+ * Pure so every branch is testable on a host with no jail (Rule 10.4); the
+ * caller injects what the machine says.
+ */
+export function renderHookExecutionSection(input: HookExecutionInput): {
+  lines: string[];
+  failCount: number;
+  warnCount: number;
+} {
+  const { availability, policy, record, host, monitored } = input;
+  const lines: string[] = ['Hook execution'];
+  let failCount = 0;
+  let warnCount = 0;
+
+  // ce-29z: auto defers on sandbox-exec, so the doctor must not report a jail
+  // the executor will not build. One predicate, two consumers.
+  const autoDeferred = policy === 'auto' && autoJailDefers(availability);
+  const liveJailed = policy !== 'off' && availability.backend !== 'none' && !autoDeferred;
+  if (policy === 'required' && availability.backend === 'none') {
+    lines.push(
+      `  ${ANSI.red}✗${ANSI.reset} CELILO_HOOK_JAIL=required and no jail is available — every module hook on this host fails rather than run unjailed`,
+    );
+    lines.push(`      ${ANSI.dim}${availability.reason ?? 'no reason was recorded'}${ANSI.reset}`);
+    failCount++;
+  } else if (policy === 'off') {
+    lines.push(`  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${JAIL_OFF_REASON}`);
+    warnCount++;
+  } else if (availability.backend === 'none') {
+    lines.push(
+      `  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${availability.reason ?? 'no reason was recorded'}`,
+    );
+    warnCount++;
+  } else if (autoDeferred) {
+    lines.push(
+      `  ${ANSI.yellow}⚠${ANSI.reset} hooks run unjailed — ${SANDBOX_EXEC_AUTO_DEFERRED_REASON}`,
+    );
+    warnCount++;
+  } else {
+    lines.push(`  ${ANSI.green}✔${ANSI.reset} hooks run jailed (${availability.backend})`);
+  }
+
+  const regressed =
+    record && record.host === host && record.mode === 'unjailed' && record.lastJailed;
+  if (regressed && record.lastJailed) {
+    lines.push(
+      `  ${ANSI.red}✗${ANSI.reset} this host ran hooks jailed (${record.lastJailed.backend}) until ${record.lastJailed.recordedAt} and has stopped`,
+    );
+    if (record.reason) lines.push(`      ${ANSI.dim}${record.reason}${ANSI.reset}`);
+    failCount++;
+    if (monitored === false) {
+      lines.push(
+        `    ${ANSI.dim}→ nothing alerts on this — celilo monitor add ${HOOK_JAIL_CHECK}${ANSI.reset}`,
+      );
+    }
+  } else if (!record) {
+    lines.push(
+      `  ${ANSI.dim}no execution mode recorded yet — the first real module-hook run writes it${ANSI.reset}`,
+    );
+  } else if (record.host !== host) {
+    lines.push(
+      `  ${ANSI.dim}last recorded mode belongs to host "${record.host}" (this data directory moved) — the next hook run re-records${ANSI.reset}`,
+    );
+  } else {
+    const backend = record.mode === 'jailed' ? ` (${record.backend})` : '';
+    lines.push(
+      `  ${ANSI.dim}last hook ran ${record.mode}${backend} at ${record.recordedAt}${ANSI.reset}`,
+    );
+  }
+
+  // The moment this hint pays for itself is BEFORE a regression: the monitor
+  // has to exist for the transition to page anyone.
+  if (liveJailed && monitored === false) {
+    lines.push(
+      `    ${ANSI.dim}→ a host that stops jailing alerts only if monitored: celilo monitor add ${HOOK_JAIL_CHECK}${ANSI.reset}`,
+    );
+  }
+
+  return { lines, failCount, warnCount };
+}
+
 /**
  * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
  * package.json). The fleet dispatcher check compares this against the
@@ -616,6 +736,33 @@ export async function handleSystemDoctor(
   lines.push(...prereqResult.lines);
   lines.push('');
 
+  // Hook execution mode (hook-process-boundary task 4.6). The policy read
+  // throws on a typo'd CELILO_HOOK_JAIL — report that rather than crash the
+  // doctor, since the same throw is about to fail every hook invocation too.
+  let hookExec: { lines: string[]; failCount: number; warnCount: number };
+  try {
+    hookExec = renderHookExecutionSection({
+      availability: detectJailBackend(),
+      policy: jailPolicy(),
+      record: readJailMode(),
+      host: hostname(),
+      monitored: existsSync(getDbPath())
+        ? findMonitorByTarget(getDb(), HOOK_JAIL_CHECK) !== undefined
+        : null,
+    });
+  } catch (error) {
+    hookExec = {
+      lines: [
+        'Hook execution',
+        `  ${ANSI.red}✗${ANSI.reset} ${error instanceof Error ? error.message : String(error)}`,
+      ],
+      failCount: 1,
+      warnCount: 0,
+    };
+  }
+  lines.push(...hookExec.lines);
+  lines.push('');
+
   const workspaceRoot = findWorkspaceRoot(process.cwd());
   const workspaceVersions = workspaceRoot ? collectWorkspaceVersions(workspaceRoot) : [];
   const workspaceMap = new Map(workspaceVersions.map((w) => [w.name, w]));
@@ -748,6 +895,9 @@ export async function handleSystemDoctor(
   }
   if (driftCount > 0) problems.push(`${driftCount} package(s) behind workspace`);
   if (unresolvedCount > 0) problems.push(`${unresolvedCount} unresolved`);
+  if (hookExec.failCount > 0) {
+    problems.push(`${hookExec.failCount} hook-execution problem(s)`);
+  }
   if (fleet.failCount > 0) problems.push(`${fleet.failCount} fleet check(s) failing`);
   if (aspectFailCount > 0) problems.push(`${aspectFailCount} system(s) missing a fleet aspect`);
 
@@ -760,7 +910,7 @@ export async function handleSystemDoctor(
   }
 
   // Fleet warnings don't fail the run, but they shouldn't read as a clean bill.
-  const warnTotal = fleet.warnCount + aspectWarnCount;
+  const warnTotal = fleet.warnCount + aspectWarnCount + hookExec.warnCount;
   if (warnTotal > 0) {
     lines.push(`${ANSI.yellow}OK with warnings${ANSI.reset} — ${warnTotal} warning(s); see above`);
   } else {