@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/canvas/boot.js

@@ -0,0 +1,157 @@
+// Detects a boot change (a host reboot, or — the case this exists for — a
+// Blaxel/Firecracker microVM destroy+recreate) so callers can stop trusting any
+// `pi_pid` recorded before it.
+//
+// canvas.db is durable — it survives a VM/sandbox destroy+recreate or a host
+// reboot on whatever volume it lives on (see paths.ts / the storage-tiers
+// doc) — but `pi_pid` is a raw OS pid: once the process table resets, a small
+// stale pid can coincidentally collide with an unrelated process that now
+// happens to hold that number, so `isPidAlive` reads it "alive" when the
+// broker it once named is long gone. Left unchecked this fools BOTH the
+// daemon's own liveness poll (crtrd.ts) and reviveNode's double-launch guard
+// (revive.ts) into believing a dead broker is still running — the node then
+// stays permanently unrevivable until a human runs `canvas revive --fresh`.
+//
+// The signal (primary): the Linux kernel's per-boot identity at
+// `/proc/sys/kernel/random/boot_id` — a fresh random UUID minted on every
+// kernel boot. A Firecracker microVM recreate (Blaxel's deployment shape) boots
+// a brand-new kernel, so `boot_id` changes; a plain daemon restart within the
+// same boot leaves it identical. This is an EXACT identity, so on Linux we need
+// no wall-clock window at all. NOTE this detects a *kernel boot*, not an
+// arbitrary container recreate: an ordinary container that shares the host
+// kernel keeps the host's `boot_id` across recreation, so this would NOT fire
+// there — that shape is out of scope (Hearth runs on Firecracker microVMs).
+//
+// The signal (fallback, non-Linux dev only): `os.uptime()` resets to ~0 on a
+// reboot and is otherwise monotonic, so `now - uptime` estimates the current
+// boot's wall-clock start (the "boot epoch"). Used only when `boot_id` is
+// unavailable (e.g. macOS dev), where a genuine reboot/recreate is not a
+// production concern; the epoch comparison keeps a generous tolerance there.
+//
+// The last-seen identity is persisted in canvas.db (the same durable tier the
+// pids live in) as a single `canvas_meta` row, and the compare+sweep runs in
+// ONE `BEGIN IMMEDIATE` transaction so concurrent callers (daemon startup and a
+// manual/direct revive in another process) are serialized: a second caller
+// blocks on the write lock, then reads the marker the first already updated and
+// no-ops, so it can never clear a pid the first just recorded (single-writer).
+import { readFileSync } from 'node:fs';
+import { uptime } from 'node:os';
+import { openDb } from './db.js';
+/** Wall-clock epoch drift (fallback signal only) beyond which two boot-start
+ *  estimates are called DIFFERENT boots. Absorbs clock-sync jitter (NTP, a VM's
+ *  first sync after boot) and `os.uptime()`'s ~1s resolution. Only consulted
+ *  when the exact kernel `boot_id` is unavailable on BOTH sides (non-Linux
+ *  dev). A false positive would clear a genuinely live pid and let reviveNode
+ *  double-spawn onto the same session; a false negative just falls back to the
+ *  manual `--fresh` status quo — so it is kept generous, biased against the
+ *  dangerous direction. The production target (Linux/Firecracker) never reaches
+ *  this branch; there `boot_id` is exact. */
+const BOOT_EPOCH_TOLERANCE_MS = 60_000;
+function readKernelBootId() {
+    try {
+        const id = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+        return id.length > 0 ? id : null;
+    }
+    catch {
+        return null; // non-Linux, or unreadable — fall back to the wall-clock epoch
+    }
+}
+/** Identity of the CURRENT OS boot. `now` is injectable for tests. */
+export function currentBootIdentity(now = Date.now()) {
+    return { bootId: readKernelBootId(), bootEpochMs: now - Math.round(uptime() * 1000) };
+}
+/** Pure decision core: does `current` belong to a DIFFERENT boot than the
+ *  persisted `known`? `known === null` (no history — a fresh install, or the
+ *  first run of a build that added this marker) is never a boot change: there
+ *  is nothing to contradict it, and treating "no history" as a change could
+ *  clear genuinely live pids that predate this feature.
+ *
+ *  When BOTH sides carry a kernel `boot_id`, that exact identity decides it — no
+ *  wall-clock window, so a real quick reboot/recreate (a short-lived prior boot
+ *  whose start is <60s away) is still detected. Only when a `boot_id` is missing
+ *  on either side (non-Linux dev) does it fall back to the epoch-drift window.
+ *  Unit-testable without real uptime/fs. */
+export function bootChanged(current, known) {
+    if (known === null)
+        return false;
+    if (current.bootId !== null && known.bootId !== null) {
+        return current.bootId !== known.bootId;
+    }
+    return Math.abs(current.bootEpochMs - known.bootEpochMs) > BOOT_EPOCH_TOLERANCE_MS;
+}
+const BOOT_MARKER_KEY = 'boot_identity';
+function readBootMarker(db) {
+    const row = db
+        .prepare('SELECT value FROM canvas_meta WHERE key = ?')
+        .get(BOOT_MARKER_KEY);
+    if (row === undefined)
+        return null;
+    try {
+        const parsed = JSON.parse(row.value);
+        if (typeof parsed.bootEpochMs !== 'number')
+            return null;
+        return {
+            bootId: typeof parsed.bootId === 'string' ? parsed.bootId : null,
+            bootEpochMs: parsed.bootEpochMs,
+        };
+    }
+    catch {
+        return null; // malformed — treat as "no history yet"
+    }
+}
+function writeBootMarker(db, identity) {
+    db.prepare('INSERT INTO canvas_meta (key, value) VALUES (?, ?) ' +
+        'ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(BOOT_MARKER_KEY, JSON.stringify(identity));
+}
+/** Idempotent and safe to call from every revive entry point (daemon startup,
+ *  reviveNode): compares the current boot's identity against the last one
+ *  recorded, and if they differ, clears `pi_pid` on every node that has one —
+ *  regardless of status, since reviveNode's double-launch guard reads `pi_pid`
+ *  unconditionally, not just on active/idle rows. The first caller after a
+ *  genuine boot change does the sweep and persists the new marker; every call
+ *  after that (in this process or another) reads a matching marker and no-ops.
+ *
+ *  SINGLE-WRITER: the whole read-marker + sweep + write-marker runs in one
+ *  `BEGIN IMMEDIATE` transaction. A concurrent caller (a manual revive racing
+ *  daemon startup, in a separate process) blocks on the SQLite write lock until
+ *  this commits, then reads the already-updated marker and no-ops — so it can
+ *  never `clearPid` a broker pid the first caller's revive just recorded, which
+ *  would otherwise hide a live broker behind `pi_pid=NULL` and risk a second
+ *  broker on the same session.
+ *
+ *  `current` defaults to the real identity; tests inject a synthetic one against
+ *  an isolated CRTR_HOME to simulate a boot change without a real reboot. */
+export function reconcileBootLiveness(current = currentBootIdentity()) {
+    const db = openDb();
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const known = readBootMarker(db);
+        if (!bootChanged(current, known)) {
+            if (known === null)
+                writeBootMarker(db, current); // seed first-ever marker
+            db.exec('COMMIT');
+            return { changed: false, cleared: [] };
+        }
+        const rows = db
+            .prepare('SELECT node_id FROM nodes WHERE pi_pid IS NOT NULL')
+            .all();
+        const upd = db.prepare('UPDATE nodes SET pi_pid = NULL WHERE node_id = ?');
+        const cleared = [];
+        for (const row of rows) {
+            upd.run(row.node_id);
+            cleared.push(row.node_id);
+        }
+        writeBootMarker(db, current);
+        db.exec('COMMIT');
+        return { changed: true, cleared };
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch {
+            /* best-effort — nothing was committed */
+        }
+        throw err;
+    }
+}

