@celilo/cli 2.1.0 → 2.2.1

package/src/services/alerting/run-monitor.test.ts

@@ -6,6 +6,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Monitor, alerts, monitorRuns, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import type { HealthCheckResult } from '../health-runner';
 import { HOOK_JAIL_CHECK, type HookJailState } from './hook-jail';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
@@ -71,7 +72,7 @@ describe('runOneMonitor', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/run-monitor.ts

@@ -47,7 +47,7 @@ export interface MonitorRunOutcomeSummary {
   monitorId: string;
   outcome: 'success' | 'error';
   errorMessage?: string;
-  failingKeyCount: number;
+  failingKeys: FailingKey[];
   createdIds: string[];
   resolvedIds: string[];
 }
@@ -186,7 +186,7 @@ export async function runOneMonitor(
     monitorId: monitor.id,
     outcome: product.outcome,
     errorMessage: product.errorMessage,
-    failingKeyCount: product.failingKeys.length,
+    failingKeys: product.failingKeys,
     createdIds,
     resolvedIds,
   };

package/src/services/alerting/store.test.ts

@@ -6,6 +6,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { alerts, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { moduleAlertKey, moduleCheckAlertKey } from './keys';
 import type { ReconcileAction } from './reconcile';
 import {
@@ -55,7 +56,7 @@ describe('alert store', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/sweep-runner.test.ts

@@ -6,6 +6,7 @@ import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type Alert, type Monitor, alerts, modules, monitors } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import type { HealthCheckResult } from '../health-runner';
 import { deleteModuleConfig, upsertModuleConfig } from '../module-config';
 import { HEALTH_CHECK_INTERVAL_CONFIG_KEY, reconcileModuleWatchState } from './health-cadence';
@@ -99,7 +100,7 @@ describe('runSweep', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/alerting/tokens.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import type { DbClient } from '../../db/client';
 import { modules, people, routes } from '../../db/schema';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   consumeDelivery,
   deliveriesForAlert,
@@ -75,7 +76,7 @@ describe('delivery records', () => {
 
   afterEach(() => {
     db.$client.close();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/aspect-approvals.test.ts

@@ -6,6 +6,7 @@ import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
 import type { BaseModuleAspect } from '../manifest/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   checkAspectApproval,
   computeAspectScopeHash,
@@ -44,7 +45,7 @@ describe('aspect-approvals', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/aspect-reconcile.test.ts

@@ -20,6 +20,7 @@ import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { type ModuleState, modules } from '../db/schema';
 import type { BaseModuleAspect } from '../manifest/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   computeAspectScopeHash,
   recordAspectApproval,
@@ -159,7 +160,7 @@ describe('reconcileAspectsForSystems', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -310,7 +311,7 @@ describe('planAspectFanOut onlyHostnames', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -352,7 +353,7 @@ describe('verifyAspectCoverage', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/services/aspect-runner.test.ts

@@ -20,6 +20,7 @@ import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
 import type { BaseModuleAspect, ModuleManifest } from '../manifest/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import {
   computeAspectScopeHash,
   findAspectApproval,
@@ -109,7 +110,7 @@ describe('aspect-runner', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

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

@@ -82,27 +82,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: [

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

@@ -58,20 +58,6 @@ export function auditModuleIntegrity(deps: ModuleIntegrityAuditDeps): DriftFindi
       });
     }
 
-    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,
-        subject: result.moduleId,
-      });
-    }
-
     // File differences are only meaningful once the baseline is trustworthy.
     // Reporting them under a stale baseline is what made `module verify`
     // unreadable: 72 violations across two healthy modules, nearly all of them

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

@@ -6,15 +6,16 @@
 import { copyFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { create as tarCreate } from 'tar';
 import { getDbPath, getMasterKeyPath } from '../config/paths';
 import { getDb } from '../db/client';
 import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { createConsoleLogger } from '../hooks/logger';
 import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
-import { shellEscape } from '../utils/shell';
 import { encryptFileToFile } from './backup-cipher';
 import { buildManifest } from './backup-manifest';
 import {
@@ -153,8 +154,7 @@ export async function createSystemStateBackup(
     // Tar the envelope. Operator can re-extract a backup file manually
     // for diagnostics: `age -d -p file.backup | tar -t` shows the contents.
     const tarPath = join(tempDir, 'envelope.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)} .`);
+    await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts. The plaintext is
     // never held in memory, so a large fleet DB can't OOM the snapshot.
@@ -401,6 +401,7 @@ export async function createModuleBackup(
         debug: false,
         systems: getModuleSystems(moduleId, db),
         remoteAccess: remoteAccessPolicy(moduleId, db),
+        hookStores: () => createHookStores(db, moduleId),
       },
     );
 
@@ -434,8 +435,7 @@ export async function createModuleBackup(
 
     // Tar the envelope (manifest.json + data/).
     const tarPath = join(tempDir, 'envelope.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)} .`);
+    await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts. Module artifacts run
     // to hundreds of MB (forgejo's are ~774 MB); holding one in memory is
@@ -566,6 +566,7 @@ export async function importModuleBackup(
           debug: false,
           systems: getModuleSystems(moduleId, db),
           remoteAccess: remoteAccessPolicy(moduleId, db),
+          hookStores: () => createHookStores(db, moduleId),
         },
       );
 
@@ -590,8 +591,7 @@ export async function importModuleBackup(
 
     // Tar the artifacts
     const tarPath = join(tempDir, 'backup.tar');
-    const { execSync } = await import('node:child_process');
-    execSync(`tar -cf ${shellEscape(tarPath)} -C ${shellEscape(artifactDir)} .`);
+    await tarCreate({ file: tarPath, cwd: artifactDir }, ['.']);
 
     // Encrypt the tar, streamed — see backup-cipher.ts.
     const masterKey = await getOrCreateMasterKey();

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

@@ -16,16 +16,26 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { getDbPath } from '../config/paths';
 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, parseManifest } from './backup-manifest';
+import { MANIFEST_SCHEMA_VERSION, buildManifest, parseManifest } from './backup-manifest';
 import { restoreSystemStateBackup } from './backup-restore';
 import { addBackupStorage, setDefaultBackupStorage, verifyBackupStorage } from './backup-storage';
 
@@ -55,7 +65,7 @@ describe('backup envelope round-trip', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     try {
       rmSync(dir, { recursive: true, force: true });
@@ -121,6 +131,40 @@ describe('backup envelope round-trip', () => {
     expect(restoreResult.error).toBeUndefined();
   });
 
+  it('an archive written by SYSTEM tar (the pre-library producer) restores via the tar library', async () => {
+    // The tar library replaced `tar -cf/-xf` shell-outs (celilo#1235). A
+    // self-consistent round-trip cannot detect a layout change, because the
+    // new extract sites would happily read back the new layout. So this test
+    // builds the envelope with the SYSTEM tar — byte-for-byte the command the
+    // old code ran — and restores it with the current code, proving a backup
+    // taken BEFORE the change still restores after it.
+    const db = getDb();
+    db.insert(systemConfig).values({ key: 'pre-change-sentinel', value: 'before-backup' }).run();
+
+    // Take a real backup to get a valid row + storage location, then swap the
+    // artifact for one produced by the system tar the old code shelled out to.
+    const result = await createSystemStateBackup();
+    expect(result.success).toBe(true);
+    const artifactPath = join(storageDir, 'celilo-backups', result.storagePath as string);
+
+    const envelopeDir = join(dir, 'pre-change-envelope');
+    mkdirSync(envelopeDir, { recursive: true });
+    copyFileSync(getDbPath(), join(envelopeDir, 'celilo.db'));
+    writeFileSync(
+      join(envelopeDir, 'manifest.json'),
+      JSON.stringify(buildManifest({ kind: 'system' }), null, 2),
+    );
+    const tarPath = join(dir, 'pre-change.tar');
+    execSync(`tar -cf '${tarPath}' -C '${envelopeDir}' .`);
+    const masterKey = await getOrCreateMasterKey();
+    await encryptFileToFile(tarPath, artifactPath, masterKey);
+
+    const backupRow = db.select().from(backups).all()[0];
+    const restoreResult = await restoreSystemStateBackup(backupRow);
+    expect(restoreResult.success).toBe(true);
+    expect(restoreResult.error).toBeUndefined();
+  });
+
   it('system restore refuses an artifact with a wrong manifest kind', async () => {
     // Create a valid backup, then poison the manifest by re-packing.
     const result = await createSystemStateBackup();

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,7 +35,7 @@ describe('backup/restore in-flight refusal', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.CELILO_MASTER_KEY_PATH = undefined;
     try {
       rmSync(dir, { recursive: true, force: true });

package/src/services/backup-restore.ts

@@ -4,21 +4,21 @@
  * For system state backups, restores the Celilo database.
  */
 
-import { execSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { extract as tarExtract } from 'tar';
 import { getDbPath } from '../config/paths';
 import { closeDb, getDb } from '../db/client';
 import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
 import type { Backup } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
+import { createHookStores } from '../hooks/hook-store';
 import { createConsoleLogger } from '../hooks/logger';
 import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
-import { shellEscape } from '../utils/shell';
 import { decryptFileToFile } from './backup-cipher';
 import { assertCompatibleSchema, parseManifest } from './backup-manifest';
 import { createStorageProvider } from './backup-storage';
@@ -70,7 +70,7 @@ export async function restoreSystemStateBackup(backup: Backup): Promise<RestoreR
     mkdirSync(envelopeDir, { recursive: true });
     const tarPath = join(tempDir, 'envelope.tar');
     await decryptFileToFile(encryptedPath, tarPath, masterKey);
-    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
+    await tarExtract({ file: tarPath, cwd: envelopeDir });
 
     // Read + validate manifest BEFORE touching the live DB. An
     // incompatible artifact must not get past this point.
@@ -180,6 +180,9 @@ export async function restoreModuleBackup(
   if (!backup.moduleId) {
     return { success: false, error: 'Backup has no associated module' };
   }
+  // Captured because the narrowing above does not survive into the hookStores
+  // callback below, where TypeScript widens the parameter back to string|null.
+  const moduleId = backup.moduleId;
 
   const db = getDb();
   const mod = db.select().from(modules).where(eq(modules.id, backup.moduleId)).get();
@@ -221,7 +224,7 @@ export async function restoreModuleBackup(
     const masterKey = await getOrCreateMasterKey();
     const tarPath = join(tempDir, 'envelope.tar');
     await decryptFileToFile(encryptedPath, tarPath, masterKey);
-    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
+    await tarExtract({ file: tarPath, cwd: envelopeDir });
 
     // Read + validate envelope manifest BEFORE invoking the hook.
     const manifestPath = join(envelopeDir, 'manifest.json');
@@ -290,6 +293,7 @@ export async function restoreModuleBackup(
         debug: false,
         systems: getModuleSystems(backup.moduleId, db),
         remoteAccess: remoteAccessPolicy(backup.moduleId, db),
+        hookStores: () => createHookStores(db, moduleId),
       },
     );
 

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,7 +175,7 @@ describe('bus-mediated interviewForEnsureInputs', () => {
   afterEach(() => {
     bus.close();
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.EVENT_BUS_DB = undefined;
   });
 

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,7 +92,7 @@ beforeEach(() => {
 afterEach(() => {
   server.stop(true);
   rmSync(dir, { recursive: true, force: true });
-  process.env.CELILO_DB_PATH = undefined;
+  resetTestDbPath();
   process.env.CELILO_ORIGINAL_CWD = undefined;
   process.env.EVENT_BUS_DB = undefined;
 });

package/src/services/bus-interview.ts

@@ -16,7 +16,7 @@
 
 import { type Bus, defineEvents, openBus } from '@celilo/event-bus';
 import { getEventBusPath } from '../config/paths';
-import { InterviewAbandonedError } from './interview-errors';
+import { InterviewAbandonedError, InterviewUnansweredError } from './interview-errors';
 import { ensureResponderForInterview } from './responder-probe';
 
 const NO_SCHEMAS = defineEvents({});
@@ -271,17 +271,26 @@ export async function busInterview<TReply>(
   type: string,
   payload: object,
   ownerBus?: Bus,
+  timeoutMs = 0,
 ): Promise<TReply> {
   const ownsBus = !ownerBus;
   const bus: Bus = ownerBus ?? openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
   try {
     const replies = await bus.query(type as never, payload as never, {
-      timeoutMs: 0, // wait forever — race semantics, no timeout
+      timeoutMs, // 0 = wait forever — race semantics, no timeout
       pollIntervalMs: 250,
       expect: 'first',
     });
     if (replies.length === 0) {
-      throw new Error(`bus-interview: ${type} returned no reply`);
+      // Typed so a bounded caller can distinguish "nobody answered in time"
+      // from a decline. With the default 0 this is unreachable (the query
+      // waits forever), but keeping it typed costs nothing.
+      throw new InterviewUnansweredError(
+        type,
+        timeoutMs > 0
+          ? `No reply within ${timeoutMs}ms (${type})`
+          : `bus-interview: ${type} returned no reply`,
+      );
     }
     return replies[0].payload as unknown as TReply;
   } finally {
@@ -305,9 +314,10 @@ export async function busInterviewGuarded<TReply>(
   type: string,
   payload: object,
   ownerBus?: Bus,
+  timeoutMs = 0,
 ): Promise<TReply> {
   await ensureResponderForInterview(type);
-  return busInterview<TReply>(type, payload, ownerBus);
+  return busInterview<TReply>(type, payload, ownerBus, timeoutMs);
 }
 
 /**
@@ -326,9 +336,10 @@ export async function busInterviewGuarded<TReply>(
 export async function askInterview(
   payload: InterviewRequiredPayload,
   ownerBus?: Bus,
+  timeoutMs = 0,
 ): Promise<unknown> {
   const type = EVENT_TYPES.interviewRequired(payload.scope, payload.key);
-  const reply = await busInterviewGuarded<InterviewReply>(type, payload, ownerBus);
+  const reply = await busInterviewGuarded<InterviewReply>(type, payload, ownerBus, timeoutMs);
   if (reply.abandoned) throw new InterviewAbandonedError(type, reply.abandoned.reason);
   return reply.value;
 }
@@ -463,16 +474,28 @@ export async function askConfirm(opts: {
   message: string;
   defaultValue?: boolean;
   description?: string;
+  /**
+   * Bound the wait for a reply. 0 (the default) waits forever, which is
+   * right when the operator IS the responder (TTY). A headless caller whose
+   * responder may be attached but not staged for this question passes a
+   * finite bound so it skips instead of hanging until the suite budget
+   * kills it (module-orchestrator-primitives design.md D5).
+   */
+  timeoutMs?: number;
 }): Promise<boolean> {
-  const value = await askInterview({
-    scope: opts.scope,
-    key: opts.key,
-    kind: 'confirm',
-    message: opts.message,
-    required: true,
-    defaultValue: opts.defaultValue === undefined ? undefined : String(opts.defaultValue),
-    description: opts.description,
-  });
+  const value = await askInterview(
+    {
+      scope: opts.scope,
+      key: opts.key,
+      kind: 'confirm',
+      message: opts.message,
+      required: true,
+      defaultValue: opts.defaultValue === undefined ? undefined : String(opts.defaultValue),
+      description: opts.description,
+    },
+    undefined,
+    opts.timeoutMs,
+  );
   if (typeof value !== 'boolean') {
     throw new Error(
       `askConfirm(${opts.scope}.${opts.key}): expected a boolean reply, got ${typeof value}`,

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,7 +155,7 @@ describe('bus-mediated interviewForMissingSecrets', () => {
   afterEach(() => {
     bus.close();
     rmSync(tempDir, { recursive: true, force: true });
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     process.env.EVENT_BUS_DB = undefined;
   });
 

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/config-provenance.ts

@@ -74,6 +74,8 @@ export function describeDerivedSource(variable: VariableDeclare): string {
       return 'from the infrastructure celilo selected for this module';
     case 'terraform':
       return 'from a Terraform output, at deploy time';
+    case 'hook':
+      return `by the module's own hooks at runtime (via context.config.set), and never by an operator`;
     default:
       return `computed by celilo (source: ${variable.source})`;
   }
@@ -98,6 +100,8 @@ export function explainNotSettable(moduleId: string, variable: VariableDeclare):
       return `${header}\n${origin}\n  • node placement: set the service default for NEW deploys (celilo service reconfigure); move an existing container with 'celilo proxmox migrate'.\n  • vmid / IP: auto-allocated by IPAM.`;
     case 'terraform':
       return `${header}\n${origin}\n  • It is read back from Terraform outputs after the deploy creates the resource.`;
+    case 'hook':
+      return `${header}\n${origin}\n  • It is written by the module's own hook via context.config.set, not by any operator path.`;
     default:
       return `${header}\n${origin}`;
   }