@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/viewer.js

@@ -0,0 +1,873 @@
+// viewer.ts — the orchestrator for `crtr surface attach`: build the session
+// context, construct the collaborators that own each slice of it, wire them
+// together, start. Every behavior lives in a module under session/ chrome/
+// render/ input/ overlays/ — see src/clients/attach/.crouter/memory/INDEX.md
+// for the layering, viewer role invariants, and why attach owns no engine.
+//
+// Side-effect imports: must precede any pi theme/asset access
+// (session/pi-assets.ts) and any OAuth flow access (session/pi-oauth-flows.ts).
+import { envHomeOverride } from '../../shared/env.js';
+import './session/pi-assets.js';
+import './session/pi-oauth-flows.js';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { openReadonlyPopup } from './session/readonly-popup.js';
+import { Container, ProcessTerminal, TuiMainScreen } from '@earendil-works/pi-tui';
+import { croutonBannerLines } from '../../core/runtime/banner.js';
+// tmux driver verbs only through placement (the §5.1 model-over-driver seam) —
+// never `core/runtime/tmux.js` directly.
+import { currentTmux, inTmux, installTmuxBindings, shellQuote } from '../../core/runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../../core/runtime/surface-bg.js';
+import { resolveUserKeybindingSettings } from '../../core/keybindings/index.js';
+import { readConfig } from '../../core/config.js';
+import { ChatView } from './render/chat-view.js';
+import { createTranscriptViewport } from './render/viewport.js';
+import { createTranscriptSearchModel } from './render/transcript-search.js';
+import { createTranscriptSearch } from './session/transcript-search.js';
+import { createScrollAnimator } from './render/scroll-animation.js';
+import { createTranscriptCopy } from './render/transcript-copy.js';
+import { ActivitySlot } from './render/activity-slot.js';
+import { createInputController, createViewerCapabilitiesForInput } from './session/input-wiring.js';
+import { createRoster } from './chrome/roster.js';
+import { createInboxStrip } from './chrome/inbox-strip.js';
+import { createTicketPanel } from './chrome/ticket-panel.js';
+import { createPaneFocus } from './session/pane-focus.js';
+import { createStatusLine } from './chrome/status-line.js';
+import { createChromeWidgets } from './chrome/widgets.js';
+import { createRecapHeader } from './chrome/header.js';
+import { createChromeRefresh, isTransientDaemonFailure } from './session/chrome-refresh.js';
+import { createTeardown } from './session/teardown.js';
+import { reportInvariant } from './session/invariant.js';
+import { createReconnect } from './session/reconnect.js';
+import { createFrameHandler } from './session/frames.js';
+import { installGlobalKeys } from './session/keys.js';
+import { createMouseReporting } from './session/mouse.js';
+import { createFrameSelection } from './session/selection.js';
+import { extractFileOpenInput, openLinkedFileInPane } from './session/file-links.js';
+import { createDocumentLinks } from './session/document-links.js';
+import { FOCUS_REPORTING_ON } from './session/focus-events.js';
+import { GraphOverlay } from './overlays/graph.js';
+import { HelpOverlay } from './overlays/help.js';
+import { applyTheme, attachPalette, createKeybindingsManager, mirrorKeybindingsToEditor, mirrorKittyProtocolToEditor, resolveFdPath, } from './config.js';
+import { launchFileReview } from './overlays/file-review.js';
+import { openReviewSurfaceById, takeStartupReviewId } from '../inbox/review/launch.js';
+import { ViewerSurfaceHost } from './session/surface-host.js';
+import { createInboxSurface } from '../inbox/surface.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { watchInboxActivity } from '../../core/human/root.js';
+import { byNewestFirst, inboxRowFromDTO } from '../inbox/dto-adapt.js';
+import { cliClient } from '../../commands/api-client.js';
+import { loadPersonSettingsViaApi } from '../../commands/person-settings.js';
+import { buildBannerInfo } from './session/banner.js';
+import { backgroundBashHint, detachBindingHint, detachHint, inboxOpenHint, refreshAttachBindingSnapshot } from './session/bindings.js';
+import { connectToNode, resolveHelloRole } from './session/connection.js';
+import { createEditorChrome } from './session/editor-frame.js';
+import { createLayout } from './session/layout.js';
+import { createEditorInventory } from './session/editor-inventory.js';
+import { createFrecencyStore } from './input/completion-frecency.js';
+import { createNodeIdentity } from './session/identity.js';
+import { createPaneTag } from './session/pane-tag.js';
+import { launchProfileFileSearch, relatedNodes } from './session/profile-files.js';
+import { createSessionStateSync } from './session/state-sync.js';
+import { WhipAnimation, randomWhipMessage, GO_FASTER_WHIP_MESSAGE } from './session/whip.js';
+import { recordWhip } from './session/whip-achievements.js';
+import { mark } from '../../core/timing.js';
+/** Run the interactive attach session against `nodeId`. Resolves when the
+ *  viewer detaches (ctrl+c/ctrl+d), the broker goes away, or a signal lands —
+ *  always restoring the terminal first. `canvasName`, when set, attaches over
+ *  a relayed WebSocket to that `remoteCanvas.targets.<name>` instead of the
+ *  local unix socket — see the `--canvas` flag on `attachToLeaf`. */
+export async function runAttach(nodeId, observer, canvasName, wakeParked = true) {
+    // The viewer is its own esbuild bundle with its own copy of the settings cache: read the person's settings before anything
+    // calls readConfig (theme, keybindings, ChatView's field initializers all do).
+    await loadPersonSettingsViaApi();
+    // 1. Get onto the broker before anything paints (session/connection.ts):
+    //    resolve local-vs-relay, revive the node server-side if it is dormant,
+    //    and win the connect race. A failure here is still a plain CLI error.
+    //    `remote` is THE single remote fact (it selects the canvas and turns off local-host operations; `role` alone decides driving) for this whole session,
+    //    derived once here and threaded via `AttachSession` — every local disk
+    //    read, native slash command, pane tag and lifecycle action gates on it,
+    //    and no collaborator may re-derive it.
+    mark('viewer.connect_start', { node: nodeId });
+    const connection = await connectToNode(nodeId, canvasName, wakeParked);
+    mark(connection.initialSnapshot === undefined ? 'viewer.socket_connected' : 'viewer.offline_snapshot_ready');
+    const { remote, canvasSource, meta, socket } = connection;
+    const role = resolveHelloRole(observer);
+    const clientId = randomUUID();
+    // 2. Theme + keybindings — pi's components throw "Theme not initialized"
+    //    otherwise. One KeybindingsManager feeds BOTH editor and input; the
+    //    editor may resolve a separate pi-tui instance, so mirror onto it (and
+    //    await, so it never handles a key against stale defaults). `fd` powers
+    //    the @-mention file picker; `null` just leaves @-mention file-less.
+    applyTheme({ cwd: meta.cwd });
+    const pal = attachPalette();
+    const km = createKeybindingsManager();
+    let crouterBindingSettings = resolveUserKeybindingSettings();
+    let crouterBindings = crouterBindingSettings.bindings;
+    await mirrorKeybindingsToEditor(km);
+    const fdPath = await resolveFdPath();
+    // 3. Build the transcript source before the frame that virtualizes it. The
+    //    recap component is nested in layout's header container after it exists;
+    //    its state getter is first called only after `sync` is constructed below.
+    const procTerminal = new ProcessTerminal();
+    const tui = new TuiMainScreen(procTerminal);
+    const chatContainer = new Container();
+    // This viewer-owned container is a fixed frame slot, not part of ChatView's
+    // virtualized transcript. ChatView signals each loader swap through this hook.
+    const activityContainer = new ActivitySlot();
+    const chatView = new ChatView(tui, chatContainer, {
+        cwd: meta.cwd,
+        palette: pal,
+        hideThinking: true,
+        banner: croutonBannerLines(buildBannerInfo(meta)),
+        // Local only: a remote attach cannot read this canvas's ticket dirs, so it
+        // has nothing to render a page block from.
+        inlinePageBlocks: !remote,
+        pageOpenHint: () => inboxOpenHint(crouterBindings),
+        // The backgrounding gesture, offered under a bash call that has been
+        // running a while. Local and in-tmux only: the job files belong to the node
+        // host, and the gesture is a tmux menu pair, so anywhere else the row would
+        // name something the person cannot press.
+        backgroundBashHint: () => (remote || !inTmux() ? null : backgroundBashHint(crouterBindings)),
+        onActivityChange: (loader) => {
+            activityContainer.clear();
+            if (loader)
+                activityContainer.addChild(loader);
+        },
+    });
+    const transcriptSource = chatView.transcriptSource();
+    // Search paints its hits as the viewport draws each row, so it decorates the
+    // slice rather than the composed frame — the viewport is the only thing that
+    // knows which absolute content line a physical row is showing.
+    const searchModel = createTranscriptSearchModel(transcriptSource);
+    const viewport = createTranscriptViewport(transcriptSource, searchModel.decorate);
+    const transcriptCopy = createTranscriptCopy(chatView, viewport, transcriptSource);
+    let sync;
+    const recapHeader = createRecapHeader({ tui, pal }, () => sync.state());
+    const search = createTranscriptSearch(tui, pal, viewport, searchModel, {
+        bindings: () => crouterBindings,
+        setNotice: (message) => setNotice(message),
+    });
+    const layout = createLayout(procTerminal, tui, chatContainer, activityContainer, pal, km, viewport, search.component);
+    const { containers, editor } = layout;
+    const whipAnimation = new WhipAnimation(tui, pal);
+    containers.header.addChild(whipAnimation);
+    containers.header.addChild(recapHeader.component);
+    const ctx = { nodeId, remote, role, meta, canvasSource, socket, tui, pal, editor, containers };
+    // The pending-request strip below the recap goal line. Its hooks close over
+    // collaborators built later (paneFocus, roster, inbox, setNotice) — all are
+    // constructed before any key or refresh can invoke them.
+    const strip = createInboxStrip(ctx, {
+        syncCursor: () => paneFocus.sync(),
+        exitRoster: () => roster.exit(),
+        openTicket: (ticket) => { void ticketPanel.open(ticket); },
+        suppressed: () => ticketPanel.active(),
+        setNotice: (msg) => setNotice(msg),
+        onRefreshFailure: (cause) => chromeRefresh.reportFailure('inbox strip refresh', cause),
+    });
+    containers.header.addChild(strip.component);
+    const userConfig = readConfig('user');
+    const initialWhip = process.env['CRTR_ATTACH_INITIAL_WHIP'] === '1';
+    delete process.env['CRTR_ATTACH_INITIAL_WHIP'];
+    const startupReviewId = takeStartupReviewId();
+    const startupTicketId = process.env['CRTR_ATTACH_OPEN_TICKET'];
+    if (startupTicketId !== undefined)
+        delete process.env['CRTR_ATTACH_OPEN_TICKET'];
+    const mouse = createMouseReporting((data) => process.stdout.write(data), userConfig.mouse_mode_default);
+    // Mouse reporting takes drag-select away from the terminal, so the viewer
+    // owns it: the highlight paints over the composed frame, and the text copied
+    // is read from the same physical rows.
+    const selection = createFrameSelection({
+        frame: () => layout.frame.lastRenderedFrame(),
+        width: () => tui.terminal.columns,
+    });
+    layout.frame.setOverlay((frame) => selection.apply(frame));
+    // 4. The collaborators. Built in dependency order so that ONLY the status
+    //    line — first out of the gate, and read by everything — needs forward
+    //    references; every module after it passes its collaborators directly, so
+    //    a lazy `() => x.y()` below marks a genuine construction cycle rather
+    //    than mere ordering.
+    // Footer/status line — role, live state, transient notices. `setNotice` and
+    // `renderFooter` are aliased: they are by far the most-called verbs in the
+    // viewer (26 and 8 call sites), and read better as verbs than as reaches.
+    const statusLine = createStatusLine(ctx, {
+        state: () => sync.state(),
+        bashMode: () => editorChrome.bashMode(),
+        asks: () => chromeRefresh.asks(),
+        bindings: () => crouterBindings,
+        // Only meaningful for a LOCAL in-tmux attach: a remote attach's local inbox
+        // registry cannot open the remote canvas's filesystem tickets.
+        inboxAffordance: !remote && inTmux(),
+        mouseEnabled: () => mouse.enabled(),
+    });
+    const surfaceHost = new ViewerSurfaceHost({
+        tui,
+        mouse,
+        rows: () => tui.terminal.rows,
+        statusNotice: statusLine.setNotice,
+        formatNotice: (text) => pal.warning(`⚠ ${text}`),
+        noticeMs: 3_000,
+        capabilities: {
+            remote,
+            canFocusNode: !remote && process.env['TMUX_PANE'] !== undefined,
+        },
+        selfPane: process.env['TMUX_PANE'],
+    });
+    // The inbox is a session-long owner, unlike transient argument-bearing review
+    // surfaces. Keep its explicit viewer hook for the key and slash entry points.
+    // A no-inbox page carries no badge and never appears in `scanInbox()`, but a
+    // reply-bearing one raised by THIS node still has to be answerable from the
+    // viewer its transcript block sits in — so the local scan merges the two.
+    // The inbox opens on this node's own profile. The id is the identity that
+    // decides membership; the name only labels the heading, so a profile whose
+    // manifest will not load is still filtered on, under its id.
+    const inboxProfile = (() => {
+        const id = meta.profile_id;
+        if (!id)
+            return undefined;
+        try {
+            return { id, label: loadProfileManifest(id).manifest.name };
+        }
+        catch {
+            return { id, label: id };
+        }
+    })();
+    const inbox = createInboxSurface({
+        host: surfaceHost,
+        ...(inboxProfile === undefined ? {} : { profile: inboxProfile }),
+        ...(remote ? {} : { scan: async () => {
+                const client = cliClient();
+                const [inbox, history] = await Promise.all([client.listHumanInbox(), client.getInboxHistory(nodeId, { state: 'pending' })]);
+                const merged = new Map();
+                for (const item of inbox.tickets) {
+                    const row = inboxRowFromDTO(item);
+                    merged.set(row.dir, row);
+                }
+                for (const item of history.tickets) {
+                    const page = inboxRowFromDTO(item);
+                    if (page.kind !== 'page' || page.state !== 'pending' || !page.awaitsResponse || page.inbox)
+                        continue;
+                    if (!merged.has(page.dir))
+                        merged.set(page.dir, page);
+                }
+                // Subtree tickets the strip already scanned, so an Enter-opened child
+                // ticket is present in the surface it seats.
+                for (const ticket of strip.pendingTickets()) {
+                    if (!merged.has(ticket.dir))
+                        merged.set(ticket.dir, ticket);
+                }
+                return [...merged.values()].sort(byNewestFirst);
+            } }),
+    });
+    // Page mutations (publish, --replace, answer, cancel) touch the activity file
+    // whether or not the page went to the inbox, so transcript blocks refresh live.
+    const stopPageWatch = remote ? () => { } : watchInboxActivity(() => {
+        void chatView.refreshPageBlocks();
+        void strip.refresh();
+    });
+    // The inline ticket page under the editor — what Enter on a strip row opens.
+    // Review tickets and unreadable pages fall back to the full-pane inbox.
+    const ticketPanel = createTicketPanel(ctx, {
+        syncCursor: () => paneFocus.sync(),
+        refreshStrip: () => { void strip.refresh(); },
+        setNotice: (msg) => setNotice(msg),
+        openInbox: (dir) => inbox.open(dir),
+        suspendForChild: () => surfaceHost.suspendForChild(),
+    });
+    containers.ticketPanel.addChild(ticketPanel.component);
+    const viewerHooks = { toggleInbox: () => {
+            // Escalate an open inline ticket to the full inbox surface, seated on it.
+            const dir = ticketPanel.currentDir();
+            if (dir !== undefined) {
+                ticketPanel.close();
+                inbox.open(dir);
+                return;
+            }
+            inbox.toggle();
+        } };
+    // A full-pane surface covers every base row, so a notice painted into the
+    // status line while one is mounted is painted underneath it and never seen.
+    // The host owns the visible channel and delegates straight back to the status
+    // line when nothing is mounted, so this is the one notice verb either way.
+    const setNotice = (msg, opts) => {
+        if (surfaceHost.hasFullPaneSurface())
+            surfaceHost.notice(msg, opts);
+        else
+            statusLine.setNotice(msg, opts);
+    };
+    const renderFooter = statusLine.render;
+    const copyTarget = (target) => {
+        setNotice(transcriptCopy.copy(target));
+    };
+    const scrollAnimator = createScrollAnimator(viewport, () => tui.requestRender());
+    const viewportActions = {
+        'crtr.attach.scroll.up': () => { scrollAnimator.cancel(); if (viewport.scrollBy(-1))
+            tui.requestRender(); },
+        'crtr.attach.scroll.down': () => { scrollAnimator.cancel(); if (viewport.scrollBy(1))
+            tui.requestRender(); },
+        'crtr.attach.scroll.page-up': () => { scrollAnimator.page('up'); },
+        'crtr.attach.scroll.page-down': () => { scrollAnimator.page('down'); },
+        'crtr.attach.scroll.live': () => { scrollAnimator.cancel(); viewport.goLive(); tui.requestRender(); },
+        'crtr.attach.mouse.toggle': () => {
+            const on = mouse.toggle();
+            if (!on && selection.clear())
+                tui.requestRender();
+            setNotice(on ? 'Mouse: wheel scrolling on, drag to select and copy' : 'Mouse: off — tmux drag-select and copy-mode restored');
+        },
+        'crtr.attach.copy.message': () => copyTarget('message'),
+    };
+    let reconnect;
+    const capabilities = createViewerCapabilitiesForInput(ctx, () => reconnect === undefined ? connection.initialSnapshot !== undefined : reconnect.isDormant());
+    // Per-user completion frecency (usage bias), shared by the editor inventory
+    // that RANKS completions and the input controller that RECORDS uses. One
+    // store per viewer session; persists to the user scope root.
+    const frecency = createFrecencyStore();
+    // Everything the editor completes against — slash commands, the loaded-
+    // command preview, the memory-ref inventory — has ONE owner.
+    const inventory = createEditorInventory(ctx, capabilities, { setNotice, bindings: () => crouterBindings, fdPath, frecency });
+    // Canvas identity (kind/mode/lifecycle) behind the context badge. A remote
+    // attach starts without one, so load it as soon as the viewer exists.
+    const identity = createNodeIdentity(ctx, connection.nodeIdentity, {
+        isTornDown: () => lifecycle.isTornDown(),
+        onChanged: () => {
+            editorChrome.syncContextBadge();
+            const engine = sync.state().engine;
+            if (engine !== undefined)
+                editorChrome.setTitle(engine.sessionName);
+            tui.requestRender();
+        },
+    });
+    if (remote)
+        identity.refresh();
+    // Editor chrome: owns bashMode and the `/color` chip override, paints the
+    // border/title/badge/git adornments, and installs `editor.onChange`.
+    const editorChrome = createEditorChrome(ctx, {
+        nodeIdentity: identity.current,
+        thinkingLevel: () => sync.state().engine?.thinkingLevel,
+        renderFooter,
+        onTextChange: inventory.syncCommandPreview,
+    });
+    editorChrome.syncContextBadge();
+    // The two broker-fed container painters: extension widgets in their cockpit
+    // slots, and the queued-steering panel.
+    const { renderExtensionWidgets, renderQueued } = createChromeWidgets(ctx, () => sync.state());
+    // The OWNER of the folded SessionState and of what each delta repaints.
+    sync = createSessionStateSync(role, {
+        setEngineState: (engine) => input.setState(engine),
+        setEditorTitle: editorChrome.setTitle,
+        paintEditorFrame: editorChrome.paintFrame,
+        renderExtensionWidgets: () => {
+            recapHeader.render();
+            renderExtensionWidgets();
+        },
+        renderQueued,
+        renderFooter,
+        setTerminalTitle: (title) => procTerminal.setTitle(title),
+        refreshChrome: () => chromeRefresh.refresh(),
+    });
+    // The Inspector is an earned takeover (rich, self-contained, its own keys) but
+    // NOT a place you leave open beside your work — so it rides a display-popup that
+    // closes back onto this pane rather than claiming a persistent window. The popup
+    // is a real TTY, so `surface
+    // inspect` hosts in-place inside it.
+    const openInspector = (section) => {
+        if (!inTmux()) {
+            setNotice('Inspector requires tmux');
+            return;
+        }
+        setNotice(`Opening Inspector (${section})…`);
+        const home = envHomeOverride();
+        const prefix = home === undefined ? '' : `CRTR_HOME=${shellQuote(home)} `;
+        const cmd = `${prefix}crtr surface inspect ${shellQuote(nodeId)} --section ${section}`;
+        execFile('tmux', ['display-popup', '-E', '-T', ` inspector · ${section} `, '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => {
+            chromeRefresh.refresh();
+        });
+    };
+    // A watched object the node waits on (a workflow run, a pull request) has one
+    // read surface every kind shares: `crtr canvas read`. Its output is a page of
+    // markdown, so it rides the same read-only nvim popup as a loaded command
+    // rather than a bare command popup that would close the instant it printed.
+    const openObject = (objectId) => {
+        if (!inTmux()) {
+            setNotice('Object details require tmux');
+            return;
+        }
+        setNotice('Opening object…');
+        const home = envHomeOverride();
+        const prefix = home === undefined ? '' : `CRTR_HOME=${shellQuote(home)} `;
+        openReadonlyPopup({
+            name: objectId,
+            produce: (page) => `${prefix}crtr canvas read ${shellQuote(objectId)} > ${page} 2>&1`,
+            title: `object · ${objectId}`,
+            noNvim: 'nvim is required to view the object. Install Neovim and retry.',
+            onClose: () => chromeRefresh.refresh(),
+        });
+    };
+    // The inline subagent scroll+swap roster below the editor. It owns the two
+    // editor couplings the list needs (`onCursorDownAtBottom`, `paneFocused`), so
+    // the pane-focus events feed it rather than poking the editor directly.
+    const roster = createRoster(ctx, {
+        asks: () => chromeRefresh.asks(),
+        setNotice,
+        requestChromeRefresh: () => chromeRefresh.refresh(),
+        openInspector,
+        openObject,
+        syncCursor: () => paneFocus.sync(),
+    });
+    // The one hollow-cursor owner: pane focus AND neither list holding the highlight.
+    const paneFocus = createPaneFocus(editor, [roster.active, strip.active, ticketPanel.active]);
+    // The GRAPH overlay — a bounded, centered modal navigator over the same
+    // nav-model graph, reading the live ask counts.
+    const graphOverlay = new GraphOverlay(tui, nodeId, () => chromeRefresh.asks(), pal, crouterBindings, canvasSource, role, (cause) => chromeRefresh.reportFailure('canvas graph refresh', cause), setNotice);
+    const helpOverlay = new HelpOverlay(tui, pal);
+    helpOverlay.setBindings(crouterBindings);
+    // The canvas-chrome refresh/poll engine: owns the ask-count map, the
+    // coalescing refresh loop, and the 5s chrome poll.
+    const chromeRefresh = createChromeRefresh(ctx, {
+        isTornDown: () => lifecycle.isTornDown(),
+        setNotice,
+        refreshRoster: async () => {
+            await roster.refresh();
+            await strip.refresh();
+        },
+        refreshGraph: () => graphOverlay.refresh(),
+        refreshIdentity: () => identity.refresh(),
+        renderFooter,
+        renderExtensionWidgets,
+        refreshInFlightTools: () => chatView.refreshInFlightTools(),
+        pollGit: editorChrome.pollGit,
+    });
+    // Input layer — session/input-wiring.ts answers every hook InputController
+    // takes (socket sinks, slash context, pickers, auth, dormant submit).
+    const input = createInputController(ctx, km, capabilities, {
+        setNotice,
+        agentDir: () => sync.state().agentDir,
+        openNodeMetadata: () => openInspector('overview'),
+        isDormant: () => reconnect.isDormant(),
+        copyTarget,
+        toggleToolsExpanded: () => chatView.toggleToolsExpanded(),
+        toggleFoldTools: () => chatView.toggleFoldSettledTools(),
+        toggleShowWorking: () => chatView.toggleShowWorking(),
+        toggleThinking: () => chatView.toggleThinking(),
+        toggleGraph: () => graphOverlay.toggle(),
+        toggleInbox: viewerHooks.toggleInbox,
+        toggleHelp: () => helpOverlay.toggle(),
+        toggleMouse: () => mouse.toggle(),
+        quit: () => teardown('detach'),
+        setChipColor: editorChrome.setChipColor,
+        onPromptSent: () => {
+            if (userConfig.whip_mode)
+                whipAnimation.play();
+        },
+        frecency,
+    });
+    const whip = () => {
+        if (surfaceHost.hasFullPaneSurface()) {
+            setNotice('Close the active surface before whipping the agent');
+            return;
+        }
+        // `whip_message_mode` chooses what the one whip action says: the random
+        // rotation, or the plain fixed line.
+        const message = userConfig.whip_message_mode === 'go-faster'
+            ? GO_FASTER_WHIP_MESSAGE
+            : randomWhipMessage(userConfig.whip_messages);
+        if (!input.sendInterrupting(message))
+            return;
+        whipAnimation.play();
+        recordWhip(pal);
+        setNotice(`Whipped agent — ${message}`);
+    };
+    // `[[…]]` document links: readable names and local browser URLs.
+    const documentLinks = createDocumentLinks({
+        selfNodeId: nodeId,
+        remote,
+        canvasSource,
+        port: userConfig.document_port,
+        fetchSecret: async () => (await cliClient().documents.browserAccess()).secret,
+        onSecretError: (err) => setNotice(`Document links are unavailable: ${err instanceof Error ? err.message : String(err)}`),
+        refresh: () => chatView.refreshMarkdown(),
+    });
+    const openFileReview = () => {
+        if (ticketPanel.active()) {
+            setNotice('Close the open request first (Esc)');
+            return;
+        }
+        // Documents referenced as `[[…]]` sit beside file paths; the picker and
+        // launcher tell them apart by their brackets.
+        const candidates = [
+            ...chatView.getTranscriptDocRefsNewestFirst().map((ref) => `[[${ref}]]`),
+            ...chatView.getTranscriptFilePathsNewestFirst(),
+        ];
+        const review = (file) => {
+            void launchFileReview(surfaceHost, file, {
+                originNodeId: nodeId,
+                onNotice: setNotice,
+            });
+        };
+        // The cockpit's picker slot lives in the base frame, which a full-pane
+        // surface covers while owning input — so mount the picker on the host's
+        // own stack before opening the selected review in its window.
+        if (surfaceHost.hasFullPaneSurface()) {
+            void surfaceHost
+                .pickReviewFile({ candidates, cwd: meta.cwd, title: 'Review a file or document named in this transcript' })
+                .then((file) => {
+                if (file !== null)
+                    review(file);
+            });
+            return;
+        }
+        input.openFileReviewPicker(candidates, meta.cwd, review);
+    };
+    const openProfileFiles = () => {
+        if (remote) {
+            setNotice('Profile file search is unavailable on remote canvases');
+            return;
+        }
+        if (!inTmux()) {
+            setNotice('Profile file search requires tmux');
+            return;
+        }
+        void canvasSource.listNodes()
+            .then((nodes) => {
+            const family = relatedNodes(nodes, nodeId);
+            launchProfileFileSearch({
+                cwd: meta.cwd,
+                nodeDirs: family.map((node) => node.cwd),
+                nodes: family,
+                profileId: meta.profile_id ?? null,
+                fdPath,
+                onNotice: setNotice,
+            });
+        })
+            .catch((error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            setNotice(`Could not load related node directories: ${detail}`);
+        });
+    };
+    // Every broker frame into both layers. The SHARED reducer owns every fact the
+    // broker told us (that is `sync.fold`); the handler owns only local effects.
+    let bindingInstallTimer;
+    const scheduleTmuxBindingInstall = () => {
+        if (bindingInstallTimer !== undefined)
+            clearTimeout(bindingInstallTimer);
+        bindingInstallTimer = setTimeout(() => {
+            bindingInstallTimer = undefined;
+            refreshAttachBindingSnapshot(() => crouterBindingSettings, () => { }, inTmux, installTmuxBindings);
+        }, 1000);
+        bindingInstallTimer.unref();
+    };
+    const handleBrokerFrame = createFrameHandler(ctx, {
+        foldState: sync.fold,
+        chat: chatView,
+        setNotice,
+        renderFooter,
+        setEditorText: (text) => {
+            editor.setText(text);
+            tui.requestRender();
+        },
+        attachDialog: (req) => input.attachDialog(req),
+        dismissDialog: (id) => input.dismissDialog(id),
+        refreshNodeIdentity: identity.refresh,
+        setCommands: inventory.setCommands,
+        resetMemoryRefs: inventory.resetMemoryRefs,
+        reloadBindings: () => {
+            crouterBindingSettings = refreshAttachBindingSnapshot(resolveUserKeybindingSettings, (bindings) => {
+                graphOverlay.setBindings(bindings);
+                helpOverlay.setBindings(bindings);
+            }, inTmux, installTmuxBindings);
+            crouterBindings = crouterBindingSettings.bindings;
+        },
+        modelThinkingLabel: sync.modelThinkingLabel,
+        onWelcome: () => scheduleTmuxBindingInstall(),
+    });
+    // Last resort for a background daemon call that escaped its owner's catch.
+    // Node's default for an unhandled rejection is to exit, and this process IS
+    // the person's pane: one stray promise from a fire-and-forget refresh closed
+    // every open viewer at once when crtrd stalled. Every background read keeps
+    // its own catch; this only decides what an escaped one costs. A failure that
+    // reached here is recorded to the viewer's invariant log (never the terminal,
+    // which would paint over the frame) and the session keeps running on its
+    // last rendered state. A broken broker socket still ends the session through
+    // the reconnect path, which does not depend on this.
+    const onUnhandledRejection = (reason) => {
+        const detail = reason instanceof Error ? `${reason.name}: ${reason.message}` : String(reason);
+        reportInvariant('attach.unhandled_rejection', detail);
+        if (isTransientDaemonFailure(reason))
+            chromeRefresh.reportFailure('background daemon call', reason);
+    };
+    process.on('unhandledRejection', onUnhandledRejection);
+    const removeRejectionGuard = () => { process.off('unhandledRejection', onUnhandledRejection); };
+    // The `@crtr_node` pane tag, claimed after the startup checkpoint below.
+    const paneTag = createPaneTag(remote, nodeId);
+    // Lifecycle / teardown — always restore the terminal, exactly once
+    // (session/teardown.ts owns the ordering rules and the four end reasons).
+    // `stopLocal` is this viewer's own shutdown: every collaborator it built
+    // stops here, BEFORE the socket is told anything.
+    const lifecycle = createTeardown(ctx, {
+        stopLocal: () => {
+            if (bindingInstallTimer !== undefined)
+                clearTimeout(bindingInstallTimer);
+            surfaceHost.closeAll();
+            scrollAnimator.cancel();
+            mouse.disable();
+            chromeRefresh.stop();
+            ticketPanel.close();
+            statusLine.dispose();
+            graphOverlay.close();
+            helpOverlay.close();
+            search.close();
+            whipAnimation.dispose();
+            paneTag.clear();
+            removeKeyListener();
+            removeSelectionClear();
+            removeFileOpenListener();
+            removeRejectionGuard();
+            documentLinks.dispose();
+            stopPageWatch();
+            try {
+                chatView.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        // Reached lazily: reconnect is built after teardown (it needs `isTornDown`),
+        // and this is only ever read once teardown actually runs.
+        lastSocketError: () => reconnect.lastSocketError(),
+        tagPane: paneTag.pane,
+    });
+    const teardown = lifecycle.teardown;
+    // The reconnect supervisor: the hello handshake, the permanent socket
+    // handlers, and the redial policy that decides whether a closed socket means
+    // "hold the pane, the broker is coming back" or "this node is genuinely gone".
+    reconnect = createReconnect(ctx, {
+        role,
+        remote,
+        initialDormant: connection.initialSnapshot !== undefined,
+        clientId,
+        onFrame: handleBrokerFrame,
+        setNotice,
+        isTornDown: () => lifecycle.isTornDown(),
+        teardown,
+        // An idle-released broker has settled its turn and will not relay a final
+        // session event to this viewer. Clear its live-only display locally.
+        onEnterDormancy: () => {
+            scheduleTmuxBindingInstall();
+            chatView.settleRun();
+            sync.patchLocal({ isStreaming: false });
+        },
+    });
+    // 5. The startup checkpoint. A relay's post-upgrade "no node"/"no running
+    //    broker" close may have arrived any time during the synchronous setup
+    //    above; connection.ts's never-removed error listener is how it survives
+    //    that gap. Surface it BEFORE the reconnect supervisor takes over (which
+    //    would misclassify a genuinely-gone target as a live session that
+    //    dropped) and before the pane tag is claimed (so a failed attach never
+    //    leaves a stale tag behind).
+    connection.assertConnected();
+    paneTag.set();
+    reconnect.install();
+    // 6. Lay out, paint, start, then handshake — starting before the handshake
+    //    means the welcome's applySnapshot renders into a live TUI.
+    layout.mount();
+    tui.start();
+    if (connection.initialSnapshot !== undefined) {
+        // Seed the same state/transcript owners a broker welcome feeds. No socket
+        // frame is fabricated: the first real welcome remains authoritative and
+        // ChatView's generation guard replaces this saved reconstruction cleanly.
+        sync.fold({ type: 'welcome', snapshot: connection.initialSnapshot, role });
+        void chatView.applySnapshot(connection.initialSnapshot);
+        inventory.setCommands(connection.initialCommands);
+        // A parked conversation has no broker, so the attach bridge never sees it shown.
+        if (!remote)
+            void cliClient().markNodeRead(nodeId).catch(() => undefined);
+    }
+    if (userConfig.whip_mode && initialWhip)
+        whipAnimation.play();
+    mouse.reassert();
+    let fileLinkOpening = false;
+    const openFile = (file) => {
+        if (fileLinkOpening)
+            return;
+        if (remote) {
+            setNotice('Opening a file is unavailable in a remote attach');
+            return;
+        }
+        const tmux = currentTmux();
+        if (tmux === null)
+            return;
+        const result = openLinkedFileInPane({
+            file,
+            pane: tmux.pane,
+            cwd: meta.cwd,
+            nodeId,
+            observer,
+            beforeRespawn: paneTag.clear,
+        });
+        if (result === 'opened') {
+            fileLinkOpening = true;
+            return;
+        }
+        // A queued respawn did not land, so this pane is still a viewer and must
+        // regain the identity that `beforeRespawn` just cleared.
+        if (result === 'failed')
+            paneTag.set();
+        if (result === 'missing')
+            setNotice('File no longer exists');
+        if (result === 'no_nvim')
+            setNotice('Neovim is required to open files — install it (brew install neovim / apt install neovim) and retry');
+        if (result === 'failed')
+            setNotice('Could not open file in Neovim');
+    };
+    mouse.install(tui, {
+        onWheel: (direction, lines) => {
+            if (selection.clear())
+                tui.requestRender();
+            if (surfaceHost.handleWheel(direction, lines))
+                return;
+            scrollAnimator.cancel();
+            if (viewport.scrollBy(direction === 'up' ? -lines : lines))
+                tui.requestRender();
+        },
+        onPrimaryPress: (column, row) => {
+            // Full-pane surfaces own the visible screen while mounted; neither a
+            // file-link click nor a selection may reach the base frame beneath one.
+            if (surfaceHost.hasFullPaneSurface())
+                return;
+            if (selection.clear())
+                tui.requestRender();
+            selection.begin(column, row);
+        },
+        onPrimaryDrag: (column, row) => {
+            if (surfaceHost.hasFullPaneSurface())
+                return;
+            if (selection.extend(column, row))
+                tui.requestRender();
+        },
+        onPrimaryRelease: () => {
+            const released = selection.release();
+            if (released?.kind !== 'selection')
+                return;
+            setNotice(released.notice);
+            tui.requestRender();
+        },
+    });
+    // iTerm Semantic History sends this private control after Command-clicking a
+    // rendered local Markdown path. It is not editor text.
+    const removeFileOpenListener = tui.addInputListener((data) => {
+        const input = extractFileOpenInput(data);
+        if (input === undefined)
+            return undefined;
+        const file = input.file;
+        if (file === undefined)
+            setNotice('Could not open file link');
+        else
+            openFile(file);
+        return input.remaining.length > 0 ? { data: input.remaining } : { consume: true };
+    });
+    // Registered after the mouse listener, which consumes mouse sequences, so
+    // this sees keyboard input only: any keystroke retires the highlight the way
+    // it retires a terminal's own selection.
+    const removeSelectionClear = tui.addInputListener(() => {
+        if (selection.clear())
+            tui.requestRender();
+        return undefined;
+    });
+    // The global key listener — fires before the focused component, so it must
+    // hand back everything it does not claim (session/keys.ts). Mouse reporting
+    // registers first so terminal mouse sequences are consumed before key input.
+    const removeKeyListener = installGlobalKeys(ctx, {
+        bindings: () => crouterBindings,
+        detachHint: () => detachHint(crouterBindings),
+        hasExclusiveSurface: () => surfaceHost.hasFullPaneSurface(),
+        setPaneFocused: (focused) => {
+            if (focused)
+                paneTag.stamp();
+            paneFocus.setPaneFocused(focused);
+            tui.requestRender();
+        },
+        viewportActions: () => viewportActions,
+        searchHandleKey: search.handleKey,
+        panelHandleKey: ticketPanel.handleKey,
+        stripHandleKey: strip.handleKey,
+        rosterHandleKey: roster.handleKey,
+        setNotice,
+        detach: () => teardown('detach'),
+        cancelTurn: () => {
+            if (input.abortTurn())
+                setNotice('Canceling the agent…');
+            else
+                setNotice(`Nothing running to cancel — press ${detachBindingHint(crouterBindings) ?? 'ctrl+d'} to detach`);
+        },
+        toggleGraph: () => graphOverlay.toggle(),
+        toggleHelp: () => helpOverlay.toggle(),
+        toggleInbox: viewerHooks.toggleInbox,
+        toggleInboxStrip: () => {
+            if (surfaceHost.hasFullPaneSurface()) {
+                setNotice('Close the active surface before opening the request strip');
+                return;
+            }
+            // From an open inline ticket, the strip binding steps back up to the list.
+            if (ticketPanel.active())
+                ticketPanel.close();
+            strip.toggle();
+        },
+        // Through the input layer, not straight to the socket: the ladder is a
+        // mutating frame and must ride the same capability gate as every other one.
+        cycleModelLadder: (direction) => input.cycleLadder(direction),
+        inspectLoadedCommand: inventory.inspectLoadedCommand,
+        openFileReview,
+        openProfileFiles,
+        openSearch: () => {
+            if (surfaceHost.hasFullPaneSurface() || ticketPanel.active()) {
+                setNotice('Close the active surface before searching the transcript');
+                return;
+            }
+            search.open();
+        },
+        whip,
+    });
+    // Registered only now: every collaborator `stopLocal` touches (the key
+    // listener included) finally exists, so a signal cannot race a half-built
+    // session.
+    lifecycle.installSignalHandlers();
+    renderFooter();
+    chromeRefresh.refresh();
+    renderQueued();
+    editorChrome.pollGit();
+    mark('viewer.first_paint');
+    // Ask the terminal (tmux pane) to report focus in/out; Restore() turns it off.
+    process.stdout.write(FOCUS_REPORTING_ON);
+    // ProcessTerminal negotiated the keyboard protocol on OUR pi-tui instance; the
+    // editor reads the flag from its own (possibly separate) instance.
+    void mirrorKittyProtocolToEditor(procTerminal.kittyProtocolActive);
+    // A live viewer waits for welcome so the synchronous tmux sweep cannot block
+    // that frame. If the broker vanishes before welcome, reconnect's dormancy
+    // callback schedules the same install. A dormant viewer schedules it directly.
+    if (connection.initialSnapshot !== undefined)
+        scheduleTmuxBindingInstall();
+    if (connection.initialSnapshot === undefined) {
+        mark('viewer.hello_sent');
+        reconnect.sendHello();
+    }
+    else {
+        reconnect.startDormant();
+    }
+    chromeRefresh.start();
+    if (startupReviewId !== undefined)
+        void openReviewSurfaceById(surfaceHost, startupReviewId);
+    if (startupTicketId !== undefined && startupTicketId !== '' && !remote) {
+        // The dashboard opened this conversation for its oldest pending ask: show the ask first.
+        // Resolve it from the same two reads the inbox strip makes (listed tickets, plus pending unlisted pages).
+        void (async () => {
+            const client = cliClient();
+            const [listed, history] = await Promise.all([client.listHumanInbox(), client.getInboxHistory(undefined, { state: 'pending' })]);
+            const row = [...listed.tickets, ...history.tickets].map(inboxRowFromDTO).find((r) => r.inboxTicketId === startupTicketId && (r.kind !== 'page' || r.state === 'pending'));
+            if (row === undefined)
+                setNotice('ask already answered');
+            else
+                void ticketPanel.open(row);
+        })().catch((err) => setNotice(`could not open the ask: ${String(err?.message ?? err)}`));
+    }
+    await lifecycle.done;
+}