@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/canvas/canvas.js

@@ -4,11 +4,12 @@
 // Source-of-truth split: a node's meta.json is canonical for its own fields;
 // the db row is a queryable index re-derivable from it. The subscribes_to edges
 // are db-authoritative (mutable, many-writers — what WAL is for).
-import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, rmSync, } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, renameSync, readdirSync, rmSync, openSync, writeSync, fsyncSync, closeSync, statSync, } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { openDb } from './db.js';
 import { isPidAlive } from './pid.js';
-import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
+import { cancelTriggersFor } from './triggers.js';
+import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, jobDir, } from './paths.js';
 // ---------------------------------------------------------------------------
 // meta.json (durable identity — the source of truth for what PERSISTS)
 //
@@ -40,14 +41,53 @@ function readMeta(nodeId) {
     // Legacy metas may still carry runtime fields on disk; toIdentity-on-read is
     // unnecessary (callers go through getNode, which overlays the row), but the
     // raw parse is typed as identity — extra props are ignored.
-    return JSON.parse(readFileSync(p, 'utf8'));
+    //
+    // Tolerate an EMPTY or unparseable meta.json by treating it as MISSING (null)
+    // rather than throwing. A bare write-temp-then-rename without fsync can leave a
+    // 0-byte meta.json on an NFS-backed home after the holding process/sandbox dies
+    // (see writeMeta + the Hearth M0 cold-boot bug); a single corrupt node must not
+    // crash rebuildIndex/revive for the whole canvas. Recovery (re-seed from a
+    // durable snapshot) is the caller's job.
+    const raw = readFileSync(p, 'utf8');
+    if (raw.trim() === '')
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
 }
-/** Serialize ONLY the identity subset → meta.json never holds runtime fields. */
+/** Serialize ONLY the identity subset → meta.json never holds runtime fields.
+ *
+ *  Durable write: fsync the temp file before the rename, then fsync the parent
+ *  directory so the rename itself is on disk. A bare writeFileSync+rename can
+ *  leave a 0-byte meta.json on an NFS-backed home (Hearth's durable Volume mounts
+ *  `local_lock=none,noac`): when meta.json is held open, the rename silly-renames
+ *  the open inode and the new content is never flushed, so a sandbox
+ *  recreate-from-template loses it. meta.json is written rarely (birth, polymorph,
+ *  session-id capture, naming) so the per-write fsync cost is negligible.
+ *  Bug: Hearth M0 cold-boot — 0-byte meta.json → rebuild-index/revive JSON.parse(''). */
 function writeMeta(meta) {
     const p = nodeMetaPath(meta.node_id);
     const tmp = `${p}.tmp`;
-    writeFileSync(tmp, JSON.stringify(toIdentity(meta), null, 2));
+    const data = JSON.stringify(toIdentity(meta), null, 2);
+    const fd = openSync(tmp, 'w');
+    try {
+        writeSync(fd, data);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
     renameSync(tmp, p);
+    const dirFd = openSync(dirname(p), 'r');
+    try {
+        fsyncSync(dirFd);
+    }
+    finally {
+        closeSync(dirFd);
+    }
 }
 // ---------------------------------------------------------------------------
 // row index — identity columns are a derived projection of meta; runtime
@@ -356,6 +396,22 @@ export function rebuildIndex() {
             recordSpawn(meta.node_id, prov);
     }
 }
