@celilo/cli 2.1.0 → 2.2.1

package/src/cli/commands/monitor.ts

@@ -17,6 +17,7 @@ import {
   runBuiltinCheckForMonitor,
 } from '../../services/alerting/builtin-source';
 import { loadModuleCoverage } from '../../services/alerting/coverage-source';
+import { renderMonitorRunMessage } from '../../services/alerting/format';
 import { loadModuleHealthCadences } from '../../services/alerting/health-cadence';
 import { HEALTH_COVERAGE_CHECK } from '../../services/alerting/health-coverage';
 import { HOOK_JAIL_CHECK } from '../../services/alerting/hook-jail';
@@ -198,16 +199,7 @@ async function handleRun(args: string[]): Promise<CommandResult> {
   const summary = await runOneMonitor(db, monitor, buildDeps());
   promoteReadyAlerts(db, new Date());
 
-  if (summary.outcome === 'error') {
-    return {
-      success: true,
-      message: `${target}: check could not run — ${summary.errorMessage ?? 'unknown error'}`,
-    };
-  }
-  return {
-    success: true,
-    message: `${target}: ${summary.failingKeyCount} failing, ${summary.resolvedIds.length} resolved`,
-  };
+  return { success: true, message: renderMonitorRunMessage(target, summary) };
 }
 
 function handleToggle(args: string[], enabled: boolean): CommandResult {

package/src/cli/commands/notify-config.test.ts

@@ -22,10 +22,10 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../../db/client';
 import { createPerson } from '../../services/alerting/people';
 import { setupTestDatabaseAt } from '../../test-utils/database';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handlePerson } from './notify-config';
 
 let dir: string;
-const previousDbPath = process.env.CELILO_DB_PATH;
 
 beforeEach(async () => {
   dir = mkdtempSync(join(tmpdir(), 'celilo-person-'));
@@ -39,8 +39,10 @@ beforeEach(async () => {
 
 afterEach(() => {
   closeDb();
-  if (previousDbPath === undefined) delete process.env.CELILO_DB_PATH;
-  else process.env.CELILO_DB_PATH = previousDbPath;
+  // Reset to the scratch path, never restore: the saved value may be another
+  // suite's temp database or unset — which sends the next var-less reader to
+  // the operator's real celilo.db (celilo#1315).
+  resetTestDbPath();
   rmSync(dir, { recursive: true, force: true });
 });
 

package/src/cli/commands/registry-owner.test.ts

@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import {
   handleRegistryOwnerList,
   handleRegistryOwnerSet,
@@ -45,7 +46,7 @@ describe('registry owner commands', () => {
     fetchSpy.mockRestore();
     closeDb();
     process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     if (existsSync(dataDir)) await rm(dataDir, { recursive: true, force: true });
   });
 

package/src/cli/commands/registry-token.test.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import { CrossModuleDataManager } from '../../services/cross-module-data-manager';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleRegistryTokenAdd, handleRegistryTokenRm } from './registry-token';
 
 /** Read back the stored publish_tokens list via the production read path. */
@@ -50,7 +51,7 @@ describe('registry token add/rm (F2 clobber fix)', () => {
   afterEach(async () => {
     closeDb();
     process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    resetTestDbPath();
     if (existsSync(dataDir)) {
       await rm(dataDir, { recursive: true, force: true });
     }

package/src/cli/commands/restore.ts

@@ -82,15 +82,25 @@ export async function handleRestore(
 
   // Run Drizzle migrations on the restored DB so a backup from an
   // older celilo opens cleanly. No-op if the DB schema is already
-  // current. Best-effort: if migrations fail (e.g., a destructive
-  // backward migration would be needed), surface the error but the
-  // restore itself already landed.
+  // current. A failure here FAILS the restore (celilo#1269): the swap
+  // has landed, so the box holds restored state it cannot yet open
+  // safely, and reporting success over an unmigrated database trains
+  // operators to ignore the one warning that matters on a recovery
+  // path. The error names the command that retries the migration and
+  // the check that says whether the schema is complete.
+
+  let migrationError: string | undefined;
   try {
     await migrateRestoredDb();
   } catch (err) {
-    log.warn(
-      `Restore complete but migrations failed: ${err instanceof Error ? err.message : String(err)}. The restored DB may need manual migration.`,
-    );
+    migrationError = err instanceof Error ? err.message : String(err);
+  }
+
+  if (migrationError) {
+    return {
+      success: false,
+      error: `Restore landed but migrations failed: ${migrationError}. The database was restored to this box, but its schema may not match this celilo build and celilo commands may fail against it. Run \`celilo system migrate\` to retry the migrations, and \`celilo system doctor\` to check whether the schema is complete before using the box.`,
+    };
   }
 
   // Re-register event-bus subscriptions from the restored modules' manifests.

package/src/cli/commands/system-apply-config-equivalence.test.ts

@@ -30,24 +30,22 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { getDb } from '../../db/client';
 import { loadExistingConfiguration } from '../../services/system-init';
+import { resetTestDbPath } from '../../test-utils/db-path';
 import { handleSystemApplyConfig } from './system-apply-config';
 import { handleSystemInit } from './system-init';
 
 describe('system apply-config equivalence with system init --accept-defaults', () => {
   let tmpDir: string;
-  let savedDbPath: string | undefined;
 
   beforeEach(() => {
     tmpDir = mkdtempSync(join(tmpdir(), 'celilo-apply-config-test-'));
-    savedDbPath = process.env.CELILO_DB_PATH;
   });
 
   afterEach(() => {
-    if (savedDbPath !== undefined) {
-      process.env.CELILO_DB_PATH = savedDbPath;
-    } else {
-      process.env.CELILO_DB_PATH = undefined;
-    }
+    // Reset to the scratch path, never restore: the saved value may be
+    // another suite's temp database, or unset — which sends the next
+    // var-less reader to the operator's real celilo.db (celilo#1315).
+    resetTestDbPath();
     rmSync(tmpDir, { recursive: true, force: true });
   });
 

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

@@ -0,0 +1,148 @@
+/**
+ * Tests for the set-time interview gate on `system config set`
+ * (slice 3 of hook-jail-config-surface, design D5 + peba's --force addition).
+ *
+ * Writing `hooks.jail_policy off` is a fleet-wide security posture change, so
+ * the write asks first over the bus interview and only proceeds on an explicit
+ * confirm. `auto` and `required` write directly. `--force` skips the ask per
+ * the house flags.force convention.
+ *
+ * Isolation: CELILO_DB_PATH / CELILO_DATA_DIR / EVENT_BUS_DB are set before the
+ * SUT is imported, so nothing touches the production database or event bus.
+ * bun test runs non-TTY, so `withInterviewSession` starts no terminal responder
+ * and the interview guard probes the isolated bus — a successful direct write
+ * with no responder running is itself proof the command never asked.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+
+const testRoot = mkdtempSync(join(tmpdir(), 'celilo-jailgate-'));
+const busDbPath = join(testRoot, 'bus.db');
+process.env.CELILO_DB_PATH = join(testRoot, 'celilo.db');
+process.env.CELILO_DATA_DIR = join(testRoot, 'data');
+process.env.EVENT_BUS_DB = busDbPath;
+
+const { getDb, closeDb } = await import('../../db/client');
+const { systemConfig } = await import('../../db/schema');
+const { handleSystemConfigSet } = await import('./system-config');
+const { startProgrammaticResponder } = await import('../../services/programmatic-responder');
+
+const KEY = 'hooks.jail_policy';
+const CONFIRM_KEY = 'hooks-jail-policy.set-off';
+
+function storedJailPolicy(): string | undefined {
+  return getDb().select().from(systemConfig).where(eq(systemConfig.key, KEY)).get()?.value;
+}
+
+afterAll(() => {
+  closeDb();
+  rmSync(testRoot, { recursive: true, force: true });
+});
+
+describe('system config set — jail_policy value validation', () => {
+  beforeEach(() => {
+    getDb().delete(systemConfig).where(eq(systemConfig.key, KEY)).run();
+  });
+
+  test('a value outside the enum is refused and names the allowed values', async () => {
+    const result = await handleSystemConfigSet([KEY, 'alwayssafe']);
+
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('expected a refusal');
+    expect(result.error).toContain('auto');
+    expect(result.error).toContain('required');
+    expect(storedJailPolicy()).toBeUndefined();
+  });
+});
+
+describe('system config set — jail_policy values that never ask', () => {
+  beforeEach(() => {
+    getDb().delete(systemConfig).where(eq(systemConfig.key, KEY)).run();
+  });
+
+  test('auto writes directly with no responder listening', async () => {
+    const result = await handleSystemConfigSet([KEY, 'auto']);
+
+    expect(result.success).toBe(true);
+    expect(storedJailPolicy()).toBe('auto');
+  });
+
+  test('required writes directly with no responder listening', async () => {
+    const result = await handleSystemConfigSet([KEY, 'required']);
+
+    expect(result.success).toBe(true);
+    expect(storedJailPolicy()).toBe('required');
+  });
+});
+
+describe('system config set — the off interview gate', () => {
+  beforeEach(() => {
+    getDb().delete(systemConfig).where(eq(systemConfig.key, KEY)).run();
+  });
+
+  test('off fails fast with no responder listening and writes nothing', async () => {
+    let threw: unknown;
+    try {
+      await handleSystemConfigSet([KEY, 'off']);
+    } catch (error) {
+      threw = error;
+    }
+
+    expect(threw).toBeInstanceOf(Error);
+    expect(String((threw as Error).message)).toContain('No responder is listening');
+    expect(storedJailPolicy()).toBeUndefined();
+  });
+
+  test('off writes after a confirming reply over non-TTY, and the question was asked', async () => {
+    const responder = startProgrammaticResponder({
+      busDbPath,
+      db: getDb(),
+      onMissing: 'skip',
+      values: { interview: { [CONFIRM_KEY]: true } },
+    });
+    try {
+      const result = await handleSystemConfigSet([KEY, 'off']);
+
+      expect(result.success).toBe(true);
+      expect(storedJailPolicy()).toBe('off');
+
+      const asked = responder.seenInterviewPayloads();
+      expect(asked.length).toBe(1);
+      expect(asked[0].scope).toBe('hooks-jail-policy');
+      expect(asked[0].key).toBe('set-off');
+      expect(asked[0].message).toContain('unjailed');
+    } finally {
+      responder.close();
+    }
+  });
+
+  test('off is cancelled when the reply declines, and writes nothing', async () => {
+    const responder = startProgrammaticResponder({
+      busDbPath,
+      db: getDb(),
+      onMissing: 'skip',
+      values: { interview: { [CONFIRM_KEY]: false } },
+    });
+    try {
+      const result = await handleSystemConfigSet([KEY, 'off']);
+
+      expect(result.success).toBe(false);
+      if (result.success) throw new Error('expected cancellation');
+      expect(result.error).toBe('Cancelled by user');
+      expect(storedJailPolicy()).toBeUndefined();
+    } finally {
+      responder.close();
+    }
+  });
+
+  test('--force skips the ask and writes off with no responder listening', async () => {
+    const result = await handleSystemConfigSet([KEY, 'off'], { force: true });
+
+    expect(result.success).toBe(true);
+    expect(storedJailPolicy()).toBe('off');
+  });
+});

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

@@ -7,6 +7,7 @@ import { dirname, join } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { getDb } from '../../db/client';
 import { systemConfig } from '../../db/schema';
+import { askConfirm, withInterviewSession } from '../../services/bus-interview';
 import type { SystemConfigSchema } from '../../services/system-config-schema-types';
 import { validateKey, validateValue } from '../../services/system-config-validator';
 import { getArg, validateRequiredArgs } from '../parser';
@@ -47,7 +48,10 @@ function loadSchema(): SystemConfigSchema {
  * @param args - Command arguments
  * @returns Command result
  */
-export function handleSystemConfigSet(args: string[]): CommandResult {
+export async function handleSystemConfigSet(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
   // Validate arguments
   const error = validateRequiredArgs(args, 2);
   if (error) {
@@ -82,6 +86,27 @@ export function handleSystemConfigSet(args: string[]): CommandResult {
     return { success: false, error: valueValidation.error };
   }
 
+  // D5 of hook-jail-config-surface: turning jailing off fleet-wide is a security
+  // posture change, so the write asks first. `auto` and `required` write
+  // directly — `auto` is the status quo default and `required` tightens the
+  // posture. `--force` skips the ask, matching the house flags.force convention
+  // (backup-delete, machine-remove, service-remove, ...).
+  if (key === 'hooks.jail_policy' && value === 'off' && !flags.force) {
+    const confirmed = await withInterviewSession(() =>
+      askConfirm({
+        scope: 'hooks-jail-policy',
+        key: 'set-off',
+        message:
+          'Set hooks.jail_policy to off? Hooks will run unjailed fleet-wide and the doctor will warn.',
+        defaultValue: false,
+      }),
+    );
+
+    if (!confirmed) {
+      return { success: false, error: 'Cancelled by user' };
+    }
+  }
+
   const db = getDb();
 
   // Store value in database

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

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import type { JailModeRecord } from '../../hooks/jail';
 import {
   type HookExecutionInput,
+  assembleHookExecutionSection,
   compareVersions,
   renderHookExecutionSection,
 } from './system-doctor';
@@ -61,6 +62,9 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
     renderHookExecutionSection({
       availability: { backend: 'bubblewrap' },
       policy: 'auto',
+      source: 'default',
+      envValue: undefined,
+      configValue: undefined,
       record: jailedRecord,
       host: HOST,
       monitored: true,
@@ -153,4 +157,71 @@ describe('renderHookExecutionSection (hook-process-boundary task 4.6)', () => {
     expect(text(r)).toContain('belongs to host "old-box"');
     expect(r.failCount).toBe(0);
   });
+
+  test('the source line names the environment when the env var won (D4)', () => {
+    const r = render({
+      policy: 'off',
+      source: 'env',
+      envValue: 'off',
+      record: undefined,
+    });
+    expect(text(r)).toContain('policy from CELILO_HOOK_JAIL=off (environment override)');
+  });
+
+  test('the source line names system config when the stored key won (D4)', () => {
+    const r = render({
+      policy: 'required',
+      source: 'config',
+      configValue: 'required',
+      record: undefined,
+    });
+    expect(text(r)).toContain('policy from system config (hooks.jail_policy)');
+    expect(text(r)).not.toContain('policy from CELILO_HOOK_JAIL');
+  });
+
+  test('the source line names the default and how to change it (D4)', () => {
+    const r = render({ policy: 'auto', source: 'default', record: undefined });
+    expect(text(r)).toContain(
+      'policy default (auto) — set hooks.jail_policy or CELILO_HOOK_JAIL to change',
+    );
+  });
+
+  test('env and config disagreeing renders the losing value (D4)', () => {
+    const r = render({
+      policy: 'required',
+      source: 'env',
+      envValue: 'required',
+      configValue: 'off',
+      record: undefined,
+    });
+    expect(text(r)).toContain(
+      "system config holds 'off' but CELILO_HOOK_JAIL='required' overrides it",
+    );
+  });
+
+  test('env and config agreeing renders no disagreement line (D4)', () => {
+    const r = render({
+      policy: 'off',
+      source: 'env',
+      envValue: 'off',
+      configValue: 'off',
+      record: undefined,
+    });
+    expect(text(r)).not.toContain('system config holds');
+  });
+
+  test('a bad stored row renders as a failing check naming the row, not a crash', () => {
+    const r = assembleHookExecutionSection({
+      envValue: () => undefined,
+      configValue: () => 'alwayssafe',
+      availability: () => ({ backend: 'bubblewrap' }),
+      record: () => undefined,
+      host: () => HOST,
+      monitored: () => true,
+    });
+    expect(r.lines[0]).toBe('Hook execution');
+    expect(r.lines[1]).toContain("hooks.jail_policy='alwayssafe' is not a hook jail policy");
+    expect(r.failCount).toBe(1);
+    expect(r.warnCount).toBe(0);
+  });
 });

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

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

package/src/cli/commands/system-init-deprecation.test.ts

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

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

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

package/src/cli/generate-zsh-completion.ts

@@ -362,7 +362,7 @@ _celilo_system_config_keys() {
     'network.secure-mgmt.subnet:Control-plane subnet (celilo-mgr own network)'
     'network.secure-mgmt.gateway:Control-plane gateway IP'
     'network.control-plane-vpn.subnet:Administrative VPN client subnet (WireGuard remote access)'
-    'firewall.trusted_subnets:Extra subnets that reach every managed zone (comma-separated CIDRs)'
+    'firewall.trusted_subnets:Extra subnets that reach every managed zone (comma-separated CIDRs or JSON array)'
     'dns.primary:Primary DNS server'
     'dns.fallback:Fallback DNS servers'
     'routing.internal_gateway:Internal gateway IP'