dsh-ssh-tui 0.8.3 → 0.8.4-rc.1

package/lib/types/dsh-compat.d.ts

@@ -9,9 +9,10 @@
  * here picks the API that is actually present so one build runs on either
  * host line.
  */
+import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { ContextFormed } from '@deepseek-ai/dsh-llm';
-import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import type z from '@deepseek-ai/schemastery';
 /**
@@ -294,3 +295,21 @@ export declare function streamChunkOf(frame: unknown, fallback?: {
 export declare function listenHostEvent(ctx: {
     on: (event: never, handler: never) => unknown;
 }, event: string, handler: (...args: unknown[]) => unknown): () => void;
+/**
+ * Wind down the selected direct children of one parent, under both names the
+ * subagent service has shipped.
+ *
+ * 0.2.1-rc.2 renamed `drainContinuableChildren(parent, childIds)` to
+ * `drainChildren(parent, childIds)` — same contract (release the selected
+ * resident direct children of one exact live parent, leaving its other children
+ * admitted). Both 0.2.0 rcs and 0.2.1-rc.2 are declared, so the call site asks
+ * for whichever spelling the host has instead of pinning one and failing to
+ * compile on the other. A composition without the service at all resolves: the
+ * caller has already handled "no service", and this keeps the helper total.
+ *
+ * @param subagents - the host's subagent service.
+ * @param parent - the exact live parent whose children are being released.
+ * @param childIds - durable direct-child ids to release when resident.
+ * @returns once every selected activation released its execution handle.
+ */
+export declare function drainChildSubagents(subagents: Context['subagents'], parent: Agent, childIds: readonly SessionId[]): Promise<void>;

package/lib/types/footer-budget.d.ts

@@ -83,15 +83,6 @@ export interface FooterStripInput {
         long: string;
         short: string;
     };
-    /**
-     * The Host-local echo: the last thing this Host confirmed to the reader
-     * (`/theme` switched, a preset saved, a copy landed).
-     *
-     * Not history (AD-13) and not telemetry: it is an acknowledgement, so it is the
-     * lowest-priority chip on the row — the first thing a narrow terminal gives up, and
-     * never at the cost of the link, the activity, the quota or the context reading.
-     */
-    echo?: string;
     /** Whether the terminal must be painted with ASCII glyphs. */
     ascii?: boolean;
     /** Colour depth the accents are downgraded for. */

package/lib/types/input-reader.d.ts