+/** Hard-delete ONE node: drop its row (the edges→nodes FK, ON DELETE CASCADE,
+ *  GCs its edges) and remove its on-disk `nodes/<id>/` dir. The single-node
+ *  analogue of {@link pruneNodes}, for IMMEDIATE reaping — e.g. an empty node the
+ *  user closed or detached from. Pure persisted-state removal: the caller MUST
+ *  have already torn down the broker engine + viewer (this does not signal any
+ *  process). Reaps this node's triggers FIRST (spec §Deterministic removal,
+ *  criterion 15: target deletion kills any in-flight predicate process group and
+ *  consumes target-bound + owner-armed trigger rows, instead of leaving them to
+ *  the FK cascade alone with no kill and no notice) via the same
+ *  `cancelTriggersFor` seam `close`/`cancel` already use. Best-effort dir removal
+ *  after the row delete, mirroring pruneNodes. */
+export function deleteNode(nodeId) {
+    cancelTriggersFor(nodeId);
+    openDb().prepare('DELETE FROM nodes WHERE node_id = ?').run(nodeId);
+    rmSync(nodeDir(nodeId), { recursive: true, force: true });
+}
 /** Retention sweep: remove TERMINAL nodes (status dead | done | canceled) whose
  *  `created` is older than `ttlDays`, bounding the otherwise-unbounded growth of
  *  node rows + dirs. The edges→nodes FK (`ON DELETE CASCADE`, migration v4) GCs
@@ -409,7 +465,24 @@ export function pruneNodes(opts) {
     const candidates = [...terminal, ...stale];
     if (dryRun || candidates.length === 0)
         return { pruned: candidates, dryRun };
-    // One transactioned sweep — delete the rows; the FK cascades their edges.
+    deletePrunedNodes(candidates);
+    return { pruned: candidates, dryRun };
+}
+/** Hard-delete a set of pruned nodes: reaps each node's triggers (killing any
+ *  in-flight predicate process group and consuming target-bound + owner-armed
+ *  rows — spec criterion 15, the same reap {@link deleteNode} does) BEFORE the
+ *  transactioned row sweep (the edges→nodes FK, ON DELETE CASCADE, GCs their
+ *  edges), followed by best-effort on-disk `nodes/<id>/` dir removal. Shared by
+ *  {@link pruneNodes} (TTL) and {@link pruneToLimit} (count) so the delete
+ *  semantics never drift. The fs isn't transactional, so dirs are removed AFTER
+ *  COMMIT — by then the rows are gone, so a re-run never re-finds a
+ *  half-deleted node. */
+function deletePrunedNodes(candidates) {
+    if (candidates.length === 0)
+        return;
+    for (const c of candidates)
+        cancelTriggersFor(c.node_id);
+    const db = openDb();
     db.exec('BEGIN');
     try {
         const del = db.prepare('DELETE FROM nodes WHERE node_id = ?');
@@ -421,9 +494,66 @@ export function pruneNodes(opts) {
         db.exec('ROLLBACK');
         throw e;
     }
-    // Remove each pruned node's on-disk dir (best-effort, after COMMIT).
     for (const c of candidates) {
         rmSync(nodeDir(c.node_id), { recursive: true, force: true });
     }
+}
+/** "Most recent activity" sort key (epoch ms) read CHEAPLY: a `statSync` (no file
+ *  read, no parse) of the node's `job/telemetry.json` — rewritten on every
+ *  turn_end at a deterministic path, so it tracks last-message recency without a
+ *  meta read. Falls back to `created`'s epoch when a node never ran a turn.
+ *  Mirrors render.ts's `sessionMtime` (the same key the snapshot roster surfaces
+ *  as `last_activity`). Never throws. */
+function recencyMs(nodeId, created) {
+    try {
+        const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+        if (st !== undefined)
+            return st.mtimeMs;
+    }
+    catch {
+        /* fall through to created */
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+/** Count-based retention sweep: keep at most `maxNodes` of the MOST-RECENTLY-
+ *  ACTIVE nodes, but NEVER delete a live node — so the real retained floor is
+ *  `max(maxNodes, liveCount)`. Bounds the otherwise-unbounded growth the TTL
+ *  sweep can't (a canvas that never crosses the TTL still grows without limit).
+ *
+ *  Liveness (protected, always kept): status active|idle AND a live `pi_pid` —
+ *  the SAME signal `pruneNodes`'s `includeStale` and placement use (`isPidAlive`).
+ *  The caller ($CRTR_NODE_ID) is also always protected.
+ *
+ *  Algorithm: order ALL nodes by recency DESC (telemetry.json mtime, falling back
+ *  to `created`); `target = max(maxNodes, liveCount)`; delete every node ranked
+ *  beyond `target` (0-indexed rank >= target) that is NOT live and NOT the caller.
+ *  Retained = all live + the newest terminal nodes up to `target`.
+ *
+ *  Mirrors {@link pruneNodes} exactly for the delete (shared `deletePrunedNodes`:
+ *  transactioned row sweep + FK edge cascade + best-effort dir removal). `dryRun`
+ *  reports the candidate set and deletes NOTHING. */
+export function pruneToLimit(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const rows = listNodes();
+    // Rank ALL nodes by recency DESC, tagging liveness as we go.
+    const ranked = rows
+        .map((r) => ({
+        node_id: r.node_id,
+        status: r.status,
+        created: r.created,
+        recency: recencyMs(r.node_id, r.created),
+        live: (r.status === 'active' || r.status === 'idle') && isPidAlive(r.pi_pid),
+    }))
+        .sort((a, b) => b.recency - a.recency);
+    const liveCount = ranked.filter((r) => r.live).length;
+    const target = Math.max(opts.maxNodes, liveCount);
+    const candidates = ranked
+        .filter((r, rank) => rank >= target && !r.live && r.node_id !== selfId)
+        .map((r) => ({ node_id: r.node_id, status: r.status, created: r.created }));
+    if (dryRun || candidates.length === 0)
+        return { pruned: candidates, dryRun };
+    deletePrunedNodes(candidates);
     return { pruned: candidates, dryRun };
 }

package/dist/core/canvas/db.js

@@ -44,15 +44,27 @@ CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
 CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
 `);
 }
+/** The node row's current columns, used to make additive migrations safe to
+ *  re-run against a partially applied schema. */
+function nodeColumns(db) {
+    return new Set(db.prepare('PRAGMA table_info(nodes)').all().map((r) => r.name));
+}
+function addNodeColumnIfMissing(db, columns, name, ddl) {
+    if (columns.has(name))
+        return;
+    db.exec(ddl);
+    columns.add(name);
+}
 /** v2 — additive runtime columns the keystone (Phase 2) will make
  *  authoritative: `intent, pi_pid, window, tmux_session`. `status` already
  *  lives in the baseline row, so it is NOT re-added here. All four default to
  *  NULL, so nothing observes a behavior change until a later phase reads them. */
 function addRuntimeColumns(db) {
-    db.exec(`ALTER TABLE nodes ADD COLUMN intent       TEXT;`);
-    db.exec(`ALTER TABLE nodes ADD COLUMN pi_pid       INTEGER;`);
-    db.exec(`ALTER TABLE nodes ADD COLUMN window       TEXT;`);
-    db.exec(`ALTER TABLE nodes ADD COLUMN tmux_session TEXT;`);
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'intent', `ALTER TABLE nodes ADD COLUMN intent TEXT;`);
+    addNodeColumnIfMissing(db, columns, 'pi_pid', `ALTER TABLE nodes ADD COLUMN pi_pid INTEGER;`);
+    addNodeColumnIfMissing(db, columns, 'window', `ALTER TABLE nodes ADD COLUMN window TEXT;`);
+    addNodeColumnIfMissing(db, columns, 'tmux_session', `ALTER TABLE nodes ADD COLUMN tmux_session TEXT;`);
 }
 /** v3 — DATA backfill (keystone, Phase 2). The runtime fields
  *  (`intent, pi_pid, window, tmux_session`) become authoritative in the row;
@@ -190,7 +202,8 @@ CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
  *  Defaults NULL — nothing reads it until the placement layer lands, so this
  *  observes no behavior change. Additive, forward-only. */
 function addPaneColumn(db) {
-    db.exec(`ALTER TABLE nodes ADD COLUMN pane TEXT;`);
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'pane', `ALTER TABLE nodes ADD COLUMN pane TEXT;`);
 }
 /** v6 — the `focuses` table: durable, PLURAL on-screen viewports, one row per
  *  viewport (Q7 widens canvas.db from "topology" to "topology + focuses"). Each
@@ -219,7 +232,7 @@ CREATE TABLE IF NOT EXISTS focuses (
  *  `owner_id` is the ARMER, set on EVERY row, and is deliberately a PLAIN indexed
  *  column with NO FK (design D1/D2): an FK on `owner_id` would cascade-drop a
  *  crashed-then-pruned armer's detached cron, violating Invariant E. A detached
- *  wake is reaped only by the explicit `cancelWakesFor` DELETE, never by cascade.
+ *  wake is reaped only by the explicit `cancelTriggersFor` DELETE, never by cascade.
  *
  *  `fire_at` is an ISO 8601 UTC string for the NEXT occurrence, so the per-tick
  *  due query is a lexicographic `<=` compare. The partial unique index
@@ -243,6 +256,76 @@ CREATE INDEX IF NOT EXISTS idx_wakeups_owner ON wakeups(owner_id);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_wakeups_deadline ON wakeups(node_id) WHERE kind = 'deadline';
 `);
 }
+/** v9 — generalize the `wakeups` table (v7) into the `triggers` table (the
+ *  unified node-trigger-grammar substrate). The old `kind` axis (bare/noted/
+ *  deadline/spawn) splits into three orthogonal axes: `action` (what enacts:
+ *  'msg'|'new') x `action_mode` (how: 'inbox_message'|'fresh_revive'|
+ *  'deadline_message'|'node_birth') x `trigger_type` (when: 'at'|'every'|
+ *  'when'|'until') — so a daemon-owned predicate (`--when`) trigger can live in
+ *  the same table as a clock trigger. Predicate-only columns (`when_script`
+ *  through `last_stderr`) are additive null/idle for every migrated clock row.
+ *
+ *  Migration mapping, preserving every existing `wakeup_id` as `trigger_id`
+ *  (so an old wake's id stays cancelable): bare→fresh_revive, noted→
+ *  inbox_message, deadline→deadline_message (trigger_type='until'), spawn→
+ *  node_birth. `payload` JSON carries over unchanged — the old per-kind
+ *  payload shapes (plus SpawnChildOpts) map 1:1 onto the new payload union at
+ *  the TS layer (triggers.ts), no JSON transform needed. The `wakeups` table
+ *  is then DROPPED — not kept as a parallel table. Additive, forward-only. */
+function migrateWakeupsToTriggers(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS triggers (
+  trigger_id        TEXT PRIMARY KEY,
+  owner_id          TEXT NOT NULL,
+  node_id           TEXT,                       -- TARGET + node-anchored cancel anchor; NULL = canvas-detached
+  action            TEXT NOT NULL,               -- 'msg' | 'new'
+  action_mode       TEXT NOT NULL,               -- 'inbox_message' | 'fresh_revive' | 'deadline_message' | 'node_birth'
+  trigger_type      TEXT NOT NULL,               -- 'at' | 'every' | 'when' | 'until'
+  fire_at           TEXT,                        -- clock triggers: NEXT occurrence, ISO 8601 UTC; lexicographic <=
+  recur             TEXT,                        -- NULL = one-shot; else the recur JSON the daemon advances
+  payload           TEXT,                        -- JSON action payload, discriminated by action_mode
+  when_script       TEXT,                        -- predicate triggers: the --when bash source
+  eval_every        TEXT,                        -- predicate triggers: evaluation cadence (recur-shaped JSON)
+  next_eval_at      TEXT,                        -- predicate triggers: next evaluation instant
+  timeout_at        TEXT,                        -- predicate triggers: wall-clock expiry
+  eval_state        TEXT NOT NULL DEFAULT 'idle', -- 'idle' | 'running'
+  eval_started_at   TEXT,
+  eval_pid          INTEGER,
+  eval_lease_owner  TEXT,
+  last_eval_at      TEXT,
+  last_exit         INTEGER,
+  last_stderr       TEXT,
+  created           TEXT NOT NULL,
+  FOREIGN KEY (node_id) REFERENCES nodes(node_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_fire  ON triggers(fire_at);                  -- clock per-tick due query
+CREATE INDEX IF NOT EXISTS idx_triggers_node  ON triggers(node_id);                  -- by-node cancel / list
+CREATE INDEX IF NOT EXISTS idx_triggers_owner ON triggers(owner_id);                 -- by-owner reap
+CREATE INDEX IF NOT EXISTS idx_triggers_eval  ON triggers(eval_state, next_eval_at); -- predicate due query
+CREATE UNIQUE INDEX IF NOT EXISTS idx_triggers_deadline ON triggers(node_id) WHERE action_mode = 'deadline_message';
+
+INSERT INTO triggers (trigger_id, owner_id, node_id, action, action_mode, trigger_type, fire_at, recur, payload, created)
+SELECT
+  wakeup_id,
+  owner_id,
+  node_id,
+  CASE kind WHEN 'spawn' THEN 'new' ELSE 'msg' END,
+  CASE kind
+    WHEN 'bare' THEN 'fresh_revive'
+    WHEN 'noted' THEN 'inbox_message'
+    WHEN 'deadline' THEN 'deadline_message'
+    WHEN 'spawn' THEN 'node_birth'
+  END,
+  CASE WHEN kind = 'deadline' THEN 'until' WHEN recur IS NULL THEN 'at' ELSE 'every' END,
+  fire_at,
+  recur,
+  payload,
+  created
+FROM wakeups;
+
+DROP TABLE wakeups;
+`);
+}
 /** v8 — additive identity column `host_kind`: which HOST launches + supervises a
  *  node — `'tmux'` (a pane) or `'broker'` (the headless in-process engine). It is
  *  durable IDENTITY mirrored from meta.json like `cwd` (NOT runtime like `pane`),
@@ -250,7 +333,21 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_wakeups_deadline ON wakeups(node_id) WHERE
  *  Defaults NULL ⇒ `'tmux'` (every existing node is tmux-hosted); no data
  *  backfill. Additive, forward-only. */
 function addHostKindColumn(db) {
-    db.exec(`ALTER TABLE nodes ADD COLUMN host_kind TEXT;`);
+    const columns = nodeColumns(db);
+    addNodeColumnIfMissing(db, columns, 'host_kind', `ALTER TABLE nodes ADD COLUMN host_kind TEXT;`);
+}
+/** v10 — the `canvas_meta` key/value table: a single durable place for
+ *  small, cross-process canvas-wide scalars that aren't node rows. First user:
+ *  the boot marker (boot.ts), which records the last-seen kernel boot identity
+ *  so boot-liveness reconciliation is a single-writer SQLite transaction on
+ *  this row rather than a race-prone JSON file. Additive, forward-only. */
+function addCanvasMetaTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS canvas_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`);
 }
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
  *  `user_version` tracks how many have been applied. Append only. */
@@ -263,6 +360,8 @@ export const MIGRATIONS = [
     /* v6 */ addFocusesTable,
     /* v7 */ appendWakeupsTable,
     /* v8 */ addHostKindColumn,
+    /* v9 */ migrateWakeupsToTriggers,
+    /* v10 */ addCanvasMetaTable,
 ];
 /** Bring `db` up to the latest schema version. Reads `user_version`, runs each
  *  pending migration in order, and bumps `user_version` after each so the work
@@ -284,8 +383,21 @@ const handles = new Map();
 export function openDb() {
     const path = canvasDbPath();
     const existing = handles.get(path);
-    if (existing)
-        return existing;
+    if (existing) {
+        try {
+            existing.prepare('PRAGMA database_list').all();
+            return existing;
+        }
+        catch {
+            try {
+                existing.close();
+            }
+            catch {
+                /* ignore */
+            }
+            handles.delete(path);
+        }
+    }
     ensureHome();
     const db = new DatabaseSync(path);
     db.exec('PRAGMA journal_mode = WAL;');

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

