@celilo/cli 2.1.0 → 2.2.0

package/src/policy/module-script-scan.ts

@@ -26,7 +26,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 
 export interface ScanViolation {
   /** Path as the operator should see it — relative to the scanned root. */
@@ -52,7 +52,58 @@ export interface ScanViolation {
  */
 const ESCAPE_HATCH_LOOKBACK_LINES = 8;
 
+/**
+ * The rule name for a module script that reaches the `celilo` CLI as a child
+ * process. Exported because the debt list below and both test files key on it;
+ * a literal repeated in three places is the duplicate that drifts.
+ */
+export const JAILED_CLI_SPAWN_RULE = 'jailed hook spawns the celilo CLI';
+
+/**
+ * The rule name for a module script that catches a refused framework call and
+ * carries on with a value it invented (e2e-suite-recovery §4, spec delta
+ * `specs/module-lifecycle/spec.md`). Exported for the same reason as the spawn
+ * rule: the debt list below and the gate's test file key on it.
+ */
+export const SWALLOWED_REFUSAL_RULE = 'swallowed framework refusal';
+
+/**
+ * A framework-reaching call, spelled as this repo spells them today: one of
+ * the spawn-family calls naming the `celilo` CLI (the same shape the spawn
+ * rule above keys on — extracted here so the two rules cannot disagree about
+ * what reaches the framework), or a call through `runCelilo`, knot-unbound-
+ * internal's injected CLI runner (wired to `execFileSync('celilo', …)` where
+ * the hook is constructed; the debt list's own reason text names the
+ * "runCelilo wrapper").
+ *
+ * What it deliberately cannot see, same honesty class as every rule in this
+ * file: a wrapper under any other name, a binary path resolved into a
+ * variable, or a spawn reached through an indirection. A lint, not a boundary.
+ */
+const CLI_SPAWN_RE =
+  /\b(?:execSync|execFileSync|execFile|exec|spawnSync|spawn)\s*\(\s*(?:['"`]\s*celilo(?=\s|['"`])|`[^`]*\bcelilo(?=\s|`))/;
+const FRAMEWORK_CALL_RE = new RegExp(`${CLI_SPAWN_RE.source}|\\brunCelilo\\s*\\(`);
+
 const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
+  {
+    rule: JAILED_CLI_SPAWN_RULE,
+    // Same regex as CLI_SPAWN_RE below — one definition of "reaches the
+    // framework", used by both rules that key on it. Matches the CLI as
+    // argv[0] of a spawn-family call ('celilo' / "celilo"), or inside a shell
+    // string passed to one, where celilo is followed by a word (a subcommand)
+    // or the closing quote — so `docker exec celilo-mgr …`, a `celilo.db` file
+    // name, and prose that merely names the CLI do not fire. What it
+    // deliberately cannot see: a binary path resolved into a variable, or a
+    // spawn reached through an indirection. Same honesty class as the
+    // namespace rule — a lint, not a boundary.
+    re: CLI_SPAWN_RE,
+    hint:
+      'A jailed hook has no celilo binary and no shell, so this dies with ' +
+      '"Executable not found in $PATH" (celilo#1225). Replace the spawn with an ' +
+      'injected capability — context.secrets/context.config for self-config and ' +
+      'self-secrets (openspec/changes/hook-owned-state) — or move the operation ' +
+      'into the framework the way celilo-mgmt on_install did (5e0e624d).',
+  },
   {
     rule: 'raw ssh invocation (StrictHostKeyChecking)',
     re: /StrictHostKeyChecking/,
@@ -97,6 +148,45 @@ const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
   },
 ];
 
+/**
+ * How far below a framework-reaching call the `catch` clause may sit for the
+ * call to count as caught. Calibrated against the three real sites rather than
+ * guessed: the widest call-to-catch gap among them is four lines (on_backup's
+ * machine-pool snapshot parses between the call and the catch). Six covers
+ * those with headroom and cannot reach the next statement's catch in any
+ * module script in the tree.
+ */
+const SWALLOW_LOOKAHEAD_LINES = 6;
+
+/**
+ * How deep into a catch body the scan looks for a `throw` before concluding
+ * the catch swallows. A refusal that propagates (rethrow, wrapped throw) is
+ * correct handling and must not fire; a catch that returns a literal, logs and
+ * continues, or only comments must. Eight lines is beyond any catch body in
+ * the tree; a longer one hides from this scan the same way a renamed wrapper
+ * does.
+ */
+const SWALLOW_CATCH_BODY_LINES = 8;
+
+const CATCH_CLAUSE_RE = /\bcatch\b/;
+const THROW_RE = /\bthrow\b/;
+const CATCH_CLOSE_RE = /^\s*}\s*(?:catch|finally|else)?\s*;?\s*$/;
+
+/**
+ * The catch clause a framework-reaching call landed in swallows when its body
+ * contains no `throw` within the window: the refusal is absorbed and the hook
+ * carries on. Returns false (handled correctly) when the catch propagates the
+ * refusal, and true only for the swallowed shape.
+ */
+function catchSwallows(lines: string[], catchIdx: number): boolean {
+  const end = Math.min(catchIdx + SWALLOW_CATCH_BODY_LINES, lines.length - 1);
+  for (let k = catchIdx + 1; k <= end; k++) {
+    if (THROW_RE.test(lines[k])) return false;
+    if (k > catchIdx + 1 && CATCH_CLOSE_RE.test(lines[k])) break;
+  }
+  return true;
+}
+
 /** A `runAppCommand(` / `runAppCommandWithSecret(` CALL — not the import. */
 const RAW_EXEC_CALL = /\brunAppCommand(?:WithSecret)?\s*\(/;
 
@@ -131,6 +221,35 @@ export function scanModuleScriptSource(file: string, source: string): ScanViolat
     }
   });
 
+  // The swallowed-refusal pass: windowed, like the escape-hatch check above —
+  // a catch clause this far below a framework-reaching call is the call's
+  // catch. Reported on the CALL line, because that is the site an author fixes.
+  lines.forEach((text, i) => {
+    if (!FRAMEWORK_CALL_RE.test(text)) return;
+    const last = Math.min(i + SWALLOW_LOOKAHEAD_LINES, lines.length - 1);
+    for (let j = i + 1; j <= last; j++) {
+      if (CATCH_CLAUSE_RE.test(lines[j])) {
+        if (catchSwallows(lines, j)) {
+          violations.push({
+            file,
+            line: i + 1,
+            rule: SWALLOWED_REFUSAL_RULE,
+            hint:
+              'A refused framework call must fail, not continue with an answer it invented ' +
+              '(e2e-suite-recovery §4): a refusal and an absence are different facts. Let the ' +
+              'error propagate, or read through a surface that distinguishes them — an injected ' +
+              'typed-absent reader (openspec/changes/hook-owned-state) — rather than catching ' +
+              'and substituting.',
+          });
+        }
+        break;
+      }
+      // A blank line or a closing brace at statement level ends the call's
+      // statement; a catch further down belongs to something else.
+      if (lines[j].trim() === '' || /^[)}]/.test(lines[j])) break;
+    }
+  });
+
   return violations;
 }
 