@@ -0,0 +1,198 @@
+/**
+ * How long a read that could still grow into a sequence is held.
+ *
+ * The window is what makes a lone `ESC` (the reader pressed Escape) different from
+ * the first byte of a sequence the terminal is still sending. W-1 moved the timer,
+ * not the number: changing it changes how Escape feels, and that is a separate
+ * decision with its own evidence.
+ */
+export declare const ESCAPE_HOLD_MS = 60;
+/**
+ * One framed unit of input.
+ *
+ * The vocabulary is deliberately small — four kinds carry text, one carries the
+ * released Escape, one carries a device reply — because the Reader's job is to say
+ * *what arrived*, not what it means. `key` and `burst` reach the same routing today;
+ * they are distinguished because the Router (W-2) has to decide "one key" versus
+ * "several keys in one read" (the read-coalescing gaps G-1/G-2 live exactly there).
+ */
+export type InputFrame = 
+/** One complete terminal unit: a control byte, a full CSI sequence, or a lone ESC. */
+{
+    kind: 'key';
+    sequence: string;
+}
+/** A read of ordinary typing. It may carry several keys — W-3 splits it. */
+ | {
+    kind: 'burst';
+    text: string;
+}
+/** Text to be typed exactly as it is (a sequence tail, an Alt remainder, a release). */
+ | {
+    kind: 'literal';
+    text: string;
+}
+/** The payload between paste markers. */
+ | {
+    kind: 'paste';
+    text: string;
+}
+/** The held read turned out to be the Escape key itself. */
+ | {
+    kind: 'escape';
+}
+/** A device reply (cursor position) — input to the prober, never to an owner. */
+ | {
+    kind: 'reply';
+    sequence: string;
+};
+export interface InputReaderOptions {
+    /** A read that survived decoding and reply filtering. */
+    onRead: (text: string) => void;
+    /** A frame the Reader produced on its own: paste traffic, or a released hold. */
+    onFrame: (frame: InputFrame) => void;
+    /**
+     * How long a stalled paste may hold the reader before it is abandoned.
+     *
+     * A seam for tests only — the default is the release value. A test that waited the
+     * real two seconds kept a whole file's process alive alongside the others and was
+     * enough to unbalance a timer-sensitive paint test on a Windows runner.
+     */
+    pasteMarkerHoldMs?: number;
+}
+/**
+ * How long a paste may sit with half a marker before the reader gives up on it.
+ *
+ * This is a watchdog, not a key hold: a paste is a stream, and its close marker may
+ * arrive in a second chunk after a slow terminal, a ConPTY or a loaded runner — on
+ * Windows CI the gap was over 200 ms, and expiring that early typed the marker's tail
+ * into the draft and left the session inside the paste. So the window is generous.
+ * When it does expire the reader does not just release the tail as payload, it
+ * **leaves the paste**: a paste that never closed must not keep the keyboard as its
+ * payload for the rest of the session.
+ */
+export declare const PASTE_MARKER_HOLD_MS = 2000;
+export declare class InputReader {
+    private readonly options;
+    private readonly decoder;
+    private readonly guard;
+    /** A read that may still grow (escape assembly). */
+    private held;
+    private holdTimer;
+    /** Inside `ESC[200~ … ESC[201~`. */
+    private inPaste;
+    /**
+     * The tail of a read that ended *inside* a paste marker (`…ESC[20`), waiting for
+     * its other half.
+     */
+    private pasteTail;
+    private pasteTailTimer;
+    constructor(options: InputReaderOptions);
+    /** One read of bytes: decode it, drop device replies, hand the rest on. */
+    push(chunk: Buffer): void;
+    /** The read with any held prefix in front of it. The hold window is over. */
+    assemble(text: string): string;
+    /**
+     * The frames of one read, whichever kind it is.
+     *
+     * A read is what the terminal happened to send, not what the reader pressed: a
+     * fast typist, a slow link or ConPTY can put several keys in one read. This is the
+     * one place that decides where one unit ends and the next begins; everything above
+     * it (Router, owners) sees complete units only, and nothing above it re-parses the
+     * bytes (AD-20 §4.4, §6).
+     */
+    read(text: string): InputFrame[];
+    /**
+     * Frame one paste read, holding back a marker it cut in half.
+     *
+     * A terminal writes bytes, not reads: `ESC[201~` can arrive as `…ESC[20` and `1~`.
+     * Framed naively, the first read swallows `ESC[20` as payload and the second one
+     * carries no marker at all — so `inPaste` never clears and **every later key is
+     * pasted text**: Esc stops closing a dialog, `/exit` stops exiting. Found by
+     * `scripts/tui-paste-probe.mjs` on CI, where the pty chunked the write exactly
+     * there. The fix is the same rule the escape ladder already uses — a read that
+     * could still grow is held, and released as payload if its other half never comes.
+     */
+    private framePaste;
+    private armPasteTail;
+    private cancelPasteTail;
+    /**
+     * One non-paste read, split into complete units.
+     *
+     * The rules, and why each one exists:
+     *
+     *   - **A complete CSI/SS3 sequence is one unit.** `ESC [ 5 ~ ESC [ 5 ~` is two page
+     *     keys, not one unnameable read (G-1). A sequence the read cuts short stays one
+     *     piece: `hold()` has already claimed it if it could still grow, and a trailing
+     *     `ESC [` must reach the hold again rather than be split into `ESC` + `[`.
+     *   - **An Alt chord is one unit.** `ESC` plus exactly one printable character is
+     *     Alt+that key, so `ESC 1 x` is the chord Alt+1 *and then* `x` — never the text
+     *     `1x` (G-3), and never a chord that swallows the character behind it.
+     *   - **A control byte is one unit, CR/LF pair as one Enter.** `\x10\x10` is two
+     *     presses of a rebound key (G-2/G-8), and Windows' CRLF is one key.
+     *   - **A run of ordinary characters is one unit.** Splitting typing per character
+     *     would make a pasted `yes` answer a confirm dialog character by character,
+     *     which is the boundary W-0 pinned (`yes-typed-at-dialog`). Keymap lookup on a
+     *     whole run is still exactly what a run means: text.
+     *   - **A burst the paste heuristic claims stays whole.** A console without
+     *     bracketed paste sends a paste as ordinary bytes with line breaks in them;
+     *     that read has to reach the paste path intact (`looksLikePasteBurst`).
+     */
+    units(text: string): InputFrame[];
+    /**
+     * Whether a read is paste traffic: inside a paste, or carrying a marker.
+     *
+     * Asked before anything else, exactly as the inline check it replaces was: while
+     * inside a paste, CR/LF are literal characters rather than submit.
+     */
+    isPasteTraffic(combined: string): boolean;
+    /**
+     * The frames of one paste read, in order: payload inside the markers as `paste`,
+     * everything outside them as `literal` (which is what the inline version typed
+     * directly, without a keymap lookup).
+     *
+     * Only complete markers are handled here: `framePaste` holds back a read that ends
+     * inside one, because a marker whose two halves land in two reads would otherwise
+     * leave the reader inside the paste for the rest of the session.
+     */
+    frames(combined: string): InputFrame[];
+    /**
+     * Keep a read that could still grow into a sequence.
+     * @returns true when it was held (the caller stops there), false when the read is
+     *   complete as it stands.
+     */
+    hold(combined: string): boolean;
+    /**
+     * Whether one read is a paste from a console that cannot say so.
+     *
+     * A burst carrying more than one line break is not a human pressing Enter twice —
+     * they cannot press it twice inside one read. This is the fallback's one rule, and
+     * it lives here so every caller applies the same one.
+     */
+    static looksLikePasteBurst(text: string): boolean;
+    /** Whether a complete read is a device reply rather than input. */
+    isDeviceReply(text: string): boolean;
+    /** Classify one complete read by shape. */
+    classify(text: string): InputFrame;
+    /**
+     * Hand over a held reply tail now.
+     *
+     * The guard releases on its own window; this is for a caller that already knows
+     * the tail is stale — `scripts/bench-b2.mjs` drives keystrokes faster than the
+     * hold, and a measurement that waited for the window would be measuring the wait.
+     */
+    releaseReplyTail(): void;
+    /** Drop the holds and the reply filter (display detached, teardown). */
+    stop(): void;
+    private cancelHold;
+    /**
+     * What a held read turned out to be.
+     *
+     * Verbatim from the inline timer it replaces: a lone `ESC` is the Escape key, an
+     * `ESC O` without its final byte is Alt+O, an escape sequence that never completed
+     * is consumed silently (its `ESC` must not read as a cancel), and anything else is
+     * typed. The last branch is unreachable for the shapes `isEscapePrefix` accepts —
+     * it is kept because "unreachable today" is not a reason to change a release.
+     */
+    private releaseHold;
+}

