@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,1050 @@
+// 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 { envNodeId } from '../../../shared/env.js';
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, loadSearchTextFromSource, renderForestFromSource } from '../render-source.js';
+import { fullName } from '../labels.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
+import { buildTree, flatten, pruneNode, scoreRow, TABS } from './model.js';
+import { loadPins, savePins } from './pins.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.report', 'crtr.browse.pin', 'crtr.browse.search',
+    'crtr.browse.revive-now', 'crtr.browse.focus', 'crtr.browse.focus-background', 'crtr.browse.yank-id',
+];
+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, previewLayout, PREVIEW_HEIGHT } from './render.js';
+import { writeClipboardTextEverywhere } from '../../clipboard-text.js';
+/** Viewport (body) height = total rows minus the header renderFrame draws (see
+ *  render.ts headerHeight), the footer, and the BOTTOM preview panel when that is
+ *  the layout in play. The side preview column costs columns, not rows, so it does
+ *  not shrink the viewport. Kept in lockstep with render.ts via the shared
+ *  headerHeight/previewLayout/PREVIEW_HEIGHT. */
+function viewportHeight(size, inputLine, previewOn) {
+    const rows = Math.max(8, size.rows);
+    const previewH = previewLayout(size.cols, previewOn).mode === 'bottom' ? PREVIEW_HEIGHT : 0;
+    return Math.max(1, rows - headerHeight(inputLine) - 1 /* footer */ - previewH);
+}
+export async function runBrowse(opts) {
+    const source = opts.source;
+    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 pages — they have no pi
+    // session, so `surface node focus` refuses them; they are never a navigation/resume
+    // target (mirrors the surface-node focus guard).
+    let rows;
+    let nodeRows;
+    let rootIds;
+    let childIds;
+    let tree;
+    let totalNodes;
+    // Fetch pending ticket counts once per snapshot, not per flush or keystroke.
+    let askCounts = {};
+    const rebuildSnapshot = async () => {
+        let viewedNodeIds = new Set();
+        if (opts.viewedNodeIds !== undefined) {
+            try {
+                viewedNodeIds = await opts.viewedNodeIds();
+            }
+            catch { /* best-effort viewer cue */ }
+        }
+        nodeRows = await (source.browseSnapshot?.() ?? source.listNodes());
+        rows = (await dashboardRowsAllFromSource(source, viewedNodeIds, false, nodeRows)).filter((r) => r.kind !== 'human');
+        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;
+        // Counts for the union of every non-human root's view, in ONE request — the
+        // exact id set the per-root `ticketCountsForView` calls covered (`view()` is an
+        // in-memory BFS over the cached roster, not a fan-out). Deliberately NOT
+        // `nodeRows`: a row whose parent is set but which no root's view reaches is
+        // still drawn, as a disconnected subtree, and counting it would badge rows this
+        // page has always left unbadged.
+        askCounts = await Promise.all(rootIds.map(async (root) => [root, ...await source.view(root)]))
+            .then((views) => source.ticketCountsForNodes([...new Set(views.flat())]))
+            .catch(() => ({}));
+    };
+    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 = {
+        // Open on Live (active|idle): the navigator's job is getting you back to a
+        // node you are working with, and All buries those under every dormant row.
+        tab: 'Live',
+        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 — the hovered node's conversation is the point
+        showReport: false,
+        residentsOnly: true, // default ON: hide one-shot workers (decision)
+        pendingClose: null,
+        flash: null,
+        pinned: loadPins(),
+        help: false,
+        rename: false,
+        renameBuf: '',
+        renameTarget: null,
+        message: false,
+        messageBuf: '',
+        messageTarget: null,
+    };
+    let visible = [];
+    // Conversation-content search (`/`): node id → best matching snippet for the
+    // query the last completed request ran. Local daemon only.
+    let contentHits = new Map();
+    let contentSearching = false;
+    let contentTimer;
+    let contentInFlight = false;
+    const CONTENT_DEBOUNCE_MS = 300;
+    const CONTENT_MIN_CHARS = 3;
+    const clearContentSearch = () => {
+        if (contentTimer !== undefined)
+            clearTimeout(contentTimer);
+        contentTimer = undefined;
+        contentHits = new Map();
+    };
+    /** Run one content search for the current query over the ids that pass the tab,
+     *  profile, cwd and residents filters with the query ignored. At most one request
+     *  is in flight; a result for a query that has since changed is dropped and the
+     *  newest query is sent. */
+    const runContentSearch = async () => {
+        if (contentInFlight || !state.search)
+            return;
+        const query = state.query.trim();
+        if (query.length < CONTENT_MIN_CHARS)
+            return;
+        const scope = flatten(tree, {
+            collapsed: state.collapsed, tab: state.tab, query: '', cwdScope: state.cwdScope,
+            profileScope: state.profileScope, residentsOnly: state.residentsOnly, sort: 'recency', pinned: state.pinned,
+        }).map((v) => v.id);
+        if (scope.length === 0) {
+            contentHits = new Map();
+            recompute();
+            scheduleFlush();
+            return;
+        }
+        contentInFlight = true;
+        contentSearching = true;
+        scheduleFlush();
+        let hits;
+        let failure;
+        try {
+            const res = await opts.contentSearch({ query, nodes: scope, types: ['transcript'], weigh_body: true, per_node: true });
+            hits = new Map();
+            for (const h of res.hits) {
+                const id = h['node_id'];
+                const snip = h['snippet'];
+                if (typeof id === 'string' && typeof snip === 'string')
+                    hits.set(id, snip);
+            }
+        }
+        catch (err) {
+            failure = `conversation search failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        contentInFlight = false;
+        contentSearching = false;
+        if (restored)
+            return;
+        if (state.query.trim() !== query) {
+            // Stale: the query moved on while this ran. Send the newest one.
+            if (state.search)
+                void runContentSearch();
+            return;
+        }
+        if (hits !== undefined) {
+            contentHits = hits;
+        }
+        else {
+            state.flash = failure ?? null;
+        }
+        recompute();
+        scheduleFlush();
+    };
+    const scheduleContentSearch = () => {
+        if (contentTimer !== undefined)
+            clearTimeout(contentTimer);
+        contentTimer = undefined;
+        if (state.query.trim().length < CONTENT_MIN_CHARS) {
+            contentHits = new Map();
+            return;
+        }
+        contentTimer = setTimeout(() => { contentTimer = undefined; void runContentSearch(); }, CONTENT_DEBOUNCE_MS);
+    };
+    // 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 */ }
+    };
+    // 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);
+    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).
+     *  With a return pane (the `/resume` popup), the chosen node REPLACES that pane:
+     *  `--in-place` respawns it onto the node, so resuming swaps the viewer you came
+     *  from instead of splitting another one beside it. The respawn kills that pane's
+     *  process tree, so it is dispatched through `tmux run-shell -b` — the tmux server
+     *  context — and never as a child of this popup, which the same teardown can take
+     *  with it mid-call. Without a return pane, the caller's own pane hosts the viewer
+     *  as before. */
+    const selectAndFocus = (id) => {
+        cleanup();
+        const returnPane = opts.returnPane !== undefined && opts.returnPane !== '' ? opts.returnPane : undefined;
+        try {
+            if (returnPane !== undefined) {
+                execFileSync('tmux', ['run-shell', '-b', `crtr surface node focus ${id} --pane ${returnPane} --in-place >/dev/null 2>&1`], { stdio: 'ignore' });
+            }
+            else {
+                execFileSync('crtr', ['surface', 'node', 'focus', id], { 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,
+            contentHits,
+        });
+        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;
+    };
+    /** The content-search snippet for the selected row, only when the row matched on
+     *  content alone (no name/prompt tier match to show instead). */
+    const selectedContentSnippet = () => {
+        if (state.query === '')
+            return undefined;
+        const sel = visible[state.cursor];
+        const snip = sel === undefined ? undefined : contentHits.get(sel.id);
+        const row = sel === undefined ? undefined : rowOf(sel.id);
+        if (snip === undefined || row === undefined || scoreRow(state.query, row).tier > 0)
+            return undefined;
+        return snip;
+    };
+    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, 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 (asks). The selected row's
+        // preview is NOT read here — the frame paints at once with whatever that row
+        // already holds ("loading…" until then), and schedulePreview reads it off the
+        // paint path once the cursor settles. Reading it inline parked every keystroke
+        // behind a conversation read, which is what made scrolling lag.
+        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, askCounts);
+        schedulePreview(previewOn, previewLayout(size.cols, previewOn).mode === 'side');
+        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,
+            showReport: state.showReport,
+            residentsOnly: state.residentsOnly, pendingClose: state.pendingClose, flash: state.flash,
+            pinned: state.pinned, help: state.help,
+            rename: state.rename, renameBuf: state.renameBuf,
+            message: state.message, messageBuf: state.messageBuf,
+            searchingContent: contentSearching,
+            contentSnippet: selectedContentSnippet(),
+            readOnly: false,
+        }, size, caps);
+        process.stdout.write(frame);
+    };
+    // The selected row's preview, read after the cursor has rested PREVIEW_SETTLE_MS so
+    // holding an arrow key does not queue a conversation read per row passed. One read
+    // is in flight at a time; when it lands, the frame repaints only if that row is
+    // still selected (a stale result still warms its row for when the cursor returns),
+    // and the loop then serves whichever row the cursor moved to meanwhile.
+    const PREVIEW_SETTLE_MS = 90;
+    let previewTimer;
+    let previewInFlight = false;
+    let previewWant = { on: false, transcript: false };
+    const previewPending = (r) => r.previewLoaded !== true
+        || (previewWant.transcript && r.transcriptLoaded !== true)
+        || (state.search && state.query !== '' && r.promptsLoaded !== true);
+    const schedulePreview = (on, transcript) => {
+        previewWant = { on, transcript };
+        const id = curRow()?.id;
+        const r = id === undefined ? undefined : rowOf(id);
+        if (!on || r === undefined || !previewPending(r))
+            return;
+        if (previewTimer !== undefined)
+            clearTimeout(previewTimer);
+        previewTimer = setTimeout(() => { previewTimer = undefined; void runPreview(); }, PREVIEW_SETTLE_MS);
+    };
+    const runPreview = async () => {
+        if (previewInFlight || restored)
+            return;
+        const id = curRow()?.id;
+        const r = id === undefined ? undefined : rowOf(id);
+        if (!previewWant.on || r === undefined || !previewPending(r))
+            return;
+        previewInFlight = true;
+        try {
+            await loadPreviewFromSource(source, r, { transcript: previewWant.transcript });
+            if (state.search && state.query !== '')
+                await loadSearchTextFromSource(source, r);
+        }
+        catch (err) {
+            logAsyncFailure('preview load failed', err);
+            r.previewLoaded = true; // paint "(no conversation yet)" rather than retrying forever
+            r.transcriptLoaded = true;
+        }
+        finally {
+            previewInFlight = false;
+        }
+        if (restored)
+            return;
+        if (curRow()?.id === id)
+            scheduleFlush();
+        else
+            schedulePreview(previewWant.on, previewWant.transcript);
+    };
+    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, where a naive per-key handler drops batched chunks (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';
+            clearContentSearch();
+            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);
+            scheduleContentSearch();
+            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;
+            scheduleContentSearch();
+            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 = envNodeId();
+        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.handle = name;
+                n.row.name = fullName({ name, kind: n.row.kind, description: n.row.description });
+            }
+        }
+        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);
+        // Any keystroke retires the previous one-shot footer confirmation.
+        state.flash = null;
+        // 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.
+        if (action === 'crtr.browse.close-subtree') {
+            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;
+        }
+        if (action === 'crtr.browse.report') {
+            state.showReport = !state.showReport;
+            scheduleFlush();
+            return;
+        }
+        // Help overlay.
+        if (input === '?') {
+            state.help = true;
+            scheduleFlush();
+            return;
+        }
+        // Pin or unpin in the local, view-only pin set.
+        if (action === 'crtr.browse.pin') {
+            if (row !== undefined)
+                togglePin(row.id);
+            scheduleFlush();
+            return;
+        }
+        // Recenter on the launching node.
+        if (input === '.') {
+            recenterOnSelf();
+            scheduleFlush();
+            return;
+        }
+        // Rename the node inline.
+        if (input === 'R') {
+            if (row !== undefined) {
+                state.rename = true;
+                state.renameTarget = row.id;
+                state.renameBuf = rowOf(row.id)?.name ?? '';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Message the node without resuming it.
+        if (input === 'm') {
+            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') {
+            startWarm();
+            state.search = true;
+            state.query = '';
+            clearContentSearch();
+            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.
+        if (action === 'crtr.browse.revive-now') {
+            if (row !== undefined) {
+                const r = rowOf(row.id);
+                if (r?.hanging != null)
+                    reviveNow(row.id);
+            }
+            scheduleFlush();
+            return;
+        }
+        // Yank the hovered node's id to the system clipboard, so it can be pasted into
+        // a prompt or another command without retyping it off the screen.
+        if (action === 'crtr.browse.yank-id') {
+            if (row !== undefined) {
+                const { system, tmux } = writeClipboardTextEverywhere(row.id);
+                state.flash = system || tmux
+                    ? `Copied ${row.id}${system ? '' : ' to the tmux buffer'}`
+                    : 'No clipboard tool available — nothing copied';
+            }
+            scheduleFlush();
+            return;
+        }
+        // Resume the selected node.
+        if (action === 'crtr.browse.focus') {
+            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.
+        if (action === 'crtr.browse.focus-background') {
+            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 = envNodeId();
+    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: progressively enrich + load search text for 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).
+    //
+    // It runs on the FIRST search, not at boot. The pass reads a session file per
+    // node, and the only thing it feeds is prompt-text search — so paying for it at
+    // launch charged every user who merely navigates for a corpus they never query,
+    // and each chunk's disk read stalled the loop in front of their keystrokes.
+    let warmStarted = false;
+    const startWarm = () => {
+        if (warmStarted)
+            return;
+        warmStarted = true;
+        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, askCounts);
+            await Promise.all(slice.map((r) => loadSearchTextFromSource(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);
+    });
+}