@north-light/crouter 0.3.154

package/dist/core/canvas/db.js

@@ -0,0 +1,1167 @@
+// canvas.db — the topology skeleton. sqlite in WAL mode so the many concurrent
+// writers a sisyphus-grade swarm produces don't contend on a single locked JSON.
+//
+// Node rows are a rebuildable index over each node's meta.json (the source of
+// truth). The `subscribes_to` edges are the one genuinely-mutable part no meta
+// owns, so the db is authoritative for them.
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, readFileSync, readdirSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { canvasDbPath, ensureHome, nodesRoot, nodeMetaPath } from './paths.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);
+`);
+}
+/** The node row's current columns, used to make additive migrations safe to
+ *  re-run against a partially applied schema. */
+function nodeColumns(db) {
+    return new Set(db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name));
+}
+function addNodeColumnIfMissing(db, columns, name, ddl) {
+    if (columns.has(name))
+        return;
+    db.exec(ddl);
+    columns.add(name);
+}
+/** v2 — additive runtime columns the keystone (Phase 2) will make
+ *  authoritative: `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, so nothing observes a behavior change until a later phase reads 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 (keystone, Phase 2). 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 (explicitly sanctioned by the runtime-fix plan): 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
+ *  (crouter#98 final review, Fix 1 — 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 — the `consult_outbox` table: the receipted delivery record for a Lane B
+ *  follow-up consultation fork's answer (design-followup-consult-v2.md §B.4).
+ *  One row per consult fork (`node_id` PK). `status` walks armed → pending →
+ *  acked (happy path) or armed/pending → errored/canceled (failure/cancel
+ *  paths). `final_report` (the basename under the fork's `reports/`) is set
+ *  only when the row is promoted armed→pending inside the SAME SQLite
+ *  transaction that commits the fork's canonical final (`feed.ts
+ *  commitCanonicalFinal`) — that atomicity is the whole point of the outbox:
+ *  a crash between commit and dispatch still leaves a durable `pending` row
+ *  for follow-up reconciliation to redeliver. `dir`/`root`/`request_id` bind
+ *  the row back to the humanloop ticket + the exact follow-up request it
+ *  answers, so a stale/superseded fork's late delivery is a no-op at the
+ *  humanloop layer (compare-and-publish under `.followup-lock`), never here.
+ *
+ *  NO foreign key on `node_id` (matches the authoritative design's schema
+ *  exactly — it declares no FK at all): unlike the retired `triggers`/`wakeups`
+ *  tables did, an
+ *  unsettled (`armed`/`pending`) receipt is the ONLY durable record that a
+ *  follow-up answer is still owed, and ordinary node pruning (`canvas.ts`
+ *  `pruneNodes`) deletes terminal node rows + their `reports/` dirs on a
+ *  routine schedule that has nothing to do with whether humanloop has
+ *  actually accepted the delivery. A `nodes` cascade would let a prune race
+ *  silently erase that receipt (and, once `final_report` is set, the report
+ *  file itself) before follow-up reconciliation/delivery ever
+ *  runs — the crash-safety net the whole table exists to provide. Only
+ *  `acked`/`errored`/`canceled` rows are truly done; those are reaped by the
+ *  outbox's own housekeeping, never by a `nodes` FK. Two composite indexes
+ *  back the request-bound and ticket-bound DAO reads a `_consult`/`_deliver`
+ *  caller needs (`getActiveFollowUpWorkByRequest`,
+ *  `listActiveFollowUpWorkByDir` in human-work-outbox.ts) without scanning
+ *  every row in the table. Additive, forward-only. */
+function addHumanWorkOutboxTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS consult_outbox (
+  node_id      TEXT PRIMARY KEY,   -- the consult fork's id
+  dir          TEXT NOT NULL,      -- ticket dir
+  root         TEXT NOT NULL,      -- registered root (for submitFollowUpResult auth)
+  request_id   TEXT NOT NULL,      -- binds this fork to one follow-up request
+  status       TEXT NOT NULL,      -- armed | pending | acked | errored | canceled
+  final_report TEXT,               -- basename of reports/<...>-final.md, set on promote
+  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 = new Set(db.prepare('PRAGMA table_info(consult_outbox)').all().map((row) => row.name));
+    const add = (name, ddl) => {
+        if (columns.has(name))
+            return;
+        db.exec(ddl);
+        columns.add(name);
+    };
+    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 = new Set(db.prepare('PRAGMA table_info(crons)').all().map((r) => r.name));
+    // 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 = new Set(db.prepare('PRAGMA table_info(crons)').all().map((r) => r.name));
+    // 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);
+`);
+}
+/** The ordered migration list. Index `i` is migration version `i + 1`; the db's
+ *  `user_version` tracks how many have been applied. Append only. */
+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,
+];
+/** 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;
+        }
+    }
+}
+const handles = new Map();
+// --- V-2 open-ledger instrumentation --------------------------------------
+//
+// When `CRTR_DB_OPEN_LEDGER=<path>` is set, every *fresh* canvas.db open (i.e.
+// one that actually constructs a new DatabaseSync, not a cache hit) appends one
+// line recording the opening process's identity. This is corroborating runtime
+// evidence for the crtrd-sole-state-owner guarantee: the C-4 §11 scenario
+// runner sets the env for daemon + CLI and asserts the ledger contains ONLY the
+// crtrd process — zero opens attributed to a `crtr`/`bin/crtr` CLI process.
+//
+// Line format (space-separated, one per open, trivially parseable):
+//   <iso-timestamp> <pid> <argv1>
+// e.g. `2026-07-21T18:04:11.923Z 40521 /Users/x/crouter/dist/daemon/crtrd.js`
+//
+// A dumb append — no locking, no dedup. Zero behavior change when the env is
+// unset; a failing append is swallowed so instrumentation never breaks an open.
+function recordOpenLedger() {
+    const ledger = process.env.CRTR_DB_OPEN_LEDGER;
+    if (!ledger)
+        return;
+    try {
+        const line = `${new Date().toISOString()} ${process.pid} ${process.argv[1] ?? '<unknown>'}\n`;
+        appendFileSync(ledger, line);
+    }
+    catch {
+        /* instrumentation only — never let a ledger write break a db open */
+    }
+}
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
+ *  schema and WAL on first open. Keyed by path so tests with distinct homes get
+ *  independent handles. */
+export function openDb() {
+    const path = canvasDbPath();
+    const existing = handles.get(path);
+    if (existing) {
+        try {
+            existing.prepare('PRAGMA database_list').all();
+            return existing;
+        }
+        catch {
+            try {
+                existing.close();
+            }
+            catch {
+                /* ignore */
+            }
+            handles.delete(path);
+        }
+    }
+    ensureHome();
+    recordOpenLedger();
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA journal_mode = WAL;');
+    // Load-bearing as of migration v4: the edges→nodes FK (ON DELETE CASCADE)
+    // needs this ON at the deleting connection so a node delete reaps its edges.
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec('PRAGMA busy_timeout = 5000;');
+    migrate(db);
+    handles.set(path, db);
+    return db;
+}
+/** Run `body` under the canvas SQLite write lock, joining an outer transaction
+ *  when the shared connection already owns one. This is the common boundary for
+ *  multi-statement mutations whose reads and writes must linearize as one unit;
+ *  `node:sqlite` rejects nested BEGINs, so only the outermost call commits.
+ */
+export function withCanvasWrite(body) {
+    const db = openDb();
+    if (db.isTransaction)
+        return body(db);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = body(db);
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* transaction was already closed */ }
+        throw err;
+    }
+}
+/** Close and forget the handle for the current home. Mainly for tests. */
+export function closeDb() {
+    const path = canvasDbPath();
+    const db = handles.get(path);
+    if (db) {
+        db.close();
+        handles.delete(path);
+    }
+}