@crouton-kit/crouter 0.3.28 → 0.3.30

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

@@ -20,12 +20,28 @@ export { detectColorCaps };
 // Fixed chrome heights, shared with app.ts so its viewport math never drifts
 // from what renderFrame actually draws.
 //   header = title + tab bar + status line + separator (+ search input when searching)
-//   preview = separator + meta line + PREVIEW_BODY prompt lines
-export const PREVIEW_BODY = 5;
+//   preview = separator + meta line + PROMPT_LINES (spawn/match) + REPLY_LINES (last reply)
+export const PROMPT_LINES = 3;
+export const REPLY_LINES = 3;
+export const PREVIEW_BODY = PROMPT_LINES + REPLY_LINES;
 export const PREVIEW_HEIGHT = PREVIEW_BODY + 2;
+//   header = title + tab bar + status line + column header + separator (+ search input)
 export function headerHeight(search) {
-    return 4 + (search ? 1 : 0);
+    return 5 + (search ? 1 : 0);
 }
+// ── Row table layout ──────────────────────────────────────────────────────────
+// A row is three zones: a fixed-width STATUS rail (glyph + word) on the left, the
+// flexible tree-indented NAME in the middle, and a flush-right METADATA cluster
+// (kind/mode · ctx · age · project) whose fixed-width segments align into clean
+// vertical columns down the right edge. Wide terminals widen the name; narrow ones
+// clip the name (and drop the cluster) first. The status WORD — not a lone glyph —
+// is the legible, NO_COLOR-safe state signal.
+const STATUS_W = 10; // glyph + ' ' + longest word ('active'/'cancel') + trailing gap
+const KM_W = 22; // kind/mode column
+const CTX_W = 6; // ctx tokens column
+const AGE_W = 5; // age column
+const PROJ_W = 16; // project (~basename) column, only across All dirs
+const COL_GAP = '  ';
 // ── ANSI ────────────────────────────────────────────────────────────────────
 const ESC = '\x1b[';
 const RESET = `${ESC}0m`;
@@ -40,6 +56,7 @@ 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: '●',
@@ -165,8 +182,67 @@ function nameSpans(name, query, style) {
     flush();
     return out;
 }
-/** One row line: `<indent><collapse> <glyph> <name> [kind/mode] ctx Nk age [~dir] [⚑n]`.
- *  `showCwd` adds the project-name cue (All-dirs view); `now` drives the age. */
+/** Visible (cell) width of a span group — ANSI-free, surrogate-safe. */
+function spansWidth(spans) {
+    let n = 0;
+    for (const s of spans)
+        n += [...s.text].length;
+    return n;
+}
+/** The status rail: a status WORD next to its glyph, both in the status hue, padded
+ *  to STATUS_W so the rail forms a clean left column. `live` (bright green) when the
+ *  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 pad = Math.max(1, STATUS_W - [...text].length);
+    return [
+        { text, style: { fg, bold: streaming } },
+        { text: ' '.repeat(pad) },
+    ];
+}
+/** The flush-right metadata cluster as fixed-width segments, so kind/mode · ctx ·
+ *  age · project align into vertical columns down the right edge. `showCwd` adds the
+ *  project column (only meaningful across All dirs). */
+function metaCluster(r, now, showCwd) {
+    const ctxFg = ctxColorCode(r.ctx_tokens);
+    const out = [
+        { text: clipPad(`${r.kind}/${r.mode}`, KM_W), style: { fg: FG_GRAY } },
+        { text: COL_GAP },
+        { text: fmtCtx(r.ctx_tokens).padStart(CTX_W), style: { fg: ctxFg, dim: ctxFg === undefined } },
+        { text: COL_GAP },
+        { text: relAge(r.created, now).padStart(AGE_W), style: { dim: true } },
+    ];
+    if (showCwd) {
+        out.push({ text: COL_GAP }, { text: clipPad(`~${baseDir(r.cwd)}`, PROJ_W), style: { fg: FG_GRAY } });
+    }
+    return out;
+}
+/** Left-clip-pad: clip `s` to `w` cells then pad-end with spaces to exactly `w`. */
+function clipPad(s, w) {
+    return clip(s, w).padEnd(w);
+}
+/** Compose a row from a flexible LEFT zone and a fixed flush-right RIGHT cluster:
+ *  pad fills the gap so RIGHT hugs the edge; when the terminal is too narrow the
+ *  cluster is dropped rather than colliding with the name. The caller has already
+ *  clipped the name to fit. */
+function assembleRow(left, right, width, color, lineBase, fill) {
+    const leftW = spansWidth(left);
+    const rightW = spansWidth(right);
+    if (right.length === 0 || leftW + rightW + 1 > width) {
+        return assemble(left, width, color, lineBase, fill);
+    }
+    const pad = width - leftW - rightW;
+    return assemble([...left, { text: ' '.repeat(pad) }, ...right], width, color, lineBase, fill);
+}
+/** One table row: `<status rail>  <indent><collapse> <name> <flags>` ........ `<meta>`.
+ *  `showCwd` adds the project column (All-dirs view); `now` drives the age. */
 function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     const node = tree.nodes.get(row.id);
     if (node === undefined)