@@ -4,6 +4,6 @@ export * from './paths.js';
 export * from './canvas.js';
 export * from './history.js';
 export * from './focuses.js';
-export * from './wakeups.js';
+export * from './triggers.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -6,6 +6,6 @@ export * from './paths.js';
 export * from './canvas.js';
 export * from './history.js';
 export * from './focuses.js';
-export * from './wakeups.js';
+export * from './triggers.js';
 export * from './telemetry.js';
 export { openDb, closeDb } from './db.js';

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

@@ -15,13 +15,11 @@ export interface NamedNode {
  *  message). Never empty. */
 export declare function fullName(node: NamedNode): string;
 /** The pi session display name — the editor label in the top-left. Format is
- *  `<kind> (<mode>) <fullName> <cycle>` where `<fullName>` is the node's handle
- *  plus the pi-generated description of its first task (see fullName) and
- *  `<cycle>` is the revive count (meta.cycles). So `developer (orchestrator)
- *  fix-auth refactor-auth-flow 2` reads as a developer orchestrator on its 2nd
- *  cycle working the auth refactor. The name segment is omitted while it
- *  collapses to the bare kind (a bare root before its first message is named).
+ *  `<fullName> <kind> (<mode>)`, where `<fullName>` is the node's handle plus
+ *  the pi-generated description of its first task (see fullName). The name
+ *  segment is omitted while it collapses to the bare kind (a bare root before
+ *  its first message is named), so the fallback is just `<kind> (<mode>)`.
  *  Recomputed from meta on every revive (and pushed live via pi.setSessionName
- *  when a bare root is named mid-session), so a base→orchestrator polymorph, a
- *  fresh cycle, or a first-message naming all update the label. */
+ *  when a bare root is named mid-session), so a base→orchestrator polymorph or
+ *  a first-message naming update the label immediately. */
 export declare function editorLabel(meta: NodeMeta): string;

