@north-light/crouter 0.3.154

package/dist/core/canvas/canvas.js

@@ -0,0 +1,897 @@
+// The canvas data-access layer. The one place that reads/writes the node+edge
+// model. Later phases (spawn, push, lifecycle, daemon) call only this.
+//
+// Source-of-truth split: a node's meta.json is canonical for its own fields;
+// the db row is a queryable index re-derivable from it. The subscribes_to edges
+// are db-authoritative (mutable, many-writers — what WAL is for).
+import { existsSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { openDb, withCanvasWrite } from './db.js';
+import { withMetaLock, readMetaObject, writeMetaObjectLocked, writeJsonFileDurably } from './meta-file.js';
+import { isPidAlive, recordedPidLiveness, capturePidIdentities, identitiesMatch, isLegacyTicksIdentity, isBootScopedIdentity, } from './pid.js';
+import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
+// ---------------------------------------------------------------------------
+// meta.json (durable identity — the source of truth for what PERSISTS)
+//
+// One authoritative store per fact: meta.json holds NodeIdentity only; the six
+// runtime fields (status, intent, pi_pid, window, tmux_session, pane) are
+// authoritative in the WAL'd `nodes` row, each mutated by one atomic setter
+// below. getNode() hydrates the two back into the historical NodeMeta view.
+// ---------------------------------------------------------------------------
+/** The identity keys meta.json persists. Listed explicitly so no runtime field
+ *  can ever leak onto disk even when a fully-hydrated NodeMeta is handed in. */
+const IDENTITY_KEYS = [
+    'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'host_kind', 'profile_id', 'kind', 'mode',
+    'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'human_work_target', 'private_fork_phase',
+    'private_fork_recipe', 'passive_default', 'pi_session_id', 'pi_session_file', 'cycle_pending', 'model_override',
+    'launch', 'managed_worktree',
+];
+/** Project any node object down to its durable-identity subset. */
+function toIdentity(m) {
+    const out = {};
+    for (const k of IDENTITY_KEYS) {
+        if (m[k] !== undefined)
+            out[k] = m[k];
+    }
+    return out;
+}
+function readMeta(nodeId) {
+    const p = nodeMetaPath(nodeId);
+    if (!existsSync(p))
+        return null;
+    // Legacy metas may still carry runtime fields on disk; toIdentity-on-read is
+    // unnecessary (callers go through getNode, which overlays the row), but the
+    // raw parse is typed as identity — extra props are ignored.
+    //
+    // Tolerate an EMPTY or unparseable meta.json by treating it as MISSING (null)
+    // rather than throwing. A bare write-temp-then-rename without fsync can leave a
+    // 0-byte meta.json on an NFS-backed home after the holding process/sandbox dies
+    // (see writeMeta + the guest cold-boot bug it guards against); a single corrupt
+    // node must not crash rebuildIndex/revive for the whole canvas. Recovery
+    // (re-seed from a durable snapshot) is the caller's job.
+    const raw = readFileSync(p, 'utf8');
+    if (raw.trim() === '')
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Serialize ONLY the identity subset → meta.json never holds runtime fields.
+ *
+ *  Durable write: fsync the temp file before the rename, then fsync the parent
+ *  directory so the rename itself is on disk. A bare writeFileSync+rename is not
+ *  crash-durable — a host crash or abrupt sandbox teardown shortly after the
+ *  rename can surface a 0-byte or missing meta.json (observed on a guest home as
+ *  a cold-boot 0-byte meta.json → rebuild-index/revive JSON.parse('')). meta.json
+ *  is written rarely (birth, polymorph, session-id capture, naming) so the
+ *  per-write fsync cost is negligible. */
+function writeMeta(meta) {
+    writeJsonFileDurably(nodeMetaPath(meta.node_id), toIdentity(meta));
+}
+// ---------------------------------------------------------------------------
+// row index — identity columns are a derived projection of meta; runtime
+// columns are authoritative. The two have DIFFERENT writers: upsertRow only
+// ever touches identity (so a re-index never clobbers live runtime), while
+// createNode seeds runtime once and the atomic setters own it thereafter.
+// ---------------------------------------------------------------------------
+/** Upsert the IDENTITY columns of a node's row. ON CONFLICT updates identity
+ *  ONLY — runtime columns (status/intent/pi_pid/window/tmux_session/pane) are left
+ *  exactly as they are, so re-indexing or an identity edit never disturbs live
+ *  state. A fresh insert takes the schema defaults for runtime. */
+function upsertRow(meta) {
+    openDb()
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
+         profile_id=excluded.profile_id, parent=excluded.parent`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created);
+}
+/** Seed a node's row at BIRTH: identity columns + runtime columns taken from the
+ *  incoming meta (defaults: status='active', the rest null). The only writer
+ *  that sets runtime columns alongside identity in one statement — afterwards
+ *  the atomic setters are the sole runtime writers. */
+function seedRow(meta) {
+    openDb()
+        .prepare(`INSERT INTO nodes
+         (node_id, name, kind, mode, lifecycle, cwd, host_kind, profile_id, parent, created,
+          status, intent, waiting_for, final_report, finalized_at, pi_pid, "window", tmux_session, pane)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         lifecycle=excluded.lifecycle, cwd=excluded.cwd, host_kind=excluded.host_kind,
+         profile_id=excluded.profile_id, parent=excluded.parent,
+         status=excluded.status, intent=excluded.intent, waiting_for=excluded.waiting_for,
+         final_report=excluded.final_report, finalized_at=excluded.finalized_at,
+         pi_pid=excluded.pi_pid, "window"=excluded."window", tmux_session=excluded.tmux_session,
+         pane=excluded.pane`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.created, meta.status ?? 'active', meta.intent ?? null, meta.waiting_for ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.pi_pid ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null);
+}
+function rowFrom(r) {
+    return {
+        node_id: r['node_id'],
+        name: r['name'],
+        kind: r['kind'],
+        mode: r['mode'],
+        lifecycle: r['lifecycle'],
+        status: r['status'],
+        cwd: r['cwd'],
+        host_kind: r['host_kind'] ?? null,
+        profile_id: r['profile_id'] ?? null,
+        parent: r['parent'] ?? null,
+        created: r['created'],
+        intent: r['intent'] ?? null,
+        waiting_for: r['waiting_for'] ?? null,
+        final_report: r['final_report'] ?? null,
+        finalized_at: r['finalized_at'] ?? null,
+        pi_pid: r['pi_pid'] ?? null,
+        pi_pid_identity: r['pi_pid_identity'] ?? null,
+        window: r['window'] ?? null,
+        tmux_session: r['tmux_session'] ?? null,
+        pane: r['pane'] ?? null,
+    };
+}
+/** The authoritative runtime fields for `nodeId`, read from its row. Null when
+ *  no row exists yet (the hydration then falls back to whatever the meta held). */
+function runtimeFromRow(nodeId) {
+    const r = openDb()
+        .prepare('SELECT status, intent, waiting_for, final_report, finalized_at, pi_pid, pi_pid_identity, "window", tmux_session, pane FROM nodes WHERE node_id = ?')
+        .get(nodeId);
+    if (r === undefined)
+        return null;
+    return {
+        status: r['status'] ?? 'active',
+        intent: r['intent'] ?? null,
+        waiting_for: r['waiting_for'] ?? null,
+        final_report: r['final_report'] ?? null,
+        finalized_at: r['finalized_at'] ?? null,
+        pi_pid: r['pi_pid'] ?? null,
+        pi_pid_identity: r['pi_pid_identity'] ?? null,
+        window: r['window'] ?? null,
+        tmux_session: r['tmux_session'] ?? null,
+        pane: r['pane'] ?? null,
+    };
+}
+// ---------------------------------------------------------------------------
+// Nodes
+// ---------------------------------------------------------------------------
+/** Create a node: scaffold its dirs, persist identity to meta.json, and seed the
+ *  row (identity + runtime from the incoming meta). Returns the hydrated view. */
+export function createNode(meta) {
+    ensureHome();
+    ensureNodeDirs(meta.node_id);
+    writeMeta(meta);
+    seedRow(meta);
+    return getNode(meta.node_id);
+}
+/** The canonical node record: durable identity (meta.json) ∪ authoritative
+ *  runtime (the row). Null if unknown. */
+export function getNode(nodeId) {
+    const ident = readMeta(nodeId);
+    if (ident === null)
+        return null;
+    const rt = runtimeFromRow(nodeId);
+    // The row is authoritative for runtime; overlay it over identity. When no row
+    // exists yet (rare — pre-rebuild), keep whatever the meta carried.
+    return { ...ident, ...(rt ?? {}) };
+}
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export function getRow(nodeId) {
+    const r = openDb()
+        .prepare('SELECT * FROM nodes WHERE node_id = ?')
+        .get(nodeId);
+    return r ? rowFrom(r) : null;
+}
+/** The node row whose durable LOCATION pane is `pane`, or null. Lets placement
+ *  resolve "who sits in this pane" by the first-class `%pane_id` handle (e.g.
+ *  to adopt a caller's pane as a focus). pane is not UNIQUE in the schema, but a
+ *  live pane backs at most one node, so this returns the single match. */
+export function getRowByPane(pane) {
+    const r = openDb()
+        .prepare('SELECT * FROM nodes WHERE pane = ?')
+        .get(pane);
+    return r ? rowFrom(r) : null;
+}
+/** Merge an IDENTITY patch into a node's meta.json and re-index its identity
+ *  columns. Identity has a single writer per node, so this read-modify-write is
+ *  safe (the contended runtime fields were moved out — see the atomic setters
+ *  below). Returns the hydrated view (runtime included). */
+export function updateNode(nodeId, patch) {
+    const path = nodeMetaPath(nodeId);
+    // The whole read/merge/write runs under the SAME per-node lock a migration
+    // takes (meta-file.ts), so a concurrent v15 normalization and an identity edit
+    // cannot interleave into a lost write or a restored legacy hook prefix.
+    const next = withMetaLock(path, () => {
+        const cur = readMetaObject(path);
+        if (cur === null)
+            throw new Error(`unknown node: ${nodeId}`);
+        const identity = toIdentity({ ...cur, ...patch, node_id: nodeId });
+        writeMetaObjectLocked(path, identity);
+        return identity;
+    });
+    upsertRow(next);
+    return getNode(nodeId);
+}
+// ---------------------------------------------------------------------------
+// Atomic runtime setters — each one a single-statement UPDATE on the WAL'd row,
+// the authoritative store for live state. No read-modify-write, so concurrent
+// writers of DIFFERENT fields (the daemon stamping pi_pid while a node flips
+// status) can never clobber each other: WAL serializes the two statements.
+// `"window"` is quoted defensively — it is a SQLite keyword.
+// ---------------------------------------------------------------------------
+/** Set a node's status. Atomic single-column write. */
+export function setStatus(nodeId, status) {
+    openDb().prepare('UPDATE nodes SET status = ? WHERE node_id = ?').run(status, nodeId);
+}
+/** Set a node's exit intent. Atomic single-column write. */
+export function setIntent(nodeId, intent) {
+    openDb().prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(intent ?? null, nodeId);
+}
+/** Set a node's tmux presence in one atomic write: the durable LOCATION anchor
+ *  `pane` (the `%pane_id`) plus its derived cache (`tmux_session` + `window`).
+ *  All three move together — `pane` joins the others inside the single UPDATE so
+ *  a move never half-writes the location. `pane` is optional: a caller that does
+ *  not yet track it (every caller, until the placement layer lands) writes null,
+ *  which is harmless because nothing reads `pane` yet. */
+export function setPresence(nodeId, presence) {
+    openDb()
+        .prepare('UPDATE nodes SET tmux_session = ?, "window" = ?, pane = ? WHERE node_id = ?')
+        .run(presence.tmux_session ?? null, presence.window ?? null, presence.pane ?? null, nodeId);
+}
+/** Record the live pi pid (daemon liveness signal) PLUS its launch-time
+ *  identity fingerprint, in one atomic write (crouter#98 review finding 1):
+ *  `capturePidIdentities([pid])` is a signal-0-adjacent `ps -p <pid>` probe
+ *  taken RIGHT NOW, while `pid` is the process we just spawned/bound and
+ *  therefore definitely still exists — this is the LAUNCH-time baseline
+ *  `headlessBrokerHost.teardown()` later compares against before signaling
+ *  anything. A failed probe (rare — `ps` itself misbehaving) or a probe that
+ *  finds no row for `pid` (raced away in the instant between spawn and this
+ *  call) both write `NULL`: no baseline recorded, so the teardown guard fails
+ *  open exactly like a node booted before this column existed — never a false
+ *  identity that could itself cause a false mismatch later. */
+export function recordPid(nodeId, pid) {
+    const identity = capturePidIdentities([pid])?.get(pid) ?? null;
+    openDb()
+        .prepare('UPDATE nodes SET pi_pid = ?, pi_pid_identity = ? WHERE node_id = ?')
+        .run(pid, identity, nodeId);
+}
+/** Clear the pi pid (window-backed relaunch, before the fresh pi re-records it)
+ *  AND its recorded launch-time identity — the two are written together by
+ *  `recordPid` and must be cleared together, or a subsequent relaunch that
+ *  reuses the pid namespace could compare its own fresh pid against a STALE
+ *  identity left over from the pid this row held before. */
+export function clearPid(nodeId) {
+    openDb().prepare('UPDATE nodes SET pi_pid = NULL, pi_pid_identity = NULL WHERE node_id = ?').run(nodeId);
+}
+/** ONE-TIME completion of the boot-scoped-identity format migration, run once
+ *  at daemon startup (the natural boot-reconciliation chokepoint, right after
+ *  `reconcileBootLiveness`). It closes the gap the `identitiesMatch` legacy
+ *  lane only TOLERATES: a broker that survives an in-place crouter upgrade
+ *  keeps its old `lstart#ticks` row indefinitely (`recordPid` only fires on
+ *  launch/revive/session_start), so the cross-boot ticks-collision exposure the
+ *  boot-scoped base was added to close never provably shuts for those rows.
+ *
+ *  For every row whose RECORDED identity is legacy-format while this platform
+ *  now composes new-format (a readable kernel boot_id):
+ *   - if the recorded pid's CURRENT live identity matches the recorded one via
+ *     the migration lane (same live process, `identitiesMatch` true) AND that
+ *     current identity is itself boot-scoped — re-record it with the new
+ *     composer, completing the migration in place;
+ *   - otherwise (pid gone, probe failed, reused — no match, or no readable
+ *     boot_id for it) — leave the row untouched for the normal liveness
+ *     handling that already runs each tick.
+ *
+ *  After this runs once, the legacy compare lane only ever engages for
+ *  genuinely no-boot_id platforms. NOT a per-caller reconciliation layer — a
+ *  single startup sweep. `captureIdentity` is injectable for unit tests.
+ *
+ *  GATED on proven same-boot provenance by its caller (daemon startup runs it
+ *  only when `reconcileBootLiveness` returned `sameBootProven` — see
+ *  `bootProvenSame`). This is what makes a bare ticks match safe to bless as a
+ *  current-boot identity: without that proof an equal-ticks collision with an
+ *  unrelated process from a DIFFERENT boot could be rewritten as
+ *  `<currentBootId>#<ticks>`, permanently baptizing a stranger.
+ *
+ *  Not transactional by design: it never HOLDS the write lock across the (slow,
+ *  per-row) `ps` probe. Each re-record is a compare-and-swap single-row UPDATE
+ *  constrained by ALL three snapshotted values (`node_id`, `pi_pid`,
+ *  `pi_pid_identity`), counted only when a row actually changed. So if the old
+ *  broker exits and a concurrent revive atomically records a fresh
+ *  `(pi_pid, pi_pid_identity)` between this sweep's probe and its update, the
+ *  CAS matches zero rows and the migration is skipped rather than clobbering
+ *  the newer identity with the stale one. */
+export function migrateLegacyPidIdentities(captureIdentity = (pid) => capturePidIdentities([pid])?.get(pid)) {
+    const db = openDb();
+    const rows = db
+        .prepare('SELECT node_id, pi_pid, pi_pid_identity FROM nodes WHERE pi_pid IS NOT NULL AND pi_pid_identity IS NOT NULL')
+        .all();
+    // Compare-and-swap: rewrite only if the row STILL carries the exact pid +
+    // legacy identity we probed. A concurrent revive between probe and update
+    // records a new (pi_pid, pi_pid_identity) pair, so this WHERE fails to match
+    // and we skip rather than clobber the fresh baseline.
+    const upd = db.prepare('UPDATE nodes SET pi_pid_identity = ? WHERE node_id = ? AND pi_pid = ? AND pi_pid_identity = ?');
+    const migrated = [];
+    for (const row of rows) {
+        if (!isLegacyTicksIdentity(row.pi_pid_identity))
+            continue;
+        const current = captureIdentity(row.pi_pid);
+        if (current === undefined)
+            continue; // pid gone / probe failed → normal liveness handling
+        if (!isBootScopedIdentity(current))
+            continue; // no readable boot_id for it → nothing to upgrade
+        if (!identitiesMatch(current, row.pi_pid_identity))
+            continue; // reused → leave to liveness
+        const res = upd.run(current, row.node_id, row.pi_pid, row.pi_pid_identity);
+        if (res.changes > 0)
+            migrated.push(row.node_id); // skipped if a concurrent revive re-recorded
+    }
+    return { migrated };
+}
+/** The one clause that hides unclaimed warm-pool spares from every listing.
+ *  A spare is a real node with a booted broker, but nobody has been handed it
+ *  yet — surfacing it would put a phantom empty conversation in the user's
+ *  sidebar. Claiming deletes the marker, which is what makes the node visible. */
+const NOT_A_SPARE = 'node_id NOT IN (SELECT node_id FROM warm_pool)';
+/** All rows, optionally filtered by status. Unclaimed warm spares are excluded. */
+export function listNodes(filter) {
+    const db = openDb();
+    let rows;
+    if (filter?.status !== undefined) {
+        const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+        const placeholders = statuses.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM nodes WHERE status IN (${placeholders}) AND ${NOT_A_SPARE} ORDER BY created`)
+            .all(...statuses);
+    }
+    else {
+        rows = db.prepare(`SELECT * FROM nodes WHERE ${NOT_A_SPARE} ORDER BY created`).all();
+    }
+    return rows.map(rowFrom);
+}
+// ---------------------------------------------------------------------------
+// Warm pool — spare booted roots awaiting a `prefer_warm` claim (see
+// `runtime/warm-pool.ts` for the recipe key and the mint/refill policy).
+// ---------------------------------------------------------------------------
+/** Mark an already-spawned node as an unclaimed spare for `recipeKey`. Hides it
+ *  from every listing until it is claimed. */
+export function registerWarmSpare(nodeId, recipeKey) {
+    withCanvasWrite((db) => {
+        db.prepare('INSERT OR REPLACE INTO warm_pool (node_id, recipe_key, created) VALUES (?, ?, ?)')
+            .run(nodeId, recipeKey, new Date().toISOString());
+    });
+}
+/** Take a parked spare OUT of the pool without claiming it — the reaper's
+ *  first move. Returns false when the marker was already gone (a concurrent
+ *  claim won it), which is the reaper's signal to leave that node alone: it is
+ *  somebody's live conversation now, not a spare. Deleting the marker under the
+ *  write lock is exactly what `claimWarmSpare` does, so the two can never both
+ *  succeed on the same node. */
+export function unregisterWarmSpare(nodeId) {
+    return withCanvasWrite((db) => db.prepare('DELETE FROM warm_pool WHERE node_id = ?').run(nodeId).changes > 0);
+}
+function warmSpareRowsFor(db, recipeKey) {
+    const sql = `SELECT w.node_id AS node_id, w.recipe_key AS recipe_key, w.created AS created,
+            n.status AS status, n.pi_pid AS pi_pid, n.pi_pid_identity AS pi_pid_identity
+       FROM warm_pool w JOIN nodes n ON n.node_id = w.node_id` +
+        (recipeKey === undefined ? '' : ' WHERE w.recipe_key = ?') +
+        ' ORDER BY w.created';
+    const rows = (recipeKey === undefined ? db.prepare(sql).all() : db.prepare(sql).all(recipeKey));
+    return rows.map((r) => ({
+        node_id: r['node_id'],
+        recipe_key: r['recipe_key'],
+        created: r['created'],
+        status: r['status'],
+        pi_pid: r['pi_pid'] ?? null,
+        pi_pid_identity: r['pi_pid_identity'] ?? null,
+    }));
+}
+/** Every parked spare, oldest first — what the reaper (`runtime/warm-pool.ts`
+ *  `reapStaleSpares`) sweeps. Deliberately NOT filtered by liveness: judging a
+ *  spare is the caller's job. */
+export function listWarmSpares() {
+    return warmSpareRowsFor(openDb());
+}
+/** True while `nodeId` is an UNCLAIMED spare — nobody owns this conversation
+ *  yet. `registerWarmSpare` runs the instant the row exists and BEFORE the
+ *  broker launch, and a claim deletes the marker atomically, so this is a
+ *  reliable read from inside the booting engine (the context-intro extension
+ *  asks it at `session_start` to withhold bearings that would otherwise assert
+ *  the spare's placeholder persona instead of its eventual claimant's). */
+export function isWarmSpare(nodeId) {
+    const row = openDb().prepare('SELECT 1 FROM warm_pool WHERE node_id = ?').get(nodeId);
+    return row !== undefined;
+}
+/** A spare is claimable only when its broker is CONFIRMED alive. Status alone
+ *  is not enough: a broker torn down by a daemon handover leaves the row at
+ *  `active`/`idle` with a dead pid, and handing that out would answer a create
+ *  with a node that has no engine behind it. The probe is identity-aware, so a
+ *  recycled pid never reads as alive; `indeterminate` (probe failed) is treated
+ *  as not-claimable — a cold spawn is cheap, a broken node is not. */
+function spareIsClaimable(row) {
+    if (row.status !== 'active' && row.status !== 'idle')
+        return false;
+    return recordedPidLiveness(row.pi_pid, row.pi_pid_identity) === 'alive';
+}
+/** Hand out the oldest CLAIMABLE spare matching `recipeKey`, or null when the
+ *  pool has none. The select+delete run inside ONE canvas write-lock
+ *  transaction, so two concurrent creates can never be handed the same spare.
+ *  A spare whose broker is gone is skipped here and reaped by
+ *  `reapStaleSpares` — nothing ever resumes a spare (the recovery sweep reads
+ *  `listNodes`, which hides them), so a dead spare is garbage, not a parked one.
+ *
+ *  The claim also restamps the row's `created` to `created` — birth time is a
+ *  spare's MINT time, and consumers sort conversations on it, so an hour-old
+ *  spare must not sort as an hour-old conversation. This is the one sanctioned
+ *  write of `created` after birth (`upsertRow` deliberately never touches it);
+ *  the caller mirrors the same stamp into meta.json. */
+export function claimWarmSpare(recipeKey, created) {
+    return withCanvasWrite((db) => {
+        const row = warmSpareRowsFor(db, recipeKey).find(spareIsClaimable);
+        if (row === undefined)
+            return null;
+        const res = db.prepare('DELETE FROM warm_pool WHERE node_id = ?').run(row.node_id);
+        if (res.changes === 0)
+            return null;
+        db.prepare('UPDATE nodes SET created = ? WHERE node_id = ?').run(created, row.node_id);
+        return row.node_id;
+    });
+}
+/** How many CLAIMABLE spares are parked for `recipeKey` (the depth check a
+ *  refill reads before minting). Uses the same liveness test as the claim, so a
+ *  spare the claim would skip can never hold the pool at depth 1 and starve
+ *  every later create of a warm start. */
+export function warmSpareCount(recipeKey) {
+    return warmSpareRowsFor(openDb(), recipeKey).filter(spareIsClaimable).length;
+}
+/** Direct children of `id`, oldest first — an indexed point query
+ *  (`idx_nodes_parent`) instead of a full-table `listNodes()` scan. */
+export function childrenOf(id) {
+    return openDb()
+        .prepare('SELECT node_id FROM nodes WHERE parent = ? ORDER BY created')
+        .all(id).map((r) => r.node_id);
+}
+/** Every node's lean roster row, oldest first — a single scan indexed by
+ *  `idx_nodes_created`. No per-row `getNode`/meta.json read, no N+1. */
+export function rosterNodes() {
+    return openDb()
+        .prepare(`SELECT node_id, name, kind, mode, lifecycle, status, cwd, host_kind, parent, created
+         FROM nodes WHERE ${NOT_A_SPARE} ORDER BY created`)
+        .all().map((r) => ({
+        node_id: r['node_id'],
+        name: r['name'],
+        kind: r['kind'],
+        mode: r['mode'],
+        lifecycle: r['lifecycle'],
+        status: r['status'],
+        cwd: r['cwd'],
+        host_kind: r['host_kind'] ?? null,
+        parent: r['parent'] ?? null,
+        created: r['created'],
+    }));
+}
+/** Every `subscribes_to` edge (passive + multiple preserved, never collapsed) —
+ *  a single scan indexed by `idx_edges_from`/`idx_edges_to` (composite
+ *  `(type, from_id|to_id)`, so a bare `type` predicate still uses one of
+ *  them). Paired with `rosterNodes()` as the roster's exactly-two-query
+ *  contract. */
+export function rosterEdges() {
+    return openDb()
+        .prepare(`SELECT from_id, to_id, active, created FROM edges WHERE type = 'subscribes_to' ORDER BY created`)
+        .all().map((r) => ({
+        from_id: r['from_id'],
+        to_id: r['to_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+/** Resumable ROOT conversations pinned to `cwd`, most-recently-created first.
+ *  A "root" is the top of a spine (`parent IS NULL`) that is a real
+ *  conversation (not a `kind:'human'` ask) and still resumable (`active`/`idle`,
+ *  never a `done`/`dead`/`canceled` node). This backs the front-door
+ *  `crtr -c`/`-r` resume: cwd is the key (the Claude-Code mental model — "my
+ *  last session HERE"), so it never teleports across projects. */
+export function listResumableRoots(cwd) {
+    const rows = openDb()
+        .prepare(`SELECT * FROM nodes
+        WHERE parent IS NULL AND kind != 'human'
+          AND status IN ('active','idle') AND cwd = ?
+          AND ${NOT_A_SPARE}
+        ORDER BY created DESC`)
+        .all(cwd);
+    return rows.map(rowFrom);
+}
+// ---------------------------------------------------------------------------
+// Edges
+// ---------------------------------------------------------------------------
+function addEdge(type, from, to, active) {
+    openDb()
+        .prepare(`INSERT INTO edges (type, from_id, to_id, active, created)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(type, from_id, to_id) DO UPDATE SET active=excluded.active`)
+        .run(type, from, to, active ? 1 : 0, new Date().toISOString());
+}
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export function subscribe(subscriber, publisher, active = true) {
+    addEdge('subscribes_to', subscriber, publisher, active);
+}
+/** Drop a subscription edge. */
+export function unsubscribe(subscriber, publisher) {
+    openDb()
+        .prepare('DELETE FROM edges WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run('subscribes_to', subscriber, publisher);
+}
+/** Flip an existing subscription's wake behavior. */
+export function setSubscriptionActive(subscriber, publisher, active) {
+    openDb()
+        .prepare('UPDATE edges SET active = ? WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run(active ? 1 : 0, 'subscribes_to', subscriber, publisher);
+}
+/** Record the audit-only `child spawned_by parent` edge. */
+export function recordSpawn(child, parent) {
+    addEdge('spawned_by', child, parent, true);
+}
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export function subscribersOf(publisher) {
+    return openDb()
+        .prepare(`SELECT from_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`)
+        .all(publisher).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export function subscriptionsOf(subscriber) {
+    return openDb()
+        .prepare(`SELECT to_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND from_id = ? ORDER BY created`)
+        .all(subscriber).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+// ---------------------------------------------------------------------------
+// Graph queries
+// ---------------------------------------------------------------------------
+/** A "view": every node whose output cascades up to `root` via subscriptions —
+ *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
+ *  Returns ids excluding root, in BFS order. Cycle-safe. */
+export function view(root) {
+    const seen = new Set([root]);
+    const out = [];
+    const queue = subscriptionsOf(root).map((s) => s.node_id);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+        for (const s of subscriptionsOf(id)) {
+            if (!seen.has(s.node_id))
+                queue.push(s.node_id);
+        }
+    }
+    return out;
+}
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export function hasActiveLiveSubscription(nodeId) {
+    const r = openDb()
+        .prepare(`SELECT 1 FROM edges e JOIN nodes n ON n.node_id = e.to_id
+       WHERE e.type = 'subscribes_to' AND e.from_id = ? AND e.active = 1
+         AND n.status IN ('active', 'idle') LIMIT 1`)
+        .get(nodeId);
+    return r !== undefined;
+}
+/** Whether a node explicitly awaits a controller that can still deliver. A
+ * parent relationship never implies this wait; the node must declare it. */
+export function hasLiveMessageWait(nodeId) {
+    const controller = getNode(nodeId)?.waiting_for;
+    if (controller == null)
+        return false;
+    const target = getNode(controller);
+    return target !== null && (target.status === 'active' || target.status === 'idle');
+}
+/** Settle an explicit message wait before appending the qualifying delivery.
+ * This ordering makes the delivery's one wake observe cleared durable state. */
+export function setMessageWait(nodeId, controller) {
+    openDb().prepare('UPDATE nodes SET waiting_for = ?, waiting_for_generation = waiting_for_generation + 1 WHERE node_id = ?').run(controller, nodeId);
+}
+/** Append a qualifying delivery and settle its matching wait while holding the
+ * canvas write lock. A concurrent `node wait controller` runs before or after this whole
+ * boundary, never between the durable inbox append and its compare-and-clear. */
+export function deliverAndSettleMessageWait(nodeId, from, deliver) {
+    return withCanvasWrite((db) => {
+        const armed = db.prepare('SELECT waiting_for_generation FROM nodes WHERE node_id = ? AND waiting_for = ?').get(nodeId, from);
+        const result = deliver();
+        if (from !== null && armed !== undefined) {
+            db.prepare('UPDATE nodes SET waiting_for = NULL WHERE node_id = ? AND waiting_for = ? AND waiting_for_generation = ?').run(nodeId, from, armed.waiting_for_generation);
+        }
+        return result;
+    });
+}
+/** Write one controller-death notice and settle only the still-current dead
+ * wait. The check, notice append, and clear share one canvas write boundary. */
+export function settleDeadMessageWait(nodeId, controller, deliver) {
+    return withCanvasWrite((db) => {
+        const row = db.prepare(`SELECT waiter.waiting_for, waiter.waiting_for_generation, target.status AS controller_status
+       FROM nodes AS waiter LEFT JOIN nodes AS target ON target.node_id = waiter.waiting_for
+       WHERE waiter.node_id = ?`).get(nodeId);
+        const live = row?.controller_status === 'active' || row?.controller_status === 'idle';
+        if (row?.waiting_for !== controller || live)
+            return null;
+        const result = deliver();
+        db.prepare('UPDATE nodes SET waiting_for = NULL WHERE node_id = ? AND waiting_for = ? AND waiting_for_generation = ?').run(nodeId, controller, row.waiting_for_generation);
+        return result;
+    });
+}
+/** #343: close the TOCTOU between checking a target has a natural cycle ahead
+ *  of it and the write that depends on that (for example, a deferred inbox
+ *  append). Fresh-reads `nodeId`'s
+ *  (status, final_report) and either runs `body` (a write) or short-circuits
+ *  with a `'terminal'`/`'missing'` outcome — the read and `body`'s write share
+ *  ONE canvas write-lock boundary (`withCanvasWrite`'s `BEGIN IMMEDIATE`), so
+ *  a concurrent finish/cancel/finalization/deletion either commits entirely
+ *  before this reads (observed here, `body` never runs) or entirely after
+ *  (`body` completes uncontested) — never in the gap a separate check-then-
+ *  write left open. Pass the shared `hasNoNaturalCycle` predicate rather than
+ *  a bespoke one so the two never drift.
+ *
+ *  #343 review (Major): a dangling `nodeId` — the row deleted after the
+ *  caller's own selection but before this guard's fresh read — MUST NEVER run
+ *  `body`. Reporting `'missing'` distinctly from `'terminal'` (rather than
+ *  folding it into either the terminal branch or a fabricated "safe" empty
+ *  snapshot) keeps the two failure shapes from being conflated: a terminal
+ *  target has a real `status`/`final_report` to report and its own
+ *  `deferred_no_natural_cycle`-style rejection, while a missing target has
+ *  nothing to report and belongs to the caller's own not-found contract. */
+export function withFreshTerminalGuard(nodeId, isTerminal, body) {
+    return withCanvasWrite((db) => {
+        const row = db
+            .prepare('SELECT status, final_report FROM nodes WHERE node_id = ?')
+            .get(nodeId);
+        if (row === undefined) {
+            return { kind: 'missing' };
+        }
+        if (isTerminal(row)) {
+            return { kind: 'terminal', status: row.status, final_report: row.final_report };
+        }
+        return { kind: 'ran', result: body() };
+    });
+}
+// ---------------------------------------------------------------------------
+// Index rebuild
+// ---------------------------------------------------------------------------
+/** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Only the IDENTITY columns are rebuilt — they are a projection of meta. The
+ *  runtime columns (status/intent/pi_pid/window/tmux_session/pane) are NOT in meta
+ *  and NOT re-derivable from it: they describe live process/presence state, so
+ *  an existing row keeps them and a freshly re-created row takes the schema's
+ *  quiescent defaults (status='active', the rest null). The daemon reconciles
+ *  liveness from tmux reality, not from a stale file.
+ *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
+ *  re-derived from each meta's `spawned_by` (fallback: `parent` for legacy metas). */
+export function rebuildIndex() {
+    if (!existsSync(nodesRoot()))
+        return;
+    // Collect every on-disk meta first, then index in TWO passes. Under the
+    // edges→nodes FK (migration v4), a `spawned_by` edge insert whose endpoint
+    // row isn't present yet violates the constraint — so ALL node rows must exist
+    // before ANY edge is added.
+    const metas = [];
+    for (const id of readdirSync(nodesRoot())) {
+        if (!existsSync(join(nodeDir(id), 'meta.json')))
+            continue;
+        const meta = readMeta(id);
+        if (!meta)
+            continue;
+        metas.push(meta);
+    }
+    // Pass 1 — upsert every node row (the edge endpoints).
+    for (const meta of metas)
+        upsertRow(meta);
+    // Pass 2 — add the audit-only `spawned_by` provenance edges. Skip any whose
+    // provenance node has no on-disk meta (a deleted/pruned ancestor): the FK
+    // would reject it, and an orphan provenance edge is exactly what v4 makes
+    // unrepresentable.
+    const known = new Set(metas.map((m) => m.node_id));
+    for (const meta of metas) {
+        const prov = meta.spawned_by ?? meta.parent;
+        if (prov && known.has(prov))
+            recordSpawn(meta.node_id, prov);
+    }
+}
+/** True when this node's identity is still required to own a managed checkout. */
+function hasOpenManagedWorktree(nodeId) {
+    return getNode(nodeId)?.managed_worktree?.state === 'open';
+}
+/** True when this node still carries a LIVE (`armed`/`pending`) follow-up human-work
+ *  receipt (design-followup-consult-v2.md §B.4; integrated-review Major-2).
+ *  An `armed` fork has not yet committed its final report; a `pending` fork
+ *  HAS committed it (promoted atomically inside `commitCanonicalFinal`'s own
+ *  transaction) but the receipt has not yet been acknowledged by
+ *  `submitFollowUpResult` — in both cases the node's on-disk report payload
+ *  (`reports/<final_report>` once pending) is still needed for delivery, so
+ *  neither status may ever be pruned/deleted out from under it. Queried via
+ *  raw SQL against the `consult_outbox` table directly (not the
+ *  `human-work-outbox.ts` peer module) to avoid a canvas.ts↔human-work-outbox.ts
+ *  import cycle — that module itself imports `getNode` from here. */
+function hasLiveFollowUpReceipt(nodeId) {
+    const r = openDb()
+        .prepare("SELECT 1 FROM consult_outbox WHERE node_id = ? AND work_kind = 'follow_up' AND status IN ('armed', 'pending') LIMIT 1")
+        .get(nodeId);
+    return r !== undefined;
+}
+/** Hard-delete ONE node: drop its row (the edges→nodes FK, ON DELETE CASCADE,
+ *  GCs its edges) and remove its on-disk `nodes/<id>/` dir. The single-node
+ *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
+ *  user closed or detached from. An open managed worktree is never deleted: its
+ *  node retains the ownership needed for `node worktree close`. Nor is a node
+ *  with a LIVE (`armed`/`pending`) follow-up human-work receipt — its report payload
+ *  is still needed for delivery (integrated-review Major-2). Pure persisted-
+ *  state removal: the caller MUST have already torn down the broker engine +
+ *  viewer (this does not signal any process). The node row and its FK-coupled
+ *  state are removed in one canvas write boundary. Best-effort dir removal
+ *  follows the commit. */
+export function deleteNode(nodeId) {
+    if (hasOpenManagedWorktree(nodeId) || hasLiveFollowUpReceipt(nodeId))
+        return { deleted: false };
+    const result = withCanvasWrite((db) => {
+        db.prepare('DELETE FROM nodes WHERE node_id = ?').run(nodeId);
+        return { deleted: true };
+    });
+    rmSync(nodeDir(nodeId), { recursive: true, force: true });
+    return result;
+}
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
+ *  node rows + dirs. Open managed-worktree nodes are retained so their checkout
+ *  remains owned until `node worktree close`. The edges→nodes FK (`ON DELETE
+ *  CASCADE`, migration v4) GCs each pruned node's edges automatically; the
+ *  on-disk `nodes/<id>/` dir is removed too.
+ *
+ *  With `includeStale`, ALSO prunes nominally-live (active | idle) nodes past the
+ *  TTL whose process is provably gone — `pi_pid` is NULL or no longer alive. This
+ *  reaps stale roots (a bare `crtr` whose pi died without the row transitioning),
+ *  which the daemon's supervision never reconciled. A genuinely-running node keeps
+ *  a live `pi_pid`, so it is protected, as is the CALLER ($CRTR_NODE_ID). Without
+ *  the flag, active | idle are NEVER touched (the daemon's domain).
+ *
+ *  Row deletes run in ONE transaction, so the sweep is all-or-nothing. Dir
+ *  removals follow after COMMIT — the fs isn't transactional, and by then
+ *  the rows are gone, so a re-run never re-finds a half-deleted node. `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export function pruneNodes(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const includeStale = opts.includeStale ?? false;
+    const cutoff = new Date(Date.now() - opts.ttlDays * 86_400_000).toISOString();
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const db = openDb();
+    const terminal = db
+        .prepare(`SELECT node_id, status, created FROM nodes
+         WHERE status IN ('dead', 'done', 'canceled') AND created < ?
+         ORDER BY created`)
+        .all(cutoff).map((r) => ({
+        node_id: r['node_id'],
+        status: r['status'],
+        created: r['created'],
+    }));
+    // Stale non-terminal sweep (opt-in): active | idle past the TTL whose process
+    // is provably gone (pi_pid NULL or not alive). Never the caller itself.
+    const stale = !includeStale ? [] : db
+        .prepare(`SELECT node_id, status, created, pi_pid FROM nodes
+         WHERE status IN ('active', 'idle') AND created < ?
+         ORDER BY created`)
+        .all(cutoff)
+        .filter((r) => {
+        if (r['node_id'] === selfId)
+            return false;
+        const pid = r['pi_pid'];
+        return !isPidAlive(pid);
+    })
+        .map((r) => ({
+        node_id: r['node_id'],
+        status: r['status'],
+        created: r['created'],
+    }));
+    const candidates = [...terminal, ...stale].filter((node) => !hasOpenManagedWorktree(node.node_id) && !hasLiveFollowUpReceipt(node.node_id));
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    deletePrunedNodes(candidates);
+    return { pruned: candidates, dryRun };
+}
+/** Hard-delete a set of pruned nodes in one transaction (the edges→nodes and
+ *  anchored-crons FKs cascade their coupled state), followed by best-effort
+ *  on-disk `nodes/<id>/` removal. Shared by TTL and count pruning so their
+ *  delete semantics never drift. */
+function deletePrunedNodes(candidates) {
+    if (candidates.length === 0)
+        return;
+    withCanvasWrite((db) => {
+        const del = db.prepare('DELETE FROM nodes WHERE node_id = ?');
+        for (const c of candidates)
+            del.run(c.node_id);
+    });
+    for (const c of candidates) {
+        rmSync(nodeDir(c.node_id), { recursive: true, force: true });
+    }
+}
+/** "Most recent activity" sort key (epoch ms) read CHEAPLY: a `statSync` (no file
+ *  read, no parse) of the node's `job/telemetry.json` — rewritten on every
+ *  turn_end at a deterministic path, so it tracks last-message recency without a
+ *  meta read. Falls back to `created`'s epoch when a node never ran a turn.
+ *  Mirrors render.ts's `sessionMtime` (the same key the snapshot roster surfaces
+ *  as `last_activity`). Never throws. */
+function recencyMs(nodeId, created) {
+    try {
+        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+        if (st !== undefined)
+            return st.mtimeMs;
+    }
+    catch {
+        /* fall through to created */
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+/** Count-based retention sweep: retain the `maxNodes` MOST-RECENTLY-ACTIVE
+ *  nodes plus every protected node, so the real retained floor is
+ *  `max(maxNodes, protectedCount)`. Bounds the otherwise-unbounded growth the
+ *  TTL sweep can't (a canvas that never crosses the TTL still grows without
+ *  limit).
+ *
+ *  Protected (never a prune candidate, regardless of recency rank): any
+ *  non-terminal node — status active|idle — REGARDLESS of `pi_pid` liveness,
+ *  a node with an open managed worktree, and a node with a LIVE
+ *  (`armed`/`pending`) follow-up human-work receipt. A crashed-but-non-terminal row
+ *  (dead pid, status still active/idle) must survive for daemon crash-recovery
+ *  to resume, an open worktree must retain its node ownership until
+ *  `node worktree close`, and a live consult receipt's report payload is still
+ *  needed for delivery (integrated-review Major-2); none of the three is
+ *  eligible for count-based pruning. The caller ($CRTR_NODE_ID) is also always
+ *  protected.
+ *
+ *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
+ *  to `created`); `target = max(maxNodes, protectedCount)`; delete every node
+ *  ranked beyond `target` (0-indexed rank >= target) that is NOT protected and
+ *  NOT the caller. Retained = all protected + the newest terminal nodes up to
+ *  `target`.
+ *
+ *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
+ *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export function pruneToLimit(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const rows = listNodes();
+    // Rank ALL nodes by recency DESC, tagging protection as we go. Protection is
+    // status-only (active|idle) — NOT gated on pi_pid liveness — so a node whose
+    // broker crashed but whose row is still non-terminal stays protected for
+    // crash-recovery instead of being hard-deleted here.
+    const ranked = rows
+        .map((r) => ({
+        node_id: r.node_id,
+        status: r.status,
+        created: r.created,
+        recency: recencyMs(r.node_id, r.created),
+        protected: r.status === 'active' || r.status === 'idle' || hasOpenManagedWorktree(r.node_id) || hasLiveFollowUpReceipt(r.node_id),
+    }))
+        .sort((a, b) => b.recency - a.recency);
+    const protectedCount = ranked.filter((r) => r.protected).length;
+    const target = Math.max(opts.maxNodes, protectedCount);
+    const candidates = ranked
+        .filter((r, rank) => rank >= target && !r.protected && r.node_id !== selfId)
+        .map((r) => ({ node_id: r.node_id, status: r.status, created: r.created }));
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    deletePrunedNodes(candidates);
+    return { pruned: candidates, dryRun };
+}