@@ -174,30 +250,35 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     const r = node.row;
     const indent = '  '.repeat(row.depth);
     const collapse = !row.hasChildren ? ' ' : row.collapsed ? '▸' : '▾';
-    const glyph = STATUS_GLYPH[r.status] ?? '?';
     const terminal = r.status === 'done' || r.status === 'dead' || r.status === 'canceled';
-    const ctxStr = fmtCtx(r.ctx_tokens);
-    const ctxFg = ctxColorCode(r.ctx_tokens);
-    const age = relAge(r.created, now);
-    // Name: bold on the cursor row; dim for terminal status (live names stay default).
-    const nameStyle = { dim: !isCursor && terminal, bold: isCursor };
-    const spans = [
-        { text: `${indent}${collapse} ` },
-        { text: glyph, style: { fg: STATUS_COLOR[r.status] } }, // load-bearing status hue
-        { text: ' ' },
-        ...nameSpans(r.name, query, nameStyle),
-        { text: ` [${r.kind}/${r.mode}]`, style: { fg: FG_GRAY } }, // recedes
-        { text: ' ctx ', style: { dim: true } },
-        { text: ctxStr, style: { fg: ctxFg, dim: ctxFg === undefined } }, // tiered budget cue
-    ];
-    if (age !== '')
-        spans.push({ text: ` ${age}`, style: { dim: true } }); // recency cue
-    if (showCwd)
-        spans.push({ text: ` ~${baseDir(r.cwd)}`, style: { fg: FG_GRAY } }); // project cue (All dirs)
+    // Left gutter (fixed slot): an eye when a viewer is ATTACHED — a scannable rail
+    // down the left edge of "what's on a screen right now". Blank otherwise.
+    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,
+    // attached lives in the gutter).
+    const flags = [];
     if (r.asks > 0)
