@north-light/crouter 0.3.154

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

@@ -0,0 +1,916 @@
+// app.ts — the interactive `crtr canvas browse` runtime.
+//
+// Owns the browser state + the stdin keystroke loop. Pure logic lives in
+// model.ts (buildTree/flatten/fuzzyMatch) and render.ts (renderFrame); this file
+// wires the canvas data access in, holds mutable state, and translates keys.
+//
+// Resume is one action: Enter routes the chosen node through `crtr surface node focus`,
+// which goes via reviveNode() — the ONLY sanctioned open. NEVER spawn
+// `pi --session` directly (see reviveNode() in revive.ts for the desync hazard).
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render-source.js';
+import { RemoteCanvasSource } from '../remote-canvas-source.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
+import { buildTree, flatten, pruneNode, TABS } from './model.js';
+import { loadPins, savePins } from './pins.js';
+import { createCoalescedRebuilder } from './rebuild-coalescer.js';
+import { matchesTerminalInput, resolveUserKeybindings, } from '../../keybindings/index.js';
+const BROWSE_NAV_ACTIONS = [
+    'crtr.browse.quit', 'crtr.browse.down', 'crtr.browse.up', 'crtr.browse.first', 'crtr.browse.last',
+    'crtr.browse.expand-or-child', 'crtr.browse.collapse-or-parent', 'crtr.browse.toggle-fold',
+    'crtr.browse.tab-next', 'crtr.browse.tab-previous', 'crtr.browse.tab.1', 'crtr.browse.tab.2',
+    'crtr.browse.tab.3', 'crtr.browse.tab.4', 'crtr.browse.tab.5', 'crtr.browse.close-subtree', 'crtr.browse.sort',
+    'crtr.browse.scope', 'crtr.browse.profile', 'crtr.browse.residents', 'crtr.browse.preview', 'crtr.browse.search',
+    'crtr.browse.revive-now', 'crtr.browse.focus', 'crtr.browse.focus-background',
+];
+const BROWSE_SEARCH_ACTIONS = [
+    'crtr.browse.search.cancel', 'crtr.browse.search.commit', 'crtr.browse.search.delete',
+    'crtr.browse.search.quit',
+];
+function firstMatching(bindings, ids, raw) {
+    return ids.find((id) => matchesTerminalInput(bindings, id, raw)) ?? null;
+}
+export function resolveBrowseNavAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_NAV_ACTIONS, raw);
+}
+export function resolveBrowseSearchAction(bindings, raw) {
+    return firstMatching(bindings, BROWSE_SEARCH_ACTIONS, raw);
+}
+// Sort cycle for the `s` key. Starts on the default `attention` ordering; one `s`
+// press restores the structural `tree` view, then relevance/recency, then back.
+const SORT_CYCLE = ['attention', 'tree', 'relevance', 'recency'];
+import { renderFrame, detectColorCaps, headerHeight, PREVIEW_HEIGHT } from './render.js';
+/** Viewport (body) height = total rows minus the header renderFrame draws (see
+ *  render.ts headerHeight), the footer, and the preview panel when shown. Kept
+ *  in lockstep with render.ts via the shared headerHeight/PREVIEW_HEIGHT. */
+function viewportHeight(rowsTotal, inputLine, previewOn) {
+    const rows = Math.max(8, rowsTotal);
+    const previewH = previewOn ? PREVIEW_HEIGHT : 0;
+    return Math.max(1, rows - headerHeight(inputLine) - 1 /* footer */ - previewH);
+}
+/** Wires a RemoteEventStream's `nodes`/`inbox` events through the coalescer
+ *  (`rebuild-coalescer.ts`) so a burst of SSE events collapses to ONE rebuild
+ *  round, never one N+1 remote-subprocess rebuild per event. Exported (rather
+ *  than left inline in `runBrowse`) so the coalescer integration test can
+ *  drive this ACTUAL wiring, not just `createCoalescedRebuilder` in isolation
+ *  — the test asserts this function routes through the coalescer rather than
+ *  calling `rebuild()` directly per event. */
+export function wireEventStreamRebuild(eventStream, rebuild) {
+    const rebuilder = createCoalescedRebuilder(rebuild);
+    const unsubscribe = eventStream.subscribe(() => rebuilder.trigger());
+    eventStream.start();
+    return { rebuilder, unsubscribe };
+}
+export async function runBrowse(opts) {
+    const source = opts.source;
+    const isRemote = source instanceof RemoteCanvasSource;
+    const bindings = resolveUserKeybindings();
+    // No TTY → print the static forest and exit 0 (no raw mode).
+    if (!process.stdin.isTTY) {
+        process.stdout.write(await renderForestFromSource(source) + '\n');
+        return;
+    }
+    // Snapshot the canvas. Drop kind:'human' control-plane decks — they have no pi
+    // session, so `surface node focus` refuses them; they are never a navigation/resume
+    // target (mirrors the surface-node focus guard). Factored into a function so the SSE
+    // listener below can re-pull the tree on a `nodes`/`inbox` event instead of
+    // recomputing over a stale snapshot.
+    let rows;
+    let nodeRows;
+    let rootIds;
+    let childIds;
+    let tree;
+    let totalNodes;
+    // Remote-only: pending human-ticket counts per node, merged from one
+    // `ticketCountsForView` call per forest root (RemoteCanvasSource.ticketCountsForView
+    // already shells a single `canvas attention map --view <root>` per root, same
+    // cost class as the per-node `subscriptionsOf` fan-out this snapshot already
+    // does below) — fetched once per snapshot rebuild, not per flush/keystroke, so
+    // enrichRowsFromSource's per-row loop stays a pure sync-shaped map lookup.
+    let remoteAskCounts = {};
+    const rebuildSnapshot = async () => {
+        let viewedNodeIds = new Set();
+        if (!isRemote && opts.viewedNodeIds !== undefined) {
+            try {
+                viewedNodeIds = await opts.viewedNodeIds();
+            }
+            catch { /* best-effort viewer cue */ }
+        }
+        rows = (await dashboardRowsAllFromSource(source, viewedNodeIds)).filter((r) => r.kind !== 'human');
+        nodeRows = await source.listNodes();
+        rootIds = nodeRows
+            .filter((n) => n.parent === null && n.kind !== 'human')
+            .map((n) => n.node_id);
+        const nextChildIds = new Map();
+        await Promise.all(nodeRows.map(async (n) => {
+            nextChildIds.set(n.node_id, (await source.subscriptionsOf(n.node_id).catch(() => [])).map((s) => s.node_id));
+        }));
+        childIds = nextChildIds;
+        tree = buildTree(rows, rootIds, (id) => childIds.get(id) ?? []);
+        totalNodes = tree.nodes.size;
+        // Ask counts per node, merged from one `ticketCountsForView` call per root
+        // (covers the whole canvas — rootIds is every non-human root). Fetched for BOTH
+        // the local API source and a remote canvas, since neither can do a per-node
+        // openDb ticket scan; feeds enrichRowsFromSource's per-row map lookup.
+        const maps = await Promise.all(rootIds.map((root) => source.ticketCountsForView(root).catch(() => ({}))));
+        remoteAskCounts = Object.assign({}, ...maps);
+    };
+    await rebuildSnapshot();
+    // The launch dir is retained only as the optional cwd filter target. Browse opens
+    // canvas-wide; `c` narrows to this resolved directory.
+    const launchCwd = opts.cwd !== undefined && opts.cwd.trim() !== '' ? resolve(opts.cwd) : null;
+    // The launching node's selected profile is the initial scope. `P` can widen to
+    // every profile, then return here; a direct invocation with no profile starts
+    // canvas-wide because there is no truthful profile to select.
+    const launchProfileId = opts.profileId;
+    const state = {
+        tab: 'All',
+        cursor: 0,
+        // Initial collapse = every node with children → only roots/top-level show.
+        collapsed: new Set([...tree.nodes.entries()].filter(([, n]) => n.childIds.length > 0).map(([id]) => id)),
+        query: '',
+        search: false,
+        scrollOffset: 0,
+        cwdScope: null, // default: All dirs
+        profileScope: launchProfileId,
+        sort: 'attention', // default: attention ordering (attached/streaming/live first)
+        preview: true, // default ON (decision)
+        residentsOnly: true, // default ON: hide one-shot workers (decision)
+        pendingClose: null,
+        pinned: loadPins(),
+        help: false,
+        rename: false,
+        renameBuf: '',
+        renameTarget: null,
+        message: false,
+        messageBuf: '',
+        messageTarget: null,
+    };
+    let visible = [];
+    // The DashboardRow ref the tree holds for a visible id. Enrichment mutates this
+    // object in place, so a later renderFrame (reading off the same tree) re-renders
+    // the upgraded label/ctx/preview without a re-snapshot.
+    const rowOf = (id) => tree.nodes.get(id)?.row;
+    // Color capability is fixed for the session (it's a property of the tty/env).
+    const caps = detectColorCaps();
+    // Restore the terminal exactly once, however we leave (quit, resume, crash).
+    let restored = false;
+    const cleanup = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            restoreTerminal();
+        }
+        catch { /* best-effort */ }
+        unsubscribeEventStream?.();
+        rebuilder?.stop();
+        opts.eventStream?.stop();
+    };
+    // Safety net: an uncaught throw in the (un-unit-tested) keystroke path must
+    // never strand the tty in raw + alt-screen + hidden-cursor.
+    process.once('exit', cleanup);
+    // Remote-only live invalidation: `canvas browse` has no local fs-watch/poll to
+    // replace (there is none — this is a one-shot snapshot TUI, re-rendering only
+    // on keystrokes). This is net-new plumbing for the remote case only: when a
+    // pre-built RemoteEventStream is threaded in (canvas-browse.ts, once it has
+    // already resolved the target's credentials), a `nodes`/`inbox` SSE event
+    // invalidates the remote source's cache and triggers the same recompute +
+    // coalesced repaint a keystroke would. The local (no eventStream) path is
+    // untouched.
+    let unsubscribeEventStream;
+    let rebuilder;
+    if (opts.eventStream !== undefined) {
+        if (source instanceof RemoteCanvasSource)
+            source.invalidate();
+        // `trigger()` debounces a burst into one rebuild, and single-flights it
+        // against an already-in-flight rebuild — see wireEventStreamRebuild above.
+        const wired = wireEventStreamRebuild(opts.eventStream, async () => {
+            try {
+                if (source instanceof RemoteCanvasSource)
+                    source.invalidate();
+                await rebuildSnapshot();
+                recompute(curRow()?.id);
+                scheduleFlush();
+            }
+            catch (err) {
+                logAsyncFailure('SSE rebuild failed', err);
+            }
+        });
+        rebuilder = wired.rebuilder;
+        unsubscribeEventStream = wired.unsubscribe;
+    }
+    const logAsyncFailure = (label, err) => {
+        process.stderr.write(`[crtr browse] ${label}: ${String(err?.message ?? err)}\n`);
+    };
+    /** On-demand kick of a hanging node: shell `node lifecycle revive <id> --now`
+     *  (which SIGTERMs the live broker — the daemon resumes it). Synchronous +
+     *  quiet (stdio ignored) so it never takes over the TUI; best-effort. */
+    const reviveNow = (id) => {
+        try {
+            execFileSync('crtr', ['node', 'lifecycle', 'revive', id, '--now'], { stdio: 'ignore' });
+        }
+        catch {
+            /* best-effort — the SIGTERM is what matters; the daemon owns the resume */
+        }
+    };
+    /** Open the chosen node — the ONLY sanctioned path (reviveNode via surface node focus). */
+    const selectAndFocus = (id) => {
+        cleanup();
+        const args = ['surface', 'node', 'focus', id, ...(opts.returnPane !== undefined && opts.returnPane !== '' ? ['--pane', opts.returnPane] : [])];
+        try {
+            execFileSync('crtr', args, { stdio: 'inherit' });
+        }
+        catch {
+            // `surface node focus` swaps panes out from under us; a sync call can be
+            // interrupted. Best-effort — the swap is what matters.
+        }
+        process.exit(0);
+    };
+    /** Focus the chosen node WITHOUT leaving the navigator ("open in background"):
+     *  shell the same `surface node focus --pane` (still the ONLY sanctioned open), but keep
+     *  this browse popup running on top so several nodes can be resumed in a row. The
+     *  focus lands the viewer beside the originating pane BEHIND the popup; you see it
+     *  when you finally quit. Synchronous + quiet (stdio ignored — the popup owns the
+     *  screen, so `surface node focus` must not paint into it), mirroring reviveNow. */
+    const selectAndFocusKeepOpen = (id) => {
+        const args = ['surface', 'node', 'focus', id, ...(opts.returnPane !== undefined && opts.returnPane !== '' ? ['--pane', opts.returnPane] : [])];
+        try {
+            execFileSync('crtr', args, { stdio: 'ignore' });
+        }
+        catch {
+            /* best-effort — the focus is what matters; a failure never wedges the picker */
+        }
+    };
+    const recompute = (keepId) => {
+        visible = flatten(tree, {
+            collapsed: state.collapsed,
+            tab: state.tab,
+            query: state.query,
+            cwdScope: state.cwdScope,
+            profileScope: state.profileScope,
+            residentsOnly: state.residentsOnly,
+            sort: state.sort,
+            pinned: state.pinned,
+        });
+        if (keepId !== undefined) {
+            const idx = visible.findIndex((v) => v.id === keepId);
+            if (idx >= 0)
+                state.cursor = idx;
+        }
+        if (state.cursor > visible.length - 1)
+            state.cursor = Math.max(0, visible.length - 1);
+        if (state.cursor < 0)
+            state.cursor = 0;
+    };
+    const flush = async () => {
+        const size = getTerminalSize();
+        const previewOn = state.preview && visible.length > 0;
+        const inputMode = state.search || state.rename || state.message;
+        const viewport = viewportHeight(size.rows, inputMode, previewOn);
+        // Keep the cursor inside the viewport window.
+        if (state.cursor < state.scrollOffset)
+            state.scrollOffset = state.cursor;
+        if (state.cursor >= state.scrollOffset + viewport)
+            state.scrollOffset = state.cursor - viewport + 1;
+        if (state.scrollOffset < 0)
+            state.scrollOffset = 0;
+        // Lazy paint: enrich only the rows about to be drawn (full label + ctx + asks),
+        // and load the selected row's preview. Both are idempotent (guard-flagged), so
+        // calling them every flush is cheap once a row is warm.
+        const top = state.scrollOffset;
+        const bottom = Math.min(visible.length, top + viewport);
+        const slice = [];
+        for (let i = top; i < bottom; i++) {
+            const r = rowOf(visible[i].id);
+            if (r !== undefined)
+                slice.push(r);
+        }
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
+        const cur = curRow();
+        if (cur !== undefined) {
+            const r = rowOf(cur.id);
+            if (r !== undefined)
+                await loadPreviewFromSource(source, r);
+        }
+        const frame = renderFrame({
+            tree, visible, tab: state.tab, cursor: state.cursor, scrollOffset: state.scrollOffset,
+            query: state.query, search: state.search, totalNodes,
+            cwdScope: state.cwdScope, profileScope: state.profileScope, sort: state.sort, preview: state.preview,
+            residentsOnly: state.residentsOnly, pendingClose: state.pendingClose,
+            pinned: state.pinned, help: state.help,
+            rename: state.rename, renameBuf: state.renameBuf,
+            message: state.message, messageBuf: state.messageBuf,
+            readOnly: isRemote,
+        }, size, caps);
+        process.stdout.write(frame);
+    };
+    const quit = () => {
+        cleanup();
+        process.exit(0);
+    };
+    const curRow = () => visible[state.cursor];
+    const isExpanded = (id) => !state.collapsed.has(id);
+    // Every node in the snapshot subtree rooted at `id` (the node + all its tree
+    // descendants), used by the close-out streaming check.
+    const subtreeIds = (id) => {
+        const out = [];
+        const stack = [id];
+        const seen = new Set();
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            if (seen.has(cur))
+                continue;
+            seen.add(cur);
+            out.push(cur);
+            for (const c of tree.nodes.get(cur)?.childIds ?? [])
+                stack.push(c);
+        }
+        return out;
+    };
+    // Is the node, or any descendant, GENUINELY mid-turn right now (from the snapshot)?
+    const anyStreaming = (id) => subtreeIds(id).some((x) => tree.nodes.get(x)?.row.streaming === true);
+    // Close-out (`x`): finish the node to `done`, cascade-cancel its exclusive
+    // subtree, tear down each engine, and detach every attached viewer. Then reflect
+    // the new terminal statuses back into the live snapshot so the row updates in
+    // place (no re-snapshot). Best-effort: a teardown failure never wedges the picker.
+    const doClose = async (id) => {
+        state.pendingClose = null;
+        let closed = [];
+        try {
+            closed = (await opts.closeNode(id)).closed;
+        }
+        catch {
+            return; // unknown/already-gone node — nothing to reflect
+        }
+        for (const cid of closed) {
+            const m = await source.getNode(cid);
+            if (m === null) {
+                // Reaped, not parked: an EMPTY node (0k ctx, no assistant message) is
+                // hard-deleted by closeNode (row + dir gone). Splice it out of the tree so
+                // its row disappears — otherwise the stale active husk lingers on screen and
+                // `x` looks like a no-op (the row was the only thing that ever changed).
+                pruneNode(tree, cid);
+                continue;
+            }
+            const n = tree.nodes.get(cid);
+            if (n === undefined)
+                continue;
+            n.row.status = m.status; // real post-close status (done / canceled)
+            n.row.streaming = false;
+            n.row.viewed = false;
+            // A finalized node is no longer hanging and owes no answer — clear both so it
+            // actually LEAVES the Attention tab (asks>0 || hanging) and stops rendering the
+            // stale `⚠ down` rail. Without this, closing a faulted/asking node from the
+            // Attention tab looks like a no-op: the row was finalized in the db but its
+            // stale fault/ask kept it matching the tab, so it never disappeared.
+            n.row.hanging = null;
+            n.row.asks = 0;
+        }
+        // Keep the cursor at the same INDEX (the row that shifts up into the closed
+        // slot), not pinned to the now-gone node — recompute() leaves state.cursor
+        // put and clamps it to the new bounds.
+        recompute();
+    };
+    const cycleTab = (dir) => {
+        const i = TABS.indexOf(state.tab);
+        state.tab = TABS[(i + dir + TABS.length) % TABS.length];
+        state.cursor = 0;
+        state.scrollOffset = 0;
+        recompute();
+    };
+    // Cycle sort (attention → tree → relevance → recency → attention), keeping the
+    // selected node put. One `s` from the default `attention` lands on `tree`.
+    const cycleSort = () => {
+        const keep = curRow()?.id;
+        const i = SORT_CYCLE.indexOf(state.sort);
+        state.sort = SORT_CYCLE[(i + 1) % SORT_CYCLE.length];
+        recompute(keep);
+    };
+    // Toggle cwd scope between the launch dir and All dirs (no-op if launch dir
+    // is unknown — stays All dirs). Keeps the selected node put when still in view.
+    const toggleScope = () => {
+        const keep = curRow()?.id;
+        state.cwdScope = state.cwdScope === null ? launchCwd : null;
+        recompute(keep);
+    };
+    // Toggle profile scope between the launching profile and All profiles. A
+    // profileless front-door invocation has no selected profile, so `P` is a no-op.
+    const toggleProfile = () => {
+        if (launchProfileId === undefined)
+            return;
+        const keep = curRow()?.id;
+        state.profileScope = state.profileScope === undefined ? launchProfileId : undefined;
+        recompute(keep);
+    };
+    // Toggle the resident-only lifecycle filter (hide/show one-shot worker nodes),
+    // keeping the selected node put when it survives the toggle.
+    const toggleResidents = () => {
+        const keep = curRow()?.id;
+        state.residentsOnly = !state.residentsOnly;
+        recompute(keep);
+    };
+    // Coalesced search repaint. The expensive work per keystroke is recompute()
+    // (a fuzzyMatch flatten over the whole corpus) + a full renderFrame. Doing it
+    // synchronously on every key blocks the event loop, so fast typing batches into
+    // the stdin reads — and batched chunks used to be dropped (see onKeySearch).
+    // Instead, each key only mutates state.query (cheap) and marks the view dirty;
+    // a single setImmediate drains AFTER every queued stdin 'data' callback (poll
+    // phase) has appended its chars, so N rapid keys collapse to ONE recompute+paint
+    // and no keystroke is ignored. The sort may still take a moment — that's fine.
+    let searchRepaintScheduled = false;
+    let flushInFlight = false;
+    let flushQueued = false;
+    const scheduleFlush = () => {
+        flushQueued = true;
+        if (flushInFlight)
+            return;
+        flushInFlight = true;
+        void (async () => {
+            try {
+                while (flushQueued && !restored) {
+                    flushQueued = false;
+                    await flush();
+                }
+            }
+            finally {
+                flushInFlight = false;
+                if (flushQueued && !restored)
+                    scheduleFlush();
+            }
+        })().catch(() => {
+            cleanup();
+            process.exit(1);
+        });
+    };
+    const scheduleSearchRepaint = () => {
+        if (searchRepaintScheduled)
+            return;
+        searchRepaintScheduled = true;
+        setImmediate(() => {
+            searchRepaintScheduled = false;
+            recompute();
+            scheduleFlush();
+        });
+    };
+    const onKeySearch = (input, key) => {
+        const action = resolveBrowseSearchAction(bindings, { input, ...key });
+        if (action === 'crtr.browse.search.cancel') {
+            // Cancel the search: drop the query AND the relevance ranking it switched
+            // on, returning to the tree. Synchronous: we're leaving search mode.
+            state.search = false;
+            state.query = '';
+            state.sort = 'tree';
+            recompute();
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.search.commit') {
+            // Commit: keep the filter, drop search mode, land on the first match. Must
+            // recompute synchronously first so the match index reflects the final query
+            // even if a coalesced repaint is still pending.
+            state.search = false;
+            recompute();
+            const firstMatch = visible.findIndex((v) => v.matched);
+            if (firstMatch >= 0)
+                state.cursor = firstMatch;
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.search.delete') {
+            state.query = state.query.slice(0, -1);
+            scheduleSearchRepaint();
+            return;
+        }
+        // Bound quit acts before text capture; other ctrl-combos are swallowed.
+        if (action === 'crtr.browse.search.quit')
+            quit();
+        if (key.ctrl)
+            return;
+        // Append every printable char in the chunk. Fast typing batches multiple
+        // chars into one stdin read, so we must take them all (not just a length-1
+        // chunk) or keystrokes get dropped. Filtering to >= ' ' strips control/escape
+        // bytes (e.g. stray \x1b from an unrecognised sequence) but keeps real input,
+        // including multi-byte UTF-8 code points.
+        const printable = [...input].filter((c) => c >= ' ').join('');
+        if (printable.length > 0) {
+            state.query += printable;
+            scheduleSearchRepaint();
+        }
+    };
+    // Recenter the cursor on the launching node (CRTR_NODE_ID), expanding its
+    // ancestors so it is actually visible. No-op outside a node or when it's filtered
+    // out of the current tab/scope. Same move the boot performs, on demand (`.`).
+    const recenterOnSelf = () => {
+        const selfId = process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '' || !tree.nodes.has(selfId))
+            return;
+        for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
+            state.collapsed.delete(p);
+        }
+        recompute(selfId);
+    };
+    // Toggle the pin on a node: mutate the in-memory set, persist best-effort, and
+    // recompute so it floats (flat sorts) / (dis)appears from the Pinned tab.
+    const togglePin = (id) => {
+        if (state.pinned.has(id))
+            state.pinned.delete(id);
+        else
+            state.pinned.add(id);
+        savePins(state.pinned);
+        recompute(id);
+    };
+    // Commit an inline rename: `crtr node config <id> --name <name>` (also renames a
+    // live viewer window), then reflect the new name into the snapshot in place.
+    const commitRename = () => {
+        const id = state.renameTarget;
+        const name = state.renameBuf.trim();
+        state.rename = false;
+        if (id !== null && name !== '') {
+            try {
+                execFileSync('crtr', ['node', 'config', id, '--name', name], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — a rename failure never wedges the picker */
+            }
+            const n = tree.nodes.get(id);
+            if (n !== undefined)
+                n.row.name = name;
+        }
+        recompute(state.renameTarget ?? undefined);
+        scheduleFlush();
+    };
+    // Commit an inline message: `crtr node message send --to <id> <body>` (immediate
+    // inbox delivery, best-effort revive if dormant). Fire-and-forget — browse stays put.
+    const commitMessage = () => {
+        const id = state.messageTarget;
+        const body = state.messageBuf.trim();
+        state.message = false;
+        if (id !== null && body !== '') {
+            try {
+                execFileSync('crtr', ['node', 'message', 'send', '--to', id, body], { stdio: 'ignore' });
+            }
+            catch {
+                /* best-effort — delivery failure never wedges the picker */
+            }
+        }
+        scheduleFlush();
+    };
+    // Shared text-input keystroke handling for the rename/message sub-modes: Esc
+    // cancels, Enter commits, Backspace deletes, Ctrl+C quits, printable chars append.
+    const onKeyText = (input, key, get, set, commit, cancel) => {
+        if (key.escape) {
+            cancel();
+            return;
+        }
+        if (key.return) {
+            commit();
+            return;
+        }
+        if (key.backspace) {
+            set(get().slice(0, -1));
+            scheduleFlush();
+            return;
+        }
+        if (key.ctrl) {
+            if (input === 'c')
+                quit();
+            return;
+        }
+        const printable = [...input].filter((c) => c >= ' ').join('');
+        if (printable.length > 0) {
+            set(get() + printable);
+            scheduleFlush();
+        }
+    };
+    const onKeyRename = (input, key) => onKeyText(input, key, () => state.renameBuf, (s) => { state.renameBuf = s; }, commitRename, () => { state.rename = false; scheduleFlush(); });
+    const onKeyMessage = (input, key) => onKeyText(input, key, () => state.messageBuf, (s) => { state.messageBuf = s; }, commitMessage, () => { state.message = false; scheduleFlush(); });
+    // Help overlay: any key dismisses (Ctrl+C still quits outright).
+    const onKeyHelp = (input, key) => {
+        if (key.ctrl && input === 'c') {
+            quit();
+            return;
+        }
+        state.help = false;
+        scheduleFlush();
+    };
+    const onKeyNav = (input, key) => {
+        const raw = { input, ...key };
+        const action = resolveBrowseNavAction(bindings, raw);
+        // Unbound ctrl-combos are swallowed so they never masquerade as printable commands.
+        if (key.ctrl && action === null)
+            return;
+        // Preserve an explicitly bound control-combo quit while the close confirmation is open.
+        // Other non-confirming input dismisses the modal without also running navigation actions.
+        if (state.pendingClose !== null && action === 'crtr.browse.quit' && key.ctrl)
+            quit();
+        if (state.pendingClose !== null) {
+            if (matchesTerminalInput(bindings, 'crtr.browse.confirm-close', raw)) {
+                const target = state.pendingClose;
+                void doClose(target).then(() => scheduleFlush()).catch(() => scheduleFlush());
+                return;
+            }
+            // n / Esc / anything else cancels the close.
+            state.pendingClose = null;
+            scheduleFlush();
+            return;
+        }
+        const row = curRow();
+        // Quit and move.
+        if (action === 'crtr.browse.quit')
+            quit();
+        if (action === 'crtr.browse.up') {
+            state.cursor = Math.max(0, state.cursor - 1);
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.down') {
+            state.cursor = Math.max(0, Math.min(visible.length - 1, state.cursor + 1));
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.first') {
+            state.cursor = 0;
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.last') {
+            state.cursor = Math.max(0, visible.length - 1);
+            scheduleFlush();
+            return;
+        }
+        // Expand / descend.
+        if (action === 'crtr.browse.expand-or-child') {
+            if (row !== undefined && row.hasChildren) {
+                if (!isExpanded(row.id)) {
+                    state.collapsed.delete(row.id);
+                    recompute(row.id);
+                }
+                else if (state.cursor + 1 < visible.length && visible[state.cursor + 1].depth > row.depth) {
+                    state.cursor += 1; // already expanded → step onto first child
+                }
+            }
+            scheduleFlush();
+            return;
+        }
+        // Collapse / ascend.
+        if (action === 'crtr.browse.collapse-or-parent') {
+            if (row !== undefined && row.hasChildren && isExpanded(row.id)) {
+                state.collapsed.add(row.id);
+                recompute(row.id);
+            }
+            else if (row !== undefined) {
+                const parentId = tree.nodes.get(row.id)?.parentId ?? null;
+                if (parentId !== null) {
+                    const idx = visible.findIndex((v) => v.id === parentId);
+                    if (idx >= 0)
+                        state.cursor = idx;
+                }
+            }
+            scheduleFlush();
+            return;
+        }
+        // Toggle collapse.
+        if (action === 'crtr.browse.toggle-fold') {
+            if (row !== undefined && row.hasChildren) {
+                if (isExpanded(row.id))
+                    state.collapsed.add(row.id);
+                else
+                    state.collapsed.delete(row.id);
+                recompute(row.id);
+            }
+            scheduleFlush();
+            return;
+        }
+        // Tabs. next/previous and tab.1–5 (including Pinned) all resolve through the
+        // catalog, so each numbered tab is user-remappable like any other binding.
+        if (action === 'crtr.browse.tab-next') {
+            cycleTab(1);
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.tab-previous') {
+            cycleTab(-1);
+            scheduleFlush();
+            return;
+        }
+        if (action?.startsWith('crtr.browse.tab.')) {
+            const idx = Number(action.slice(-1)) - 1;
+            if (idx < TABS.length) {
+                state.tab = TABS[idx];
+                state.cursor = 0;
+                state.scrollOffset = 0;
+                recompute();
+            }
+            scheduleFlush();
+            return;
+        }
+        // Close-out the selected node (+ its exclusive subtree). If anything in that
+        // subtree is actively streaming, confirm first (y/n); otherwise close at once.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
+        if (action === 'crtr.browse.close-subtree') {
+            if (isRemote)
+                return;
+            if (row === undefined) {
+                scheduleFlush();
+                return;
+            }
+            if (anyStreaming(row.id)) {
+                state.pendingClose = row.id;
+                scheduleFlush();
+                return;
+            }
+            void doClose(row.id).then(() => scheduleFlush()).catch(() => scheduleFlush());
+            return;
+        }
+        // Sort / scope / residents / preview.
+        if (action === 'crtr.browse.sort') {
+            cycleSort();
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.scope') {
+            toggleScope();
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.profile') {
+            toggleProfile();
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.residents') {
+            toggleResidents();
+            scheduleFlush();
+            return;
+        }
+        if (action === 'crtr.browse.preview') {
+            state.preview = !state.preview;
+            scheduleFlush();
+            return;
+        }
+        // Help overlay.
+        if (input === '?') {
+            state.help = true;
+            scheduleFlush();
+            return;
+        }
+        // Pin / unpin (local, view-only — works against a remote canvas too).
+        if (input === 'f') {
+            if (row !== undefined)
+                togglePin(row.id);
+            scheduleFlush();
+            return;
+        }
+        // Recenter on the launching node.
+        if (input === '.') {
+            recenterOnSelf();
+            scheduleFlush();
+            return;
+        }
+        // Rename the node inline (mutation — no-op on a remote canvas).
+        if (input === 'R') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.rename = true;
+                state.renameTarget = row.id;
+                state.renameBuf = rowOf(row.id)?.name ?? '';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Message the node without resuming it (mutation — no-op on a remote canvas).
+        if (input === 'm') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                state.message = true;
+                state.messageTarget = row.id;
+                state.messageBuf = '';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Search. Starting a search ranks by relevance (decision) so the best prompt/
+        // name match floats to the top as you type.
+        if (action === 'crtr.browse.search') {
+            state.search = true;
+            state.query = '';
+            state.sort = 'relevance';
+            state.cursor = 0;
+            state.scrollOffset = 0;
+            recompute();
+            scheduleFlush();
+            return;
+        }
+        // Revive now (on-demand kick): for a HANGING node, SIGTERM the live broker so
+        // the daemon's crash→grace→resume path brings it back in ~20s instead of
+        // waiting out the 5-min auto-revive grace. Shells `node lifecycle revive <id>
+        // --now` (browse goes through commands, never touching the runtime directly). 'k' is
+        // vim-up here, so the kick is on SHIFT-K.
+        // No-op against a remote canvas — mutations are disabled (footer says so).
+        if (action === 'crtr.browse.revive-now') {
+            if (isRemote)
+                return;
+            if (row !== undefined) {
+                const r = rowOf(row.id);
+                if (r?.hanging != null)
+                    reviveNow(row.id);
+            }
+            scheduleFlush();
+            return;
+        }
+        // Resume. No-op against a remote canvas — mutations/focus are disabled
+        // (footer says so).
+        if (action === 'crtr.browse.focus') {
+            if (isRemote)
+                return;
+            if (row !== undefined)
+                selectAndFocus(row.id);
+            return;
+        }
+        // Resume in the BACKGROUND (Shift+O): focus the node into the pane behind this
+        // popup but keep the navigator open so you can resume more nodes. Same remote
+        // guard as plain focus.
+        if (action === 'crtr.browse.focus-background') {
+            if (isRemote)
+                return;
+            if (row !== undefined)
+                selectAndFocusKeepOpen(row.id);
+            scheduleFlush();
+            return;
+        }
+    };
+    // Boot. Profile scope is deliberately retained even when it has no rows: this
+    // page opens within the launching identity by default. Relax only the secondary
+    // resident-only filter so a profile's one-shot workers remain reachable.
+    recompute();
+    if (visible.length === 0 && state.residentsOnly) {
+        state.residentsOnly = false;
+        recompute();
+    }
+    // Open with the cursor on the CURRENT node (the one browse was launched from),
+    // not the top of the tree. Expand its ancestors so the row is actually visible,
+    // then home the cursor onto it. No-op when launched outside a node, or when the
+    // node is filtered out of the current tab/scope.
+    const selfId = process.env['CRTR_NODE_ID'];
+    if (selfId !== undefined && selfId !== '' && tree.nodes.has(selfId)) {
+        for (let p = tree.nodes.get(selfId)?.parentId ?? null; p !== null; p = tree.nodes.get(p)?.parentId ?? null) {
+            state.collapsed.delete(p);
+        }
+        recompute(selfId);
+    }
+    setupTerminal();
+    await flush();
+    // Background corpus warmer: after the instant first paint, progressively enrich
+    // + load-preview every row (in small chunks, off the event loop) so the prompt
+    // super-search corpus lights up shortly after the instant name/kind/id search.
+    // Mutates row objects only; re-flushes solely while a live search is open so new
+    // matches surface. Stops as soon as the terminal is restored (quit/resume/crash).
+    const warmRows = [...tree.nodes.values()].map((n) => n.row);
+    let warmIdx = 0;
+    const WARM_CHUNK = 30;
+    const warmChunk = async () => {
+        if (restored)
+            return;
+        const end = Math.min(warmIdx + WARM_CHUNK, warmRows.length);
+        const slice = warmRows.slice(warmIdx, end);
+        await enrichRowsFromSource(source, slice, remoteAskCounts);
+        await Promise.all(slice.map((r) => loadPreviewFromSource(source, r)));
+        warmIdx = end;
+        // A live search may match the freshly-warmed prompts → recompute + repaint.
+        if (state.search && state.query !== '') {
+            recompute(curRow()?.id);
+            scheduleFlush();
+        }
+        if (warmIdx < warmRows.length)
+            setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
+    };
+    setImmediate(() => { void warmChunk().catch((err) => logAsyncFailure('background warm failed', err)); });
+    await new Promise(() => {
+        const onData = (data) => {
+            try {
+                const { input, key } = parseKeypress(data);
+                if (state.help)
+                    onKeyHelp(input, key);
+                else if (state.search)
+                    onKeySearch(input, key);
+                else if (state.rename)
+                    onKeyRename(input, key);
+                else if (state.message)
+                    onKeyMessage(input, key);
+                else
+                    onKeyNav(input, key);
+            }
+            catch {
+                // Never let a keystroke crash leave the tty wedged.
+                cleanup();
+                process.exit(1);
+            }
+        };
+        process.stdin.on('data', onData);
+        process.stdout.on('resize', scheduleFlush);
+    });
+}