@celilo/cli 2.2.1 → 3.0.0

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import type { JailModeRecord } from '../../hooks/jail';
+import { type JailModeRecord, resolveJailPolicy } from '../../hooks/jail';
 import {
   type HookExecutionInput,
   assembleHookExecutionSection,
@@ -62,12 +62,13 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
     renderHookExecutionSection({
       availability: { backend: 'bubblewrap' },
       policy: 'auto',
-      source: 'default',
-      envValue: undefined,
+      source: 'env',
+      envValue: 'auto',
       configValue: undefined,
       record: jailedRecord,
       host: HOST,
       monitored: true,
+      exemptions: [],
       ...over,
     });
 
@@ -96,10 +97,31 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
     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('an off policy warns, and the reason claims no source of its own', () => {
+    // This test used to be named "CELILO_HOOK_JAIL=off is reported as the
+    // operator's own act" and asserted that string. It stopped being true when
+    // ce-rez7 made `off` the DEFAULT: on a host where nobody set anything, the
+    // doctor named a variable that was unset and an act nobody performed. The
+    // source belongs on the source line, which is rendered separately.
+    const fromDefault = render({
+      policy: 'off',
+      source: 'default',
+      envValue: undefined,
+      record: undefined,
+    });
+    expect(text(fromDefault)).toContain('hooks run unjailed');
+    expect(text(fromDefault)).toContain('policy default (off)');
+    expect(text(fromDefault)).not.toContain('CELILO_HOOK_JAIL=off');
+    expect(fromDefault.warnCount).toBe(1);
+
+    const fromEnv = render({
+      policy: 'off',
+      source: 'env',
+      envValue: 'off',
+      record: undefined,
+    });
+    expect(text(fromEnv)).toContain('policy from CELILO_HOOK_JAIL=off (environment override)');
+    expect(fromEnv.warnCount).toBe(1);
   });
 
   test('auto deferral on sandbox-exec reads as unjailed, not jailed (ce-29z)', () => {
@@ -119,7 +141,7 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
       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(text(r)).toContain("the hook jail policy is 'required' and no jail is available");
     expect(r.failCount).toBe(1);
   });
 
@@ -180,9 +202,21 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
   });
 
   test('the source line names the default and how to change it (D4)', () => {
-    const r = render({ policy: 'auto', source: 'default', record: undefined });
+    // Ask the resolver what the default IS rather than naming it. The literal
+    // that stood here said `auto`, and it kept passing after ce-rez7 flipped
+    // the default to `off`, because it rendered a { policy, source } pair the
+    // resolver can no longer produce. A correct assertion about a state that
+    // never arrives.
+    const fallback = resolveJailPolicy(undefined, undefined, undefined);
+    const r = render({
+      policy: fallback.policy,
+      source: fallback.source,
+      envValue: undefined,
+      record: undefined,
+    });
+    expect(fallback.source).toBe('default');
     expect(text(r)).toContain(
-      'policy default (auto) — set hooks.jail_policy or CELILO_HOOK_JAIL to change',
+      `policy default (${fallback.policy}) — set hooks.jail_policy or CELILO_HOOK_JAIL to change`,
     );
   });
 
@@ -218,10 +252,42 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
       record: () => undefined,
       host: () => HOST,
       monitored: () => true,
+      exemptions: () => [],
     });
     expect(r.lines[0]).toBe('Hook execution');
     expect(r.lines[1]).toContain("hooks.jail_policy='alwayssafe' is not a hook jail policy");
     expect(r.failCount).toBe(1);
     expect(r.warnCount).toBe(0);
   });
