@celilo/cli 2.0.0 → 2.2.0

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

@@ -18,6 +18,7 @@ import {
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
+import { create as tarCreate } from 'tar';
 import { type DbClient, getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
 import { classifyVersionChange, handleModuleUpdate, updateOne } from './module-update';
@@ -556,3 +557,84 @@ describe('updateOne — an update that fails partway leaves the install untouche
     expect(mod?.version).toBe('1.0.0');
   });
 });
+
+describe('updateOne — a .netapp package source', () => {
+  let tempDir: string;
+  let installedDir: string;
+  let db: DbClient;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'celilo-netapp-'));
+    process.env.CELILO_DB_PATH = join(tempDir, 'test.db');
+    process.env.CELILO_ORIGINAL_CWD = tempDir;
+
+    installedDir = join(tempDir, 'installed', 'testmod');
+    mkdirSync(installedDir, { recursive: true });
+    writeFileSync(
+      join(installedDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 1.0.0\ndescription: fixture\n',
+    );
+
+    db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'testmod',
+        name: 'Test Module',
+        sourcePath: installedDir,
+        version: '1.0.0+5',
+        manifestData: {
+          celilo_contract: '1.0',
+          id: 'testmod',
+          name: 'Test Module',
+          version: '1.0.0',
+        },
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_ORIGINAL_CWD = undefined;
+  });
+
+  // ce-h4of: the temp-dir cleanup ran BEFORE the staged swap, and
+  // `replaceInstalledModule` still reads the extracted package through
+  // `actualPath`, which IS the temp dir for a .netapp source. Every
+  // registry-driven upgrade died with `ENOENT ... scandir
+  // .tmp-module-extract/<ts>`. Directory sources never set tempDir, which
+  // is why the path-source tests above stayed green. This test drives the
+  // real extraction path to keep that ordering honest.
+  test('the staged swap reads the package before the temp dir is cleaned', async () => {
+    const srcDir = join(tempDir, 'pkg-src');
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, 'manifest.yml'),
+      'celilo_contract: "1.0"\nid: testmod\nname: Test Module\nversion: 2.0.0\ndescription: fixture v2\n',
+    );
+    const pkgPath = join(tempDir, 'testmod-2.0.0.netapp');
+    await tarCreate({ file: pkgPath, cwd: srcDir }, ['manifest.yml']);
+
+    const extractRoot = join(process.cwd(), '.tmp-module-extract');
+    const extractCountBefore = existsSync(extractRoot) ? readdirSync(extractRoot).length : 0;
+
+    // Registry packages are pre-verified at publish time; updateOne gets
+    // skip-verify from the sweep, so no signature.sig is needed here.
+    const result = await updateOne(
+      pkgPath,
+      db,
+      { 'skip-verify': true },
+      { quiet: true, displayVersion: '2.0.0+7' },
+    );
+
+    expect(result.status).toBe('success');
+    if (result.status !== 'success') return;
+    expect(result.previousVersion).toBe('1.0.0+5');
+    expect(result.newVersion).toBe('2.0.0+7');
+    expect(readFileSync(join(installedDir, 'manifest.yml'), 'utf-8')).toContain('version: 2.0.0');
+
+    // The extraction scratch space is gone again once the swap has read it.
+    const extractCountAfter = existsSync(extractRoot) ? readdirSync(extractRoot).length : 0;
+    expect(extractCountAfter).toBe(extractCountBefore);
+  });
+});

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

@@ -128,7 +128,13 @@ export async function fetchAndUpdate(
 ): Promise<UpdateOutcome> {
   const tmpPath = join(tmpdir(), `${moduleId}-${version}-${Date.now()}.netapp`);
   try {
-    const pkgData = await client.download(moduleId, version);
+    // The index entry carries the published sha256. Look it up here rather than
+    // thread it through five call sites, so a short download is caught as a bad
+    // transfer instead of surfacing later as "zlib: unexpected end of file".
+    // Absence is tolerated: an entry predating cksum still downloads.
+    const entries = await client.getIndex(moduleId).catch(() => []);
+    const cksum = entries.find((entry) => entry.vers === version)?.cksum;
+    const pkgData = await client.download(moduleId, version, cksum);
     await Bun.write(tmpPath, pkgData);
   } catch (err) {
     return {
@@ -410,9 +416,6 @@ export async function updateOne(
     ? readFileSync(packagedSignaturePath, 'utf-8').trim()
     : null;
 
-  // Clean up temp dir if we extracted a .netapp
-  if (tempDir) await cleanupTempDir(tempDir);
-
   // Remove what the new version dropped. `updateOne` only ever overlaid files,
   // so a hook script deleted in 1.1.0 stayed on the box and stayed runnable —
   // code celilo no longer believes it has installed, which is the same class of
@@ -440,6 +443,13 @@ export async function updateOne(
   // below it runs only once the files are really in place.
   replaceInstalledModule(actualPath, installedPath, pruneDropped);
 
+  // Clean up the extracted package. This waits until after the swap because
+  // `replaceInstalledModule` reads `actualPath`, which IS `tempDir` for a
+  // .netapp source — deleting first is what made every registry-driven
+  // upgrade die with `ENOENT ... scandir .tmp-module-extract/<ts>`
+  // (ce-h4of, a regression from the celilo#1008 staging swap).
+  if (tempDir) await cleanupTempDir(tempDir);
+
   // Record it. `updateOne` never touched this table, so the baseline stayed
   // frozen at the module's FIRST import no matter how many times it was
   // updated. That is why `module verify` reported the same violations whether

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/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/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'

package/src/cli/index.ts

@@ -951,9 +951,10 @@ Usage:
   Shows how celilo classifies every interface on a firewall: the zone it
   matched, the external edge, or ALIEN when nothing accounts for it.
 
-  Read-only. It reads the recorded interface table and the declared zone
-  subnets and classifies in memory — it never touches the box, so it is safe
-  to run against a firewall whose converge is currently refusing.
+  It reads the interface table LIVE from the box, the same way the next
+  converge will, so its answer is the answer the converge will act on. If the
+  box cannot be reached, it says so and classifies the interface snapshot
+  recorded at machine add instead, labelled as possibly stale.
 
   With no hostname, every machine celilo classifies as a router is shown.
 

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

@@ -0,0 +1,159 @@
+/**
+ * Tests for the restore migration contract (celilo#1269):
+ *
+ *   1. A restore whose post-swap migration step fails reports FAILURE, not a
+ *      warning over a success result. The failure names the recovery command
+ *      (`celilo system migrate`) and the check that says whether the schema is
+ *      complete (`celilo system doctor`).
+ *   2. A connection held across the migration step is observable at the step's
+ *      own boundary: migrateRestoredDb throws naming the lock instead of
+ *      quietly proceeding over a locked database.
+ *
+ * The round-trip here (encrypted envelope → on_restore hook → staged system
+ * files → swap → migrate) is the first module-artifact round-trip at unit
+ * level; the envelope mechanics mirror backup-envelope-roundtrip.test.ts.
+ */
+
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { create as tarCreate } from 'tar';
+import { getDbPath } from '../config/paths';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { modules } from '../db/schema';
+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 { runCli } from './index';
+
+const FIXTURES_DIR = join(import.meta.dir, '../hooks/test-fixtures');
+const STAGING_HOOK = join(FIXTURES_DIR, 'on-restore-staging-hook.ts');
+const MODULE_ID = 'restore-migration-test';
+
+/** The manifest the module row carries: one on_restore hook, the fixture. */
+const MODULE_MANIFEST = {
+  celilo_contract: '1.0',
+  id: MODULE_ID,
+  name: 'Restore Migration Test',
+  version: '0.0.1',
+  hooks: {
+    on_restore: {
+      script: STAGING_HOOK,
+      timeout: 60000,
+    },
+  },
+};
+
+/**
+ * Build an encrypted module artifact whose envelope carries `dbBytes` as the
+ * backed-up celilo.db. The fixture on_restore hook stages it into system/ so
+ * the restore swaps it over the live DB before the migration step runs.
+ */
+async function buildModuleArtifact(dir: string, dbBytes: string): Promise<string> {
+  const envelopeDir = join(dir, 'envelope-build');
+  mkdirSync(join(envelopeDir, 'data'), { recursive: true });
+  writeFileSync(
+    join(envelopeDir, 'manifest.json'),
+    JSON.stringify(buildManifest({ kind: 'module', moduleId: MODULE_ID, moduleVersion: '0.0.1' })),
+  );
+  writeFileSync(join(envelopeDir, 'data', 'celilo.db'), dbBytes);
+  const tarPath = join(dir, 'envelope.tar');
+  await tarCreate({ file: tarPath, cwd: envelopeDir }, ['.']);
+  const masterKey = await getOrCreateMasterKey();
+  const artifactPath = join(dir, 'module.backup');
+  await encryptFileToFile(tarPath, artifactPath, masterKey);
+  return artifactPath;
+}
+
+describe('restore migration failure reporting (celilo#1269)', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-restore-mig-fail-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    process.env.CELILO_DATA_DIR = dir;
+    process.env.CELILO_MASTER_KEY_PATH = join(dir, 'master.key');
+    await runMigrations(process.env.CELILO_DB_PATH);
+
+    // The artifact's module must already be imported (restore-from-file's
+    // contract with bootstrap.sh). Its sourcePath points at the workspace
+    // fixture dir: the canonical <dataDir>/modules/<id> does not exist here,
+    // so restore-from-file falls back to sourcePath for the hook.
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id: MODULE_ID,
+        name: 'Restore Migration Test',
+        version: '0.0.1',
+        sourcePath: FIXTURES_DIR,
+        manifestData: MODULE_MANIFEST,
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_DATA_DIR = undefined;
+    process.env.CELILO_MASTER_KEY_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  test('a restore whose migration step fails reports failure and names the recovery path', async () => {
+    // The artifact's celilo.db is not a database at all. The swap lands it
+    // (staging bytes are deliberately tolerated so the file-copy path stays
+    // testable), and the migration step then fails on open — the same
+    // failure surface a locked or half-restored DB produces.
+    const artifact = await buildModuleArtifact(dir, 'this is not a SQLite database');
+    const result = await runCli(['node', 'celilo', 'restore', '--from', artifact, '--force']);
+
+    expect(result.success).toBe(false);
+    const err = result.success ? '' : (result.error ?? '');
+    expect(err).toContain('migrat');
+    expect(err).toContain('celilo system migrate');
+    expect(err).toContain('celilo system doctor');
+  });
+
+  test('the swap happened even when migrations failed (the error says so)', async () => {
+    const artifact = await buildModuleArtifact(dir, 'this is not a SQLite database');
+    const result = await runCli(['node', 'celilo', 'restore', '--from', artifact, '--force']);
+
+    expect(result.success).toBe(false);
+    const err = result.success ? '' : (result.error ?? '');
+    // The operator must learn the swap DID land — the failure is about the
+    // schema step, not a lost restore.
+    expect(err).toContain('restored');
+  });
+
+  // The timeout is 30s, not the 5s default: the holder pins the write lock
+  // for the full busy_timeout window before the migration step gives up, and
+  // the two windows are the same 5s.
+  test('a connection held across the migration step throws naming the lock', async () => {
+    // Current schema, ledger emptied so drizzle has work to do, then a write
+    // lock held across the step. Deleting one ledger row is not enough: the
+    // watermark is created_at-based and every migration shares one timestamp,
+    // so the whole ledger has to go. The re-run hits "already exists", the
+    // ledger-repair path then tries to write, and that write blocks on the
+    // holder until busy_timeout expires.
+    const livePath = getDbPath();
+    const ledger = new Database(livePath);
+    ledger.run('DELETE FROM __drizzle_migrations');
+    ledger.close();
+
+    const holder = new Database(livePath);
+    holder.run('BEGIN IMMEDIATE');
+    try {
+      await expect(migrateRestoredDb()).rejects.toThrow(/locked/i);
+    } finally {
+      holder.close();
+    }
+  }, 30000);
+});

package/src/db/client.ts

@@ -96,6 +96,10 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
       runMigrationsOn(db);
     } catch (error) {
       console.error('Failed to run migrations:', error);
+      // Release the file before rethrowing: the caller never receives this
+      // connection, so leaving it open holds the WAL lock on a db it cannot
+      // use (celilo#1269).
+      sqlite.close();
       throw error;
     }
   }
@@ -120,6 +124,7 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
       }
     } catch (error) {
       console.error('Failed to backfill module_systems:', error);
+      sqlite.close();
       throw error;
     }
   }

package/src/db/migrate.test.ts

@@ -1,147 +1,73 @@
 /**
- * The frozen-watermark recurrence gate (celilo#169).
+ * Tests for the standalone migration entrypoint's connection lifecycle.
  *
- * The state under test is one no correct deploy can produce, so it is seeded
- * by hand rather than reached: a database written by a celilo from the
- * imperative hand-list era, where schema changes were applied directly and
- * `__drizzle_migrations` never recorded them. Its ledger therefore remembers
- * an old migration while the tables and columns of every later one are already
- * present.
+ * runMigrations opens its own connection via createDbClient — which is NOT
+ * the process-wide singleton. Its teardown used to call closeDb(), which
+ * closes the SINGLETON: a different connection. Two consequences, both bad:
+ * the connection this call created was never closed, and a caller that had
+ * the singleton open had it closed out from under it.
  *
- * That is the carve-out CLAUDE.md draws around seeding state: deploying
- * anything cannot reproduce this row, because current celilo has recorded
- * every migration it applied since ISS-0100 made drizzle authoritative. A
- * suite that starts from an empty database can only ever prove the forward
- * invariant, and says nothing about the installed base.
- *
- * What made it a hazard: drizzle's migrator is watermark-only. It re-runs
- * every migration newer than the newest ledger row, so the first `ALTER TABLE
- * ... ADD` dies on `duplicate column name`, the transaction rolls back, and
- * the throw happens inside `createDbClient` — so EVERY celilo command on that
- * box fails at database open, not just a migrate. celilo-mgr was remediated by
- * hand once. This gate is what stops the next one needing a runbook.
+ * One bun:sqlite caveat this suite deliberately does NOT paper over: closing
+ * a drizzle-wrapped connection releases the file only once drizzle's prepared
+ * statements are collected, so a just-closed connection can still hold locks
+ * until the next GC. The restore path (the only in-tree caller) does not need
+ * the file again after migrating, so the caveat is harmless there — the thing
+ * that must hold is that the CLOSE TARGETS THE RIGHT CONNECTION.
  */
 
-import { afterEach, describe, expect, test } from 'bun:test';
-import { rmSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { type DbClient, createDbClient } from './client';
-import { runMigrationsOn } from './migrate';
-import { findSchemaDrift } from './schema-introspection';
-
-describe('runMigrationsOn — a database from the hand-list era', () => {
-  const paths: string[] = [];
-
-  const freshDb = (): { db: DbClient; path: string } => {
-    const path = join(tmpdir(), `celilo-migrate-test-${Bun.nanoseconds()}.db`);
-    paths.push(path);
-    return { db: createDbClient({ path }), path };
-  };
-
-  afterEach(() => {
-    for (const path of paths.splice(0)) {
-      for (const suffix of ['', '-wal', '-shm']) {
-        rmSync(`${path}${suffix}`, { force: true });
-      }
+import { closeDb, getDb } from './client';
+import { runMigrations } from './migrate';
+import { systemConfig } from './schema';
+
+describe('runMigrations connection lifecycle', () => {
+  it("does not close the caller's singleton connection", async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-migrate-close-test-'));
+    try {
+      const livePath = join(dir, 'celilo.db');
+      process.env.CELILO_DB_PATH = livePath;
+      await runMigrations(livePath);
+
+      // A caller with the singleton open (e.g. the restore CLI between swap
+      // and resync) runs migrations on a path and keeps using ITS OWN
+      // connection. The old teardown called closeDb(), which closes the
+      // singleton — a different connection — so the caller's next query died
+      // with a closed-connection error.
+      const db = getDb();
+      db.insert(systemConfig).values({ key: 'probe', value: 'before' }).run();
+
+      const otherPath = join(dir, 'other.db');
+      await runMigrations(otherPath);
+
+      // The singleton must have survived the migration on the other path.
+      expect(() => db.select().from(systemConfig).limit(1).all()).not.toThrow();
+      closeDb();
+    } finally {
+      closeDb();
+      process.env.CELILO_DB_PATH = undefined;
+      rmSync(dir, { recursive: true, force: true });
     }
   });
 
-  /**
-   * Freeze the ledger to its oldest entry, leaving the schema fully applied.
-   * This is the hand-list-era shape: the objects exist, the ledger has
-   * forgotten who made them.
-   */
-  const freezeWatermark = (db: DbClient): void => {
-    db.$client.run(
-      'DELETE FROM `__drizzle_migrations` WHERE created_at > (SELECT MIN(created_at) FROM `__drizzle_migrations`)',
-    );
-  };
-
-  const appliedCount = (db: DbClient): number =>
-    db.$client.query<{ c: number }, []>('SELECT COUNT(*) AS c FROM `__drizzle_migrations`').get()
-      ?.c ?? 0;
-
-  test('converges instead of dying on the first already-applied statement', () => {
-    const { db } = freshDb();
-    const migrationCount = appliedCount(db);
-    freezeWatermark(db);
-    expect(appliedCount(db)).toBe(1);
-
-    // Red before the ledger repair: drizzle re-runs 0001 and throws
-    // "duplicate column name: role", leaving the ledger frozen.
-    expect(() => runMigrationsOn(db)).not.toThrow();
-
-    expect(appliedCount(db)).toBe(migrationCount);
-  });
-
-  test('leaves the schema whole, so the drift detector goes green', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-
-    runMigrationsOn(db);
-
-    const drift = findSchemaDrift(db.$client);
-    expect(drift.missingTables).toEqual([]);
-    expect(drift.missingColumns).toEqual([]);
-  });
-
-  test('is idempotent — a second pass applies nothing and still converges', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-    runMigrationsOn(db);
-    const afterBaseline = appliedCount(db);
-
-    runMigrationsOn(db);
-
-    expect(appliedCount(db)).toBe(afterBaseline);
-  });
-
-  /**
-   * The repair must not become a blanket "assume it already ran". It fires only
-   * where the answer is unambiguous — the declared schema is entirely present,
-   * so every migration plainly did run and the ledger is what is wrong. A
-   * PARTIALLY applied schema is the genuinely hard case, and the one celilo-mgr
-   * was actually in: it carried 0011's column and not 0010's table. Stamping
-   * there would record migrations that never ran and bury the missing schema
-   * for good, so it keeps failing and a human decides.
-   */
-  test('refuses to stamp when the schema is only partly there', () => {
-    const { db } = freshDb();
-    freezeWatermark(db);
-    db.$client.run('DROP TABLE `dns_registrations`');
-
-    expect(() => runMigrationsOn(db)).toThrow();
-    // The ledger is left exactly as found, so the drift is still diagnosable.
-    expect(appliedCount(db)).toBe(1);
-  });
-
-  /**
-   * The path that actually matters. Every celilo command opens the database
-   * through createDbClient, which migrates on open, so a frozen watermark
-   * failed there rather than anywhere an operator could aim a fix at — and
-   * `celilo system migrate`, the command whose whole job is repairing this,
-   * reached its own repair through the same open and died first.
-   */
-  test('repairs on database open, not just when migrate is called by hand', () => {
-    const { db, path } = freshDb();
-    const migrationCount = appliedCount(db);
-    freezeWatermark(db);
-    db.$client.close();
-
-    const reopened = createDbClient({ path });
-
-    expect(appliedCount(reopened)).toBe(migrationCount);
-    expect(findSchemaDrift(reopened.$client).missingTables).toEqual([]);
-  });
-
-  test('a healthy database is untouched by the fallback', () => {
-    const { db } = freshDb();
-    const before = appliedCount(db);
-
-    runMigrationsOn(db);
-
-    expect(appliedCount(db)).toBe(before);
-    expect(findSchemaDrift(db.$client).missingTables).toEqual([]);
+  it('closes its own connection: the db reopens cleanly afterwards', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'celilo-migrate-own-conn-test-'));
+    try {
+      const dbPath = join(dir, 'celilo.db');
+      await runMigrations(dbPath);
+
+      // A fresh connection must be able to take the database over. The old
+      // closeDb() closed nothing here (the singleton was null), so this
+      // statement ran against a connection held open by nobody's bookkeeping
+      // — released only by GC, at a time of GC's choosing.
+      const probe = new Database(dbPath, { readonly: true });
+      expect(probe.query<{ journal_mode: string }, []>('PRAGMA journal_mode').get()).toBeDefined();
+      probe.close();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
   });
 });

package/src/db/migrate.ts

@@ -1,7 +1,7 @@
 import type { Database } from 'bun:sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
 import { readMigrationFiles } from 'drizzle-orm/migrator';
-import { type DbClient, closeDb, createDbClient, findMigrationsFolder } from './client';
+import { type DbClient, createDbClient, findMigrationsFolder } from './client';
 import { findSchemaDrift } from './schema-introspection';
 
 /**
@@ -93,7 +93,12 @@ export async function runMigrations(dbPath?: string) {
     console.error('Migration failed:', error);
     throw error;
   } finally {
-    closeDb();
+    // 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();
   }
 }
 

package/src/db/schema.ts

@@ -126,6 +126,16 @@ export const moduleConfigs = sqliteTable(
     key: text('key').notNull(),
     value: text('value').notNull(),
     valueJson: text('value_json'), // JSON for complex types (arrays, objects)
+    /**
+     * Who owns the row (hook-owned-state design D7 — one column shared with
+     * `derived-value-recomputation`). 'hook' means the owning module's own
+     * hook wrote it via `context.config.set`, and no operator path may touch
+     * it. NULL is every row written before the column existed — operator
+     * intent, legacy derived seeds, and framework keys alike — and stays the
+     * value for operator writes until derived-value-recomputation lands its
+     * own classification.
+     */
+    source: text('source'),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
     updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },