@north-light/crouter 0.3.232 → 0.3.234

package/dist/core/canvas/db.js

@@ -1,1325 +1,24 @@
-// 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.
+// canvas.db — connection management only. Opens (or reuses) the WAL-mode
+// handle, applies pending schema migrations on first open, and serializes
+// writes under one transaction boundary. 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 { basename, join, resolve } from 'node:path';
-import { canvasDbPath, crtrHome, ensureHome, 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);
-`);
-}
-/** 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 — 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 = 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);
-`);
-}
-/** 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;
-        }
-    }
-}
+// The versioned schema chain itself (`MIGRATIONS`, `migrate()`) lives in
+// `./migrations.js` — see that file's header for how this repo's three
+// migration homes divide. Re-exported here so every existing import of
+// `migrate`/`MIGRATIONS` from this module keeps working.
+import { DatabaseSync } from 'node:sqlite';
+import { appendFileSync } from 'node:fs';
+import { canvasDbPath, ensureHome } from './paths.js';
+import { migrate } from './migrations.js';
+export { migrate, MIGRATIONS } from './migrations.js';
 const handles = new Map();
-// --- V-2 open-ledger instrumentation --------------------------------------
+// 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
@@ -1348,25 +47,24 @@ function recordOpenLedger() {
 }
 /** 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. */
+ *  independent handles.
+ *
+ *  A cache hit trusts the cached handle outright: `crtrd` is this process's
+ *  sole canvas-db owner (see `crtrd-sole-state-owner`), and nothing outside
+ *  `openDb`/`closeDb` ever touches `handles` — there is no other actor in this
+ *  process that could invalidate a live handle out from under it. (A
+ *  2026-06-25 revision added a `PRAGMA database_list` liveness probe here that
+ *  silently closed and reopened the handle on any throw; it shipped alongside
+ *  an unrelated guest-relay `PATH` fix for the now-removed `hearth` guest
+ *  bootstrap, named no concrete failure mode in its commit or a test, and that
+ *  guest-relay path no longer exists. Removed rather than kept-and-logged: a
+ *  silent boot-path reopen is worse than trusting a handle this process
+ *  already owns.) */
 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);
-        }
-    }
+    if (existing)
+        return existing;
     ensureHome();
     recordOpenLedger();
     const db = new DatabaseSync(path);