@celilo/cli 2.2.0 → 2.3.0

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';
@@ -315,6 +316,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)
@@ -588,6 +590,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 +633,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 +648,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
 
@@ -631,6 +668,7 @@ Subcommands:
       --preflight                        Run pre-flight validation only (no deployment)
       --verbose                          Keep all sub-events visible (no collapse-on-success)
       --stop-after-interview             Exit after config+secrets interview (no infra/hooks)
+      --keep                             Retain the generated project after a successful deploy (it is deleted by design)
 
   health [module-id]                    Run health checks (transitions to VERIFIED on success)
     Options:
@@ -646,6 +684,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:
@@ -661,6 +704,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
@@ -835,6 +891,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.
@@ -1055,6 +1117,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:
@@ -1139,6 +1202,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:
@@ -1608,6 +1673,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':
@@ -2238,7 +2305,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       }
       const configArgs = parsed.args.slice(1);
       if (configSubcommand === 'set') {
-        return handleSystemConfigSet(configArgs);
+        return await handleSystemConfigSet(configArgs, parsed.flags);
       }
       if (configSubcommand === 'get') {
         return handleSystemConfigGet(configArgs);

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

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { closeDb, getDb } from '../db/client';
 import { runMigrations } from '../db/migrate';
 import { modules } from '../db/schema';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 describe('celilo restore', () => {
@@ -32,10 +33,10 @@ describe('celilo restore', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
-    process.env.CELILO_SUPPRESS_DEPRECATION = undefined;
+    resetTestDbPath();
+    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

@@ -28,6 +28,7 @@ import { getOrCreateMasterKey } from '../secrets/master-key';
 import { encryptFileToFile } from '../services/backup-cipher';
 import { buildManifest } from '../services/backup-manifest';
 import { migrateRestoredDb } from '../services/restore-from-file';
+import { resetTestDbPath } from '../test-utils/db-path';
 import { runCli } from './index';
 
 const FIXTURES_DIR = join(import.meta.dir, '../hooks/test-fixtures');
@@ -97,9 +98,9 @@ describe('restore migration failure reporting (celilo#1269)', () => {
 
   afterEach(() => {
     closeDb();
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_DATA_DIR = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    resetTestDbPath();
+    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/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');
@@ -141,9 +141,9 @@ describe('paths configuration', () => {
     it.skipIf(skipIntegration({ platform: 'darwin' }))(
       'returns data dir + celilo.db on macOS in production',
       () => {
-        process.env.CELILO_DB_PATH = undefined;
-        process.env.CELILO_DATA_DIR = undefined;
-        process.env.ENVIRONMENT = undefined;
+        delete process.env.CELILO_DB_PATH;
+        delete process.env.CELILO_DATA_DIR;
+        delete process.env.ENVIRONMENT;
 
         const path = getDbPath();
 
@@ -156,8 +156,8 @@ describe('paths configuration', () => {
     );
 
     it('returns celilo-data/celilo.db in development mode', () => {
-      process.env.CELILO_DB_PATH = undefined;
-      process.env.CELILO_DATA_DIR = undefined;
+      delete process.env.CELILO_DB_PATH;
+      delete process.env.CELILO_DATA_DIR;
       process.env.ENVIRONMENT = 'dev';
 
       const path = getDbPath();
@@ -165,9 +165,9 @@ describe('paths configuration', () => {
     });
 
     it('respects CELILO_DATA_DIR override', () => {
-      process.env.CELILO_DB_PATH = undefined;
+      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.

package/src/db/migrate.test.ts

@@ -20,6 +20,7 @@ import { describe, expect, it } 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 { closeDb, getDb } from './client';
 import { runMigrations } from './migrate';
 import { systemConfig } from './schema';
@@ -48,7 +49,7 @@ describe('runMigrations connection lifecycle', () => {
       closeDb();
     } finally {
       closeDb();
-      process.env.CELILO_DB_PATH = undefined;
+      resetTestDbPath();
       rmSync(dir, { recursive: true, force: true });
     }
   });

package/src/db/migrate.ts

@@ -80,26 +80,26 @@ export function runMigrationsOn(db: DbClient): void {
 }
 
 /**
- * Run database migrations (standalone entrypoint — `bun run src/db/migrate.ts`).
- * createDbClient already migrates on open; this re-asserts for explicit use.
+ * Open a database at `dbPath` with migrations applied, then close it.
+ * Standalone entrypoint (`bun run src/db/migrate.ts`); tests also use it to
+ * prepare a fresh scratch database.
+ *
+ * createDbClient migrates synchronously on open (its own runMigrationsOn
+ * call), so this function is open + close. It deliberately does NOT call
+ * runMigrationsOn again: a second pass is always a ledger no-op when the
+ * first succeeded, and keeping it invited a double-migrate everywhere this
+ * entrypoint is used (celilo#1315).
  */
 export async function runMigrations(dbPath?: string) {
   console.log('Running database migrations...');
   const db = createDbClient(dbPath ? { path: dbPath } : undefined);
-  try {
-    runMigrationsOn(db);
-    console.log('Migrations completed successfully');
-  } catch (error) {
-    console.error('Migration failed:', error);
-    throw error;
-  } finally {
-    // Close the connection THIS call created. It is not the singleton —
-    // createDbClient does not register one — so the old closeDb() here closed
-    // whatever else was open (usually nothing) and leaked this connection,
-    // which then held the file in WAL and blocked every later journal-mode
-    // switch on it (celilo#1269).
-    db.$client.close();
-  }
+  console.log('Migrations completed successfully');
+  // Close the connection THIS call created. It is not the singleton —
+  // createDbClient does not register one — so an old closeDb() here closed
+  // whatever else was open (usually nothing) and leaked this connection,
+  // which then held the file in WAL and blocked every later journal-mode
+  // switch on it (celilo#1269).
+  db.$client.close();
 }
 
 // Run migrations if executed directly

package/src/db/schema.ts

@@ -212,6 +212,45 @@ export const capabilityBindings = sqliteTable(
   }),
 );
 
+/**
+ * One build-bus `on_upstream_publish` hook execution (services/build-bus/hook-dispatcher.ts).
+ *
+ * The self-update path had no durable record: outcomes were console output
+ * inside the receiver daemon, so a CLI that never upgraded looked like a
+ * healthy fleet (celilo#1304). One row per (event, module, hook) run — the
+ * newest row answers "did the self-update for @celilo/cli@X fire and succeed?".
+ *
+ * `exit_code` is NULL when the script never ran to an exit (spawn failure).
+ * Not an event-bus delivery: hooks run from the receiver's in-process
+ * dispatcher, which no `deliveries` row was ever written for.
+ *
+ * @owner celilo — build-bus self-update audit trail (celilo#1304)
+ */
+export const buildBusHookRuns = sqliteTable(
+  'build_bus_hook_runs',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** The PublishEvent's dedup id — joins back to the bus's `build-bus.publish` event. */
+    eventId: text('event_id').notNull(),
+    packageName: text('package_name').notNull(),
+    packageVersion: text('package_version').notNull(),
+    tag: text('tag').notNull(),
+    moduleId: text('module_id').notNull(),
+    hookName: text('hook_name').notNull(),
+    scriptPath: text('script_path').notNull(),
+    /** Null means the script never reached an exit (spawn failure). */
+    exitCode: integer('exit_code'),
+    timedOut: integer('timed_out', { mode: 'boolean' }).notNull().default(false),
+    durationMs: integer('duration_ms').notNull(),
+    stdoutTail: text('stdout_tail'),
+    stderrTail: text('stderr_tail'),
+    ranAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    ranAtLookup: index('build_bus_hook_runs_created_at_idx').on(table.ranAt),
+  }),
+);
+
 /**
  * Capability secrets table - stores encrypted secrets owned by capabilities
  * Values are encrypted with AES-256-GCM using master key
@@ -310,6 +349,28 @@ export const moduleIntegrity = sqliteTable('module_integrity', {
   updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
+/**
+ * Per-module hook jail policy — the operator's row in the four-step
+ * precedence (per-module-jail-policy task 1.1), ranked between the
+ * `CELILO_HOOK_JAIL` environment variable and the system-wide
+ * `hooks.jail_policy` key.
+ *
+ * One row per module; an absent row means "follow the system", so there is
+ * no default column to get wrong. The value is validated at set time by the
+ * `module jail` verb and re-validated at read time by `resolveJailPolicy`,
+ * which throws rather than coercing — a restored or hand-edited row outside
+ * the accepted set must fail loudly, the same rule the system key follows
+ * (peba's ruling on ce-8832).
+ * @owner celilo — operator-set per-module jail policy
+ */
+export const moduleJailPolicies = sqliteTable('module_jail_policies', {
+  moduleId: text('module_id')
+    .primaryKey()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  policy: text('policy').$type<'auto' | 'off' | 'required'>().notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
 /**
  * Lifecycle states an instance moves through.
  *
@@ -1579,3 +1640,5 @@ export type NotificationDelivery = typeof notificationDeliveries.$inferSelect;
 export type NewNotificationDelivery = typeof notificationDeliveries.$inferInsert;
 export type CapabilityBinding = typeof capabilityBindings.$inferSelect;
 export type NewCapabilityBinding = typeof capabilityBindings.$inferInsert;
+export type BuildBusHookRun = typeof buildBusHookRuns.$inferSelect;
+export type NewBuildBusHookRun = typeof buildBusHookRuns.$inferInsert;