package/dist/core/canvas/labels.js

@@ -19,18 +19,15 @@ export function fullName(node) {
     return combined !== '' ? combined : node.name;
 }
 /** The pi session display name — the editor label in the top-left. Format is
- *  `<kind> (<mode>) <fullName> <cycle>` where `<fullName>` is the node's handle
- *  plus the pi-generated description of its first task (see fullName) and
- *  `<cycle>` is the revive count (meta.cycles). So `developer (orchestrator)
- *  fix-auth refactor-auth-flow 2` reads as a developer orchestrator on its 2nd
- *  cycle working the auth refactor. The name segment is omitted while it
- *  collapses to the bare kind (a bare root before its first message is named).
+ *  `<fullName> <kind> (<mode>)`, where `<fullName>` is the node's handle plus
+ *  the pi-generated description of its first task (see fullName). The name
+ *  segment is omitted while it collapses to the bare kind (a bare root before
+ *  its first message is named), so the fallback is just `<kind> (<mode>)`.
  *  Recomputed from meta on every revive (and pushed live via pi.setSessionName
- *  when a bare root is named mid-session), so a base→orchestrator polymorph, a
- *  fresh cycle, or a first-message naming all update the label. */
+ *  when a bare root is named mid-session), so a base→orchestrator polymorph or
+ *  a first-message naming update the label immediately. */
 export function editorLabel(meta) {
-    const base = `${meta.kind} (${meta.mode})`;
     const full = fullName(meta);
-    const cycle = meta.cycles ?? 0;
-    return full !== '' && full !== meta.kind ? `${base} ${full} ${cycle}` : `${base} ${cycle}`;
+    const base = `${meta.kind} (${meta.mode})`;
+    return full !== '' && full !== meta.kind ? `${full} ${base}` : base;
 }

