@north-light/api 0.3.580 → 0.3.588

package/dist/core/canvas/canvas.js

@@ -0,0 +1,1206 @@
+// The canvas data-access layer. Nodes, their sessions, executions, and managed
+// worktrees are SQL-authoritative. Node directories hold only artifacts.
+import { envNodeId } from '../../shared/env.js';
+import { lstatSync, realpathSync, rmdirSync, rmSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { removeTreeBeneath } from '../spaces/open-beneath.js';
+import { emitEvent } from '../events/emit.js';
+import { withCanvasWrite, openDb } from './db.js';
+import { conversationStore, ConversationNotFoundError } from '../conversation-store/index.js';
+import { hasUnseenWakeMail, UNSEEN_WAKE_MAIL_SQL } from './deliveries.js';
+import { isAppRun } from './app-run.js';
+import { registerOutcomeAction } from './outcome-actions.js';
+import { publish } from '../graph/events.js';
+import { nodeObject } from '../graph/objects.js';
+import { findNodeBySessionFileSql } from './sessions.js';
+import { hydrateFault } from './recovery.js';
+import { hasUnreconciledWorktree, openWorktree, readWorktree, worktreeFromRow } from './worktrees.js';
+import { isPidAlive, isPidPresent, recordedPidLiveness } from './pid.js';
+import { ensureHome, jobDir, nodeDir, nodeRunDir } from './paths.js';
+import { appForNode, ensureNodeDirs, nodeAgentDir } from './node-agent-paths.js';
+import { appSpace } from '../layout.js';
+import { createObject, getById, ownerForGrantee, setObjectKind, setObjectName } from '../graph/objects.js';
+import { profileObject } from '../graph/reader.js';
+import { writeActsFor } from '../permissions/facts.js';
+import { CrtrError } from '../errors.js';
+import { deleteNodeWithOwned } from '../graph/deletion.js';
+import { SUBTREE_ALL_IDS_SQL, SUBTREE_IDS_SQL } from './tree.js';
+import { filterAsync, mapAsync } from '../async-array.js';
+function jsonValue(value, field) {
+    if (value === undefined || value === null)
+        return null;
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new TypeError(`${field} must be JSON-serializable`);
+    return encoded;
+}
+export async function assertRunNotDeleting(db, runId) {
+    if ((await db.prepare('SELECT deleting_at FROM nodes WHERE node_id = ?').get(runId))?.deleting_at)
+        throw new Error('run is deleting');
+}
+/** The profile's object (made on first use), or null when the profile has no stored manifest to name one from. */
+async function profileObjectFor(db, profileId, app) {
+    try {
+        return await profileObject(db, profileId, app);
+    }
+    catch (e) {
+        if (e instanceof CrtrError && e.code === 'not_found')
+            return null;
+        throw e;
+    }
+}
+async function seedRow(meta, db) {
+    const app = await ownerForGrantee(db, meta.grantee ?? 'app:terminal');
+    // The node sits under its profile's object when it has one; otherwise directly under its app.
+    const profile = meta.profile_id ? await profileObjectFor(db, meta.profile_id, app) : null;
+    await createObject(db, { id: meta.node_id, type: 'node', kind: meta.kind, owner: (profile ?? app).id, privacy: 'public', name: meta.name, preview: '' });
+    // A node directly under an app is readable by the person it was made for.
+    if (profile === null && meta.sub)
+        await writeActsFor(db, meta.node_id, meta.sub);
+    await db.prepare(`INSERT INTO nodes (node_id, description, title, icon, cycles, mode, lifecycle, cwd, host_kind, profile_id, parent, spawned_by, creator, fork_from, fork_source_file, created, passive_default, cycle_pending, model_override, persona_ack_json, review_binding_json, launch_config_json, scopes_json, isolated, status, intent, final_report, finalized_at, deadline_at, "window", tmux_session, pane, sub, grant_id, client_id, metadata_json, run_id, event_cursor, usage_json, deleting_at, caused_by, app) VALUES (${Array(42).fill('?').join(', ')})`)
+        .run(meta.node_id, meta.description ?? null, meta.title ?? null, meta.icon ?? null, meta.cycles ?? null, meta.mode, meta.lifecycle, meta.cwd, meta.host_kind ?? null, meta.profile_id ?? null, meta.parent ?? null, meta.spawned_by ?? null, meta.creator ?? null, meta.fork_from ?? null, meta.fork_source_file ?? null, meta.created, meta.passive_default === true ? 1 : 0, meta.cycle_pending === true ? 1 : 0, meta.model_override ?? null, jsonValue(meta.persona_ack, 'persona_ack'), jsonValue(meta.review_binding, 'review_binding'), jsonValue(meta.launch, 'launch'), jsonValue(meta.scopes, 'scopes'), meta.isolated === true ? 1 : 0, meta.status ?? 'active', meta.intent ?? null, meta.final_report ?? null, meta.finalized_at ?? null, meta.deadline_at ?? null, meta.window ?? null, meta.tmux_session ?? null, meta.pane ?? null, meta.sub ?? null, meta.grant_id ?? null, meta.client_id ?? null, meta.metadata_json ?? null, meta.run_id ?? null, meta.event_cursor ?? null, meta.usage_json ?? null, meta.deleting_at ?? null, meta.caused_by ?? null, app.id);
+}
+/** The `node_rows` view projects the active fault's columns under a `fault_`
+ * prefix; strip it and hydrate through the same mapper `readFault` uses. */
+function faultFrom(r) {
+    if (r['fault_id'] == null)
+        return null;
+    const columns = Object.entries(r).filter(([key]) => key.startsWith('fault_')).map(([key, value]) => [key === 'fault_id' ? key : key.slice('fault_'.length), value]);
+    return hydrateFault(Object.fromEntries(columns));
+}
+function rowFrom(r) {
+    const node = {
+        node_id: r['node_id'],
+        name: r['name'],
+        description: r['description'] ?? undefined,
+        cycles: r['cycles'] ?? undefined,
+        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,
+        scopes: r['scopes_json'] == null ? null : JSON.parse(r['scopes_json']),
+        isolated: r['isolated'] === 1,
+        grantee: r['grantee'],
+        sub: r['sub'] ?? null,
+        grant_id: r['grant_id'] ?? null,
+        client_id: r['client_id'] ?? null,
+        metadata_json: r['metadata_json'] ?? null,
+        run_id: r['run_id'] ?? null,
+        event_cursor: r['event_cursor'] ?? null,
+        last_activity_at: r['last_activity_at'] ?? null,
+        usage_json: r['usage_json'] ?? null,
+        caused_by: r['caused_by'] ?? null,
+        last_turn_error_json: r['last_turn_error_json'] ?? null,
+        deleting_at: r['deleting_at'] ?? null,
+        parent: r['parent'] ?? null,
+        created: r['created'],
+        intent: r['intent'] ?? null,
+        frozen_at: r['frozen_at'] ?? null,
+        respawn_failures: r['respawn_failures'] ?? 0,
+        respawn_not_before: r['respawn_not_before'] ?? null,
+        launched_at: r['launched_at'] ?? null,
+        last_settled_at: r['last_settled_at'] ?? null,
+        terminal_reason: r['terminal_reason'] ?? null,
+        final_report: r['final_report'] ?? null,
+        finalized_at: r['finalized_at'] ?? null,
+        outcome_kind: r['outcome_kind'] ?? null,
+        outcome_reason: r['outcome_reason'] ?? null,
+        outcome_at: r['outcome_at'] ?? null,
+        outcome_revision: r['outcome_revision'] ?? 0,
+        outcome_detail_json: r['outcome_detail_json'] ?? null,
+        deadline_at: r['deadline_at'] ?? null,
+        telemetry_tokens_in: r['telemetry_tokens_in'] ?? null,
+        telemetry_context_tokens: r['telemetry_context_tokens'] ?? null,
+        telemetry_last_activity: r['telemetry_last_activity'] ?? null,
+        telemetry_updated_at: r['telemetry_updated_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,
+        fault: null,
+        streaming: false,
+    };
+    const pidAlive = isPidPresent(node.pi_pid);
+    const fault = faultFrom(r);
+    node.fault = fault?.link === 'pi→provider' && fault.retry.by === 'daemon' && fault.retry.disposition === 'auto' && !pidAlive
+        ? null
+        : fault;
+    node.streaming = r['turn_open_at'] !== null && r['turn_closed_at'] === null && pidAlive;
+    return node;
+}
+async function metaFrom(r, worktree) {
+    worktree ??= await readWorktree(r['node_id']);
+    return {
+        ...rowFrom(r),
+        title: r['title'] ?? undefined,
+        icon: r['icon'] ?? undefined,
+        spawned_by: r['spawned_by'] ?? null,
+        creator: r['creator'] ?? null,
+        fork_from: r['fork_from'] ?? null,
+        fork_source_file: r['fork_source_file'] ?? null,
+        passive_default: r['passive_default'] === 1,
+        cycle_pending: r['cycle_pending'] === 1,
+        model_override: r['model_override'] ?? null,
+        scopes: r['scopes_json'] == null ? null : JSON.parse(r['scopes_json']),
+        persona_ack: r['persona_ack_json'] == null ? undefined : JSON.parse(r['persona_ack_json']),
+        review_binding: r['review_binding_json'] == null ? undefined : JSON.parse(r['review_binding_json']),
+        launch: r['launch_config_json'] == null ? undefined : JSON.parse(r['launch_config_json']),
+        pi_session_id: r['pi_session_id'] ?? null,
+        pi_session_file: r['pi_session_file'] ?? null,
+        ...(worktree === null ? {} : { managed_worktree: worktree }),
+    };
+}
+// Nodes
+/** Create a SQL-authoritative node, then ensure its artifact directories exist. */
+export async function createNode(meta, opts = {}) {
+    ensureHome();
+    await withCanvasWrite(async (db) => {
+        await seedRow(meta, db);
+        if (meta.managed_worktree !== undefined && meta.managed_worktree !== null)
+            await openWorktree(meta.node_id, meta.managed_worktree, db);
+        if (opts.outcomeDelivery !== undefined)
+            await registerOutcomeAction(db, meta.node_id, opts.outcomeDelivery);
+        await opts.withinCreate?.(db, meta);
+    });
+    await ensureNodeDirs(meta.node_id);
+    return await getNode(meta.node_id);
+}
+/** The canonical node record, hydrated from SQL. Null if unknown. */
+export async function getNode(nodeId) {
+    const row = await (await openDb()).prepare('SELECT * FROM node_rows WHERE node_id = ?').get(nodeId);
+    if (row === undefined)
+        return null;
+    return await metaFrom(row);
+}
+/** The canonical node records for `nodeIds` in the order given, read with their worktrees in one query. Unknown ids are skipped. */
+export async function getNodes(nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    const worktreeProjection = WORKTREE_COLUMNS.map((column) => `w.${column} AS worktree_${column}`).join(', ');
+    const rows = await (await openDb())
+        .prepareUncached(`SELECT n.*, ${worktreeProjection} FROM node_rows n LEFT JOIN worktrees w ON w.node_id = n.node_id WHERE n.node_id IN (${nodeIds.map(() => '?').join(',')})`)
+        .all(...nodeIds);
+    const byId = new Map(rows.map((row) => [row['node_id'], row]));
+    return await mapAsync(nodeIds.map((id) => byId.get(id)).filter((row) => row !== undefined), async (row) => await metaFrom(row, worktreeFromProjection(row)));
+}
+const CREATE_REQUEST_TTL_MS = 24 * 60 * 60 * 1000;
+function createRequestRecord(row) {
+    return { requestKey: row.request_key, nodeId: row.node_id, state: row.state };
+}
+export async function findCreateRequest(requestKey) {
+    const existing = await (await openDb()).prepareUncached('SELECT request_key, node_id, state FROM create_requests WHERE request_key = ?').get(requestKey);
+    return existing === undefined ? null : createRequestRecord(existing);
+}
+/** Reserve an idempotency key before creation. A null node id means the request
+ *  has not yet selected a cold-birth identity or claimed a warm spare. */
+export async function reserveCreateRequest(requestKey) {
+    return await withCanvasWrite(async (db) => {
+        const now = Date.now();
+        await db.prepareUncached('DELETE FROM create_requests WHERE expires_at <= ?').run(now);
+        // One atomic claim: a concurrent reservation of the same key (another process) waits on the first insert, does nothing,
+        // and then reads the row that won.
+        await db.prepareUncached("INSERT INTO create_requests (request_key, node_id, expires_at, state) VALUES (?, NULL, ?, 'reserved') ON CONFLICT (request_key) DO NOTHING")
+            .run(requestKey, now + CREATE_REQUEST_TTL_MS);
+        const winner = await db.prepareUncached('SELECT request_key, node_id, state FROM create_requests WHERE request_key = ?').get(requestKey);
+        return createRequestRecord(winner);
+    });
+}
+/** Delete keys past their recovery window; returns how many were removed. */
+export async function pruneExpiredCreateRequests(now = Date.now()) {
+    return Number((await (await openDb()).prepareUncached('DELETE FROM create_requests WHERE expires_at <= ?').run(now)).changes);
+}
+/** Bind a reserved key to the node it created (state `complete`). The mapping is
+ *  durable so a retry after a daemon handover returns the original node. */
+export async function recordCreateRequestNode(requestKey, nodeId) {
+    await (await openDb()).prepareUncached("UPDATE create_requests SET node_id = ?, state = 'complete' WHERE request_key = ?").run(nodeId, requestKey);
+}
+/** Reserve a cold-birth node id for a key (state stays `reserved`) so a retry
+ *  after a daemon restart resumes the same identity instead of minting another.
+ *  Only the first caller binds: two API processes holding one unbound key race
+ *  here, and each gets back the id the key actually names. */
+export async function reserveCreateRequestNode(requestKey, nodeId) {
+    const db = await openDb();
+    await db.prepareUncached("UPDATE create_requests SET node_id = ?, state = 'reserved' WHERE request_key = ? AND node_id IS NULL").run(nodeId, requestKey);
+    const bound = await db.prepareUncached('SELECT node_id FROM create_requests WHERE request_key = ?').get(requestKey);
+    return bound?.node_id ?? null;
+}
+export async function completeCreateRequest(requestKey, nodeId) {
+    await (await openDb()).prepareUncached("UPDATE create_requests SET state = 'complete' WHERE request_key = ? AND node_id = ?").run(requestKey, nodeId);
+}
+/** Forget an unserved reservation after a pre-birth failure. A record that
+ *  names a durable node is never removed by this path. */
+export async function abandonCreateRequest(requestKey, nodeId) {
+    await withCanvasWrite(async (db) => {
+        if (nodeId === null) {
+            await db.prepareUncached('DELETE FROM create_requests WHERE request_key = ? AND node_id IS NULL').run(requestKey);
+            return;
+        }
+        await db.prepareUncached('DELETE FROM create_requests WHERE request_key = ? AND node_id = ?').run(requestKey, nodeId);
+    });
+}
+export function canonicalSessionFile(sessionFile) {
+    return resolve(sessionFile);
+}
+/** Resolve the crouter node that owns one exact Pi session file. */
+export async function findNodeBySessionFile(sessionFile) {
+    const nodeId = await findNodeBySessionFileSql(sessionFile);
+    return nodeId === null ? null : await getNode(nodeId);
+}
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export async function getRow(nodeId) {
+    const r = await (await openDb()).prepare('SELECT * FROM node_rows 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 async function getRowByPane(pane) {
+    const r = await (await openDb()).prepare('SELECT * FROM node_rows WHERE pane = ?').get(pane);
+    return r ? rowFrom(r) : null;
+}
+/** Nodes whose persisted spawn deadline has elapsed and that remain live work. */
+export async function dueNodeDeadlines(nowIso) {
+    return (await (await openDb()).prepare(`SELECT * FROM node_rows
+     WHERE deadline_at IS NOT NULL AND outcome_at IS NULL
+       AND deadline_at <= ? AND status IN ('active','idle') AND kind != 'human'
+     ORDER BY deadline_at, created, node_id`).all(nowIso)).map(rowFrom);
+}
+/** Write a claimed warm spare's deadline before it is handed to its caller. */
+export async function setNodeDeadline(nodeId, deadlineAt) {
+    return Number((await (await openDb()).prepare('UPDATE nodes SET deadline_at = ? WHERE node_id = ?').run(deadlineAt, nodeId)).changes) === 1;
+}
+/** Shift active/idle profile deadlines by a completed profile pause duration. */
+export async function shiftProfileNodeDeadlines(profileId, pauseDurationMs) {
+    if (!Number.isFinite(pauseDurationMs) || pauseDurationMs <= 0)
+        return 0;
+    return await withCanvasWrite(async (db) => {
+        const rows = await db.prepare(`SELECT node_id, deadline_at FROM nodes
+       WHERE profile_id = ? AND deadline_at IS NOT NULL AND status IN ('active', 'idle')`).all(profileId);
+        const update = db.prepare('UPDATE nodes SET deadline_at = ? WHERE node_id = ? AND deadline_at = ?');
+        let shifted = 0;
+        for (const row of rows) {
+            const at = Date.parse(row.deadline_at);
+            if (Number.isNaN(at))
+                continue;
+            shifted += Number((await update.run(new Date(at + pauseDurationMs).toISOString(), row.node_id, row.deadline_at)).changes);
+        }
+        return shifted;
+    });
+}
+function sqlInput(value, field) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint' || value instanceof Uint8Array)
+        return value;
+    throw new TypeError(`${field} must be a SQLite scalar`);
+}
+/** Update node identity/configuration columns. Sessions and worktrees have named stores. */
+export async function updateNode(nodeId, patch) {
+    const fields = [];
+    const add = (key, column = key) => {
+        if (Object.prototype.hasOwnProperty.call(patch, key))
+            fields.push([column, sqlInput(patch[key], key)]);
+    };
+    add('description');
+    add('title');
+    add('icon');
+    add('cycles');
+    add('mode');
+    add('lifecycle');
+    add('cwd');
+    add('host_kind');
+    add('profile_id');
+    add('parent');
+    add('spawned_by');
+    add('creator');
+    add('fork_from');
+    add('fork_source_file');
+    add('model_override');
+    if (Object.prototype.hasOwnProperty.call(patch, 'passive_default'))
+        fields.push(['passive_default', patch.passive_default === true ? 1 : 0]);
+    if (Object.prototype.hasOwnProperty.call(patch, 'cycle_pending'))
+        fields.push(['cycle_pending', patch.cycle_pending === true ? 1 : 0]);
+    if (Object.prototype.hasOwnProperty.call(patch, 'persona_ack'))
+        fields.push(['persona_ack_json', jsonValue(patch.persona_ack, 'persona_ack')]);
+    if (Object.prototype.hasOwnProperty.call(patch, 'review_binding'))
+        fields.push(['review_binding_json', jsonValue(patch.review_binding, 'review_binding')]);
+    // Isolation is fixed at birth; updateNode must never weaken it.
+    if (Object.prototype.hasOwnProperty.call(patch, 'isolated'))
+        throw new TypeError('isolated cannot change after node creation');
+    if (Object.prototype.hasOwnProperty.call(patch, 'scopes'))
+        fields.push(['scopes_json', jsonValue(patch.scopes, 'scopes')]);
+    if (Object.prototype.hasOwnProperty.call(patch, 'launch'))
+        fields.push(['launch_config_json', jsonValue(patch.launch, 'launch')]);
+    const has = (key) => Object.prototype.hasOwnProperty.call(patch, key);
+    await withCanvasWrite(async (db) => {
+        const object = await getById(db, nodeId);
+        if (object === null || object.type !== 'node')
+            throw new Error(`unknown node: ${nodeId}`);
+        if (has('name'))
+            await setObjectName(db, object, sqlInput(patch.name, 'name'));
+        if (has('kind'))
+            await setObjectKind(db, object, sqlInput(patch.kind, 'kind'));
+        if (fields.length === 0)
+            return;
+        // A profile change moves the node under the new profile's object, or back under its app when it has none.
+        if (has('profile_id')) {
+            const app = await db.prepare('SELECT app FROM nodes WHERE node_id = ?').get(nodeId);
+            const appObject = app?.app ? await getById(db, app.app) : null;
+            if (appObject) {
+                const profile = patch.profile_id ? await profileObjectFor(db, patch.profile_id, appObject) : null;
+                await db.prepare('UPDATE objects SET owner = ? WHERE id = ?').run((profile ?? appObject).id, nodeId);
+                const sub = (await db.prepare('SELECT sub FROM nodes WHERE node_id = ?').get(nodeId)).sub;
+                if (profile === null && sub)
+                    await writeActsFor(db, nodeId, sub);
+            }
+        }
+        const result = await db.prepareUncached(`UPDATE nodes SET ${fields.map(([column]) => `${column} = ?`).join(', ')} WHERE node_id = ?`).run(...fields.map(([, value]) => value), nodeId);
+        if (result.changes !== 1)
+            throw new Error(`unknown node: ${nodeId}`);
+    });
+    return await 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 async function setStatus(nodeId, status) {
+    await (await openDb()).prepare('UPDATE nodes SET status = ? WHERE node_id = ?').run(status, nodeId);
+}
+/** Set a node's exit intent. Atomic single-column write. */
+export async function setIntent(nodeId, intent) {
+    await (await openDb()).prepare('UPDATE nodes SET intent = ? WHERE node_id = ?').run(intent ?? null, nodeId);
+}
+/** Atomically write status and/or intent, gated on an optional from-status set
+ *  and/or on the row carrying no committed final_report. The lifecycle state
+ *  machine (runtime/lifecycle.ts) is the one caller: it owns the legality
+ *  table and the unknown-node/illegal-move/already-finalized-cancel branching,
+ *  this only performs the single conditional UPDATE it needs. A PRESENT key in
+ *  `fields` (even `intent: null`) writes that column; an ABSENT key leaves it
+ *  unchanged. Returns the row-changed count so the caller can distinguish "no
+ *  such node", "gate failed", and "already applied" without a second query. */
+export async function transitionStatusIntent(nodeId, fields, opts = {}) {
+    // Keep the ordinary lifecycle write exactly as its pre-outcome form: one
+    // conditional UPDATE and no transaction boundary.
+    if (opts.outcome === undefined) {
+        const assignments = [];
+        const values = [];
+        if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
+            assignments.push('status = ?');
+            values.push(fields.status ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
+            assignments.push('intent = ?');
+            values.push(fields.intent ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
+            assignments.push('terminal_reason = ?');
+            values.push(fields.terminal_reason ?? null);
+        }
+        const predicates = ['node_id = ?'];
+        values.push(nodeId);
+        if (opts.fromStatuses !== undefined) {
+            predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
+            values.push(...opts.fromStatuses);
+        }
+        if (opts.requireNoFinalReport === true)
+            predicates.push('final_report IS NULL');
+        const result = await (await openDb())
+            .prepareUncached(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`)
+            .run(...values);
+        return Number(result.changes);
+    }
+    const outcome = opts.outcome;
+    return await withCanvasWrite(async (db) => {
+        const assignments = [];
+        const values = [];
+        if (Object.prototype.hasOwnProperty.call(fields, 'status')) {
+            assignments.push('status = ?');
+            values.push(fields.status ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'intent')) {
+            assignments.push('intent = ?');
+            values.push(fields.intent ?? null);
+        }
+        if (Object.prototype.hasOwnProperty.call(fields, 'terminal_reason')) {
+            assignments.push('terminal_reason = ?');
+            values.push(fields.terminal_reason ?? null);
+        }
+        const outcomeValue = (value, column) => outcome.supersede === true ? '?' : `CASE WHEN outcome_at IS NULL THEN ? ELSE ${column} END`;
+        assignments.push(`outcome_kind = ${outcomeValue(outcome.kind, 'outcome_kind')}`, `outcome_reason = ${outcomeValue(outcome.reason, 'outcome_reason')}`, `outcome_detail_json = ${outcomeValue(outcome.detailJson, 'outcome_detail_json')}`, `outcome_revision = ${outcome.supersede === true ? 'outcome_revision + 1' : 'CASE WHEN outcome_at IS NULL THEN outcome_revision + 1 ELSE outcome_revision END'}`, `outcome_at = ${outcomeValue(outcome.at, 'outcome_at')}`);
+        values.push(outcome.kind, outcome.reason, outcome.detailJson, outcome.at);
+        const predicates = ['node_id = ?'];
+        values.push(nodeId);
+        if (opts.fromStatuses !== undefined) {
+            predicates.push(`status IN (${opts.fromStatuses.map(() => '?').join(', ')})`);
+            values.push(...opts.fromStatuses);
+        }
+        if (opts.requireNoFinalReport === true)
+            predicates.push('final_report IS NULL');
+        const result = await db.prepareUncached(`UPDATE nodes SET ${assignments.join(', ')} WHERE ${predicates.join(' AND ')}`).run(...values);
+        if (Number(result.changes) === 0)
+            return 0;
+        const latched = await db.prepare('SELECT outcome_at FROM nodes WHERE node_id = ?').get(nodeId);
+        if ((outcome.supersede === true || latched.outcome_at === outcome.at) && outcome.documentJson !== null && outcome.documentJson !== undefined) {
+            await publish(db, { event: 'outcome', object: await nodeObject(db, nodeId), actor: null,
+                attrs: { revision: Number((await db.prepare('SELECT outcome_revision FROM nodes WHERE node_id = ?').get(nodeId)).outcome_revision) },
+                messageBody: JSON.parse(outcome.documentJson) });
+        }
+        return Number(result.changes);
+    });
+}
+/** Read a node's committed-final latch pointer. Pure read, no side effect. */
+export async function getFinalReport(nodeId) {
+    const row = await (await openDb()).prepare('SELECT final_report FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.final_report ?? null;
+}
+/** CAS-clear a node's finalization latch (final_report + finalized_at) —
+ *  retract-pointer-only. Gated on the exact final_report value the caller
+ *  observed via getFinalReport, so a concurrent clear/refinalize can never be
+ *  clobbered. Returns true iff the CAS matched and cleared. */
+export async function clearFinalReportIfMatches(nodeId, expectedFinalReport) {
+    const result = await (await openDb()).prepare('UPDATE nodes SET final_report = NULL, finalized_at = NULL WHERE node_id = ? AND final_report = ?')
+        .run(nodeId, expectedFinalReport);
+    return result.changes > 0;
+}
+/** 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 async function setPresence(nodeId, presence) {
+    await (await openDb()).prepare('UPDATE nodes SET tmux_session = ?, "window" = ?, pane = ? WHERE node_id = ?')
+        .run(presence.tmux_session ?? null, presence.window ?? null, presence.pane ?? null, nodeId);
+}
+export async function recordLaunch(nodeId, at) {
+    await (await openDb()).prepare('UPDATE nodes SET launched_at = ?, frozen_at = NULL, respawn_not_before = NULL WHERE node_id = ?')
+        .run(at, nodeId);
+}
+export async function recordSettledTurn(nodeId, at) {
+    await (await openDb()).prepare('UPDATE nodes SET last_settled_at = ? WHERE node_id = ?').run(at, nodeId);
+}
+export async function setFrozen(nodeId, at) {
+    await (await openDb()).prepare('UPDATE nodes SET frozen_at = ? WHERE node_id = ?').run(at, nodeId);
+}
+export async function clearFrozen(nodeId) {
+    await (await openDb()).prepare('UPDATE nodes SET frozen_at = NULL WHERE node_id = ?').run(nodeId);
+}
+export async function recordRespawnAttempt(nodeId, attempt) {
+    await (await openDb()).prepare('UPDATE nodes SET respawn_failures = ?, respawn_not_before = ? WHERE node_id = ?')
+        .run(attempt.failures, attempt.notBefore, nodeId);
+}
+/** 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)';
+/** Every hydrated node whose durable profile identity equals `profileId`.
+ *  Unlike `listNodes`, this includes unclaimed warm-pool spares: profile
+ *  deletion owns every matching row, whether or not it is user-visible. */
+const WORKTREE_COLUMNS = [
+    'state', 'cleanup_state', 'path', 'branch', 'repo_root', 'base_ref', 'base_sha', 'created_at', 'closed_at',
+    'next_attempt_at', 'attempts', 'quarantined', 'sweep_reason', 'sweep_detail', 'sweep_last_at', 'sweep_observed_json',
+    'abandoned_json', 'land_intent_json', 'disposal_json',
+];
+function worktreeFromProjection(r) {
+    if (r['worktree_state'] === null)
+        return null;
+    return worktreeFromRow(Object.fromEntries(WORKTREE_COLUMNS.map((column) => [column, r[`worktree_${column}`]])));
+}
+export async function listNodesByProfile(profileId) {
+    const worktreeProjection = WORKTREE_COLUMNS.map((column) => `w.${column} AS worktree_${column}`).join(', ');
+    const rows = await (await openDb())
+        .prepareUncached(`SELECT n.*, ${worktreeProjection} FROM node_rows n LEFT JOIN worktrees w ON w.node_id = n.node_id WHERE n.profile_id = ? ORDER BY n.created`)
+        .all(profileId);
+    return (await mapAsync(rows, async (row) => await metaFrom(row, worktreeFromProjection(row))));
+}
+/** Browse's first frame: select only fields its rows/tree use. Keep the fault and
+ * turn columns for rowFrom's live fault/streaming semantics, but never hydrate
+ * outcomes, placement, metadata or the (often large) telemetry activity text. */
+export async function browseNodes() {
+    const db = await openDb();
+    const rows = await db.prepare(`SELECT
+      node_id, name, description, kind, mode, lifecycle, status, cwd, profile_id,
+      grantee, parent, created, frozen_at, terminal_reason, final_report,
+      telemetry_tokens_in, telemetry_updated_at, pi_pid, turn_open_at, turn_closed_at,
+      fault_id, fault_link, fault_op, fault_kind, fault_message, fault_since,
+      fault_operation_id, fault_anchor_entry_id, fault_retry_disposition,
+      fault_retry_by, fault_retry_attempt, fault_retry_max, fault_retry_next_at,
+      fault_provider_error_json
+    FROM node_rows WHERE ${NOT_A_SPARE} ORDER BY created`).all();
+    return rows.map(rowFrom);
+}
+/** All rows, optionally filtered by status and terminal execution traces. Unclaimed warm spares are excluded. */
+export async function updateNodeTelemetry(nodeId, telemetry) {
+    await (await openDb()).prepare(`UPDATE nodes
+    SET telemetry_tokens_in = ?,
+        telemetry_context_tokens = COALESCE(?, telemetry_context_tokens),
+        telemetry_last_activity = COALESCE(?, telemetry_last_activity),
+        telemetry_updated_at = ?
+    WHERE node_id = ?
+      AND (telemetry_updated_at IS NULL OR telemetry_updated_at < ?)`).run(telemetry.tokensIn, telemetry.contextTokens, telemetry.lastActivity, telemetry.updatedAt, nodeId, telemetry.updatedAt);
+}
+/** Stored fields the attach graph displays, plus the two live execution cues it
+ * needs. This keeps the interactive graph off the full node-summary projection
+ * and its unused runtime, outcome, and placement fields. */
+export async function graphNodes() {
+    const rows = await (await openDb()).prepare(`SELECT
+      node_id, name, description, cycles, kind, status, frozen_at,
+      telemetry_context_tokens, telemetry_last_activity,
+      pi_pid, turn_open_at, turn_closed_at,
+      fault_id, fault_link, fault_op, fault_kind, fault_message, fault_since,
+      fault_operation_id, fault_anchor_entry_id, fault_retry_disposition,
+      fault_retry_by, fault_retry_attempt, fault_retry_max, fault_retry_next_at,
+      fault_provider_error_json
+    FROM node_rows WHERE ${NOT_A_SPARE} ORDER BY created`).all();
+    return rows.map((row) => {
+        const pid = row['pi_pid'] ?? null;
+        const pidAlive = isPidPresent(pid);
+        const fault = faultFrom(row);
+        return {
+            node_id: row['node_id'],
+            name: row['name'],
+            description: row['description'] ?? null,
+            cycles: row['cycles'] ?? null,
+            kind: row['kind'],
+            status: row['status'],
+            frozen_at: row['frozen_at'] ?? null,
+            pi_pid: pid,
+            telemetry_context_tokens: row['telemetry_context_tokens'] ?? null,
+            telemetry_last_activity: row['telemetry_last_activity'] ?? null,
+            fault: fault?.link === 'pi→provider' && fault.retry.by === 'daemon' && fault.retry.disposition === 'auto' && !pidAlive
+                ? null
+                : fault,
+            streaming: row['turn_open_at'] !== null && row['turn_closed_at'] === null && pidAlive,
+        };
+    });
+}
+export async function listNodes(filter) {
+    const clauses = [NOT_A_SPARE];
+    const params = [];
+    if (filter?.under !== undefined) {
+        if (filter.underInclusive === true) {
+            clauses.push(`(node_id IN (${SUBTREE_ALL_IDS_SQL}) OR node_id = ?)`);
+            params.push(filter.under, filter.under, filter.under);
+        }
+        else {
+            clauses.push(`node_id IN (${SUBTREE_IDS_SQL})`);
+            params.push(filter.under, filter.under);
+        }
+    }
+    if (filter?.lifecycle !== undefined) {
+        clauses.push('lifecycle = ?');
+        params.push(filter.lifecycle);
+    }
+    if (filter?.kind !== undefined) {
+        clauses.push('kind = ?');
+        params.push(filter.kind);
+    }
+    if (filter?.mode !== undefined) {
+        clauses.push('mode = ?');
+        params.push(filter.mode);
+    }
+    if (filter?.profileId !== undefined) {
+        clauses.push('profile_id = ?');
+        params.push(filter.profileId);
+    }
+    if (filter?.profilePrefix !== undefined) {
+        clauses.push(`profile_id LIKE ? ESCAPE '\\'`);
+        params.push(`${filter.profilePrefix.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
+    }
+    if (filter?.parent !== undefined) {
+        clauses.push('parent = ?');
+        params.push(filter.parent);
+    }
+    if (filter?.topLevel === true)
+        clauses.push('parent IS NULL');
+    if (filter?.hanging === true)
+        clauses.push('parent IS NOT NULL AND parent NOT IN (SELECT node_id FROM node_rows)');
+    if (filter?.status !== undefined) {
+        const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+        clauses.push(`status IN (${statuses.map(() => '?').join(',')})`);
+        params.push(...statuses);
+    }
+    if (filter?.withRecordedPid === true)
+        clauses.push('pi_pid IS NOT NULL');
+    if (filter?.withRecordedPidOrFrozen === true)
+        clauses.push('(pi_pid IS NOT NULL OR frozen_at IS NOT NULL)');
+    const rows = await (await openDb())
+        .prepareUncached(`SELECT * FROM node_rows WHERE ${clauses.join(' AND ')} ORDER BY created`)
+        .all(...params);
+    return rows.map(rowFrom);
+}
+// idx_nodes_terminal_placement_created (a partial index on placement presence)
+// keeps this from enumerating every terminal row on old-heavy canvases.
+export const terminalPlacementResidueSql = `SELECT
+      node_id, created, launched_at, last_settled_at, finalized_at,
+      outcome_at, last_activity_at, pane, "window", tmux_session
+    FROM nodes
+    WHERE ${NOT_A_SPARE}
+      AND status IN ('done', 'canceled', 'dead')
+      AND (pane IS NOT NULL OR "window" IS NOT NULL OR tmux_session IS NOT NULL)
+    ORDER BY created`;
+export async function listTerminalPlacementResidue() {
+    return await (await openDb()).prepare(terminalPlacementResidueSql)
+        .all();
+}
+/** The daemon's complete supervision set. Live rows participate regardless of
+ * PID; terminal rows participate only while they retain a PID or freeze mark. */
+// Materialize and deduplicate IDs first: the view must use node PK lookups,
+// never enumerate its outer historical terminal-status range. The frozen branch
+// matches the partial index idx_nodes_supervision_frozen.
+export const nodesForSupervisionSql = `WITH candidates AS MATERIALIZED (
+    SELECT node_id FROM nodes WHERE status IN ('active', 'idle')
+    UNION
+    SELECT node_id FROM nodes
+      WHERE frozen_at IS NOT NULL AND status IN ('done', 'canceled', 'dead')
+    UNION
+    SELECT node_id FROM executions
+      WHERE state != 'exited' AND state = 'running' AND pid IS NOT NULL
+  )
+  SELECT v.* FROM candidates c CROSS JOIN node_rows v
+  WHERE v.node_id = c.node_id
+    AND v.node_id NOT IN (SELECT node_id FROM warm_pool)
+    AND v.kind != 'human'
+    AND (v.status IN ('active', 'idle') OR (v.status IN ('done', 'canceled', 'dead') AND (v.pi_pid IS NOT NULL OR v.frozen_at IS NOT NULL)))
+  ORDER BY v.created`;
+export async function listNodesForSupervision() {
+    const rows = await (await openDb()).prepare(nodesForSupervisionSql)
+        .all();
+    return rows.map(rowFrom);
+}
+/** A parked resident the runtime may reopen when wake mail reaches it: `done` +
+ *  `intent='parked'`, resident, no final latch, and not being deleted. Finalized,
+ *  canceled, dead, terminal-lifecycle and deleting nodes are never reopened by mail.
+ *  The SQL form of `isParkedResident` (runtime/lifecycle.ts), which must change with it; `n` is a `nodes` row. */
+export const PARKED_RESIDENT_SQL = (n) => `(${n}.status = 'done' AND ${n}.intent = 'parked' AND ${n}.lifecycle = 'resident' AND ${n}.final_report IS NULL AND ${n}.deleting_at IS NULL)`;
+/** A node the runtime can still bring back to life, so its cwd must keep existing: a live row
+ *  (`active`/`idle`), a parked resident the lifecycle tick reopens when wake mail arrives
+ *  (`PARKED_RESIDENT_SQL`), or a terminal row with no final latch that still carries a frozen
+ *  mark, which the tick thaws (`node-lifecycle/tick.ts` `classifyRow`). `n` is a `nodes` row. */
+export const RESUMABLE_NODE_SQL = (n) => `(${n}.status IN ('active', 'idle') OR ${PARKED_RESIDENT_SQL(n)} OR (${n}.status IN ('done', 'canceled', 'dead') AND ${n}.frozen_at IS NOT NULL AND ${n}.final_report IS NULL))`;
+/** Every resumable node (`RESUMABLE_NODE_SQL`) other than `ownerId`, with the cwd it will run in. */
+export async function resumableNodeCwds(ownerId) {
+    return await (await openDb()).prepare(`SELECT node_id, cwd FROM nodes WHERE ${RESUMABLE_NODE_SQL('nodes')} AND node_id != ?`).all(ownerId);
+}
+/** Parked residents with unseen wake mail (`UNSEEN_WAKE_MAIL_SQL`), which nothing else
+ *  launches: the lifecycle tick reopens them. Each parked resident seeks its own mail
+ *  through `deliveries_destination`. */
+export async function listParkedResidentsWithWakeMail() {
+    const rows = await (await openDb()).prepare(`SELECT v.* FROM node_rows v
+    WHERE ${PARKED_RESIDENT_SQL('v')}
+      AND EXISTS (SELECT 1 FROM deliveries d WHERE d.destination_id = v.node_id AND ${UNSEEN_WAKE_MAIL_SQL('d')}) AND v.kind != 'human' AND v.node_id NOT IN (SELECT node_id FROM warm_pool)
+    ORDER BY v.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 async function registerWarmSpare(nodeId, recipeKey) {
+    await (await openDb()).prepare('INSERT INTO warm_pool (node_id, recipe_key, created) VALUES (?, ?, ?) ON CONFLICT (node_id) DO UPDATE SET recipe_key = excluded.recipe_key, created = excluded.created')
+        .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 async function unregisterWarmSpare(nodeId) {
+    return (await (await openDb()).prepare('DELETE FROM warm_pool WHERE node_id = ?').run(nodeId)).changes > 0;
+}
+async 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 node_rows n ON n.node_id = w.node_id` +
+        (recipeKey === undefined ? '' : ' WHERE w.recipe_key = ?') +
+        ' ORDER BY w.created';
+    const rows = (recipeKey === undefined ? await db.prepareUncached(sql).all() : await db.prepareUncached(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 async function listWarmSpares() {
+    return await warmSpareRowsFor(await 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 async function isWarmSpare(nodeId) {
+    const row = await (await 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 daemon's row query
+ *  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. */
+export async function claimWarmSpare(recipeKey, created, opts = {}) {
+    return await withCanvasWrite(async (db) => {
+        const row = (await warmSpareRowsFor(db, recipeKey)).find(spareIsClaimable);
+        if (row === undefined)
+            return null;
+        // Bind the key to the spare in the same transaction that takes it, so a
+        // retry after a handover finishes this spare rather than claiming a second.
+        if (opts.requestKey !== undefined) {
+            const bound = await db.prepareUncached("UPDATE create_requests SET node_id = ?, state = 'warm_claimed' WHERE request_key = ? AND node_id IS NULL").run(row.node_id, opts.requestKey);
+            if (bound.changes === 0)
+                return null;
+        }
+        const res = await db.prepare('DELETE FROM warm_pool WHERE node_id = ?').run(row.node_id);
+        if (res.changes === 0)
+            return null;
+        await db.prepare('UPDATE nodes SET created = ?, deadline_at = ? WHERE node_id = ?')
+            .run(created, opts.deadlineAt ?? null, row.node_id);
+        if (opts.outcomeDelivery !== undefined)
+            await registerOutcomeAction(db, row.node_id, opts.outcomeDelivery);
+        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 async function warmSpareCount(recipeKey) {
+    return (await warmSpareRowsFor(await 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 async function childrenOf(id) {
+    return (await (await 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`, with no per-row hydration or N+1 query. */
+export async function rosterNodes() {
+    return (await (await openDb())
+        .prepareUncached(`SELECT node_id, name, kind, mode, lifecycle, status, cwd, host_kind, parent, created, description
+         FROM node_rows 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'],
+        description: r['description'] ?? null,
+    }));
+}
+/** 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 async function listResumableRoots(cwd) {
+    const rows = await (await openDb())
+        .prepareUncached(`SELECT * FROM node_rows
+        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);
+}
+export * from './tree.js';
+/** 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, frozen_at) and either runs `body` (a write) or short-circuits
+ *  with a `'terminal'`/`'missing'` outcome — the read takes the node row
+ *  `FOR UPDATE` and holds it through `body`'s write in the same transaction, so
+ *  a concurrent finish/cancel/finalization/deletion either commits entirely
+ *  before this reads (observed here, `body` never runs) or waits on the row
+ *  until `body` commits — 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.
+ *
+ *  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 async function withFreshTerminalGuard(nodeId, isTerminal, body) {
+    return await withCanvasWrite(async (db) => {
+        const row = await db.prepare('SELECT status, final_report, frozen_at FROM nodes WHERE node_id = ? FOR UPDATE')
+            .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: await body() };
+    });
+}
+/** True when this node's identity is still required to own a managed checkout.
+ *
+ *  Ownership outlives the OPEN state. A closed record whose cleanup is still
+ *  pending names a checkout and a branch that are physically still there, and
+ *  this node record is the only proof of who they belong to — deleting it turns
+ *  a retained residual into an ownerless orphan the daemon sweep can never
+ *  safely reclaim, because it must never guess at a worktree it cannot prove it
+ *  created. So prune may take this node only once cleanup is COMPLETE. A
+ *  historical closed record written before the cleanup field existed carries no
+ *  such proof and counts as incomplete.
+ *
+ *  An abandoned record is deliberately NOT protected: abandon already removed
+ *  the checkout and retains its branch for a person on purpose, so there is no
+ *  residual for the sweep to own. */
+async function hasUnreconciledManagedWorktree(nodeId) {
+    return await hasUnreconciledWorktree(nodeId);
+}
+/** Whether a row may be removed by an automatic collection sweep. */
+export async function isCollectible(row, opts = {}) {
+    if (!['done', 'dead', 'canceled'].includes(row.status)
+        || row.pi_pid !== null
+        || row.frozen_at !== null
+        || await hasUnreconciledManagedWorktree(row.node_id)
+        || row.node_id === envNodeId()
+        // App runs (e.g. chat conversations) are deleted only through the runs API.
+        || isAppRun(row))
+        return false;
+    return opts.pastTtl === true || !['crashed', 'stranded', null].includes(row.terminal_reason ?? null);
+}
+async function nodeConversationIds(nodeIds) {
+    if (nodeIds.length === 0)
+        return [];
+    const placeholders = nodeIds.map(() => '?').join(',');
+    const rows = await (await openDb()).prepareUncached(`SELECT s.session_id, s.transcript_path, s.node_id, n.grantee FROM sessions s JOIN node_rows n ON n.node_id = s.node_id WHERE s.node_id IN (${placeholders}) AND s.session_id IS NOT NULL AND s.transcript_path IS NOT NULL ORDER BY s.created_at, s.seq`).all(...nodeIds);
+    return [...new Map(rows.map((row) => [row.session_id, { id: row.session_id, path: row.transcript_path, dir: join(appSpace(row.grantee).conversations, row.node_id) }])).values()];
+}
+/** Delete conversations nothing still needs: no sessions row names them, and no fork
+ *  that has not launched yet (a node with no sessions row) replays them as its source.
+ *  Runs after the owner's rows are gone, so the store can no longer resolve a path: each file is
+ *  removed by the path read before. */
+async function deleteNodeConversations(conversations) {
+    const db = await openDb();
+    const referenced = db.prepare('SELECT 1 FROM sessions WHERE session_id = ? LIMIT 1');
+    const pendingFork = db.prepare(`SELECT 1 FROM nodes n WHERE n.fork_source_file LIKE '%\\_' || ? || '.jsonl' ESCAPE '\\'
+    AND NOT EXISTS (SELECT 1 FROM sessions s WHERE s.node_id = n.node_id) LIMIT 1`);
+    for (const { id, path, dir } of conversations) {
+        if (await referenced.get(id) !== undefined || await pendingFork.get(id) !== undefined)
+            continue;
+        if (lstatSync(path, { throwIfNoEntry: false }) === undefined)
+            continue;
+        if (!isBeneath(dir, path)) {
+            console.error(`[canvas] not deleting transcript outside its node's conversations directory: ${path}`);
+            continue;
+        }
+        try {
+            await conversationStore().delete(id, path);
+        }
+        catch (error) {
+            if (!(error instanceof ConversationNotFoundError))
+                throw error;
+        }
+    }
+}
+/** A node chooses the transcript path it binds, so only a file beneath the deleting
+ *  node's own conversations directory (no link in the way) is ever removed. */
+function isBeneath(dir, path) {
+    try {
+        const rel = relative(realpathSync(dir), join(realpathSync(dirname(path)), basename(path)));
+        return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** Delete one node and what it owns, in the caller's transaction; false when it is already gone. */
+async function deleteNodeObject(db, nodeId) {
+    const node = await getById(db, nodeId);
+    if (node === null || node.deleted_at !== null)
+        return false;
+    await deleteNodeWithOwned(db, node);
+    return true;
+}
+export async function nodeFiles(nodeId) {
+    return { nodeId, app: await getNode(nodeId) === null ? null : await appForNode(nodeId) };
+}
+/** Remove the trees an app can write into (the node's agent folder and run
+ *  folder) without following any link inside them (R18G). Synchronous even on
+ *  the retention sweep: a plain recursive rm would follow an app-planted link. */
+async function removeNodeAppTrees({ nodeId, app }) {
+    if (app !== null)
+        removeTreeBeneath(appSpace(app).nodes, await nodeAgentDir(nodeId, app));
+    removeTreeBeneath(dirname(nodeRunDir(nodeId)), nodeRunDir(nodeId));
+}
+/** The daemon-owned directories a deleted node owned, removed whole with a plain rm. */
+function nodeOwnedDirs({ nodeId }) {
+    return [nodeDir(nodeId)];
+}
+/** A conversation another node still references keeps its file, and so its
+ *  conversations directory: remove it only when empty. */
+function removeNodeConversationDir({ nodeId, app }) {
+    if (app === null)
+        return;
+    try {
+        rmdirSync(join(appSpace(app).conversations, nodeId));
+    }
+    catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY'].includes(error.code ?? ''))
+            throw error;
+    }
+}
+/** Remove every directory a deleted node owned. A conversation another node
+ *  still references keeps its file, and so its conversations directory. */
+export async function removeNodeFiles(files) {
+    await removeNodeAppTrees(files);
+    for (const dir of nodeOwnedDirs(files))
+        rmSync(dir, { recursive: true, force: true });
+    removeNodeConversationDir(files);
+}
+/** Delete ONE node with what it owns ({@link deleteNodeWithOwned}) 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`. 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 async function deleteNode(nodeId) {
+    if (await hasUnreconciledManagedWorktree(nodeId))
+        return { deleted: false };
+    const files = await nodeFiles(nodeId);
+    const conversations = await nodeConversationIds([nodeId]);
+    const result = await withCanvasWrite(async (db) => {
+        await deleteNodeObject(db, nodeId);
+        return { deleted: true };
+    });
+    await deleteNodeConversations(conversations);
+    await removeNodeFiles(files);
+    return result;
+}
+/** Hard-delete a validated set of nodes in one row transaction, then remove
+ *  their directories. The caller must tear down engines and viewers first. */
+export async function deleteNodes(nodeIds) {
+    const ids = [...new Set(nodeIds)];
+    if (ids.length === 0)
+        return [];
+    const blocked = (await filterAsync(ids, hasUnreconciledManagedWorktree));
+    if (blocked.length > 0) {
+        throw new Error(`refusing to delete nodes with unreconciled managed worktrees: ${blocked.join(', ')}`);
+    }
+    const files = (await mapAsync(ids, nodeFiles));
+    const conversations = await nodeConversationIds(ids);
+    const placeholders = ids.map(() => '?').join(',');
+    const existing = (await (await openDb())
+        .prepareUncached(`SELECT node_id FROM nodes WHERE node_id IN (${placeholders}) ORDER BY created`)
+        .all(...ids)).map(({ node_id }) => node_id);
+    const deleted = (await filterAsync(existing, async (id) => await withCanvasWrite(async (db) => await deleteNodeObject(db, id))));
+    await deleteNodeConversations(conversations);
+    for (const id of deleted) {
+        const node = files[ids.indexOf(id)];
+        await eachNodeBestEffort(node, async () => await removeNodeFiles(node));
+    }
+    return deleted;
+}
+/** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
+ *  last activity ({@link lastActivityMs}) is older than `ttlDays`, bounding the
+ *  otherwise-unbounded growth of node rows + dirs. Only {@link isCollectible}
+ *  rows qualify, and never one `held` claims. Each node is deleted with what it
+ *  owns ({@link deleteNodeWithOwned}); 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 and that nothing will bring back: no live
+ *  `pi_pid`, not sleeping until a wake (`idle-release`), no unseen wake mail,
+ *  not frozen, not in respawn backoff, not an app run, not held, and never the CALLER
+ *  ($CRTR_NODE_ID). Without the flag, active | idle are NEVER touched.
+ *
+ *  Each node's rows change in its own transaction. 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 async function pruneNodes(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const includeStale = opts.includeStale ?? false;
+    const cutoffMs = Date.now() - opts.ttlDays * 86_400_000;
+    // `created` is a lower bound on last activity, so it is a sound SQL prefilter.
+    const cutoff = new Date(cutoffMs).toISOString();
+    const selfId = envNodeId() ?? '';
+    const db = await openDb();
+    const quiet = (row) => lastActivityMs(row) < cutoffMs;
+    const toPruned = (row) => ({ node_id: row.node_id, status: row.status, created: row.created });
+    const watchedOwners = await ownersOfWatchedDocuments();
+    const terminal = (await filterAsync((await db.prepare(`SELECT * FROM node_rows
+       WHERE status IN ('dead', 'done', 'canceled') AND created < ?
+       ORDER BY created`)
+        .all(cutoff))
+        .map(rowFrom), async (row) => await isCollectible(row, { pastTtl: true }) && quiet(row) && !watchedOwners.has(row.node_id) && !await opts.held(row.node_id)))
+        .map(toPruned);
+    const stale = !includeStale ? [] : (await filterAsync((await db.prepare(`SELECT * FROM node_rows
+       WHERE status IN ('active', 'idle') AND created < ?
+       ORDER BY created`)
+        .all(cutoff))
+        .map(rowFrom), async (row) => row.node_id !== selfId
+        && !isPidAlive(row.pi_pid ?? null)
+        && (row.frozen_at ?? null) === null
+        && (row.respawn_not_before ?? null) === null
+        && row.intent !== 'idle-release'
+        && !isAppRun(row)
+        && !await hasUnseenWakeMail(row.node_id)
+        && !await hasUnreconciledManagedWorktree(row.node_id)
+        && quiet(row)
+        && !await opts.held(row.node_id)))
+        .map(toPruned);
+    const candidates = await retainRunRootsWithMembers([...terminal, ...stale]);
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    await deletePrunedNodes(candidates, opts.removeDirs);
+    return { pruned: candidates, dryRun };
+}
+/** Nodes that own a live document some other live object still watches. Deleting such a node deletes the document under
+ *  that watcher (only a link from a live document keeps one), so the sweep leaves the node until the watcher ends. A
+ *  watcher is live when it is not a node (a profile, an app, a person) or is a node that is active or idle; a finished
+ *  node's watches end with it. */
+async function ownersOfWatchedDocuments() {
+    const rows = await (await openDb()).prepare(`SELECT DISTINCT d.owner AS owner FROM watches w
+    JOIN objects d ON d.id = w.object AND d.type = 'document' AND d.deleted_at IS NULL
+    JOIN objects o ON o.id = w.watcher AND o.deleted_at IS NULL
+    LEFT JOIN nodes n ON n.node_id = w.watcher
+    WHERE w.watcher != d.owner AND d.owner IS NOT NULL AND (n.node_id IS NULL OR n.status IN ('active', 'idle'))`)
+        .all();
+    return new Set(rows.map((r) => r.owner));
+}
+/** A run's nodes all carry the root's `run_id`, and the run observer and every
+ *  run-event append read the root's row. A sweep therefore never deletes a run
+ *  root while a node of its run survives: a member can be retained alone (its
+ *  managed worktree is unreconciled, `held` claims it, it is still live), and
+ *  deleting the root under it leaves a `run_id` that points at nothing. The
+ *  root goes on a later sweep, once its last member has. */
+async function retainRunRootsWithMembers(candidates) {
+    const db = await openDb();
+    const members = db.prepare('SELECT node_id FROM nodes WHERE run_id = ? AND node_id != ?');
+    const sweeping = new Set(candidates.map((c) => c.node_id));
+    return (await filterAsync(candidates, async (c) => (await members.all(c.node_id, c.node_id)).every((m) => sweeping.has(m.node_id))));
+}
+/** Delete a set of pruned nodes, each with what it owns in its own transaction, followed by best-effort
+ *  on-disk `nodes/<id>/` removal. Shared by TTL and count pruning so their
+ *  delete semantics never drift. `removeDirs` replaces the synchronous removal
+ *  (the daemon passes an async one so a large sweep never blocks its tick). */
+async function deletePrunedNodes(candidates, removeDirs) {
+    if (candidates.length === 0)
+        return;
+    const files = (await mapAsync(candidates, async (c) => await nodeFiles(c.node_id)));
+    const conversations = await nodeConversationIds(candidates.map((c) => c.node_id));
+    for (const c of candidates)
+        await withCanvasWrite(async (db) => await deleteNodeObject(db, c.node_id));
+    await deleteNodeConversations(conversations);
+    if (removeDirs !== undefined) {
+        for (const node of files) {
+            await eachNodeBestEffort(node, async () => {
+                await removeNodeAppTrees(node);
+                removeNodeConversationDir(node);
+            });
+        }
+        removeDirs(files.flatMap(nodeOwnedDirs));
+        return;
+    }
+    for (const node of files)
+        await eachNodeBestEffort(node, async () => await removeNodeFiles(node));
+}
+/** The rows are already gone, so one node's refused or failed removal is
+ *  logged and the batch continues: nothing finds these directories later. */
+async function eachNodeBestEffort(node, remove) {
+    try {
+        remove();
+    }
+    catch (error) {
+        emitEvent({ level: 'error', event: 'canvas.node_files.remove_failed', error, fields: { node_id: node.nodeId } });
+    }
+}
+/** A node's most recent activity (epoch ms): the latest of its lifecycle
+ *  timestamps (created, launched, settled, finalized, outcome, last run event)
+ *  and the mtime of `job/telemetry.json`, which every turn_end rewrites. 0 when
+ *  none is readable. The single clock every retention decision uses. Never throws. */
+export function lastActivityMs(row) {
+    let latest = 0;
+    for (const value of [row.created, row.launched_at, row.last_settled_at, row.finalized_at, row.outcome_at, row.last_activity_at]) {
+        if (value === null || value === undefined)
+            continue;
+        const t = Date.parse(value);
+        if (Number.isFinite(t) && t > latest)
+            latest = t;
+    }
+    try {
+        const st = statSync(join(jobDir(row.node_id), 'telemetry.json'), { throwIfNoEntry: false });
+        if (st !== undefined && st.mtimeMs > latest)
+            latest = st.mtimeMs;
+    }
+    catch {
+        /* telemetry is disposable */
+    }
+    return latest;
+}
+/** Count-based retention sweep: keep every row that is not collectible or that
+ *  `held` claims, plus the most recently active collectible rows up to
+ *  `maxNodes` in total, so the real retained floor is `max(maxNodes,
+ *  retainedCount)`. Bounds the growth the TTL sweep can't (a canvas that never
+ *  crosses the TTL still grows without limit). Recency is {@link lastActivityMs}.
+ *
+ *  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 async function pruneToLimit(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const rows = await listNodes();
+    const collectible = (await filterAsync(rows, async (row) => await isCollectible(row) && !await opts.held(row.node_id)));
+    const retainedCount = rows.length - collectible.length;
+    const keep = Math.max(0, opts.maxNodes - retainedCount);
+    const unfiltered = collectible
+        .map((row) => ({ row, recency: lastActivityMs(row) }))
+        .sort((a, b) => b.recency - a.recency)
+        .slice(keep)
+        .map(({ row }) => ({ node_id: row.node_id, status: row.status, created: row.created }));
+    const candidates = await retainRunRootsWithMembers(unfiltered);
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    await deletePrunedNodes(candidates);
+    return { pruned: candidates, dryRun };
+}