@crouton-kit/crouter 0.3.31 → 0.3.33

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

@@ -82,6 +82,13 @@ export interface PruneResult {
     pruned: PrunedNode[];
     dryRun: boolean;
 }
+/** 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). Best-effort dir removal after the row delete, mirroring pruneNodes. */
+export declare function deleteNode(nodeId: string): void;
 /** 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

package/dist/core/canvas/canvas.js

@@ -4,8 +4,8 @@
 // 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, } 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';
@@ -40,14 +40,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 +395,16 @@ 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). Best-effort dir removal after the row delete, mirroring pruneNodes. */
+export function deleteNode(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

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
@@ -250,7 +263,8 @@ 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;`);
 }
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
  *  `user_version` tracks how many have been applied. Append only. */
@@ -284,8 +298,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/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

@@ -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');
 }
@@ -73,6 +102,12 @@ export function injectedDocsPath(nodeId) {
 }
 /** Create the full directory skeleton for a node. Idempotent. */
 export function ensureNodeDirs(nodeId) {
+    // Refuse an empty nodeId: it would mint stray `nodes/context`, `nodes/job`,
+    // `nodes/reports` siblings (non-node entries the test harness's node-dir
+    // scan would miscount). A node skeleton must belong to a real node id.
+    if (!nodeId) {
+        throw new Error('ensureNodeDirs: empty nodeId — refusing to create stray node-skeleton dirs under nodes/');
+    }
     for (const d of [contextDir(nodeId), jobDir(nodeId), reportsDir(nodeId)]) {
         mkdirSync(d, { recursive: true });
     }

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

@@ -1,4 +1,9 @@
+import { type Fault } from '../runtime/fault.js';
 import type { NodeStatus, Lifecycle } from './types.js';
+export declare function activeFaultForDisplay<T extends {
+    status: NodeStatus;
+    pi_pid?: number | null;
+}>(node: T, fault: Fault | null): Fault | null;
 /**
  * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
  * The root is the first line (no connector prefix); children are indented.
@@ -59,6 +64,13 @@ export interface DashboardRow {
      *  live "is it generating?" cue. Computed on the cheap boot path 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?: 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 the one listFocuses() query. */
     viewed?: boolean;
@@ -70,6 +82,19 @@ export interface DashboardRow {
      *  session (prompts + lastAssistant). Idempotency marker for the selected row. */
     previewLoaded?: boolean;
 }
+/** Did this node's engine ever PRODUCE something — an assistant message with real
+ *  text, a tool call, or non-empty reasoning? The signal that a node did work and
+ *  is not an empty shell. A never-revived node (no session file) is trivially
+ *  false; an assistant turn that is only an empty/aborted `thinking` stub does NOT
+ *  count (that's a node started and killed before it did anything). CONSERVATIVE
+ *  by design: ANY substance keeps the node, so the reap never deletes real work
+ *  — 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;
+/** {@link isStreaming} keyed by node id alone — hydrates the broker pid off the
+ *  db row. The exported "is this node actively generating right now?" guard so a
+ *  reap never nukes a node mid-first-turn before its output lands on disk. */
+export declare function isNodeStreaming(nodeId: string): boolean;
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export declare function dashboardRows(rootId: string): DashboardRow[];
 /**

package/dist/core/canvas/render.js

@@ -20,16 +20,22 @@ import { jobDir, contextDir } from './paths.js';
 import { countAsks, asksForNodes } from './attention.js';
 import { isPidAlive } from './pid.js';
 import { listFocuses } from './focuses.js';
+import { resolveNodeVisual, faultSummary } from './status-glyph.js';
+import { readFault } from '../runtime/fault.js';
 // ---------------------------------------------------------------------------
-// Glyphs
+// Active-fault overlay: stale daemon-owned provider faults are hidden once the
+// broker pid is gone; manual/client faults stay visible until cleared.
 // ---------------------------------------------------------------------------
-const STATUS_GLYPH = {
-    active: '●',
-    idle: '○',
-    done: '✓',
-    dead: '✗',
-    canceled: '⊘',
-};
+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;
+}
+function hangingFor(node) {
+    return activeFaultForDisplay(node, readFault(node.node_id));
+}
 function readNodeTelemetry(nodeId) {
     const path = join(jobDir(nodeId), 'telemetry.json');
     if (!existsSync(path))
@@ -57,12 +63,14 @@ function nodeLine(nodeId, indent, connector) {
         // Node id is in the db but meta.json is gone — paranoid guard.
         return `${indent}${connector}? <missing meta: ${nodeId}>`;
     }
-    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const hanging = hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
     const tel = readNodeTelemetry(nodeId);
     const ctx = fmtCtx(tel.tokens_in);
     const asks = countAsks(nodeId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`;
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
 }
 /**
  * Recursively walk the subscription sub-DAG rooted at `nodeId`, appending
@@ -112,9 +120,11 @@ export function renderTree(rootId) {
     const ctx = fmtCtx(tel.tokens_in);
     const asks = countAsks(rootId);
     const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
-    const glyph = STATUS_GLYPH[node.status] ?? '?';
+    const hanging = hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
     const out = [];
-    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}`);
+    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
     // visited starts with root already rendered (walkTree doesn't re-emit root).
     const visited = new Set([rootId]);
     const children = subscriptionsOf(rootId);
@@ -261,6 +271,77 @@ function readSessionParts(sessionFile) {
     }
     return { prompts, lastAssistant };
 }
+/** Did this node's engine ever PRODUCE something — an assistant message with real
+ *  text, a tool call, or non-empty reasoning? The signal that a node did work and
+ *  is not an empty shell. A never-revived node (no session file) is trivially
+ *  false; an assistant turn that is only an empty/aborted `thinking` stub does NOT
+ *  count (that's a node started and killed before it did anything). CONSERVATIVE
+ *  by design: ANY substance keeps the node, so the reap never deletes real work
+ *  — 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 function nodeHasAssistantMessage(sessionFile) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return false;
+    let lines;
+    try {
+        if (!existsSync(sessionFile))
+            return false;
+        lines = readFileSync(sessionFile, 'utf8').split('\n');
+    }
+    catch {
+        return false;
+    }
+    for (const line of lines) {
+        if (line === '' || (line.indexOf('"role":"assistant"') === -1 && line.indexOf('"role": "assistant"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'assistant')
+            continue;
+        if (assistantContentIsSubstantive(rec.message.content))
+            return true;
+    }
+    return false;
+}
+/** True when an assistant message's content has at least one block that PRODUCED
+ *  something: non-empty text, non-empty thinking, a tool call (`toolCall`/
+ *  `tool_use`/…), or any other non-thinking/text block type. The lone non-case is
+ *  an empty thinking stub (`[{type:'thinking',thinking:''}]`) or empty content —
+ *  what an immediately-aborted first turn leaves behind. */
+function assistantContentIsSubstantive(content) {
+    if (typeof content === 'string')
+        return content.trim() !== '';
+    if (!Array.isArray(content))
+        return false;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const b = block;
+        const t = (b.type ?? '').toLowerCase();
+        if (t === 'text') {
+            if (typeof b.text === 'string' && b.text.trim() !== '')
+                return true;
+        }
+        else if (t === 'thinking') {
+            if (typeof b.thinking === 'string' && b.thinking.trim() !== '')
+                return true;
+        }
+        else
+            return true; // toolCall / tool_use / toolResult / any other block = real output
+    }
+    return false;
+}
+/** {@link isStreaming} keyed by node id alone — hydrates the broker pid off the
+ *  db row. The exported "is this node actively generating right now?" guard so a
+ *  reap never nukes a node mid-first-turn before its output lands on disk. */
+export function isNodeStreaming(nodeId) {
+    return isStreaming(nodeId, getNode(nodeId)?.pi_pid ?? null);
+}
 /** 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
@@ -354,6 +435,7 @@ export function dashboardRowsAll() {
     const focusedNodeIds = new Set(listFocuses().map((f) => f.node_id));
     return listNodes().map((row) => {
         const live = row.status === 'active' || row.status === 'idle';
+        const hanging = activeFaultForDisplay(row, readFault(row.node_id));
         return {
             node_id: row.node_id,
             name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
@@ -366,7 +448,8 @@ export function dashboardRowsAll() {
             created: row.created,
             lifecycle: row.lifecycle,
             mtimeMs: sessionMtime(row.node_id, row.created),
-            streaming: live ? isStreaming(row.node_id, row.pi_pid) : false,
+            streaming: hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+            hanging,
             viewed: focusedNodeIds.has(row.node_id),
         };
     });