@north-light/crouter 0.3.312 → 0.3.313

package/dist/core/canvas/render-source.d.ts

@@ -1,12 +1,7 @@
 import type { CanvasSource } from './source.js';
 import { type NodeRecap } from './node-recap.js';
-import { type Fault } from '../runtime/fault.js';
-import type { NodeStatus, Lifecycle, NodeMeta, NodeRow, TerminalReason } from './types.js';
-export declare function activeFaultForDisplay<T extends {
-    status: NodeStatus;
-    pi_pid?: number | null;
-}>(node: T, fault: Fault | null): Fault | null;
-export declare function hangingFor(node: NodeMeta): Fault | null;
+import type { Fault } from '../runtime/fault.js';
+import type { NodeStatus, Lifecycle, NodeRow, TerminalReason } from './types.js';
 export interface NodeTelemetry {
     tokens_in?: number;
 }
@@ -79,17 +74,17 @@ export interface DashboardRow {
      *  updates as they work, so this is the last thing the node deliberately DELIVERED —
      *  usually crisper than its last assistant message. */
     report?: NodeReportPreview;
-    /** True when the node is GENUINELY mid-turn right now — its `busy` marker exists
-     *  AND its broker pid is alive (not merely an `active`, between-turns node). The
-     *  live "is it generating?" cue. Computed on the cheap boot path for LIVE nodes
-     *  only (dormant rows are always false). */
+    /** True when the node is GENUINELY mid-turn right now — the projected row's
+     *  `streaming` (its live execution has an open turn AND its broker pid is alive),
+     *  not merely an `active`, between-turns node. The live "is it generating?" cue,
+     *  carried for LIVE nodes only (dormant rows are always false). */
     streaming?: boolean;
     /** Set when the node is parked on an active fault. The otherwise-invisible
      *  "stuck, awaiting recovery" window. Mutually exclusive with `streaming`
-     *  (hanging means the turn ended, so `busy` is gone); when set,
-     *  dashboardRowsAll forces `streaming:false`. Computed on the cheap boot path
-     *  for every node, then suppressed only for stale daemon-owned provider faults
-     *  whose broker pid is gone. */
+     *  (hanging means the turn ended, so no turn is open); when set,
+     *  dashboardRowsAll forces `streaming:false`. The projected row field, already
+     *  overlaid by the owning daemon (stale daemon-owned provider faults whose
+     *  broker pid is gone are suppressed there). */
     hanging?: Fault | null;
     /** True when a viewer (focus row) is attached to the node — i.e. someone has it
      *  open on screen. Set on the cheap boot path from one listFocuses() query. The
@@ -161,23 +156,17 @@ export declare function readTranscript(sessionFile: string | null | undefined):
  *  — a tool-call-only turn (no final text) still counts. Drives reap-on-close/
  *  detach. One file read with an early exit on the first substantive turn. */
 export declare function nodeHasAssistantMessage(sessionFile: string | null | undefined): boolean;
-/** Is the node GENUINELY mid-turn right now? The `busy` marker (touched on
- *  agent_start, removed on agent_end) AND-ed with broker-pid liveness, so a stale
- *  marker from a crashed pi reads false. This is the live "generating?" signal
- *  — distinct from `status: 'active'`, which only means the engine never closed
- *  (an active node is usually dormant between turns). Read directly off disk
- *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
-export declare function isStreaming(nodeId: string, piPid: number | null | undefined): boolean;
 /** "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 canvas-home path, so it tracks last-message recency without a meta
  *  read. Falls back to `created`'s epoch when a node never ran a turn (no telemetry).
  *  Never throws. */
 export declare function sessionMtime(nodeId: string, created: string, remote?: boolean): number;
-/** Build one cheap-boot row from a raw db/source row. `remote` suppresses the
- *  LOCAL disk reads (fault/streaming/telemetry-mtime/viewers) that are meaningless
- *  for a truly remote canvas. A local row is viewed when either its tmux focus
- *  row exists or its live broker reports a terminal/web viewer. */
+/** Build one cheap-boot row from a raw db/source row. `fault`/`streaming` are
+ *  projected row fields, so they hold for a remote row too; `remote` suppresses the
+ *  LOCAL disk reads (telemetry-mtime/viewers) that are meaningless for a truly
+ *  remote canvas. A local row is viewed when either its tmux focus row exists or
+ *  its live broker reports a terminal/web viewer. */
 export declare function dashboardRowFromNodeRow(row: NodeRow, focusedNodeIds: ReadonlySet<string>, remote: boolean): DashboardRow;
 /** One row per node visible in the sub-DAG of `rootId` (including root), read
  *  entirely through the source — the openDb-free sibling of `dashboardRows`.
@@ -188,7 +177,7 @@ export declare function dashboardRowsFromSource(source: CanvasSource, rootId: st
  *  fields that need no per-node meta/session read. Local API callers may supply
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
- *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
+ *  set. Local disk telemetry is likewise suppressed remotely. */
 export declare function dashboardRowsAllFromSource(source: CanvasSource, localFocusedNodeIds?: ReadonlySet<string>, liveOnly?: boolean, snapshot?: readonly NodeRow[]): Promise<DashboardRow[]>;
 export declare function enrichRowsFromSource(_source: CanvasSource, rows: DashboardRow[], asks?: Record<string, number>): Promise<void>;
 /** goal (initial-prompt.md) and session parts are local disk reads — suppressed

package/dist/core/canvas/render-source.js

@@ -8,8 +8,8 @@
 // in a separate `render.ts` re-export shim have been retired; their few real callers
 // migrated onto these `*FromSource` variants directly.
 //
-// ALLOWED imports (verified openDb-free): node:fs/path, ./pid.js, ./labels.js,
-// ./status-glyph.js, ./node-recap.js, ../runtime/fault.js, ../frontmatter.js,
+// ALLOWED imports (verified openDb-free): node:fs/path, ./labels.js,
+// ./status-glyph.js, ./node-recap.js, ../frontmatter.js,
 // ./paths.js, ./remote-canvas-source.js, and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
 // ./focuses.js, or ./db.js here — that is the whole point of the split.
 import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
@@ -19,22 +19,8 @@ import { fullName } from './labels.js';
 import { jobDir, contextDir, reportsDir } from './paths.js';
 import { readNodeRecap } from './node-recap.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { isPidAlive, isPidPresent } from './pid.js';
 import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
-import { readFault } from '../runtime/fault.js';
 import { parseCard } from '../../shared/generated-context.js';
-// Active-fault overlay: stale daemon-owned provider faults are hidden once the
-// broker pid is gone; manual/client faults stay visible until cleared.
-export function activeFaultForDisplay(node, fault) {
-    if (fault === null)
-        return null;
-    if (fault.link === 'pi→provider' && fault.retry.by === 'daemon' && fault.retry.disposition === 'auto' && !isPidAlive(node.pi_pid))
-        return null;
-    return fault;
-}
-export function hangingFor(node) {
-    return activeFaultForDisplay(node, readFault(node.node_id));
-}
 export function readNodeTelemetry(nodeId) {
     const path = join(jobDir(nodeId), 'telemetry.json');
     if (!existsSync(path))
@@ -56,14 +42,14 @@ export function fmtCtx(tokensIn) {
 //
 // Ticket counts are threaded in as a `Record<node_id, count>` fetched ONCE per
 // render via `source.ticketCountsForView(root)` (the API/remote source's
-// attention projection) — never `countTickets()` (openDb). `ctx`/`hanging` are
-// LOCAL disk reads (telemetry.json / fault.json), valid for a same-host source
-// but meaningless for a truly remote canvas, so both are suppressed when the
-// source is a `RemoteCanvasSource`.
+// attention projection) — never `countTickets()` (openDb). The active fault is a
+// projected row field (the owning daemon already applied the stale-provider
+// overlay), so it renders for a remote node too; `ctx` is a LOCAL telemetry.json
+// read and stays suppressed when the source is a `RemoteCanvasSource`.
 function nodeLineFromSource(node, nodeId, indent, connector, remote, tickets) {
     if (node === undefined)
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
-    const hanging = remote ? null : hangingFor(node);
+    const hanging = node.fault ?? null;
     const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
     const asks = tickets[nodeId] ?? 0;
@@ -117,7 +103,7 @@ export async function renderTreeFromSource(source, rootId, snapshot, ticketSnaps
     const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
     const asks = tickets[rootId] ?? 0;
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    const hanging = remote ? null : hangingFor(node);
+    const hanging = node.fault ?? null;
     const glyph = resolveNodeVisual(node.status, { hanging, frozen: isFrozenRow(node) }).glyph;
     const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     const out = [];
@@ -467,22 +453,6 @@ function assistantContentIsSubstantive(content) {
     }
     return false;
 }
-/** Is the node GENUINELY mid-turn right now? The `busy` marker (touched on
- *  agent_start, removed on agent_end) AND-ed with broker-pid liveness, so a stale
- *  marker from a crashed pi reads false. This is the live "generating?" signal
- *  — distinct from `status: 'active'`, which only means the engine never closed
- *  (an active node is usually dormant between turns). Read directly off disk
- *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
-export function isStreaming(nodeId, piPid) {
-    if (!isPidPresent(piPid))
-        return false;
-    try {
-        return existsSync(join(jobDir(nodeId), 'busy'));
-    }
-    catch {
-        return false;
-    }
-}
 /** Concatenate the `text` blocks of one pi user message's content. Content is
  *  usually an array of `{type,text}` blocks but may be a bare string. */
 function extractUserText(content) {
@@ -530,13 +500,14 @@ function hasLiveBrokerViewer(row) {
         return false;
     }
 }
-/** Build one cheap-boot row from a raw db/source row. `remote` suppresses the
- *  LOCAL disk reads (fault/streaming/telemetry-mtime/viewers) that are meaningless
- *  for a truly remote canvas. A local row is viewed when either its tmux focus
- *  row exists or its live broker reports a terminal/web viewer. */
+/** Build one cheap-boot row from a raw db/source row. `fault`/`streaming` are
+ *  projected row fields, so they hold for a remote row too; `remote` suppresses the
+ *  LOCAL disk reads (telemetry-mtime/viewers) that are meaningless for a truly
+ *  remote canvas. A local row is viewed when either its tmux focus row exists or
+ *  its live broker reports a terminal/web viewer. */
 export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
     const live = row.status === 'active' || row.status === 'idle';
-    const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
+    const hanging = row.fault ?? null;
     return {
         node_id: row.node_id,
         name: fullName(row), // description is a row column (v38) — no meta read needed
@@ -555,7 +526,7 @@ export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
         lifecycle: row.lifecycle,
         finalized: row.final_report != null,
         mtimeMs: sessionMtime(row.node_id, row.created, remote),
-        streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+        streaming: hanging === null && live && row.streaming === true,
         hanging,
         viewed: remote ? false : focusedNodeIds.has(row.node_id) || hasLiveBrokerViewer(row),
         srcRow: row,
@@ -597,7 +568,7 @@ export async function dashboardRowsFromSource(source, rootId, snapshot, ticketSn
  *  fields that need no per-node meta/session read. Local API callers may supply
  *  the node ids from one `listFocuses()` query so `viewed` remains visible without
  *  coupling the canvas source to local viewer state. Remote sources ignore that
- *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
+ *  set. Local disk telemetry is likewise suppressed remotely. */
 export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set(), liveOnly = false, snapshot) {
     const remote = source instanceof RemoteCanvasSource;
     const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;

package/dist/core/canvas/sessions.d.ts

@@ -0,0 +1,33 @@
+export interface SessionBinding {
+    bindingId: string;
+    sessionId: string | null;
+    nodeId: string;
+    transcriptPath: string | null;
+    sourceSessionId: string | null;
+    forkEntryId: string | null;
+    createdAt: string;
+    boundAt: string;
+    unboundAt: string | null;
+}
+export declare function readLiveSession(nodeId: string): SessionBinding | null;
+export declare function findNodeBySessionFileSql(path: string): string | null;
+export declare function bindSession(nodeId: string, input: {
+    executionId: string;
+    sessionId: string | null;
+    transcriptPath: string | null;
+    sourceSessionId?: string | null;
+}): 'bound' | 'shutdown';
+export declare function resetSession(nodeId: string, input: {
+    sessionId: string;
+    transcriptPath: string | null;
+}): void;
+export declare function transferSession(input: {
+    fromNodeId: string;
+    fromBindingId: string;
+    toNodeId: string;
+    executionId: string;
+    sessionId: string | null;
+    transcriptPath: string | null;
+}): 'transferred' | 'shutdown' | 'changed';
+export declare function unbindSession(nodeId: string): void;
+export declare function setCyclePending(nodeId: string, pending: boolean): void;

package/dist/core/canvas/sessions.js

@@ -0,0 +1,78 @@
+import { randomUUID } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+import { canonicalSessionFile } from './canvas.js';
+function now() {
+    return new Date().toISOString();
+}
+function liveExecution(db, nodeId, executionId) {
+    return db.prepare("SELECT 1 FROM executions WHERE execution_id = ? AND node_id = ? AND state != 'exited'").get(executionId, nodeId) !== undefined;
+}
+function hydrate(row) {
+    return {
+        bindingId: row['binding_id'],
+        sessionId: row['session_id'] ?? null,
+        nodeId: row['node_id'],
+        transcriptPath: row['transcript_path'] ?? null,
+        sourceSessionId: row['source_session_id'] ?? null,
+        forkEntryId: row['fork_entry_id'] ?? null,
+        createdAt: row['created_at'],
+        boundAt: row['bound_at'],
+        unboundAt: row['unbound_at'] ?? null,
+    };
+}
+export function readLiveSession(nodeId) {
+    const row = openDb().prepare('SELECT * FROM sessions WHERE node_id = ? AND unbound_at IS NULL').get(nodeId);
+    return row === undefined ? null : hydrate(row);
+}
+export function findNodeBySessionFileSql(path) {
+    const row = openDb().prepare('SELECT node_id FROM sessions WHERE transcript_path = ? AND unbound_at IS NULL').get(canonicalSessionFile(path));
+    return row?.node_id ?? null;
+}
+export function bindSession(nodeId, input) {
+    return withCanvasWrite((db) => {
+        if (!liveExecution(db, nodeId, input.executionId))
+            return 'shutdown';
+        const at = now();
+        const path = input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath);
+        const current = db.prepare('SELECT binding_id, session_id FROM sessions WHERE node_id = ? AND unbound_at IS NULL').get(nodeId);
+        if (current !== undefined && current.session_id === input.sessionId) {
+            db.prepare('UPDATE sessions SET transcript_path = ?, source_session_id = ?, bound_at = ? WHERE binding_id = ?').run(path, input.sourceSessionId ?? null, at, current.binding_id);
+        }
+        else {
+            if (current !== undefined)
+                db.prepare('UPDATE sessions SET unbound_at = ? WHERE binding_id = ?').run(at, current.binding_id);
+            db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, ?, NULL, ?, ?)').run(randomUUID(), input.sessionId, nodeId, path, input.sourceSessionId ?? null, at, at);
+        }
+        db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(nodeId);
+        return 'bound';
+    });
+}
+export function resetSession(nodeId, input) {
+    withCanvasWrite((db) => {
+        const at = now();
+        db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(at, nodeId);
+        db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, NULL, NULL, ?, ?)').run(randomUUID(), input.sessionId, nodeId, input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath), at, at);
+        db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(nodeId);
+    });
+}
+export function transferSession(input) {
+    return withCanvasWrite((db) => {
+        if (!liveExecution(db, input.toNodeId, input.executionId))
+            return 'shutdown';
+        const source = db.prepare('SELECT binding_id FROM sessions WHERE node_id = ? AND binding_id = ? AND unbound_at IS NULL').get(input.fromNodeId, input.fromBindingId);
+        if (source === undefined)
+            return 'changed';
+        const at = now();
+        db.prepare('UPDATE sessions SET unbound_at = ? WHERE binding_id = ?').run(at, input.fromBindingId);
+        db.prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(at, input.toNodeId);
+        db.prepare('INSERT INTO sessions (binding_id, session_id, node_id, transcript_path, source_session_id, fork_entry_id, created_at, bound_at) VALUES (?, ?, ?, ?, NULL, NULL, ?, ?)').run(randomUUID(), input.sessionId, input.toNodeId, input.transcriptPath === null ? null : canonicalSessionFile(input.transcriptPath), at, at);
+        db.prepare('UPDATE nodes SET cycle_pending = 0 WHERE node_id = ?').run(input.toNodeId);
+        return 'transferred';
+    });
+}
+export function unbindSession(nodeId) {
+    openDb().prepare('UPDATE sessions SET unbound_at = ? WHERE node_id = ? AND unbound_at IS NULL').run(now(), nodeId);
+}
+export function setCyclePending(nodeId, pending) {
+    openDb().prepare('UPDATE nodes SET cycle_pending = ? WHERE node_id = ?').run(pending ? 1 : 0, nodeId);
+}

