@celilo/cli 2.2.0 → 2.3.0

package/src/services/audit/jail-exemptions.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Tests for the `jail_exemptions` audit category (per-module-jail-policy
+ * task 3.3/3.4).
+ *
+ * The severity contract is the point: an operator-recorded exemption is
+ * `todo`, never `drift`, so `system update` never treats it as work. And the
+ * negative half: a fleet with no exemptions contributes no findings.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { auditJailExemptions } from './jail-exemptions';
+
+const EXEMPT = { moduleId: 'caddy', policy: 'off' as const, systemPolicy: 'auto' as const };
+
+describe('auditJailExemptions (per-module-jail-policy task 3.3)', () => {
+  test('no exemptions produce no findings (the negative half of task 3.4)', async () => {
+    expect(await auditJailExemptions({ exemptions: [] })).toEqual([]);
+  });
+
+  test('each exemption is one finding, severity todo, never drift', async () => {
+    const findings = await auditJailExemptions({
+      exemptions: [EXEMPT, { moduleId: 'vault', policy: 'auto', systemPolicy: 'required' }],
+    });
+    expect(findings).toHaveLength(2);
+    for (const f of findings) {
+      expect(f.category).toBe('jail_exemptions');
+      expect(f.severity).toBe('todo');
+      expect(f.severity).not.toBe('drift');
+      expect(f.code).toBe('hook_jail_exemption');
+      expect(f.actionable).toBe(false);
+    }
+  });
+
+  test('the finding names the module and both policies', async () => {
+    const [finding] = await auditJailExemptions({ exemptions: [EXEMPT] });
+    expect(finding).toBeDefined();
+    expect(finding?.subject).toBe('caddy');
+    expect(finding?.message).toContain('caddy');
+    expect(finding?.message).toContain("'off'");
+    expect(finding?.message).toContain("'auto'");
+  });
+});

package/src/services/audit/jail-exemptions.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-module hook jail exemption check (per-module-jail-policy task 3.3).
+ *
+ * One finding per module the operator exempted from the fleet's jail policy.
+ * Severity `todo`, deliberately NOT `drift`: the operator chose this, so it
+ * is a list of recorded exceptions to revisit, not a system that moved away
+ * from a desired state. `todo` never escalates the verdict past READY, which
+ * is what keeps `system update` from treating an exemption as work to do.
+ */
+
+import type { JailExemption } from '../jail-exemptions';
+import type { DriftFinding } from './types';
+
+export interface JailExemptionsAuditDeps {
+  /**
+   * The exemptions, from the shared collector (`services/jail-exemptions.ts`).
+   * A fleet with none contributes nothing — that is the normal state, and
+   * emitting a "no exemptions" finding would be a surface reporting an
+   * exemption nobody set (task 3.4).
+   */
+  exemptions: JailExemption[];
+}
+
+export async function auditJailExemptions(deps: JailExemptionsAuditDeps): Promise<DriftFinding[]> {
+  return deps.exemptions.map((exemption) => ({
+    category: 'jail_exemptions' as const,
+    severity: 'todo' as const,
+    code: 'hook_jail_exemption',
+    subject: exemption.moduleId,
+    message: `${exemption.moduleId} runs under jail policy '${exemption.policy}', weaker than the system's '${exemption.systemPolicy}'`,
+    details: [
+      'Its hooks run with the weaker posture while the rest of the fleet jails.',
+      'The operator recorded this per-module policy with `celilo module jail`.',
+      'Exemptions are deliberate, which is why this is todo and not drift —',
+      'but an exemption nobody remembers is how a jail quietly stops covering',
+      'the fleet. Revisit it: either the reason still holds, or clear it.',
+      '',
+      `To review:  celilo module jail ${exemption.moduleId}`,
+      `To clear:   celilo module jail ${exemption.moduleId} --clear`,
+    ].join('\n'),
+    remediation: `Clear it with 'celilo module jail ${exemption.moduleId} --clear' if the module now jails cleanly`,
+    actionable: false,
+  }));
+}

package/src/services/audit/module-integrity.test.ts