package/dist/core/canvas/nav-model.d.ts

@@ -18,8 +18,9 @@ export declare const RED = "\u001B[31m";
 export declare const YELLOW = "\u001B[33m";
 export declare const CYAN = "\u001B[36m";
 export declare const GRAY = "\u001B[90m";
-/** Status glyph colored by state: active green, idle dim, done cyan, dead red. */
-export declare function coloredGlyph(node: NodeMeta | null): string;
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. */
+export declare function nodeGlyph(node: NodeMeta | null): string;
 /** Visible width, ignoring ANSI escapes. */
 export declare function visibleWidth(s: string): number;
 /** Truncate to `max` VISIBLE columns: escape sequences are copied through
@@ -151,8 +152,8 @@ export declare function computeDefaultExpanded(root: string, self: string): Set<
 export declare function buildGraphModel(self: string, folds: FoldState, expand?: ReadonlySet<string>): FlatRow[];
 /** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
  *  (human-watched) node → a coloured background bar; SELF → bold name. The
- *  cursor outranks the attached tint when both land on the same row. Running
- *  is signaled by the dot glyph alone (● green = active engine). */
+ *  cursor outranks the attached tint when both land on the same row. The
+ *  overlay-aware glyph alone carries the live signal (status / ⟳ / ⚠). */
 export declare function renderGraphRow(r: FlatRow, isCursor: boolean, focused: ReadonlySet<string>, activeBelow: ReadonlyMap<string, number>, asks: Record<string, number>): string;
 /** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
  *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own

package/dist/core/canvas/nav-model.js

@@ -1,7 +1,7 @@
 // nav-model.ts — the pure model/render layer of the canvas graph-nav chrome.
 //
 // Extracted from src/pi-extensions/canvas-nav.ts so a SINGLE source feeds both
-// the legacy pi extension (canvas-nav) and the headless `crtr attach` viewer.
+// the legacy pi extension (canvas-nav) and the headless `crtr surface attach` viewer.
 // Everything here is pi-API-free: it reads the canvas (sqlite + meta.json + node
 // telemetry) and produces ANSI-styled strings + a flattened graph model. The
 // extension-host wiring (widgets, key taps, the ask-poll timer, run/focus
@@ -15,6 +15,11 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getNode, subscribersOf, subscriptionsOf, jobDir, listFocuses } from './index.js';
+import { isPidAlive } from './pid.js';
+import { isBusy } from '../runtime/busy.js';
+import { readFault } from '../runtime/fault.js';
+import { activeFaultForDisplay } from './render.js';
+import { resolveNodeVisual, faultSummary } from './status-glyph.js';
 // ---------------------------------------------------------------------------
 // Tuning constants
 // ---------------------------------------------------------------------------
@@ -27,9 +32,9 @@ export const VIEWPORT_FALLBACK_ROWS = 30;
 // ANSI styling. pi renders embedded escapes in widget lines and measures width
 // ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
 // (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
-// NO_COLOR; the attached-row tint is a background COLOUR, while the dot glyph
-// (●/○/✓/✗) carries the running signal independently, even where colour is
-// stripped.
+// NO_COLOR; the attached-row tint is a background COLOUR, while the overlay-
+// aware glyph (●/○/✓/✗/⟳/⚠) carries the live signal independently, even where
+// colour is stripped.
 // ---------------------------------------------------------------------------
 export const ESC = '\x1b[';
 export const RESET = `${ESC}0m`;
@@ -45,18 +50,25 @@ export const RED = `${ESC}31m`;
 export const YELLOW = `${ESC}33m`;
 export const CYAN = `${ESC}36m`;
 export const GRAY = `${ESC}90m`;
-/** Status glyph colored by state: active green, idle dim, done cyan, dead red. */
-export function coloredGlyph(node) {
+function hangingFor(node) {
+    return activeFaultForDisplay(node, readFault(node.node_id));
+}
+function streamingFor(node) {
+    if (node.status !== 'active' && node.status !== 'idle')
+        return false;
+    if (!isPidAlive(node.pi_pid))
+        return false;
+    // `isBusy` (the canonical mid-turn marker) AND-ed with the live pid above —
+    // a stale marker from a crashed pi fails the pid check, never the existsSync.
+    return isBusy(node.node_id);
+}
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. */
+export function nodeGlyph(node) {
     if (node === null)
         return '?';
-    switch (node.status) {
-        case 'active': return `${GREEN}●${RESET}`;
-        case 'idle': return `${GRAY}○${RESET}`;
-        case 'done': return `${CYAN}✓${RESET}`;
-        case 'dead': return `${RED}✗${RESET}`;
-        case 'canceled': return `${YELLOW}⊘${RESET}`;
-        default: return '?';
-    }
+    const v = resolveNodeVisual(node.status, { streaming: streamingFor(node), hanging: hangingFor(node) });
+    return `${ESC}${v.color}m${v.glyph}${RESET}`;
 }
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 /** Visible width, ignoring ANSI escapes. */
@@ -451,8 +463,8 @@ export function buildGraphModel(self, folds, expand) {
 }
 /** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
  *  (human-watched) node → a coloured background bar; SELF → bold name. The
- *  cursor outranks the attached tint when both land on the same row. Running
- *  is signaled by the dot glyph alone (● green = active engine). */
+ *  cursor outranks the attached tint when both land on the same row. The
+ *  overlay-aware glyph alone carries the live signal (status / ⟳ / ⚠). */
 export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
     const wrap = (line, attached) => isCursor ? fillBar(line, fillWidth(), REVERSE)
         : attached ? fillBar(line, fillWidth(), BG_ATTACHED)
@@ -462,7 +474,7 @@ export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
         return wrap(line, false);
     }
     const node = cNode(r.id);
