@celilo/cli 2.2.1 → 3.0.0

package/src/cli/commands/subscribers-install-daemon.ts

@@ -0,0 +1,107 @@
+/**
+ * `celilo subscribers install-daemon` — write a systemd unit (Linux) or
+ * launchd plist (macOS) that runs the build-bus webhook receiver
+ * (`celilo subscribers serve`) under supervision. Mirrors
+ * `celilo events install-daemon` for the dispatcher: default is a
+ * per-user unit; `--system` writes the system-scope unit that survives
+ * logout/reboot — the management-plane shape. Writes the file but
+ * doesn't touch supervisor state — the operator (or the celilo-mgmt
+ * Ansible role) runs the enable/bootstrap steps themselves.
+ *
+ * The rendered unit runs `subscribers serve --no-dispatch` by default:
+ * the standing dispatcher (celilo-events.service) owns dispatch on a
+ * management box, and a second dispatcher polling the same bus is the
+ * celilo#580/#610 failure. Pass --dispatch for a combined unit on a box
+ * that has no events daemon.
+ *
+ * celilo#1304: nothing installed the receiver anywhere, so celilo-mgr's
+ * on_upstream_publish self-update could never fire. This command is the
+ * missing installer.
+ */
+
+import {
+  installReceiverDaemon,
+  planReceiverInstall,
+  uninstallReceiverDaemon,
+} from '../../services/build-bus/receiver-daemon';
+import type { CommandResult } from '../types';
+import { resolveServeSecret } from './subscribers-serve';
+
+function shortenPath(p: string): string {
+  return p.startsWith(process.env.HOME ?? '\0') ? p.replace(process.env.HOME ?? '', '~') : p;
+}
+
+function daemonScopeFrom(flags: Record<string, string | boolean>): 'user' | 'system' {
+  return flags.system === true ? 'system' : 'user';
+}
+
+export async function handleSubscribersInstallDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+  env: Record<string, string | undefined> = process.env,
+): Promise<CommandResult> {
+  try {
+    const options = {
+      celiloPath: typeof flags['celilo-path'] === 'string' ? flags['celilo-path'] : undefined,
+      port: flags.port ? Number(flags.port) : undefined,
+      // Same resolution as `serve`: the flag wins, CELILO_BUS_SECRET is
+      // the documented fallback (the doctor remediation names it), and
+      // null means the renderer refuses rather than invent a secret.
+      secret: resolveServeSecret(flags, env) ?? undefined,
+      scope: daemonScopeFrom(flags),
+      dispatch: flags.dispatch === true,
+    };
+    // --print: render-only, raw unit content on stdout. The celilo-mgmt
+    // Ansible role captures this and does the root-owned write itself
+    // (the deb wrapper runs celilo as the unprivileged celilo user, so
+    // a direct --system write would EACCES on /etc/systemd/system).
+    if (flags.print) {
+      const plan = planReceiverInstall(options);
+      return { success: true, message: plan.unitContent, rawOutput: true, data: plan };
+    }
+    const result = installReceiverDaemon(options);
+    const lines = [
+      `Wrote ${result.platform} ${result.scope} unit: ${shortenPath(result.unitPath)}`,
+      `  celilo:    ${shortenPath(result.celiloPath)}`,
+      `  port:      ${result.port}`,
+      `  dispatch:  ${result.dispatch ? 'combined (receiver + hooks)' : 'receiver-only (--no-dispatch)'}`,
+      ...(result.runAsUser ? [`  runs as:   ${result.runAsUser}`] : []),
+      '',
+      'The unit embeds the shared secret the publisher must sign webhooks with —',
+      "register this host in the publisher's build-bus-subscribers.json with the",
+      'same value (`celilo subscribers add <this-host-url> --secret <same secret>`).',
+      '',
+      'Next steps (run these yourself — install does not touch supervisor state):',
+      ...result.nextSteps.map((s) => `  ${s}`),
+    ];
+    return { success: true, message: lines.join('\n'), data: result };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function handleSubscribersUninstallDaemon(
+  _args: string[],
+  flags: Record<string, string | boolean>,
+): Promise<CommandResult> {
+  try {
+    const result = uninstallReceiverDaemon({ scope: daemonScopeFrom(flags) });
+    const lines = [
+      result.removed
+        ? `Removed unit: ${shortenPath(result.unitPath)}`
+        : `No unit file at ${shortenPath(result.unitPath)} — nothing to remove.`,
+      '',
+      'Next steps:',
+      ...result.nextSteps.map((s) => `  ${s}`),
+    ];
+    return { success: true, message: lines.join('\n'), data: result };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/cli/commands/subscribers-serve.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test';
+import { resolveServeSecret } from './subscribers-serve';
+
+describe('resolveServeSecret', () => {
+  it('prefers the --secret flag over the environment', () => {
+    expect(resolveServeSecret({ secret: 'flag-secret' }, { CELILO_BUS_SECRET: 'env-secret' })).toBe(
+      'flag-secret',
+    );
+  });
+
+  it('falls back to CELILO_BUS_SECRET when the flag is absent', () => {
+    expect(resolveServeSecret({}, { CELILO_BUS_SECRET: 'env-secret' })).toBe('env-secret');
+  });
+
+  it('ignores an empty env value', () => {
+    expect(resolveServeSecret({}, { CELILO_BUS_SECRET: '' })).toBeNull();
+  });
+
+  it('returns null when neither source has a secret', () => {
+    expect(resolveServeSecret({}, {})).toBeNull();
+  });
+});

package/src/cli/commands/subscribers-serve.ts

@@ -16,6 +16,24 @@ import { startHookDispatcher } from '../../services/build-bus/hook-dispatcher';
 import { startReceiverServer } from '../../services/build-bus/receiver-server';
 import type { CommandResult } from '../types';
 
+/**
+ * Resolve the receiver's shared HMAC secret. The `--secret` flag wins;
+ * otherwise `CELILO_BUS_SECRET` from the environment — which is what
+ * the supervisor unit (celilo-build-bus-receiver.service / the launchd
+ * plist) sets, and what the doctor's build-bus-publishing remediation
+ * has always told operators to export. Returns null when neither has a
+ * usable value; the caller turns that into the flag-required error.
+ */
+export function resolveServeSecret(
+  flags: Record<string, string | boolean>,
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  if (typeof flags.secret === 'string' && flags.secret) return flags.secret;
+  const fromEnv = env.CELILO_BUS_SECRET;
+  if (typeof fromEnv === 'string' && fromEnv) return fromEnv;
+  return null;
+}
+
 export async function handleSubscribersServe(
   _args: string[],
   flags: Record<string, string | boolean>,
@@ -27,11 +45,11 @@ export async function handleSubscribersServe(
       error: `Invalid --port value: ${flags.port}. Must be 1–65535.`,
     };
   }
-  const secret = flags.secret;
-  if (typeof secret !== 'string' || !secret) {
+  const secret = resolveServeSecret(flags);
+  if (!secret) {
     return {
       success: false,
-      error: '--secret <shared-hmac-secret> is required.',
+      error: '--secret <shared-hmac-secret> is required (or export CELILO_BUS_SECRET).',
     };
   }
 
@@ -47,7 +65,7 @@ export async function handleSubscribersServe(
     secret,
     onEvent: dispatcher
       ? async (envelope) => {
-          // handleEvent returns HookRunResult[]; the receiver's
+          // handleEvent returns UpstreamHookResult[]; the receiver's
           // onEvent contract is void | Promise<void>. Discard the
           // array — the dispatcher logs its own outcomes.
           await dispatcher.handleEvent(envelope.event);

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

@@ -45,7 +45,6 @@ import {
   type LatestCliVersionFetcher,
   fetchLatestCliVersion,
 } from '../../services/audit/cli-version';
-import type { MachineReachableResult } from '../../services/audit/machines-reachable';
 import type { ModuleVersionFetcher } from '../../services/audit/module-versions';
 import {
   loadPublicDnsEvidence,
@@ -57,8 +56,10 @@ import type { ServiceCredentialsResult } from '../../services/audit/services-cre
 import type { ServiceReachableResult } from '../../services/audit/services-reachable';
 import type { TerraformPlanRunner } from '../../services/audit/terraform-plan';
 import { getServiceCredentials, listContainerServices } from '../../services/container-service';
+import { probeDiskUsage } from '../../services/disk-probe';
 import { collectFirewallReach } from '../../services/firewall-reach';
 import { runAllHealthChecks } from '../../services/health-runner';
+import { collectJailExemptions } from '../../services/jail-exemptions';
 import { probeMachines } from '../../services/machine-probe';
 import { parseStoredConfigValue } from '../../services/module-config';
 import { createPublicDnsProbe, loadPublicDnsProbeSettings } from '../../services/public-dns-probe';
@@ -153,8 +154,14 @@ function findMigrationsFolderSafe(): string | null {
  * indicators (FuelGauge) inside the audit subroutines and routes
  * progress messages to the caller instead — used by the TUI so
  * audit progress appears inside the alt-screen render.
+ *
+ * `quiet` (when true) silences them outright: the caller is going to
+ * emit a JSON document on stdout, and a gauge's frames are not JSON
+ * (celilo#1362).
  */
-async function buildAuditDeps(onProgress?: (msg: string) => void) {
+async function buildAuditDeps(
+  options: { onProgress?: (msg: string) => void; quiet?: boolean } = {},
+) {
   const db = getDb();
 
   const installed = db.select().from(modules).all();
@@ -209,7 +216,10 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     envVars: terraformEnvByModule.get(m.id) ?? {},
   }));
 
-  const healthResults = await runAllHealthChecks(db, { onProgress });
+  const healthResults = await runAllHealthChecks(db, {
+    onProgress: options.onProgress,
+    quiet: options.quiet,
+  });
 
   // Module integrity. Shallow by default: the installed tree against its
   // baseline, and the generated project against the installed tree. Both are
@@ -341,11 +351,22 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     }),
   );
 
-  // Machines-reachable: probe each pool machine. Shared with the monitor sweep
-  // (services/machine-probe.ts) — this block used to be a second copy of the
-  // same SSH logic, and both copies reported the local management box as
-  // unreachable because celilo does not hold an SSH key for itself.
-  const machineReachableResults: MachineReachableResult[] = await probeMachines();
+  // Machines-reachable and disk-space both SSH every system, so they run
+  // concurrently here rather than paying each other's latency. The machine
+  // probe is shared with the monitor sweep (services/machine-probe.ts) —
+  // this block used to be a second copy of the same SSH logic, and both
+  // copies reported the local management box as unreachable because celilo
+  // does not hold an SSH key for itself.
+  //
+  // The disk probe measures every system's root filesystem — the machine
+  // pool AND every provisioned instance, the systems celilo#1133 filled —
+  // in the same pre-computed measurement shape the disk_space monitor
+  // sweep consumes, so an audit finding and an alert page carry the same
+  // numbers.
+  const [machineReachableResults, diskUsageResults] = await Promise.all([
+    probeMachines(),
+    probeDiskUsage(db),
+  ]);
 
   const migrationsFolder = findMigrationsFolderSafe();
 
@@ -384,6 +405,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    jailExemptions: { exemptions: collectJailExemptions(db) },
     health: { results: healthResults },
     backups: { modules: installedBackupInfo },
     abandonedOperations: { records: loadAbandonedOperations(db) },
@@ -417,6 +439,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
       probe: createPublicDnsProbe(loadPublicDnsProbeSettings(db)),
       evidence: loadPublicDnsEvidence(db),
     },
+    diskSpace: { results: diskUsageResults },
     // Reads the record the poller already writes — this check never performs a
     // read of its own. One that did would drain the queue and eat the
     // acknowledgement it exists to protect (#541).
@@ -428,7 +451,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
       // still catching a transport that has genuinely stopped being readable.
       staleAfterMs: 30 * 60_000,
     },
-    trustedSources: { firewalls: collectFirewallReach(db) },
+    trustedSources: collectFirewallReach(db),
   };
 }
 
@@ -528,7 +551,7 @@ export async function handleSystemAudit(
           // and so the spinner caption keeps changing during the
           // parallel-audit phase (which doesn't emit its own).
           onProgress('Reading system state…');
-          const deps = await buildAuditDeps(onProgress);
+          const deps = await buildAuditDeps({ onProgress });
           onProgress('Analyzing drift across categories…');
           return runAudit(deps, onCategory);
         },
@@ -545,7 +568,7 @@ export async function handleSystemAudit(
 
   let deps: Awaited<ReturnType<typeof buildAuditDeps>>;
   try {
-    deps = await buildAuditDeps();
+    deps = await buildAuditDeps({ quiet: json });
   } catch (err) {
     return {
       success: false,

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

@@ -0,0 +1,295 @@
+/**
+ * Doctor remediation-arrow gate (celilo#1308).
+ *
+ * `celilo system doctor` renders `→ <command>` remediation lines under failing
+ * checks. Those strings are built by hand in three files and were never checked
+ * against the CLI's own command table, so doctor prescribed commands that
+ * cannot run:
+ *
+ * - `celilo module update <module-id>` — `module update` takes a PATH, so a
+ *   module id names an argument form that does not exist (the lunacycle case
+ *   in #1308).
+ * - `celilo system doctor --deep` — the doctor's own instruction, rejected by
+ *   `checkFlags` because `deep` was never declared on `system doctor`.
+ * - `celilo capability chain <module> <var>` — a command the ISS-0115 rework
+ *   removed from the registry.
+ *
+ * The gate scans the three files that produce the doctor's `→` surface
+ * (system-doctor.ts, fleet-checks.ts, module-integrity.ts) for `celilo ...`
+ * command spans and validates each against COMMANDS from @celilo/core:
+ *
+ * 1. every command word must resolve along the registry tree,
+ * 2. every flag must be declared on the leaf command,
+ * 3. positional count must fit the leaf command's declared args,
+ * 4. a value known to be a module id must never fill a path slot (an arg whose
+ *    completion is `directories` or `files`), variadic or not.
+ *
+ * Commands are parsed, never executed. A span is "strict" when a quote or
+ * backtick delimits it (the author wrote a command); a `celilo ...` occurrence
+ * without a delimiter is a hint embedded in a sentence and is only validated
+ * when everything after the command path is argument-shaped — trailing plain
+ * words mean the line talks ABOUT celilo ("celilo knows where its control
+ * plane runs"), which is prose, not a prescription.
+ *
+ * Reach floors: the scan asserts it resolved a real number of command spans
+ * and contains the anchors it exists to police, because a scan that resolves
+ * nothing exits 0 and proves nothing.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { type ArgDef, COMMANDS, type CommandDef } from '@celilo/core';
+
+const SOURCES = [
+  join(import.meta.dir, 'system-doctor.ts'),
+  join(import.meta.dir, '../../services/fleet-checks.ts'),
+  join(import.meta.dir, '../../services/audit/module-integrity.ts'),
+];
+
+/** Completion kinds whose value is a filesystem path, not an id. */
+const PATH_COMPLETIONS = new Set(['directories', 'files']);
+
+const INTERP = '\u0000';
+
+/** `${...}` expressions found by masking, in order. */
+const interps: string[] = [];
+
+function maskInterpolations(source: string): string {
+  interps.length = 0;
+  return source.replace(/\$\{([^{}]*)\}/g, (_m, expr: string) => {
+    interps.push(expr);
+    return `${INTERP}${interps.length - 1}${INTERP}`;
+  });
+}
+
+function interpText(masked: string): string {
+  const m = masked.match(new RegExp(`${INTERP}(\\d+)${INTERP}`));
+  return m ? (interps[Number(m[1])] ?? masked) : masked;
+}
+
+interface ParsedToken {
+  kind: 'word' | 'flag' | 'positional';
+  text: string;
+  /** True when the token's runtime value is a module id. */
+  isModuleId: boolean;
+}
+
+/**
+ * One `celilo ...` occurrence: the tokens after the word `celilo`, plus
+ * whether a quote delimited it (strict).
+ */
+interface Span {
+  tokens: ParsedToken[];
+  strict: boolean;
+  raw: string;
+}
+
+const FLAG = /^--[a-z0-9][a-z0-9-]*/;
+const PLACEHOLDER = /^<[^<>\s]+>/;
+
+function tokenize(text: string): ParsedToken[] {
+  const tokens: ParsedToken[] = [];
+  let rest = text;
+  while (rest.length > 0) {
+    rest = rest.replace(/^[\s,;]+/, '');
+    if (rest.length === 0) break;
+    let m = rest.match(FLAG);
+    if (m) {
+      tokens.push({ kind: 'flag', text: m[0].slice(2), isModuleId: false });
+      rest = rest.slice(m[0].length);
+      continue;
+    }
+    m = rest.match(PLACEHOLDER);
+    if (m) {
+      tokens.push({ kind: 'positional', text: m[0], isModuleId: false });
+      rest = rest.slice(m[0].length);
+      continue;
+    }
+    m = rest.match(/^\u0000(\d+)\u0000/);
+    if (m) {
+      const expr = interps[Number(m[1])] ?? '';
+      rest = rest.slice(m[0].length);
+      // ANSI chrome (${ANSI.reset} and friends) renders as an escape code,
+      // not as a value the operator types.
+      if (/^ANSI\.\w+$/.test(expr.trim())) continue;
+      tokens.push({ kind: 'positional', text: expr, isModuleId: /\bmoduleId\b/.test(expr) });
+      continue;
+    }
+    m = rest.match(/^[a-z][a-z0-9-]*(?:\.\u0000\d+\u0000[a-z0-9-]*)*/);
+    if (m) {
+      // A word that carries an interpolation (a key built at runtime, like
+      // network.<zone>.subnet) is a value, never a subcommand.
+      const isInterp = m[0].includes(INTERP);
+      const isModuleId = isInterp
+        ? (m[0].match(/\u0000(\d+)\u0000/g) ?? []).some((mark) =>
+            /\bmoduleId\b/.test(interpText(mark)),
+          )
+        : false;
+      tokens.push({ kind: isInterp ? 'positional' : 'word', text: m[0], isModuleId });
+      rest = rest.slice(m[0].length);
+      continue;
+    }
+    break; // punctuation, a closing quote, prose — the command part is over
+  }
+  return tokens;
+}
+
+/** Extract every `celilo ` occurrence with its span, per the rules above. */
+function extractSpans(maskedLine: string): Span[] {
+  const spans: Span[] = [];
+  const re = /\bcelilo(?=\s)/g;
+  let m: RegExpExecArray | null = re.exec(maskedLine);
+  while (m !== null) {
+    const before = m.index > 0 ? maskedLine[m.index - 1] : '';
+    const delimiter = before === '`' || before === "'" || before === '"' ? before : null;
+    const start = m.index + 'celilo'.length;
+    let content: string;
+    let strict: boolean;
+    if (delimiter) {
+      const closer = maskedLine.indexOf(delimiter, start);
+      strict = true;
+      content = closer === -1 ? maskedLine.slice(start) : maskedLine.slice(start, closer);
+      if (closer !== -1) re.lastIndex = closer + 1;
+    } else {
+      strict = false;
+      content = maskedLine.slice(start);
+    }
+    const tokens = tokenize(content);
+    if (tokens.length > 0) spans.push({ tokens, strict, raw: content.trim() });
+    if (re.lastIndex <= m.index) re.lastIndex = start;
+    m = re.exec(maskedLine);
+  }
+  return spans;
+}
+
+function walkPath(tokens: ParsedToken[]): { path: CommandDef[]; rest: ParsedToken[] } {
+  const path: CommandDef[] = [];
+  let node: CommandDef | undefined = COMMANDS.find((c) => c.name === tokens[0]?.text);
+  if (!node) return { path, rest: tokens };
+  path.push(node);
+  let i = 1;
+  while (i < tokens.length && tokens[i].kind === 'word') {
+    const next: CommandDef | undefined = node.subcommands?.find((s) => s.name === tokens[i].text);
+    if (!next) break;
+    node = next;
+    path.push(next);
+    i++;
+  }
+  return { path, rest: tokens.slice(i) };
+}
+
+/** Which declared arg the i-th positional fills (variadic absorbs the tail). */
+function slotFor(args: ArgDef[], i: number): ArgDef | undefined {
+  const variadicIndex = args.findIndex((a) => a.variadic);
+  const fixed = variadicIndex === -1 ? args.length : variadicIndex;
+  if (i < fixed) return args[i];
+  return variadicIndex === -1 ? undefined : args[variadicIndex];
+}
+
+function validateSpan(span: Span): string[] {
+  const { path, rest } = walkPath(span.tokens);
+  if (path.length === 0) return []; // first word is not a command: prose about celilo
+
+  // A hint embedded in prose is only a prescription when everything after the
+  // command path is argument-shaped. Trailing plain words mean the sentence
+  // continues ("celilo system migrate` to apply pending migrations...").
+  if (!span.strict && rest.some((t) => t.kind === 'word')) return [];
+
+  const name = `celilo ${path.map((c) => c.name).join(' ')}`;
+  const leaf = path[path.length - 1];
+  const violations: string[] = [];
+
+  for (const t of rest.filter((t) => t.kind === 'word')) {
+    violations.push(`${name}: unknown command word '${t.text}'`);
+  }
+
+  const declaredFlags = new Set([...(leaf.flags ?? []).map((f) => f.name), 'help', 'h']);
+  for (const t of rest.filter((t) => t.kind === 'flag')) {
+    if (!declaredFlags.has(t.text)) {
+      violations.push(`${name}: flag --${t.text} is not declared in the command registry`);
+    }
+  }
+
+  const args = leaf.args ?? [];
+  const positionals = rest.filter((t) => t.kind === 'positional');
+  if (!args.some((a) => a.variadic) && positionals.length > args.length) {
+    violations.push(
+      `${name}: ${positionals.length} positional value(s) but only ${args.length} declared arg(s)`,
+    );
+  }
+  positionals.forEach((token, i) => {
+    const slot = slotFor(args, i);
+    if (!slot) return;
+    if (
+      token.isModuleId &&
+      slot.completion !== undefined &&
+      PATH_COMPLETIONS.has(slot.completion)
+    ) {
+      violations.push(
+        `${name}: module id '${token.text}' fills the '${slot.name}' slot, which takes a path (${slot.completion})`,
+      );
+    }
+  });
+
+  return violations;
+}
+
+describe('doctor remediation arrow gate (celilo#1308)', () => {
+  it('flags a module id passed into a path slot, even a variadic one', () => {
+    // Rule 7.6 anchor: the exact defect shape from #1308 (`module update
+    // <module-id>`), pinned synthetically so the rule cannot silently stop
+    // matching the registry.
+    maskInterpolations(''); // reset
+    interps.push('result.moduleId');
+    const violations = validateSpan({
+      tokens: tokenize(`module update ${INTERP}0${INTERP}`),
+      strict: true,
+      raw: 'module update ${result.moduleId}',
+    });
+    expect(violations.some((v) => v.includes('takes a path'))).toBe(true);
+  });
+
+  it('every command the doctor prescribes exists, with declared flags and fitting args', () => {
+    const violations: string[] = [];
+    let resolvedCount = 0;
+    const resolvedHeads = new Set<string>();
+
+    for (const file of SOURCES) {
+      const raw = readFileSync(file, 'utf8');
+      // Strip block comments and whole-line // comments so doc headers that
+      // mention commands historically are not prescribed commands now.
+      const stripped = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+      const masked = maskInterpolations(stripped);
+      const shortFile = file.split('/').pop() ?? file;
+
+      for (const line of masked.split('\n')) {
+        for (const span of extractSpans(line)) {
+          const found = validateSpan(span);
+          if (found.length === 0 && span.strict) resolvedCount++;
+          for (const v of found) violations.push(`[${shortFile}] ${v}  (span: "${span.raw}")`);
+          const head = span.tokens
+            .slice(0, 2)
+            .map((t) => t.text)
+            .join(' ');
+          if (head) resolvedHeads.add(head);
+        }
+      }
+    }
+
+    // Reach floors. A scan that resolves nothing proves nothing.
+    expect(resolvedCount).toBeGreaterThanOrEqual(12);
+    for (const anchor of [
+      'system doctor',
+      'module verify',
+      'monitor add',
+      'events repair',
+      'system migrate',
+    ]) {
+      const found = [...resolvedHeads].some((h) => h.startsWith(anchor));
+      expect(found).toBe(true);
+    }
+
+    expect(violations).toEqual([]);
+  });
+});