@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/overlays/graph.js

@@ -0,0 +1,725 @@
+// overlays/graph.ts — the configurable GRAPH navigator overlay for `crtr surface attach`.
+//
+// Native reimplementation of canvas-nav.ts's GRAPH modal as a pi-tui OVERLAY
+// (the viewer has no pi extension host). `tui.showOverlay(this, …)` mounts this
+// Component as a BOUNDED, centered modal (~72% of the terminal, themed frame) and
+// CAPTURES keyboard focus (mirrors overlays/dialogs.ts);
+// `OverlayHandle.hide()` tears it down and restores focus to the editor. While
+// shown, every key routes to handleInput() — a fold-aware NERDTree of the
+// active CanvasSource subscription graph. Actions and footer hints resolve from
+// the crouter binding catalog; input is decoded with pi-tui's canonical matcher
+// (kitty/CSI-u aware).
+//
+// Enter/m run the shared focus decision in-process (core/runtime/focus-viewer.ts,
+// the same code `crtr surface node focus` runs) with this viewer's own pane as
+// the anchor; r/x SHELL `crtr` out-of-process (node lifecycle revive / close).
+// The viewer itself never spawns pi or opens a session (the §0 one-writer
+// invariant) — focus revives only through crtrd's attach API. Under the
+// one-viewer-per-node model the target's existing viewer is navigated in place,
+// or a fresh viewer opens BESIDE this pane — never a second pane for the same node.
+//
+// REMOTE mode (source instanceof RemoteCanvasSource, i.e. `attach --canvas`):
+// this overlay is READ-ONLY. Focus/revive/kill are local-drive-plane actions and
+// a remote node id has no relationship to this machine's canvas.db, so Enter/r/m/x
+// no-op instead of shelling local lifecycle commands on an id that either doesn't
+// exist locally or, worse, collides with one that does. The footer hint drops the
+// local-action hints accordingly, and every
+// telemetry/fault/attach/focus adornment below is suppressed to a safe default
+// (see nav-model's `remote` parameters) — the remote CanvasSource supplies
+// graph structure + node metadata ONLY.
+import { execFile } from 'node:child_process';
+import { matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import { formatBinding, matchesPiTuiInput, } from '../../../core/keybindings/index.js';
+// Pure leaf imports (NOT the canvas/index barrel or nav-model, both of which
+// reach the canvas-db): fullName from labels.js, faultSummary from
+// status-glyph.js, all render helpers from nav-render.js. A LOCAL snapshot is
+// one `GET /v1/canvas/graph` read through the crtrd API — display rows,
+// subscription edges, and the tmux-focus set together — so this viewer stays off
+// the canvas-db and off the enriched full-node list.
+import { fullName } from '../../../core/canvas/labels.js';
+import { faultSummary, resolveNodeVisual } from '../../../core/canvas/status-glyph.js';
+import { RemoteCanvasSource } from '../../../core/canvas/remote-canvas-source.js';
+import { cliClient } from '../../../commands/api-client.js';
+import { focusNode } from '../../../core/runtime/focus-viewer.js';
+import { daemonErrorMessage } from '../../inbox/resolve.js';
+import { statusRank } from '../../../core/canvas/node-order.js';
+import { navLabel, nodeGlyph, tokensCell, cycleBadge, askBadge, activityCell, shortId, visibleWidth, fillBar, fillWidth, truncate, isAttached, VIEWPORT_FALLBACK_ROWS, ESC, DIM, RESET, BOLD, YELLOW, REVERSE, BG_ATTACHED, GREEN, } from '../../../core/canvas/nav-render.js';
+// A BOUNDED, centered modal (CTO ruling: not full-bleed). Width/height are capped
+// at ~72% of the terminal; the overlay clips our lines to maxHeight, and render()
+// budgets the panel to the SAME fraction (HEIGHT_PCT) so the framed box is never
+// clipped. margin keeps it off the screen edges.
+const HEIGHT_PCT = 0.72;
+const OVERLAY_OPTIONS = { anchor: 'center', width: '72%', minWidth: 48, maxHeight: '72%', margin: 1 };
+// The footer is width-budgeted (fitHints drops WHOLE trailing entries that
+// won't fit rather than mid-clipping the tail). List the keys a user most needs
+// to discover first — dismiss (the only way out) then the remapped local
+// actions — so they survive at the narrowest overlay width; routine navigation
+// trails and is the first to be dropped.
+const GRAPH_PRIMARY_LOCAL_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+    ['crtr.graph.focus', 'focus'],
+    ['crtr.graph.revive', 'revive'],
+    ['crtr.graph.close-subtree', 'close'],
+    ['crtr.graph.focus-manager', 'manager'],
+];
+const GRAPH_PRIMARY_READ_ONLY_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+];
+const GRAPH_NAV_HINTS = [
+    ['crtr.graph.down', 'down'],
+    ['crtr.graph.up', 'up'],
+    ['crtr.graph.first', 'first'],
+    ['crtr.graph.last', 'last'],
+    ['crtr.graph.collapse-or-manager', 'fold/manager'],
+    ['crtr.graph.expand-or-child', 'expand/child'],
+];
+const LEGEND_ROW = [
+    ...['active', 'idle', 'done', 'dead', 'canceled']
+        .map((status) => [resolveNodeVisual(status, {}), status]),
+    [resolveNodeVisual('active', { streaming: true }), 'live'],
+    [resolveNodeVisual('active', { frozen: true }), 'frozen'],
+    [resolveNodeVisual('active', { hanging: { kind: 'wedged' } }), 'fault'],
+].map(([visual, label]) => `${ESC}${visual.color}m${visual.glyph}${RESET} ${DIM}${label}${RESET}`).join('  ');
+/** One graph row mapped onto the display shape the nav helpers render. The wire
+ *  fault is asserted back to the row's branded type exactly as `withRowFault`
+ *  does for every other API-backed row; `api/` cannot express the branded
+ *  `operation_id`. */
+function graphRow(dto) {
+    return {
+        node_id: dto.node_id,
+        name: dto.name,
+        kind: dto.kind,
+        description: dto.description ?? undefined,
+        cycles: dto.cycles ?? undefined,
+        status: dto.status,
+        frozen_at: dto.frozen_at,
+        pi_pid: dto.pi_pid,
+        telemetry_context_tokens: dto.telemetry_context_tokens,
+        telemetry_last_activity: dto.telemetry_last_activity,
+        fault: (dto.fault ?? null),
+        streaming: dto.streaming,
+    };
+}
+export class GraphOverlay {
+    tui;
+    self;
+    getAsks;
+    palette;
+    bindings;
+    source;
+    role;
+    onRefreshFailure;
+    onNotice;
+    handle;
+    /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
+     *  both override the default activity-driven policy and survive open/close. */
+    userExpanded = new Set();
+    userCollapsed = new Set();
+    folds = { userExpanded: this.userExpanded, userCollapsed: this.userCollapsed };
+    /** Cursor as a node id (indices shift as topology changes). */
+    cursorId;
+    /** Viewport scroll offset (row index of the top visible tree row). */
+    scrollTop = 0;
+    /** Transient close confirmation gate. */
+    pendingConfirm;
+    snapshot;
+    snapshotSeq = 0;
+    /** True when `source` is a `RemoteCanvasSource` — gates every local disk/
+     *  SQLite adornment (tokens, activity, fault, attach, focus) to a safe
+     *  default and makes Enter/r/m/x no-op instead of shelling local lifecycle
+     *  commands against a remote graph row. See the file header. */
+    remote;
+    constructor(tui, self, getAsks, palette, bindings, source, role = 'controller', onRefreshFailure = () => { }, onNotice = () => { }) {
+        this.tui = tui;
+        this.self = self;
+        this.getAsks = getAsks;
+        this.palette = palette;
+        this.bindings = bindings;
+        this.source = source;
+        this.role = role;
+        this.onRefreshFailure = onRefreshFailure;
+        this.onNotice = onNotice;
+        this.remote = source instanceof RemoteCanvasSource;
+    }
+    setBindings(bindings) {
+        this.bindings = bindings;
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    hint(entries) {
+        return entries.flatMap(([id, label]) => this.bindings.gestures(id).length === 0 ? [] : [`${formatBinding(this.bindings, id)} ${label}`]);
+    }
+    /** Compose footer hints in priority order, dropping WHOLE entries that would
+     *  overflow `budget` visible columns rather than letting the border mid-clip
+     *  the tail — so the prioritized head (dismiss + remapped local actions) stays
+     *  discoverable even in a narrow overlay. */
+    fitHints(entries, budget) {
+        const SEP = 3; // visible width of ' · '
+        const out = [];
+        let used = 0;
+        for (const piece of this.hint(entries)) {
+            const add = (out.length === 0 ? 0 : SEP) + visibleWidth(piece);
+            if (used + add > budget)
+                break;
+            out.push(piece);
+            used += add;
+        }
+        return out.join(' · ');
+    }
+    isOpen() {
+        return this.handle !== undefined;
+    }
+    open() {
+        if (this.handle !== undefined)
+            return;
+        this.scrollTop = 0;
+        this.pendingConfirm = undefined;
+        // Open with the cursor on the CURRENT (attached) node every time, not wherever
+        // it was left on the last open — the overlay should always default to self.
+        this.cursorId = this.self;
+        this.handle = this.tui.showOverlay(this, OVERLAY_OPTIONS);
+        this.refresh();
+    }
+    close() {
+        if (this.handle === undefined)
+            return;
+        this.pendingConfirm = undefined;
+        this.handle.hide();
+        this.handle = undefined;
+        this.tui.requestRender();
+    }
+    toggle() {
+        if (this.handle === undefined)
+            this.open();
+        else
+            this.close();
+    }
+    /** Repaint if shown (the low-rate ask poll calls this). */
+    refresh() {
+        if (this.handle === undefined)
+            return;
+        const seq = ++this.snapshotSeq;
+        void this.buildSnapshot().then((snapshot) => {
+            if (seq !== this.snapshotSeq)
+                return;
+            this.snapshot = snapshot;
+            this.tui.requestRender();
+        }).catch((err) => {
+            // Preserve the last good snapshot. The attach process owns an alternate-
+            // screen TUI, so the parent reports this through its footer rather than
+            // writing raw stderr bytes into the frame.
+            this.onRefreshFailure(err);
+            this.tui.requestRender();
+        });
+    }
+    invalidate() {
+        this.refresh();
+    }
+    /** Local: ONE `/v1/canvas/graph` read supplies the display rows, both edge
+     *  directions, and the focus set — no enriched node list, no roster call, no
+     *  separate focus query. Remote: unchanged — a remote canvas exposes only the
+     *  per-node `CanvasSource` reads, and its focus set stays empty (a remote node
+     *  id may collide with a local focus row). */
+    async fetchInput() {
+        if (this.remote) {
+            const listed = await this.source.listNodes().catch(() => []);
+            return {
+                nodes: new Map(listed.map((node) => [node.node_id, node])),
+                subscriptions: async (id) => (await this.source.subscriptionsOf(id)).map((ref) => ref.node_id),
+                subscribers: async (id) => (await this.source.subscribersOf(id)).map((ref) => ref.node_id),
+                focused: new Set(),
+            };
+        }
+        const graph = await cliClient().canvasGraph();
+        const subscriptions = new Map();
+        const subscribers = new Map();
+        // Edges arrive in `created` order — the same order the per-node reads
+        // return — so the tree keeps its existing child and manager ordering.
+        for (const edge of graph.edges) {
+            const subs = subscriptions.get(edge.from_id);
+            if (subs === undefined)
+                subscriptions.set(edge.from_id, [edge.to_id]);
+            else
+                subs.push(edge.to_id);
+            const managers = subscribers.get(edge.to_id);
+            if (managers === undefined)
+                subscribers.set(edge.to_id, [edge.from_id]);
+            else
+                managers.push(edge.from_id);
+        }
+        return {
+            nodes: new Map(graph.nodes.map((node) => [node.node_id, graphRow(node)])),
+            subscriptions: (id) => Promise.resolve(subscriptions.get(id) ?? []),
+            subscribers: (id) => Promise.resolve(subscribers.get(id) ?? []),
+            focused: new Set(graph.focused_node_ids),
+        };
+    }
+    async buildSnapshot() {
+        const input = await this.fetchInput();
+        const { nodes, focused } = input;
+        const childIds = new Map();
+        const sortedChildIds = new Map();
+        const managerOf = new Map();
+        const activeBelow = new Map();
+        const children = async (id) => {
+            const hit = childIds.get(id);
+            if (hit !== undefined)
+                return hit;
+            let refs;
+            try {
+                refs = await input.subscriptions(id);
+            }
+            catch {
+                refs = [];
+            }
+            const out = refs.filter((childId) => nodes.get(childId)?.kind !== 'human');
+            childIds.set(id, out);
+            return out;
+        };
+        const manager = async (id) => {
+            if (managerOf.has(id))
+                return managerOf.get(id);
+            let mgr;
+            try {
+                mgr = (await input.subscribers(id))[0];
+            }
+            catch {
+                mgr = undefined;
+            }
+            managerOf.set(id, mgr);
+            return mgr;
+        };
+        const climbRoot = async () => {
+            let cur = this.self;
+            const seen = new Set([cur]);
+            for (;;) {
+                const mgr = await manager(cur);
+                if (mgr === undefined || seen.has(mgr))
+                    break;
+                seen.add(mgr);
+                cur = mgr;
+            }
+            return cur;
+        };
+        const sortedChildren = async (id) => {
+            const cached = sortedChildIds.get(id);
+            if (cached !== undefined)
+                return cached;
+            const ids = [...await children(id)];
+            ids.sort((a, b) => statusRank(nodes.get(a)?.status) - statusRank(nodes.get(b)?.status));
+            sortedChildIds.set(id, ids);
+            return ids;
+        };
+        const autoExpanded = new Set();
+        const seenActivity = new Set();
+        const visitActivity = async (id) => {
+            const selfActive = nodes.get(id)?.status === 'active';
+            if (seenActivity.has(id))
+                return { active: selfActive ? 1 : 0, reveal: selfActive || id === this.self };
+            seenActivity.add(id);
+            let below = 0;
+            let childReveal = false;
+            for (const childId of await children(id)) {
+                const result = await visitActivity(childId);
+                below += result.active;
+                if (result.reveal)
+                    childReveal = true;
+            }
+            activeBelow.set(id, below);
+            if (childReveal)
+                autoExpanded.add(id);
+            return { active: below + (selfActive ? 1 : 0), reveal: childReveal || selfActive || id === this.self };
+        };
+        const root = await climbRoot();
+        await visitActivity(root);
+        await Promise.all([...childIds.keys()].map((id) => sortedChildren(id)));
+        const snapshot = {
+            root,
+            rows: [],
+            autoExpanded,
+            activeBelow,
+            nodes,
+            childIds,
+            sortedChildIds,
+            managerOf,
+            focused,
+        };
+        snapshot.rows = this.projectRows(snapshot);
+        return snapshot;
+    }
+    /** Fold state is presentation-only. Reproject the visible DFS from the fully
+     * fetched topology so h/l never cross the daemon boundary. The explicit stack
+     * also keeps a deep graph from consuming the JavaScript call stack. */
+    projectRows(snapshot) {
+        const rows = [];
+        const visited = new Set();
+        const stack = [
+            { id: snapshot.root, prefix: '', isRoot: true, isLast: true },
+        ];
+        while (stack.length > 0) {
+            const { id, prefix, isRoot, isLast } = stack.pop();
+            const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+            if (visited.has(id)) {
+                rows.push({ id, hasKids: false, isSelf: id === this.self, branch: prefix + connector, cycle: true, collapsed: false });
+                continue;
+            }
+            visited.add(id);
+            const kids = snapshot.sortedChildIds.get(id) ?? [];
+            const folded = this.folds.userExpanded.has(id)
+                ? false
+                : this.folds.userCollapsed.has(id)
+                    ? true
+                    : !snapshot.autoExpanded.has(id);
+            rows.push({ id, hasKids: kids.length > 0, isSelf: id === this.self, branch: prefix + connector, cycle: false, collapsed: folded });
+            if (folded)
+                continue;
+            const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
+            for (let i = kids.length - 1; i >= 0; i--) {
+                stack.push({ id: kids[i], prefix: childPrefix, isRoot: false, isLast: i === kids.length - 1 });
+            }
+        }
+        return rows;
+    }
+    repaintFolds() {
+        if (this.snapshot !== undefined)
+            this.snapshot.rows = this.projectRows(this.snapshot);
+        this.tui.requestRender();
+    }
+    renderSnapshotRow(snapshot, r, isCursor, 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 = snapshot.nodes.get(r.id) ?? null;
+        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(node, this.remote)}${RESET}`;
+        const expandable = r.hasKids && r.collapsed;
+        const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
+        const cycle = cycleBadge(node);
+        const childCount = snapshot.childIds.get(r.id)?.length ?? 0;
+        const child = node !== null && childCount > 0 ? ` ${DIM}⤳${childCount}${RESET}` : '';
+        const below = node !== null && node.status !== 'active' && (snapshot.activeBelow.get(node.node_id) ?? 0) > 0
+            ? ` ${GREEN}⇣${snapshot.activeBelow.get(node.node_id) ?? 0}${RESET}`
+            : '';
+        // The fault rides on the row its owning daemon projected, so a remote node
+        // shows its own canvas's fault instead of a local-id collision.
+        const fault = node?.fault ?? null;
+        const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
+        const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycle}${child}${below}${askBadge(r.id, asks)}${activityCell(node, this.remote)}${faultSuffix}`;
+        return wrap(line, isAttached(r.id, node, snapshot.focused, this.remote));
+    }
+    render(width) {
+        const asks = this.getAsks();
+        const rows = this.snapshot?.rows ?? [];
+        // Re-resolve the cursor id → row (it may have vanished under a fold/close).
+        let cursorIdx = rows.findIndex((r) => r.id === this.cursorId);
+        if (cursorIdx < 0) {
+            cursorIdx = rows.findIndex((r) => r.id === this.self);
+            if (cursorIdx < 0)
+                cursorIdx = 0;
+        }
+        this.cursorId = rows[cursorIdx]?.id ?? this.self;
+        // Bounded panel budget (centered modal, not full-bleed): the box height
+        // shrinks to content but is capped at HEIGHT_PCT of the terminal — matching
+        // the overlay's maxHeight so our framed lines are never clipped. 2 rows go to
+        // the top/bottom border, the rest to the body — whose first row is the legend,
+        // so the tree viewport is one row shorter than the body budget.
+        const term = process.stdout.rows ?? VIEWPORT_FALLBACK_ROWS;
+        // Never exceed the overlay's own maxHeight (term-2 after the margin), so the
+        // bottom border is never slice-clipped even on a very short terminal.
+        const maxPanelH = Math.max(3, Math.min(Math.floor(term * HEIGHT_PCT), term - 2));
+        // The body holds the legend row plus every tree row, so size it for both;
+        // otherwise a graph that fits still loses a row to the legend and another to
+        // the "more" indicator.
+        const bodyArea = Math.min(maxPanelH - 2, 1 + Math.max(1, rows.length));
+        const treeArea = bodyArea - 1;
+        const showMore = treeArea >= 3;
+        // Track the cursor within treeArea, reserving ↑/↓ "more" indicators. Up to
+        // 4 passes converge the mutual dependency between window size and indicators
+        // (an indicator steals a tree row → can re-home scrollTop → toggles the other
+        // indicator); see canvas-nav.ts renderGraph for the rationale.
+        let viewportH = treeArea;
+        for (let pass = 0; treeArea > 0 && pass < 4; pass++) {
+            if (cursorIdx < this.scrollTop)
+                this.scrollTop = cursorIdx;
+            if (cursorIdx >= this.scrollTop + viewportH)
+                this.scrollTop = cursorIdx - viewportH + 1;
+            this.scrollTop = Math.max(0, Math.min(this.scrollTop, Math.max(0, rows.length - viewportH)));
+            const fit = treeArea - (showMore && this.scrollTop > 0 ? 1 : 0) - (showMore && this.scrollTop + viewportH < rows.length ? 1 : 0);
+            if (fit === viewportH)
+                break;
+            viewportH = Math.max(1, fit);
+        }
+        const end = Math.min(rows.length, this.scrollTop + viewportH);
+        const body = [];
+        if (showMore && this.scrollTop > 0)
+            body.push(`${DIM}  ↑ ${this.scrollTop} more${RESET}`);
+        for (let i = this.scrollTop; i < end; i++) {
+            const snapshot = this.snapshot;
+            body.push(snapshot !== undefined ? this.renderSnapshotRow(snapshot, rows[i], i === cursorIdx, asks) : '');
+        }
+        if (showMore && end < rows.length)
+            body.push(`${DIM}  ↓ ${rows.length - end} more${RESET}`);
+        body.unshift(LEGEND_ROW);
+        while (body.length < bodyArea)
+            body.push(''); // fill so the overlay is opaque
+        const title = rows.length > 0
+            ? `${BOLD}⌗ canvas graph${RESET} ${DIM}(${cursorIdx + 1}/${rows.length})${RESET}`
+            : `${BOLD}⌗ canvas graph${RESET} ${DIM}(loading)${RESET}`;
+        const hint = this.pendingConfirm !== undefined
+            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}${this.hint([
+                ['crtr.graph.confirm.accept', 'accept'],
+                ['crtr.graph.confirm.cancel', 'cancel'],
+            ]).join(' · ')}${RESET}`
+            : `${DIM}${this.fitHints([
+                ...(this.remote || this.role !== 'controller' ? GRAPH_PRIMARY_READ_ONLY_HINTS : GRAPH_PRIMARY_LOCAL_HINTS),
+                ...GRAPH_NAV_HINTS,
+            ], Math.max(1, width - 5))}${RESET}`; // budget matches borderRow's span
+        // Frame the panel: title in the top border, hint in the bottom border, tree
+        // rows boxed with themed side bars (truncate/pad to the inner width so the
+        // right edge stays flush and opaque).
+        const B = this.palette.border;
+        const innerW = Math.max(1, width - 4); // "│ " + content + " │"
+        // Hard-cut (empty ellipsis) + pad to innerW: ANSI-aware, so the cursor fill
+        // bar reaches the right border flush with no stray "…" and the box edge is
+        // opaque.
+        const boxed = body.map((line) => `${B('│')} ${truncateToWidth(line, innerW, '', true)} ${B('│')}`);
+        // Paint the WHOLE modal — border rows + boxed body + opaque space-fill — on
+        // the theme's distinct-surface background (selectedBg) so the float reads as
+        // a separate surface, not a hole in the viewer behind it (CTO ruling).
+        const S = this.palette.surface;
+        return [
+            this.borderRow('╭', '╮', title, width),
+            ...boxed,
+            this.borderRow('╰', '╯', hint, width),
+        ].map(S);
+    }
+    /** A top/bottom border row: `<lc>─ <label> ────<rc>`, frame in the theme border
+     *  color, the label keeping its own styling. The label is visible-truncated to
+     *  the available span so a long label (a narrow pane, or a long `kill <name>?`
+     *  confirm) never spills past the corner. */
+    borderRow(lc, rc, label, width) {
+        const B = this.palette.border;
+        const span = Math.max(1, width - 5); // lc ─ _ <span> _ ─… rc
+        const lbl = truncateToWidth(label, span, '…');
+        const fill = Math.max(0, width - 5 - visibleWidth(lbl));
+        return `${B(`${lc}─`)} ${lbl} ${B('─'.repeat(fill) + rc)}`;
+    }
+    handleInput(data) {
+        try {
+            this.dispatch(data);
+        }
+        catch {
+            /* a key handler is best-effort; never throw out of the input pump */
+        }
+    }
+    dispatch(data) {
+        // y/n confirm gate takes precedence over everything.
+        if (this.pendingConfirm !== undefined) {
+            if (this.matches('crtr.graph.confirm.accept', data)) {
+                const act = this.pendingConfirm.action;
+                this.pendingConfirm = undefined;
+                act();
+            }
+            else {
+                // Preserve GRAPH's modal fallback: any non-accept key cancels close.
+                this.pendingConfirm = undefined;
+            }
+            this.tui.requestRender();
+            return;
+        }
+        if (this.matches('crtr.graph.dismiss', data)) {
+            this.close();
+            return;
+        }
+        const snapshot = this.snapshot;
+        const rows = snapshot?.rows ?? [];
+        let idx = rows.findIndex((r) => r.id === this.cursorId);
+        if (idx < 0)
+            idx = Math.max(0, rows.findIndex((r) => r.id === this.self));
+        const cur = rows[idx];
+        // Cycle rows (↺ back-refs) carry the SAME id as the real node they echo, so a
+        // cursor landing on one resolves back to the earlier real row on the next
+        // findIndex — the cursor snaps up and can't pass the echo. They're non-
+        // actionable (focusing re-targets the real node you can already reach), so
+        // navigation skips them: the cursor only ever rests on a unique, real row.
+        const isSelectable = (r) => r !== undefined && !r.cycle;
+        const step = (from, dir) => {
+            for (let i = from + dir; i >= 0 && i < rows.length; i += dir) {
+                if (isSelectable(rows[i]))
+                    return i;
+            }
+            return from; // no selectable row that way — hold position
+        };
+        const edge = (dir) => {
+            const start = dir === 1 ? 0 : rows.length - 1;
+            for (let i = start; i >= 0 && i < rows.length; i += dir) {
+                if (isSelectable(rows[i]))
+                    return i;
+            }
+            return idx;
+        };
+        if (this.matches('crtr.graph.down', data)) {
+            idx = step(idx, 1);
+            this.cursorId = rows[idx]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (this.matches('crtr.graph.up', data)) {
+            idx = step(idx, -1);
+            this.cursorId = rows[idx]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (this.matches('crtr.graph.first', data)) {
+            this.cursorId = rows[edge(1)]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (this.matches('crtr.graph.last', data)) {
+            this.cursorId = rows[edge(-1)]?.id ?? this.cursorId;
+            this.tui.requestRender();
+            return;
+        }
+        if (this.matches('crtr.graph.collapse-or-manager', data)) {
+            if (cur !== undefined && cur.hasKids && !cur.collapsed) {
+                this.userCollapsed.add(cur.id);
+                this.userExpanded.delete(cur.id);
+                this.repaintFolds();
+            }
+            else {
+                const p = snapshot?.managerOf.get(this.cursorId ?? this.self);
+                if (p !== undefined && rows.some((r) => r.id === p))
+                    this.cursorId = p;
+                this.tui.requestRender();
+            }
+            return;
+        }
+        if (this.matches('crtr.graph.expand-or-child', data)) {
+            if (cur !== undefined && cur.collapsed && cur.hasKids) {
+                this.userExpanded.add(cur.id);
+                this.userCollapsed.delete(cur.id);
+                this.repaintFolds();
+            }
+            else if (cur !== undefined && cur.hasKids) {
+                const c = snapshot?.sortedChildIds.get(cur.id)?.[0];
+                if (c !== undefined)
+                    this.cursorId = c;
+                this.tui.requestRender();
+            }
+            return;
+        }
+        // Focus/revive/manager/close actions drive local lifecycle/focus (in-process focus /
+        // `crtr node lifecycle revive` / `crtr node lifecycle close`) against
+        // `this.cursorId`. A remote graph row has no relationship to this machine's
+        // canvas, and an observer is read-only, so neither may shell a local action.
+        if (this.matches('crtr.graph.focus', data)) {
+            if (this.remote)
+                return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot focus nodes');
+                return;
+            }
+            if (this.cursorId !== undefined)
+                this.focusTarget(this.cursorId);
+            this.close();
+            return;
+        }
+        if (this.matches('crtr.graph.revive', data)) {
+            if (this.remote)
+                return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot revive nodes');
+                return;
+            }
+            const target = this.cursorId;
+            const node = target === undefined ? null : snapshot?.nodes.get(target) ?? null;
+            if (target !== undefined && node !== null && node.status !== 'active' && node.status !== 'idle') {
+                this.reviveTarget(target);
+                this.close();
+            }
+            return;
+        }
+        if (this.matches('crtr.graph.focus-manager', data)) {
+            if (this.remote)
+                return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot focus nodes');
+                return;
+            }
+            const mgr = snapshot?.managerOf.get(this.self);
+            if (mgr !== undefined) {
+                this.focusTarget(mgr);
+                this.close();
+            }
+            return;
+        }
+        if (this.matches('crtr.graph.close-subtree', data)) {
+            if (this.remote)
+                return;
+            if (this.role !== 'controller') {
+                this.onNotice('Read-only observer attach — cannot close nodes');
+                return;
+            }
+            const target = this.cursorId ?? this.self;
+            const n = snapshot?.nodes.get(target) ?? null;
+            const nm = n !== null ? fullName(n) : shortId(target);
+            this.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'lifecycle', 'close', '--node', target]) };
+            this.tui.requestRender();
+            return;
+        }
+        // Modal: swallow everything else so a stray
+        // key never reaches the editor underneath.
+    }
+    /** Focus node `id` from the overlay, in-process: the same decision
+     *  `crtr surface node focus <id> --pane <here>` makes (core/runtime/focus-viewer.ts),
+     *  without paying a cold `crtr` boot before the target's viewer pane even
+     *  spawns. THIS pane is the ANCHOR: if `id` has no viewer yet a fresh one
+     *  splits beside it; if it already has one, that viewer is navigated in place
+     *  (this pane is left as-is). Finished work opens its saved-transcript popup. */
+    focusTarget(id) {
+        const pane = process.env['TMUX_PANE'];
+        if (pane === undefined || pane === '') {
+            this.onNotice('Focusing a node needs a local viewer in tmux');
+            return;
+        }
+        void (async () => {
+            const client = cliClient();
+            const node = await client.getNode(id);
+            const res = await focusNode(client, node, { pane });
+            if (!res.focused)
+                this.onNotice('Could not open that node’s viewer');
+        })().catch((error) => this.onNotice(daemonErrorMessage(error)));
+    }
+    /** Revive is deliberate and separate from Enter's inspect-or-focus behavior.
+     * After the broker reports ready, focus opens its live attach viewer. */
+    reviveTarget(id) {
+        this.shellCrtr(['node', 'lifecycle', 'revive', id], () => this.focusTarget(id));
+    }
+    shellCrtr(argv, after) {
+        try {
+            // execFile has no `stdio` option (it always pipes stdin) — end the
+            // child's stdin immediately so an inherited held-open pipe can never
+            // hang a future body-leaf invocation here (see readStdinRaw's
+            // contract in io.ts), the same non-hang guarantee pi bash tool and
+            // the bash valve supervisor get from an ignored stdin.
+            const child = execFile('crtr', argv, (err) => {
+                if (err == null)
+                    after?.();
+            });
+            child.stdin?.end();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}