-    const dot = coloredGlyph(node);
+    const dot = nodeGlyph(node);
     const rawName = navLabel(node, r.id);
     const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
     const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
@@ -473,7 +485,9 @@ export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
     const expandable = r.hasKids && r.collapsed;
     const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
     const fold = expandable ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
-    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycleBadge(node)}${childBadge(node)}${liveBelowBadge(node, activeBelow)}${fold}${askBadge(r.id, asks)}${activityCell(r.id, node)}`;
+    const fault = node !== null ? activeFaultForDisplay(node, readFault(r.id)) : null;
+    const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
+    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycleBadge(node)}${childBadge(node)}${liveBelowBadge(node, activeBelow)}${fold}${askBadge(r.id, asks)}${activityCell(r.id, node)}${faultSuffix}`;
     return wrap(line, isAttached(r.id, node, focused));
 }
 /** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at

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

@@ -1,9 +1,26 @@
 /** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
  *  Nested under the `.crouter` scope root so the whole runtime lives in one
  *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
- *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
+ *  durable user content (memory/plugins/marketplaces/config) at the scope root. */
 export declare function crtrHome(): string;
+/** Absolute path to the SQLite canvas db file. Defaults to `canvas.db` under
+ *  the canvas home, but `CRTR_CANVAS_DB` overrides ONLY this file's location
+ *  (its `-wal`/`-shm` siblings follow it) while leaving `nodesRoot()` and all
+ *  other node data under `crtrHome()`. This split exists for the Hearth guest:
+ *  node data (meta.json/sessions, plain-file writes) stays on the durable NFS
+ *  Volume via `CRTR_HOME`, but canvas.db's SQLite fcntl/WAL locks would hang on
+ *  NFS (`local_lock=none`) — so it must live on local disk. Parent dir is
+ *  created on use so an unset-default and an override both just work. */
 export declare function canvasDbPath(): string;
