@crouton-kit/crouter 0.3.32 → 0.3.33

package/dist/core/artifact.d.ts

@@ -1,37 +1,6 @@
-export type ArtifactKind = 'plans' | 'specs';
 export declare function mangleCwd(cwd?: string): string;
-export declare function artifactsRoot(kind: ArtifactKind, cwd?: string): string;
-/** Per-cwd interactions root, mirroring artifactsRoot construction.
- *  `~/.crouter/<mangled-cwd>/interactions/`. */
+export declare function workspaceRoot(cwd?: string): string;
 export declare function interactionsRoot(cwd?: string): string;
-/** Directory for one interaction. `id` is sanitized like an artifact name. */
 export declare function interactionDir(id: string, cwd?: string): string;
 export declare function sanitizeName(raw: string): string;
-export declare function artifactPath(kind: ArtifactKind, name: string, cwd?: string): string;
-/** Lines above this threshold trigger an oversize advisory in follow_up. */
-export declare const OVERSIZE_WARN_LINES = 200;
-export interface SaveArtifactResult {
-    path: string;
-    oversize: boolean;
-    lineCount: number;
-}
-/**
- * Atomically write an artifact. Prepends a minimal frontmatter block when
- * `meta` is non-empty so readers can extract structured fields without
- * parsing the full body. Returns the written path and oversize status.
- */
-export declare function saveArtifact(kind: ArtifactKind, name: string, body: string, meta?: Record<string, string>): SaveArtifactResult;
-export interface ArtifactRecord {
-    name: string;
-    path: string;
-    body: string;
-    /** Present only in plan artifacts; null if not set. */
-    spec: string | null;
-}
-export declare function readArtifact(kind: ArtifactKind, name: string): ArtifactRecord;
-export interface ArtifactListItem {
-    name: string;
-    path: string;
-    updated_at: string;
-}
-export declare function listArtifacts(kind: ArtifactKind): ArtifactListItem[];
+export declare function migrateLegacyWorkspaceDirs(): void;

package/dist/core/artifact.js

@@ -1,24 +1,20 @@
-// Core artifact primitives for plan and spec subtrees.
+// Core per-cwd workspace primitives for human interaction artifacts.
 // No commander, no spawn, no output helpers — pure data logic only.
-// Old registerArtifactCommand (commander-based) is removed; callers ported to JSON I/O.
 import { homedir } from 'node:os';