+
+  test('an exemption is counted and named (per-module-jail-policy task 3.2)', () => {
+    const r = render({
+      exemptions: [
+        { moduleId: 'caddy', policy: 'off', systemPolicy: 'auto' },
+        { moduleId: 'vault', policy: 'auto', systemPolicy: 'auto' },
+      ],
+    });
+    expect(text(r)).toContain("2 modules run under a weaker jail policy than the system's");
+    expect(text(r)).toContain('caddy (off)');
+    expect(text(r)).toContain('vault (auto)');
+    expect(r.warnCount).toBe(1);
+  });
+
+  test('one exemption reads as singular', () => {
+    const r = render({
+      exemptions: [{ moduleId: 'caddy', policy: 'off', systemPolicy: 'auto' }],
+    });
+    expect(text(r)).toContain('1 module runs under a weaker jail policy');
+    expect(text(r)).not.toContain('modules run');
+  });
+
+  test('no exemptions render no exemption line (per-module-jail-policy task 3.4)', () => {
+    // The negative half: a surface that reports an exemption nobody set is
+    // as bad as one that hides a real one. With no rows the section must be
+    // word-for-word what it was before this slice.
+    const r = render({});
+    expect(text(r)).not.toContain('weaker jail policy');
+    expect(text(r)).not.toContain('exempt');
+    expect(r.warnCount).toBe(0);
+  });
 });

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

@@ -60,6 +60,7 @@ import {
   checkSubscribers,
   runFleetChecks,
 } from '../../services/fleet-checks';
+import { type JailExemption, collectJailExemptions } from '../../services/jail-exemptions';
 import { resyncAllSubscriptions } from '../../services/module-subscriptions';
 import { checkAllPrerequisites, failingPrerequisites } from '../../system/prereqs';
 import type { CommandResult } from '../types';