@@ -58,7 +58,9 @@ describe('auditModuleIntegrity', () => {
     expect(findings).toHaveLength(1);
     expect(findings[0]?.code).toBe('module_integrity_stale_baseline');
     expect(findings[0]?.severity).toBe('unmeasured');
-    expect(findings[0]?.remediation).toBe('celilo module update wireguard');
+    expect(findings[0]?.remediation).toBe(
+      'no automatic remediation: the baseline predates version stamping',
+    );
   });
 
   test('file drift under a TRUSTWORTHY baseline is drift, and lists every file', () => {
@@ -82,27 +84,6 @@ describe('auditModuleIntegrity', () => {
     expect(findings[0]?.details).toContain('scripts/new.ts');
   });
 
-  test('a stale generated project is drift, and says a deploy would ship the wrong bytes', () => {
-    const findings = auditModuleIntegrity({
-      results: [
-        {
-          ...clean('wireguard-manager'),
-          success: false,
-          violations: [
-            {
-              type: 'stale-generated',
-              path: 'ansible/roles/vpn/files/bin',
-              message: 'Generated project holds different bytes',
-            },
-          ],
-        },
-      ],
-    });
-    expect(findings.map((f) => f.code)).toEqual(['module_generated_stale']);
-    expect(findings[0]?.severity).toBe('drift');
-    expect(findings[0]?.remediation).toBe('celilo module generate wireguard-manager');
-  });
-
   test('host-plane results carry through with the right severity', () => {
     const findings = auditModuleIntegrity({
       results: [
@@ -143,4 +124,24 @@ describe('auditModuleIntegrity', () => {
       expect(f.actionable).toBe(true);
     }
   });
+
+  test('a stale baseline says there is no command, it does not prescribe one (celilo#1308)', () => {
+    const findings = auditModuleIntegrity({
+      results: [
+        {
+          ...clean('c'),
+          success: false,
+          violations: [
+            { type: 'stale-baseline', path: 'x', message: 'baseline is v1, manifest v2' },
+          ],
+        },
+      ],
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0].code).toBe('module_integrity_stale_baseline');
+    // `module update` takes a source path, not the module id this finding
+    // carries, and no other verb restamps a baseline. Name the gap.
+    expect(findings[0].remediation).not.toMatch(/celilo /);
+    expect(findings[0].actionable).toBe(false);
+  });
 });

package/src/services/audit/module-integrity.ts

@@ -52,22 +52,13 @@ export function auditModuleIntegrity(deps: ModuleIntegrityAuditDeps): DriftFindi
         severity: 'unmeasured',
         code: 'module_integrity_stale_baseline',
         message: `${result.moduleId}: ${violation.message}`,
-        remediation: `celilo module update ${result.moduleId}`,
-        actionable: true,
-        subject: result.moduleId,
-      });
-    }
-
-    const generated = result.violations.filter((v) => v.type === 'stale-generated');
-    if (generated.length > 0) {
-      findings.push({
-        category: 'module_integrity',
-        severity: 'drift',
-        code: 'module_generated_stale',
-        message: `${result.moduleId}: ${generated.length} generated asset(s) do not match the installed module — a deploy would ship the wrong bytes`,
-        details: generated.map((v) => `  • ${v.path}`).join('\n'),
-        remediation: `celilo module generate ${result.moduleId}`,
-        actionable: true,
+        // No command restamps a baseline. `module update` takes a module
+        // source PATH, not an id (celilo#1308: prescribing it with the id
+        // named an argument form that does not exist), and `module upgrade`
+        // deploys the registry version instead. Say so rather than name a
+        // command that cannot run.
+        remediation: 'no automatic remediation: the baseline predates version stamping',
+        actionable: false,
         subject: result.moduleId,
       });
     }

package/src/services/audit/types.ts

@@ -45,7 +45,8 @@ export type DriftCategory =
   | 'trusted_sources'
   | 'interface_classification'
   | 'module_integrity'
-  | 'detect_without_converge';
+  | 'detect_without_converge'
+  | 'jail_exemptions';
 
 /**
  * `unmeasured` is a check that could not reach its subject

package/src/services/backup-age-agreement.test.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { backupStorages, backups, modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { loadBackupAuditInfo } from './audit/backup-source';
 import { findBackupEligibleModules } from './backup-create';
 import { loadBackupHistory } from './backup-metadata';
@@ -79,7 +80,7 @@ describe('backup age: the run path and the audit path read the same column', ()
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/services/backup-create.ts

@@ -35,6 +35,7 @@ import {
 import type { Cadence } from './cadence';
 import { materializeCrossModuleRoot, moduleHasCrossModuleRead } from './cross-module-read';
 import { getModuleSystems } from './deployed-systems';
+import { listMachines } from './machine-pool';
 import { parseStoredConfigValue } from './module-config';
 import {
   completeOperation,
@@ -367,6 +368,14 @@ export async function createModuleBackup(
 
       const staged = stageSystemState(join(tempDir, 'system-state'));
       hookInputs.system_state_root = staged.root;
+
+      // The machine inventory rides the same privilege. on_backup used to
+      // shell `celilo machine list --json` for this, which the hook jail kills
+      // (no celilo binary, celilo#1225) and which never worked before that:
+      // the CLI had no --json flag, so the hook's JSON.parse failed and its
+      // catch wrote [] into every envelope. listMachines() is the same read
+      // the CLI performs, offered as staged data instead of a spawn.
+      hookInputs.machine_pool = JSON.stringify(await listMachines());
       if (!staged.masterKeyStaged) {
         logger.warn(
           `master.key not found at ${getMasterKeyPath()} — secrets in the DB snapshot will be unreadable on restore.`,

package/src/services/backup-envelope-roundtrip.test.ts

@@ -32,6 +32,7 @@ import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { backups, systemConfig } from '../db/schema';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { decryptFileToFile, encryptFileToFile } from './backup-cipher';
 import { createSystemStateBackup } from './backup-create';
 import { MANIFEST_SCHEMA_VERSION, buildManifest, parseManifest } from './backup-manifest';
@@ -64,8 +65,8 @@ describe('backup envelope round-trip', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_MASTER_KEY_PATH;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/backup-in-flight-refusal.test.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { backups, moduleOperations } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { createModuleBackup, createSystemStateBackup } from './backup-create';
 import { restoreModuleBackup, restoreSystemStateBackup } from './backup-restore';
 import { InFlightError } from './module-operations';
@@ -34,8 +35,8 @@ describe('backup/restore in-flight refusal', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_MASTER_KEY_PATH;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/build-bus/hook-dispatch-mgmt.test.ts

@@ -155,3 +155,51 @@ exit 0
     expect(results).toEqual([]);
   });
 });
+
+/**
+ * The durable outcome record (celilo#1304): every dispatched run lands in
+ * the `build_bus_hook_runs` ledger via the injectable recordRun. Without it
+ * a failed self-update existed only as daemon console output, which no
+ * surface reads.
+ */
+describe('hook-dispatcher outcome record', () => {
+  test('a failing script records exit code, stderr tail, and the event identity', async () => {
+    const failDir = mkdtempSync(join(tmpdir(), 'hook-record-test-'));
+    const scriptPath = join(failDir, 'fail.sh');
+    writeFileSync(scriptPath, '#!/usr/bin/env bash\necho "boom" >&2\nexit 7\n');
+    chmodSync(scriptPath, 0o755);
+
+    const recorded: Array<{
+      event: PublishEvent;
+      result: { exitCode: number | null; stderr: string };
+    }> = [];
+    const dispatcher = await startHookDispatcher({
+      loadModules: () => [
+        {
+          moduleId: 'celilo-mgmt',
+          sourcePath: failDir,
+          hooks: [
+            {
+              name: 'self-update-celilo-cli',
+              match: { registry: 'npm', tag: 'latest', package_pattern: '@celilo/cli' },
+              script: 'fail.sh',
+            },
+          ],
+        },
+      ],
+      recordRun: (event, result) => recorded.push({ event, result }),
+    });
+
+    await dispatcher.handleEvent(
+      buildEvent({ package: { name: '@celilo/cli', version: '2.2.1' } }),
+    );
+    await dispatcher.stop();
+    rmSync(failDir, { recursive: true, force: true });
+
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].event.eventId).toBe('evt-1');
+    expect(recorded[0].event.package.name).toBe('@celilo/cli');
+    expect(recorded[0].result.exitCode).toBe(7);
+    expect(recorded[0].result.stderr).toContain('boom');
+  });
+});