@@ -164,12 +283,25 @@ export function moduleScriptFiles(scriptsDir: string): string[] {
 
 /**
  * Scan a module directory (the one holding `manifest.yml`). Returns every
- * violation in its `scripts/`, with paths relative to `moduleDir`.
+ * violation in its `scripts/`, with paths relative to `moduleDir`, minus the
+ * jailed-CLI-spawn sites on the debt list. The module id is the directory's
+ * basename — the same assumption `packaging/build.ts`'s refusal message makes.
  */
 export function scanModuleDirectory(moduleDir: string): ScanViolation[] {
-  return moduleScriptFiles(join(moduleDir, 'scripts')).flatMap((f) =>
-    scanModuleScriptSource(relative(moduleDir, f), readFileSync(f, 'utf-8')),
-  );
+  const moduleId = basename(moduleDir);
+  // One exemption set per rule, keyed the same way: a debt entry silences its
+  // own rule on its own file and nothing else.
+  const debtByRule: Record<string, Set<string>> = {
+    [JAILED_CLI_SPAWN_RULE]: new Set(
+      JAILED_CLI_SPAWN_DEBT.filter((e) => e.module === moduleId).map((e) => e.file),
+    ),
+    [SWALLOWED_REFUSAL_RULE]: new Set(
+      SWALLOWED_REFUSAL_DEBT.filter((e) => e.module === moduleId).map((e) => e.file),
+    ),
+  };
+  return moduleScriptFiles(join(moduleDir, 'scripts'))
+    .flatMap((f) => scanModuleScriptSource(relative(moduleDir, f), readFileSync(f, 'utf-8')))
+    .filter((v) => !(debtByRule[v.rule]?.has(v.file) ?? false));
 }
 
 /** Render violations for a test failure message or a refused publish. */
@@ -177,6 +309,144 @@ export function formatViolations(violations: ScanViolation[]): string {
   return violations.map((v) => `  ${v.file}:${v.line}\n    → ${v.rule}. ${v.hint}`).join('\n');
 }
 
+export interface PolicyDebtEntry {
+  /** Module directory name under `modules/`. */
+  module: string;
+  /** Script path relative to the module directory, e.g. `scripts/setup.ts`. */
+  file: string;
+  /** How many jailed-CLI spawns the file carries today. Pinned so a NEW spawn in an exempted file cannot hide behind the entry. */
+  matches: number;
+  /** Who converts this site, and into what. */
+  reason: string;
+}
+
+/**
+ * The known jailed-CLI spawns, exempted from the rule above until their
+ * conversion lands (hook-owned-state task 5.5; e2e-suite-recovery §3).
+ *
+ * These sites are tracked defects, not sanctioned forms: the jail kills every
+ * one of them the same way it killed celilo-mgmt's on_install (5e0e624d). The
+ * list exists so the rule can land RED-proof while the conversion — which
+ * needs the HookStore from hook-owned-state tasks 2 and 3 — is still at 0%.
+ * It is narrow on purpose (celilo#1014's lesson): one entry per file, each
+ * naming its owner, each pinning the exact number of spawns so a new call
+ * site cannot hide behind an existing entry.
+ *
+ * The debt test in `no-hand-built-ssh.test.ts` asserts every entry still
+ * matches its recorded count. When a conversion lands the count drops to zero,
+ * the test goes red, and the entry must be deleted in the same change.
+ */
+export const JAILED_CLI_SPAWN_DEBT: readonly PolicyDebtEntry[] = [
+  {
+    module: 'celilo-mgmt',
+    file: 'scripts/on_backup.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 / survey class G: machine list becomes a machine-pool read capability',
+  },
+  {
+    module: 'caddy-internal',
+    file: 'scripts/private-web-functions.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (routes, capability-owned-tables Group B1)',
+  },
+  {
+    module: 'dnsmasq-dhcp',
+    file: 'scripts/dhcp-server-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/on-consumer-removed.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (runner_registrations, Group B3)',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/setup.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (secret set)',
+  },
+  {
+    module: 'forgejo',
+    file: 'scripts/source-forge-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'generic-cpanel-hosting-provider',
+    file: 'scripts/on-consumer-removed.ts',
+    matches: 1,
+    reason: 'hook-owned-state 5.5 (publications, Group B4)',
+  },
+  {
+    module: 'generic-cpanel-hosting-provider',
+    file: 'scripts/publish-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/control-plane-vpn-functions.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 shape (self-config write); not in its 10-site table — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/health-check.ts',
+    matches: 1,
+    reason:
+      'survey class C: system config get becomes an injected read; not in hook-owned-state 5.5 — reconcile there',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/on_install.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 (registered_peers, Group B2); THE five-suite blocker per the wave-0 census',
+  },
+  {
+    module: 'wireguard-manager',
+    file: 'scripts/setup.ts',
+    matches: 3,
+    reason:
+      'hook-owned-state 5.5 (vpn_endpoint/vpn_server_public_key/client_pool, category 3; secret set)',
+  },
+];
+
+/**
+ * The known swallowed refusals, exempted from the rule above until their
+ * conversion lands (hook-owned-state 5.5; e2e-suite-recovery §4). Same
+ * mechanics and same narrowness as the spawn debt above — one entry per file,
+ * each naming its owner, each pinning the exact number of swallows — with the
+ * same guarded rot: when a site converts, the count drops, the debt test goes
+ * red, and the entry must be deleted in the same change.
+ *
+ * Converted on 2026-09-07 by ce-pvii: knot-unbound-internal/scripts/on-install.ts
+ * dropped its last swallow (the runCelilo wrapper), so the rule fires on
+ * exactly these two sites and nothing else in the tree.
+ */
+export const SWALLOWED_REFUSAL_DEBT: readonly PolicyDebtEntry[] = [
+  {
+    module: 'celilo-mgmt',
+    file: 'scripts/on_backup.ts',
+    matches: 1,
+    reason:
+      'hook-owned-state 5.5 / survey class G: machine list becomes a typed-absent machine-pool read',
+  },
+  {
+    module: 'wireguard',
+    file: 'scripts/health-check.ts',
+    matches: 1,
+    reason: 'survey class C: system config get becomes an injected typed-absent read',
+  },
+];
+
 /**
  * The files inside `@celilo/capabilities` that implement the remote-exec
  * primitives themselves. `remote.ts` is the ONE sanctioned place the

package/src/policy/no-hand-built-ssh.test.ts

@@ -12,15 +12,18 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import {
+  JAILED_CLI_SPAWN_DEBT,
+  JAILED_CLI_SPAWN_RULE,
   REMOTE_PRIMITIVE_FILES,
   capabilityPackageSourceFiles,
   formatViolations,
   moduleScriptFiles,
   scanCapabilityPackageSource,
   scanModuleDirectory,
+  scanModuleScriptSource,
 } from './module-script-scan';
 
 /** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
@@ -56,6 +59,36 @@ describe('recurrence gate: modules never hand-build SSH', () => {
   });
 });
 
+describe('recurrence gate: the jailed-CLI-spawn debt list is honest', () => {
+  // The debt list in module-script-scan exempts real, tracked defects from the
+  // jailed-CLI-spawn rule so the rule can land green before hook-owned-state
+  // converts them. Three ways this list could silently rot, and this is the
+  // guard for each:
+  //   a site is converted  -> the file stops matching, the entry must go
+  //   a NEW site appears   -> the pinned count moves, the entry must be revisited
+  //   a file is deleted    -> the entry names a ghost and must go
+  test('every entry names an existing file carrying exactly its pinned spawn count', () => {
+    for (const entry of JAILED_CLI_SPAWN_DEBT) {
+      const f = join(repoRoot(), 'modules', entry.module, entry.file);
+      expect(
+        existsSync(f),
+        `${entry.module}/${entry.file} no longer exists — delete its debt entry`,
+      ).toBe(true);
+      const hits = scanModuleScriptSource(entry.file, readFileSync(f, 'utf-8')).filter(
+        (v) => v.rule === JAILED_CLI_SPAWN_RULE,
+      );
+      expect(
+        hits.length,
+        `${entry.module}/${entry.file} carries ${hits.length} jailed-CLI spawns, the debt entry pins ${entry.matches} (${entry.reason}) — convert or update the entry`,
+      ).toBe(entry.matches);
+    }
+  });
+
+  test('the debt list is non-trivial (the guard actually reached the entries)', () => {
+    expect(JAILED_CLI_SPAWN_DEBT.length).toBeGreaterThan(5);
+  });
+});
+
 describe('recurrence gate: @celilo/capabilities itself never hand-builds SSH', () => {
   // The workspace source — where the package is authored, and the only copy a
   // commit in this repo can fix. Each module's bundled copy is an npm snapshot

package/src/policy/no-swallowed-refusal.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Recurrence gate for openspec/changes/e2e-suite-recovery §4: **a hook whose
+ * framework call is refused fails, rather than continuing with an answer it
+ * invented** (spec delta `specs/module-lifecycle/spec.md`, scenario "The
+ * pattern cannot be reintroduced").
+ *
+ * The rule itself lives in `./module-script-scan`, because this is not the only
+ * place it runs — `.netapp` packaging applies the same scan at publish time.
+ * One definition, two callers.
+ *
+ * The two sites this gate exists for (e2e-suite-recovery tasks 4.1/4.2, all
+ * still in the tree on the swallow debt list; a third, knot-unbound-internal
+ * scripts/on-install.ts:69, converted on 2026-09-07 by ce-pvii and deleted
+ * from both debt lists in the same change):
+ *   modules/celilo-mgmt/scripts/on_backup.ts:52        catch { return [] }
+ *   modules/wireguard/scripts/health-check.ts:73       catch { return null }
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  SWALLOWED_REFUSAL_DEBT,
+  SWALLOWED_REFUSAL_RULE,
+  formatViolations,
+  moduleScriptFiles,
+  scanModuleDirectory,
+  scanModuleScriptSource,
+} from './module-script-scan';
+
+/** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
+function repoRoot(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'modules')) && existsSync(join(dir, 'apps'))) return dir;
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with modules/ + apps/)');
+}
+
+function moduleDirs(): string[] {
+  const modulesRoot = join(repoRoot(), 'modules');
+  return readdirSync(modulesRoot)
+    .map((m) => join(modulesRoot, m))
+    .filter((d) => statSync(d).isDirectory() && existsSync(join(d, 'scripts')));
+}
+
+/** Swallow-rule violations only — the other rules are different gates with their own tests. */
+function swallowRule(violations: ReturnType<typeof scanModuleScriptSource>) {
+  return violations.filter((v) => v.rule === SWALLOWED_REFUSAL_RULE);
+}
+
+describe('recurrence gate: a hook does not swallow a refused framework call', () => {
+  describe('the shapes it must reject', () => {
+    test('catch returning a literal below a spawned framework call (on_backup shape)', () => {
+      const source = [
+        'function snapshot(): unknown[] {',
+        '  try {',
+        "    const stdout = execSync('celilo machine list --json', { encoding: 'utf-8' });",
+        '    return JSON.parse(stdout);',
+        '  } catch {',
+        '    // older celilo, or no machines yet',
+        '    return [];',
+        '  }',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(3); // the framework-reaching call, not the catch
+    });
+
+    test('comment-only catch below an injected CLI-runner call (on_install shape)', () => {
+      const source = [
+        'function repoint(ip: string, runCelilo: (args: string[]) => string): void {',
+        '  let prior: string | undefined;',
+        '  try {',
+        "    prior = parse(runCelilo(['system', 'config', 'get', 'dns.primary']));",
+        '  } catch {',
+        '    // dns.primary not set yet — nothing to demote.',
+        '  }',
+        '  runCelilo(["system", "apply-config", `dns.primary=${ip}`]);',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(4);
+    });
+
+    test('catch returning null below execFileSync (health-check shape)', () => {
+      const source = [
+        'function read(key: string): string | null {',
+        '  try {',
+        "    const out = execFileSync('celilo', ['system', 'config', 'get', key], { encoding: 'utf-8' });",
+        '    return parse(key, out);',
+        '  } catch {',
+        '    return null;',
+        '  }',
+        '}',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+      expect(hits[0].line).toBe(3);
+    });
+
+    test('log-and-continue catch below a spawned framework call', () => {
+      const source = [
+        'try {',
+        "  execSync('celilo system apply-config dns.primary=10.0.0.1');",
+        '} catch (err) {',
+        '  logger.warn(`repoint failed: ${err}`);',
+        '}',
+        'logger.success("dns.primary repointed");',
+      ].join('\n');
+      const hits = swallowRule(scanModuleScriptSource('scripts/x.ts', source));
+      expect(hits.length, `expected 1, got:\n${formatViolations(hits)}`).toBe(1);
+    });
+  });
+
+  describe('the shapes it must accept', () => {
+    test('a typed-absent reader: no catch between the hook and the answer', () => {
+      const source = [
+        'export async function healthCheck(deps: HealthDeps): Promise<Output> {',
+        '  const { readConfig } = deps;',
+        '  const value = readConfig("server_public_key");',
+        '  if (!value.present) return { status: "absent", key: "server_public_key" };',
+        '  return { status: "ok", key: value.data };',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+
+    test('a catch that rethrows: the refusal propagates', () => {
+      const source = [
+        'try {',
+        "  execSync('celilo system apply-config dns.primary=10.0.0.1');",
+        '} catch (err) {',
+        '  throw new Error(`dns.primary repoint refused: ${String(err)}`);',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+
+    test('a catch below work that never reaches the framework', () => {
+      const source = [
+        'function parse(raw: string): unknown[] {',
+        '  try {',
+        '    const parsed: unknown = JSON.parse(raw);',
+        '    return Array.isArray(parsed) ? parsed : [];',
+        '  } catch {',
+        '    return [];',
+        '  }',
+        '}',
+      ].join('\n');
+      expect(swallowRule(scanModuleScriptSource('scripts/x.ts', source))).toEqual([]);
+    });
+  });
+
+  test('reach: the scan walks every scripts/ directory and flags every planted violation', () => {
+    // Mirror of the real layout (modules/<m>/scripts/**), planted per the
+    // reach rule: a violating hook in EVERY directory the scan should reach —
+    // the module scripts root and a nested subdirectory — plus a clean module
+    // the scan must come back empty on.
+    const root = join(repoRoot(), '.tmp-swallow-reach-fixture');
+    rmSync(root, { recursive: true, force: true });
+    const violating = (name: string) =>
+      [
+        `// ${name}`,
+        'export function run() {',
+        '  try {',
+        "    execSync('celilo system config get dns.primary');",
+        '  } catch {',
+        '    return null;',
+        '  }',
+        '}',
+      ].join('\n');
+    try {
+      const planted = [
+        'modules/alpha/scripts/one.ts',
+        'modules/alpha/scripts/nested/two.ts',
+        'modules/beta/scripts/three.ts',
+      ];
+      for (const p of planted) {
+        const f = join(root, p);
+        mkdirSync(resolve(f, '..'), { recursive: true });
+        writeFileSync(f, violating(p));
+      }
+      const cleanDir = join(root, 'modules/clean/scripts');
+      mkdirSync(cleanDir, { recursive: true });
+      writeFileSync(
+        join(cleanDir, 'clean.ts'),
+        'export function run(readConfig: (k: string) => { present: boolean }) {\n  return readConfig("k");\n}\n',
+      );
+
+      // Per-module expectation, in the module-relative paths the scan
+      // reports: every planted file came back exactly once, and the clean
+      // module contributed nothing.
+      const flagged = (m: string) =>
+        new Set(swallowRule(scanModuleDirectory(join(root, 'modules', m))).map((v) => v.file));
+      expect([...flagged('alpha')].sort()).toEqual(['scripts/nested/two.ts', 'scripts/one.ts']);
+      expect([...flagged('beta')]).toEqual(['scripts/three.ts']);
+      expect([...flagged('clean')]).toEqual([]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('today’s tree: the remaining known sites are flagged, and nothing else is', () => {
+    // Raw scan, deliberately NOT scanModuleDirectory: the debt list below
+    // exempts these same files so the merged gate stays green while
+    // hook-owned-state converts them, and this assertion has to outlive that
+    // exemption to prove the rule still reaches them.
+    const violations = moduleDirs().flatMap((d) =>
+      swallowRule(
+        moduleScriptFiles(join(d, 'scripts')).flatMap((f) =>
+          scanModuleScriptSource(f, readFileSync(f, 'utf-8')),
+        ),
+      ),
+    );
+    const sites = violations.map((v) => v.file.replace(`${repoRoot()}/`, '')).sort();
+    // Pinned to the exact sites from e2e-suite-recovery task 4.2, as measured
+    // on 2026-09-07 at on_backup.ts:52 and health-check.ts:73 (a third,
+    // on-install.ts:69, converted by ce-pvii the same day). A converted site
+    // drops out and the debt entry must go; a NEW site appearing here is the
+    // next instance this scan exists to stop.
+    expect(sites).toEqual([
+      'modules/celilo-mgmt/scripts/on_backup.ts',
+      'modules/wireguard/scripts/health-check.ts',
+    ]);
+  });
+});
+
+describe('recurrence gate: the swallow debt list is honest', () => {
+  // Same three ways this list could silently rot as the jailed-CLI-spawn debt
+  // guard, same guard for each.
+  test('every entry names an existing file carrying exactly its pinned swallow count', () => {
+    for (const entry of SWALLOWED_REFUSAL_DEBT) {
+      const f = join(repoRoot(), 'modules', entry.module, entry.file);
+      expect(
+        existsSync(f),
+        `${entry.module}/${entry.file} no longer exists — delete its debt entry`,
+      ).toBe(true);
+      const hits = scanModuleScriptSource(entry.file, readFileSync(f, 'utf-8')).filter(
+        (v) => v.rule === SWALLOWED_REFUSAL_RULE,
+      );
+      expect(
+        hits.length,
+        `${entry.module}/${entry.file} carries ${hits.length} swallowed refusals, the debt entry pins ${entry.matches} (${entry.reason}) — convert or update the entry`,
+      ).toBe(entry.matches);
+    }
+  });
+
+  test('the debt list is non-trivial (the guard actually reached the entries)', () => {
+    // The list held three entries until ce-pvii converted the on-install.ts
+    // entry (2026-09-07); two remain, so the guard still proves engagement.
+    expect(SWALLOWED_REFUSAL_DEBT.length).toBeGreaterThan(1);
+  });
+});

package/src/policy/no-tar-shell-out-in-services.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Recurrence gate for celilo#1235: **services never shell out to `tar`; they
+ * use the `tar` package.**
+ *
+ * `tar@^7` is a declared dependency of @celilo/cli, but backup/restore built
+ * tar command lines and handed them to execSync. That made `tar` an undeclared
+ * runtime dependency on a host binary: Essential on Debian, so it never bit,
+ * but a container base image is where "always there" stops being true. The
+ * services now use the library (same shape the hook boundary is moving to via
+ * pack_directory), and this file keeps them there.
+ *
+ * Scoped to apps/celilo/src/services (the surface celilo#1235 covers). Test
+ * files are excluded — they legitimately drive the system tar to cross-check
+ * archives written by the library.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+function serviceSourceFiles(): string[] {
+  const dir = join(import.meta.dir, '../services');
+  const walk = (d: string): string[] =>
+    readdirSync(d).flatMap((name) => {
+      const path = join(d, name);
+      if (statSync(path).isDirectory()) return walk(path);
+      return name.endsWith('.ts') && !name.endsWith('.test.ts') ? [path] : [];
+    });
+  return walk(dir);
+}
+
+describe('recurrence gate: services never shell out to tar', () => {
+  test('scans a non-trivial set of service sources (sanity — the scan actually ran)', () => {
+    expect(serviceSourceFiles().length).toBeGreaterThan(10);
+  });
+
+  test('no service source passes a "tar ..." string to execSync', () => {
+    const offenders = serviceSourceFiles().filter((path) =>
+      /execSync\(\s*[`'"]tar /.test(readFileSync(path, 'utf-8')),
+    );
+    expect(offenders).toEqual([]);
+  });
+});