package/lib/types/input-router.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The InputRouter: one unit in, exactly one owner out.
+ *
+ * W-1 taught the TUI *what arrived* (`InputFrame`). This module answers the other
+ * question — *who takes it* — and it is the only place that may. The four owners
+ * (Screen, Surface, Composer, Workspace) each have an adapter in `tui.ts`; an
+ * adapter may read its own state, but it may not decide cross-owner ownership
+ * again, and it may not hand a unit on to the next owner when it does not use it
+ * (AD-20 §4.3, §4.5 F-1/F-6).
+ *
+ * The decision is a pure function of `(unit kind, unit, ownership snapshot)`: no
+ * app state is read or written, nothing is painted, no transcript row is pushed,
+ * and the snapshot is a plain object the caller keeps and overwrites, so a
+ * keystroke costs no allocation (W-2 is a hot-path migration).
+ *
+ * The rules are the ones `tui.ts` already applied inline, moved here verbatim —
+ * including one asymmetry that is **recorded debt, not a decision**:
+ *
+ *   1. `Ctrl+L` is handled by the Screen when a Screen is up and by the Composer
+ *      otherwise; the repaint has two implementations and W-2 does not merge them
+ *      (AD-20 §6: only a test that proves both owners repaint identically may).
+ *      W-3b.2 owns that one.
+ *
+ * W-3b.1 closed the other asymmetry this module used to record:
+ * `SURFACE_COMPOSER_KEYS` sent `Home`/`End`/`Delete`/kitty-`Ctrl+Shift+C` to the
+ * composer while a Surface was up. The Surface owns them now, like every other unit,
+ * and its adapter decides what they mean — the field it borrowed, or nothing.
+ *
+ * @module dsh-ssh-tui/input-router
+ */
+/** Who takes a unit. Exactly one of these, per unit, decided here. */
+export type Owner = 'screen' | 'surface' | 'composer' | 'workspace';
+/**
+ * The unit classes the ladder dispatches.
+ *
+ * `text` and `control` are the composer's own shapes, `sequence` is a complete
+ * CSI/SS3 unit, `paste` is a payload with its markers already off, and `escape` is
+ * the released lone Escape. `burst` frames never reach this module as a whole: the
+ * ladder types them character by character, so every character is routed on its own
+ * (which is also what lets a Surface answer `y` and the composer take the `es`).
+ */
+export type UnitKind = 'text' | 'control' | 'sequence' | 'paste' | 'escape';
+/** The read-only ownership state a decision may look at. */
+export interface OwnershipSnapshot {
+    /** The Screen that is up, if any (its kind, for reports). */
+    screenKind: string | undefined;
+    /** The Surface (dialog) that is up, if any. */
+    surfaceKind: string | undefined;
+    /**
+     * …and whether that Surface owns a borrowed text field.
+     *
+     * Part of the contract's vocabulary, and no rule branches on it since W-3b.1:
+     * whether a Surface borrowed a field decides what its *adapter* does with an
+     * editing key, not who owns the key.
+     */
+    surfaceHasField: boolean;
+    /** The composer's field is empty — the focus ring's precondition. */
+    composerEmpty: boolean;
+    /** The transcript has collapsible cards — the focus ring's other precondition. */
+    workspaceCards: boolean;
+}
+export declare class InputRouter {
+    /** The one cross-owner decision. One unit in, one owner out. */
+    route(kind: UnitKind, unit: string, view: OwnershipSnapshot): Owner;
+    /**
+     * With nothing layered over the workspace, the Composer owns text and its editing
+     * keys, and the Workspace owns the transcript: the mouse, the page keys, and the
+     * focus ring — which an arrow reaches only while the field is empty and there is a
+     * card to land on (otherwise the same arrow browses history, and history is the
+     * composer's).
+     */
+    private composerOrWorkspace;
+}