package/dist/core/canvas/types.d.ts

@@ -166,11 +166,8 @@ export interface ReviewBinding {
     branch_file: string;
     target_file: string;
 }
-/** A node's DURABLE IDENTITY — the subset that `meta.json` persists on disk.
- *  Written rarely (birth, polymorph, session-id capture, naming); never touched
- *  by a status flip, an intent change, a focus swap, or a pid stamp. The db row
- *  indexes the queryable identity columns; `rebuildIndex()` re-derives them from
- *  here. (Live runtime state lives in NodeRuntime, authoritative in the row.) */
+/** A node's durable configuration, stored in SQL node columns. Sessions and
+ *  managed worktrees have their own SQL stores. */
 export interface NodeIdentity {
     node_id: string;
     name: string;
@@ -197,17 +194,13 @@ export interface NodeIdentity {
     /** The dir this node is pinned to — its cwd (where pi runs, bash executes). */
     cwd: string;
     /** Which HOST launches + supervises this node: 'tmux' (a pane) or 'broker' (the
-     *  headless in-process engine). Durable IDENTITY (mirrored to the row like
-     *  `cwd`, re-derived on index rebuild), NOT live runtime like `pane`.
-     *  NULL ⇒ 'tmux' (every pre-broker node). */
+     *  headless in-process engine). NULL ⇒ 'tmux' (every pre-broker node). */
     host_kind?: 'tmux' | 'broker' | null;
     /** The profile this node runs under, a stable profile-directory id
-     *  (`<slug>-<id>`, see `core/profiles/manifest.ts`). Durable IDENTITY mirrored
-     *  to the row (like `cwd`/`host_kind`), NOT re-derived by `rebuildIndex()` —
-     *  it is chosen once at spawn (inherited from the spawner, or `--profile`) and
-     *  is the runtime→resolver seam (`CRTR_PROFILE_ID`) the memory/gate substrate
-     *  reads. NULL only for historical root/no-profile rows; new root conversations
-     *  use the stable root profile id. */
+     *  (`<slug>-<id>`, see `core/profiles/manifest.ts`). It is chosen once at spawn
+     *  (inherited from the spawner, or `--profile`) and is the runtime→resolver seam
+     *  (`CRTR_PROFILE_ID`) the memory/gate substrate reads. NULL only for historical
+     *  root/no-profile rows; new root conversations use the stable root profile id. */
     profile_id?: string | null;
     /** Role the node was born as: explore | developer | plan | review | general… */
     kind: string;
@@ -269,12 +262,10 @@ export interface NodeIdentity {
     /** Managed git worktree owned by this node (if any). */
     managed_worktree?: ManagedWorktree | null;
 }
-/** A node's LIVE RUNTIME state — authoritative in the WAL'd `nodes` row, each
- *  field mutated by exactly one atomic single-statement `UPDATE` (setStatus /
- *  setIntent / setPresence / recordPid+clearPid). NOT persisted to meta.json and
- *  NOT re-derivable by `rebuildIndex()` — it describes live process/presence
- *  state that is meaningless after the event that would lose the db; the daemon
- *  reconciles it from tmux reality, not from a stale file. */
+/** A node's live runtime state, stored in the WAL-backed `nodes` row. Each
+ *  field is mutated by an atomic single-statement `UPDATE` (setStatus / setIntent /
+ *  setPresence / recordPid+clearPid). The daemon reconciles process and presence
+ *  state from tmux and broker reality. */
 export interface NodeRuntime {
     /** What the node is doing right now. */
     status: NodeStatus;
@@ -335,26 +326,31 @@ export interface NodeRuntime {
      *  in the row exactly like `window`/`tmux_session` — a RUNTIME field, NOT meta
      *  identity — written by the one atomic `setPresence` UPDATE. */
     pane?: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
 }
-/** The hydrated node view `getNode()` returns: durable identity (from meta.json)
- *  ∪ live runtime (from the row). Keeps the historical `NodeMeta` name and field
- *  set so every `meta.X` read across the codebase typechecks unchanged — but
- *  `writeMeta` serializes only the NodeIdentity subset and the runtime fields are
- *  hydrated from the authoritative row. */
+/** The hydrated node view `getNode()` returns: durable configuration and live
+ *  runtime from SQL, with session and worktree state from their named stores.
+ *  It retains the historical `NodeMeta` name for existing callers. */
 export type NodeMeta = NodeIdentity & NodeRuntime;
-/** The queryable projection of a node stored as a canvas.db row: the indexed
- *  identity columns PLUS the authoritative runtime columns. */
+/** The queryable projection of a node's SQL configuration and runtime state. */
+/** The SQL fields corpus discovery needs to resolve a node memory store. */
+export interface NodeMemoryTarget {
+    nodeId: string;
+    cwd: string;
+    profileId: string | null;
+}
 export interface NodeRow {
     node_id: string;
     name: string;
     /** The pi-generated first-task description; see NodeIdentity.description.
-     *  Durable IDENTITY mirrored to the row (like `cwd`/`host_kind`) so a roster
-     *  read can build the full display label without opening meta.json. Absent for
-     *  a node not yet named — the column's NULL is mapped to undefined at `rowFrom`
-     *  so identity, row, and DTO all spell "unnamed" the same way. */
+     *  Absent for a node not yet named — the column's NULL is mapped to undefined
+     *  at `rowFrom` so identity, row, and DTO all spell "unnamed" the same way. */
     description?: string;
-    /** Relaunch count; see NodeIdentity.cycles. Mirrored to the row for the same
-     *  reason as `description`; absent on a row written before this column. */
+    /** Relaunch count; see NodeIdentity.cycles. Absent on a row written before
+     *  this column. */
     cycles?: number;
     kind: string;
     mode: Mode;
@@ -392,6 +388,10 @@ export interface NodeRow {
     tmux_session: string | null;
     /** The durable LOCATION handle (the tmux `%pane_id`); see NodeRuntime.pane. */
     pane: string | null;
+    /** Active fault projected from SQL recovery state; stale daemon provider faults are suppressed. */
+    fault?: import('../fault-classifier.js').Fault | null;
+    /** True only while the live execution has an open turn and its PID is alive. */
+    streaming?: boolean;
 }
 /** An edge as stored. For `subscribes_to`, `from` is the subscriber and `to`
  *  is the publisher (A subscribes_to B ⇒ A receives B's output). For

package/dist/core/canvas/types.js

@@ -1,9 +1,6 @@
 // The canvas vocabulary — the node + edge model the whole runtime hangs on.
 //
-// One global canvas (`~/.crouter/canvas/canvas.db`) holds the topology (nodes +
-// edges); each node's flesh lives on disk under `~/.crouter/canvas/nodes/<id>/`. A node's
-// `meta.json` is the source of truth for its own row; the db is a queryable
-// index over those metas, plus the authoritative store for the mutable
-// `subscribes_to` edges (which no single meta owns).
+// One global canvas (`~/.crouter/canvas/canvas.db`) holds the node graph and
+// runtime state. Each node directory holds only its artifacts.
 /** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
 export const OUTCOME_PAYLOAD_MAX_BYTES = 64 * 1024;

package/dist/core/canvas/waits.d.ts

@@ -0,0 +1,18 @@
+export interface ControllerWait {
+    waitId: string;
+    nodeId: string;
+    controllerId: string;
+    generation: number;
+    createdAt: number;
+    satisfiedAt: number | null;
+}
+/** Replace a node's live controller wait while retaining the prior row as history. */
+export declare function armControllerWait(nodeId: string, controllerId: string, now?: number): ControllerWait;
+export declare function readControllerWait(nodeId: string): ControllerWait | null;
+/** Clear only the wait that was observed for this sender; a rearm wins a race. */
+export declare function settleMatchingControllerWait(nodeId: string, senderId: string | null, now: number, db?: import("node:sqlite").DatabaseSync): boolean;
+/** Clear a matching wait only if its controller is no longer active or idle. */
+export declare function settleDeadControllerWait(nodeId: string, controllerId: string, now: number, db?: import("node:sqlite").DatabaseSync): boolean;
+/** Live rows drive controller-death reconciliation without relying on the retired node columns. */
+export declare function liveControllerWaits(): ControllerWait[];
+export declare function hasLiveControllerWait(nodeId: string): boolean;

package/dist/core/canvas/waits.js

@@ -0,0 +1,70 @@
+import { randomBytes } from 'node:crypto';
+import { openDb, withCanvasWrite } from './db.js';
+function waitFrom(row) {
+    return {
+        waitId: row.wait_id,
+        nodeId: row.node_id,
+        controllerId: row.target_id,
+        generation: row.generation,
+        createdAt: row.created_at,
+        satisfiedAt: row.satisfied_at,
+    };
+}
+function newWaitId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (id === '00000000000000000000000000000000');
+    return id;
+}
+/** Replace a node's live controller wait while retaining the prior row as history. */
+export function armControllerWait(nodeId, controllerId, now = Date.now()) {
+    return withCanvasWrite((db) => {
+        db.prepare('UPDATE waits SET satisfied_at = ? WHERE node_id = ? AND satisfied_at IS NULL').run(now, nodeId);
+        const generation = Number(db.prepare('SELECT COALESCE(MAX(generation), 0) AS generation FROM waits WHERE node_id = ?').get(nodeId).generation) + 1;
+        const wait = {
+            wait_id: newWaitId(),
+            node_id: nodeId,
+            kind: 'controller',
+            target_id: controllerId,
+            generation,
+            created_at: now,
+            satisfied_at: null,
+        };
+        db.prepare(`INSERT INTO waits (wait_id, node_id, kind, target_id, generation, created_at, satisfied_at)
+       VALUES (?, ?, 'controller', ?, ?, ?, NULL)`).run(wait.wait_id, wait.node_id, wait.target_id, wait.generation, wait.created_at);
+        return waitFrom(wait);
+    });
+}
+export function readControllerWait(nodeId) {
+    const row = openDb().prepare("SELECT * FROM waits WHERE node_id = ? AND kind = 'controller' AND satisfied_at IS NULL").get(nodeId);
+    return row === undefined ? null : waitFrom(row);
+}
+/** Clear only the wait that was observed for this sender; a rearm wins a race. */
+export function settleMatchingControllerWait(nodeId, senderId, now, db = openDb()) {
+    if (senderId === null)
+        return false;
+    const row = db.prepare("SELECT wait_id, generation FROM waits WHERE node_id = ? AND kind = 'controller' AND target_id = ? AND satisfied_at IS NULL").get(nodeId, senderId);
+    if (row === undefined)
+        return false;
+    return Number(db.prepare('UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL').run(now, row.wait_id, row.generation).changes) === 1;
+}
+/** Clear a matching wait only if its controller is no longer active or idle. */
+export function settleDeadControllerWait(nodeId, controllerId, now, db = openDb()) {
+    const row = db.prepare(`SELECT w.wait_id, w.generation, target.status AS controller_status
+       FROM waits w LEFT JOIN nodes target ON target.node_id = w.target_id
+      WHERE w.node_id = ? AND w.kind = 'controller' AND w.target_id = ? AND w.satisfied_at IS NULL`).get(nodeId, controllerId);
+    if (row === undefined || row.controller_status === 'active' || row.controller_status === 'idle')
+        return false;
+    return Number(db.prepare('UPDATE waits SET satisfied_at = ? WHERE wait_id = ? AND generation = ? AND satisfied_at IS NULL').run(now, row.wait_id, row.generation).changes) === 1;
+}
+/** Live rows drive controller-death reconciliation without relying on the retired node columns. */
+export function liveControllerWaits() {
+    return openDb().prepare("SELECT * FROM waits WHERE kind = 'controller' AND satisfied_at IS NULL").all().map(waitFrom);
+}
+export function hasLiveControllerWait(nodeId) {
+    const row = openDb().prepare(`SELECT 1 FROM waits w JOIN nodes target ON target.node_id = w.target_id
+      WHERE w.node_id = ? AND w.kind = 'controller' AND w.satisfied_at IS NULL
+        AND target.status IN ('active', 'idle') LIMIT 1`).get(nodeId);
+    return row !== undefined;
+}

package/dist/core/canvas/worktrees.d.ts

@@ -0,0 +1,40 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { ManagedWorktree, ManagedWorktreeObservation } from './types.js';
+export declare function readWorktree(nodeId: string): ManagedWorktree | null;
+export declare function openWorktree(nodeId: string, worktree: ManagedWorktree, db?: DatabaseSync): void;
+export declare function closeWorktree(nodeId: string, input: {
+    cleanup: 'pending' | 'complete';
+    closedAt: string;
+}): void;
+/** Complete a worktree close and repoint the node in the same SQL transaction.
+ * A close invalidates the active transcript because Pi remains in the old
+ * checkout; the next launch starts from the durable base checkout. */
+export declare function closeWorktreeAndRepoint(nodeId: string, input: {
+    cwd: string;
+    cleanup: 'pending' | 'complete';
+    closedAt: string;
+    unbindSession: boolean;
+}): void;
+export declare function abandonWorktree(nodeId: string, abandoned: NonNullable<ManagedWorktree['abandoned']>): void;
+export declare function abandonWorktreeAndRepoint(nodeId: string, input: {
+    cwd: string;
+    abandoned: NonNullable<ManagedWorktree['abandoned']>;
+}): void;
+export declare function recordLandIntent(nodeId: string, intent: NonNullable<ManagedWorktree['land_intent']>): void;
+export declare function recordDisposalGrant(nodeId: string, disposal: NonNullable<ManagedWorktree['disposal']>): void;
+export declare function recordSweepAttempt(nodeId: string, input: {
+    reason: string;
+    detail?: string;
+    observed: ManagedWorktreeObservation;
+    attempts: number;
+    lastAttemptAt: string;
+    nextAttemptAt: string;
+    quarantined: boolean;
+}): void;
+export declare function completeCleanup(nodeId: string): void;
+export declare function hasUnreconciledWorktree(nodeId: string): boolean;
+export declare function sweepCandidates(now: string): string[];
+export declare function quarantinedWorktrees(): Array<{
+    nodeId: string;
+    worktree: ManagedWorktree;
+}>;