@north-light/crouter 0.3.154

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

@@ -0,0 +1,657 @@
+// 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/r/m/x SHELL `crtr` out-of-process (surface node focus / revive / close) — the viewer
+// itself never spawns pi or opens a session (the §0 one-writer invariant). It
+// passes its own pane as `crtr surface node focus --pane <anchor>`: 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, activeFaultForDisplay from
+// render-source.js, all render/telemetry helpers from nav-render.js. The
+// tmux-focus set (formerly nav-model's focusedNodeIds → listFocuses db read) is
+// fetched through the crtrd API (cliClient().listFocuses) so this viewer stays
+// off the canvas-db.
+import { fullName } from '../../../core/canvas/labels.js';
+import { activeFaultForDisplay } from '../../../core/canvas/render-source.js';
+import { readFault } from '../../../core/runtime/fault.js';
+import { faultSummary } from '../../../core/canvas/status-glyph.js';
+import { RemoteCanvasSource } from '../../../core/canvas/remote-canvas-source.js';
+import { cliClient } from '../../../commands/api-client.js';
+import { beginFrameTelem, navLabel, nodeGlyph, tokensCell, cycleBadge, askBadge, activityCell, shortId, visibleWidth, fillBar, fillWidth, truncate, isAttached, VIEWPORT_FALLBACK_ROWS, 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'],
+];
+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;
+    }
+    /** The tmux-focus set for `isAttached`, fetched via crtrd (was nav-model's
+     *  focusedNodeIds → listFocuses db read). Empty for a remote source (a remote
+     *  node id may collide with a local focus row); a failed API call degrades to
+     *  empty rather than throwing the whole snapshot. */
+    async fetchFocused() {
+        if (this.remote)
+            return new Set();
+        try {
+            return new Set((await cliClient().listFocuses()).map((f) => f.node_id));
+        }
+        catch {
+            return new Set();
+        }
+    }
+    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();
+    }
+    // -------------------------------------------------------------------------
+    async buildSnapshot() {
+        beginFrameTelem();
+        const nodes = new Map();
+        const childIds = new Map();
+        const sortedChildIds = new Map();
+        const managerOf = new Map();
+        const activeBelow = new Map();
+        const node = async (id) => {
+            if (nodes.has(id))
+                return nodes.get(id) ?? null;
+            let v;
+            try {
+                v = await this.source.getNode(id);
+            }
+            catch {
+                v = null;
+            }
+            nodes.set(id, v);
+            return v;
+        };
+        const children = async (id) => {
+            const hit = childIds.get(id);
+            if (hit !== undefined)
+                return hit;
+            let refs;
+            try {
+                refs = await this.source.subscriptionsOf(id);
+            }
+            catch {
+                refs = [];
+            }
+            const out = [];
+            for (const ref of refs) {
+                if ((await node(ref.node_id))?.kind !== 'human')
+                    out.push(ref.node_id);
+            }
+            childIds.set(id, out);
+            return out;
+        };
+        const manager = async (id) => {
+            if (managerOf.has(id))
+                return managerOf.get(id);
+            let mgr;
+            try {
+                mgr = (await this.source.subscribersOf(id))[0]?.node_id;
+            }
+            catch {
+                mgr = undefined;
+            }
+            managerOf.set(id, mgr);
+            return mgr;
+        };
+        const climbRoot = async (self) => {
+            let cur = 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 rank = async (id) => {
+            switch ((await node(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;
+            }
+        };
+        const sortedChildren = async (id) => {
+            const cached = sortedChildIds.get(id);
+            if (cached !== undefined)
+                return cached;
+            const ids = [...await children(id)];
+            const ranks = new Map();
+            await Promise.all(ids.map(async (cid) => { ranks.set(cid, await rank(cid)); }));
+            ids.sort((a, b) => (ranks.get(a) ?? 99) - (ranks.get(b) ?? 99));
+            sortedChildIds.set(id, ids);
+            return ids;
+        };
+        const expand = new Set();
+        const seenActivity = new Set();
+        const visitActivity = async (id) => {
+            const selfActive = (await node(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 c of await children(id)) {
+                const r = await visitActivity(c);
+                below += r.active;
+                if (r.reveal)
+                    childReveal = true;
+            }
+            activeBelow.set(id, below);
+            if (childReveal)
+                expand.add(id);
+            return { active: below + (selfActive ? 1 : 0), reveal: childReveal || selfActive || id === this.self };
+        };
+        await visitActivity(await climbRoot(this.self));
+        const rows = [];
+        const visited = new Set();
+        const walk = async (id, prefix, isRoot, isLast) => {
+            if (visited.has(id)) {
+                const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+                rows.push({ id, hasKids: false, isSelf: id === this.self, branch: prefix + connector, cycle: true, collapsed: false });
+                return;
+            }
+            visited.add(id);
+            const kids = await sortedChildren(id);
+            const folded = this.folds.userExpanded.has(id) ? false : this.folds.userCollapsed.has(id) ? true : !expand.has(id);
+            const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+            rows.push({ id, hasKids: kids.length > 0, isSelf: id === this.self, branch: prefix + connector, cycle: false, collapsed: folded });
+            if (folded)
+                return;
+            const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
+            for (let i = 0; i < kids.length; i++)
+                await walk(kids[i], childPrefix, false, i === kids.length - 1);
+        };
+        await walk(await climbRoot(this.self), '', true, true);
+        return { rows, activeBelow, nodes, childIds, sortedChildIds, managerOf, focused: await this.fetchFocused() };
+    }
+    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, this.remote);
+        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, 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}`
+            : '';
+        // A remote fault is a local disk read (readFault) keyed on a node id that
+        // may collide with a local one — skip it entirely rather than read-then-
+        // discard.
+        const fault = node !== null && !this.remote ? activeFaultForDisplay(node, readFault(r.id)) : null;
+        const faultSuffix = fault !== null ? ` · ${faultSummary(fault)}` : '';
+        const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${cycle}${child}${below}${askBadge(r.id, asks)}${activityCell(r.id, node, this.remote)}${faultSuffix}`;
+        return wrap(line, isAttached(r.id, node, snapshot.focused, this.remote));
+    }
+    render(width) {
+        beginFrameTelem();
+        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 tree rows.
+        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));
+        const treeArea = Math.max(2, Math.min(rows.length, maxPanelH - 2));
+        // 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; 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 - (this.scrollTop > 0 ? 1 : 0) - (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 (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 (end < rows.length)
+            body.push(`${DIM}  ↓ ${rows.length - end} more${RESET}`);
+        while (body.length < treeArea)
+            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.refresh();
+            }
+            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.refresh();
+            }
+            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 (`crtr surface node 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 by shelling `crtr surface node focus <id> --pane <here>`.
+     *  Under the one-viewer-per-node model `--pane` is the ANCHOR to open beside: if
+     *  `id` has no viewer yet a fresh one splits beside this pane; if it already has
+     *  one, that viewer is navigated in place (this pane is left as-is). We pass
+     *  TMUX_PANE explicitly so the anchor is THIS pane even if env resolution differs. */
+    focusTarget(id) {
+        const argv = ['surface', 'node', 'focus', id];
+        const pane = process.env['TMUX_PANE'];
+        if (pane !== undefined && pane !== '')
+            argv.push('--pane', pane);
+        this.shellCrtr(argv);
+    }
+    /** 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 */
+        }
+    }
+}