@celilo/cli 2.2.0 → 2.3.0

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

@@ -44,11 +44,12 @@ import {
   type JailAvailability,
   type JailModeRecord,
   type JailPolicy,
+  type JailPolicySource,
   SANDBOX_EXEC_AUTO_DEFERRED_REASON,
   autoJailDefers,
   detectJailBackend,
-  jailPolicy,
   readJailMode,
+  resolveJailPolicy,
 } from '../../hooks/jail';
 import type { ModuleManifest } from '../../manifest/schema';
 import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
@@ -59,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';
@@ -353,6 +355,12 @@ function provisionedBrowserFlavor(): string | null {
 export interface HookExecutionInput {
   availability: JailAvailability;
   policy: JailPolicy;
+  /** Which source decided `policy` (D4 of hook-jail-config-surface). */
+  source: JailPolicySource;
+  /** Raw `CELILO_HOOK_JAIL` value, when set; rendered on the source line. */
+  envValue: string | undefined;
+  /** Raw stored `hooks.jail_policy` value, when present; rendered on the disagreement line. */
+  configValue: string | undefined;
   /** What the last real module-hook run recorded, if any. */
   record: JailModeRecord | undefined;
   host: string;
@@ -361,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[];
 }
 
 /**
@@ -390,13 +404,41 @@ export function renderHookExecutionSection(input: HookExecutionInput): {
   let failCount = 0;
   let warnCount = 0;
 
+  // Which source decided the policy (D4 of hook-jail-config-surface). When
+  // env and config both hold values and disagree, name the loser too: a
+  // control whose two sources disagree and whose rendering hides one of them
+  // is the exact failure this change fixes, one level down.
+  if (input.source === 'env' && input.envValue !== undefined) {
+    lines.push(
+      `  ${ANSI.dim}policy from CELILO_HOOK_JAIL=${input.envValue} (environment override)${ANSI.reset}`,
+    );
+  } 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 (${policy}) — set hooks.jail_policy or CELILO_HOOK_JAIL to change${ANSI.reset}`,
+    );
+  }
+  if (
+    input.source === 'env' &&
+    input.configValue !== undefined &&
+    input.envValue !== input.configValue
+  ) {
+    lines.push(
+      `  ${ANSI.dim}system config holds '${input.configValue}' but CELILO_HOOK_JAIL='${input.envValue}' overrides it${ANSI.reset}`,
+    );
+  }
+
   // 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`,
+      `  ${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++;
@@ -417,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) {
@@ -456,6 +510,79 @@ export function renderHookExecutionSection(input: HookExecutionInput): {
   return { lines, failCount, warnCount };
 }
 
+/** Where `assembleHookExecutionSection` gets what the machine says. Every
+ * reader is a thunk so any of their throws (a bad stored row, a corrupt
+ * record) land in the one catch that renders this section. */
+export interface HookExecutionIO {
+  envValue: () => string | undefined;
+  configValue: () => string | undefined;
+  availability: () => JailAvailability;
+  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[];
+}
+
+/**
+ * Resolve the effective jail policy from its two sources and render the
+ * Hook execution section (hook-jail-config-surface D2/D4).
+ *
+ * The single catch is the section's one error path: a typo'd env value or a
+ * bad stored row renders as a failing check rather than crashing the doctor,
+ * because the same throw is about to fail every hook invocation too.
+ */
+export function assembleHookExecutionSection(io: HookExecutionIO): {
+  lines: string[];
+  failCount: number;
+  warnCount: number;
+} {
+  try {
+    const envValue = io.envValue();
+    const configValue = io.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,
+      source: resolved.source,
+      envValue,
+      configValue,
+      record: io.record(),
+      host: io.host(),
+      monitored: io.monitored(),
+      exemptions: io.exemptions(),
+    });
+  } catch (error) {
+    return {
+      lines: [
+        'Hook execution',
+        `  ${ANSI.red}✗${ANSI.reset} ${error instanceof Error ? error.message : String(error)}`,
+      ],
+      failCount: 1,
+      warnCount: 0,
+    };
+  }
+}
+
+/**
+ * The stored `hooks.jail_policy` value, or undefined when there is no row or
+ * no celilo DB to ask (a dev box). Same row-read pattern as
+ * `ipam/auto-allocator.ts`; the drizzle table is `systemConfig` in
+ * `db/schema.ts`.
+ */
+function readStoredJailPolicy(): string | undefined {
+  if (!existsSync(getDbPath())) return undefined;
+  const row = getDb()
+    .$client.prepare('SELECT value FROM system_config WHERE key = ?')
+    .get('hooks.jail_policy') as { value: string } | undefined;
+  return row?.value;
+}
+
 /**
  * mtime (ms) of the installed dispatcher code (`@celilo/event-bus`
  * package.json). The fleet dispatcher check compares this against the
@@ -736,30 +863,20 @@ 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
+  // Hook execution mode (hook-process-boundary task 4.6; sources per D4 of
+  // hook-jail-config-surface). The policy read throws on a typo'd
+  // CELILO_HOOK_JAIL or a bad stored row — 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,
-    };
-  }
+  const hookExec = assembleHookExecutionSection({
+    envValue: () => process.env.CELILO_HOOK_JAIL,
+    configValue: () => readStoredJailPolicy(),
+    availability: () => detectJailBackend(),
+    record: () => readJailMode(),
+    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

@@ -12,6 +12,7 @@ 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 { resetTestDbPath } from '../../test-utils/db-path';
 import { handleSystemInit } from './system-init';
 
 interface CapturedStream {
@@ -35,19 +36,21 @@ function captureStderr(): CapturedStream {
 
 describe('celilo system init deprecation banner', () => {
   let tmpDir: string;
-  let savedDbPath: string | undefined;
   let savedSuppress: string | undefined;
 
   beforeEach(() => {
     tmpDir = mkdtempSync(join(tmpdir(), 'celilo-deprecation-test-'));
-    savedDbPath = process.env.CELILO_DB_PATH;
     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(() => {
-    process.env.CELILO_DB_PATH = savedDbPath;
+    // Never restore the previous value: it may be another suite's temp
+    // database (or, worse, unset — which sends the next var-less reader to
+    // the operator's real celilo.db). The scratch path is the neutral state
+    // (celilo#1315).
+    resetTestDbPath();
     process.env.CELILO_SUPPRESS_DEPRECATION = savedSuppress;
     rmSync(tmpDir, { recursive: true, force: true });
   });

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

@@ -4,6 +4,7 @@ import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb, findMigrationsFolder } from '../../db/client';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleSystemMigrate } from './system-migrate';
 
 /**
@@ -32,7 +33,7 @@ describe('handleSystemMigrate', () => {
   });
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

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';
@@ -576,6 +577,7 @@ export async function handleSystemUpdate(
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    jailExemptions: { exemptions: collectJailExemptions(db) },
     health: { results: healthResults },
     backups: {
       modules: upgradableModules.map((m) => ({
@@ -613,6 +615,9 @@ 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: [] },
   };

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();

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([]);
+  });
+});