@north-light/crouter 0.3.154

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

@@ -0,0 +1,284 @@
+// nav-model.ts — the canvas-graph half of the nav model for attach's chrome.
+//
+// The PURE render + telemetry helpers (ANSI styling, fillBar/truncate,
+// nodeGlyph, tokensCell, the graph row/fold types, …) live in nav-render.ts and
+// are RE-EXPORTED here so existing importers of nav-model keep working. What
+// stays here is the canvas-db graph layer: getNode/subscriptions walks and the
+// fold/flatten model built over them.
+//
+// Everything is pi-API-free. Per-view interaction state, including ask counts
+// and manual fold overrides, is threaded through parameters (see `asks` and
+// `FoldState`) so this layer owns no singletons and each consumer keeps its own
+// state.
+import { getNode, subscribersOf, subscriptionsOf } from './index.js';
+import { activeFaultForDisplay } from './render.js';
+import { readFault } from '../runtime/fault.js';
+import { faultSummary } from './status-glyph.js';
+import { beginFrameTelem, nodeGlyph, navLabel, shortId, tokensCell, activityCell, cycleBadge, askBadge, liveBelowBadge, truncate, fillBar, fillWidth, isAttached, BOLD, DIM, RESET, REVERSE, BG_ATTACHED, } from './nav-render.js';
+// Re-export the pure render/telemetry half so existing nav-model importers
+// (chrome/canvas-panels, overlays/graph, resume) keep resolving these here.
+export { PI_MAX_WIDGET_LINES, VIEWPORT_FALLBACK_ROWS, ESC, RESET, BOLD, DIM, REVERSE, BG_ATTACHED, GREEN, RED, YELLOW, CYAN, GRAY, nodeGlyph, visibleWidth, truncate, fillWidth, fillBar, readTelemetry, fmtTokens, tokensCell, activityCell, cycleBadge, navLabel, shortId, askBadge, liveBelowBadge, isAttached, hasBrokerViewers, fetchAsksMap, graphWidgetBudget, GRAPH_HINT, } from './nav-render.js';
+// ---------------------------------------------------------------------------
+// Per-frame read cache
+//
+// One render fans the SAME handful of nodes out 5-10× each: computeSubtreeActivity
+// walks the whole tree (getNode + subscriptions per node), buildGraphModel walks it
+// again (climbRoot, sortedChildIds), then every visible row re-reads getNode +
+// telemetry + subscriptions for its badges. getNode alone is an fs.readFileSync of
+// meta.json plus a sqlite row read, and readTelemetry another readFileSync — so on a
+// modest graph a single 'j' keystroke fanned out to DOZENS of redundant disk reads.
+// That redundancy is the GRAPH view's open/scroll lag.
+//
+// Each render is a synchronous snapshot, so we memoize the read primitives for the
+// duration of one frame and clear at the top of render(): the next keystroke (or the
+// ask-poll / inbox render) re-reads fresh, so a killed node, a new spawn, or a status
+// flip all surface on the very next frame. Nothing here writes, so a stale entry can
+// at worst be one frame old — and render() always reruns immediately after any action.
+// The telemetry cache lives in nav-render (readTelemetry); beginFrame clears it too.
+// ---------------------------------------------------------------------------
+const frameNodes = new Map();
+const frameSubs = new Map();
+const frameMgrs = new Map();
+export function beginFrame() {
+    frameNodes.clear();
+    frameSubs.clear();
+    frameMgrs.clear();
+    beginFrameTelem();
+}
+/** getNode memoized for the current frame (meta.json read + sqlite row). */
+export function cNode(id) {
+    if (frameNodes.has(id))
+        return frameNodes.get(id) ?? null;
+    const v = getNode(id);
+    frameNodes.set(id, v);
+    return v;
+}
+/** subscriptionsOf (a node's reports) memoized for the current frame. */
+export function cSubscriptions(id) {
+    const hit = frameSubs.get(id);
+    if (hit !== undefined)
+        return hit;
+    let v;
+    try {
+        v = subscriptionsOf(id);
+    }
+    catch {
+        v = [];
+    }
+    frameSubs.set(id, v);
+    return v;
+}
+/** subscribersOf (a node's managers) memoized for the current frame. */
+export function cSubscribers(id) {
+    const hit = frameMgrs.get(id);
+    if (hit !== undefined)
+        return hit;
+    let v;
+    try {
+        v = subscribersOf(id);
+    }
+    catch {
+        v = [];
+    }
+    frameMgrs.set(id, v);
+    return v;
+}
+// ---------------------------------------------------------------------------
+// Attachment — is a human currently WATCHING a node? A separate axis from
+// 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.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Graph queries (dependency-free, straight off the canvas db)
+// ---------------------------------------------------------------------------
+/** First manager (by created) — the UP step for the ancestry spine. */
+export function managerOf(id) {
+    return cSubscribers(id)[0]?.node_id;
+}
+/** 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 follows the
+ *  bridge node's parent relation), 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 function isHumanAsk(id) {
+    return cNode(id)?.kind === 'human';
+}
+/** A node's direct children that are navigable conversations — human-ask nodes
+ *  dropped. The one place the nav chrome enumerates children. */
+export function convoChildIds(id) {
+    return cSubscriptions(id).map((s) => s.node_id).filter((cid) => !isHumanAsk(cid));
+}
+/** Live reports (active|idle) of a node — the DOWN set in BASE. */
+export function liveReports(id) {
+    return convoChildIds(id).filter((cid) => {
+        const st = cNode(cid)?.status;
+        return st === 'active' || st === 'idle';
+    });
+}
+/** Direct navigable children — used for the ⤳ badge (human-ask nodes excluded,
+ *  so the count matches what the tree actually shows). */
+export function childCount(id) {
+    return convoChildIds(id).length;
+}
+/** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
+export function climbRoot(self) {
+    let cur = self;
+    const seen = new Set([cur]);
+    for (;;) {
+        const mgr = managerOf(cur);
+        if (mgr === undefined || seen.has(mgr))
+            break;
+        seen.add(mgr);
+        cur = mgr;
+    }
+    return cur;
+}
+/** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
+export function subtreeIds(root) {
+    const out = [];
+    const seen = new Set([root]);
+    const q = convoChildIds(root);
+    while (q.length > 0) {
+        const id = q.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+        for (const cid of convoChildIds(id))
+            if (!seen.has(cid))
+                q.push(cid);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Shared cell builders
+// ---------------------------------------------------------------------------
+/** ⤳M direct-children badge — the single child-count signal, shown on any row
+ *  with navigable children (folded or not). In GRAPH the ▸ caret separately marks
+ *  a collapsed row, so this stays a pure count and never doubles as a fold badge. */
+export function childBadge(node) {
+    if (node === null)
+        return '';
+    const m = childCount(node.node_id);
+    return m > 0 ? ` ${DIM}⤳${m}${RESET}` : '';
+}
+/** 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 function statusRank(id) {
+    switch (cNode(id)?.status) {
+        case 'active': return 0;
+        case 'idle': return 1;
+        case 'done': return 2;
+        case 'canceled': return 3;
+        case 'dead': return 4;
+        default: return 5;
+    }
+}
+/** 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 function sortedChildIds(id) {
+    return convoChildIds(id).sort((a, b) => statusRank(a) - statusRank(b));
+}
+// ---------------------------------------------------------------------------
+// GRAPH model — flatten the local graph fold-aware. Rebuilt every render (cheap
+// sqlite reads) so a finished child / new spawn shows live; the manual fold
+// overrides and the cursor id are the only persisted state.
+// ---------------------------------------------------------------------------
+export function computeSubtreeActivity(root, self) {
+    const expand = new Set();
+    const activeBelow = new Map();
+    const seen = new Set();
+    // Returns the count of active nodes in subtree(id) INCLUDING id, and whether
+    // that subtree is worth revealing (holds an active node or self).
+    const visit = (id) => {
+        const selfActive = cNode(id)?.status === 'active';
+        if (seen.has(id))
+            return { active: selfActive ? 1 : 0, reveal: selfActive || id === self };
+        seen.add(id);
+        let below = 0;
+        let childReveal = false;
+        for (const c of convoChildIds(id)) {
+            const r = visit(c);
+            below += r.active;
+            if (r.reveal)
+                childReveal = true;
+        }
+        activeBelow.set(id, below);
+        if (childReveal)
+            expand.add(id); // a descendant is worth revealing → unfold id
+        return { active: below + (selfActive ? 1 : 0), reveal: childReveal || selfActive || id === self };
+    };
+    visit(root);
+    return { expand, activeBelow };
+}
+/** 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 function computeDefaultExpanded(root, self) {
+    return computeSubtreeActivity(root, self).expand;
+}
+export function buildGraphModel(self, folds, expand) {
+    const rootId = climbRoot(self);
+    const defaultExpanded = expand ?? computeDefaultExpanded(rootId, self);
+    // userExpanded / userCollapsed override the auto policy; absent → policy decides.
+    const isFolded = (id) => folds.userExpanded.has(id) ? false : folds.userCollapsed.has(id) ? true : !defaultExpanded.has(id);
+    const rows = [];
+    const visited = new Set();
+    const walk = (id, prefix, isRoot, isLast) => {
+        if (visited.has(id)) {
+            const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+            rows.push({ id, hasKids: false, isSelf: id === self, branch: prefix + connector, cycle: true, collapsed: false });
+            return;
+        }
+        visited.add(id);
+        const kids = sortedChildIds(id);
+        const folded = isFolded(id);
+        const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+        rows.push({ id, hasKids: kids.length > 0, isSelf: id === self, branch: prefix + connector, cycle: false, collapsed: folded });
+        if (folded)
+            return; // folded — don't descend
+        const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
+        for (let i = 0; i < kids.length; i++)
+            walk(kids[i], childPrefix, false, i === kids.length - 1);
+    };
+    walk(rootId, '', true, true);
+    return rows;
+}
+/** 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. The
+ *  overlay-aware glyph alone carries the live signal (status / ⟳ / ⚠). */
+export function renderGraphRow(r, isCursor, focused, activeBelow, asks) {
+    const wrap = (line, attached) => isCursor ? fillBar(line, fillWidth(), REVERSE)
+        : attached ? fillBar(line, fillWidth(), BG_ATTACHED)
+            : truncate(line);
+    if (r.cycle) {
+        const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
+        return wrap(line, false);
+    }
+    const node = cNode(r.id);
+    const dot = nodeGlyph(node);
+    const rawName = navLabel(node, r.id);
+    const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
+    const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
+    const tokens = `${DIM}${tokensCell(r.id)}${RESET}`;
+    // ▸ marks an expandable (collapsed-with-kids) row. The cursor row gets no
+    // caret — its reverse-video bar already distinguishes it — so the triangle
+    // reads purely as "this unfolds".
+    const expandable = r.hasKids && r.collapsed;
+    const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
+    const fault = node !== null ? activeFaultForDisplay(node, readFault(r.id)) : null;
+    const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
+    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycleBadge(node)}${childBadge(node)}${liveBelowBadge(node, activeBelow)}${askBadge(r.id, asks)}${activityCell(r.id, node)}${faultSuffix}`;
+    return wrap(line, isAttached(r.id, node, focused));
+}

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

@@ -0,0 +1,124 @@
+import type { NodeMeta } from './types.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";
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export declare function nodeGlyph(node: NodeMeta | null, remote?: boolean): 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;
+/** Clear the per-frame telemetry cache. Called from nav-model's beginFrame so
+ *  the graph half and the render half share one frame boundary. */
+export declare function beginFrameTelem(): void;
+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. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export declare function tokensCell(id: string, remote?: boolean): 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.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export declare function activityCell(id: string, node: NodeMeta | null, remote?: boolean): 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;
+/** True when a human is watching `id` right now via the broker viewer count
+ *  (attach.json). The tmux-focus axis (a `focuses` row) is a canvas-db read and
+ *  stays in nav-model's `isAttached`, which ORs this signal with the focus set.
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export declare function hasBrokerViewers(id: string, node: NodeMeta | null, remote?: boolean): boolean;
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `focused` is the tmux-focus set (a canvas-db read the caller supplies). The
+ *  broker-viewer half is a pure `attach.json` read. `remote` skips the local read
+ *  entirely and reports false (a remote node id may collide with a local one). */
+export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>, remote?: boolean): boolean;
+/** ⚑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;
+export declare function fetchAsksMap(rootId: string): Record<string, number>;
+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 result over the local graph (see computeSubtreeActivity
+ *  in nav-model.ts):
+ *   - `expand`: which nodes auto-UNFOLD — a node expands when a child subtree holds
+ *     a running ('active') agent or self.
+ *   - `activeBelow`: per node, the count of ACTIVE descendants (excluding itself). */
+export interface SubtreeActivity {
+    expand: Set<string>;
+    activeBelow: Map<string, number>;
+}
+/** 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";

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

@@ -0,0 +1,266 @@
+// nav-render.ts — the PURE render + telemetry half of the nav model.
+//
+// Everything here is canvas-db-free: it reads node telemetry (job/telemetry.json,
+// attach.json — pure `jobDir` fs reads), per-node fault/busy/pid marker files, and
+// produces ANSI-styled strings. No `getNode`/`subscriptionsOf`/`listFocuses` — the
+// graph-walking half lives in nav-model.ts (which re-exports these helpers for its
+// own callers). This split lets the attach viewer's pure chrome pull render helpers
+// without dragging the canvas state-store into its bundle.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from './paths.js';
+import { isPidAlive } from './pid.js';
+import { isBusy } from '../runtime/busy.js';
+import { readFault } from '../runtime/fault.js';
+import { activeFaultForDisplay } from './render-source.js';
+import { resolveNodeVisual } from './status-glyph.js';
+// ---------------------------------------------------------------------------
+// Tuning constants
+// ---------------------------------------------------------------------------
+/** 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 const PI_MAX_WIDGET_LINES = 10;
+export const VIEWPORT_FALLBACK_ROWS = 30;
+// ---------------------------------------------------------------------------
+// ANSI styling. pi renders embedded escapes in widget lines and measures width
+// ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
+// (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
+// NO_COLOR; the attached-row tint is a background COLOUR, while the overlay-
+// aware glyph (●/○/✓/✗/⟳/⚠) carries the live signal independently, even where
+// colour is stripped.
+// ---------------------------------------------------------------------------
+export const ESC = '\x1b[';
+export const RESET = `${ESC}0m`;
+export const BOLD = `${ESC}1m`;
+export const DIM = `${ESC}2m`;
+export const REVERSE = `${ESC}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 const BG_ATTACHED = `${ESC}48;5;22m`;
+export const GREEN = `${ESC}32m`;
+export const RED = `${ESC}31m`;
+export const YELLOW = `${ESC}33m`;
+export const CYAN = `${ESC}36m`;
+export const GRAY = `${ESC}90m`;
+function hangingFor(node) {
+    return activeFaultForDisplay(node, readFault(node.node_id));
+}
+function streamingFor(node) {
+    if (node.status !== 'active' && node.status !== 'idle')
+        return false;
+    if (!isPidAlive(node.pi_pid))
+        return false;
+    // `isBusy` (the canonical mid-turn marker) AND-ed with the live pid above —
+    // a stale marker from a crashed pi fails the pid check, never the existsSync.
+    return isBusy(node.node_id);
+}
+/** Overlay-aware glyph for a node: hanging ⚠ outranks streaming ⟳, which
+ *  outranks the base status glyph. `remote` skips the local `readFault` /
+ *  `isPidAlive` / `isBusy` reads entirely (a remote node id may collide with a
+ *  local one) and renders the bare status glyph instead. */
+export function nodeGlyph(node, remote = false) {
+    if (node === null)
+        return '?';
+    const v = resolveNodeVisual(node.status, {
+        streaming: remote ? false : streamingFor(node),
+        hanging: remote ? null : hangingFor(node),
+    });
+    return `${ESC}${v.color}m${v.glyph}${RESET}`;
+}
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Visible width, ignoring ANSI escapes. */
+export function visibleWidth(s) {
+    return s.replace(ANSI_RE, '').length;
+}
+/** 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 function truncate(s, max = fillWidth()) {
+    if (visibleWidth(s) <= max)
+        return s;
+    let out = '';
+    let w = 0;
+    let i = 0;
+    while (i < s.length && w < max - 1) {
+        if (s[i] === '\x1b') {
+            const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
+            if (m) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        out += s[i];
+        w++;
+        i++;
+    }
+    return `${out}…${RESET}`;
+}
+/** 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 function fillWidth() {
+    return Math.max(20, Math.min((process.stdout.columns ?? 80) - 2, 180));
+}
+/** 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 function fillBar(content, width, open) {
+    const clipped = truncate(content, width);
+    const reasserted = clipped.replace(/\x1b\[0m/g, `${RESET}${open}`);
+    const pad = Math.max(0, width - visibleWidth(clipped));
+    return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
+}
+// ---------------------------------------------------------------------------
+// Per-frame telemetry cache. Cleared at the top of each render pass (nav-model's
+// beginFrame calls beginFrameTelem) so token/activity cells read fresh once per
+// frame instead of once per row. Nothing here writes, so a stale entry can at
+// worst be one frame old.
+// ---------------------------------------------------------------------------
+const frameTelem = new Map();
+/** Clear the per-frame telemetry cache. Called from nav-model's beginFrame so
+ *  the graph half and the render half share one frame boundary. */
+export function beginFrameTelem() {
+    frameTelem.clear();
+}
+export function readTelemetry(nodeId) {
+    const hit = frameTelem.get(nodeId);
+    if (hit !== undefined)
+        return hit;
+    let v;
+    try {
+        const p = join(jobDir(nodeId), 'telemetry.json');
+        v = existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : {};
+    }
+    catch {
+        v = {};
+    }
+    frameTelem.set(nodeId, v);
+    return v;
+}
+export function fmtTokens(n) {
+    return n < 1_000 ? `${n}` : `${Math.round(n / 1_000)}k`;
+}
+/** 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. `remote` skips the local
+ *  `telemetry.json` read entirely and reports 0 (a remote node id may collide
+ *  with a local one). */
+export function tokensCell(id, remote = false) {
+    return fmtTokens(remote ? 0 : (readTelemetry(id).context_tokens ?? 0));
+}
+/** 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.
+ *  `remote` skips the local `telemetry.json` read entirely and reports empty. */
+export function activityCell(id, node, remote = false) {
+    if (remote)
+        return '';
+    if (node?.status !== 'active')
+        return '';
+    const a = (readTelemetry(id).last_activity ?? '').trim();
+    return a === '' ? '' : ` ${DIM}· ${a}${RESET}`;
+}
+/** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
+export function cycleBadge(node) {
+    const c = node?.cycles ?? 0;
+    return c > 0 ? ` ${DIM}⟳${c}${RESET}` : '';
+}
+/** 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 function navLabel(node, id) {
+    if (node === null)
+        return shortId(id);
+    const handle = node.name && node.name !== node.kind ? node.name : '';
+    if (handle !== '')
+        return handle;
+    const desc = (node.description ?? '').trim();
+    return desc !== '' ? desc : node.name;
+}
+export function shortId(id) {
+    return id.slice(0, 8);
+}
+/** True when a human is watching `id` right now via the broker viewer count
+ *  (attach.json). The tmux-focus axis (a `focuses` row) is a canvas-db read and
+ *  stays in nav-model's `isAttached`, which ORs this signal with the focus set.
+ *  `remote` skips the local `attach.json` read entirely and reports false (a
+ *  remote node id may collide with a local one). */
+export function hasBrokerViewers(id, node, remote = false) {
+    if (remote)
+        return false;
+    if (node?.status !== 'active')
+        return false; // stale attach.json from a crash
+    try {
+        const p = join(jobDir(id), 'attach.json');
+        if (!existsSync(p))
+            return false;
+        const rec = JSON.parse(readFileSync(p, 'utf8'));
+        return typeof rec.viewers === 'number' && rec.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when a human is watching `id` right now (tmux focus or broker viewer).
+ *  `focused` is the tmux-focus set (a canvas-db read the caller supplies). The
+ *  broker-viewer half is a pure `attach.json` read. `remote` skips the local read
+ *  entirely and reports false (a remote node id may collide with a local one). */
+export function isAttached(id, node, focused, remote = false) {
+    if (remote)
+        return false;
+    if (focused.has(id))
+        return true;
+    return hasBrokerViewers(id, node, remote);
+}
+/** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
+export function askBadge(id, asks) {
+    const k = asks[id] ?? 0;
+    return k > 0 ? ` ${YELLOW}⚑${k}${RESET}` : '';
+}
+/** "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 function liveBelowBadge(node, activeBelow) {
+    if (node === null || node.status === 'active')
+        return '';
+    const n = activeBelow.get(node.node_id) ?? 0;
+    return n > 0 ? ` ${GREEN}⇣${n}${RESET}` : '';
+}
+// ---------------------------------------------------------------------------
+// Per-node ask counts — ONE shell-out per poll. `crtr canvas attention map`
+// buckets a whole sub-DAG's pending asks by node in a single process, so the
+// timer stays cheap (< 2 s) regardless of how many nodes are visible. --json
+// gives a parseable {counts} blob (the default render is XML chrome).
+// ---------------------------------------------------------------------------
+export function fetchAsksMap(rootId) {
+    try {
+        const raw = execFileSync('crtr', ['canvas', 'attention', 'map', '--view', rootId, '--json'], {
+            timeout: 2_500,
+            encoding: 'utf8',
+        });
+        const parsed = JSON.parse(raw.trim());
+        return parsed.counts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** 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 function graphWidgetBudget() {
+    const rows = process.stdout.rows ?? VIEWPORT_FALLBACK_ROWS;
+    return Math.max(4, Math.min(PI_MAX_WIDGET_LINES, rows - 4));
+}
+export const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · e expand · x kill · m mgr · esc${RESET}`;