@north-light/api 0.3.580 → 0.3.588

package/dist/clients/attach/session/frames.js

@@ -0,0 +1,203 @@
+// session/frames.ts — what this terminal DOES about each broker frame.
+//
+// Every fact a frame carries is folded by the shared pure reducer
+// (`core/session-model`) in `foldState` before anything here runs. What is left,
+// and all this file owns, is the
+// LOCAL effects: transcript writes, notices, editor text, and the correlated
+// refetches a fresh broker forces.
+//
+// The rule for adding a case: if the frame changes something a reader could
+// see in the reducer's state, it belongs in the reducer, not here.
+import { writeClipboardText } from '../../../core/clipboard-text.js';
+import { parsePreviewableCommands } from '../slash/prompt-preview.js';
+import { mark } from '../../../core/timing.js';
+/** Build the single `frame` handler the socket is wired to. */
+export function createFrameHandler(ctx, fx) {
+    const { socket } = ctx;
+    /** The two refetches a FRESH broker forces. A broker that just came up
+     *  (post-crash-revive, post-refresh, or a redial after sleep/Wi-Fi loss) has
+     *  no memory of this viewer's inventories, and `/reload` can replace both
+     *  corpora under a live one — same recovery either way. The epoch bump inside
+     *  `resetMemoryRefs` supersedes any request still in flight from a PRIOR
+     *  connection, so a late reply can never overwrite the fresh inventory. */
+    const refetchInventories = () => {
+        socket.send({ type: 'get_commands' });
+        fx.resetMemoryRefs();
+    };
+    const handleAck = (frame) => {
+        // get_commands replies with the broker's merged command list as JSON in
+        // `detail` — rebuild the autocomplete provider with it (slashCommandList
+        // re-appends the native canvas commands, deduped).
+        if (frame.for === 'get_commands' && frame.ok && frame.detail) {
+            try {
+                fx.setCommands(parsePreviewableCommands(frame.detail));
+            }
+            catch {
+                /* malformed — keep the current provider */
+            }
+            return;
+        }
+        // navigate_tree's detail is the navigated-to user message's text (pi
+        // parity: the tree navigator restores it to the editor for re-editing);
+        // the rewound transcript itself arrives via the broker's re-welcome.
+        if (frame.for === 'navigate_tree' && frame.ok) {
+            if (frame.detail)
+                fx.setEditorText(frame.detail);
+            return;
+        }
+        if (frame.for === 'share') {
+            if (frame.ok && frame.detail) {
+                fx.setNotice(`Shared: ${frame.detail}`);
+                writeClipboardText(frame.detail);
+            }
+            else if (!frame.ok) {
+                fx.setNotice(`share failed: ${frame.detail ?? 'unknown error'}`);
+            }
+            return;
+        }
+        if (frame.for === 'clone' && !frame.ok) {
+            fx.setNotice(`clone failed: ${frame.detail ?? 'unknown error'}`);
+            return;
+        }
+        if (!frame.ok) {
+            fx.setNotice(`command failed: ${frame.for}${frame.detail ? ` — ${frame.detail}` : ''}`);
+            return;
+        }
+        // Confirm commands whose effect is otherwise invisible — without this a
+        // `/reload` looks like it did nothing (the engine reloads silently).
+        if (frame.for === 'reload') {
+            fx.reloadBindings();
+            // `session.reload()` can replace extension command metadata AND the
+            // resolvable memory-ref corpus (a memory doc added/edited/removed). Drop
+            // the old inventory and its disclosure immediately, so a partially-typed
+            // ref or command never keeps completing against a stale one; only a fresh
+            // ack may repopulate it.
+            fx.setCommands();
+            refetchInventories();
+            fx.setNotice('Reloaded keybindings, extensions, skills, prompts, and themes');
+        }
+    };
+    /** A relayed AgentSessionEvent — everything not in the switch below. */
+    const handleSessionEvent = (event) => {
+        fx.chat.handleEvent(event);
+        if (event.type === 'session_info_changed') {
+            // Recap title regeneration persists a new canvas icon before changing the
+            // pi session name. Refreshing here lets the identity owner's onChanged
+            // repaint normalize that name with the matching icon instead of keeping
+            // the icon cached when this viewer attached.
+            fx.refreshNodeIdentity();
+        }
+        else if (event.type === 'thinking_level_changed') {
+            fx.setNotice(fx.modelThinkingLabel() ?? `Thinking level: ${event.level}`);
+        }
+        else if (event.type === 'tool_execution_start' || event.type === 'tool_execution_end') {
+            // R4: a bash tool call starting or ending changes what the on-disk job
+            // scan (oldestRunningBashJobStartedAtMs, read inside the status line)
+            // would return, so repaint immediately rather than waiting for the next
+            // 5s chrome poll — no session state to track, just the repaint.
+            fx.renderFooter();
+        }
+    };
+    let markedWelcome = false;
+    return (frame) => {
+        fx.foldState(frame);
+        switch (frame.type) {
+            case 'welcome': {
+                // The end of the front-door clock under CRTR_TIMING: the first frame
+                // carrying engine state, i.e. the moment the pane stops being empty
+                // chrome. Only the first one is marked — reconnects re-welcome.
+                if (!markedWelcome) {
+                    markedWelcome = true;
+                    mark('viewer.welcome');
+                }
+                // Every fact this welcome carries — role, agentDir, pi's state, the
+                // context seed, the retained display levels, and the queue reset a fresh
+                // broker needs (it has no memory of this viewer's queue panel, and an
+                // empty queue emits no `queue_update` to overwrite it) — was already
+                // folded by `foldState`. What remains here is local: the transcript, and
+                // the refetches this viewer owns.
+                //
+                // applySnapshot yields to the event loop between chunks for a large
+                // non-streaming catch-up (so stdin drains during construction); it runs
+                // synchronously for a streaming snapshot. Fire without await — nothing
+                // below reads the constructed view, and applySnapshot requests its own
+                // final render. ChatView is a single ordered writer: live frames that
+                // arrive mid-build defer and replay in wire order once it finishes, and
+                // a second welcome supersedes an older build outright — so this void
+                // call cannot interleave transcripts.
+                void fx.chat.applySnapshot(frame.snapshot);
+                // A fresh broker may reflect a new node persona or lifecycle.
+                fx.refreshNodeIdentity();
+                refetchInventories();
+                if (frame.pending_dialog != null)
+                    fx.attachDialog(frame.pending_dialog);
+                fx.onWelcome?.();
+                break;
+            }
+            case 'tool_group_summary':
+                fx.chat.applyToolGroupSummary(frame.key, frame.summary);
+                break;
+            case 'turn_reply':
+                fx.chat.applyTurnReply(frame.key, frame.reply);
+                break;
+            case 'working_activity':
+                fx.chat.setWorkingActivity(frame.activity);
+                break;
+            case 'model_changed': {
+                // The broker's own post-set_model/cycle_model announcement (pi emits no
+                // engine event for a model switch) already moved the footer's model
+                // through the reducer. Announce the resulting model + thinking level.
+                const modelLabel = fx.modelThinkingLabel();
+                if (modelLabel)
+                    fx.setNotice(modelLabel);
+                break;
+            }
+            case 'error':
+                // A refusal answers the keystroke that caused it in one short line, so
+                // the transient notice is its slot. Every other error frame carries the
+                // engine's own text, which is routinely multi-line — a send with no
+                // credential answers with pi's three-line login help — and the notice
+                // rides the one-row status bar, where the frame allocator keeps only the
+                // LAST line: the user saw a bare path to docs/models.md with the
+                // instruction above it cut off. Those go to the transcript, which has
+                // the rows for the whole message and keeps it after the turn.
+                if (frame.code === 'read_only')
+                    fx.setNotice('read-only');
+                else
+                    fx.chat.showError(frame.message);
+                break;
+            case 'node_named':
+                // Nothing to do here: the naming extension shares this process, so it
+                // set the live session name in the same callback and pi's own
+                // `session_info_changed` already moved this viewer's label chip. The
+                // frame exists for clients that are NOT in the broker's process.
+                break;
+            case 'ack':
+                handleAck(frame);
+                break;
+            case 'extension_ui_request':
+                // pi's uniform envelope: the three display METHODS are session state the
+                // reducer already folded and `foldState` already painted. Everything
+                // else — notify and the blocking four — is a live TUI overlay we own.
+                if (frame.method !== 'setStatus' && frame.method !== 'setWidget' && frame.method !== 'setTitle') {
+                    fx.attachDialog(frame);
+                }
+                break;
+            case 'extension_ui_dismiss':
+                fx.dismissDialog(frame.id);
+                break;
+            case 'bash_start':
+                fx.chat.bashStart(frame.command, frame.excludeFromContext);
+                break;
+            case 'bash_output':
+                fx.chat.bashOutput(frame.chunk);
+                break;
+            case 'bash_end':
+                fx.chat.bashEnd(frame);
+                break;
+            default:
+                handleSessionEvent(frame);
+                break;
+        }
+    };
+}

