@north-light/crouter 0.3.233 → 0.3.235

package/dist/core/canvas/migrations.js

@@ -0,0 +1,1339 @@
+// canvas.db's versioned schema chain — the FIRST of this repo's three
+// migration homes. This module owns the v1..vN sequence gated by
+// `PRAGMA user_version`: schema DDL, one-time data backfills, and the
+// journaled on-disk-lane splice (`../../migrations/registry.ts`'s
+// `journaled` entries, appended at the tail of `MIGRATIONS`). A step here
+// runs inside `db.ts`'s per-open `migrate()`, exactly once per database,
+// transactionally.
+//
+// The other two homes:
+//   - `../../migrations/registry.ts` — the `STATE_MIGRATIONS` registry for
+//     on-disk memory documents, profile manifests, and the corpus lane,
+//     driven by `crtr sys migrate`. Its registrants may import ONLY
+//     fs/frontmatter utilities — never canvas-db or canvas accessors — so
+//     the file stays legal in every CLI leaf's import graph. That is why
+//     this chain (which reads node meta, queries other tables mid-step, and
+//     builds shell commands from canvas data) is NOT a registrant there.
+//   - `../../daemon/boot-migrations.ts` — filesystem repairs that run
+//     unconditionally at every daemon boot, outside any version gate
+//     (idempotent by their own convergence, not `user_version`).
+//
+// `db.ts` itself keeps only connection management (`openDb`/`withCanvasWrite`
+// /`closeDb`) and re-exports `migrate`/`MIGRATIONS` from here so external
+// imports are unaffected by this split.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { crtrHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
+import { STATE_MIGRATIONS } from '../../migrations/registry.js';
+import { customExtensionPaths } from './extensions.js';
+import { updateJsonFileDurably } from './meta-file.js';
+// Schema as a forward-only migration list
+//
+// The schema is the migration list: one place a schema change is expressed,
+// one gate (`PRAGMA user_version`) that applies it. `migrate()` runs every
+// pending step in order and bumps `user_version` after each, so a fresh db and
+// the live fleet (all at `user_version 0`) converge on the same final shape.
+// Migrations are append-only and forward-only — never edit a shipped step.
+/** v1 — the baseline tables + indexes. `IF NOT EXISTS` makes this a no-op on
+ *  any existing db (the live fleet already has these tables). */
+function baselineSchema(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id    TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  kind       TEXT NOT NULL,
+  mode       TEXT NOT NULL DEFAULT 'base',
+  lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+  status     TEXT NOT NULL DEFAULT 'active',
+  cwd        TEXT NOT NULL,
+  parent     TEXT,
+  created    TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  type     TEXT NOT NULL,           -- 'subscribes_to' | 'spawned_by'
+  from_id  TEXT NOT NULL,
+  to_id    TEXT NOT NULL,
+  active   INTEGER NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL,
+  PRIMARY KEY (type, from_id, to_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
+`);
+}
+/** A table's current columns, used to make additive migrations safe to re-run
+ *  against a partially applied schema. Shared across every table this chain
+ *  alters in place (`nodes`, `consult_outbox`, `crons`) instead of each step
+ *  hand-rolling its own `PRAGMA table_info` + `Set` build. */
+function tableColumns(db, table) {
+    return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((r) => r.name));
+}
+function addColumnIfMissing(db, columns, name, ddl) {
+    if (columns.has(name))
+        return;
+    db.exec(ddl);
+    columns.add(name);
+}
+/** `nodes`-table convenience alias — every existing call site names it this
+ *  way, and the table this chain adds columns to most is `nodes`. */
+function nodeColumns(db) {
+    return tableColumns(db, 'nodes');
+}
+const addNodeColumnIfMissing = addColumnIfMissing;
+/** v2 — the additive runtime columns: `intent, pi_pid, window, tmux_session`.
+ *  `status` already lives in the baseline row, so it is NOT re-added here. All
+ *  four default to NULL; v3 backfills them. */
+function addRuntimeColumns(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'intent', `ALTER TABLE nodes ADD COLUMN intent TEXT;`);
+    addNodeColumnIfMissing(db, columns, 'pi_pid', `ALTER TABLE nodes ADD COLUMN pi_pid INTEGER;`);
+    addNodeColumnIfMissing(db, columns, 'window', `ALTER TABLE nodes ADD COLUMN window TEXT;`);
+    addNodeColumnIfMissing(db, columns, 'tmux_session', `ALTER TABLE nodes ADD COLUMN tmux_session TEXT;`);
+}
+/** v3 — DATA backfill. The runtime fields
+ *  (`intent, pi_pid, window, tmux_session`) become authoritative in the row;
+ *  copy each existing node's values out of its meta.json into the row columns
+ *  once, so the version boundary loses no live state. `status` already mirrors
+ *  the row, so it is not re-copied.
+ *
+ *  LAYERING NOTE — a sanctioned exception: a *data* migration must read
+ *  meta.json, which db.ts normally would not. Reading it
+ *  directly here — via paths.ts, a one-time, clearly-labeled boot-time data
+ *  migration — is the deliberate choice over splitting the `user_version`
+ *  counter across two modules. Idempotent and gated: it runs exactly once at the
+ *  v2→v3 boundary. An UPDATE for a node with no row yet hits 0 rows (harmless). */
+function backfillRuntime(db) {
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return;
+    const upd = db.prepare('UPDATE nodes SET intent = ?, pi_pid = ?, "window" = ?, tmux_session = ? WHERE node_id = ?');
+    for (const id of readdirSync(root)) {
+        const p = nodeMetaPath(id);
+        if (!existsSync(p))
+            continue;
+        let meta;
+        try {
+            meta = JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch {
+            continue; // a single unreadable meta never aborts the migration
+        }
+        upd.run(meta['intent'] ?? null, meta['pi_pid'] ?? null, meta['window'] ?? null, meta['tmux_session'] ?? null, id);
+    }
+}
+/** v4 — edges referential integrity (IRREVERSIBLE table rebuild). Rebuild the
+ *  `edges` table so `from_id`/`to_id` are FOREIGN KEYs to `nodes(node_id)` with
+ *  `ON DELETE CASCADE`: after this, deleting a node can NEVER orphan an edge —
+ *  the schema GCs them, so prune (and any future delete) doesn't have to. The
+ *  cargo-cult `PRAGMA foreign_keys = ON` (openDb) finally enforces something.
+ *
+ *  GOTCHA — pre-existing orphan edges. Nothing ever deleted a node before this
+ *  phase, but manual dir removals / failed spawns can have left `edges` whose
+ *  endpoint has no `nodes` row. Copying those into the FK-constrained table
+ *  would violate the constraint, so the rebuild runs with `foreign_keys = OFF`
+ *  (it MUST be toggled in autocommit — a no-op inside a txn) and the
+ *  INSERT…SELECT FILTERS orphans: only edges whose BOTH endpoints have a row
+ *  survive. `PRAGMA foreign_key_check` then confirms the rebuilt table is clean,
+ *  and a row-count assertion guards that every NON-orphan edge is preserved.
+ *
+ *  CRASH-SAFETY — the whole rebuild is one transaction. A throw ROLLs it back to
+ *  the pre-v4 state (the `edges_new` scratch table and all copies vanish) and
+ *  `user_version` stays at 3, so the next open re-runs v4 cleanly: no half-state.
+ *  Even a crash between COMMIT and the version bump is safe — re-running v4 over
+ *  an already-rebuilt (clean) `edges` is idempotent in effect. */
+function edgesForeignKeyCascade(db) {
+    // Degenerate db with no `edges` table (a real db always has it — v1 created it
+    // — but a hand-seeded fixture may not). Nothing to rebuild; create the
+    // FK-shaped table fresh so the schema still converges, then we're done.
+    const hasEdges = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'edges'")
+        .get() !== undefined;
+    if (!hasEdges) {
+        db.exec(`
+CREATE TABLE edges (
+  type     TEXT NOT NULL,
+  from_id  TEXT NOT NULL,
+  to_id    TEXT NOT NULL,
+  active   INTEGER NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL,
+  PRIMARY KEY (type, from_id, to_id),
+  FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+  FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+`);
+        return;
+    }
+    // FK enforcement must be toggled OUTSIDE a transaction (a no-op within one).
+    db.exec('PRAGMA foreign_keys = OFF;');
+    try {
+        // Non-orphan edges that MUST survive the rebuild (both endpoints present).
+        const expected = db
+            .prepare(`SELECT COUNT(*) AS n FROM edges
+           WHERE from_id IN (SELECT node_id FROM nodes)
+             AND to_id   IN (SELECT node_id FROM nodes)`)
+            .get().n;
+        db.exec('BEGIN');
+        try {
+            db.exec(`
+CREATE TABLE edges_new (
+  type     TEXT NOT NULL,
+  from_id  TEXT NOT NULL,
+  to_id    TEXT NOT NULL,
+  active   INTEGER NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL,
+  PRIMARY KEY (type, from_id, to_id),
+  FOREIGN KEY (from_id) REFERENCES nodes(node_id) ON DELETE CASCADE,
+  FOREIGN KEY (to_id)   REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+INSERT INTO edges_new (type, from_id, to_id, active, created)
+  SELECT type, from_id, to_id, active, created FROM edges
+  WHERE from_id IN (SELECT node_id FROM nodes)
+    AND to_id   IN (SELECT node_id FROM nodes);
+DROP TABLE edges;
+ALTER TABLE edges_new RENAME TO edges;
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+`);
+            // Row-count assertion: every non-orphan edge preserved across the rebuild.
+            const after = db.prepare('SELECT COUNT(*) AS n FROM edges').get().n;
+            if (after !== expected) {
+                throw new Error(`edges FK rebuild lost rows: expected ${expected} non-orphan edge(s), got ${after}`);
+            }
+            // Belt-and-suspenders: the rebuilt table must hold no FK violations (the
+            // orphan filter above should guarantee this).
+            const violations = db.prepare('PRAGMA foreign_key_check').all();
+            if (violations.length > 0) {
+                throw new Error(`edges FK rebuild left ${violations.length} foreign-key violation(s)`);
+            }
+            db.exec('COMMIT');
+        }
+        catch (e) {
+            db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+    finally {
+        db.exec('PRAGMA foreign_keys = ON;');
+    }
+}
+/** v5 — additive runtime column `pane`: LOCATION's authoritative handle, the
+ *  durable tmux `%pane_id` a node's pane is anchored on. Unlike the derived
+ *  `window`/`tmux_session` cache (v2), the pane id survives a user
+ *  `move-pane`/`join-pane`/`break-pane` and window renumbering, so a later step
+ *  reconciles window/session FROM it and uses pane-existence for liveness.
+ *  Defaults NULL — nothing reads it until the placement layer lands, so this
+ *  observes no behavior change. Additive, forward-only. */
+function addPaneColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'pane', `ALTER TABLE nodes ADD COLUMN pane TEXT;`);
+}
+/** v6 — the `focuses` table: durable, PLURAL on-screen viewports, one row per
+ *  viewport (Q7 widens canvas.db from "topology" to "topology + focuses"). Each
+ *  row is anchored on the durable tmux `%pane_id`; `session` is a derived cache
+ *  reconciled from the pane; `node_id` is UNIQUE so a node occupies at most one
+ *  focus (Q5). The focuses table is the CANONICAL focus store — there is no
+ *  focus.ptr file and no dual-write bridge; placement writes focus rows directly. */
+function addFocusesTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS focuses (
+  focus_id  TEXT PRIMARY KEY,   -- stable internal id for the viewport
+  pane      TEXT,               -- the durable %pane_id realizing the focus
+  session   TEXT,               -- derived cache of the user session (reconciled from pane)
+  node_id   TEXT NOT NULL UNIQUE -- the node shown; UNIQUE → a node occupies <=1 focus
+);
+`);
+}
+/** v7 — the `wakeups` table: durable store for scheduled wake-ups (the
+ *  scheduled-wakeups feature). One row per armed wake. `node_id` is the TARGET
+ *  and the node-anchored cancel anchor — it carries a `ON DELETE CASCADE` FK to
+ *  `nodes(node_id)` so a pruned/deleted node's node-anchored wakes are reaped in
+ *  the same transaction (mirroring the edges v4 cascade; works because
+ *  `PRAGMA foreign_keys = ON` is set at every open). NULL `node_id` = a
+ *  canvas-detached wake (deferred spawn / spawn-cron) that survives.
+ *
+ *  `owner_id` is the ARMER, set on EVERY row, and is deliberately a PLAIN indexed
+ *  column with NO FK (design D1/D2): an FK on `owner_id` would cascade-drop a
+ *  crashed-then-pruned armer's detached cron, violating Invariant E. A detached
+ *  wake is never reaped by node-row cascade.
+ *
+ *  `fire_at` is an ISO 8601 UTC string for the NEXT occurrence, so the per-tick
+ *  due query is a lexicographic `<=` compare. The partial unique index
+ *  `idx_wakeups_deadline` enforces ≤1 deadline per node. Additive, forward-only. */
+function appendWakeupsTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS wakeups (
+  wakeup_id  TEXT PRIMARY KEY,
+  node_id    TEXT,                       -- TARGET + node-anchored cancel anchor; NULL = canvas-detached
+  owner_id   TEXT NOT NULL,              -- ARMER; set on EVERY row. PLAIN column, NO FK (design D1/D2)
+  fire_at    TEXT NOT NULL,              -- ISO 8601 UTC; NEXT occurrence; lexicographic <=
+  kind       TEXT NOT NULL,              -- 'bare' | 'noted' | 'deadline' | 'spawn'
+  recur      TEXT,                       -- NULL = one-shot; else the pinned recur JSON
+  payload    TEXT,                       -- JSON per kind (shared contracts)
+  created    TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_wakeups_fire  ON wakeups(fire_at);                 -- per-tick due query
+CREATE INDEX IF NOT EXISTS idx_wakeups_node  ON wakeups(node_id);                 -- by-node cancel / list
+CREATE INDEX IF NOT EXISTS idx_wakeups_owner ON wakeups(owner_id);               -- by-owner reap (ruling A)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_wakeups_deadline ON wakeups(node_id) WHERE kind = 'deadline';
+`);
+}
+/** v9 — generalize the `wakeups` table (v7) into the `triggers` table (the
+ *  unified node-trigger-grammar substrate). The old `kind` axis (bare/noted/
+ *  deadline/spawn) splits into three orthogonal axes: `action` (what enacts:
+ *  'msg'|'new') x `action_mode` (how: 'inbox_message'|'fresh_revive'|
+ *  'deadline_message'|'node_birth') x `trigger_type` (when: 'at'|'every'|
+ *  'when'|'until') — so a daemon-owned predicate (`--when`) trigger can live in
+ *  the same table as a clock trigger. Predicate-only columns (`when_script`
+ *  through `last_stderr`) are additive null/idle for every migrated clock row.
+ *
+ *  Migration mapping, preserving every existing `wakeup_id` as `trigger_id`
+ *  (so an old wake's id stays cancelable): bare→fresh_revive, noted→
+ *  inbox_message, deadline→deadline_message (trigger_type='until'), spawn→
+ *  node_birth. `payload` JSON carries over unchanged — the old per-kind
+ *  payload shapes (plus SpawnChildOpts) map 1:1 onto the intermediate row, so
+ *  no JSON transform is needed. The `wakeups` table is then DROPPED — not kept
+ *  as a parallel table. Additive, forward-only. */
+function migrateWakeupsToTriggers(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS triggers (
+  trigger_id        TEXT PRIMARY KEY,
+  owner_id          TEXT NOT NULL,
+  node_id           TEXT,                       -- TARGET + node-anchored cancel anchor; NULL = canvas-detached
+  action            TEXT NOT NULL,               -- 'msg' | 'new'
+  action_mode       TEXT NOT NULL,               -- 'inbox_message' | 'fresh_revive' | 'deadline_message' | 'node_birth'
+  trigger_type      TEXT NOT NULL,               -- 'at' | 'every' | 'when' | 'until'
+  fire_at           TEXT,                        -- clock triggers: NEXT occurrence, ISO 8601 UTC; lexicographic <=
+  recur             TEXT,                        -- NULL = one-shot; else the recur JSON the daemon advances
+  payload           TEXT,                        -- JSON action payload, discriminated by action_mode
+  when_script       TEXT,                        -- predicate triggers: the --when bash source
+  eval_every        TEXT,                        -- predicate triggers: evaluation cadence (recur-shaped JSON)
+  next_eval_at      TEXT,                        -- predicate triggers: next evaluation instant
+  timeout_at        TEXT,                        -- predicate triggers: wall-clock expiry
+  eval_state        TEXT NOT NULL DEFAULT 'idle', -- 'idle' | 'running'
+  eval_started_at   TEXT,
+  eval_pid          INTEGER,
+  eval_lease_owner  TEXT,
+  last_eval_at      TEXT,
+  last_exit         INTEGER,
+  last_stderr       TEXT,
+  created           TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_fire  ON triggers(fire_at);                  -- clock per-tick due query
+CREATE INDEX IF NOT EXISTS idx_triggers_node  ON triggers(node_id);                  -- by-node cancel / list
+CREATE INDEX IF NOT EXISTS idx_triggers_owner ON triggers(owner_id);                 -- by-owner reap
+CREATE INDEX IF NOT EXISTS idx_triggers_eval  ON triggers(eval_state, next_eval_at); -- predicate due query
+CREATE UNIQUE INDEX IF NOT EXISTS idx_triggers_deadline ON triggers(node_id) WHERE action_mode = 'deadline_message';
+
+INSERT INTO triggers (trigger_id, owner_id, node_id, action, action_mode, trigger_type, fire_at, recur, payload, created)
+SELECT
+  wakeup_id,
+  owner_id,
+  node_id,
+  CASE kind WHEN 'spawn' THEN 'new' ELSE 'msg' END,
+  CASE kind
+    WHEN 'bare' THEN 'fresh_revive'
+    WHEN 'noted' THEN 'inbox_message'
+    WHEN 'deadline' THEN 'deadline_message'
+    WHEN 'spawn' THEN 'node_birth'
+  END,
+  CASE WHEN kind = 'deadline' THEN 'until' WHEN recur IS NULL THEN 'at' ELSE 'every' END,
+  fire_at,
+  recur,
+  payload,
+  created
+FROM wakeups;
+
+DROP TABLE wakeups;
+`);
+}
+/** v8 — additive identity column `host_kind`: which HOST launches + supervises a
+ *  node — `'tmux'` (a pane) or `'broker'` (the headless in-process engine). It is
+ *  durable IDENTITY mirrored from meta.json like `cwd` (NOT runtime like `pane`),
+ *  so it survives an index rebuild via the `IDENTITY_KEYS`/`upsertRow` path.
+ *  Defaults NULL ⇒ `'tmux'` (every existing node is tmux-hosted); no data
+ *  backfill. Additive, forward-only. */
+function addHostKindColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'host_kind', `ALTER TABLE nodes ADD COLUMN host_kind TEXT;`);
+}
+/** v10 — the `canvas_meta` key/value table: a single durable place for
+ *  small, cross-process canvas-wide scalars that aren't node rows. First user:
+ *  the boot marker (boot.ts), which records the last-seen kernel boot identity
+ *  so boot-liveness reconciliation is a single-writer SQLite transaction on
+ *  this row rather than a race-prone JSON file. Additive, forward-only. */
+function addCanvasMetaTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS canvas_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`);
+}
+/** v11 — additive identity column `profile_id`: the profile-directory id
+ *  (`<slug>-<id>`) a node runs under, chosen once at spawn (inherited from the
+ *  spawner, or `--profile`). Durable IDENTITY mirrored from meta.json like
+ *  `cwd`/`host_kind` (NOT runtime like `pane`), so it survives an index rebuild
+ *  via the `IDENTITY_KEYS`/`upsertRow` path. Defaults NULL for historical
+ *  root/no-profile rows; new root conversations use the stable root profile
+ *  id instead. No data backfill. Additive, forward-only. */
+function addProfileIdColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'profile_id', `ALTER TABLE nodes ADD COLUMN profile_id TEXT;`);
+}
+/** v12 — additive runtime column `pi_pid_identity`: the LAUNCH-time process-
+ *  identity fingerprint (`pid.ts`'s `composeIdentity`) recorded alongside
+ *  `pi_pid` (v2) by `recordPid`, so `headlessBrokerHost.teardown()` can refuse
+ *  to signal a `pi_pid` the OS has since recycled for an unrelated process
+ *  (see `NodeRuntime.pi_pid_identity`).
+ *  Defaults NULL ⇒ no baseline ⇒ the guard fails open, exactly like a node
+ *  booted before this column existed. No data backfill: an existing `pi_pid`
+ *  with no recorded identity simply has no launch-time baseline to compare
+ *  against. Additive, forward-only. */
+function addPidIdentityColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'pi_pid_identity', `ALTER TABLE nodes ADD COLUMN pi_pid_identity TEXT;`);
+}
+/** v13 — mutable controller-message wait state. It belongs with runtime state,
+ * not meta identity: both the waiting node and an incoming sender can settle it. */
+function addMessageWaitColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'waiting_for', `ALTER TABLE nodes ADD COLUMN waiting_for TEXT;`);
+}
+/** v14 — canonical final identity. Existing done rows receive their newest valid
+ * final report once; runtime never infers canonical state from report files. */
+function addCanonicalFinalColumns(db) {
+    const columns = nodeColumns(db);
+    // Metadata-only migration harnesses can legitimately advance user_version on
+    // an otherwise empty database. There is no node index to repair in that case.
+    if (columns.size === 0)
+        return;
+    addNodeColumnIfMissing(db, columns, 'final_report', `ALTER TABLE nodes ADD COLUMN final_report TEXT;`);
+    addNodeColumnIfMissing(db, columns, 'finalized_at', `ALTER TABLE nodes ADD COLUMN finalized_at TEXT;`);
+    const rows = db.prepare("SELECT node_id FROM nodes WHERE status = 'done' AND final_report IS NULL").all();
+    const update = db.prepare('UPDATE nodes SET final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL');
+    for (const { node_id } of rows) {
+        const dir = join(nodesRoot(), node_id, 'reports');
+        if (!existsSync(dir))
+            continue;
+        let winner = null;
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith('.md'))
+                continue;
+            try {
+                const raw = readFileSync(join(dir, name), 'utf8');
+                const match = /^---\nnode: [^\n]+\nkind: final\nts: ([^\n]+)\n---\n/.exec(raw);
+                if (match === null || Number.isNaN(Date.parse(match[1])))
+                    continue;
+                const candidate = { name, ts: match[1] };
+                if (winner === null || candidate.ts > winner.ts || (candidate.ts === winner.ts && candidate.name > winner.name))
+                    winner = candidate;
+            }
+            catch { /* malformed historical reports are not canonical */ }
+        }
+        if (winner !== null)
+            update.run(winner.name, winner.ts, node_id);
+    }
+}
+/** v15 — canonicalize persisted launch metadata after a retired generation-root
+ * experiment. Canvas hooks are launch-owned; retain every genuine custom extra. */
+function normalizePersistedLaunchExtensions(_db) {
+    const root = nodesRoot();
+    if (!existsSync(root))
+        return;
+    for (const id of readdirSync(root)) {
+        const path = nodeMetaPath(id);
+        if (!existsSync(path))
+            continue;
+        updateJsonFileDurably(path, (meta) => {
+            const launch = meta['launch'];
+            if (typeof launch !== 'object' || launch === null || Array.isArray(launch))
+                return false;
+            const extensions = launch.extensions;
+            if (!Array.isArray(extensions) || !extensions.every((value) => typeof value === 'string'))
+                return false;
+            const custom = customExtensionPaths(extensions);
+            if (custom.length === extensions.length)
+                return false;
+            launch.extensions = custom;
+            return true;
+        });
+    }
+}
+/** v17 — monotonically identifies each explicit wait arm. Delivery settlement
+ * uses this watermark as well as the controller identity. */
+function addMessageWaitGenerationColumn(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'waiting_for_generation', `ALTER TABLE nodes ADD COLUMN waiting_for_generation INTEGER NOT NULL DEFAULT 0;`);
+}
+/** v18 — create the historical `consult_outbox` table. The old schema stays
+ *  replayable for existing databases until its later migration removes it.
+ *  No current user-facing flow creates rows. Its remaining diagnostics and
+ *  retention readers keep armed/pending legacy rows from losing their node
+ *  before startup or crash reconciliation terminalizes those rows. */
+function addHumanWorkOutboxTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS consult_outbox (
+  node_id      TEXT PRIMARY KEY,   -- legacy work node id
+  dir          TEXT NOT NULL,      -- legacy ticket directory
+  root         TEXT NOT NULL,      -- legacy registered root
+  request_id   TEXT NOT NULL,      -- legacy request id
+  status       TEXT NOT NULL,      -- armed | pending | acked | errored | canceled
+  final_report TEXT,               -- legacy final report basename
+  updated_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_status ON consult_outbox(status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_dir ON consult_outbox(dir);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_dir_request_status ON consult_outbox(dir, request_id, status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_dir_status ON consult_outbox(dir, status);
+`);
+}
+/** v19 — generalize the physical `consult_outbox` ABI into human work without
+ * changing its table name. Existing rows and old literal follow-up inserts gain
+ * `follow_up` by default; Visual reserves namespaced statuses so old
+ * `armed`/`pending` reconcilers cannot select it. */
+function addHumanWorkColumns(db) {
+    const columns = tableColumns(db, 'consult_outbox');
+    const add = (name, ddl) => addColumnIfMissing(db, columns, name, ddl);
+    add('work_kind', "ALTER TABLE consult_outbox ADD COLUMN work_kind TEXT NOT NULL DEFAULT 'follow_up';");
+    add('interaction_id', 'ALTER TABLE consult_outbox ADD COLUMN interaction_id TEXT;');
+    add('generation_id', 'ALTER TABLE consult_outbox ADD COLUMN generation_id TEXT;');
+    add('interaction_snapshot', 'ALTER TABLE consult_outbox ADD COLUMN interaction_snapshot TEXT;');
+    add('handler_command', 'ALTER TABLE consult_outbox ADD COLUMN handler_command TEXT;');
+    add('handler_args_json', 'ALTER TABLE consult_outbox ADD COLUMN handler_args_json TEXT;');
+    add('claim_token', 'ALTER TABLE consult_outbox ADD COLUMN claim_token TEXT;');
+    db.exec(`
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_human_work_status ON consult_outbox(work_kind, status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_human_work_dir_status ON consult_outbox(dir, work_kind, status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_human_work_request_status ON consult_outbox(dir, request_id, work_kind, status);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_consult_outbox_visual_request ON consult_outbox(dir, request_id, work_kind) WHERE work_kind = 'visual';
+`);
+}
+/** v20 — index `nodes(parent)` and `nodes(created)`. `listNodes()`'s
+ *  `ORDER BY created` and the `children = rows.filter(r => r.parent === id)`
+ *  child lookup (`daemon/api/handlers/nodes.ts`'s `edgesFor`) were both
+ *  full-table scans under the daemon's single event loop; a live fleet's
+ *  `GET /v1/nodes/:id` measured >15s under concurrent-viewer load. Additive,
+ *  forward-only — `IF NOT EXISTS` makes re-running a no-op. */
+function addNodeParentCreatedIndexes(db) {
+    db.exec(`
+CREATE INDEX IF NOT EXISTS idx_nodes_parent  ON nodes(parent);
+CREATE INDEX IF NOT EXISTS idx_nodes_created ON nodes(created);
+`);
+}
+/** v21 — the `crons` + `cron_runs` tables. One scheduling primitive: run this
+ *  bash, then. Key contracts pinned by the spec:
+ *   - `created_by` is provenance ONLY — no FK, never cascades; a lifelong job
+ *     is not hostage to the window that typed it.
+ *   - `anchor_node` is the OPT-IN node coupling, carrying the one FK
+ *     (ON DELETE CASCADE); NULL = outlives every node on the canvas.
+ *   - the partial unique index `idx_crons_deadline` is the ≤1-deadline-per-node
+ *     backstop for the future `node wait deadline` sugar (cancel_on_wake rows).
+ *   - execution context (cwd/env/profile) is SNAPSHOTTED at arm time, never
+ *     resolved at run time.
+ *   - `cron_runs` is a bounded ring (last 20 per cron, pruned by the DAO's
+ *     recordCronRun).
+ *  Additive and forward-only. */
+function addCronsTables(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS crons (
+  cron_id          TEXT PRIMARY KEY,
+  name             TEXT NOT NULL,          -- agent-legible label; how it shows in list
+  created_by       TEXT,                   -- provenance only, NO FK, never cascades
+  command          TEXT NOT NULL,          -- the bash
+
+  fire_at          TEXT NOT NULL,          -- next occurrence, ISO 8601 UTC; lexicographic <=
+  recur            TEXT,                   -- NULL = one-shot; else recur JSON the daemon advances
+  tz               TEXT,                   -- IANA zone for calendar cadence
+  expires_at       TEXT,                   -- clock bound; row is deleted when passed
+
+  anchor_node      TEXT,                   -- opt-in node coupling; NULL = outlives every node
+  cancel_on_wake   INTEGER NOT NULL DEFAULT 0,  -- deleted when anchor revives (deadline rule)
+
+  cwd              TEXT NOT NULL,          -- snapshotted at creation
+  env_json         TEXT,
+  profile          TEXT,
+  scope            TEXT NOT NULL DEFAULT 'profile',   -- 'profile' | 'global'
+
+  run_timeout_s    INTEGER NOT NULL DEFAULT 300,
+  overlap          TEXT NOT NULL DEFAULT 'skip',      -- 'skip' | 'queue' | 'replace'
+  on_output        TEXT NOT NULL DEFAULT 'on-failure',-- 'silent'|'on-failure'|'always'|'on-change'
+  sink             TEXT NOT NULL,          -- JSON: {node}|{spawn,kind,...}|{human}
+  tier             TEXT NOT NULL DEFAULT 'normal',
+  last_output_hash TEXT,                   -- drives 'on-change'
+
+  state            TEXT NOT NULL DEFAULT 'active',    -- 'active' | 'paused'
+  run_state        TEXT NOT NULL DEFAULT 'idle',      -- 'idle' | 'running'
+  run_pid          INTEGER,
+  run_pid_identity TEXT,                  -- v23: launch-time pid fingerprint; a kill requires a MATCH
+  run_started_at   TEXT,
+  run_lease_owner  TEXT,
+  run_out_of_band  INTEGER NOT NULL DEFAULT 0,        -- v24: this lease is a manual cron run, not a scheduled fire
+
+  created          TEXT NOT NULL,
+  updated          TEXT NOT NULL,
+  FOREIGN KEY (anchor_node) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_crons_deadline ON crons(anchor_node) WHERE cancel_on_wake = 1;
+CREATE INDEX IF NOT EXISTS idx_crons_fire ON crons(fire_at);
+
+CREATE TABLE IF NOT EXISTS cron_runs (                -- bounded ring, last 20 per cron
+  run_id       TEXT PRIMARY KEY,
+  cron_id      TEXT NOT NULL,
+  started      TEXT NOT NULL,
+  finished     TEXT,
+  duration_ms  INTEGER,
+  exit_code    INTEGER,                    -- NULL while running; -1 for timeout kill
+  stdout_head  TEXT,                       -- capped at 4KB
+  stderr_head  TEXT,
+  delivered    TEXT,                       -- what the sink did, or why it didn't
+  FOREIGN KEY (cron_id) REFERENCES crons(cron_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_cron_runs_cron ON cron_runs(cron_id, started);
+`);
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function uniqueHeredocDelimiter(body, stem) {
+    let suffix = 0;
+    while (true) {
+        const delimiter = `${stem}_${suffix}`;
+        if (!body.split('\n').includes(delimiter))
+            return delimiter;
+        suffix++;
+    }
+}
+function heredocCommand(command, body, stem) {
+    const delimiter = uniqueHeredocDelimiter(body, stem);
+    return `${command} <<'${delimiter}'\n${body}\n${delimiter}`;
+}
+/** `payload` was a NULLABLE text column, so NULL, non-string, and legacy or
+ *  hand-edited JSON are all shapes the retired schema declared legal. A schema
+ *  migration must never fail on data shape, so anything unreadable degrades to
+ *  an empty payload; the per-key readers below then decide whether what is left
+ *  is enough to convert the row. */
+function migrationPayload(raw) {
+    if (typeof raw !== 'string')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function requiredString(payload, key, triggerId) {
+    const value = payload[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`trigger ${triggerId} payload requires non-empty ${key}`);
+    }
+    return value;
+}
+function optionalString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/** The same reader over a `triggers` ROW rather than its payload: returns the
+ *  column when it holds a usable string, `undefined` otherwise. */
+function optionalColumn(row, key) {
+    const value = row[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function migratedMessageCommand(target, tier, body, triggerId) {
+    return heredocCommand(`crtr node message send --to ${shellSingleQuote(target)} --tier ${shellSingleQuote(tier)}`, body, `CRTR_MIGRATED_${triggerId.replace(/[^A-Za-z0-9]/g, '_')}`);
+}
+/** A body-less predicate message: the retired daemon filled the body from the
+ *  gate's stdout at fire time (`p.body ?? outcome.stdout`), so the migrated
+ *  script pipes the captured gate output into the send. */
+function migratedGateStdoutMessageCommand(target, tier) {
+    return `printf '%s\\n' "$CRTR_GATE_STDOUT" | crtr node message send --to ${shellSingleQuote(target)} --tier ${shellSingleQuote(tier)}`;
+}
+function migratedSpawnCommand(payload, triggerId) {
+    const flags = [`crtr node new --kind ${shellSingleQuote(requiredString(payload, 'kind', triggerId))}`];
+    const strings = [
+        ['mode', 'mode'],
+        ['cwd', 'cwd'],
+        ['name', 'name'],
+        ['parent', 'parent'],
+        ['worktreeBase', 'worktree'],
+        ['forkFrom', 'fork-from'],
+        ['model', 'model'],
+        ['profile', 'profile'],
+        ['situationalContext', 'situational-context'],
+    ];
+    for (const [key, flag] of strings) {
+        const value = optionalString(payload, key);
+        if (value !== undefined)
+            flags.push(`--${flag} ${shellSingleQuote(value)}`);
+    }
+    if (payload['root'] === true)
+        flags.push('--root');
+    const prompt = requiredString(payload, 'prompt', triggerId);
+    return heredocCommand(flags.join(' '), prompt, `CRTR_MIGRATED_${triggerId.replace(/[^A-Za-z0-9]/g, '_')}`);
+}
+/** The `canvas_meta` key holding the v22 skip ledger: a JSON array of
+ *  `{ trigger_id, reason }` for every retired schedule the migration could not
+ *  express as a cron. Written only when at least one row is skipped. */
+const V22_SKIPPED_META_KEY = 'migration.v22.skipped';
+/** The execution-context cwd for a schedule whose armer is gone. `owner_id`
+ *  carries NO foreign key by design (see v7), so a crashed-then-pruned armer's
+ *  detached schedule is an EXPECTED row, not a corrupt one — it must still
+ *  convert. Falls back to the oldest root node's cwd (the ambient canvas root),
+ *  then to this process's cwd. */
+function ambientMigrationCwd(db) {
+    const root = db
+        .prepare('SELECT cwd FROM nodes WHERE parent IS NULL ORDER BY created LIMIT 1')
+        .get();
+    return (root !== undefined ? optionalColumn(root, 'cwd') : undefined) ?? process.cwd();
+}
+/** Best-effort reap of in-flight predicate evaluations before the table that
+ *  records them is dropped. The retired cancel path killed the evaluation's
+ *  process GROUP; without this the migration would orphan a running gate
+ *  script with nothing left on disk that names it. */
+function reapRunningPredicateEvaluations(db) {
+    let running;
+    try {
+        running = db
+            .prepare("SELECT eval_pid FROM triggers WHERE eval_state = 'running' AND eval_pid IS NOT NULL")
+            .all();
+    }
+    catch {
+        return; // a drifted table shape has no evaluations we can name; never fatal
+    }
+    for (const row of running) {
+        const pid = row['eval_pid'];
+        if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 1)
+            continue;
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            /* the evaluation already exited, or the group is gone — nothing to reap */
+        }
+    }
+}
+/** v22 — migrate each scheduled action into a shell cron, preserving its id and
+ * execution context, then remove the superseded table.
+ *
+ * SKIP-AND-RECORD, never throw. `migrate()` runs on every `openDb()`, so a
+ * migration that hard-fails on data shape would make EVERY crtr process fail to
+ * open the canvas forever. Rows the retired schema declared legal but this step
+ * cannot express (unknown action/timing pairs, a missing fire time, drifted
+ * JSON) are skipped, named in the `canvas_meta` ledger under
+ * `migration.v22.skipped`, and warned about — the schema always advances.
+ * `INSERT OR REPLACE` makes a re-run over already-converted ids converge rather
+ * than collide on the `cron_id` primary key. */
+function migrateTriggersToCrons(db) {
+    const skipped = [];
+    // A db already wedged by an interrupted pre-atomicity run (crons committed,
+    // the table dropped, `user_version` still 21) re-runs this step with nothing
+    // left to convert; it must advance, not throw.
+    const hasTriggers = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'triggers'")
+        .get() !== undefined;
+    if (hasTriggers)
+        reapRunningPredicateEvaluations(db);
+    let rows = [];
+    if (hasTriggers) {
+        try {
+            rows = db.prepare('SELECT * FROM triggers ORDER BY created, trigger_id').all();
+        }
+        catch (err) {
+            // A column-drifted table (no `created`/`trigger_id`) must not brick every
+            // open either: record that its rows were unreadable and advance.
+            skipped.push({
+                trigger_id: '<unreadable table>',
+                reason: `triggers table could not be read: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    const fallbackCwd = ambientMigrationCwd(db);
+    const insert = db.prepare(`
+INSERT OR REPLACE INTO crons (
+  cron_id, name, created_by, command, fire_at, recur, tz, expires_at,
+  anchor_node, cancel_on_wake, cwd, env_json, profile, scope,
+  run_timeout_s, overlap, on_output, sink, tier, created, updated
+) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, NULL, ?, 'profile', ?, 'skip', 'on-failure', '{}', ?, ?, ?)`);
+    for (const row of rows) {
+        const triggerId = optionalColumn(row, 'trigger_id');
+        if (triggerId === undefined) {
+            skipped.push({ trigger_id: '<unidentified row>', reason: 'row carries no trigger_id' });
+            continue;
+        }
+        try {
+            convertTriggerRow(db, insert, row, triggerId, fallbackCwd);
+        }
+        catch (err) {
+            skipped.push({ trigger_id: triggerId, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    if (skipped.length > 0) {
+        db.prepare('INSERT INTO canvas_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(V22_SKIPPED_META_KEY, JSON.stringify(skipped));
+        console.warn(`[canvas migration v22] ${skipped.length} retired schedule(s) could not be converted to crons and were dropped; ` +
+            `see canvas_meta['${V22_SKIPPED_META_KEY}']: ` +
+            skipped.map((entry) => `${entry.trigger_id} (${entry.reason})`).join('; '));
+    }
+    db.exec(`
+DROP INDEX IF EXISTS idx_triggers_fire;
+DROP INDEX IF EXISTS idx_triggers_node;
+DROP INDEX IF EXISTS idx_triggers_owner;
+DROP INDEX IF EXISTS idx_triggers_eval;
+DROP INDEX IF EXISTS idx_triggers_deadline;
+DROP TABLE IF EXISTS triggers;
+`);
+}
+/** Convert ONE retired schedule row into a cron row. Throws only when the row
+ *  cannot be expressed as a cron at all; the caller turns that into a recorded
+ *  skip so the schema still advances. */
+function convertTriggerRow(db, insert, row, triggerId, fallbackCwd) {
+    const ownerId = requiredString(row, 'owner_id', triggerId);
+    // A pruned armer is expected, not corrupt (no FK on `owner_id`, by design):
+    // keep the schedule and snapshot the ambient root cwd instead of its armer's.
+    const owner = db.prepare('SELECT cwd, profile_id FROM nodes WHERE node_id = ?').get(ownerId);
+    const cwd = (owner === undefined ? undefined : optionalColumn(owner, 'cwd')) ?? fallbackCwd;
+    const profile = owner === undefined ? null : optionalColumn(owner, 'profile_id') ?? null;
+    const nodeId = optionalColumn(row, 'node_id') ?? null;
+    const action = requiredString(row, 'action', triggerId);
+    const actionMode = requiredString(row, 'action_mode', triggerId);
+    const triggerType = requiredString(row, 'trigger_type', triggerId);
+    const payload = migrationPayload(row['payload']);
+    const created = optionalColumn(row, 'created') ?? new Date().toISOString();
+    const tier = actionMode === 'deadline_message' ? 'urgent' : optionalString(payload, 'tier') ?? 'normal';
+    const label = optionalString(payload, 'label');
+    let command;
+    let name;
+    // A `--when` schedule could legally omit its body: the retired daemon filled
+    // it from the gate's stdout at fire time. Such a row pipes the captured gate
+    // output into the send instead of carrying a heredoc.
+    let bodyFromGate = false;
+    if (action === 'msg' && (actionMode === 'inbox_message' || actionMode === 'deadline_message')) {
+        if (nodeId === null)
+            throw new Error('has no message target');
+        const body = optionalString(payload, 'body');
+        if (body !== undefined) {
+            command = migratedMessageCommand(nodeId, tier, body, triggerId);
+        }
+        else if (triggerType === 'when') {
+            bodyFromGate = true;
+            command = migratedGateStdoutMessageCommand(nodeId, tier);
+        }
+        else {
+            // Not expressible from a gate: synthesize the most informative body the
+            // row still holds rather than losing the enactment.
+            command = migratedMessageCommand(nodeId, tier, label ?? 'Scheduled message (no body was recorded when this schedule was armed).', triggerId);
+        }
+        name = label ?? (actionMode === 'deadline_message' ? 'deadline' : 'scheduled message');
+    }
+    else if (action === 'msg' && actionMode === 'fresh_revive') {
+        if (nodeId === null)
+            throw new Error('has no revive target');
+        command = `crtr node lifecycle revive ${shellSingleQuote(nodeId)} --fresh`;
+        name = label ?? 'scheduled fresh revive';
+    }
+    else if (action === 'new' && actionMode === 'node_birth') {
+        command = migratedSpawnCommand(payload, triggerId);
+        name = optionalString(payload, 'name') ?? `scheduled ${requiredString(payload, 'kind', triggerId)} node`;
+    }
+    else {
+        throw new Error(`has unsupported action ${action}/${actionMode}`);
+    }
+    let fireAt;
+    let recur;
+    let expiresAt = null;
+    if (triggerType === 'when') {
+        fireAt = requiredString(row, 'next_eval_at', triggerId);
+        // A when-row with no evaluation cadence would silently become a ONE-SHOT
+        // gate that evaporates on its first unsatisfied check; skip-and-record it.
+        recur = requiredString(row, 'eval_every', triggerId);
+        expiresAt = optionalColumn(row, 'timeout_at') ?? null;
+        const gate = requiredString(row, 'when_script', triggerId);
+        const open = bodyFromGate ? `if ! CRTR_GATE_STDOUT="$(\n${gate}\n)"; then` : `if ! (\n${gate}\n); then`;
+        // `&&`, not a newline: the run's exit status must be the ACTION's, so a
+        // failed enactment escalates through the cron's on-failure path and leaves
+        // the cron armed instead of silently self-cancelling on a lost message.
+        // The action is BRACE-GROUPED because it may be heredoc-shaped: a `&&`
+        // appended straight onto it would land on the heredoc's closing delimiter
+        // line, which then never terminates the document.
+        command = `${open}\n  exit 0\nfi\n{\n${command}\n} && crtr cron cancel "$CRTR_CRON_ID"`;
+    }
+    else if (triggerType === 'at' || triggerType === 'every' || triggerType === 'until') {
+        fireAt = requiredString(row, 'fire_at', triggerId);
+        recur = triggerType === 'every' ? requiredString(row, 'recur', triggerId) : null;
+    }
+    else {
+        throw new Error(`has unknown timing type ${triggerType}`);
+    }
+    // `INSERT OR REPLACE` (the re-run convergence for a repeated `cron_id`) would
+    // ALSO silently evict a conflicting row on the ≤1-deadline-per-node partial
+    // index. Only drifted data can produce that shape, and it must be recorded,
+    // not resolved in silence: keep the earlier deadline, skip this one.
+    if (actionMode === 'deadline_message' && nodeId !== null) {
+        const rival = db
+            .prepare('SELECT cron_id FROM crons WHERE anchor_node = ? AND cancel_on_wake = 1 AND cron_id <> ?')
+            .get(nodeId, triggerId);
+        if (rival !== undefined) {
+            throw new Error(`node ${nodeId} already has a migrated deadline (${String(rival['cron_id'])}); only one is allowed`);
+        }
+    }
+    insert.run(triggerId, name, ownerId, command, fireAt, recur, expiresAt, nodeId, actionMode === 'deadline_message' ? 1 : 0, cwd, profile, 300, 
+    // `tier` and `sink` are INERT for migrated rows: the delivery lives entirely
+    // inside `command` (which carries its own `--tier`), and `sink = '{}'`
+    // parses to "no sink armed". `tier` is preserved only as provenance of what
+    // the retired schedule would have sent.
+    tier, created, created);
+}
+/** v23 — pid-REUSE guard for the cron run lease: `crons.run_pid_identity` holds
+ * the `capturePidIdentities` fingerprint of the run's process, captured at lease
+ * acquisition beside `run_pid`. Every kill site (stale-lease recovery,
+ * `cancelCron`, `cancelCronsOnWake`, deadline displacement) re-captures the
+ * identity of the recorded pid and refuses to signal unless it MATCHES.
+ *
+ * Without it, a bare pid recorded by a daemon life that ended (SIGKILL, host
+ * reboot) is compared only with `isPidAlive` — after a reboot the pid comes
+ * from a dead kernel's pid space, a low pid is likely recycled, and the run's
+ * own timeout is trivially exceeded, so recovery SIGTERMs an unrelated user
+ * process group. Rows written before this column exist have NULL identity and
+ * therefore fall to the fail-closed path (release the lease, never signal). */
+function addCronRunPidIdentityColumn(db) {
+    const columns = tableColumns(db, 'crons');
+    // A metadata-only harness db may have no `crons` table at all (PRAGMA returns
+    // no rows); there is nothing to alter and the version must still advance.
+    if (columns.size === 0 || columns.has('run_pid_identity'))
+        return;
+    db.exec('ALTER TABLE crons ADD COLUMN run_pid_identity TEXT;');
+}
+/** v24 — mark an OUT-OF-BAND run lease, and drop the never-implemented
+ * `crons.queued` column.
+ *
+ * `run_out_of_band` is set by `acquireCronRunLease` when the run is a `cron run`
+ * (the manual verify verb) rather than a scheduled fire. The overlap pass
+ * selects on `run_state = 'running'` alone, so without this marker a manual run
+ * that happens to straddle a real occurrence gets that occurrence advanced past
+ * (`overlap=skip` — a scheduled fire silently lost to a verification) or gets
+ * itself SIGTERMed (`overlap=replace`). The overlap pass now excludes it.
+ *
+ * `queued` was written by nothing and read by nothing: `overlap='queue'` is
+ * implemented purely by LEAVING `fire_at` past-due, so the depth is structural
+ * (one occurrence per row) and needs no counter. A column documenting a policy
+ * it does not implement misleads the next reader, so it goes. */
+function addCronOutOfBandColumn(db) {
+    const columns = tableColumns(db, 'crons');
+    // A metadata-only harness db may have no `crons` table at all (PRAGMA returns
+    // no rows); there is nothing to alter and the version must still advance.
+    if (columns.size === 0)
+        return;
+    if (!columns.has('run_out_of_band')) {
+        db.exec('ALTER TABLE crons ADD COLUMN run_out_of_band INTEGER NOT NULL DEFAULT 0;');
+    }
+    if (columns.has('queued'))
+        db.exec('ALTER TABLE crons DROP COLUMN queued;');
+}
+/** v25 — the `warm_pool` table: the spare-node pool behind `prefer_warm`.
+ *
+ *  A spare IS a real canvas node (its broker is already booted against a real
+ *  node dir); the row here is the marker that it has not been handed to anyone
+ *  yet. Membership in this table is what hides a node from every listing
+ *  (`listNodes`/`rosterNodes`/`listResumableRoots`) — an unclaimed spare must
+ *  never surface as a phantom empty conversation in a user's sidebar. Claiming
+ *  is exactly the DELETE of this row, taken under the canvas write-lock, so two
+ *  concurrent creates can never be handed the same spare.
+ *
+ *  `recipe_key` is the frozen-tuple digest a claim must match exactly (see
+ *  `runtime/warm-pool.ts`); the FK cascade reaps the marker when the node row
+ *  goes away. */
+function addWarmPoolTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS warm_pool (
+  node_id    TEXT PRIMARY KEY REFERENCES nodes(node_id) ON DELETE CASCADE,
+  recipe_key TEXT NOT NULL,   -- frozen launch tuple this spare was minted for
+  created    TEXT NOT NULL    -- ISO 8601, mint time (oldest spare claimed first)
+);
+CREATE INDEX IF NOT EXISTS idx_warm_pool_recipe ON warm_pool(recipe_key, created);
+`);
+}
+/** v26 — narrow `consult_outbox` for the humanloop absorption into
+ *  `src/core/human/` (absorb-humanloop
+ *  design, "The human-work receipt table"; Landing 2 Part E task E2). The
+ *  five-column trust binding (`handler_command`, `handler_args_json`,
+ *  `claim_token`, `generation_id`, `interaction_snapshot`) existed only to let
+ *  crtrd re-verify that a Visual event arrived through crouter's own
+ *  registered handler argv — that registry is deleted in this landing, so
+ *  there is nothing left to bind. `dir`/`root` collapse into `ticket_node_id`,
+ *  the bridge node id a ticket's directory is derived from at every call site
+ *  (`ticketDir(nodeId)` in `src/core/human/root.ts`) — `basename(dir)` IS that
+ *  node id today, already relied on as such at
+ *  `src/daemon/api/handlers/human.ts:290` (`const jobId = basename(dir)`) and
+ *  `src/core/canvas/attention.ts:21`.
+ *
+ *  THIS IS A TABLE REBUILD, NOT `ALTER TABLE … DROP COLUMN`: six of the nine
+ *  existing indexes are on `dir` (`idx_consult_outbox_dir`,
+ *  `idx_consult_outbox_dir_request_status`, `idx_consult_outbox_dir_status`
+ *  from v18; `idx_consult_outbox_human_work_dir_status`,
+ *  `idx_consult_outbox_human_work_request_status`, and the partial-unique
+ *  `idx_consult_outbox_visual_request` from v19), and SQLite refuses
+ *  `DROP COLUMN` on any indexed column. `ticket_node_id` cannot be a SQL
+ *  DEFAULT either — SQLite has no `basename()` — so it is computed per row in
+ *  JS: read every existing row through a prepared SELECT, insert each into a
+ *  freshly created `consult_outbox_new` with `ticket_node_id = basename(dir)`,
+ *  drop the old table (dropping its indexes with it), rename the new table
+ *  into place, and recreate exactly five indexes on the narrowed shape. Every
+ *  row is carried, including terminal ones, EXCEPT a row whose legacy `dir` is
+ *  not a canonical direct child of its recorded `root`, or whose basename is
+ *  not a safe node id — either would create an unaddressable or aliased ticket
+ *  id once `root` is discarded. A warning names how many are dropped.
+ *
+ *  THERE IS NO ROLLBACK. A sealed older runtime generation still running
+ *  against this canvas.db fails on the Visual lane (`INSERT INTO
+ *  consult_outbox (… dir, root, handler_command …)`) once this has run —
+ *  acceptable because this migration lands WITH a generation roll
+ *  (`npm run build && npm run install-runtime && crtr sys daemon restart`),
+ *  never alongside one. Not self-transactional: like every ordinary migration
+ *  it runs inside `migrate()`'s per-step `BEGIN IMMEDIATE`, so an interrupted
+ *  run leaves `consult_outbox` exactly as it was (SQLite DDL is transactional)
+ *  and a re-open resumes cleanly at the same step. */
+function narrowHumanWorkOutbox(db) {
+    const rows = db
+        .prepare('SELECT node_id, dir, root, request_id, work_kind, status, final_report, updated_at FROM consult_outbox')
+        .all();
+    db.exec(`
+CREATE TABLE consult_outbox_new (
+  node_id        TEXT PRIMARY KEY,
+  ticket_node_id TEXT NOT NULL,
+  request_id     TEXT NOT NULL,
+  work_kind      TEXT NOT NULL DEFAULT 'follow_up',
+  status         TEXT NOT NULL,
+  final_report   TEXT,
+  updated_at     TEXT NOT NULL
+);
+`);
+    const insert = db.prepare(`
+INSERT INTO consult_outbox_new (node_id, ticket_node_id, request_id, work_kind, status, final_report, updated_at)
+VALUES (?, ?, ?, ?, ?, ?, ?)`);
+    let dropped = 0;
+    for (const row of rows) {
+        const ticketNodeId = basename(row.dir);
+        const directChild = row.root === resolve(row.root) && row.dir === join(row.root, ticketNodeId);
+        if (!directChild || !isSafeNodeId(ticketNodeId)) {
+            dropped += 1;
+            continue;
+        }
+        insert.run(row.node_id, ticketNodeId, row.request_id, row.work_kind, row.status, row.final_report, row.updated_at);
+    }
+    if (dropped > 0) {
+        console.warn(`[canvas migration v26] dropped ${dropped} consult_outbox row(s) whose legacy ticket path cannot safely map to a ticket node id`);
+    }
+    db.exec(`
+DROP TABLE consult_outbox;
+ALTER TABLE consult_outbox_new RENAME TO consult_outbox;
+
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_status ON consult_outbox(status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_human_work_status ON consult_outbox(work_kind, status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_ticket_status ON consult_outbox(ticket_node_id, work_kind, status);
+CREATE INDEX IF NOT EXISTS idx_consult_outbox_ticket_request_status ON consult_outbox(ticket_node_id, request_id, work_kind, status);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_consult_outbox_visual_request ON consult_outbox(ticket_node_id, request_id, work_kind) WHERE work_kind = 'visual';
+`);
+}
+/** v27 — the canonical daemon-owned review record. */
+function addReviewsTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS reviews (
+  review_id            TEXT PRIMARY KEY,
+  idempotency_key      TEXT NOT NULL UNIQUE,
+  origin_kind          TEXT NOT NULL CHECK (origin_kind IN ('ticket', 'inline')),
+  origin_node_id       TEXT NOT NULL,
+  bridge_node_id       TEXT,
+  companion_node_id    TEXT NOT NULL UNIQUE,
+  review_dir           TEXT NOT NULL,
+  file                 TEXT NOT NULL,
+  origin_session_file  TEXT NOT NULL,
+  origin_session_id    TEXT NOT NULL,
+  origin_leaf_id       TEXT NOT NULL,
+  model_spec           TEXT NOT NULL,
+  branch_file          TEXT NOT NULL,
+  baseline_sha256      TEXT NOT NULL,
+  baseline_bytes       INTEGER NOT NULL,
+  anchor_base_sha256   TEXT NOT NULL,
+  anchor_base_bytes    BLOB NOT NULL,
+  state                TEXT NOT NULL CHECK (state IN ('binding', 'open', 'approved', 'canceled')),
+  created              TEXT NOT NULL,
+  captured_at          TEXT NOT NULL,
+  opened_at            TEXT,
+  output_path          TEXT,
+  subtitle             TEXT,
+  approved_at          TEXT,
+  approved_sha256      TEXT,
+  changed              INTEGER,
+  comments_total       INTEGER,
+  comments_unresolved  INTEGER,
+  result_json          TEXT,
+  canceled_at          TEXT,
+  cancel_reason        TEXT,
+  cancel_actor         TEXT,
+  delivery_entry_id    TEXT,
+  delivered_at         TEXT,
+  delivery_error       TEXT,
+  projected_at         TEXT,
+  projection_error     TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_reviews_state ON reviews(state);
+CREATE INDEX IF NOT EXISTS idx_reviews_origin ON reviews(origin_node_id);
+CREATE INDEX IF NOT EXISTS idx_reviews_file ON reviews(file);
+CREATE INDEX IF NOT EXISTS idx_reviews_bridge ON reviews(bridge_node_id);
+`);
+}
+/** v28 — current review-comment projection and append-only comment audit. */
+function addReviewCommentTables(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS review_comments (
+  comment_id          TEXT PRIMARY KEY,
+  review_id           TEXT NOT NULL,
+  status              TEXT NOT NULL CHECK (status IN ('open', 'resolved', 'deleted')),
+  revision            INTEGER NOT NULL,
+  text                TEXT NOT NULL,
+  anchor_line         INTEGER NOT NULL,
+  anchor_end_line     INTEGER NOT NULL,
+  anchor_col_start    INTEGER,
+  anchor_col_end      INTEGER,
+  anchor_quote        TEXT,
+  anchor_line_text    TEXT NOT NULL,
+  anchor_doc_hash     TEXT NOT NULL,
+  author_kind         TEXT NOT NULL CHECK (author_kind IN ('human', 'node')),
+  author_node_id      TEXT,
+  updated_by_kind     TEXT NOT NULL CHECK (updated_by_kind IN ('human', 'node')),
+  updated_by_node_id  TEXT,
+  created_at          TEXT NOT NULL,
+  updated_at          TEXT NOT NULL,
+  resolved_at         TEXT,
+  deleted_at          TEXT,
+  created_seq         INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS review_comment_events (
+  seq             INTEGER PRIMARY KEY AUTOINCREMENT,
+  review_id       TEXT NOT NULL,
+  comment_id      TEXT NOT NULL,
+  kind            TEXT NOT NULL CHECK (kind IN ('created', 'edited', 'resolved', 'reopened', 'deleted', 'reanchored', 'notified', 'notify_failed')),
+  state_change    INTEGER NOT NULL,
+  revision_after  INTEGER,
+  actor_kind      TEXT NOT NULL CHECK (actor_kind IN ('human', 'node', 'system')),
+  actor_node_id   TEXT,
+  at              TEXT NOT NULL,
+  operation_id    TEXT NOT NULL,
+  payload         TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_review_comments_review_line_seq
+  ON review_comments(review_id, anchor_line, created_seq);
+CREATE INDEX IF NOT EXISTS idx_review_comments_review_status
+  ON review_comments(review_id, status);
+CREATE INDEX IF NOT EXISTS idx_review_comment_events_review_seq
+  ON review_comment_events(review_id, seq);
+CREATE INDEX IF NOT EXISTS idx_review_comment_events_comment_seq
+  ON review_comment_events(comment_id, seq);
+`);
+}
+/** v29 — durable review-comment anchor disposition. v28 is already released, so this corrects both fresh and migrated databases without rewriting its historical schema. */
+function addReviewCommentAnchorState(db) {
+    db.exec(`
+ALTER TABLE review_comments
+  ADD COLUMN anchor_state TEXT NOT NULL DEFAULT 'live' CHECK (anchor_state IN ('live', 'detached'));
+`);
+}
+/** v30 — remove the retired human-work receipt table after every runtime reader is gone. */
+function dropConsultOutbox(db) {
+    db.exec('DROP TABLE IF EXISTS consult_outbox');
+}
+/** v31 — a human's submit intent recorded on a still-open review, so the
+ *  approval can wait for the companion to stop working. Deliberately a column
+ *  and not a new `state` value: through the wait the review IS open — comments
+ *  still land, ranges still remap, and cancellation still applies. */
+function addReviewSubmitRequested(db) {
+    db.exec('ALTER TABLE reviews ADD COLUMN submit_requested_at TEXT');
+}
+/** v32 — held crons (the exit-75 owed-gate disposition). `held` marks a row
+ *  whose last scheduled run exited 75 ("owed but not currently eligible"):
+ *  the occurrence was not spent and the row waits for an eligibility poke or
+ *  its natural backstop slot. `last_poke_at` records the most recent
+ *  `POST /v1/crons/poke` receipt on EVERY row, closing the race where a poke
+ *  lands while a gate check is in flight (the settling run compares its start
+ *  against it and re-dues instead of parking). Deliberately not part of the
+ *  due query: a held row is non-due by `fire_at`, never by a new predicate. */
+function addCronHeldColumns(db) {
+    db.exec(`
+ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
+`);
+}
+/** v33 — durable, daemon-owned attempts to deliver settled human completions. */
+function addHumanActionDeliveries(db) {
+    db.exec(`
+CREATE TABLE human_action_deliveries (
+  request_id           TEXT PRIMARY KEY,
+  state                TEXT NOT NULL,
+  attempt              INTEGER NOT NULL DEFAULT 0,
+  argv_json            TEXT NOT NULL,
+  cwd                  TEXT NOT NULL,
+  completion_json      TEXT NOT NULL,
+  next_attempt_at      INTEGER NOT NULL,
+  claimed_at           INTEGER,
+  claim_owner          TEXT,
+  accepted_at          INTEGER,
+  permanent_failed_at  INTEGER,
+  last_failure_json    TEXT,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL
+);
+CREATE INDEX idx_human_action_deliveries_due ON human_action_deliveries(state, next_attempt_at);
+`);
+}
+/** v34 — index the exact Pi session file coordinate used to recover fork
+ * exposure provenance without hydrating every node meta. Meta remains authoritative;
+ * normal identity upserts keep this projection current after the one-time backfill. */
+function addNodeSessionFileIndex(db) {
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'pi_session_file', 'ALTER TABLE nodes ADD COLUMN pi_session_file TEXT;');
+    for (const entry of readdirSync(nodesRoot(), { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            const meta = JSON.parse(readFileSync(nodeMetaPath(entry.name), 'utf8'));
+            if (typeof meta.pi_session_file === 'string') {
+                db.prepare('UPDATE nodes SET pi_session_file = ? WHERE node_id = ?').run(meta.pi_session_file, entry.name);
+            }
+        }
+        catch {
+            // Corrupt node metadata is ignored by the ordinary canvas rebuild too.
+        }
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_pi_session_file ON nodes(pi_session_file);');
+}
+/** The journaled lane of the state-migration registry, adapted to this chain's
+ *  step shape. Registry order is preserved, so these versions stay stable as
+ *  long as the registry is append-only (same contract as the local list). */
+const JOURNALED_STATE_MIGRATIONS = STATE_MIGRATIONS
+    .filter((m) => m.lane === 'journaled')
+    .map((m) => (db) => m.apply(db, crtrHome()));
+/** The ordered migration list. Index `i` is migration version `i + 1`; the db's
+ *  `user_version` tracks how many have been applied. Append only. Journaled
+ *  entries from `src/migrations/registry.ts` follow the local steps, so a new
+ *  registry migration lands as the next version. */
+export const MIGRATIONS = [
+    /* v1 */ baselineSchema,
+    /* v2 */ addRuntimeColumns,
+    /* v3 */ backfillRuntime,
+    /* v4 */ edgesForeignKeyCascade,
+    /* v5 */ addPaneColumn,
+    /* v6 */ addFocusesTable,
+    /* v7 */ appendWakeupsTable,
+    /* v8 */ addHostKindColumn,
+    /* v9 */ migrateWakeupsToTriggers,
+    /* v10 */ addCanvasMetaTable,
+    /* v11 */ addProfileIdColumn,
+    /* v12 */ addPidIdentityColumn,
+    /* v13 */ addMessageWaitColumn,
+    /* v14 */ addCanonicalFinalColumns,
+    /* v15 */ normalizePersistedLaunchExtensions,
+    // Repair databases that reached v15 through the concurrent launch-metadata
+    // migration before canonical finalization joined the ordered mainline.
+    /* v16 */ addCanonicalFinalColumns,
+    /* v17 */ addMessageWaitGenerationColumn,
+    /* v18 */ addHumanWorkOutboxTable,
+    /* v19 */ addHumanWorkColumns,
+    /* v20 */ addNodeParentCreatedIndexes,
+    /* v21 */ addCronsTables,
+    /* v22 */ migrateTriggersToCrons,
+    /* v23 */ addCronRunPidIdentityColumn,
+    /* v24 */ addCronOutOfBandColumn,
+    /* v25 */ addWarmPoolTable,
+    /* v26 */ narrowHumanWorkOutbox,
+    /* v27 */ addReviewsTable,
+    /* v28 */ addReviewCommentTables,
+    /* v29 */ addReviewCommentAnchorState,
+    /* v30 */ dropConsultOutbox,
+    /* v31 */ addReviewSubmitRequested,
+    /* v32 */ addCronHeldColumns,
+    /* v33 */ addHumanActionDeliveries,
+    /* v34 */ addNodeSessionFileIndex,
+    ...JOURNALED_STATE_MIGRATIONS,
+];
+/** Migration indexes that manage their OWN transaction and therefore must not
+ *  be wrapped by `migrate()` — `node:sqlite` rejects a nested BEGIN. Index 3
+ *  (v4, the edges FK rebuild) both BEGINs internally and toggles
+ *  `PRAGMA foreign_keys`, which is a no-op inside a transaction. Its docblock
+ *  documents its own crash-safety: a partial rebuild rolls back and a re-run
+ *  over an already-rebuilt table is idempotent. (Entering `migrate()` from
+ *  INSIDE a caller's transaction with `user_version` still at 3 would make that
+ *  internal BEGIN nest and throw — pre-existing and unreachable from `openDb()`,
+ *  which migrates in autocommit.) */
+const SELF_TRANSACTIONAL_MIGRATIONS = new Set([3]);
+function currentUserVersion(db) {
+    return db.prepare('PRAGMA user_version').get().user_version;
+}
+function applyMigration(db, v) {
+    MIGRATIONS[v](db);
+    // `user_version` takes no bound parameters; v is a controlled integer.
+    db.exec(`PRAGMA user_version = ${v + 1}`);
+}
+/** Bring `db` up to the latest schema version. Reads `user_version`, runs each
+ *  pending migration in order, and bumps `user_version` after each so the work
+ *  is gated and idempotent: re-running is a no-op once `user_version` reaches
+ *  `MIGRATIONS.length`. Forward-only.
+ *
+ *  ATOMIC AND RESTARTABLE: each step AND its `user_version` bump run inside one
+ *  `BEGIN IMMEDIATE`/`COMMIT` (SQLite journals `user_version` with the
+ *  transaction, so a rollback restores it too). An interrupted or failing step
+ *  therefore leaves the db exactly at the previous version with none of its
+ *  writes committed — a half-applied step can never wedge every later open. The
+ *  write lock also serializes concurrent openers; the version is re-read after
+ *  acquiring it so a step another process just applied is skipped rather than
+ *  re-run. */
+export function migrate(db) {
+    if (currentUserVersion(db) >= MIGRATIONS.length)
+        return;
+    // Pending work: a step now holds the write lock for its whole duration, and
+    // the fs-heavy legacy steps (v3/v14/v15) can outlast the ordinary 5s busy
+    // timeout. Let concurrent openers WAIT for the migration rather than fail.
+    const priorTimeout = db.prepare('PRAGMA busy_timeout').get().timeout;
+    db.exec('PRAGMA busy_timeout = 60000;');
+    try {
+        runPendingMigrations(db);
+    }
+    finally {
+        db.exec(`PRAGMA busy_timeout = ${priorTimeout};`);
+    }
+}
+function runPendingMigrations(db) {
+    for (;;) {
+        const v = currentUserVersion(db);
+        if (v >= MIGRATIONS.length)
+            return;
+        // Already inside a caller's transaction (or a self-transactional step):
+        // run bare rather than nesting a BEGIN node:sqlite would reject.
+        if (db.isTransaction || SELF_TRANSACTIONAL_MIGRATIONS.has(v)) {
+            applyMigration(db, v);
+            continue;
+        }
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            // Another process may have applied this step while we waited on the lock.
+            if (currentUserVersion(db) === v)
+                applyMigration(db, v);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* transaction was already closed */ }
+            throw err;
+        }
+    }
+}