@@ -368,6 +369,12 @@ export interface HookExecutionInput {
    * ask (a dev box), which also suppresses the add-the-monitor hint.
    */
   monitored: boolean | null;
+  /**
+   * Modules running under a recorded policy weaker than the system's
+   * (per-module-jail-policy task 3.2), from the shared collector. Empty is
+   * the normal state and renders nothing.
+   */
+  exemptions: readonly JailExemption[];
 }
 
 /**
@@ -408,8 +415,11 @@ export function renderHookExecutionSection(input: HookExecutionInput): {
   } else if (input.source === 'config') {
     lines.push(`  ${ANSI.dim}policy from system config (hooks.jail_policy)${ANSI.reset}`);
   } else {
+    // Read the default off `policy` rather than naming it. The literal that
+    // stood here said `auto` and stayed saying it after ce-rez7 flipped the
+    // default to `off`, so the doctor named the one value not in play.
     lines.push(
-      `  ${ANSI.dim}policy default (auto) — set hooks.jail_policy or CELILO_HOOK_JAIL to change${ANSI.reset}`,
+      `  ${ANSI.dim}policy default (${policy}) — set hooks.jail_policy or CELILO_HOOK_JAIL to change${ANSI.reset}`,
     );
   }
   if (
@@ -428,7 +438,7 @@ export function renderHookExecutionSection(input: HookExecutionInput): {
   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`,
+      `  ${ANSI.red}✗${ANSI.reset} the hook jail policy is '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++;
@@ -449,6 +459,18 @@ export function renderHookExecutionSection(input: HookExecutionInput): {
     lines.push(`  ${ANSI.green}✔${ANSI.reset} hooks run jailed (${availability.backend})`);
   }
 
+  // Per-module exemptions (per-module-jail-policy task 3.2). Loud and
+  // countable is the whole design: the count AND the names, every time, and
+  // nothing at all when there are none.
+  if (input.exemptions.length > 0) {
+    const n = input.exemptions.length;
+    const named = input.exemptions.map((e) => `${e.moduleId} (${e.policy})`).join(', ');
+    lines.push(
+      `  ${ANSI.yellow}⚠${ANSI.reset} ${n} module${n === 1 ? '' : 's'} run${n === 1 ? 's' : ''} under a weaker jail policy than the system's: ${named}`,
+    );
+    warnCount++;
+  }
+
   const regressed =
     record && record.host === host && record.mode === 'unjailed' && record.lastJailed;
   if (regressed && record.lastJailed) {
@@ -498,6 +520,8 @@ export interface HookExecutionIO {
   record: () => JailModeRecord | undefined;
   host: () => string;
   monitored: () => boolean | null;
+  /** Modules exempted from the system's jail policy (per-module-jail-policy task 3.2). */
+  exemptions: () => JailExemption[];
 }
 
 /**
@@ -516,7 +540,12 @@ export function assembleHookExecutionSection(io: HookExecutionIO): {
   try {
     const envValue = io.envValue();
     const configValue = io.configValue();
-    const resolved = resolveJailPolicy(envValue, configValue);
+    // The module step of the four-step precedence stays out of the headline
+    // resolution — the headline is the policy the EXECUTOR would use for a
+    // module with no row of its own. Per-module rows are surfaced separately
+    // as exemptions (per-module-jail-policy task 3.2), which is the shape the
+    // operator acts on.
+    const resolved = resolveJailPolicy(envValue, undefined, configValue);
     return renderHookExecutionSection({
       availability: io.availability(),
       policy: resolved.policy,
@@ -526,6 +555,7 @@ export function assembleHookExecutionSection(io: HookExecutionIO): {
       record: io.record(),
       host: io.host(),
       monitored: io.monitored(),
+      exemptions: io.exemptions(),
     });
   } catch (error) {
     return {
@@ -845,6 +875,7 @@ export async function handleSystemDoctor(
     host: () => hostname(),
     monitored: () =>
       existsSync(getDbPath()) ? findMonitorByTarget(getDb(), HOOK_JAIL_CHECK) !== undefined : null,
+    exemptions: () => (existsSync(getDbPath()) ? collectJailExemptions(getDb()) : []),
   });
   lines.push(...hookExec.lines);
   lines.push('');

package/src/cli/commands/system-init-deprecation.test.ts

@@ -42,7 +42,7 @@ describe('celilo system init deprecation banner', () => {
     tmpDir = mkdtempSync(join(tmpdir(), 'celilo-deprecation-test-'));
     savedSuppress = process.env.CELILO_SUPPRESS_DEPRECATION;
     process.env.CELILO_DB_PATH = join(tmpDir, 'init.db');
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    delete process.env.CELILO_SUPPRESS_DEPRECATION;
   });
 
   afterEach(() => {

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

@@ -34,6 +34,7 @@ import { makeJournalReader, readAppliedMigrations } from '../../services/audit/s
 import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
 import { BACKUP_SCHEDULE_CONFIG_KEY } from '../../services/backup-schedule';
 import { runAllHealthChecks, runModuleHealthCheck } from '../../services/health-runner';
+import { collectJailExemptions } from '../../services/jail-exemptions';
 import { configOverride, parseStoredConfigValue } from '../../services/module-config';
 import { deployModule } from '../../services/module-deploy';
 import { buildModuleGraph } from '../../services/update/dep-graph';
@@ -285,7 +286,11 @@ async function buildSnapshots(
  * - `health` calls `runModuleHealthCheck`.
  * - `snapshotCeliloDb` calls `createSystemStateBackup`.
  */
-function buildOps(registry: RegistryClient, wasDeployed: Set<string>): OrchestratorOps {
+function buildOps(
+  registry: RegistryClient,
+  wasDeployed: Set<string>,
+  quiet: boolean,
+): OrchestratorOps {
   return {
     backup: async (moduleId, _updateId) => {
       // IMPORTED modules don't have running state to back up; skip
@@ -361,9 +366,10 @@ function buildOps(registry: RegistryClient, wasDeployed: Set<string>): Orchestra
         return { status: 'no-checks', detail: 'not deployed; health check skipped' };
       }
       // We can call the existing health-runner directly today — that's
-      // already a clean service.
+      // already a clean service. quiet keeps the check's gauge and plain
+      // log lines off stdout when the caller asked for JSON (celilo#1362).
       const db = getDb();
-      const r = await runModuleHealthCheck(id, db);
+      const r = await runModuleHealthCheck(id, db, { quiet });
       return { status: r.status, detail: r.error };
     },
     snapshotCeliloDb: async (_updateId) => {
@@ -493,7 +499,7 @@ export async function handleSystemUpdate(
   // Build audit deps. (Mostly mirrors system-audit.ts; could be refactored
   // into a shared helper in Phase 5.)
   const migrationsFolder = findMigrationsFolderSafe();
-  const healthResults = await runAllHealthChecks(db);
+  const healthResults = await runAllHealthChecks(db, { quiet: json });
 
   // Module integrity, shallow. Local and milliseconds; the host plane is one
   // SSH per system and belongs to `module verify --deep`.
@@ -576,6 +582,7 @@ export async function handleSystemUpdate(
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    jailExemptions: { exemptions: collectJailExemptions(db) },
     health: { results: healthResults },
     backups: {
       modules: upgradableModules.map((m) => ({
@@ -613,8 +620,11 @@ export async function handleSystemUpdate(
     // flow's partial audit does no probing. `system audit` and the scheduled
     // monitor own this check.
     publicDns: { records: [], probe: unusedPublicDnsProbe },
+    // Disk probing is one SSH per system; the update flow's partial audit
+    // does no probing. `system audit` and the monitor sweep own this check.
+    diskSpace: { results: [] },
     transportReads: { statuses: [], now: new Date(), staleAfterMs: 30 * 60_000 },
-    trustedSources: { firewalls: [] },
+    trustedSources: { firewalls: [], unreachableFirewalls: [] },
   };
 
   if (dryRun) {
@@ -682,7 +692,7 @@ export async function handleSystemUpdate(
     }
   }
 
-  const ops = buildOps(registry, wasDeployed);
+  const ops = buildOps(registry, wasDeployed, json);
 
   const result = await runSystemUpdate({
     audit: auditDeps,

package/src/cli/completion.ts

@@ -171,6 +171,7 @@ export async function getCompletions(words: string[], current: number): Promise<
   if (command === 'module' && currentIndex === 1) {
     const subcommands = [
       'check',
+      'changeset',
       'import',
       'list',
       'publish',
@@ -187,7 +188,6 @@ export async function getCompletions(words: string[], current: number): Promise<
       'build',
       'generate',
       'deploy',
-      'destroy',
       'health',
       'logs',
       'journal',
@@ -201,6 +201,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'validate',
       'pause',
       'unpause',
+      'jail',
     ];
     return filterSuggestions(subcommands, args[1] || '');
   }
@@ -470,7 +471,6 @@ export async function getCompletions(words: string[], current: number): Promise<
     const moduleCommands = [
       'generate',
       'deploy',
-      'destroy',
       'logs',
       'journal',
       'remove',
@@ -483,6 +483,7 @@ export async function getCompletions(words: string[], current: number): Promise<
       'audit', // deprecation alias for `verify`
       'pause',
       'unpause',
+      'jail',
     ];
     if (moduleCommands.includes(args[1] || '')) {
       const db = getDb();
@@ -492,6 +493,11 @@ export async function getCompletions(words: string[], current: number): Promise<
     }
   }
 
+  // Module jail <module-id> - complete with policy values
+  if (command === 'module' && args[1] === 'jail' && currentIndex === 3) {
+    return filterSuggestions(['auto', 'off', 'required'], args[3] || '');
+  }
+
   // Module run-hook <module-id> - complete with hook names from manifest
   if (command === 'module' && args[1] === 'run-hook' && currentIndex === 3) {
     const db = getDb();
@@ -509,7 +515,16 @@ export async function getCompletions(words: string[], current: number): Promise<
 
   // Subscribers subcommands
   if (command === 'subscribers' && currentIndex === 1) {
-    const subcommands = ['list', 'add', 'remove', 'test', 'serve', 'status'];
+    const subcommands = [
+      'list',
+      'add',
+      'remove',
+      'test',
+      'serve',
+      'status',
+      'install-daemon',
+      'uninstall-daemon',
+    ];
     return filterSuggestions(subcommands, args[1] || '');
   }
 

package/src/cli/flag-surface-gate.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Flag-surface gate (celilo#1327) and subcommand-surface gate (celilo#1337).
+ *
+ * A CLI flag lives in two places: the handler reads it off `flags.X`, and
+ * packages/core/src/command-registry.ts declares it so the parser accepts it.
+ * When only the first happens, the flag is fully implemented — often unit
+ * tested, because the test drives the handler directly and never consults
+ * validateFlags — and still rejected at the terminal with
+ * "Command 'X' does not accept any flags".
+ *
+ * Instances of exactly that shape: #1308 (doctor remediation arrows),
+ * #1316 (module deploy --keep), #1325 (system config set --force), and three
+ * handler reads found the first time this gate ran (module check --no-build
+ * and --strict, module changeset --bump — their subcommands were missing from
+ * the registry entirely, so validation was skipped, not failed).
+ *
+ * A subcommand drifts the opposite way: the registry declares it, dispatch
+ * runs it, and the hand-written help block never mentions it, so a user
+ * reading `celilo <command> --help` cannot learn the subcommand exists.
+ * #1337 measured ten such subcommands under `celilo module` (upgrade, audit,
+ * validate, changeset, status, where, operations, logs, journal, backup), and
+ * the first run of this scan found four more elsewhere (events
+ * list-unanswered, system migrate, ipam show, backup pull).
+ *
+ * All scans are deliberately coarse: a flag name must be declared SOMEWHERE
+ * in the registry, and a subcommand name must merely APPEAR SOMEWHERE in its
+ * command's help block — word-boundary match, not a parsed Subcommands:
+ * section, because help blocks vary in shape. A per-subcommand check would be
+ * tighter, but every known instance was declared nowhere / printed nowhere,
+ * and a coarse gate that runs beats a precise one nobody finishes.
+ *
+ * Reach floors: each scan asserts it walked a real surface (minimum distinct
+ * flag names / files / help blocks / commands). A scan that resolves no files
+ * exits 0 and proves nothing, so the gate fails loudly instead.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { COMMANDS } from '@celilo/core';
+
+const commandsDir = join(import.meta.dir, 'commands');
+const indexSource = readFileSync(join(import.meta.dir, 'index.ts'), 'utf8');
+
+/** Every flag name declared at any depth of the command registry. */
+function collectDeclaredFlags(): Set<string> {
+  const declared = new Set<string>();
+  function walk(defs: typeof COMMANDS): void {
+    for (const def of defs) {
+      for (const flag of def.flags ?? []) declared.add(flag.name);
+      if (def.subcommands) walk(def.subcommands);
+    }
+  }
+  walk(COMMANDS);
+  return declared;
+}
+
+const declaredFlags = collectDeclaredFlags();
+
+/**
+ * Flags accepted without a registry entry, each with the reason:
+ * - help/h: universal, added by validateFlags itself (parser.ts).
+ * - remote: top-level transport flag, intercepted at the top of runCli by
+ *   resolveRemote (packages/core/src/remote-client.ts) before any dispatch.
+ */
+const flagsOutsideTheRegistry = new Set(['help', 'h', 'remote']);
+
+interface HandlerScan {
+  byName: Map<string, string[]>;
+  fileCount: number;
+  totalReads: number;
+}
+
+/**
+ * Every flag literal a command handler reads via hasFlag(flags, 'x') or
+ * getFlag(flags, 'x'). Reads that pass a variable instead of a literal are
+ * invisible to this scan — accepted coarseness, see the header.
+ */
+function scanHandlerFlagReads(): HandlerScan {
+  const byName = new Map<string, string[]>();
+  const files = readdirSync(commandsDir).filter(
+    (f) => f.endsWith('.ts') && !f.endsWith('.test.ts'),
+  );
+  let totalReads = 0;
+
+  for (const file of files) {
+    const source = readFileSync(join(commandsDir, file), 'utf8');
+    const reads = source.matchAll(/(?:hasFlag|getFlag)\(\s*flags\s*,\s*'([^']+)'/g);
+    for (const read of reads) {
+      totalReads++;
+      const flagName = read[1];
+      if (!flagName) continue;
+      const holders = byName.get(flagName) ?? [];
+      holders.push(file);
+      byName.set(flagName, holders);
+    }
+  }
+
+  return { byName, fileCount: files.length, totalReads };
+}
+
+/**
+ * Source of each displayXxxHelp function in index.ts (the help-text blocks).
+ * Each block is bounded by the NEXT top-level declaration, not by the next
+ * display function and not by end-of-source. The original end-of-source bound
+ * let the last block swallow runCli's body, so --principal, --get-completions
+ * and --version were read out of dispatch code and reported as advertised.
+ */
+function extractHelpBlocks(source: string): string[] {
+  const fns = [...source.matchAll(/function display\w*Help\(\)/g)];
+  const topLevelDecl = /^(?:export )?(?:async )?function \w+|^export const \w+/gm;
+  const blocks: string[] = [];
+  for (const fn of fns) {
+    if (fn.index === undefined) continue;
+    const start = fn.index + fn[0].length;
+    topLevelDecl.lastIndex = start;
+    const next = topLevelDecl.exec(source);
+    const end = next?.index ?? source.length;
+    blocks.push(source.slice(start, end));
+  }
+  return blocks;
+}
+
+/** Distinct --flag names advertised across all help blocks. */
+function scanAdvertisedFlags(): { byName: Set<string>; blockCount: number } {
+  const byName = new Set<string>();
+  let blockCount = 0;
+
+  for (const block of extractHelpBlocks(indexSource)) {
+    // External-tool example lines (ansible-vault, ansible-playbook) carry the
+    // other tool's flags. Not celilo's surface. The flag often sits on the
+    // continuation line, so drop --vault-password-file by name as well as the
+    // ansible- command lines. // @psbanka - 2026-09
+    const celiloLines = block
+      .split('\n')
+      .filter((line) => !line.includes('ansible-'))
+      .filter((line) => !line.includes('vault-password-file'));
+    blockCount++;
+    for (const line of celiloLines) {
+      for (const match of line.matchAll(/--([a-zA-Z0-9][a-zA-Z0-9-]*)/g)) {
+        const flagName = match[1];
+        if (flagName) byName.add(flagName);
+      }
+    }
+  }
+
+  return { byName, blockCount };
+}
+
+/** `module` -> `Module`, `escalation-policy` -> `EscalationPolicy`. */
+function pascalCase(name: string): string {
+  return name.replace(/(^|-)([a-z])/g, (_match, prefix, char) => prefix + char.toUpperCase());
+}
+
+/**
+ * Help blocks keyed by the display function's name suffix: displayModuleHelp
+ * -> "Module". A command with subcommands but no dedicated display function
+ * (api, alerts, route, ...) is simply absent from the map and skipped by the
+ * subcommand scan — it has no help block to drift from.
+ */
+function extractNamedHelpBlocks(): Map<string, string> {
+  const byName = new Map<string, string>();
+  for (const match of indexSource.matchAll(/function display(\w*)Help\(\)/g)) {
+    if (match.index === undefined) continue;
+    const start = match.index + match[0].length;
+    const topLevelDecl = /^(?:export )?(?:async )?function \w+|^export const \w+/gm;
+    topLevelDecl.lastIndex = start;
+    const next = topLevelDecl.exec(indexSource);
+    byName.set(match[1], indexSource.slice(start, next?.index ?? indexSource.length));
+  }
+  return byName;
+}
+
+/**
+ * Registry subcommands that appear nowhere in their command's help block.
+ * Commands without a dedicated help block are skipped (nothing to diff).
+ */
+function scanSubcommandDrift(): {
+  missing: string[];
+  commandCount: number;
+  subcommandCount: number;
+} {
+  const helpBlocks = extractNamedHelpBlocks();
+  const missing: string[] = [];
+  let commandCount = 0;
+  let subcommandCount = 0;
+
+  for (const command of COMMANDS) {
+    if (!command.subcommands?.length) continue;
+    const name = pascalCase(command.name);
+    const block = helpBlocks.get(name);
+    if (block === undefined) continue;
+    commandCount++;
+    subcommandCount += command.subcommands.length;
+    for (const sub of command.subcommands) {
+      if (!new RegExp(`\\b${sub.name}\\b`).test(block)) {
+        missing.push(`celilo ${command.name} ${sub.name}`);
+      }
+    }
+  }
+
+  return { missing, commandCount, subcommandCount };
+}
+
+describe('subcommand-surface gate: help text vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanSubcommandDrift();
+    if (scan.commandCount < 14 || scan.subcommandCount < 60) {
+      throw new Error(
+        `Subcommand scan walked too little to prove anything: ${scan.commandCount} commands with help blocks, ${scan.subcommandCount} registry subcommands. Expected >= 14 commands, >= 60 subcommands. If the help-block surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.commandCount).toBeGreaterThanOrEqual(14);
+  });
+
+  it("every registry subcommand appears in its command's help block", () => {
+    const scan = scanSubcommandDrift();
+
+    if (scan.missing.length > 0) {
+      throw new Error(
+        `${scan.missing.length} registry subcommand(s) appear nowhere in their command's help text (scanned ${scan.commandCount} commands, ${scan.subcommandCount} subcommands):\n${scan.missing.map((entry) => `  ${entry}`).join('\n')}\nFix: add the subcommand to its displayXxxHelp block in apps/celilo/src/cli/index.ts, or remove it from packages/core/src/command-registry.ts if it is no longer dispatched.`,
+      );
+    }
+    expect(scan.missing).toEqual([]);
+  });
+});
+
+describe('flag-surface gate: handler reads vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanHandlerFlagReads();
+    if (scan.fileCount < 10 || scan.byName.size < 30 || scan.totalReads < 60) {
+      throw new Error(
+        `Handler scan walked too little to prove anything: ${scan.fileCount} files, ${scan.byName.size} distinct flags, ${scan.totalReads} reads. Expected >= 10 files, >= 30 distinct, >= 60 reads. If the handler surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.byName.size).toBeGreaterThanOrEqual(30);
+  });
+
+  it('every flag a handler reads is declared in the command registry', () => {
+    const scan = scanHandlerFlagReads();
+    const undeclared = [...scan.byName.entries()].filter(([name]) => !declaredFlags.has(name));
+
+    if (undeclared.length > 0) {
+      const detail = undeclared
+        .map(([name, files]) => `  --${name}  read by: ${[...new Set(files)].join(', ')}`)
+        .join('\n');
+      throw new Error(
+        `${undeclared.length} handler-read flag(s) are declared nowhere in COMMANDS (scanned ${scan.fileCount} handler files, ${scan.totalReads} reads, ${scan.byName.size} distinct flags):\n${detail}\nFix: declare each flag on its command in packages/core/src/command-registry.ts.`,
+      );
+    }
+    expect(undeclared).toEqual([]);
+  });
+});
+
+describe('flag-surface gate: help text vs command registry', () => {
+  it('scanned a real surface (reach floor)', () => {
+    const scan = scanAdvertisedFlags();
+    if (scan.blockCount < 15 || scan.byName.size < 60) {
+      throw new Error(
+        `Help-text scan walked too little to prove anything: ${scan.blockCount} help blocks, ${scan.byName.size} distinct advertised flags. Expected >= 15 blocks, >= 60 distinct. If the help surface genuinely shrank, update the floors here consciously.`,
+      );
+    }
+    expect(scan.byName.size).toBeGreaterThanOrEqual(60);
+  });
+
+  it('every flag advertised in help text is declared in the command registry', () => {
+    const scan = scanAdvertisedFlags();
+    const undeclared = [...scan.byName].filter(
+      (name) => !declaredFlags.has(name) && !flagsOutsideTheRegistry.has(name),
+    );
+
+    if (undeclared.length > 0) {
+      throw new Error(
+        `${undeclared.length} flag(s) advertised in index.ts help text are declared nowhere in COMMANDS (scanned ${scan.blockCount} help blocks, ${scan.byName.size} distinct advertised flags): ${undeclared.map((n) => `--${n}`).join(', ')}\nFix: declare each flag on its command in packages/core/src/command-registry.ts.`,
+      );
+    }
+    expect(undeclared).toEqual([]);
+  });
+});