-        spans.push({ text: ` ⚑${r.asks}`, style: { fg: FG_BRIGHT_YELLOW, bold: true } }); // attention
-    // Row base: cursor → subtle bg (256) or reverse fallback (also covers !color);
-    // non-matched ancestor → whole-row dim for tree context (keep prior behavior).
+        flags.push({ text: ` ⚑${r.asks}`, style: { fg: FG_BRIGHT_YELLOW, bold: true } }); // pending asks
+    const status = statusRail(r);
+    const right = metaCluster(r, now, showCwd);
+    const treeLead = `${indent}${collapse} `;
+    // Clip the NAME (only) so gutter + status + tree + name + flags + meta all fit;
+    // the cluster is dropped first (assembleRow) when even a 4-col name won't fit it.
+    const fixed = spansWidth([gutter]) + spansWidth(status) + [...treeLead].length + spansWidth(flags);
+    const rightW = spansWidth(right);
+    const nameMax = Math.max(4, width - fixed - rightW - 1);
+    const nameStyle = { dim: !isCursor && terminal, bold: isCursor }; // dim terminal names; bold the cursor row
+    const left = [
+        gutter,
+        ...status,
+        { text: treeLead, style: { dim: true } },
+        ...nameSpans(clip(r.name, nameMax), query, nameStyle),
+        ...flags,
+    ];
+    // Row base: cursor → subtle bg (256) or reverse fallback (also !color); non-matched
+    // ancestor → whole-row dim for tree context.
     let lineBase = '';
     let fill = false;
     if (isCursor) {
@@ -207,7 +288,26 @@ function rowLine(row, tree, width, isCursor, query, caps, showCwd, now) {
     else if (!row.matched) {
         lineBase = DIM;
     }
-    return assemble(spans, width, caps.color, lineBase, fill);
+    return assembleRow(left, right, width, caps.color, lineBase, fill);
+}
+/** The column-header row — dim labels aligned to the same zones the rows use, so
+ *  the metadata columns read as a table. */
+function columnHeaderLine(width, showCwd, caps) {
+    const left = [
+        { text: '  ' }, // viewer gutter (no label)
+        { text: 'STATUS'.padEnd(STATUS_W), style: { dim: true, bold: true } },
+        { text: 'NAME', style: { dim: true, bold: true } },
+    ];
+    const right = [
+        { text: 'KIND/MODE'.padEnd(KM_W), style: { dim: true, bold: true } },
+        { text: COL_GAP },
+        { text: 'CTX'.padStart(CTX_W), style: { dim: true, bold: true } },
+        { text: COL_GAP },
+        { text: 'AGE'.padStart(AGE_W), style: { dim: true, bold: true } },
+    ];
+    if (showCwd)
+        right.push({ text: COL_GAP }, { text: 'PROJECT'.padEnd(PROJ_W), style: { dim: true, bold: true } });
+    return assembleRow(left, right, width, caps.color, '', false);
 }
 /** The status line (always present): active cwd scope · sort mode · committed
  *  filter. The committed-filter indicator lives here now (not its own line) so a
@@ -248,11 +348,13 @@ 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), then the selected node's
- *  prompt wrapped to PREVIEW_BODY lines. Under a live query the body is WINDOWED to
- *  the matching prompt (anywhere in the conversation) with the match highlighted;
- *  with no query it shows the spawn prompt from the start. The "which one was this?"
- *  answer — paired with super-search. Always full height so viewport math holds. */
+ *  line (status · kind/mode · project · age · ctx · asks · streaming/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
+ *  highlighted; with no query it shows the spawn prompt from the start. Seeing both
+ *  ends — what it was asked and where it left off — answers "which one was this?".
+ *  Always full height so viewport math holds. */
 function previewPanel(r, width, caps, now, query) {
     const out = [`${DIM}${'─'.repeat(width)}${RESET}`];
     if (r === undefined) {
@@ -266,23 +368,43 @@ function previewPanel(r, width, caps, now, query) {
     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.streaming === true)
+        metaPieces.push('⟳ streaming');
+    if (r.viewed === true)
+        metaPieces.push('◉ viewing');
     const metaText = clip(metaPieces.filter((p) => p !== '').join('  ·  '), Math.max(0, width - 2));
     out.push(caps.color ? `${glyph} ${DIM}${metaText}${RESET}` : `${glyph} ${metaText}`);
-    // With a query, window+highlight the matching prompt from the WHOLE conversation;
-    // otherwise show the spawn prompt from the start.
+    // Block 1 — spawn prompt / query-match. With a query, window+highlight the
+    // matching prompt from the WHOLE conversation; otherwise the spawn prompt.
     const sourceText = query !== '' ? promptText(r) : (r.goal ?? '');
-    const snippet = previewSnippet(query, sourceText, width, PREVIEW_BODY);
-    if (snippet.length === 0) {
+    const promptSnippet = previewSnippet(query, sourceText, width, PROMPT_LINES);
+    if (promptSnippet.length === 0) {
         out.push(`${DIM}(no spawn prompt)${RESET}`);
-        for (let i = 1; i < PREVIEW_BODY; i++)
+        for (let i = 1; i < PROMPT_LINES; i++)
             out.push('');
     }
     else {
-        for (let i = 0; i < PREVIEW_BODY; i++) {
-            const ln = snippet[i];
+        for (let i = 0; i < PROMPT_LINES; i++) {
+            const ln = promptSnippet[i];
             out.push(ln === undefined ? '' : snippetLine(ln, width, caps));
         }
     }
+    // Block 2 — the node's LAST assistant reply, prefixed `↩` on its first line so
+    // the two blocks read apart. Wrapped to width-2 to leave room for the marker.
+    const replyMark = caps.color ? `${DIM}↩ ${RESET}` : '↩ ';
+    const replySnippet = previewSnippet('', r.lastAssistant ?? '', Math.max(1, width - 2), REPLY_LINES);
+    if (replySnippet.length === 0) {
+        out.push(`${replyMark}${DIM}(no reply yet)${RESET}`);
+        for (let i = 1; i < REPLY_LINES; i++)
+            out.push('');
+    }
+    else {
+        for (let i = 0; i < REPLY_LINES; i++) {
+            const ln = replySnippet[i];
+            const prefix = i === 0 ? replyMark : '  ';
+            out.push(ln === undefined ? (i === 0 ? `${replyMark}` : '') : `${prefix}${snippetLine(ln, Math.max(1, width - 2), caps)}`);
+        }
+    }
     return out;
 }
 /**
@@ -315,11 +437,12 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         const slash = caps.color ? `${ESC}${FG_CYAN}m/${RESET}` : '/';
         lines.push(`${slash} ${state.query}▎`);
     }
-    // separator.
+    // column header (table labels) + separator.
+    const showCwd = state.cwdScope === null; // project column only matters across dirs
+    lines.push(columnHeaderLine(width, showCwd, caps));
     lines.push(`${DIM}${'─'.repeat(width)}${RESET}`);
     // body — windowed visible rows, leaving room for the (optional) preview panel.
     const head = lines.length; // === headerHeight(state.search)
-    const showCwd = state.cwdScope === null; // project cue only matters across dirs
     const previewOn = state.preview && state.visible.length > 0;
     const previewH = previewOn ? PREVIEW_HEIGHT : 0;
     const viewport = Math.max(1, rows - head - 1 /* footer */ - previewH);
@@ -344,11 +467,19 @@ export function renderFrame(state, size, caps = { color: false, color256: false
         for (const l of previewPanel(r, width, caps, now, state.query))
             lines.push(l);
     }
-    // footer.
-    const footer = state.search
-        ? '⏎ commit  Esc cancel  ⌫ delete'
-        : '↑↓ move  →/← tree  ⏎ resume  Tab tabs  / search  s sort  c cwd  r residents  p preview  q quit';
-    lines.push(`${DIM}${clip(footer, width)}${RESET}`);
+    // footer — the y/n close-out confirm takes over when pending; else search / nav.
+    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`;
+        lines.push(caps.color ? `${BOLD}${ESC}${FG_BRIGHT_YELLOW}m${clip(warn, width)}${RESET}` : `${REVERSE}${clip(warn, width)}${RESET}`);
+    }
+    else {
+        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';
+        lines.push(`${DIM}${clip(footer, width)}${RESET}`);
+    }
     // Assemble: home, each line cleared to EOL, then clear below.
     const body = lines.map((l) => `${l}${ESC}K`).join('\r\n');
     return `${ESC}H${body}${ESC}J`;

package/dist/core/canvas/canvas.js

@@ -22,7 +22,7 @@ import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from '.
 const IDENTITY_KEYS = [
     'node_id', 'name', 'description', 'cycles', 'created', 'cwd', 'host_kind', 'kind', 'mode',
     'lifecycle', 'persona_ack', 'parent', 'spawned_by', 'fork_from', 'passive_default',
-    'home_session', 'pi_session_id', 'pi_session_file', 'model_override', 'launch',
+    'pi_session_id', 'pi_session_file', 'model_override', 'launch',
 ];
 /** Project any node object down to its durable-identity subset. */
 function toIdentity(m) {

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

@@ -4,10 +4,10 @@ import type { FocusRow } from './types.js';
 export declare function openFocusRow(focus_id: string, pane: string | null, session: string | null, node_id: string): void;
 /** Hot-swap a focus's occupant — single-statement UPDATE. Respects
  *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
- *  (correct — vacate-first is retargetFocus's job, Step 6, not this setter's). */
+ *  (correct — vacate-first is placement.focus()'s job, not this setter's). */
 export declare function setFocusOccupant(focus_id: string, node_id: string): void;
-/** Re-point a focus's durable pane + its derived session cache — for
- *  reconcileFocus / the daemon (Step 6). Single-statement UPDATE. */
+/** Re-point a viewer row's durable pane + its derived session cache after the
+ *  pane moves. Single-statement UPDATE. */
 export declare function setFocusPane(focus_id: string, pane: string | null, session: string | null): void;
 /** DELETE a viewport. */
 export declare function closeFocusRow(focus_id: string): void;
@@ -16,7 +16,7 @@ export declare function getFocusByNode(node_id: string): FocusRow | null;
 /** The focus realized by a given pane (`%id`), or null. */
 export declare function getFocusByPane(pane: string): FocusRow | null;
 /** A focus by its stable id, or null. Used by placement to read a row back by id
- *  (handFocusToManager / retargetFocus / registerRootFocus). */
+ *  after openFocusRow registers a viewer. */
 export declare function getFocusById(focus_id: string): FocusRow | null;
 /** Every focus row, ordered by id. */
 export declare function listFocuses(): FocusRow[];

package/dist/core/canvas/focuses.js

@@ -11,9 +11,9 @@
 // setPresence) — it never runs raw focus SQL itself.
 //
 // Each setter is a single atomic statement. UNIQUE(node_id) upholds "a node
-// occupies at most one focus" (Q5): a second focus row (or an occupant UPDATE)
-// for an already-focused node throws — that is correct, the Q5 vacate-first
-// orchestration is retargetFocus's job (Step 6), not these setters'.
+// occupies at most one viewer" (Q5): a second focus row (or an occupant UPDATE)
+// for an already-viewed node throws — that is correct, the vacate-first
+// orchestration is placement.focus()'s job, not these setters'.
 import { openDb } from './db.js';
 function focusFrom(r) {
     return {
@@ -35,12 +35,12 @@ export function openFocusRow(focus_id, pane, session, node_id) {
 }
 /** Hot-swap a focus's occupant — single-statement UPDATE. Respects
  *  UNIQUE(node_id): if `node_id` already occupies ANOTHER focus this throws
- *  (correct — vacate-first is retargetFocus's job, Step 6, not this setter's). */
+ *  (correct — vacate-first is placement.focus()'s job, not this setter's). */
 export function setFocusOccupant(focus_id, node_id) {
     openDb().prepare('UPDATE focuses SET node_id = ? WHERE focus_id = ?').run(node_id, focus_id);
 }
-/** Re-point a focus's durable pane + its derived session cache — for
- *  reconcileFocus / the daemon (Step 6). Single-statement UPDATE. */
+/** Re-point a viewer row's durable pane + its derived session cache after the
+ *  pane moves. Single-statement UPDATE. */
 export function setFocusPane(focus_id, pane, session) {
     openDb()
         .prepare('UPDATE focuses SET pane = ?, session = ? WHERE focus_id = ?')
@@ -68,7 +68,7 @@ export function getFocusByPane(pane) {
     return r ? focusFrom(r) : null;
 }
 /** A focus by its stable id, or null. Used by placement to read a row back by id
- *  (handFocusToManager / retargetFocus / registerRootFocus). */
+ *  after openFocusRow registers a viewer. */
 export function getFocusById(focus_id) {
     const r = openDb()
         .prepare('SELECT * FROM focuses WHERE focus_id = ?')

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

@@ -227,13 +227,14 @@ export function shortId(id) {
 }
 // ---------------------------------------------------------------------------
 // Attachment — is a human currently WATCHING a node? A separate axis from
-// running (status 'active' = the engine is live on its host, which may be an
-// unwatched backstage pane or a paneless broker). Two hosts, two signals:
-//   tmux   — a `focuses` row points at the node (one cheap sqlite read per
-//            render pass; pane-existence alone is NOT the signal).
-//   broker — the broker persists its helloed-viewer count to job/attach.json
-//            on every viewer change (src/core/runtime/broker.ts). Trusted only
-//            while the node is 'active': a broker crash can leave a stale file.
+// running (status 'active' = the engine is live on its detached broker, watched
+// or not). Two signals:
+//   viewer pane — a `focuses` row points at the node (one cheap sqlite read per
+//                 render pass; pane-existence alone is NOT the signal).
+//   broker      — the broker persists its helloed-viewer count (tmux panes AND
+//                 web tabs) to job/attach.json on every viewer change
+//                 (src/core/runtime/broker.ts). Trusted only while the node is
+//                 'active': a broker crash can leave a stale file.
 // ---------------------------------------------------------------------------
 /** Node ids currently shown in a tmux focus viewport. Built once per render. */
 export function focusedNodeIds() {

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

@@ -32,18 +32,77 @@ export interface DashboardRow {
      *  agent you come back to. Drives the browser's resident-only lifecycle filter.
      *  Only populated by dashboardRowsAll (the browser snapshot). */
     lifecycle?: Lifecycle;
-    /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Only
-     *  populated by dashboardRowsAll (the browser snapshot) — the dashboard leaf
-     *  leaves it undefined to avoid a file read per node. Indexed by super-search
-     *  and shown in the preview panel when there is no live query. */
+    /** "Most recent activity" sort key — epoch ms. The cheap boot stats the node's
+     *  job/telemetry.json (rewritten on every turn_end at a DETERMINISTIC path, so
+     *  no meta read), falling back to `created`'s epoch when a node never ran a turn.
+     *  This is the cheap proxy for last-message recency the attention sort tie-breaks
+     *  on. Always set by dashboardRowsAll; optional only so synthetic test rows + the
+     *  scoped dashboardRows can omit it. (NB: the pi session-file mtime would be truer
+     *  but its path lives in meta.json at a non-deterministic location — reading it
+     *  per node would defeat the cheap boot, so telemetry mtime is used instead.) */
+    mtimeMs?: number;
+    /** The node's spawn prompt (context/initial-prompt.md), trimmed + capped. Populated
+     *  LAZILY by loadPreview (selected-row preview) — NOT on the cheap boot path.
+     *  Indexed by super-search and shown in the preview panel when there is no query. */
     goal?: string;
-    /** EVERY user prompt across the node's pi session — the whole conversation, not
-     *  just the spawn prompt — joined + capped. Populated by dashboardRowsAll, undefined
-     *  for never-revived nodes (no session file). Powers whole-conversation super-search
-     *  + the windowed match snippet in the preview. */
+    /** EVERY user prompt across the node's pi session — the whole conversation, not just
+     *  the spawn prompt — joined + capped. Populated LAZILY by loadPreview (ONE session
+     *  read, folded with lastAssistant); undefined for never-revived nodes (no session
+     *  file). Powers whole-conversation super-search + the windowed preview snippet. */
     prompts?: string;
+    /** The node's LAST assistant message (text only), trimmed + capped. Populated LAZILY
+     *  by loadPreview (same single session read as `prompts`); undefined for a node whose
+     *  session has no assistant reply yet. Shown in the preview's reply block. */
+    lastAssistant?: string;
+    /** True when the node is GENUINELY mid-turn right now — its `busy` marker exists
+     *  AND its broker pid is alive (not merely an `active`, between-turns node). The
+     *  live "is it generating?" cue. Computed on the cheap boot path for LIVE nodes
+     *  only (dormant rows are always false). */
+    streaming?: boolean;
+    /** 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;
+    /** Lazy-enrichment guard (internal): true once enrichRow/enrichRows has folded in
+     *  the full label (meta), ctx tokens (telemetry), and ⚑ asks. Idempotency marker so
+     *  progressive paint can re-call enrich for a viewport every keystroke for free. */
+    enriched?: boolean;
+    /** Lazy-enrichment guard (internal): true once loadPreview has read goal + the
+     *  session (prompts + lastAssistant). Idempotency marker for the selected row. */
+    previewLoaded?: boolean;
 }
 /** One row per node visible in the sub-DAG of `rootId` (including root). */
 export declare function dashboardRows(rootId: string): DashboardRow[];
-/** One row per node across the entire canvas. */
+/**
+ * CHEAP boot builder — one row per node across the entire canvas, with only the
+ * fields that need no per-node meta/telemetry/session read. Two db queries total:
+ * `listNodes()` + `listFocuses()` (the focus set replaces 1473 `getFocusByNode`
+ * calls). For each node:
+ *   - identity/status/kind/mode/cwd/created/lifecycle straight off the db row;
+ *   - `name` is the db HANDLE only (the informative label needs meta.description —
+ *     fold it in lazily via {@link enrichRow}/{@link enrichRows});
+ *   - `viewed` from the one focus-set;
+ *   - `streaming` only for LIVE nodes (active|idle — the only ones that can be
+ *     mid-turn); dormant rows are always false (skips an isPidAlive + statSync);
+ *   - `mtimeMs` via a cheap telemetry statSync (no read) for the attention sort;
+ *   - `ctx_tokens`/`asks` left 0 and `goal`/`prompts`/`lastAssistant` undefined —
+ *     all deferred to the lazy enrichment API below.
+ *
+ * This is the first-frame path: paint from it immediately, then enrich the visible
+ * viewport on demand. See {@link enrichRow}, {@link enrichRows}, {@link loadPreview}.
+ */
 export declare function dashboardRowsAll(): DashboardRow[];
+/** Fold the cheap-boot row's deferred fields in for ONE row: the full label
+ *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
+ *  meta read + one telemetry read + one ask scan. Idempotent (no-op once enriched).
+ *  For a batch, prefer {@link enrichRows} — it scans each cwd's ask inbox once. */
+export declare function enrichRow(row: DashboardRow): DashboardRow;
+/** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
+ *  distinct cwd's ask inbox exactly ONCE (via `asksForNodes`) instead of per row.
+ *  Use this for a whole viewport / the full forest; mutates each row in place. */
+export declare function enrichRows(rows: DashboardRow[]): void;
+/** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
+ *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
+ *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
+ *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
+ *  warm the prompt super-search corpus), never on the boot path. */
+export declare function loadPreview(row: DashboardRow): DashboardRow;