-import { join, dirname } from 'node:path';
-import { writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { renameSync } from 'node:fs';
 import { CRTR_DIR_NAME } from '../types.js';
-import { ensureDir, pathExists, readText, walkFiles } from './fs-utils.js';
-import { notFound, usage } from './errors.js';
+import { ensureDir, listDirs, pathExists, removePath } from './fs-utils.js';
+import { usage } from './errors.js';
 export function mangleCwd(cwd = process.cwd()) {
     return cwd.replace(/\//g, '-');
 }
-export function artifactsRoot(kind, cwd) {
-    return join(homedir(), CRTR_DIR_NAME, mangleCwd(cwd), kind);
+export function workspaceRoot(cwd) {
+    return join(homedir(), CRTR_DIR_NAME, 'workspaces', mangleCwd(cwd));
 }
-/** Per-cwd interactions root, mirroring artifactsRoot construction.
- *  `~/.crouter/<mangled-cwd>/interactions/`. */
 export function interactionsRoot(cwd) {
-    return join(homedir(), CRTR_DIR_NAME, mangleCwd(cwd), 'interactions');
+    return join(workspaceRoot(cwd), 'interactions');
 }
-/** Directory for one interaction. `id` is sanitized like an artifact name. */
 export function interactionDir(id, cwd) {
     return join(interactionsRoot(cwd), sanitizeName(id));
 }
@@ -34,84 +30,28 @@ export function sanitizeName(raw) {
     }
     return trimmed;
 }
-export function artifactPath(kind, name, cwd) {
-    return join(artifactsRoot(kind, cwd), `${sanitizeName(name)}.md`);
-}
-/** Lines above this threshold trigger an oversize advisory in follow_up. */
-export const OVERSIZE_WARN_LINES = 200;
-/**
- * Atomically write an artifact. Prepends a minimal frontmatter block when
- * `meta` is non-empty so readers can extract structured fields without
- * parsing the full body. Returns the written path and oversize status.
- */
-export function saveArtifact(kind, name, body, meta = {}) {
-    const filePath = artifactPath(kind, name);
-    ensureDir(dirname(filePath));
-    const metaKeys = Object.keys(meta);
-    let content;
-    if (metaKeys.length > 0) {
-        const fm = '---\n' + metaKeys.map((k) => `${k}: ${meta[k]}`).join('\n') + '\n---\n';
-        content = fm + body;
-    }
-    else {
-        content = body;
-    }
-    const finalContent = content.endsWith('\n') ? content : content + '\n';
-    writeFileSync(filePath, finalContent, 'utf8');
-    const lineCount = finalContent.split('\n').length - 1;
-    return { path: filePath, oversize: lineCount > OVERSIZE_WARN_LINES, lineCount };
-}
-const FRONTMATTER_BLOCK_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
-function parseArtifactFrontmatter(source) {
-    const match = source.match(FRONTMATTER_BLOCK_RE);
-    if (!match)
-        return { fields: {}, body: source };
-    const raw = match[1];
-    const body = source.slice(match[0].length);
-    const fields = {};
-    for (const line of raw.split(/\r?\n/)) {
-        const colon = line.indexOf(':');
-        if (colon === -1)
+const LEGACY_WORKSPACE_DIR_RE = /^-[A-Za-z0-9].*/;
+export function migrateLegacyWorkspaceDirs() {
+    const dataHome = join(homedir(), CRTR_DIR_NAME);
+    const workspaceHome = join(dataHome, 'workspaces');
+    if (!pathExists(dataHome))
+        return;
+    ensureDir(workspaceHome);
+    for (const entry of listDirs(dataHome)) {
+        if (entry === 'workspaces' || !LEGACY_WORKSPACE_DIR_RE.test(entry))
             continue;
-        const k = line.slice(0, colon).trim();
-        const v = line.slice(colon + 1).trim();
-        if (k !== '')
-            fields[k] = v;
-    }
-    return { fields, body };
-}
-export function readArtifact(kind, name) {
-    const filePath = artifactPath(kind, name);
-    if (!pathExists(filePath)) {
-        throw notFound(`${kind.slice(0, -1)} not found: ${name} (looked at ${filePath})`);
-    }
-    const raw = readText(filePath);
-    const { fields, body } = parseArtifactFrontmatter(raw);
-    const specField = fields['spec'];
-    return {
-        name,
-        path: filePath,
-        body,
-        spec: specField !== undefined ? specField : null,
-    };
-}
-export function listArtifacts(kind) {
-    const root = artifactsRoot(kind);
-    if (!pathExists(root))
-        return [];
-    const files = walkFiles(root, (n) => n.endsWith('.md'));
-    const items = files.map((abs) => {
-        const name = abs.substring(root.length + 1).replace(/\.md$/, '');
-        let updated_at = '';
+        const source = join(dataHome, entry);
+        const target = join(workspaceHome, entry);
+        if (pathExists(target)) {
+            removePath(source);
+            continue;
+        }
         try {
-            updated_at = statSync(abs).mtime.toISOString();
+            renameSync(source, target);
         }
         catch {
-            updated_at = new Date(0).toISOString();
+            // Leave the source in place only if the rename truly failed.
+            // The next startup will retry the same hard-cut move.
         }
-        return { name, path: abs, updated_at };
-    });
-    // Sort ascending by name (stable key for pagination cursor).
-    items.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
-    return items;
+    }
 }

package/dist/core/bootstrap.js

@@ -4,6 +4,7 @@ import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js
 import { ensureDir, pathExists, removePath, nowIso } from './fs-utils.js';
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
+import { migrateLegacyWorkspaceDirs } from './artifact.js';
 import { readMarketplaceManifest } from './manifest.js';
 import { CRTR_DIR_NAME } from '../types.js';
 export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
@@ -76,6 +77,7 @@ export function ensureProjectScope(argv) {
             return;
         if (shouldSkipForArgv(argv))
             return;
+        migrateLegacyWorkspaceDirs();
         // Already inside a project scope (here or in an ancestor) — nothing to do.
         if (findProjectScopeRoot() !== null)
             return;

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.