package/dist/clients/attach/session/identity.d.ts

@@ -0,0 +1,16 @@
+import type { NodeMeta } from '../../../core/canvas/types.js';
+import type { AttachSession } from './context.js';
+export type NodeIdentity = Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle' | 'icon'> | undefined;
+export interface IdentityHooks {
+    /** Drop a late refresh that lands after the viewer is gone. */
+    isTornDown: () => boolean;
+    /** Repaint the badge/chip the identity feeds. */
+    onChanged: () => void;
+}
+export interface NodeIdentityOwner {
+    current: () => NodeIdentity;
+    /** Re-read from the canvas source. Fire-and-forget; failures are ignored
+     *  (the badge simply keeps its last known value). */
+    refresh: () => void;
+}
+export declare function createNodeIdentity(ctx: Pick<AttachSession, 'nodeId' | 'canvasSource'>, initial: NodeIdentity, hooks: IdentityHooks): NodeIdentityOwner;

package/dist/clients/attach/session/identity.js

@@ -0,0 +1,26 @@
+// session/identity.ts — the OWNER of the attached node's canvas identity
+// (kind/mode/lifecycle/icon), which the editor's context badge and title chip
+// render from.
+//
+// It is the one connection fact that is NOT fixed at connect time: a remote
+// attach starts without an identity and fills it in from the relayed canvas,
+// and a fresh broker or regenerated title can reflect a new persona, lifecycle,
+// or task icon. Hence an owner with a refresh verb rather than a value on
+// `AttachSession`.
+export function createNodeIdentity(ctx, initial, hooks) {
+    let identity = initial;
+    return {
+        current: () => identity,
+        refresh: () => {
+            void ctx.canvasSource
+                .getNode(ctx.nodeId)
+                .then((node) => {
+                if (hooks.isTornDown() || node === null)
+                    return;
+                identity = node;
+                hooks.onChanged();
+            })
+                .catch(() => undefined);
+        },
+    };
+}