+/** Absolute path to a node's broker `view.sock`. Defaults to `view.sock` under
+ *  the node dir, but `CRTR_SOCK_DIR` overrides the PARENT dir (the socket becomes
+ *  `<CRTR_SOCK_DIR>/<nodeId>.sock`) while node data stays under `crtrHome()`.
+ *  Sibling of `CRTR_CANVAS_DB`, and exists for the same Hearth-guest reason: an
+ *  AF_UNIX socket cannot be bound on the durable NFS Volume (`bind()` → EACCES,
+ *  even where plain file writes into the same dir succeed), so the broker socket
+ *  must live on local disk. Unset (the default) is unchanged for normal
+ *  local-disk hosts. Parent dir is created on use so both paths just work. */
+export declare function viewSocketPath(nodeId: string): string;
 export declare function nodesRoot(): string;
 export declare function nodeDir(nodeId: string): string;
 export declare function contextDir(nodeId: string): string;

package/dist/core/canvas/paths.js

@@ -13,22 +13,51 @@
 //
 // `CRTR_HOME` overrides the root (used by tests and isolated runs).
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { mkdirSync } from 'node:fs';
 import { CRTR_DIR_NAME } from '../../types.js';
 /** Root of the global canvas home (`~/.crouter/canvas` unless `CRTR_HOME` is set).
  *  Nested under the `.crouter` scope root so the whole runtime lives in one
  *  visible top-level dir; `canvas/` keeps node-graph runtime state separate from
- *  durable user content (skills/plugins/marketplaces/config) at the scope root. */
+ *  durable user content (memory/plugins/marketplaces/config) at the scope root. */
 export function crtrHome() {
     const override = process.env['CRTR_HOME'];
     return override !== undefined && override !== ''
         ? override
         : join(homedir(), CRTR_DIR_NAME, 'canvas');
 }
