@celilo/cli 2.2.1 → 3.0.0

package/src/cli/fuel-gauge.ts

@@ -56,11 +56,19 @@ export class FuelGauge {
   private linesDrawn = 0; // Track exactly how many lines were drawn last frame
   private startTime = Date.now();
   private lastOutputTime = Date.now();
+  /**
+   * Whether this gauge may draw frames on its output stream. A redirected
+   * or piped stream is a data channel, not a terminal (celilo#699), so the
+   * gauge tracks state silently there instead of writing frames into
+   * whatever file or protocol lies downstream (celilo#1362).
+   */
+  private readonly interactive: boolean;
 
   constructor(title: string, options: FuelGaugeOptions = {}) {
     this.title = title;
     this.output = options.output || stdout;
     this.skipAnimation = options.skipAnimation || false;
+    this.interactive = !this.skipAnimation && Boolean(this.output.isTTY);
     this.onBackground = options.onBackground;
   }
 
@@ -68,8 +76,8 @@ export class FuelGauge {
    * Start the fuel-gauge animation
    */
   start(): void {
-    if (this.skipAnimation) {
-      // Test mode: just track state
+    if (this.skipAnimation || !this.interactive) {
+      // Test mode or non-interactive output: just track state
       this.running = true;
       return;
     }
@@ -188,7 +196,7 @@ export class FuelGauge {
 
     this.running = false;
 
-    if (this.skipAnimation) {
+    if (!this.interactive) {
       return;
     }
 
@@ -233,7 +241,7 @@ export class FuelGauge {
   stopSilent(): void {
     if (!this.running) return;
     this.running = false;
-    if (this.skipAnimation) return;
+    if (!this.interactive) return;
     const display = getActiveDisplay();
     if (display) {
       display.abandon();

package/src/cli/index.ts

@@ -80,6 +80,7 @@ import { handleModuleDeploy } from './commands/module-deploy';
 import { handleModuleGenerate } from './commands/module-generate';
 import { handleModuleHealth } from './commands/module-health';
 import { handleModuleImport } from './commands/module-import';
+import { handleModuleJail } from './commands/module-jail';
 import { handleModuleJournal } from './commands/module-journal';
 import { handleModuleList } from './commands/module-list';
 import { handleModuleLogs } from './commands/module-logs';
@@ -114,6 +115,10 @@ import { handleServiceSetCredentials } from './commands/service-set-credentials'
 import { handleServiceVerify } from './commands/service-verify';
 import { handleStatus } from './commands/status';
 import { handleSubscribersAdd } from './commands/subscribers-add';
+import {
+  handleSubscribersInstallDaemon,
+  handleSubscribersUninstallDaemon,
+} from './commands/subscribers-install-daemon';
 import { handleSubscribersList } from './commands/subscribers-list';
 import { handleSubscribersRemove } from './commands/subscribers-remove';
 import { handleSubscribersServe } from './commands/subscribers-serve';
@@ -315,6 +320,7 @@ Subcommands:
   resync-subscriptions         Rebuild subscribers from deployed modules' manifests (after a restore/migration)
   list-pending [--subscriber]  List pending deliveries
   list-failed [--subscriber]   List failed/abandoned deliveries with a true total
+  list-unanswered              List interview questions nobody has answered yet
   drain [--concurrency N]      Process pending deliveries once and return
   run [--poll-ms N]            Run the long-running dispatcher (foreground)
   emit <type> [<payload>]      Emit an event (operator/test path)
@@ -363,6 +369,10 @@ Subcommands:
   test <url>                           Fire a synthetic event at a subscriber; report delivery
   serve --secret <hmac-secret>         Run the receiver daemon (verifies + emits to local bus)
        [--port <p>] [--no-dispatch]
+  install-daemon --secret <s>          Write a supervisor unit for the receiver (celilo#1304:
+       [--system] [--port <p>]         nothing else installs it). Runs serve --no-dispatch so the
+       [--dispatch] [--print]          standing dispatcher keeps owning hook delivery.
+  uninstall-daemon [--system]          Remove the receiver supervisor unit
   status                               Per-subscriber delivery history (success rate, recent failures)
   --help, -h                           Show this help
 
@@ -588,6 +598,32 @@ Subcommands:
       --auto-generate-secrets          Auto-generate all secrets without prompting
 
   list                                 List all installed modules
+    Options:
+      --json                           Output the module roster as stable JSON
+
+  status <id>                          Show detailed module status
+
+  where <id>                           Show which host(s) serve a module (host discovery)
+    Options:
+      --json                           Output host discovery as stable JSON
+
+  logs <id>                            Show deploy logs for a module
+    Options:
+      --tail <n>                       Show last N lines
+      --last                           Show only the most recent deploy run
+
+  journal <id>                         Tail a deployed module's runtime daemon journal on its host (no SSH)
+    Options:
+      --unit <glob>                    systemd unit or glob (default: <module-id>*)
+      --lines <n>                      Lines to return (default 100)
+      --since <window>                 Time window, e.g. '30 min ago'
+      --grep <text>                    Only lines containing this fixed string
+      --json                           Machine-readable JSON output
+
+  operations list|clear                Show or release in-flight module operations (the backup/restore lock)
+    Options:
+      --all                            With clear: also release operations that still look alive
+      --abandoned                      With list: also show abandoned rows (hidden by default)
 
   remove <id>                          Remove a module and all its data
 
@@ -605,8 +641,12 @@ Subcommands:
       --dry-run                        Print the ordered plan and change nothing
       --yes                            Skip the cascade confirmation
 
-  verify <id>                          Verify module integrity (signature + checksums)
-                                         (legacy alias: 'audit')
+  verify <id>                          Verify module integrity (signature + checksums) (legacy alias: 'audit')
+    Options:
+      --deep                           Deep verification (re-check all files)
+      --json                           Machine-readable JSON output
+
+  validate <id>                        Pre-flight check: validate module is ready for deployment
 
   config set <id> <key> <value>        Set module configuration value
   config get <id> [key]                Get module configuration value(s)
@@ -616,6 +656,11 @@ Subcommands:
   secret get <id> <key>                Get a decrypted module secret value
   secret list <id>                     List module secrets
 
+  jail <id> [policy]                   Get or set one module's hook jail policy (auto|off|required)
+    Options:
+      --clear                          Remove the module's policy; follow the system's hooks.jail_policy again
+      --force                          Skip the confirmation when the new policy is weaker than the system's
+
   show-config <id>                     Show all config including auto-derived values
   show-zone <id>                       Show module's network zone and config
 
@@ -647,6 +692,11 @@ Subcommands:
     Options:
       --registry <url>                  Use a custom registry (sweep mode only)
 
+  upgrade <id>                         Upgrade a module to its latest registry version (update, posture-gated backup, deploy, verify)
+    Options:
+      --poll                           Run the CD poll: upgrade every auto_upgrade module with a newer version
+      --registry <url>                 Registry URL (defaults to configured registry)
+
 Registry:
   search [query]                       Search the registry for modules
     Options:
@@ -662,6 +712,19 @@ Registry:
       --allow-dirty                    Permit publishing from a dirty git tree
       --allow-stale                    Skip the manifest-vs-src stale-check. Use sparingly.
 
+  changeset <module-dir>               Author a version changeset for a module (.changeset/<name>.md)
+    Options:
+      --bump <type>                    Version bump type: major, minor or patch (required)
+      --message <text>                 Changeset body text
+      --name <stem>                    Changeset filename stem (default: auto-generated slug)
+
+  backup <module-id>                   Create a backup of a module's data (invokes its on_backup hook)
+    Options:
+      --force                          Ignore schedule, back up now
+      --now                            Ignore schedule, back up now (alias for --force)
+      --storage <id>                   Storage destination ID
+      --no-interactive                 Non-interactive mode (for cron)
+
   check [path]                         Check a module for drift against the framework (default: .)
     Options:
       --no-build                       Skip the TypeScript build check
@@ -836,6 +899,12 @@ Subcommands:
       --storage <id>       Use specific storage destination
       --yes                Skip confirmation prompt
 
+  pull                      Download another box's backup artifact from a storage destination
+    Options:
+      --storage <name>     Storage destination name
+      --module <id>        Module ID whose backup to pull (default: system state)
+      --output <path>      Local path to write the artifact
+
 Description:
   Backups are encrypted with the master key and uploaded to a configured
   storage destination. System state backups capture the Celilo database.
@@ -1056,6 +1125,7 @@ Usage:
 Resources:
   vmid          Manage VMID reservations and allocations
   ip            Manage IP address reservations
+  show          Show comprehensive IPAM summary
   list-allocations    List all IPAM allocations (VMIDs and IPs)
 
 VMID Commands:
@@ -1140,6 +1210,8 @@ Subcommands:
   update [--module <id>] [--no-backup] [--allow-destructive] [--dry-run] [--json]
                                        Bring the system to the audit-determined READY state
 
+  migrate                              Apply pending database migrations (idempotent; safe to re-run)
+
   doctor [--fix]                       Diagnose system prerequisites and @celilo/* version drift
 
 Runbook:
@@ -1609,6 +1681,8 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleVersion(parsed.args, parsed.flags);
       case 'changeset':
         return handleModuleChangeset(parsed.args, parsed.flags);
+      case 'jail':
+        return handleModuleJail(parsed.args, parsed.flags);
       case 'audit':
         return moduleAudit(parsed.args, parsed.flags);
       case 'verify':
@@ -1843,6 +1917,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleSubscribersTest(parsed.args);
       case 'serve':
         return handleSubscribersServe(parsed.args, parsed.flags);
+      case 'install-daemon':
+        return handleSubscribersInstallDaemon(parsed.args, parsed.flags);
+      case 'uninstall-daemon':
+        return handleSubscribersUninstallDaemon(parsed.args, parsed.flags);
       case 'status':
         return handleSubscribersStatus();
       default:

package/src/cli/json-output.test.ts

@@ -27,6 +27,7 @@
  * have failed anything. See celilo#703.
  */
 
+import { Database } from 'bun:sqlite';
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
 import { spawnSync } from 'node:child_process';
 import { readFileSync, readdirSync } from 'node:fs';
@@ -49,6 +50,7 @@ const JSON_COMMANDS = [
   'module list --json',
   'module health --json',
   'system audit --json',
+  'system update --dry-run --json',
   'alerts list --json',
   'commands --json',
 ] as const;
@@ -90,6 +92,85 @@ describe('celilo#698 — JSON commands emit parseable JSON', () => {
   }
 });
 
+/**
+ * celilo#1362 — a --json command must stay parseable while its health checks
+ * run. The celilo#698 gates above all fire against an EMPTY fleet, where no
+ * health check ever executes and the pollution path never wakes up: the
+ * gauge silently animated frames onto stdout (plus plain `[module:hook]`
+ * logger lines) for every check, and `system audit --json` redirected to a
+ * file carried ~1 MB of `Testing app` frames before the first `{`.
+ *
+ * This gate seeds a module with a logging, sleeping health_check hook
+ * (`test-fixtures/modules/gauge-pollution-test`) so the checks genuinely
+ * run, then parses each fleet-wide --json command's stdout verbatim.
+ */
+describe('celilo#1362 — --json output stays parseable while health checks run', () => {
+  let ctx: IntegrationTestContext;
+  const FIXTURE_PATH = join(import.meta.dir, '../../test-fixtures/modules/gauge-pollution-test');
+  const MODULE_ID = 'gauge-pollution-test';
+  const SPAWN_ENV = () => ({
+    ...process.env,
+    CELILO_DB_PATH: ctx.dbPath,
+    CELILO_DATA_DIR: ctx.dataDir,
+    CELILO_SUPPRESS_DEPRECATION: '1',
+  });
+
+  beforeAll(async () => {
+    ctx = await setupIntegrationTest();
+
+    const imported = spawnSync(
+      'bun',
+      ['run', 'src/cli/index.ts', 'module', 'import', FIXTURE_PATH],
+      { encoding: 'utf8', env: SPAWN_ENV(), stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000 },
+    );
+    expect(
+      imported.status,
+      `module import exited ${imported.status}\nstdout: ${imported.stdout}\nstderr: ${imported.stderr}`,
+    ).toBe(0);
+
+    // runAllHealthChecks only checks INSTALLED/VERIFIED modules. Seeded
+    // the same way capability-abi-mismatch.test.ts seeds providers: the
+    // lifecycle under test is output purity, not the deploy flow.
+    const db = new Database(ctx.dbPath);
+    try {
+      db.run(`UPDATE modules SET state = 'VERIFIED' WHERE id = '${MODULE_ID}'`);
+    } finally {
+      db.close();
+    }
+  });
+
+  afterAll(async () => {
+    await ctx.cleanup();
+  });
+
+  for (const command of [
+    'system audit --json',
+    'system update --dry-run --json',
+    'module health --json',
+  ]) {
+    test(`celilo ${command} emits parseable JSON with a health-checked module deployed`, () => {
+      const result = spawnSync('bun', ['run', 'src/cli/index.ts', ...command.split(' ')], {
+        encoding: 'utf8',
+        env: SPAWN_ENV(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 120_000,
+      });
+
+      expect(
+        result.status,
+        `celilo ${command} exited ${result.status}\nstderr: ${result.stderr}`,
+      ).toBe(0);
+
+      // Verbatim JSON.parse — the gauge frames and plain logger lines both
+      // land here pre-fix, and either one alone breaks the parse.
+      expect(() => JSON.parse(result.stdout)).not.toThrow();
+
+      // And the fixture's own log lines must not ride along on stdout.
+      expect(result.stdout).not.toContain('gauge-pollution step');
+    });
+  }
+});
+
 /**
  * Walk from the index of a `{` to the index just past its matching `}`,
  * skipping over string literals so a brace inside a string doesn't unbalance

package/src/cli/parser.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from 'bun:test';
-import { getArg, getFlag, hasFlag, parseArguments, validateRequiredArgs } from './parser';
+import { COMMANDS } from '@celilo/core';
+import {
+  getArg,
+  getFlag,
+  hasFlag,
+  parseArguments,
+  validateFlags,
+  validateRequiredArgs,
+} from './parser';
 
 describe('CLI Parser', () => {
   describe('parseArguments', () => {
@@ -238,3 +246,31 @@ describe('CLI Parser', () => {
     });
   });
 });
+
+describe('a flag a handler reads is a flag the registry declares', () => {
+  // `handleSystemConfigSet` has read `flags.force` since the hooks.jail_policy
+  // interview gate landed, and its unit test drove the handler directly with
+  // `{ force: true }`. The registry declared no flags for `system config set`,
+  // so the parser answered `--force` with "does not accept any flags" and the
+  // escape hatch was tested and unreachable from a terminal. The suite could
+  // not see it, because nothing in it went through the parser.
+  const leaf = (path: readonly string[]) =>
+    path.slice(1).reduce<{ name: string; subcommands?: unknown[] } | undefined>(
+      (def, name) =>
+        (def as { subcommands?: { name: string }[] } | undefined)?.subcommands?.find(
+          (s) => s.name === name,
+        ),
+      COMMANDS.find((c) => c.name === path[0]),
+    );
+
+  test('system config set accepts --force through the real registry', () => {
+    const def = leaf(['system', 'config', 'set']);
+    expect(def).toBeDefined();
+    expect(validateFlags({ force: true }, def as never)).toBeNull();
+  });
+
+  test('and still refuses a flag nobody declared', () => {
+    const def = leaf(['system', 'config', 'set']);
+    expect(validateFlags({ frce: true }, def as never)).toContain('Unknown flag');
+  });
+});

package/src/cli/restore-command.test.ts

@@ -34,9 +34,9 @@ describe('celilo restore', () => {
   afterEach(() => {
     closeDb();
     resetTestDbPath();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.CELILO_MASTER_KEY_PATH;
+    delete process.env.CELILO_SUPPRESS_DEPRECATION;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/restore-migration-failure.test.ts

@@ -99,8 +99,8 @@ describe('restore migration failure reporting (celilo#1269)', () => {
   afterEach(() => {
     closeDb();
     resetTestDbPath();
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.CELILO_MASTER_KEY_PATH;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {

package/src/cli/tui/audit-state.ts

@@ -92,11 +92,13 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'interface_classification',
   'module_integrity',
   'detect_without_converge',
+  'jail_exemptions',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
   module_integrity: 'Module integrity',
   detect_without_converge: 'Drift without converge',
+  jail_exemptions: 'Hook jail exemptions',
   interface_classification: 'Firewall interfaces',
   cli_version: 'CLI version',
   schema: 'Schema migrations',

package/src/cli/types.ts

@@ -35,6 +35,15 @@ export interface CommandError {
   success: false;
   error: string;
   details?: unknown;
+  /**
+   * Marks a refusal that is not a failure: the action was skipped BEFORE any
+   * state changed and will be retried when its precondition holds (the
+   * registry poll defers a consumer upgrade whose capability requirements the
+   * deployed providers cannot serve — celilo#1361). Callers that read only
+   * `success` still see a non-deploy; the poll uses this to report deferrals
+   * separately from failures instead of counting them as red.
+   */
+  deferred?: boolean;
 }
 
 export type CommandResult = CommandSuccess | CommandError;

package/src/config/paths.test.ts

@@ -21,14 +21,14 @@ describe('paths configuration', () => {
   describe('getModuleStoragePath', () => {
     it('returns custom path when CELILO_DATA_DIR is set', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getModuleStoragePath();
       expect(path).toBe('/custom/data/modules');
     });
 
     it('returns dev path when ENVIRONMENT=dev', () => {
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getModuleStoragePath();
@@ -38,8 +38,8 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns platform-specific path by default',
       () => {
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getModuleStoragePath();
 
@@ -63,14 +63,14 @@ describe('paths configuration', () => {
   describe('getDataDir', () => {
     it('returns custom path when CELILO_DATA_DIR is set', () => {
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDataDir();
       expect(path).toBe('/custom/data');
     });
 
     it('returns dev path when ENVIRONMENT=dev', () => {
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getDataDir();
@@ -80,8 +80,8 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns platform-specific path by default',
       () => {
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getDataDir();
 
@@ -103,7 +103,7 @@ describe('paths configuration', () => {
     });
 
     it('returns data dir + master.key when CELILO_MASTER_KEY_PATH not set', () => {
-      process.env.CELILO_MASTER_KEY_PATH = undefined;
+      delete process.env.CELILO_MASTER_KEY_PATH;
       process.env.CELILO_DATA_DIR = '/custom/data';
 
       const path = getMasterKeyPath();
@@ -113,9 +113,9 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'uses platform-specific data dir by default',
       () => {
-        process.env.CELILO_MASTER_KEY_PATH = undefined;
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_MASTER_KEY_PATH;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getMasterKeyPath();
 
@@ -131,8 +131,8 @@ describe('paths configuration', () => {
   describe('getDbPath', () => {
     it('returns custom path when CELILO_DB_PATH is set', () => {
       process.env.CELILO_DB_PATH = '/custom/path/celilo.db';
-      process.env.CELILO_DATA_DIR = undefined;
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.CELILO_DATA_DIR;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/custom/path/celilo.db');
@@ -142,8 +142,8 @@ describe('paths configuration', () => {
       'returns data dir + celilo.db on macOS in production',
       () => {
         delete process.env.CELILO_DB_PATH;
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getDbPath();
 
@@ -157,7 +157,7 @@ describe('paths configuration', () => {
 
     it('returns celilo-data/celilo.db in development mode', () => {
       delete process.env.CELILO_DB_PATH;
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getDbPath();
@@ -167,7 +167,7 @@ describe('paths configuration', () => {
     it('respects CELILO_DATA_DIR override', () => {
       delete process.env.CELILO_DB_PATH;
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/custom/data/celilo.db');
@@ -176,7 +176,7 @@ describe('paths configuration', () => {
     it('prioritizes CELILO_DB_PATH over CELILO_DATA_DIR', () => {
       process.env.CELILO_DB_PATH = '/explicit/db.db';
       process.env.CELILO_DATA_DIR = '/custom/data';
-      process.env.ENVIRONMENT = undefined;
+      delete process.env.ENVIRONMENT;
 
       const path = getDbPath();
       expect(path).toBe('/explicit/db.db');

package/src/db/client.test.ts

@@ -3,7 +3,8 @@ import { afterEach, describe, expect, test } from 'bun:test';
 import { rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createDbClient } from './client';
+import { resetTestDbPath } from '../test-utils/db-path';
+import { closeDb, createDbClient, getDb } from './client';
 
 // #798: a command that opened the db while a deploy still held it died on
 // SQLITE_BUSY immediately, because the connection carried no busy timeout.
@@ -61,3 +62,47 @@ describe('createDbClient concurrency', () => {
     }
   });
 });
+
+/**
+ * The tripwire from celilo#1343: under bun test, a default-path open must be
+ * refused instead of landing on the operator's real database. The scratch-DB
+ * preload (apps/celilo/test-preload.ts) arms CELILO_DB_PATH only when bun
+ * runs from apps/celilo/, so every one of these tests strips the redirects
+ * itself to reproduce the out-of-scope state.
+ */
+describe('createDbClient operator-database tripwire (celilo#1343)', () => {
+  afterEach(() => {
+    closeDb();
+    resetTestDbPath();
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.ENVIRONMENT;
+  });
+
+  test('default-path open under bun test throws, naming the fix', () => {
+    delete process.env.CELILO_DB_PATH;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.ENVIRONMENT;
+
+    expect(() => getDb()).toThrow(/CELILO_DB_PATH/);
+  });
+
+  test('CELILO_DATA_DIR redirect keeps the default-path open allowed', () => {
+    delete process.env.CELILO_DB_PATH;
+    delete process.env.ENVIRONMENT;
+    process.env.CELILO_DATA_DIR = join(tmpdir(), 'celilo-tripwire-redirect');
+
+    const db = createDbClient();
+    db.$client.close();
+  });
+
+  test('explicit config path bypasses the tripwire', () => {
+    delete process.env.CELILO_DB_PATH;
+    delete process.env.CELILO_DATA_DIR;
+    delete process.env.ENVIRONMENT;
+
+    const db = createDbClient({
+      path: join(tmpdir(), 'celilo-tripwire-explicit', 'celilo.db'),
+    });
+    db.$client.close();
+  });
+});

package/src/db/client.ts

@@ -49,6 +49,32 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   const dbPath = config?.path ?? getDbPath();
   const readonly = config?.readonly ?? false;
 
+  // Tripwire against opening the operator's real database from a test
+  // (celilo#1343). The scratch-DB preload in apps/celilo/test-preload.ts only
+  // arms when bun runs from apps/celilo/ — bun reads the bunfig at the working
+  // directory — so the same suite run from the repo root reaches this function
+  // with every override unset and would open, and migrate, the operator's
+  // ~/Library/.../celilo.db. The condition below is exactly that resolution:
+  // under bun test, with every redirect unset, getDbPath() falls through to
+  // the platform data directory. A run that is properly scoped (preload armed,
+  // CELILO_DATA_DIR redirected, or an explicit config.path) never satisfies
+  // it and pays one string comparison.
+  if (
+    !config?.path &&
+    process.env.NODE_ENV === 'test' &&
+    !process.env.CELILO_DB_PATH &&
+    !process.env.CELILO_DATA_DIR &&
+    process.env.ENVIRONMENT !== 'dev'
+  ) {
+    throw new Error(
+      'Refusing to open the celilo database under bun test with no database path set ' +
+        '(celilo#1343): the scratch-DB preload in apps/celilo/test-preload.ts only arms ' +
+        "when bun runs from apps/celilo/, so this default path is the operator's real " +
+        'celilo.db. Run tests from apps/celilo/, or set CELILO_DB_PATH (or ' +
+        'CELILO_DATA_DIR) to a test-scoped path.',
+    );
+  }
+
   // bun:sqlite's `create: true` makes the file but not the parent directory.
   // First-run after a fresh install hits this — without recursive mkdir we
   // get SQLITE_CANTOPEN before init can write its config.