package/dist/core/canvas/browse/__tests__/model.test.js

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { buildTree, flatten, fuzzyMatch, tabPredicate, TABS, attentionTier, attentionMtime } from '../model.js';
+import { buildTree, flatten, fuzzyMatch, pruneNode, tabPredicate, TABS, attentionTier, attentionMtime } from '../model.js';
 // ── Fixture canvas ───────────────────────────────────────────────────────────
 //   root1 (active)            ← rank 0
 //     child-a (idle)
@@ -73,6 +73,40 @@ test('buildTree: unknown child ids are dropped (missing meta safe)', () => {
     assert.deepEqual(t.nodes.get('root1').childIds, ['child-a']);
     assert.equal(t.nodes.has('ghost'), false);
 });
+// ── pruneNode ────────────────────────────────────────────────────────────────
+// Regression: pressing `x` in canvas browse on an EMPTY active node looked like a
+// no-op — closeNode hard-deletes (reaps) an empty node, but doClose never removed
+// it from the in-memory tree, so the stale active row kept painting. pruneNode is
+// the splice doClose now applies for a reaped (getNode===null) close.
+test('pruneNode: reaping a leaf removes it from its parent and the node map', () => {
+    const t = tree();
+    pruneNode(t, 'grand-x'); // leaf under child-a
+    assert.equal(t.nodes.has('grand-x'), false);
+    assert.deepEqual(t.nodes.get('child-a').childIds, []);
+});
+test('pruneNode: reaping a mid-tree node re-homes its children to its parent', () => {
+    const t = tree();
+    pruneNode(t, 'child-a'); // child-a (under root1) owns grand-x
+    assert.equal(t.nodes.has('child-a'), false);
+    // grand-x lifts into child-a's slot in root1's child order (before child-b).
+    assert.deepEqual(t.nodes.get('root1').childIds, ['grand-x', 'child-b']);
+    assert.equal(t.nodes.get('grand-x').parentId, 'root1');
+});
+test('pruneNode: reaping a root lifts its children into the root list', () => {
+    const t = tree();
+    const rootIdx = t.roots.indexOf('root2');
+    pruneNode(t, 'root2'); // root2 owns child-c
+    assert.equal(t.nodes.has('root2'), false);
+    assert.equal(t.roots.includes('root2'), false);
+    assert.equal(t.roots[rootIdx], 'child-c'); // child-c took root2's slot
+    assert.equal(t.nodes.get('child-c').parentId, null);
+});
+test('pruneNode: absent id is a no-op', () => {
+    const t = tree();
+    const before = t.nodes.size;
+    pruneNode(t, 'ghost');
+    assert.equal(t.nodes.size, before);
+});
 // ── tab predicates ───────────────────────────────────────────────────────────
 test('tabPredicate: All / Live / Dormant / Flagged', () => {
     assert.deepEqual([...TABS], ['All', 'Live', 'Dormant', 'Flagged']);

package/dist/core/canvas/browse/app.js

@@ -6,14 +6,14 @@
 //
 // Resume is one action: Enter routes the chosen node through `crtr node focus`,
 // which goes via reviveNode() — the ONLY sanctioned open. NEVER spawn
-// `pi --session` directly (see canvas-resume.ts header for the desync hazard).
+// `pi --session` directly (see reviveNode() in revive.ts for the desync hazard).
 import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAll, enrichRows, loadPreview, renderForest } from '../render.js';
 import { listNodes, subscriptionsOf, getNode } from '../canvas.js';
 import { closeNode } from '../../runtime/close.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
-import { buildTree, flatten, TABS } from './model.js';
+import { buildTree, flatten, pruneNode, TABS } from './model.js';
 // Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
 // press restores the structural `tree` view, then relevance/recency, then back.
 const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
@@ -34,7 +34,7 @@ export async function runBrowse(opts = {}) {
     }
     // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
     // session, so `node focus` refuses them; they are never a navigation/resume
-    // target (mirrors canvas-resume.ts / the node focus guard).
+    // target (mirrors the node focus guard).
     const rows = dashboardRowsAll().filter((r) => r.kind !== 'human');
     const rootIds = listNodes()
         .filter((n) => n.parent === null && n.kind !== 'human')
@@ -80,6 +80,17 @@ export async function runBrowse(opts = {}) {
     // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
     // never strand the tty in raw + alt-screen + hidden-cursor.
     process.once('exit', cleanup);
+    /** On-demand kick of a hanging node: shell `canvas revive <id> --now` (which
+     *  SIGTERMs the live broker — the daemon resumes it). Synchronous + quiet
+     *  (stdio ignored) so it never takes over the TUI; best-effort. */
+    const reviveNow = (id) => {
+        try {
+            execFileSync('crtr', ['canvas', 'revive', id, '--now'], { stdio: 'ignore' });
+        }
+        catch {
+            /* best-effort — the SIGTERM is what matters; the daemon owns the resume */
+        }
+    };
     /** Open the chosen node — the ONLY sanctioned path (reviveNode via node focus). */
     const selectAndFocus = (id) => {
         cleanup();
@@ -188,16 +199,26 @@ export async function runBrowse(opts = {}) {
             return; // unknown/already-gone node — nothing to reflect
         }
         for (const cid of closed) {
+            const m = getNode(cid);
+            if (m === null) {
+                // Reaped, not parked: an EMPTY node (0k ctx, no assistant message) is
+                // hard-deleted by closeNode (row + dir gone). Splice it out of the tree so
+                // its row disappears — otherwise the stale active husk lingers on screen and
+                // `x` looks like a no-op (the row was the only thing that ever changed).
+                pruneNode(tree, cid);
+                continue;
+            }
             const n = tree.nodes.get(cid);
             if (n === undefined)
                 continue;
-            const m = getNode(cid);
-            if (m !== null)
-                n.row.status = m.status; // real post-close status (done / canceled)
+            n.row.status = m.status; // real post-close status (done / canceled)
             n.row.streaming = false;
             n.row.viewed = false;
         }
-        recompute(id);
+        // Keep the cursor at the same INDEX (the row that shifts up into the closed
+        // slot), not pinned to the now-gone node — recompute() leaves state.cursor
+        // put and clamps it to the new bounds.
+        recompute();
     };
     const cycleTab = (dir) => {
         const i = TABS.indexOf(state.tab);
@@ -228,10 +249,29 @@ export async function runBrowse(opts = {}) {
         state.residentsOnly = !state.residentsOnly;
         recompute(keep);
     };
+    // Coalesced search repaint. The expensive work per keystroke is recompute()
+    // (a fuzzyMatch flatten over the whole corpus) + a full renderFrame. Doing it
+    // synchronously on every key blocks the event loop, so fast typing batches into
+    // the stdin reads — and batched chunks used to be dropped (see onKeySearch).
+    // Instead, each key only mutates state.query (cheap) and marks the view dirty;
+    // a single setImmediate drains AFTER every queued stdin 'data' callback (poll
+    // phase) has appended its chars, so N rapid keys collapse to ONE recompute+paint
+    // and no keystroke is ignored. The sort may still take a moment — that's fine.
+    let searchRepaintScheduled = false;
+    const scheduleSearchRepaint = () => {
+        if (searchRepaintScheduled)
+            return;
+        searchRepaintScheduled = true;
+        setImmediate(() => {
+            searchRepaintScheduled = false;
+            recompute();
+            flush();
+        });
+    };
     const onKeySearch = (input, key) => {
         if (key.escape) {
             // Cancel the search: drop the query AND the relevance ranking it switched
-            // on, returning to the tree.
+            // on, returning to the tree. Synchronous: we're leaving search mode.
             state.search = false;
             state.query = '';
             state.sort = 'tree';
@@ -240,19 +280,20 @@ export async function runBrowse(opts = {}) {
             return;
         }
         if (key.return) {
-            // Commit: keep the filter, drop search mode, land on the first match.
+            // Commit: keep the filter, drop search mode, land on the first match. Must
+            // recompute synchronously first so the match index reflects the final query
+            // even if a coalesced repaint is still pending.
             state.search = false;
+            recompute();
             const firstMatch = visible.findIndex((v) => v.matched);
             if (firstMatch >= 0)
                 state.cursor = firstMatch;
-            recompute();
             flush();
             return;
         }
         if (key.backspace) {
             state.query = state.query.slice(0, -1);
-            recompute();
-            flush();
+            scheduleSearchRepaint();
             return;
         }
         // Any ctrl-combo: Ctrl+C quits; everything else is swallowed (never typed).
@@ -261,11 +302,15 @@ export async function runBrowse(opts = {}) {
                 quit();
             return;
         }
-        // Printable single char → append. Ignore multi-byte / control chunks.
-        if (input.length === 1 && input >= ' ') {
-            state.query += input;
-            recompute();
-            flush();
+        // Append every printable char in the chunk. Fast typing batches multiple
+        // chars into one stdin read, so we must take them all (not just a length-1
+        // chunk) or keystrokes get dropped. Filtering to >= ' ' strips control/escape
+        // bytes (e.g. stray \x1b from an unrecognised sequence) but keeps real input,
+        // including multi-byte UTF-8 code points.
+        const printable = [...input].filter((c) => c >= ' ').join('');
+        if (printable.length > 0) {
+            state.query += printable;
+            scheduleSearchRepaint();
         }
     };
     const onKeyNav = (input, key) => {
@@ -424,6 +469,20 @@ export async function runBrowse(opts = {}) {
             flush();
             return;
         }
+        // Revive now (on-demand kick): for a HANGING node, SIGTERM the live broker so
+        // the daemon's crash→grace→resume path brings it back in ~20s instead of
+        // waiting out the 5-min auto-revive grace. Shells `canvas revive <id> --now`
+        // (browse goes through commands, never touching the runtime directly). 'k' is
+        // vim-up here, so the kick is on SHIFT-K.
+        if (input === 'K') {
+            if (row !== undefined) {
+                const r = rowOf(row.id);
+                if (r?.hanging != null)
+                    reviveNow(row.id);
+            }
+            flush();
+            return;
+        }
         // Resume.
         if (key.return) {
             if (row !== undefined)
@@ -445,6 +504,17 @@ export async function runBrowse(opts = {}) {
         state.cwdScope = null;
         recompute();
     }
+    // Open with the cursor on the CURRENT node (the one browse was launched from),
+    // not the top of the tree. Expand its ancestors so the row is actually visible,
+    // then home the cursor onto it. No-op when launched outside a node, or when the
+    // node is filtered out of the current tab/scope.
+    const selfId = process.env['CRTR_NODE_ID'];
+    if (selfId !== undefined && selfId !== '' && tree.nodes.has(selfId)) {
+        for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
+            state.collapsed.delete(p);
+        }
+        recompute(selfId);
+    }
     setupTerminal();
     flush();
     // Background corpus warmer: after the instant first paint, progressively enrich

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

@@ -28,7 +28,7 @@ export interface Tree {
     nodes: Map<string, TreeNode>;
 }
 /** Sort rank for roots/stragglers — live first (active, then idle), dormant
- *  after. Mirrors render.ts / canvas-resume.ts statusRank. */
+ *  after. Mirrors render.ts statusRank. */
 export declare function statusRank(status: NodeStatus): number;
 /**
  * Build a spanning tree of the whole canvas.
@@ -43,6 +43,15 @@ export declare function statusRank(status: NodeStatus): number;
  * appended as a depth-0 straggler so "All" is genuinely the whole canvas.
  */
 export declare function buildTree(rows: DashboardRow[], rootIds: string[], childIdsOf: (id: string) => string[]): Tree;
+/** Splice a node out of an already-built tree in place (mutates `tree`). Used when
+ *  a close REAPED an empty node (row + dir hard-deleted) rather than parking it:
+ *  the node is gone from the db, so it must vanish from the in-memory tree too or
+ *  its stale row lingers on screen (the "press x, nothing happens" bug — an empty
+ *  active husk reaped by closeNode but never dropped from `tree.nodes`, so the
+ *  attention/flat view kept painting it). Surviving children are re-homed to the
+ *  reaped node's parent so a non-leaf reap never orphans them out of view. No-op
+ *  if the id is absent. */
+export declare function pruneNode(tree: Tree, id: string): void;
 /** Case-insensitive subsequence match: every char of `query` appears in `text`
  *  in order (gaps allowed). Empty query matches everything. Substrings are a
  *  subsequence, so this subsumes substring matching too. */

package/dist/core/canvas/browse/model.js

@@ -20,7 +20,7 @@ export function tabPredicate(tab, row) {
     }
 }
 /** Sort rank for roots/stragglers — live first (active, then idle), dormant
- *  after. Mirrors render.ts / canvas-resume.ts statusRank. */
+ *  after. Mirrors render.ts statusRank. */
 export function statusRank(status) {
     switch (status) {
         case 'active': return 0;
@@ -85,6 +85,42 @@ export function buildTree(rows, rootIds, childIdsOf) {
     }
     return { roots: orderedRoots, nodes };
 }
+/** Splice a node out of an already-built tree in place (mutates `tree`). Used when
+ *  a close REAPED an empty node (row + dir hard-deleted) rather than parking it:
+ *  the node is gone from the db, so it must vanish from the in-memory tree too or
+ *  its stale row lingers on screen (the "press x, nothing happens" bug — an empty
+ *  active husk reaped by closeNode but never dropped from `tree.nodes`, so the
+ *  attention/flat view kept painting it). Surviving children are re-homed to the
+ *  reaped node's parent so a non-leaf reap never orphans them out of view. No-op
+ *  if the id is absent. */
+export function pruneNode(tree, id) {
+    const node = tree.nodes.get(id);
+    if (node === undefined)
+        return;
+    const parentId = node.parentId;
+    // Children still present (their own reap, if any, already removed them) lift up
+    // to this node's parent, taking its slot in the child order.
+    const survivingKids = node.childIds.filter((c) => tree.nodes.has(c));
+    for (const c of survivingKids) {
+        const kid = tree.nodes.get(c);
+        if (kid !== undefined)
+            kid.parentId = parentId;
+    }
+    if (parentId !== null) {
+        const p = tree.nodes.get(parentId);
+        if (p !== undefined) {
+            const i = p.childIds.indexOf(id);
+            if (i >= 0)
+                p.childIds.splice(i, 1, ...survivingKids);
+        }
+    }
+    else {
+        const i = tree.roots.indexOf(id);
+        if (i >= 0)
+            tree.roots.splice(i, 1, ...survivingKids);
+    }
+    tree.nodes.delete(id);
+}
 // ---------------------------------------------------------------------------
 // Fuzzy match
 // ---------------------------------------------------------------------------

package/dist/core/canvas/browse/render.js

@@ -11,6 +11,7 @@
 // Every hue (fg / bg color) is gated on `caps.color`; structural SGR (bold/dim/
 // reverse) is allowed always. See detectColorCaps() for the gate, and the
 // canvas-browse color spec for the rationale + palette.
+import { STATUS_GLYPH, STATUS_COLOR, resolveNodeVisual, faultSummary } from '../status-glyph.js';
 import { TABS, matchIndices, promptText, previewSnippet } from './model.js';
 // Span/color primitives live in core/tui/draw.ts (one copy, shared with the
 // `crtr view` host). Re-export the color caps so browse's importers + tests keep
@@ -50,30 +51,17 @@ const DIM = `${ESC}2m`;
 const BOLD = `${ESC}1m`;
 const CURSOR_BG = `${ESC}48;5;236m`; // subtle dark-gray cursor-row bg (256-color)
 // Basic-16 ANSI fg codes used by the palette.
-const FG_GREEN = '32';
 const FG_YELLOW = '33';
 const FG_RED = '31';
 const FG_CYAN = '36';
 const FG_GRAY = '90'; // bright-black
 const FG_BRIGHT_YELLOW = '93';
-const FG_BRIGHT_GREEN = '92'; // streaming pulse (brighter than the active-status green)
 const FG_BRIGHT_CYAN = '96'; // query-match highlight (ties to the cyan search accent)
-const STATUS_GLYPH = {
-    active: '●',
-    idle: '○',
-    done: '✓',
-    dead: '✗',
-    canceled: '⊘',
-};
-/** The load-bearing color: glyph hue per status. Single source of truth, mirrors
- *  STATUS_GLYPH. Reinforces the glyph everywhere it appears (rows + summary). */
-const STATUS_COLOR = {
-    active: FG_GREEN,
-    idle: FG_YELLOW,
-    done: FG_CYAN,
-    dead: FG_RED,
-    canceled: FG_GRAY,
-};
+// STATUS_GLYPH + STATUS_COLOR are imported from ../status-glyph.js (the shared
+// canvas-graph map). STATUS_COLOR there is NUMERIC SGR (e.g. 32) — wrap with
+// `sgr()` where a string ANSI code is needed (Span fg / template literals accept
+// the number directly).
+const FG = (code) => String(code);
 function fmtCtx(tokens) {
     if (tokens <= 0)
         return '0k';
@@ -194,16 +182,17 @@ function spansWidth(spans) {
  *  node is genuinely mid-turn; otherwise the lifecycle word. The word is what makes
  *  state legible at a glance and survives NO_COLOR (the glyph is the second cue). */
 function statusRail(r) {
-    const streaming = r.streaming === true;
-    const word = streaming
-        ? 'live'
-        : ({ active: 'active', idle: 'idle', done: 'done', dead: 'dead', canceled: 'cancel' }[r.status] ?? r.status);
-    const fg = streaming ? FG_BRIGHT_GREEN : STATUS_COLOR[r.status];
-    const glyph = streaming ? '⟳' : (STATUS_GLYPH[r.status] ?? '?');
-    const text = `${glyph} ${word}`;
+    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
+    // Plain status keeps browse's own status WORD; overlays (hanging/⟳)
+    // carry their own word from resolveNodeVisual. A hanging kind label can exceed
+    // STATUS_W — acceptable: the rare, attention-demanding row gets a slightly
+    // wider rail (Math.max(1,…) keeps a gap), which draws the eye.
+    const word = v.word ?? ({ active: 'active', idle: 'idle', done: 'done', dead: 'dead', canceled: 'cancel' }[r.status] ?? r.status);
+    const fg = FG(v.color);
+    const text = `${v.glyph} ${word}`;
     const pad = Math.max(1, STATUS_W - [...text].length);
     return [
-        { text, style: { fg, bold: streaming } },
+        { text, style: { fg, bold: v.bold === true } },
         { text: ' '.repeat(pad) },
     ];
 }
@@ -256,11 +245,15 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     const gutter = r.viewed === true
         ? { text: '◉ ', style: { fg: FG_BRIGHT_CYAN, bold: true } }
         : { text: '  ' };
-    // Inline attention flag that travels with the name (streaming lives in the rail,
+    // Inline attention flag that travels with the name (fault summary lives in the rail,
     // attached lives in the gutter).
     const flags = [];
     if (r.asks > 0)
         flags.push({ text: ` ⚑${r.asks}`, style: { fg: FG_BRIGHT_YELLOW, bold: true } }); // pending asks
+    // Hanging: the fault summary travels with the name (the ⚠ + kind
+    // label live in the rail). Dim yellow so it reads as secondary detail.
+    if (r.hanging != null)
+        flags.push({ text: ` · ${faultSummary(r.hanging, now)}`, style: { fg: FG_YELLOW, dim: true } });
     const status = statusRail(r);
     const right = metaCluster(r, now, showCwd);
     const treeLead = `${indent}${collapse} `;
@@ -348,7 +341,7 @@ function snippetLine(ln, width, caps) {
     return assemble(spans, width, caps.color, '', false);
 }
 /** The bottom preview panel — exactly PREVIEW_HEIGHT lines: a separator, a meta
- *  line (status · kind/mode · project · age · ctx · asks · streaming/viewing), then
+ *  line (status · kind/mode · project · age · ctx · asks · fault/viewing), then
  *  TWO blocks — the spawn prompt / query-match (PROMPT_LINES) and the node's LAST
  *  assistant reply (REPLY_LINES, prefixed `↩`). Under a live query the prompt block
  *  is WINDOWED to the matching prompt (anywhere in the conversation) with the match
@@ -362,14 +355,17 @@ function previewPanel(r, width, caps, now, query) {
             out.push('');
         return out;
     }
+    const v = resolveNodeVisual(r.status, { streaming: r.streaming === true, hanging: r.hanging ?? null });
     const glyph = caps.color
-        ? `${ESC}${STATUS_COLOR[r.status]}m${STATUS_GLYPH[r.status]}${RESET}`
-        : (STATUS_GLYPH[r.status] ?? '?');
+        ? `${ESC}${v.color}m${v.glyph}${RESET}`
+        : v.glyph;
     const metaPieces = [`${r.status} ${r.kind}/${r.mode}`, baseDir(r.cwd), relAge(r.created, now), `ctx ${fmtCtx(r.ctx_tokens)}`];
     if (r.asks > 0)
         metaPieces.push(`⚑${r.asks}`);
+    if (r.hanging != null)
+        metaPieces.push(faultSummary(r.hanging, now));
     if (r.streaming === true)
-        metaPieces.push('⟳ streaming');
+        metaPieces.push('⟳');
     if (r.viewed === true)
         metaPieces.push('◉ viewing');
     const metaText = clip(metaPieces.filter((p) => p !== '').join('  ·  '), Math.max(0, width - 2));
@@ -471,13 +467,19 @@ export function renderFrame(state, size, caps = { color: false, color256: false
     if (state.pendingClose !== null && state.pendingClose !== undefined) {
         const node = state.tree.nodes.get(state.pendingClose);
         const who = node !== undefined ? node.row.name : state.pendingClose;
-        const warn = `⚠ ${who} is actively streaming — close it (and its subtree) anyway?  y / n`;
+        const warn = `⚠ ${who} is ⟳ — close it (and its subtree) anyway?  y / n`;
         lines.push(caps.color ? `${BOLD}${ESC}${FG_BRIGHT_YELLOW}m${clip(warn, width)}${RESET}` : `${REVERSE}${clip(warn, width)}${RESET}`);
     }
     else {
+        // When the cursor row has an active fault, lead the footer with the on-demand kick
+        // hint (K shells `canvas revive <id> --now` — immediate revive instead of
+        // waiting for the daemon's retry schedule).
+        const selRow = state.visible[state.cursor];
+        const cursorRow = selRow !== undefined ? state.tree.nodes.get(selRow.id)?.row : undefined;
+        const hangingHint = cursorRow?.hanging != null ? 'K revive now  ' : '';
         const footer = state.search
             ? '⏎ commit  Esc cancel  ⌫ delete'
-            : '↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit';
+            : `${hangingHint}↑↓ move  →/← tree  ⏎ resume  x close  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit`;
         lines.push(`${DIM}${clip(footer, width)}${RESET}`);
     }
     // Assemble: home, each line cleared to EOL, then clear below.

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

@@ -82,6 +82,18 @@ 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). 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 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
@@ -104,3 +116,24 @@ export declare function pruneNodes(opts: {
     dryRun?: boolean;
     includeStale?: boolean;
 }): PruneResult;
+/** 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 declare function pruneToLimit(opts: {
+    maxNodes: number;
+    dryRun?: boolean;
+}): PruneResult;