+/** Absolute path to the SQLite canvas db file. Defaults to `canvas.db` under
+ *  the canvas home, but `CRTR_CANVAS_DB` overrides ONLY this file's location
+ *  (its `-wal`/`-shm` siblings follow it) while leaving `nodesRoot()` and all
+ *  other node data under `crtrHome()`. This split exists for the Hearth guest:
+ *  node data (meta.json/sessions, plain-file writes) stays on the durable NFS
+ *  Volume via `CRTR_HOME`, but canvas.db's SQLite fcntl/WAL locks would hang on
+ *  NFS (`local_lock=none`) — so it must live on local disk. Parent dir is
+ *  created on use so an unset-default and an override both just work. */
 export function canvasDbPath() {
+    const override = process.env['CRTR_CANVAS_DB'];
+    if (override !== undefined && override !== '') {
+        mkdirSync(dirname(override), { recursive: true });
+        return override;
+    }
     return join(crtrHome(), 'canvas.db');
 }
+/** Absolute path to a node's broker `view.sock`. Defaults to `view.sock` under
+ *  the node dir, but `CRTR_SOCK_DIR` overrides the PARENT dir (the socket becomes
+ *  `<CRTR_SOCK_DIR>/<nodeId>.sock`) while node data stays under `crtrHome()`.
+ *  Sibling of `CRTR_CANVAS_DB`, and exists for the same Hearth-guest reason: an
+ *  AF_UNIX socket cannot be bound on the durable NFS Volume (`bind()` → EACCES,
+ *  even where plain file writes into the same dir succeed), so the broker socket
+ *  must live on local disk. Unset (the default) is unchanged for normal
+ *  local-disk hosts. Parent dir is created on use so both paths just work. */
+export function viewSocketPath(nodeId) {
+    const override = process.env['CRTR_SOCK_DIR'];
+    if (override !== undefined && override !== '') {
+        mkdirSync(override, { recursive: true });
+        return join(override, `${nodeId}.sock`);
+    }
+    return join(nodeDir(nodeId), 'view.sock');
+}
 export function nodesRoot() {
     return join(crtrHome(), 'nodes');
 }