package/lib/types/terminal-input.d.ts

@@ -37,10 +37,24 @@ export declare function stripCursorReplies(text: string): {
  * typed. A read that ends in the middle of a possible reply is held back (see
  * `flush()`) so `ESC [ 1` + `7;1R` cannot become visible digits either.
  */
+export interface TerminalInputFilterOptions {
+    /**
+     * Whether a read is bracketed-paste traffic.
+     *
+     * The filter asks instead of sniffing the markers itself: paste framing has one
+     * owner (the Reader), and a marker literal here would be a second one. It matters
+     * because a paste's close marker ends in `ESC[20` — the shape of a half-arrived
+     * cursor reply — so holding that tail cuts the marker in half and the Reader stays
+     * inside the paste for the rest of the session.
+     */
+    isPasteTraffic?: (text: string) => boolean;
+}
 export declare class TerminalInputFilter {
+    private readonly options;
     private held;
     /** The most recent cursor reply this filter swallowed, if any. */
     lastReply: string | undefined;
+    constructor(options?: TerminalInputFilterOptions);
     push(text: string): {
         forward: string;
         replies: number;
@@ -60,7 +74,7 @@ export declare class TerminalInputGuard {
     private readonly holdMs;
     private readonly filter;
     private timer;
-    constructor(emit: (text: string) => void, holdMs?: number);
+    constructor(emit: (text: string) => void, holdMs?: number, options?: TerminalInputFilterOptions);
     /** Feed one decoded read; anything that is not a reply reaches `emit`. */
     push(text: string): void;
     /** Hand a half-arrived sequence over (its window passed; it is typing). */

package/lib/types/tui.d.ts

@@ -229,7 +229,6 @@ export declare class SshTui {
     private input;
     private cursor;
     private inputFolded;
-    private inPaste;
     private history;
     private historyIndex;
     /** Live input parked while browsing history with ↑. Restored by ↓ past the newest item. */
@@ -375,7 +374,6 @@ export declare class SshTui {
     private readonly onReattach;
     private readonly onDetach;
     private renderTimer;
-    private readonly decoder;
     private readonly color;
     private readonly maxToolOutputLines;
     private readonly showReasoning;
@@ -650,8 +648,6 @@ export declare class SshTui {
      * `turn/start` is the only thing that resets it.
      */
     private reasoningExpandedChoice;
-    private escapeBuffer;
-    private escapeTimer;
     /**
      * How long an acknowledgement or a warning stays on the chrome.
      *
@@ -666,11 +662,19 @@ export declare class SshTui {
     private feedbackTtlMs;
     private feedbackTimer;
     /**
-     * Cursor-position replies removed from the relay's stdin stream. A launcher
-     * from an older release (or a reply that raced its own probe) would otherwise
-     * type `[17;1R` into the prompt or cancel a dialog with a bare ESC.
+     * The input Reader (AD-21): decoding, reply filtering, escape assembly, paste
+     * framing and unit classification live there; the frames come back through
+     * `handleInputText` / `consumeFrame`, which own the routing and the semantics.
      */
-    private readonly inputGuard;
+    private readonly reader;
+    /**
+     * The Router (AD-22, W-2): the one place a unit's owner is decided.
+     *
+     * `ownershipView` is the read-only snapshot it answers from — one object, rewritten
+     * per decision, so a keystroke allocates nothing (W-2 is a hot-path migration).
+     */
+    private readonly router;
+    private readonly ownershipView;
     private thinkingStartedAt;
     private waitStartedAt;
     /**
@@ -700,6 +704,15 @@ export declare class SshTui {
     private cwdChipRow;
     /** Set when a card expand/collapse moves chrome; next paint full-redraws. */
     private forceFullPaint;
+    /**
+     * How many times the Screen has been dismissed.
+     *
+     * A read is not a key: its units are delivered one at a time, and a Screen owns the
+     * read it was sent — once it is gone the rest is dropped (0.8.3's rule, W-3a keeps
+     * it). Counting dismissals rather than comparing the Screen object keeps that check
+     * out of the owner-read ratchet, which exists to stop new *ownership* reads.
+     */
+    private screenDismissals;
     /** Highest row the last budgeted frame could not paint, resumed next tick. */
     private paintResume;
     /** How many times a display has come back after a drop in this Host's life. */
@@ -1765,6 +1778,16 @@ export declare class SshTui {
     private setField;
     /** Insert at the caret of whichever field owns the keyboard. */
     private insertIntoField;
+    /**
+     * Move the caret of whichever field owns the keyboard to one end (Home/End).
+     *
+     * One implementation for the two owners that carry these keys (W-3b.1): the composer
+     * edits the draft, a Surface with a borrowed field edits the answer, and a Surface
+     * without one has nothing to move — `textIsEditable` is what says which of those the
+     * keyboard is on. Ctrl+A/Ctrl+E reach the same two positions through `composerUnit`,
+     * which asks the same question.
+     */
+    private moveFieldCursor;
     /** One card's key: a call's batch can repeat a question id across calls. */
     private questionCardKey;
     /**
@@ -2156,9 +2179,125 @@ export declare class SshTui {
     private scrollScreenTo;
     /** The copy key inside a Screen: what the Screen shows is what the reader means. */
     private copyFromScreen;
+    /**
+     * One read, as the Reader framed it: paste traffic is dispatched per frame,
+     * everything else is routed (W-2 lifts the routing itself into a Router).
+     */
     private handleInputText;
-    /** Handle one data chunk that may contain bracketed-paste markers. */
-    private processPasteChunk;
+    /** One framed unit, at the owner that takes it. */
+    private consumeFrame;
+    /**
+     * One read from the Reader, as the ladder has always taken it.
+     *
+     * Two kinds of table live here and they are not the same thing:
+     *
+     *   - **binding** — which byte means which action (the keymap's rebindable actions,
+     *     the Alt chords, the SS3 tail). Those stay; AD-20 F-5 wants one table per key.
+     *   - **ownership** — who takes the unit. That question is the Router's now, and it
+     *     is asked exactly once per unit, before any binding table is consulted: a
+     *     Screen owns the read outright, so the tables below are for the unlayered case,
+     *     which is the order the ladder always had.
+     *
+     * The parsing branches that are neither (a read that could still grow — the Reader
+     * holds it; an escape sequence nobody claimed — dropped) stay here as well.
+     */
+    private route;
+    /**
+     * The Router's read-only view, rewritten per decision (no allocation).
+     *
+     * The card question is the only expensive one — `collapsibleRows()` walks the
+     * visible transcript — so it is answered only for the arrow that asks it, and only
+     * when nothing is layered over the workspace.
+     */
+    private observe;
+    /**
+     * Whether a read is one of the sequence shapes the ladder claims as a whole.
+     *
+     * These are matched *before* the Reader's hold window — the order the ladder always
+     * had (`ESC [ 5 ~` is a page key, not a prefix that might still grow).
+     */
+    private isSequenceShape;
+    /** The unit class of one read, by shape (the Reader's classification, allocation-free). */
+    private readKind;
+    /** The unit class of one character — what `handleChar` routes. */
+    private charKind;
+    /** One unit, one owner: the Router decides, the owner adapter runs it. */
+    private dispatch;
+    /** Run a unit at the owner the Router already named. */
+    private dispatchWith;
+    /**
+     * A paste payload: the Router decides, the paste path executes.
+     *
+     * A paste is text, so the field that owns the keyboard takes it — and a Screen that
+     * owns the interaction terminates it (its own field or nothing), never a field
+     * behind it (AD-20 §4.3 priority 1). `handlePasteText` still re-asks that per owner;
+     * that is the compat path W-3 folds into the Router (marked there).
+     */
+    private dispatchPaste;
+    /**
+     * The Screen adapter: a Screen owns the keyboard outright (AD-20 §4.3 priority 3).
+     *
+     * One unit goes in — the Reader split the read, so a Screen sees the same keys the
+     * composer would (W-3a) and `handleScreenInput` is where the paste-burst rule stays.
+     * Its own `screen === undefined` guard stays too: a release raced by a teardown
+     * reaches it, and refusing there is the adapter's own business rather than a second
+     * ownership decision.
+     */
+    private ownerScreen;
+    /**
+     * The Surface adapter: a dialog owns the keyboard while it is up.
+     *
+     * Its arrows move a question's cursor (or nothing — an arrow a Surface does not use
+     * is not the transcript's), the page keys are not its business, and its mouse reports
+     * take the same path they always did so the refusal happens where it always did, down
+     * to the remembered press. Its own editing keys are `Home`/`End`/`Delete` (W-3b.1):
+     * they act on the field the Surface borrowed — the one row the reader can see — and a
+     * Surface that borrowed none has no field for them, so it consumes them. The kitty
+     * copy key falls out with the other sequences below: a Surface has no copy contract,
+     * and this round did not invent one. Everything else goes to the shared
+     * composer/Surface body, whose `dialog` branches are the Surface's own behaviour.
+     */
+    private ownerSurface;
+    /**
+     * The Composer adapter.
+     *
+     * Text — one character or many — is typed: the burst rule first, then one character
+     * at a time through the Router, which is what lets ownership change inside a single
+     * read (a Surface answering `y` with the composer taking the `es` behind it). The
+     * sequence shapes the composer owns are the arrows (the suggestion list, else
+     * history) and the caret keys — which it now only ever gets while it owns the
+     * keyboard: with a Surface up, the Router hands those keys to the Surface (W-3b.1).
+     */
+    private ownerComposer;
+    /**
+     * The Workspace adapter: the transcript owns the mouse, the page keys and the focus
+     * ring — and the ring only when the Router said so (empty field, a card to land on).
+     */
+    private ownerWorkspace;
+    /** An arrow the composer keeps: the suggestion list while it is up, else history. */
+    private arrowHistory;
+    /** Press, motion and release: selection, links and card toggles — the transcript's. */
+    private mouseGesture;
+    /**
+     * The composer/Surface body — the switch and the tail the ladder always had.
+     *
+     * It is shared by two adapters on purpose: its `dialog` guards *are* the Surface's
+     * behaviour for those keys (a borrowed field takes them, a field-less dialog refuses
+     * them), and splitting them is W-3's job. What the Router guarantees is that a Screen
+     * never reaches it, so every key below can only spend itself on a field the reader
+     * has in front of them — the composer's or a borrowed one. The unreachable second
+     * Screen gate the old body carried is gone with it (G-6).
+     */
+    private composerUnit;
+    /**
+     * Ctrl+L's repaint, in one place for the owners that share it (G-6).
+     *
+     * The Screen has its own implementation (`screenNeedsFullPaint`, because it repaints
+     * a Screen's frame); this one drops the cached rows so the next full frame is rebuilt
+     * from scratch. W-2 does not merge them — only a test that proves both owners repaint
+     * identically may (AD-20 §6) — but it does give the composer's copy a name.
+     */
+    private repaintNow;
     /**
      * Insert pasted text into the field that owns the keyboard; CR/LF are literal
      * newlines.
@@ -2199,6 +2338,14 @@ export declare class SshTui {
      */
     private textIsEditable;
     private handlePlainText;
+    /**
+     * One character, from a read or from the typing loop: the Router decides, again.
+     *
+     * It is asked per character rather than per read because ownership can change inside
+     * one read — a Surface that answers the first character of `yes` is gone for the rest
+     * (pinned by the `yes-typed-at-dialog` trace). A Screen never reaches the body below:
+     * the Router answered `screen` and the Screen adapter took the character.
+     */
     private handleChar;
     /**
      * Run one rebindable action.
@@ -2382,13 +2529,21 @@ export declare class SshTui {
      * inspect overlay owns the keyboard and takes no scroll at all: the transcript
      * behind a dialog must not move.
      */
-    private scrollActiveSurface;
+    private scrollWorkspace;
     private handleCtrlC;
     private submit;
     private runCommand;
-    /** Grapheme cluster immediately before `cursor`; cursor-internal positions delete it whole. */
+    /**
+     * Grapheme cluster immediately before `cursor`; cursor-internal positions delete it whole.
+     *
+     * The cluster is measured in the field that owns the keyboard, like `backspace` and
+     * `deleteAtCursor` above, which is what makes their ranges mean the same thing as the
+     * cursor they were handed (W-3b.1b): segmenting the *draft* while editing a borrowed
+     * answer gave offsets from another string, so a borrowed `a🚀` lost one surrogate and
+     * kept the caret inside the pair.
+     */
     private graphemeBefore;
-    /** Grapheme cluster containing or following `cursor`. */
+    /** Grapheme cluster containing or following `cursor`, in the field that owns the keyboard. */
     private graphemeAfter;
     /** Delete one grapheme back, in whichever field owns the keyboard. */
     private backspace;
@@ -2398,7 +2553,16 @@ export declare class SshTui {
     private moveCursor;
     private historyBack;
     private historyForward;
-    /** Typing while browsing history detaches from the saved item. */
+    /**
+     * Typing while browsing history detaches from the saved item.
+     *
+     * The browse is the **composer's**, so only the composer's own field may end it
+     * (W-3b.3a). Every editing key a Surface borrowed the field for arrives here —
+     * `backspace`, `deleteAtCursor`, `handlePasteText`, and `composerUnit`'s Ctrl+U /
+     * Ctrl+K — and detaching on that path wrote the hidden composer's state from the
+     * visible answer: the recalled entry replaced `historyDraft`, so the unsent draft
+     * the browse was holding could never be reached again with `↓`.
+     */
     private leaveHistoryBrowse;
 }
 /**