package/src/services/build-bus/hook-dispatcher.ts

@@ -20,7 +20,7 @@ import { join } from 'node:path';
 import type { PublishEvent } from '@celilo/event-bus/build-bus';
 import { parse as parseYaml } from 'yaml';
 import { getDb } from '../../db/client';
-import { modules } from '../../db/schema';
+import { buildBusHookRuns, modules } from '../../db/schema';
 import {
   type HookRunResult,
   type ModuleHookContext,
@@ -43,12 +43,59 @@ export interface HookDispatcherOptions {
    * modules table.
    */
   loadModules?: () => ModuleHookContext[];
+  /**
+   * Override the durable outcome record. The production default writes one
+   * `build_bus_hook_runs` row per run — without it a failed self-update
+   * exists only as daemon console output, which no surface reads
+   * (celilo#1304). Tests inject a capture to stay DB-free.
+   */
+  recordRun?: (event: PublishEvent, result: HookRunResult) => void;
+}
+
+/** Bound on stdout/stderr tails so one chatty hook cannot bloat the ledger. */
+const TAIL_CHARS = 2000;
+
+function tail(s: string): string {
+  return s.length > TAIL_CHARS ? s.slice(-TAIL_CHARS) : s;
+}
+
+/**
+ * The production outcome record: one `build_bus_hook_runs` row per run.
+ * Throwing here would 500 nothing (the webhook already succeeded) but
+ * would kill dispatch of later plans, so a record failure is logged and
+ * swallowed — the console outcome lines below remain the fallback signal.
+ */
+function recordHookRun(event: PublishEvent, result: HookRunResult): void {
+  try {
+    getDb()
+      .insert(buildBusHookRuns)
+      .values({
+        eventId: event.eventId,
+        packageName: event.package.name,
+        packageVersion: event.package.version,
+        tag: event.tag,
+        moduleId: result.module,
+        hookName: result.hookName,
+        scriptPath: result.scriptPath,
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        durationMs: result.durationMs,
+        stdoutTail: result.stdout ? tail(result.stdout) : null,
+        stderrTail: result.stderr ? tail(result.stderr) : null,
+      })
+      .run();
+  } catch (err) {
+    console.warn(
+      `[build-bus] could not record hook run outcome: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
 }
 
 export async function startHookDispatcher(
   opts: HookDispatcherOptions = {},
 ): Promise<HookDispatcher> {
   const loadModules = opts.loadModules ?? loadInstalledModulesWithHooks;
+  const recordRun = opts.recordRun ?? recordHookRun;
 
   return {
     async handleEvent(event) {
@@ -66,6 +113,7 @@ export async function startHookDispatcher(
           `[build-bus] ${event.package.name}@${event.package.version} → ${plan.module.moduleId} (${plan.hook.name ?? plan.hook.script})`,
         );
         const result = await runHookDispatch(plan);
+        recordRun(event, result);
         results.push(result);
         if (result.exitCode === 0) {
           console.log(`  ✓ exit 0 in ${result.durationMs}ms`);

package/src/services/bus-ensure-flow.test.ts

@@ -27,6 +27,7 @@ import { moduleConfigs, modules, secrets } from '../db/schema';
 import type { Ensure } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { resetTestDbPath } from '../test-utils/db-path';
 import type { EnsureRequiredPayload } from './bus-interview';
 import { interviewForEnsureInputs, writeModuleSecretKey } from './config-interview';
 
@@ -174,8 +175,8 @@ describe('bus-mediated interviewForEnsureInputs', () => {
   afterEach(() => {
     bus.close();
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.EVENT_BUS_DB = undefined;
+    resetTestDbPath();
+    delete process.env.EVENT_BUS_DB;
   });
 
   test('mixed inputs: array applied deterministic, config + secret routed through bus', async () => {

package/src/services/bus-interview-park.test.ts

@@ -26,6 +26,7 @@ import { type Bus, type BusEvent, defineEvents, openBus } from '@celilo/event-bu
 import { handleModuleUpdate } from '../cli/commands/module-update';
 import { getDb } from '../db/client';
 import { modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { RESPONDER_PROBE_EVENT } from './responder-probe';
 
 const NO_SCHEMAS = defineEvents({});
@@ -91,9 +92,9 @@ beforeEach(() => {
 afterEach(() => {
   server.stop(true);
   rmSync(dir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
-  process.env.CELILO_ORIGINAL_CWD = undefined;
-  process.env.EVENT_BUS_DB = undefined;
+  resetTestDbPath();
+  delete process.env.CELILO_ORIGINAL_CWD;
+  delete process.env.EVENT_BUS_DB;
 });
 
 test('a command parks on an unanswered interview, then resumes with an answer given later', async () => {

package/src/services/bus-interview.test.ts

@@ -24,7 +24,7 @@ describe('busInterview', () => {
     process.env.EVENT_BUS_DB = dbPath;
   });
   afterEach(() => {
-    if (origEnv === undefined) process.env.EVENT_BUS_DB = undefined;
+    if (origEnv === undefined) delete process.env.EVENT_BUS_DB;
     else process.env.EVENT_BUS_DB = origEnv;
     try {
       rmSync(dir, { recursive: true, force: true });
@@ -156,7 +156,7 @@ describe('multi-select payload roundtrip', () => {
     process.env.EVENT_BUS_DB = dbPath;
   });
   afterEach(() => {
-    if (origEnv === undefined) process.env.EVENT_BUS_DB = undefined;
+    if (origEnv === undefined) delete process.env.EVENT_BUS_DB;
     else process.env.EVENT_BUS_DB = origEnv;
     try {
       rmSync(dir, { recursive: true, force: true });

package/src/services/bus-secret-flow.test.ts

@@ -21,6 +21,7 @@ import { type Bus, defineEvents, openBus } from '@celilo/event-bus';
 import { type DbClient, getDb } from '../db/client';
 import { modules } from '../db/schema';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { resetTestDbPath } from '../test-utils/db-path';
 import type { SecretRequiredPayload } from './bus-interview';
 import {
   interviewForMissingSecrets,
@@ -154,8 +155,8 @@ describe('bus-mediated interviewForMissingSecrets', () => {
   afterEach(() => {
     bus.close();
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.EVENT_BUS_DB = undefined;
+    resetTestDbPath();
+    delete process.env.EVENT_BUS_DB;
   });
 
   test('user_provided: emits secret.required, responder writes, value lands in store', async () => {

package/src/services/capability-table-rows.test.ts

@@ -20,6 +20,7 @@ import { allDeclaredTables } from '@celilo/capabilities';
 import type { DbClient } from '../db/client';
 import { dnsInternalRecords, modules, portForwards, trustedSources, webRoutes } from '../db/schema';
 import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { deleteClaimedRows, planClaimedRowDeletion } from './capability-table-rows';
 
 const FW = '192.168.0.254';
@@ -74,7 +75,7 @@ describe('deleteClaimedRows', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/services/celilo-events.test.ts

@@ -29,7 +29,7 @@ describe('celilo lifecycle events', () => {
     process.env.EVENT_BUS_DB = dbPath;
   });
   afterEach(() => {
-    process.env.EVENT_BUS_DB = undefined;
+    delete process.env.EVENT_BUS_DB;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/celilo-mgmt-hooks.test.ts

@@ -11,6 +11,14 @@ import type { HookContext } from '@celilo/capabilities';
 // runnable from the apps/celilo working dir.
 const HOOK_DIR = join(import.meta.dirname, '../../../../modules/celilo-mgmt/scripts');
 
+// on_backup reads its machine-pool snapshot from the context input the
+// framework stages (backup-create.ts, from listMachines()). These tests
+// inject a JSON string so the snapshot is deterministic on every host. The
+// pre-staging version of this hook shelled `celilo machine list --json` and
+// these tests had to inject a runner stub to avoid depending on the installed
+// CLI's age (celilo#1333); the staged input made that seam unnecessary.
+const STUB_MACHINE_POOL = [{ hostname: 'stub-machine', zone: 'dmz' }];
+
 interface BackupHookOutput {
   artifact_count: number;
   size_bytes: number;
@@ -116,6 +124,7 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
         backup_dir: backupDir,
         cross_module_root: crossModuleRoot,
         system_state_root: systemStateRoot,
+        machine_pool: JSON.stringify(STUB_MACHINE_POOL),
       }),
     )) as BackupHookOutput;
 
@@ -135,7 +144,6 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     expect(result.artifact_count).toBeGreaterThan(0);
     expect(result.size_bytes).toBeGreaterThan(0);
   });
-
   it('refuses when the framework did not stage celilo state', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
 
@@ -148,24 +156,34 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     ).rejects.toThrow(/system_state_root was not provided/);
   });
 
-  it('machine-pool.json is valid JSON (array)', async () => {
+  it('machine-pool.json is the staged snapshot (valid JSON array)', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
     await hook(
       buildContext({
         backup_dir: backupDir,
         cross_module_root: crossModuleRoot,
         system_state_root: systemStateRoot,
+        machine_pool: JSON.stringify(STUB_MACHINE_POOL),
       }),
     );
 
-    const machinePool = JSON.parse(readFileSync(join(backupDir, 'machine-pool.json'), 'utf-8'));
-    expect(Array.isArray(machinePool)).toBe(true);
+    // Content, not just shape. A bare Array.isArray also passes when the
+    // hook swallowed a snapshot failure and wrote an empty pool, which is
+    // exactly the failure mode this stub exists to rule out.
+    const machinePool: unknown = JSON.parse(
+      readFileSync(join(backupDir, 'machine-pool.json'), 'utf-8'),
+    );
+    expect(machinePool).toEqual(STUB_MACHINE_POOL);
   });
 
   it('proceeds (with a warning) when cross_module_root is missing', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
     const result = (await hook(
-      buildContext({ backup_dir: backupDir, system_state_root: systemStateRoot }),
+      buildContext({
+        backup_dir: backupDir,
+        system_state_root: systemStateRoot,
+        machine_pool: JSON.stringify(STUB_MACHINE_POOL),
+      }),
     )) as BackupHookOutput;
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);

package/src/services/consumer-cleanup.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../db/client';
 import type { ModuleManifest } from '../manifest/schema';
 import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   type CleanupTarget,
   type ProviderRow,
@@ -216,7 +217,7 @@ describe('runConsumerCleanup — the paused skip is reported, not silent', () =>
   });
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 
@@ -285,7 +286,7 @@ describe('runConsumerCleanup — dispatch', () => {
   });
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     rmSync(dir, { recursive: true, force: true });
   });
 

package/src/services/container-service.test.ts

@@ -10,6 +10,7 @@ import { eq } from 'drizzle-orm';
 import { closeDb, createDbClient } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { containerServices } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   addContainerService,
   getContainerService,
@@ -53,8 +54,8 @@ describe('container-service', () => {
     }
 
     // Clear environment variables
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    resetTestDbPath();
+    delete process.env.CELILO_MASTER_KEY_PATH;
   });
 
   describe('addContainerService', () => {

package/src/services/control-plane-bootstrap.test.ts

@@ -17,6 +17,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
 import { capabilities, modules, systemConfig } from '../db/schema';
 import { setupTestDatabaseAt } from '../test-utils/database';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   type ControlPlaneBootstrapOptions,
   bootstrapControlPlane,
@@ -58,7 +59,7 @@ describe('bootstrapControlPlane', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {