@celilo/cli 1.5.0 → 1.7.0

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

@@ -472,7 +472,67 @@ async function renderAspectCoverage(opts: { fix: boolean }): Promise<{
   return { lines, failCount: missing.length, warnCount: unknown.length };
 }
 
-async function renderFleetSection(opts: { forced: boolean; fix: boolean }): Promise<{
+/**
+ * The fleet-section line for module integrity, one row per module.
+ *
+ * `module verify` is the detailed surface and `system audit` is the machine
+ * one; doctor gets the summary, because doctor is where an operator looks
+ * first. Same implementation behind all three.
+ */
+async function renderModuleIntegrity(opts: {
+  db: ReturnType<typeof getDb>;
+  deep: boolean;
+}): Promise<{ lines: string[]; failCount: number; warnCount: number }> {
+  const { auditModule } = await import('../../module/packaging/audit');
+  const { auditModuleIntegrity } = await import('../../services/audit/module-integrity');
+  const { modules: modulesTable } = await import('../../db/schema');
+
+  const installed = opts.db.select().from(modulesTable).all();
+  if (installed.length === 0) return { lines: [], failCount: 0, warnCount: 0 };
+
+  const results = await Promise.all(
+    installed.map((m) => auditModule(m.id, opts.db, { deep: opts.deep })),
+  );
+  const findings = auditModuleIntegrity({ results });
+
+  const drifted = findings.filter((f) => f.severity === 'drift');
+  const unmeasured = findings.filter((f) => f.severity === 'unmeasured');
+
+  if (findings.length === 0) {
+    const scope = opts.deep
+      ? 'including what is running on their hosts'
+      : 'installed and generated';
+    return {
+      lines: [
+        `  ${ANSI.green}✔${ANSI.reset} Module integrity  ${ANSI.dim}— ${installed.length} module(s) match their recorded version (${scope})${ANSI.reset}`,
+      ],
+      failCount: 0,
+      warnCount: 0,
+    };
+  }
+
+  const lines: string[] = [
+    `  ${drifted.length > 0 ? `${ANSI.red}✗${ANSI.reset}` : `${ANSI.yellow}?${ANSI.reset}`} Module integrity  ${ANSI.dim}— ${drifted.length} drifted, ${unmeasured.length} unmeasured, of ${installed.length} module(s)${ANSI.reset}`,
+  ];
+  // Every finding, never just the first. celilo#951 printed `drift[0]` of 19,
+  // so a real finding would have arrived at position 19 and never been seen.
+  for (const f of findings) {
+    lines.push(`      ${ANSI.dim}${f.message}${ANSI.reset}`);
+    if (f.remediation) lines.push(`    ${ANSI.dim}→ ${f.remediation}${ANSI.reset}`);
+  }
+  if (!opts.deep) {
+    lines.push(
+      `    ${ANSI.dim}Run \`celilo system doctor --deep\` to also ask each host what it is running.${ANSI.reset}`,
+    );
+  }
+  return { lines, failCount: drifted.length, warnCount: unmeasured.length };
+}
+
+async function renderFleetSection(opts: {
+  forced: boolean;
+  fix: boolean;
+  deep: boolean;
+}): Promise<{
   lines: string[];
   failCount: number;
   warnCount: number;
@@ -518,6 +578,18 @@ async function renderFleetSection(opts: { forced: boolean; fix: boolean }): Prom
       if (f.status === 'fail') failCount++;
       else if (f.status === 'warn') warnCount++;
     }
+
+    // Module integrity: is the code on each box the code celilo thinks it is?
+    // Shallow here by design — the installed tree against its baseline and the
+    // generated project against the installed tree are both local and take
+    // milliseconds. The host plane is one SSH per system and is reached with
+    // `--deep`, alongside aspect coverage, for the same reason
+    // (openspec/changes/module-integrity-rigor, D8).
+    const integrity = await renderModuleIntegrity({ db, deep: opts.deep });
+    lines.push(...integrity.lines);
+    failCount += integrity.failCount;
+    warnCount += integrity.warnCount;
+
     return { lines, failCount, warnCount };
   } finally {
     bus.close();
@@ -647,7 +719,11 @@ export async function handleSystemDoctor(
 
   // Fleet-runtime section (state-aware; only renders on a management
   // plane with a celilo DB, or when --fleet forces it).
-  const fleet = await renderFleetSection({ forced: flags.fleet === true, fix });
+  const fleet = await renderFleetSection({
+    forced: flags.fleet === true,
+    fix,
+    deep: flags.deep === true,
+  });
   if (fleet.lines.length > 0) {
     lines.push(...fleet.lines);
     lines.push('');

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

@@ -108,9 +108,11 @@ export async function handleSystemMigrate(
     }
   }
 
-  // getDb() auto-migrates on open; do it inside try so an existing DB that
-  // predates the drizzle-authoritative change fails with an actionable message
-  // instead of a raw migrator error.
+  // getDb() auto-migrates on open, and repairs a frozen `__drizzle_migrations`
+  // watermark itself when the declared schema is already complete. What reaches
+  // this catch is the case it will not guess at: schema that is only PARTLY
+  // there, where stamping would record migrations that never ran. Caught so it
+  // says what to do instead of surfacing a raw migrator error.
   let db: ReturnType<typeof getDb>;
   try {
     db = getDb();
@@ -118,7 +120,7 @@ export async function handleSystemMigrate(
     const msg = error instanceof Error ? error.message : String(error);
     return {
       success: false,
-      error: `Migration failed: ${msg}\n\nIf this DB predates the drizzle-authoritative migration change, it needs a one-time remediation (stamp \`__drizzle_migrations\` to the latest migration + create any missing table) before the migrator can run cleanly — see ISS-0100.`,
+      error: `Migration failed: ${msg}\n\nThis DB's \`__drizzle_migrations\` watermark disagrees with a schema that is only partly applied, which celilo will not resolve on its own. It needs a one-time remediation by hand (create the genuinely missing objects from their migration .sql, then stamp the watermark to the latest migration) — runbook in celilo#169.`,
     };
   }
 

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

@@ -495,6 +495,11 @@ export async function handleSystemUpdate(
   const migrationsFolder = findMigrationsFolderSafe();
   const healthResults = await runAllHealthChecks(db);
 
+  // Module integrity, shallow. Local and milliseconds; the host plane is one
+  // SSH per system and belongs to `module verify --deep`.
+  const { auditModule } = await import('../../module/packaging/audit');
+  const integrityResults = await Promise.all(upgradableModules.map((m) => auditModule(m.id, db)));
+
   const latestBackupByModule = new Map<string, number>();
   try {
     const successfulBackups = db
@@ -563,6 +568,14 @@ export async function handleSystemUpdate(
         configs: configsByModule.get(m.id) ?? {},
       })),
     },
+    moduleIntegrity: { results: integrityResults },
+    detectWithoutConverge: {
+      modules: upgradableModules.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+      })),
+    },
     health: { results: healthResults },
     backups: {
       modules: upgradableModules.map((m) => ({
@@ -714,7 +727,7 @@ export async function handleSystemUpdate(
   // orchestrator was reacting to).
   const successfulModuleSteps = result.modules.filter((m) => m.step === 'done');
   if (result.ok && successfulModuleSteps.length > 0) {
-    const refreshedAudit = await runAudit(rebuildAuditDepsForRerun(auditDeps, db));
+    const refreshedAudit = await runAudit(await rebuildAuditDepsForRerun(auditDeps, db));
     result.audit = refreshedAudit;
   }
 
@@ -747,10 +760,10 @@ type AuditDeps = Parameters<typeof runAudit>[0];
  * reflect post-upgrade reality (e.g., a module_versions drift
  * finding for a module we just upgraded is no longer reported).
  */
-export function rebuildAuditDepsForRerun(
+export async function rebuildAuditDepsForRerun(
   original: AuditDeps,
   db: ReturnType<typeof getDb>,
-): AuditDeps {
+): Promise<AuditDeps> {
   const installed = db.select().from(modules).all();
   const upgradeEligibleStates = new Set(['INSTALLED', 'VERIFIED', 'IMPORTED']);
   const upgradable = installed.filter((m) => upgradeEligibleStates.has(m.state));
@@ -763,6 +776,8 @@ export function rebuildAuditDepsForRerun(
     configsByModule.set(c.moduleId, m);
   }
 
+  const { auditModule } = await import('../../module/packaging/audit');
+
   // Backup recency is unchanged across an orchestrator run (only
   // celilo-DB snapshots happen, not per-module backup writes), so
   // we look up each module's prior lastSuccessfulBackupAt by id
@@ -793,6 +808,21 @@ export function rebuildAuditDepsForRerun(
         configs: configsByModule.get(m.id) ?? {},
       })),
     },
+    // Re-MEASURED, not carried over. An upgrade rewrites the installed tree and
+    // the baseline, so the pre-upgrade result describes files that are no
+    // longer on disk. Reusing it would be reporting a stored claim about a
+    // state that has since changed, which is the exact mistake this whole
+    // change exists to remove.
+    moduleIntegrity: {
+      results: await Promise.all(upgradable.map((m) => auditModule(m.id, db))),
+    },
+    detectWithoutConverge: {
+      modules: upgradable.map((m) => ({
+        id: m.id,
+        state: m.state,
+        manifest: m.manifestData as ModuleManifest,
+      })),
+    },
     // Unchanged across an orchestrator run — an upgrade does not reclaim
     // abandoned operations, so re-reading them would be the same rows.
     abandonedOperations: original.abandonedOperations,

package/src/cli/completion.ts

@@ -325,7 +325,15 @@ export async function getCompletions(words: string[], current: number): Promise<
   }
 
   if (command === 'service' && currentIndex === 1) {
-    const subcommands = ['add', 'list', 'verify', 'reconfigure', 'remove', 'config'];
+    const subcommands = [
+      'add',
+      'list',
+      'verify',
+      'reconfigure',
+      'remove',
+      'config',
+      'set-credentials',
+    ];
     return filterSuggestions(subcommands, args[1] || '');
   }
 
@@ -356,6 +364,13 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(serviceIds, args[2] || '');
   }
 
+  // Service set-credentials - complete with service IDs
+  if (command === 'service' && args[1] === 'set-credentials' && currentIndex === 2) {
+    const services = await listContainerServices();
+    const serviceIds = services.map((s) => s.serviceId);
+    return filterSuggestions(serviceIds, args[2] || '');
+  }
+
   // Service config operations
   if (command === 'service' && args[1] === 'config' && currentIndex === 2) {
     const operations = ['get', 'set'];

package/src/cli/index.ts

@@ -109,6 +109,7 @@ import { handleServiceConfigSet } from './commands/service-config-set';
 import { handleServiceList } from './commands/service-list';
 import { handleServiceReconfigure } from './commands/service-reconfigure';
 import { handleServiceRemove } from './commands/service-remove';
+import { handleServiceSetCredentials } from './commands/service-set-credentials';
 import { handleServiceVerify } from './commands/service-verify';
 import { handleStatus } from './commands/status';
 import { handleSubscribersAdd } from './commands/subscribers-add';
@@ -721,6 +722,7 @@ Subcommands:
     Options:
       --zone <zone>     Filter by network zone
   verify <service-id>   Re-verify a container service connection
+  set-credentials <service-id>  Update a provider endpoint or API credential
   reconfigure <service-id>  Re-run configuration interview (change template, storage, etc.)
   remove <id>           Remove a container service
     Options:
@@ -751,6 +753,9 @@ Examples:
   # Verify a service connection
   celilo service verify proxmox-home-lab
 
+  # Move a Proxmox endpoint while retaining its existing token
+  celilo service set-credentials proxmox-home-lab --api-url https://10.77.20.50:8006
+
   # Get service configuration
   celilo service config get proxmox-home-lab
   celilo service config get proxmox-home-lab name
@@ -1577,9 +1582,9 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'changeset':
         return handleModuleChangeset(parsed.args, parsed.flags);
       case 'audit':
-        return moduleAudit(parsed.args);
+        return moduleAudit(parsed.args, parsed.flags);
       case 'verify':
-        return moduleVerify(parsed.args);
+        return moduleVerify(parsed.args, parsed.flags);
       case 'config': {
         // Config requires additional subcommand (set/get)
         const configSubcommand = parsed.args[0];
@@ -1750,6 +1755,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleServiceVerify(parsed.args, parsed.flags);
     }
 
+    if (parsed.subcommand === 'set-credentials') {
+      return handleServiceSetCredentials(parsed.args, parsed.flags);
+    }
+
     if (parsed.subcommand === 'reconfigure') {
       return handleServiceReconfigure(parsed.args, parsed.flags);
     }

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

@@ -56,12 +56,12 @@ export type ModalState =
 /**
  * Per-category progress state — drives the analyzing modal's
  * fuel-gauges. `done` carries the verdict so the row can show the
- * right icon (✓ clean / ▲ drift / × blocked).
+ * right icon (✓ clean / ? unmeasured / ▲ drift / × blocked).
  */
 export type CategoryStatus =
   | 'pending'
   | 'running'
-  | { kind: 'done'; verdict: 'clean' | 'drift' | 'blocked' };
+  | { kind: 'done'; verdict: 'clean' | 'unmeasured' | 'drift' | 'blocked' };
 
 /**
  * The full set of categories the audit emits — used to seed the
@@ -90,9 +90,13 @@ export const ALL_CATEGORIES: readonly DriftCategory[] = [
   'transport_reads',
   'trusted_sources',
   'interface_classification',
+  'module_integrity',
+  'detect_without_converge',
 ];
 
 export const CATEGORY_LABELS: Record<DriftCategory, string> = {
+  module_integrity: 'Module integrity',
+  detect_without_converge: 'Drift without converge',
   interface_classification: 'Firewall interfaces',
   cli_version: 'CLI version',
   schema: 'Schema migrations',
@@ -181,7 +185,11 @@ export type AuditTuiAction =
   | { type: 'select-finding'; index: number }
   // Per-category audit-progress lifecycle.
   | { type: 'category-start'; category: DriftCategory }
-  | { type: 'category-end'; category: DriftCategory; verdict: 'clean' | 'drift' | 'blocked' }
+  | {
+      type: 'category-end';
+      category: DriftCategory;
+      verdict: 'clean' | 'unmeasured' | 'drift' | 'blocked';
+    }
   | { type: 'reset-category-progress' };
 
 const PANE_ORDER: PaneId[] = ['summary', 'categories', 'findings', 'detail', 'log'];

package/src/cli/tui/audit-tui.tsx

@@ -129,11 +129,17 @@ export function AuditTui({ source, theme: themeName }: Props) {
         return;
       }
       const findings = event.findings ?? [];
-      const verdict: 'clean' | 'drift' | 'blocked' = findings.some((f) => f.severity === 'blocked')
+      // Same ranking as `computeVerdict`: an unmeasured category is not clean
+      // and is not the same statement as a measured difference (D7).
+      const verdict: 'clean' | 'unmeasured' | 'drift' | 'blocked' = findings.some(
+        (f) => f.severity === 'blocked',
+      )
         ? 'blocked'
-        : findings.length > 0
-          ? 'drift'
-          : 'clean';
+        : findings.some((f) => f.severity === 'unmeasured')
+          ? 'unmeasured'
+          : findings.length > 0
+            ? 'drift'
+            : 'clean';
       dispatch({ type: 'category-end', category: event.category, verdict });
     };
 

package/src/cli/tui/icons.ts

@@ -8,12 +8,16 @@ export interface SeverityVisual {
 
 export const SEVERITY_VISUALS: Record<DriftSeverity, SeverityVisual> = {
   blocked: { icon: '×', color: 'red', label: 'BLOCKED' },
+  // Deliberately NOT green and NOT gray. An unmeasured check is not a pass and
+  // is not a reminder — it is a hole in what celilo knows.
+  unmeasured: { icon: '?', color: 'yellow', label: 'UNMEASURED' },
   drift: { icon: '▲', color: 'yellow', label: 'DRIFT' },
   todo: { icon: '➤', color: 'gray', label: 'TODO' },
 };
 
 export const VERDICT_VISUALS: Record<AuditVerdict, SeverityVisual> = {
   BLOCKED: { icon: '×', color: 'red', label: 'BLOCKED' },
+  UNKNOWN: { icon: '?', color: 'yellow', label: 'UNKNOWN' },
   DRIFT: { icon: '▲', color: 'yellow', label: 'DRIFT' },
   READY: { icon: '✓', color: 'green', label: 'READY' },
 };
@@ -23,6 +27,9 @@ export const VERDICT_VISUALS: Record<AuditVerdict, SeverityVisual> = {
 // what actually needs attention.
 export function severityRank(s: DriftSeverity): number {
   if (s === 'blocked') return 0;
-  if (s === 'drift') return 1;
-  return 2; // todo
+  // Above drift, for the same reason UNKNOWN outranks DRIFT: you cannot act on
+  // a diff you are not sure you have.
+  if (s === 'unmeasured') return 1;
+  if (s === 'drift') return 2;
+  return 3; // todo
 }

package/src/cli/tui/modals/analyzing.tsx

@@ -36,6 +36,9 @@ function StatusRow({ category, status }: { category: string; status: CategorySta
   if (status.verdict === 'clean') {
     return <Text color="green">✓ {padded}clean</Text>;
   }
+  if (status.verdict === 'unmeasured') {
+    return <Text color="yellow">? {padded}unmeasured</Text>;
+  }
   if (status.verdict === 'drift') {
     return <Text color="yellow">▲ {padded}drift</Text>;
   }

package/src/db/client.ts

@@ -4,8 +4,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { BUSY_TIMEOUT_MS, ensureWalMode } from '@celilo/event-bus/wal';
 import { drizzle } from 'drizzle-orm/bun-sqlite';
-import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
 import { getDbPath } from '../config/paths';
+import { runMigrationsOn } from './migrate';
 import * as schema from './schema';
 
 /**
@@ -83,15 +83,17 @@ export function createDbClient(config?: Partial<DatabaseConfig>) {
   // idempotent: it applies every migration newer than the latest recorded in
   // `__drizzle_migrations` and no-ops once current.
   //
-  // One-time caveat (ISS-0100): an existing DB from the hand-list era has a
-  // frozen `__drizzle_migrations` watermark; it must be remediated by hand
-  // (stamp the watermark to the latest migration + create any missing table)
-  // BEFORE this code opens it, or migrate() re-runs already-applied migrations
-  // and throws. `celilo system doctor` (checkSchemaDrift) detects the drift.
+  // A DB from the hand-list era has a frozen `__drizzle_migrations` watermark,
+  // so drizzle re-runs already-applied migrations and throws (celilo#169).
+  // runMigrationsOn repairs that itself where the schema is already complete.
+  // It has to happen HERE and not only in `celilo system migrate`, because
+  // that command reaches its own repair through getDb() — this line — and so
+  // would die before getting there. A PARTIALLY applied schema still throws
+  // and still needs a human. `celilo system doctor` (checkSchemaDrift) detects
+  // the drift.
   if (!readonly) {
     try {
-      const migrationsFolder = findMigrationsFolder();
-      migrate(db, { migrationsFolder });
+      runMigrationsOn(db);
     } catch (error) {
       console.error('Failed to run migrations:', error);
       throw error;

package/src/db/migrate.test.ts

@@ -0,0 +1,147 @@
+/**
+ * The frozen-watermark recurrence gate (celilo#169).
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { 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 });
+      }
+    }
+  });
+
+  /**
+   * 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([]);
+  });
+});

package/src/db/migrate.ts

@@ -1,14 +1,82 @@
+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 { findSchemaDrift } from './schema-introspection';
+
+/**
+ * Record every migration past the ledger's watermark as applied, running none
+ * of them. Only safe when the caller has already established that the schema
+ * the code declares is entirely present.
+ *
+ * Replaying the statements instead would be wrong, and quietly so. Migrations
+ * are not idempotent: `0021_dns_registration_consumers` rebuilds a table by
+ * copying it aside, `DROP TABLE`-ing the original and renaming the copy over
+ * it. Run that against a schema that is already current and it drops a live
+ * table. Skipping the statements that fail with "already exists" does not save
+ * you either, because `DROP` and `INSERT ... SELECT` do not fail that way.
+ *
+ * So the ledger is corrected and the schema is left alone.
+ */
+function stampLedgerAsApplied(sqlite: Database, migrationsFolder: string): void {
+  const newest = sqlite
+    .query<{ created_at: number }, []>(
+      'SELECT created_at FROM `__drizzle_migrations` ORDER BY created_at DESC LIMIT 1',
+    )
+    .get();
+  const watermark = Number(newest?.created_at ?? 0);
+
+  sqlite.run('BEGIN');
+  try {
+    for (const migration of readMigrationFiles({ migrationsFolder })) {
+      if (migration.folderMillis <= watermark) continue;
+      sqlite.run('INSERT INTO `__drizzle_migrations` ("hash", "created_at") VALUES (?, ?)', [
+        migration.hash,
+        migration.folderMillis,
+      ]);
+    }
+    sqlite.run('COMMIT');
+  } catch (error) {
+    sqlite.run('ROLLBACK');
+    throw error;
+  }
+}
 
 /**
  * Apply pending drizzle migrations to an open DB. Idempotent — drizzle applies
  * only migrations newer than the latest recorded in `__drizzle_migrations`.
  * The single migration mechanism (ISS-0100); createDbClient also calls this
  * shape on open (auto-migrate).
+ *
+ * The stock migrator runs first and handles every database celilo has written
+ * since ISS-0100, so a healthy box takes exactly the path it took before.
+ *
+ * It fails on one database celilo did not write: one from the imperative
+ * hand-list era, where schema changes were applied directly and
+ * `__drizzle_migrations` never recorded them. Its ledger remembers an old
+ * migration while the objects of every later one are already there, and
+ * drizzle — being watermark-only — re-runs them and dies on the first
+ * `ALTER TABLE ... ADD`. The throw happens inside `createDbClient`, so every
+ * celilo command on that box fails at database open. celilo-mgr, the one box
+ * in that state, was remediated by hand (celilo#169); this is so the next one
+ * is not.
+ *
+ * The repair is only attempted when the schema the code declares is ALREADY
+ * COMPLETE, because that is the one case with an unambiguous answer: every
+ * migration has plainly run, so the ledger is what is wrong. A database missing
+ * some of it is the genuinely hard case — celilo-mgr had 0011's column and not
+ * 0010's table — and there is no safe automatic answer, so it keeps failing
+ * with drizzle's own error and a human decides.
  */
 export function runMigrationsOn(db: DbClient): void {
-  migrate(db, { migrationsFolder: findMigrationsFolder() });
+  const migrationsFolder = findMigrationsFolder();
+  try {
+    migrate(db, { migrationsFolder });
+  } catch (error) {
+    const drift = findSchemaDrift(db.$client);
+    if (drift.missingTables.length > 0 || drift.missingColumns.length > 0) throw error;
+    stampLedgerAsApplied(db.$client, migrationsFolder);
+  }
 }
 
 /**