@celilo/cli 2.2.0 → 2.3.0

package/src/cli/commands/module-upgrade.ts

@@ -20,7 +20,8 @@ import { type DbClient, getDb } from '../../db/client';
 import { modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
 import { RegistryClient } from '../../registry/client';
-import { createModuleBackup } from '../../services/backup-create';
+import { createModuleBackup, createSystemStateBackup } from '../../services/backup-create';
+import { getDefaultBackupStorage } from '../../services/backup-storage';
 import {
   type DeployPosture,
   type UpgradePolicy,
@@ -79,12 +80,55 @@ export function needsPreUpgradeBackup(
   return posture === 'safe' && Boolean(targetManifest.hooks?.on_backup);
 }
 
+/**
+ * Pure (Rule 10): does this upgrade snapshot the celilo DB first? Safe posture
+ * means a minor/major bump, and a minor bump can migrate the DB schema — the
+ * snapshot is what makes a later package downgrade a real rollback instead of
+ * a gamble on an older binary reading a newer-migrated database.
+ */
+export function needsSystemStateSnapshot(posture: DeployPosture): boolean {
+  return posture === 'safe';
+}
+
+/**
+ * Take the system_state snapshot a safe-posture upgrade requires.
+ *
+ * A host with no default backup storage keeps today's behavior (warn and
+ * proceed): refusing every safe upgrade there would break CD for a config
+ * gap, and the module-level backup below still runs when the target manifest
+ * declares on_backup. A configured-but-failing snapshot refuses the upgrade,
+ * same rule `system update` applies to its own snapshot (D7): the DB snapshot
+ * is the safety net, and an upgrade that cannot take it should not mutate.
+ */
+async function snapshotSystemStateBeforeUpgrade(
+  moduleId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    if (!getDefaultBackupStorage()) {
+      log.warn(
+        `${moduleId}: no default backup storage configured — skipping pre-upgrade system_state snapshot`,
+      );
+      return { ok: true };
+    }
+    const snapshot = await createSystemStateBackup();
+    if (!snapshot.success) {
+      return { ok: false, error: snapshot.error ?? 'system_state backup failed' };
+    }
+    log.success(`System state snapshot taken before upgrading ${moduleId}`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 export interface PollCandidate {
   moduleId: string;
   installed: string;
   /** Latest registry version, or null when the module isn't on the registry. */
   latest: string | null;
   autoUpgrade: boolean;
+  /** True when the module row carries state ERROR (a failed upgrade, celilo#1363). */
+  inError: boolean;
 }
 
 export interface PollTarget {
@@ -102,6 +146,10 @@ export function selectPollTargets(candidates: PollCandidate[]): PollTarget[] {
   const targets: PollTarget[] = [];
   for (const c of candidates) {
     if (!c.autoUpgrade || !c.latest) continue;
+    // A module in ERROR failed an upgrade already. Retrying it on every poll
+    // redeploys the same broken version indefinitely (celilo#1363), so skip it
+    // until an attended health check clears the state (healthy → VERIFIED).
+    if (c.inError) continue;
     const change = classifyVersionChange(c.installed, c.latest);
     if (change === 'up-to-date' || change === 'ahead') continue;
     targets.push({ moduleId: c.moduleId, from: c.installed, to: c.latest });
@@ -121,8 +169,10 @@ function resolveAutoUpgrade(moduleId: string): boolean {
  * Upgrade ONE module to a known target version: posture → update → backup →
  * deploy → verify. The shared core for both the single-module command and the
  * poll. `mod` is the current DB row; `targetVersion` is the registry latest.
+ * Exported for tests: the failure paths here are where the store diverges from
+ * reality (celilo#1363).
  */
-async function upgradeOneModule(
+export async function upgradeOneModule(
   mod: typeof modules.$inferSelect,
   targetVersion: string,
   client: RegistryClient,
@@ -168,7 +218,17 @@ async function upgradeOneModule(
   });
   log.info(`Upgrading ${moduleId} ${mod.version} → ${targetVersion} (${posture} — ${reason})`);
 
-  // Safe → back up first, gated on the TARGET manifest's on_backup hook.
+  // Safe → snapshot the celilo DB first (the package rollback pair), then
+  // back up the module itself, gated on the TARGET manifest's on_backup hook.
+  if (needsSystemStateSnapshot(posture)) {
+    const snapshot = await snapshotSystemStateBeforeUpgrade(moduleId);
+    if (!snapshot.ok) {
+      return {
+        success: false,
+        error: `Pre-upgrade system_state snapshot failed for ${moduleId}: ${snapshot.error}`,
+      };
+    }
+  }
   if (needsPreUpgradeBackup(posture, targetManifest)) {
     const backup = await createModuleBackup(moduleId);
     if (!backup.success) {
@@ -185,6 +245,19 @@ async function upgradeOneModule(
   // Deploy (idempotent).
   const deployed = await deployModule(moduleId, db, {});
   if (!deployed.success) {
+    // fetchAndUpdate already swapped the files and wrote the new version to
+    // the store, so the recorded version no longer matches anything verified.
+    // Record the failure in the state rather than leaving a stale VERIFIED
+    // beside the new version (celilo#1363, option A). An attended health check
+    // that passes moves ERROR → VERIFIED and clears the record.
+    db.update(modules)
+      .set({
+        state: 'ERROR',
+        errorMessage: `Upgrade to ${targetVersion} failed to deploy: ${deployed.error}`,
+        updatedAt: new Date(),
+      })
+      .where(eq(modules.id, moduleId))
+      .run();
     return {
       success: false,
       error: `Deploy failed for ${moduleId} (now at ${targetVersion}): ${deployed.error}`,
@@ -236,6 +309,7 @@ async function runRegistryPoll(
       installed: mod.version,
       latest: await latestRegistryVersion(client, mod.id),
       autoUpgrade: resolveAutoUpgrade(mod.id),
+      inError: mod.state === 'ERROR',
     });
   }
 

package/src/cli/commands/module-verify.test.ts

@@ -2,6 +2,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 { moduleAudit } from './module-audit';
 import { moduleVerify } from './module-verify';
 
@@ -19,7 +20,6 @@ describe('moduleVerify', () => {
 describe('moduleAudit (deprecation alias)', () => {
   let dataDir: string;
   const originalDataDir = process.env.CELILO_DATA_DIR;
-  const originalDbPath = process.env.CELILO_DB_PATH;
 
   beforeEach(() => {
     dataDir = mkdtempSync(join(tmpdir(), 'celilo-audit-alias-'));
@@ -29,10 +29,9 @@ describe('moduleAudit (deprecation alias)', () => {
 
   afterEach(() => {
     rmSync(dataDir, { recursive: true, force: true });
-    if (originalDataDir === undefined) process.env.CELILO_DATA_DIR = undefined;
+    resetTestDbPath();
+    if (originalDataDir === undefined) delete process.env.CELILO_DATA_DIR;
     else process.env.CELILO_DATA_DIR = originalDataDir;
-    if (originalDbPath === undefined) process.env.CELILO_DB_PATH = undefined;
-    else process.env.CELILO_DB_PATH = originalDbPath;
   });
 
   test('writes a deprecation warning to stderr and delegates to verify', async () => {

package/src/cli/commands/module-verify.ts

@@ -102,7 +102,6 @@ export async function moduleVerify(
     modified: '✗',
     extra: '!',
     'stale-baseline': '⚠',
-    'stale-generated': '✗',
   };
 
   return {

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/publish/execute.ts

@@ -63,7 +63,10 @@ export async function executePlan(input: ExecutePlanInput): Promise<PublishResul
   }
 
   if (plan.modulePublish.length > 0) {
-    executeModulePublish(plan.modulePublish, { allowStale: plan.options.allowStale });
+    executeModulePublish(plan.modulePublish, {
+      allowStale: plan.options.allowStale,
+      skippedModules: plan.options.skippedModules,
+    });
   }
 
   return result;

package/src/cli/commands/publish/index.ts

@@ -20,6 +20,7 @@
  *   celilo publish --release-touch                  # auto-fix module stale-drift
  *   celilo publish --allow-stale                    # skip stale-version safeguards
  *   celilo publish -y / --yes                       # auto-confirm prompts
+ *   celilo publish --skip-module <id>               # leave a module out of the registry sweep
  *   celilo publish --alpha                          # X.Y.Z-alpha.N to @alpha
  *   celilo publish --alpha --track-alpha            # also force-pin alphas globally
  *   celilo publish --alpha --alpha-modules          # also publish module +N
@@ -120,6 +121,15 @@ export function parseOptions(argv: string[]): ParsedFlags {
   const alphaModulesFlag = argv.includes('--alpha-modules');
   const skipChangesets = argv.includes('--skip-changesets');
   const promoteArg = takeFlagValue('--promote');
+  const skippedModules: string[] = [];
+  for (let i = argv.indexOf('--skip-module'); i >= 0; i = argv.indexOf('--skip-module', i + 1)) {
+    const id = argv[i + 1];
+    if (id === undefined || id.startsWith('-')) {
+      console.error('✗ --skip-module requires a module id (e.g. --skip-module homebridge)');
+      process.exit(1);
+    }
+    skippedModules.push(id);
+  }
 
   if (alphaFlag && promoteArg) {
     console.error('✗ --alpha and --promote are mutually exclusive.');
@@ -152,7 +162,7 @@ export function parseOptions(argv: string[]): ParsedFlags {
   }
 
   return {
-    options: { allowStale, autoYes: yes, mode },
+    options: { allowStale, autoYes: yes, mode, skippedModules },
     dryRun,
     releaseTouch,
     skipChangesets,

package/src/cli/commands/publish/module-registry.test.ts

@@ -8,7 +8,7 @@
  */
 
 import { describe, expect, test } from 'bun:test';
-import { mapModuleDirsToItems } from './module-registry';
+import { applyModuleSkips, mapModuleDirsToItems } from './module-registry';
 
 describe('mapModuleDirsToItems', () => {
   test('empty input → empty plan', () => {
@@ -38,3 +38,26 @@ describe('mapModuleDirsToItems', () => {
     ]);
   });
 });
+
+describe('applyModuleSkips', () => {
+  const items = mapModuleDirsToItems([
+    '/repo/modules/caddy',
+    '/repo/modules/burner',
+    '/repo/modules/homebridge',
+  ]);
+
+  test('no skips leaves the plan unchanged', () => {
+    expect(applyModuleSkips(items, [])).toEqual(items);
+  });
+
+  test('drops each named module and keeps the order of the rest', () => {
+    expect(applyModuleSkips(items, ['burner']).map((m) => m.moduleDir)).toEqual([
+      '/repo/modules/caddy',
+      '/repo/modules/homebridge',
+    ]);
+  });
+
+  test('a name that matches no module directory throws and names it', () => {
+    expect(() => applyModuleSkips(items, ['burnr'])).toThrow('burnr');
+  });
+});

package/src/cli/commands/publish/module-registry.ts

@@ -11,7 +11,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { basename, join, relative } from 'node:path';
 import { REPO_ROOT, listModuleDirs } from './helpers';
 import type { ModuleItem } from './types';
 
@@ -28,13 +28,31 @@ export function mapModuleDirsToItems(dirs: string[]): ModuleItem[] {
   return dirs.map((moduleDir) => ({ moduleDir }));
 }
 
-export function planModulePublish(): ModuleItem[] {
-  return mapModuleDirsToItems(listModuleDirs());
+/**
+ * Leave the modules named by `--skip-module` out of the sweep. A name
+ * that matches no module directory throws, so a typo cannot skip
+ * nothing and publish the module it meant to hold back.
+ */
+export function applyModuleSkips(items: ModuleItem[], skippedModules: string[]): ModuleItem[] {
+  const known = new Set(items.map((m) => basename(m.moduleDir)));
+  const unknown = skippedModules.filter((id) => !known.has(id));
+  if (unknown.length > 0) {
+    throw new Error(`--skip-module names no module directory: ${unknown.join(', ')}`);
+  }
+  const skipped = new Set(skippedModules);
+  return items.filter((m) => !skipped.has(basename(m.moduleDir)));
+}
+
+export function planModulePublish(skippedModules: string[]): ModuleItem[] {
+  return applyModuleSkips(mapModuleDirsToItems(listModuleDirs()), skippedModules);
 }
 
 // ─── Executor ──────────────────────────────────────────────────────
 
-export function executeModulePublish(items: ModuleItem[], opts: { allowStale: boolean }): void {
+export function executeModulePublish(
+  items: ModuleItem[],
+  opts: { allowStale: boolean; skippedModules: string[] },
+): void {
   if (items.length === 0) {
     console.log('\nNo modules with manifest.yml found — skipping module-publish phase.');
     return;
@@ -49,6 +67,7 @@ export function executeModulePublish(items: ModuleItem[], opts: { allowStale: bo
   console.log('\n──────────────────────────────────────────────');
   console.log(' Publishing modules to celilo registry');
   console.log('──────────────────────────────────────────────');
+  for (const id of opts.skippedModules) console.log(`  modules/${id}  (skipped: --skip-module)`);
   for (const m of items) console.log(`  ${relative(REPO_ROOT, m.moduleDir)}`);
   console.log();
 

package/src/cli/commands/publish/plan.ts

@@ -76,7 +76,7 @@ export function planPublish(opts: PublishOptions): PublishPlan {
           trackAlpha: opts.mode.kind === 'alpha' && opts.mode.trackAlpha,
         })
       : [],
-    modulePublish: runPhase4 ? planModulePublish() : [],
+    modulePublish: runPhase4 ? planModulePublish(opts.skippedModules) : [],
   };
 }
 

package/src/cli/commands/publish/types.ts

@@ -61,6 +61,13 @@ export interface PublishOptions {
   allowStale: boolean;
   autoYes: boolean;
   mode: PublishMode;
+  /**
+   * Module ids to leave out of the module-registry sweep (`--skip-module
+   * <id>`, repeatable). For a module that cannot publish yet. The sweep
+   * stops at its first failed module, so one such module would otherwise
+   * take every module after it, and the release's .deb, down with it.
+   */
+  skippedModules: string[];
 }
 
 /**

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,
@@ -44,8 +45,8 @@ describe('registry owner commands', () => {
   afterEach(async () => {
     fetchSpy.mockRestore();
     closeDb();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    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. */
@@ -49,8 +50,8 @@ describe('registry token add/rm (F2 clobber fix)', () => {
 
   afterEach(async () => {
     closeDb();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_DB_PATH = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    resetTestDbPath();
     if (existsSync(dataDir)) {
       await rm(dataDir, { recursive: true, force: true });
     }

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-audit.ts

@@ -45,7 +45,6 @@ import {
   type LatestCliVersionFetcher,
   fetchLatestCliVersion,
 } from '../../services/audit/cli-version';
-import type { MachineReachableResult } from '../../services/audit/machines-reachable';
 import type { ModuleVersionFetcher } from '../../services/audit/module-versions';
 import {
   loadPublicDnsEvidence,
@@ -57,8 +56,10 @@ import type { ServiceCredentialsResult } from '../../services/audit/services-cre
 import type { ServiceReachableResult } from '../../services/audit/services-reachable';
 import type { TerraformPlanRunner } from '../../services/audit/terraform-plan';
 import { getServiceCredentials, listContainerServices } from '../../services/container-service';
+import { probeDiskUsage } from '../../services/disk-probe';
 import { collectFirewallReach } from '../../services/firewall-reach';
 import { runAllHealthChecks } from '../../services/health-runner';
+import { collectJailExemptions } from '../../services/jail-exemptions';
 import { probeMachines } from '../../services/machine-probe';
 import { parseStoredConfigValue } from '../../services/module-config';
 import { createPublicDnsProbe, loadPublicDnsProbeSettings } from '../../services/public-dns-probe';
@@ -341,11 +342,22 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
     }),
   );
 
-  // Machines-reachable: probe each pool machine. Shared with the monitor sweep
-  // (services/machine-probe.ts) — this block used to be a second copy of the
-  // same SSH logic, and both copies reported the local management box as
-  // unreachable because celilo does not hold an SSH key for itself.
-  const machineReachableResults: MachineReachableResult[] = await probeMachines();
+  // Machines-reachable and disk-space both SSH every system, so they run
+  // concurrently here rather than paying each other's latency. The machine
+  // probe is shared with the monitor sweep (services/machine-probe.ts) —
+  // this block used to be a second copy of the same SSH logic, and both
+  // copies reported the local management box as unreachable because celilo
+  // does not hold an SSH key for itself.
+  //
+  // The disk probe measures every system's root filesystem — the machine
+  // pool AND every provisioned instance, the systems celilo#1133 filled —
+  // in the same pre-computed measurement shape the disk_space monitor
+  // sweep consumes, so an audit finding and an alert page carry the same
+  // numbers.
+  const [machineReachableResults, diskUsageResults] = await Promise.all([
+    probeMachines(),
+    probeDiskUsage(db),
+  ]);
 
   const migrationsFolder = findMigrationsFolderSafe();
 
@@ -384,6 +396,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
         manifest: m.manifestData as ModuleManifest,
       })),
     },
+    jailExemptions: { exemptions: collectJailExemptions(db) },
     health: { results: healthResults },
     backups: { modules: installedBackupInfo },
     abandonedOperations: { records: loadAbandonedOperations(db) },
@@ -417,6 +430,7 @@ async function buildAuditDeps(onProgress?: (msg: string) => void) {
       probe: createPublicDnsProbe(loadPublicDnsProbeSettings(db)),
       evidence: loadPublicDnsEvidence(db),
     },
+    diskSpace: { results: diskUsageResults },
     // Reads the record the poller already writes — this check never performs a
     // read of its own. One that did would drain the queue and eat the
     // acknowledgement it exists to protect (#541).

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');
+  });
+});