package/dist/clients/attach/session/input-wiring.d.ts

@@ -0,0 +1,53 @@
+import { InputController } from '../input/controller.js';
+import type { FrecencyStore } from '../input/completion-frecency.js';
+import { type ViewerCapabilities } from '../input/capabilities.js';
+import type { ToolDisplayToggle } from '../render/chat-view.js';
+import type { KeybindingsManager } from '@earendil-works/pi-tui';
+import type { CopyTarget } from '../render/transcript-copy.js';
+import type { AttachSession } from './context.js';
+/** What the input layer needs from the rest of the session. Everything here is
+ *  a getter or a command — never a value — so nothing can go stale. */
+export interface InputWiringHooks {
+    /** Transient footer message. */
+    setNotice: (message: string) => void;
+    /** pi's agent dir from the live `welcome` state, for the auth pickers.
+     *  `undefined` before the first welcome → they fall back to the local default. */
+    agentDir: () => string | undefined;
+    /** True while the reconnect supervisor has classified the node as dormant. */
+    isDormant: () => boolean;
+    /** Copy a viewer-local transcript target and surface its confirmation. */
+    copyTarget: (target: CopyTarget) => void;
+    /** Ctrl+O — toggles either collapsed summaries or tool-output expansion. */
+    toggleToolsExpanded: () => ToolDisplayToggle;
+    /** `/fold-tools` — flip the fold-finished-tool-calls view setting; returns the
+     *  new state. */
+    toggleFoldTools: () => boolean;
+    /** `/show-working` — expand or fold each consolidated reply's working; returns
+     *  the new state, or null when consolidated replies are off. */
+    toggleShowWorking: () => boolean | null;
+    /** Ctrl+T — flip thinking-block visibility; returns true when now HIDDEN. */
+    toggleThinking: () => boolean;
+    /** `/graph` and the graph keybinding. */
+    toggleGraph: () => void;
+    /** `/inbox` and the inbox attach control. */
+    toggleInbox: () => void;
+    /** `/hotkeys` and the help keybinding. */
+    toggleHelp: () => void;
+    /** `/mouse` — flip mouse wheel reporting and return the new state. */
+    toggleMouse: () => boolean;
+    /** `/node-metadata` — open the viewer-owned Inspector dossier popup. */
+    openNodeMetadata: () => void;
+    /** `/quit` — detach this viewer; the engine keeps running. Must tear down
+     *  locally, since a bare `bye` would just trigger the reconnect loop. */
+    quit: () => void;
+    /** `/color` — recolor the editor's name chip (`null` clears to default). */
+    setChipColor: (color: string | null) => void;
+    /** A prompt or steer was accepted from the editor. */
+    onPromptSent: () => void;
+    /** Per-user completion frecency store, shared with the editor inventory. */
+    frecency: FrecencyStore;
+}
+/** Construct the viewer's one capability authority. */
+export declare function createViewerCapabilitiesForInput(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta'>, isBrokerOffline: () => boolean): ViewerCapabilities;
+/** Build the viewer's InputController with every hook answered. */
+export declare function createInputController(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'socket' | 'tui' | 'editor' | 'containers'>, km: KeybindingsManager, capabilities: ViewerCapabilities, hooks: InputWiringHooks): InputController;

package/dist/clients/attach/session/input-wiring.js

@@ -0,0 +1,146 @@
+// session/input-wiring.ts — the wiring harness for the input layer.
+//
+// `InputController` (input/controller.ts) is deliberately layout- and
+// canvas-agnostic: it takes ~20 optional hooks and no ambient knowledge. This
+// file is the ONLY place that answers each of them for the attach viewer, so
+// "what does /copy actually do here?" or "where does a picker get mounted?" has
+// one address instead of being a 130-line object literal wedged into runAttach.
+//
+// A few small behaviors live here rather than in the orchestrator because they
+// have exactly one caller — the hook itself: the clipboard copy, the two
+// display-toggle notices, the dormant wake-message send, and the two auth
+// pickers (which need a reference to the controller being constructed, so they
+// can only be closed over from inside).
+import { InputController } from '../input/controller.js';
+import { createViewerCapabilities } from '../input/capabilities.js';
+import { cliClient } from '../../../commands/api-client.js';
+import { buildLoginPicker, buildLogoutPicker } from '../overlays/auth.js';
+import { defaultAgentDir } from '../config.js';
+/** Construct the viewer's one capability authority. */
+export function createViewerCapabilitiesForInput(ctx, isBrokerOffline) {
+    return createViewerCapabilities({
+        nodeId: ctx.nodeId,
+        profileId: ctx.meta.profile_id ?? undefined,
+        remote: ctx.remote,
+        role: ctx.role,
+        isBrokerOffline,
+    });
+}
+/** Build the viewer's InputController with every hook answered. */
+export function createInputController(ctx, km, capabilities, hooks) {
+    const { nodeId, socket, tui, editor, containers } = ctx;
+    const { setNotice } = hooks;
+    // Auth pickers — viewer-local OAuth/API-key flows against the SAME auth.json
+    // the broker uses (broker + viewer share a filesystem in the tmux-local attach
+    // model), so they run entirely in this process and then tell the broker to
+    // reload with a `reload_auth` frame.
+    //
+    // A read-only viewer wires NEITHER. A REMOTE attach (`--canvas`) disables both
+    // because they target the LOCAL `auth.json` via `defaultAgentDir()`, the wrong
+    // host for a remote node; an OBSERVER because
+    // switching credentials and telling the broker to reload them mutates the
+    // engine's auth, which a read-only viewer must not do. Unwired here means the
+    // slash context carries no picker at all, so `/login` and `/logout` report
+    // themselves unavailable rather than reaching a `reload_auth` frame.
+    const reloadAuth = () => socket.send({ type: 'reload_auth' });
+    const authPickers = !capabilities.permits('auth')
+        ? {}
+        : {
+            openLoginPicker: () => {
+                const dir = hooks.agentDir() ?? defaultAgentDir();
+                void input.openAuthPicker(() => buildLoginPicker(tui, dir, reloadAuth, (m) => setNotice(m)));
+            },
+            openLogoutPicker: () => {
+                const dir = hooks.agentDir() ?? defaultAgentDir();
+                void input.openAuthPicker(() => buildLogoutPicker(dir, reloadAuth, (m) => setNotice(m)));
+            },
+        };
+    const input = new InputController(tui, editor, km, {
+        onCommand: (frame) => socket.send(frame),
+        onDialogResponse: (resp) => socket.send(resp),
+        onNotice: (msg) => setNotice(msg),
+        // The slash context: `/promote` targets this node, `/resume-node` opens
+        // scoped to its profile, `remote` structurally omits the local-only
+        // canvas commands, and `/graph` toggles the overlay.
+        onGraph: hooks.toggleGraph,
+        onInbox: hooks.toggleInbox,
+        onHelp: hooks.toggleHelp,
+        onNodeMetadata: hooks.openNodeMetadata,
+        onQuit: hooks.quit,
+        onCopy: () => hooks.copyTarget('last-assistant'),
+        onCopyTarget: hooks.copyTarget,
+        onToggleMouse: () => {
+            const on = hooks.toggleMouse();
+            setNotice(on ? 'Mouse: wheel scrolling on, drag to select and copy' : 'Mouse: off — tmux drag-select and copy-mode restored');
+        },
+        onColor: hooks.setChipColor,
+        onPromptSent: hooks.onPromptSent,
+        frecency: hooks.frecency,
+        knownRefNames: () => editor.getResolvedRefNames(),
+        // Global display toggles (Ctrl+O tools / Ctrl+T thinking) — pure render
+        // state owned by ChatView, surfaced as a footer notice mirroring pi's
+        // status line.
+        onToggleToolsExpand: () => {
+            const result = hooks.toggleToolsExpanded();
+            setNotice(result.kind === 'summaries'
+                ? result.shown ? 'Tool calls: summarized' : 'Tool calls: shown'
+                : result.expanded ? 'Tool output: expanded' : 'Tool output: collapsed');
+        },
+        onFoldTools: () => setNotice(hooks.toggleFoldTools()
+            ? 'Finished tool calls: folded to one line'
+            : 'Finished tool calls: shown in full'),
+        onShowWorking: () => {
+            const shown = hooks.toggleShowWorking();
+            setNotice(shown === null
+                ? 'Consolidated replies are off (crtr sys config set consolidate_replies --value true, then re-attach)'
+                : shown ? 'Working: shown' : 'Working: hidden behind each reply');
+        },
+        onToggleThinking: () => setNotice(hooks.toggleThinking() ? 'Thinking blocks: hidden' : 'Thinking blocks: visible'),
+        // The correlated read-op channel the native pickers (/model, /resume,
+        // /fork, /tree, /settings, /scoped-models) fetch their payloads over.
+        // Without it every picker degrades to the "isn't available in this viewer"
+        // notice (see slash/dispatch.ts + InputController.openPicker).
+        onRequest: (frame) => {
+            const refusal = capabilities.refusal('engine-drive');
+            return refusal === undefined ? socket.request(frame) : Promise.reject(new Error(refusal));
+        },
+        // Mount pickers inline in the chrome stack, directly under the editor
+        // (queued-panel pattern) rather than as a floating centered modal, so a
+        // picker reads as part of the editor — like pi's own selectors.
+        onMountPicker: (component) => {
+            containers.pickerPanel.addChild(component);
+            tui.requestRender();
+        },
+        onUnmountPicker: () => {
+            containers.pickerPanel.clear();
+            tui.requestRender();
+        },
+        // Dormant-node input: the node has no live broker, so a submitted prompt
+        // cannot reach a socket. The reconnect supervisor reports dormancy and the
+        // text is delivered as a wake message (revive + deliver) instead, so the
+        // still-open input box just works. Writable local viewers only — a remote or
+        // observer attach leaves `onDormantSubmit` unwired, and
+        // prompts fall through. This is the one mutating path that never touches the
+        // broker (it goes to crtrd via `cliClient`), so leaving it wired for an
+        // observer would let a read-only viewer wake and message the node.
+        isDormant: hooks.isDormant,
+        onDormantSubmit: !capabilities.permits('wake-dormant') ? undefined : (msgText) => {
+            void (async () => {
+                try {
+                    // Text typed into a node's box IS the human talking to it — mark it
+                    // `from: 'human'` so it wakes the node and lands as a plain user turn
+                    // (verbatim, no "From … — N updates" digest; see coalesce()), exactly
+                    // like the live path. NOT `CRTR_NODE_ID`: direct keyboard input is
+                    // the human, not whatever node owns the shell that launched us.
+                    const res = await cliClient().sendMessage(nodeId, { body: msgText, from: 'human' });
+                    setNotice(res.revived ? '↻ waking node…' : '✉ delivered — node reads on next wake');
+                }
+                catch (err) {
+                    setNotice(`Couldn't wake node: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            })();
+        },
+        ...authPickers,
+    }, capabilities);
+    return input;
+}

package/dist/clients/attach/session/invariant.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The viewer owns the whole pane, so an invariant must never be written to the
+ * terminal: console output lands in the middle of the rendered frame, and a
+ * violation that repeats every render pushes real content into tmux scrollback
+ * — the exact corruption these invariants exist to catch. Records go to a
+ * rotating log beside the daemon's, one line per report:
+ * `~/.crouter/canvas/attach-invariants.log` (`CRTR_HOME`-relative).
+ */
+export declare function reportInvariant(scope: string, message: string): void;

package/dist/clients/attach/session/invariant.js

@@ -0,0 +1,15 @@
+import { join } from 'node:path';
+import { crtrHome } from '../../../core/canvas/paths.js';
+import { appendRotatingRecord } from '../../../core/log.js';
+/**
+ * The viewer owns the whole pane, so an invariant must never be written to the
+ * terminal: console output lands in the middle of the rendered frame, and a
+ * violation that repeats every render pushes real content into tmux scrollback
+ * — the exact corruption these invariants exist to catch. Records go to a
+ * rotating log beside the daemon's, one line per report:
+ * `~/.crouter/canvas/attach-invariants.log` (`CRTR_HOME`-relative).
+ */
+export function reportInvariant(scope, message) {
+    const line = `${new Date().toISOString()} ${scope} ${message}`.replaceAll(/[\r\n]/g, ' ');
+    appendRotatingRecord(join(crtrHome(), 'attach-invariants.log'), line);
+}

package/dist/clients/attach/session/keys.d.ts

@@ -0,0 +1,46 @@
+import { type AttachBindings, type AttachViewportActions } from './bindings.js';
+import type { AttachSession } from './context.js';
+export interface KeyHooks {
+    /** The live binding snapshot — re-resolved by `/reload`, so read per key. */
+    bindings: () => AttachBindings;
+    /** How the user would spell the detach binding, for the clear-first hint. */
+    detachHint: () => string | undefined;
+    /** Terminal focus in/out — the roster owns the editor's cursor styling. */
+    setPaneFocused: (focused: boolean) => void;
+    /** Whether a full-pane surface should receive all non-control input. */
+    hasExclusiveSurface: () => boolean;
+    /** Scroll actions for this session's transcript viewport. */
+    viewportActions: () => AttachViewportActions;
+    /** Transcript search's chance at a chunk; true when it consumed it. It owns
+     *  typed characters while editing a query, so it runs ahead of the editor. */
+    searchHandleKey: (data: string) => boolean;
+    /** The inline ticket panel: while open it consumes EVERY chunk — pages
+     *  carry text inputs — so it runs ahead of search, scroll, and the lists. */
+    panelHandleKey: (data: string) => boolean;
+    /** The inbox strip's chance at a chunk; true when it consumed it. */
+    stripHandleKey: (data: string) => boolean;
+    /** The roster's chance at a chunk; true when it consumed it. */
+    rosterHandleKey: (data: string) => boolean;
+    setNotice: (message: string) => void;
+    detach: () => void;
+    /** Cancel the running turn (the second ctrl+c). Detach lives on its own binding. */
+    cancelTurn: () => void;
+    toggleGraph: () => void;
+    toggleHelp: () => void;
+    /** Toggle the mounted inbox surface. */
+    toggleInbox: () => void;
+    /** Enter or leave the top-of-pane pending-request strip. */
+    toggleInboxStrip: () => void;
+    cycleModelLadder: (direction: 'forward' | 'backward') => void;
+    inspectLoadedCommand: () => void;
+    /** The file-review chord — pick a transcript file and open its review window. */
+    openFileReview: () => void;
+    /** Search the current node's local profile project files. */
+    openProfileFiles: () => void;
+    /** Open incremental search over the displayed transcript. */
+    openSearch: () => void;
+    /** Play the whip animation and interrupt the focused agent with a command. */
+    whip: () => void;
+}
+/** Install the listener; returns the remover, which teardown MUST call. */
+export declare function installGlobalKeys(ctx: Pick<AttachSession, 'tui' | 'editor'>, hooks: KeyHooks): () => void;

package/dist/clients/attach/session/keys.js

@@ -0,0 +1,77 @@
+// session/keys.ts — the viewer's GLOBAL key listener.
+//
+// A TUI input listener fires BEFORE the focused component and before any dialog
+// overlay, so the configured attach actions work regardless of what has focus.
+// That privilege is also the hazard: anything consumed here never reaches the
+// editor. Only terminal focus reports, a private crouter control input,
+// viewport scroll bindings while the editor has focus, the roster while it holds
+// the cursor, and a configured crtr binding may claim a chunk; each returns
+// ordinary editor input untouched when it does not apply.
+import { extractAttachControlInput } from '../../../core/keybindings/index.js';
+import { dispatchAttachAction, dispatchAttachBinding, dispatchAttachViewportBinding, } from './bindings.js';
+import { FOCUS_IN, FOCUS_OUT } from './focus-events.js';
+/** Press the clear binding twice inside this window to cancel the running turn. */
+const CLEAR_OR_DETACH_MS = 1000;
+/** Install the listener; returns the remover, which teardown MUST call. */
+export function installGlobalKeys(ctx, hooks) {
+    const { tui, editor } = ctx;
+    let lastClearOrDetachAt = 0;
+    const actions = {
+        'crtr.attach.detach': hooks.detach,
+        'crtr.attach.clear-or-detach': () => {
+            const now = Date.now();
+            if (now - lastClearOrDetachAt < CLEAR_OR_DETACH_MS) {
+                lastClearOrDetachAt = 0;
+                hooks.cancelTurn();
+                return;
+            }
+            lastClearOrDetachAt = now;
+            editor.setText('');
+            hooks.setNotice(`Editor cleared — press ${hooks.detachHint()} again to cancel the agent`);
+            tui.requestRender();
+        },
+        'crtr.attach.graph.toggle': hooks.toggleGraph,
+        'crtr.attach.help.toggle': hooks.toggleHelp,
+        'crtr.attach.inbox.toggle': hooks.toggleInbox,
+        'crtr.attach.inbox-strip': hooks.toggleInboxStrip,
+        // A plain broker frame, so this works locally and remotely alike; the broker gates observers on controller role.
+        'crtr.attach.model-ladder.next': () => hooks.cycleModelLadder('forward'),
+        'crtr.attach.model-ladder.previous': () => hooks.cycleModelLadder('backward'),
+        'crtr.attach.command.inspect': hooks.inspectLoadedCommand,
+        'crtr.attach.file-review': hooks.openFileReview,
+        'crtr.attach.profile-files': hooks.openProfileFiles,
+        'crtr.attach.search': hooks.openSearch,
+        'crtr.attach.whip': hooks.whip,
+    };
+    return tui.addInputListener((data) => {
+        // Terminal focus reporting (DECSET 1004, enabled after tui.start; tmux forwards it per-pane with `focus-events on`). Pane focus drives the editor's fake cursor — solid block focused, hollow outline blurred — so a wall of attach panes shows exactly which one keys go to. The events are stripped rather than blanket-consumed in case the chunk coalesced them with real keystrokes.
+        if (data.includes(FOCUS_IN) || data.includes(FOCUS_OUT)) {
+            hooks.setPaneFocused(data.lastIndexOf(FOCUS_IN) > data.lastIndexOf(FOCUS_OUT));
+            tui.requestRender();
+            const rest = data.replaceAll(FOCUS_IN, '').replaceAll(FOCUS_OUT, '');
+            return rest.length > 0 ? { data: rest } : { consume: true };
+        }
+        const control = extractAttachControlInput(data);
+        if (control !== undefined) {
+            dispatchAttachAction(control.actionId, actions);
+            return control.remaining.length > 0 ? { data: control.remaining } : { consume: true };
+        }
+        if (hooks.hasExclusiveSurface())
+            return undefined;
+        if (hooks.panelHandleKey(data))
+            return { consume: true };
+        if (hooks.searchHandleKey(data))
+            return { consume: true };
+        // Let focused pickers and overlays retain their native page navigation.
+        if (editor.focused && dispatchAttachViewportBinding(hooks.bindings(), data, hooks.viewportActions()))
+            return { consume: true };
+        // Inline subagent scroll+swap: once the editor hands off at its ↓ boundary, ↑/↓ move over the manager/report roster and Enter dives into a node. An inactive roster never intercepts editor input.
+        // The inbox strip while it holds the highlight — ahead of the roster, whose
+        // rows the same arrows would otherwise move.
+        if (hooks.stripHandleKey(data))
+            return { consume: true };
+        if (hooks.rosterHandleKey(data))
+            return { consume: true };
+        return dispatchAttachBinding(hooks.bindings(), data, actions) ? { consume: true } : undefined;
+    });
+}

package/dist/clients/attach/session/layout.d.ts

@@ -0,0 +1,22 @@
+import { Container, type Component, type KeybindingsManager, type ProcessTerminal, type TUI } from '@earendil-works/pi-tui';
+import type { AttachPalette } from '../config.js';
+import { TitledEditor } from '../input/titled-editor.js';
+import type { TranscriptViewport } from '../render/viewport.js';
+import type { AttachContainers } from './context.js';
+import { ViewerFrame } from './frame.js';
+export interface AttachLayout {
+    /** The process terminal behind the TUI — also the owner of the window title
+     *  and the negotiated keyboard protocol, both of which the orchestrator uses. */
+    readonly procTerminal: ProcessTerminal;
+    readonly tui: TUI;
+    readonly containers: AttachContainers;
+    readonly editor: TitledEditor;
+    readonly frame: ViewerFrame;
+    /** Attach the single frame to the TUI and focus the editor. Deferred to just
+     *  before `tui.start()` so a signal landing mid-construction cannot leave a
+     *  half-mounted tree on screen. */
+    mount(): void;
+}
+/** Build the layout around the transcript viewport. The viewer creates the
+ * terminal and chat first because the viewport measures that chat source. */
+export declare function createLayout(procTerminal: ProcessTerminal, tui: TUI, chat: Container, activity: Container, pal: AttachPalette, km: KeybindingsManager, viewport: TranscriptViewport, searchBar: Component): AttachLayout;