@crouton-kit/crouter 0.3.27 → 0.3.29

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.d.ts

@@ -0,0 +1,162 @@
+import type { NodeMeta, SubscriptionRef } from './index.js';
+/** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
+ *  array widget; anything beyond it pi truncates with its own "... (widget
+ *  truncated)". Our GRAPH viewport stays at/under this and scrolls internally. */
+export declare const PI_MAX_WIDGET_LINES = 10;
+export declare const VIEWPORT_FALLBACK_ROWS = 30;
+export declare const ESC = "\u001B[";
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const REVERSE = "\u001B[7m";
+/** Dark-green background bar marking an ATTACHED node (a human is currently
+ *  watching it) — distinct from the cursor's reverse-video bar; chosen so
+ *  default-fg text stays readable. */
+export declare const BG_ATTACHED = "\u001B[48;5;22m";
+export declare const GREEN = "\u001B[32m";
+export declare const RED = "\u001B[31m";
+export declare const YELLOW = "\u001B[33m";
+export declare const CYAN = "\u001B[36m";
+export declare const GRAY = "\u001B[90m";
+/** Status glyph colored by state: active green, idle dim, done cyan, dead red. */
+export declare function coloredGlyph(node: NodeMeta | null): string;
+/** Visible width, ignoring ANSI escapes. */
+export declare function visibleWidth(s: string): number;
+/** Truncate to `max` VISIBLE columns: escape sequences are copied through
+ *  verbatim (so a cut never lands mid-escape) and the result always ends in
+ *  RESET, so a clipped style can't bleed into the editor below. */
+export declare function truncate(s: string, max?: number): string;
+/** Visible columns available to ONE widget line — the cap for every line we
+ *  emit, and the width a full-width reverse-video SELF bar fills to.
+ *
+ *  pi does NOT clip widget lines; it WRAPS them. Each string line is wrapped in
+ *  a `Text(paddingX = 1)` inside a full-terminal-width container, so the usable
+ *  content width is `columns - 2` (a 1-col margin on each side). A line wider
+ *  than that wraps, and the overflow spills onto a second row as a stray
+ *  reverse-video block (the bug this guards against). Clamp to `columns - 2`. */
+export declare function fillWidth(): number;
+/** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
+ *  the cursor, BG_ATTACHED for a human-watched node). `open` is re-asserted after every
+ *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
+ *  bar; the visible width is padded out to `width`; the line closes with a real
+ *  RESET so the style never bleeds into the editor below. */
+export declare function fillBar(content: string, width: number, open: string): string;
+export declare function beginFrame(): void;
+/** getNode memoized for the current frame (meta.json read + sqlite row). */
+export declare function cNode(id: string): NodeMeta | null;
+/** subscriptionsOf (a node's reports) memoized for the current frame. */
+export declare function cSubscriptions(id: string): SubscriptionRef[];
+/** subscribersOf (a node's managers) memoized for the current frame. */
+export declare function cSubscribers(id: string): SubscriptionRef[];
+export interface Telemetry {
+    /** Live context-window size (pi's getContextUsage) — the figure pi's own footer
+     *  shows. This is the node's window fill, NOT a per-turn delta. */
+    context_tokens?: number;
+    /** One-line "what is it doing" cue (`tool: detail`), written on every tool start. */
+    last_activity?: string;
+}
+export declare function readTelemetry(nodeId: string): Telemetry;
+export declare function fmtTokens(n: number): string;
+/** The context-window cell — live window fill rounded to the nearest 1k (the same
+ *  figure pi's footer shows), NOT a per-turn token delta. */
+export declare function tokensCell(id: string): string;
+/** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
+export declare function activityCell(id: string, node: NodeMeta | null): string;
+/** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
+export declare function cycleBadge(node: NodeMeta | null): string;
+/** Short on-screen label: the explicit handle when set, else the pi-generated
+ *  description, else the bare name. fullName joins BOTH (`handle description`);
+ *  the nav chrome shows just the first so rows stay compact. */
+export declare function navLabel(node: NodeMeta | null, id: string): string;
+export declare function shortId(id: string): string;
+/** Node ids currently shown in a tmux focus viewport. Built once per render. */
+export declare function focusedNodeIds(): Set<string>;
+/** True when a human is watching `id` right now (tmux focus or broker viewer). */
+export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>): boolean;
+export declare function fetchAsksMap(rootId: string): Record<string, number>;
+/** First manager (by created) — the UP step for the ancestry spine. */
+export declare function managerOf(id: string): string | undefined;
+/** A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
+ *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
+ *  boots a confused blank "you have been revived" pi. Its pending-ask signal
+ *  already rides the ⚑ badge on the ASKING node (attention.ts attributes asks by
+ *  source.nodeId, never to the human node), so the row carries no signal of its
+ *  own. Drop it from every navigable list (the tree, BASE reports, child counts,
+ *  subtree expansion) so it can never be selected. */
+export declare function isHumanAsk(id: string): boolean;
+/** A node's direct children that are navigable conversations — human-ask nodes
+ *  dropped. The one place the nav chrome enumerates children. */
+export declare function convoChildIds(id: string): string[];
+/** Live reports (active|idle) of a node — the DOWN set in BASE. */
+export declare function liveReports(id: string): string[];
+/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
+ *  nodes excluded, so the count matches what the tree actually shows). */
+export declare function childCount(id: string): number;
+/** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
+export declare function climbRoot(self: string): string;
+/** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
+export declare function subtreeIds(root: string): string[];
+/** ⤳M direct-children badge — only on orchestrator rows. */
+export declare function childBadge(node: NodeMeta | null): string;
+/** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
+export declare function askBadge(id: string, asks: Record<string, number>): string;
+/** "Live work below" badge — green ⇣N when this node is NOT itself active but has
+ *  N active descendants. The one signal that an idle/parked node isn't dead: real
+ *  work is still running beneath it. Count comes from the single subtree-activity
+ *  pass (no per-row walk). Suppressed on active rows (their own ● already says so). */
+export declare function liveBelowBadge(node: NodeMeta | null, activeBelow: ReadonlyMap<string, number>): string;
+/** Sort rank for sibling ordering — live nodes (active, then idle) ahead of
+ *  terminal ones, so sessions still running surface at the TOP of each child
+ *  group instead of being buried under finished/failed ones. */
+export declare function statusRank(id: string): number;
+/** Direct children, live-first — the sibling order used both when flattening
+ *  the tree and when stepping into a subtree (`l`). Array.sort is stable, so
+ *  equal-status siblings keep their creation order. */
+export declare function sortedChildIds(id: string): string[];
+export interface FlatRow {
+    id: string;
+    hasKids: boolean;
+    isSelf: boolean;
+    branch: string;
+    cycle: boolean;
+    collapsed: boolean;
+}
+/** Manual fold OVERRIDES, keyed by id. `userCollapsed` forces a fold, `userExpanded`
+ *  forces an unfold; both override the default activity-driven policy. Held by the
+ *  consumer (the extension / viewer) and threaded into buildGraphModel so this layer
+ *  carries no mutable singletons. */
+export interface FoldState {
+    userExpanded: ReadonlySet<string>;
+    userCollapsed: ReadonlySet<string>;
+}
+/** One bottom-up O(N) pass over the local graph, computing TWO things at once so
+ *  the render path never walks twice:
+ *   - `expand`: which nodes auto-UNFOLD — a node expands when a child subtree holds
+ *     a running ('active') agent or self, so the path to any live agent (and to
+ *     you) is revealed while quiescent branches stay folded.
+ *   - `activeBelow`: per node, the count of ACTIVE descendants (excluding itself) —
+ *     drives the ⇣N "live work below" badge on idle/parked nodes.
+ *  Cycle-guarded (the graph is declared acyclic; a re-seen id contributes only
+ *  its own status, never its subtree again, so counts can't double or loop). */
+export interface SubtreeActivity {
+    expand: Set<string>;
+    activeBelow: Map<string, number>;
+}
+export declare function computeSubtreeActivity(root: string, self: string): SubtreeActivity;
+/** Fold policy alone — thin wrapper over computeSubtreeActivity for the keypress
+ *  path (buildGraphModel without a precomputed set). The render path computes the
+ *  activity once and threads `expand` in, so it never recomputes here. */
+export declare function computeDefaultExpanded(root: string, self: string): Set<string>;
+export declare function buildGraphModel(self: string, folds: FoldState, expand?: ReadonlySet<string>): FlatRow[];
+/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
+ *  (human-watched) node → a coloured background bar; SELF → bold name. The
+ *  cursor outranks the attached tint when both land on the same row. Running
+ *  is signaled by the dot glyph alone (● green = active engine). */
+export declare function renderGraphRow(r: FlatRow, isCursor: boolean, focused: ReadonlySet<string>, activeBelow: ReadonlyMap<string, number>, asks: Record<string, number>): string;
+/** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
+ *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
+ *  scroll chrome — so never exceed it (and shrink on a very short terminal).
+ *  The viewport scrolls WITHIN this cap as the cursor moves. */
+export declare function graphWidgetBudget(): number;
+export declare const GRAPH_HINT = "\u001B[2mjk move \u00B7 hl fold \u00B7 \u21B5 focus \u00B7 e expand \u00B7 x kill \u00B7 m mgr \u00B7 esc\u001B[0m";