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

package/lib/tui.js

@@ -21,13 +21,14 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
-import { StringDecoder } from 'node:string_decoder';
 import { METADATA_FILE, readPresetMetadata } from './preset-compat.js';
 import { credentialRef } from '@deepseek-ai/dsh-credentials';
 import { createUserMessage, errorChain, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { commandAcceptsAttachments, forEachSessionEventAsync, hostSettingsGeneration, isTokenDeltaChunk, listenHostEvent, readSettingsSection, REPLAY_YIELD_EVERY, sessionEvents, settingsNamespace, streamChunkOf, streamFirstTokenTime, streamFrameAttemptId, streamFrameOwner, toolResultFailed, TUI_SOURCE_KIND, } from './dsh-compat.js';
+import { commandAcceptsAttachments, forEachSessionEventAsync, hostSettingsGeneration, isTokenDeltaChunk, listenHostEvent, drainChildSubagents, readSettingsSection, REPLAY_YIELD_EVERY, sessionEvents, settingsNamespace, streamChunkOf, streamFirstTokenTime, streamFrameAttemptId, streamFrameOwner, toolResultFailed, TUI_SOURCE_KIND, } from './dsh-compat.js';
 import { classifyApprovalDetailed, commandForApprovalRequest, isApprovalStatusArg, parseAutoApprovalMode } from './auto-approval.js';
+import { InputReader } from './input-reader.js';
+import { InputRouter } from './input-router.js';
 import { auditQuestionPrimaries, auditRepresentations, formatRepresentationAudit, isRepresentation, represent, } from './representation.js';
 import { clampScreenOffset, reportRowKind, screenFromDialog, screenLayout, screenPositionText, } from './screen.js';
 import { screenRuntimeStrip } from './footer-budget.js';
@@ -74,8 +75,7 @@ import { UserQuestionError, } from '@deepseek-ai/dsh-user-questions';
 import { durableQuestionRecords, answerSummaryText, questionViewOf, } from './question-state.js';
 import { clipAnsiToWidth, cursorVisualPosition, displayWidth, fmtElapsedCompact, foldInputView, highlightAnsiNeedle, hrefAtColumn, lastCodePoints, osc52Clipboard, padToWidth, paintSegmentedLine, paintedLinkHits, renderMarkdownLines, repeatToWidth, sanitizeTerminalText, searchContains, setAmbiguousWidthMeasured, setAmbiguousWidthReserve, shimmerText, sliceCodePoints, stripAnsi, truncate, truncateToWidth, visibleWidth, waitCardCopy, wrap, wrapSegmented, wrapWaitDetails, } from './term-text.js';
 import { clampSelection, offsetAfterColumn, offsetAtColumn, selectionSpans, selectionText, } from './selection.js';
-import { captureHangupSignals, advancePaintedRows, composePaintFrame, frameByteBudget, detectSshSession, formatLinkQualityChip, HANGUP_CANCEL_TIMEOUT_MS, ignoreFurtherHangupSignals, isEscapePrefix, isHangupErrno, linkQualityOf, linkRedrawBudgetMs, parseCursorPositionReply, PICKER_WINDOW, pickerWindowStart, probeTerminalRttMs, releaseHangupSignals, resolvePaintIntervalMs, toolBodyLineLimit, waitUntilIdleOrTimeout, RTT_HISTORY, medianRtt, } from './paint.js';
-import { TerminalInputGuard } from './terminal-input.js';
+import { captureHangupSignals, advancePaintedRows, composePaintFrame, frameByteBudget, detectSshSession, formatLinkQualityChip, HANGUP_CANCEL_TIMEOUT_MS, ignoreFurtherHangupSignals, isHangupErrno, linkQualityOf, linkRedrawBudgetMs, PICKER_WINDOW, pickerWindowStart, probeTerminalRttMs, releaseHangupSignals, resolvePaintIntervalMs, toolBodyLineLimit, waitUntilIdleOrTimeout, RTT_HISTORY, medianRtt, } from './paint.js';
 import { contextPressureAlertText, contextPressureView, describeProviderRoute, fitFooterStatusLine, footerActivity, footerHealthChip, footerIdentityParts, footerSubagentForeign, paintFooterSubagentChip, footerStatsGroups, formatContextPressureChip, runtimeStrip, providerHasQuotaSurface, formatStatusReport, planRouteBadge, shortQuotaPlanName, formatTokens, parseContextPressure, promptPressureTokens, providerUsesLocalOAuth, shouldIdleAutoCompact, } from './footer.js';
 import { COMMAND_CODE_CREDITS_URL, COMMAND_CODE_SUBSCRIPTIONS_URL, COMMAND_CODE_USAGE_URL, commandCodePeriodStart, commandCodeSourceFor, crossedQuotaThresholds, DEEPSEEK_PUBLIC_BASE_URL, formatAccountBalance, formatFooterBalance, formatQuotaSnapshot, joinUrl, OPENAI_COMPAT_BALANCE_PATHS, OPENCODE_GO_USAGE_URL, OPENCODE_ZEN_BASE_URL, openCodeApiErrorMessage, openCodeSourceFor, parseCommandCodeQuota, parseDeepSeekBalance, parseOpenAiCompatibleBalance, parseOpenCodeGoQuota, parseSuperGrokBilling, preferredQuotaWindow, quotaAlertText, quotaRefreshEverySteps, reasoningEffortsForDefault, SUPERGROK_BILLING_URL, tightestQuotaWindow, } from './quota.js';
 import { appendSubagentLog, foldSubagentUserLog, applyTurnEndToPlan, buildSubagentHeader, cardCategoryLabel, cardCategoryOf, clipSubagentActivity, compactionHeaderText, formatCompactCommandError, isPromptInjectionMessage, matchTranscriptRows, parseFindQuery, planCloseNudgeText, planMarkdownFromArgs, planDockNote, planIsLive, planTitleFromMarkdown, promptInjectionSources, promptInjectionTitle, describeSubagentFailure, subagentChipSummary, subagentDisplayName, subagentInspectLines, subagentRowFromSpawnTool, todoItemKind, askQuestions, todoProgressLabel, TODO_STATUS_MARK, } from './plan.js';
@@ -448,6 +448,24 @@ const QUOTA_RETRY_MS = 15_000;
  * screen's own tests have one source: the *order* is the product decision (B2.6 §3
  * keeps it unchanged), and this is where it is written down.
  */
+/** SGR mouse report: `\x1b[<button;column;row` + `M` (press/motion) or `m` (release). */
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/u;
+/**
+ * Whether one unit carries more than one Unicode code point.
+ *
+ * This is the test `composerUnit` needs, and `unit.length > 1` is not it: `.length`
+ * counts UTF-16 code units, and an astral character — `🚀`, `𠮷`, an emoji with a
+ * modifier — is two of those while being a single code point. Reading the first code
+ * point and comparing the remainder costs nothing on the hot path (ASCII answers 1, so
+ * the comparison is `length > 1` as before) and never allocates, which `Array.from`
+ * would. A lone surrogate answers 1, which is the honest reading: it is one code unit
+ * and the Reader cannot produce one from the wire.
+ */
+function carriesMultipleCodePoints(unit) {
+    if (unit.length <= 1)
+        return false;
+    return unit.length > ((unit.codePointAt(0) ?? 0) > 0xffff ? 2 : 1);
+}
 const SETUP_STEPS = ['provider', 'id', 'base-url', 'key', 'models', 'models-pick', 'model-default', 'context', 'confirm'];
 /** The steps that show a text field (the others are pickers or the confirmation). */
 const SETUP_FIELD_STEPS = new Set(['provider', 'id', 'base-url', 'key', 'models', 'context']);
@@ -807,7 +825,6 @@ export class SshTui {
     input = '';
     cursor = 0;
     inputFolded = false;
-    inPaste = false;
     history = [];
     historyIndex = -1;
     /** Live input parked while browsing history with ↑. Restored by ↓ past the newest item. */
@@ -1061,7 +1078,6 @@ export class SshTui {
     onReattach;
     onDetach;
     renderTimer;
-    decoder = new StringDecoder('utf8');
     color;
     maxToolOutputLines;
     showReasoning;
@@ -1421,8 +1437,6 @@ export class SshTui {
      * `turn/start` is the only thing that resets it.
      */
     reasoningExpandedChoice;
-    escapeBuffer = '';
-    escapeTimer;
     /**
      * How long an acknowledgement or a warning stays on the chrome.
      *
@@ -1437,11 +1451,28 @@ export class SshTui {
     feedbackTtlMs = resolveFeedbackTtlMs(process.env);
     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.
+     */
+    reader = new InputReader({
+        onRead: text => this.handleInputText(text),
+        onFrame: frame => this.consumeFrame(frame),
+    });
+    /**
+     * 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).
      */
-    inputGuard = new TerminalInputGuard(text => this.handleInputText(text));
+    router = new InputRouter();
+    ownershipView = {
+        screenKind: undefined,
+        surfaceKind: undefined,
+        surfaceHasField: false,
+        composerEmpty: true,
+        workspaceCards: false,
+    };
     thinkingStartedAt;
     waitStartedAt;
     /**
@@ -1471,6 +1502,15 @@ export class SshTui {
     cwdChipRow;
     /** Set when a card expand/collapse moves chrome; next paint full-redraws. */
     forceFullPaint = false;
+    /**
+     * 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.
+     */
+    screenDismissals = 0;
     /** Highest row the last budgeted frame could not paint, resumed next tick. */
     paintResume;
     /** How many times a display has come back after a drop in this Host's life. */
@@ -2334,12 +2374,9 @@ export class SshTui {
         if (this.renderTimer !== undefined)
             clearInterval(this.renderTimer);
         this.renderTimer = undefined;
-        if (this.escapeTimer !== undefined)
-            clearTimeout(this.escapeTimer);
         if (this.feedbackTimer !== undefined)
             clearTimeout(this.feedbackTimer);
-        this.escapeTimer = undefined;
-        this.inputGuard.stop();
+        this.reader.stop();
         process.stdin.removeListener('data', this.handleData);
         process.stdout.removeListener('resize', this.onDirectResize);
         process.stdout.removeListener('error', this.handleIoError);
@@ -3979,6 +4016,7 @@ export class SshTui {
         if (this.screen === undefined)
             return;
         this.screen = undefined;
+        this.screenDismissals += 1;
         this.screenSurface = undefined;
         this.screenSurfaceResolve = undefined;
         // One full repaint when a Screen closes, and it is deliberate: the transcript
@@ -5563,7 +5601,12 @@ export class SshTui {
             column = Math.min(width, promptWidth + inputView.cursorOffset + 1);
         }
         else {
-            const pos = cursorVisualPosition(inputView.text, this.cursor, inputTextWidth);
+            // The caret belongs to the field being drawn, like the text above it (W-3b.1a):
+            // `fieldCursor` is the borrowed answer's caret while a Surface has one, and the
+            // draft's otherwise. Reading `this.cursor` here put the terminal's caret — the
+            // cell an IME draws its pre-edit in — at the hidden draft's offset, which is a
+            // different number whenever a Surface borrowed the field.
+            const pos = cursorVisualPosition(inputView.text, fieldCursor, inputTextWidth);
             while (pos.row >= inputDisplayLines.length)
                 inputDisplayLines.push('');
             cursorRowOffset = pos.row;
@@ -5726,38 +5769,38 @@ export class SshTui {
             ...(health === undefined ? {} : { warning: { long: health.long, short: health.short } }),
             depth: this.colorDepth,
             color: this.color,
-            ...(this.footerEcho === undefined ? {} : { echo: this.footerEcho.text }),
         };
         const stripText = runtimeStrip(stripInput, Math.max(1, width), this.mutedSeparator(), this.spinnerFrame());
-        // The acknowledgement the strip could not fit.
-        //
-        // The echo chip is the lowest-priority group on the stats row, which is exactly
-        // the state a working session is in — so a command's confirmation was dropped
-        // entirely and the reader saw *no* feedback at all (B2.5, reported). The chip is
-        // still where it goes first; when it did not survive, the row that always fits
-        // says it instead. One message, one place, no extra rows.
-        const missingEcho = this.notice === undefined
-            && this.footerEcho !== undefined
-            && !stripText.includes(this.footerEcho.text)
-            ? this.footerEcho.text
-            : undefined;
         // The row is one muted run with the accents spliced in at higher intensity;
         // `muteFooterLine` reopens the mute after every reset so the (already
         // coloured) pips and meters cannot bleed into the text around them.
         const statsLine = clipAnsiToWidth(this.muteFooterLine(stripText), Math.max(1, width));
         this.healthChipRow = undefined;
-        // The identity row is composed *after* the strip, because whether it needs to
-        // carry the echo depends on what the strip managed to fit (see below).
+        // Every acknowledgement lands on the identity row, and nowhere else.
+        //
+        // The echo used to be the lowest-priority chip *on the meter row*, with the
+        // identity row as the fallback when it did not fit — so which of the two rows a
+        // message appeared on depended on its length and the window's width. The same
+        // `/copy` said `已复制 412 字…（最近回复）` on the row above the last one (it fit)
+        // and `还没有可复制的回复…` on the last one (it did not): two acknowledgements,
+        // two lines, nothing in the product saying why (reported). A confirmation is
+        // read, not measured, so it is not the meter row's business either — the first
+        // footer row answers the five telemetry questions and only those (E-1).
+        //
+        // A notice still outranks an echo: an operational warning must not be hidden by
+        // an acknowledgement that happens to be alive at the same moment. Both are
+        // Host-local, both are transient, and now both are on the row that always fits.
+        const echoText = this.notice === undefined ? this.footerEcho?.text : undefined;
         const statusText = this.notice !== undefined
             ? truncateToWidth(this.notice.text, Math.max(1, width))
-            : missingEcho === undefined
-                ? fitFooterStatusLine('', identity, Math.max(1, width))
-                : truncateToWidth(missingEcho, Math.max(1, width));
+            : echoText !== undefined
+                ? truncateToWidth(echoText, Math.max(1, width))
+                : fitFooterStatusLine('', identity, Math.max(1, width));
         // Accents on an otherwise muted line: the `sub:` chip. Each reset reopens
         // mute, the same way the pre-strip footer did. `styleLine` sanitises first,
         // so the accent is spliced in after.
         let statusLine = this.styleLine('system', statusText);
-        if (this.color && this.notice === undefined) {
+        if (this.color && this.notice === undefined && echoText === undefined) {
             // The chip is only accented when it survived the fit: a `sub:` route the
             // row could not afford is not on the line, and `paintFooterSubagentChip`
             // returns the line unchanged when it cannot find its text.
@@ -8727,6 +8770,21 @@ export class SshTui {
         const at = this.fieldCursor();
         this.setField(`${current.slice(0, at)}${text}${current.slice(at)}`, at + text.length);
     }
+    /**
+     * 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.
+     */
+    moveFieldCursor(target) {
+        if (!this.textIsEditable())
+            return;
+        this.setField(this.fieldText(), target === 'start' ? 0 : this.fieldText().length);
+        this.markDirty();
+    }
     /** One card's key: a call's batch can repeat a question id across calls. */
     questionCardKey(callId, questionId) {
         return `${callId ?? `live:${this.liveQuestionSeq}`}\u0000${questionId}`;
@@ -11253,10 +11311,7 @@ export class SshTui {
     }
     // ── keyboard ────────────────────────────────────────────────────────────
     handleData = (chunk) => {
-        const decoded = this.decoder.write(chunk);
-        if (decoded === '')
-            return;
-        this.inputGuard.push(decoded);
+        this.reader.push(chunk);
     };
     /**
      * One key, handled by the Screen that is up.
@@ -11271,6 +11326,24 @@ export class SshTui {
         const screen = this.screen;
         if (screen === undefined)
             return;
+        // Ctrl+L repaints the frame and belongs to the terminal rather than to any
+        // surface that happens to be up: a Screen replaces the workspace entirely, so a
+        // reader with a garbled terminal would otherwise have to leave the Screen to
+        // clear it. The next paint is a full one, exactly as the composer's Ctrl+L is.
+        if (combined === '\x0c') {
+            this.screenNeedsFullPaint = true;
+            this.markDirty();
+            return;
+        }
+        // A burst of line breaks in one read is a paste from a console that cannot say so
+        // (`looksLikePasteBurst`): it belongs in the field as one edit, which is how a
+        // pasted key or model list survives a terminal without bracketed paste. The Reader
+        // keeps such a read whole for exactly this check — splitting it is what would turn
+        // one paste into a step's worth of Enters.
+        if (InputReader.looksLikePasteBurst(combined)) {
+            this.pasteIntoScreen(combined);
+            return;
+        }
         // The setup Screen owns its own field, its own navigation and its own keys: it
         // consumes everything while it is up, and nothing reaches the workspace's
         // composer, history or transcript (B2.6 §4).
@@ -11414,31 +11487,86 @@ export class SshTui {
         screen.notice = caveat ?? notice;
         this.markDirty();
     }
+    /**
+     * 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).
+     */
     handleInputText(text) {
-        const combined = this.escapeBuffer + text;
-        this.escapeBuffer = '';
-        if (this.escapeTimer !== undefined) {
-            clearTimeout(this.escapeTimer);
-            this.escapeTimer = undefined;
-        }
-        // Bracketed paste: terminals wrap pasted content in \x1b[200~ ... \x1b[201~.
-        // While inside a paste, CR/LF are literal input characters rather than
-        // submit, so copying a multi-line error message arrives as one message.
-        if (this.inPaste || combined.includes('\x1b[200~') || combined.includes('\x1b[201~')) {
-            this.processPasteChunk(combined);
-            return;
-        }
-        // A key the user moved, and a key their move displaced. Consulted before any
-        // routing so a plain control byte reaches it as readily as a CSI sequence;
-        // everything else keeps the handling below, which is what makes the defaults
-        // unchanged by construction.
+        const combined = this.reader.assemble(text);
+        // A read is not a key. The Reader decides where one unit ends — complete
+        // sequences, Alt chords, control bytes, CR/LF, and runs of typing — and each unit
+        // is framed once and routed once, whichever owner it belongs to (AD-20 §3, W-3a).
+        // Bracketed paste is framed there too: while inside a paste, CR/LF are literal
+        // characters rather than submit, so a copied multi-line error message arrives as
+        // one message.
+        //
+        // A Screen owns the read it was sent, including the units after it closes: 0.8.3
+        // dropped the rest of such a read (`handleScreenInput` returned as soon as its
+        // Screen was gone) and that rule is a safety one, not an artefact — the keys after
+        // a dismissal were addressed to the Screen, and letting them land on whatever is
+        // behind it is how a paste ended up in the composer. A Surface is the other way
+        // round, and deliberately: its answer is a character like any other, and the rest
+        // of the read is routed on (`yes` typed at a confirm is refused by the Surface and
+        // leaves the draft alone — pinned by `yes-typed-at-dialog`).
+        const dismissals = this.screenDismissals;
+        for (const frame of this.reader.read(combined)) {
+            if (this.screenDismissals !== dismissals)
+                return;
+            this.consumeFrame(frame);
+        }
+    }
+    /** One framed unit, at the owner that takes it. */
+    consumeFrame(frame) {
+        switch (frame.kind) {
+            case 'paste':
+                this.dispatchPaste(frame.text);
+                return;
+            // A sequence tail, an Alt remainder or a released hold: typed as it is, with
+            // no keymap lookup — which is what the inline version did at those three sites.
+            case 'literal':
+                this.handlePlainText(frame.text);
+                return;
+            case 'escape':
+                this.handleChar('\x1b');
+                return;
+            // A device reply is the prober's input, never an owner's. W-1 keeps today's
+            // behaviour (dropped here); W-2 wires it to the prober that asked.
+            case 'reply': return;
+            // `key` and `burst` reach the same routing today. The distinction is what W-2
+            // routes on (one key versus several in one read), so the Reader decides it.
+            case 'key':
+                this.route(frame.sequence);
+                return;
+            case 'burst':
+                this.route(frame.text);
+                return;
+        }
+    }
+    /**
+     * 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.
+     */
+    route(combined) {
+        // A key the user moved, and a key their move displaced.
         const moved = combined === '' ? undefined : this.keymap.sequences.get(combined);
-        // A Screen replaces the workspace and owns every key outright. There is no
-        // composer behind it, no transcript to fall through to and no Surface it could
-        // share with: one gate, instead of the ten `dialog?.kind === 'inspect'` checks
-        // this replaced (B2.1).
-        if (this.screen !== undefined) {
-            this.handleScreenInput(combined, moved);
+        const kind = this.readKind(combined);
+        this.observe(kind, combined);
+        const owner = this.router.route(kind, combined, this.ownershipView);
+        // A Screen owns the read outright (AD-20 §4.3 priority 3): nothing below this
+        // line runs for it — no keymap action, no Alt chord, no bare ESC for the composer.
+        if (owner === 'screen') {
+            this.ownerScreen(combined, moved);
             return;
         }
         if (this.dialog === undefined && combined !== '') {
@@ -11449,124 +11577,14 @@ export class SshTui {
             if (this.dialog === undefined && this.keymap.suppressed.has(combined))
                 return;
         }
-        const escape = /^\x1b\[([A-D])$/u;
-        const match = combined.match(escape);
-        if (match !== null) {
-            switch (match[1]) {
-                case 'A':
-                    if (this.moveQuestionCursor(-1)) {
-                        return;
-                        return;
-                        return;
-                    }
-                    else if (this.dialog !== undefined) {
-                        // A surface owns the keyboard: an arrow it does not use is not the
-                        // transcript's. Falling through moved the selection behind the dialog,
-                        // and with a non-empty field it rewrote the field from history.
-                        return;
-                    }
-                    else if (this.suggestionsVisible()) {
-                        this.suggestionIndex = Math.max(0, this.suggestionIndex - 1);
-                        this.markDirty();
-                    }
-                    else if (this.fieldText() === '' && this.collapsibleRows().length > 0) {
-                        this.moveFocus(-1);
-                    }
-                    else {
-                        this.historyBack();
-                    }
-                    return;
-                case 'B':
-                    if (this.moveQuestionCursor(1)) {
-                        return;
-                        return;
-                        return;
-                    }
-                    else if (this.dialog !== undefined) {
-                        return;
-                    }
-                    else if (this.suggestionsVisible()) {
-                        this.suggestionIndex = Math.min(this.commandSuggestions.length - 1, this.suggestionIndex + 1);
-                        this.markDirty();
-                    }
-                    else if (this.fieldText() === '' && this.collapsibleRows().length > 0) {
-                        this.moveFocus(1);
-                    }
-                    else {
-                        this.historyForward();
-                    }
-                    return;
-                case 'C':
-                    if (this.textIsEditable())
-                        this.moveCursor(1);
-                    return;
-                case 'D':
-                    if (this.textIsEditable())
-                        this.moveCursor(-1);
-                    return;
-            }
-        }
-        const sgrMouse = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/u.exec(combined);
-        if (sgrMouse !== null) {
-            const button = Number(sgrMouse[1]);
-            const x = Number(sgrMouse[2]);
-            const y = Number(sgrMouse[3]);
-            if (sgrMouse[4] === 'M') {
-                if (button === 64) {
-                    this.scrollActiveSurface(3);
-                    return;
-                }
-                if (button === 65) {
-                    this.scrollActiveSurface(-3);
-                    return;
-                }
-                // 32 is "motion with the left button held": a drag over a reply. Shift
-                // adds 4 to every button code, and a terminal that still forwards the
-                // report while Shift is down (instead of keeping it for its own
-                // selection) must drag exactly like an unshifted one — otherwise the
-                // gesture the user was told to fall back on does nothing here.
-                if (button === 32 || button === 36) {
-                    this.extendMouseSelection(y, x);
-                    return;
-                }
-                if (button === 0 || button === 4) {
-                    this.beginMouseSelection(y, x);
-                    return;
-                }
-                return;
-            }
-            // A release ends either a drag (copy what it covered) or a plain click.
-            if (button === 0 || button === 4)
-                this.endMouseSelection(y, x);
-            return;
-        }
-        if (combined === '\x1b[5~') {
-            this.scrollActiveSurface(Math.max(3, Math.floor(this.screenRows() / 2)));
-            return;
-        }
-        if (combined === '\x1b[6~') {
-            this.scrollActiveSurface(-Math.max(3, Math.floor(this.screenRows() / 2)));
-            return;
-        }
-        if (parseCursorPositionReply(combined) !== undefined)
-            return;
-        if (combined === '\x1b[H' || combined === '\x1b[1~') {
-            this.cursor = 0;
-            this.markDirty();
+        if (this.reader.isDeviceReply(combined)) {
+            this.consumeFrame({ kind: 'reply', sequence: combined });
             return;
         }
-        if (combined === '\x1b[F' || combined === '\x1b[4~') {
-            this.cursor = this.input.length;
-            this.markDirty();
-            return;
-        }
-        if (combined === '\x1b[3~') {
-            this.deleteAtCursor();
-            return;
-        }
-        // kitty / CSI-u Ctrl+Shift+C (codepoint 99, mods 6 = Ctrl+Shift)
-        if (combined === '\x1b[99;6u') {
-            this.copyKey();
+        // The sequence shapes the ladder matched before its hold window: they go to their
+        // owner as one unit, and only what is left over can still grow (the Reader holds it).
+        if (this.isSequenceShape(combined)) {
+            this.dispatchWith(owner, combined, moved);
             return;
         }
         const ss3 = /^\x1bO[A-Z]/u.exec(combined);
@@ -11576,30 +11594,10 @@ export class SshTui {
                 this.handlePlainText(rest);
             return;
         }
-        if (isEscapePrefix(combined)) {
-            this.escapeBuffer = combined;
-            this.escapeTimer = setTimeout(() => {
-                this.escapeTimer = undefined;
-                const pending = this.escapeBuffer;
-                this.escapeBuffer = '';
-                if (pending === '\x1b') {
-                    this.handleChar('\x1b');
-                }
-                else if (pending === '\x1bO') {
-                    // ESC O without an SS3 final byte is an Alt+O keystroke, not a
-                    // function key.
-                    this.handlePlainText('O');
-                }
-                else if (pending.startsWith('\x1b[') || pending.startsWith('\x1bO')) {
-                    // An escape sequence that never completed: consume it silently
-                    // instead of treating its ESC byte as a cancel.
-                }
-                else if (pending !== '') {
-                    this.handlePlainText(pending);
-                }
-            }, 60);
+        // A read that could still grow into a sequence is the Reader's to hold, and the
+        // window is the same 60 ms it always was (AD-21: moved, not changed).
+        if (this.reader.hold(combined))
             return;
-        }
         if (combined.startsWith('\x1b[') || combined.startsWith('\x1bO')) {
             // Unknown escape sequence (including SS3 function keys) — consume
             // without side effects.
@@ -11631,131 +11629,321 @@ export class SshTui {
                 this.stepSearch(-1);
                 return;
             }
+            // The `/find` seed is composer *text*, so it may only be typed into a field
+            // the composer owns (W-3b.3a). This branch runs before any owner is asked
+            // (the Alt chords are workspace-global, AD-20 §1.3 step 13), so with a
+            // Surface up it used to write the hidden draft — the one thing F-2 forbids —
+            // and the reader saw their next message replaced by `/find `. A chord is not
+            // an owner, so the key is consumed here instead of reaching behind the
+            // Surface. `textIsEditable()` alone is not this question: it answers "a field
+            // is editable", and a borrowed answer is one — the seed is the *composer's*
+            // field, which is exactly `borrowedText === undefined`.
             if (alt === 'f' || alt === 'F' || alt === '/') {
-                this.input = '/find ';
-                this.cursor = this.input.length;
-                this.markDirty();
+                if (this.textIsEditable() && this.borrowedText === undefined) {
+                    this.input = '/find ';
+                    this.cursor = this.input.length;
+                    this.markDirty();
+                }
                 return;
             }
             // Other Alt+<key>: ignore ESC so it does not cancel, type the remainder.
             this.handlePlainText(alt);
             return;
         }
-        this.handlePlainText(combined);
+        this.dispatchWith(owner, combined, moved);
     }
-    /** Handle one data chunk that may contain bracketed-paste markers. */
-    processPasteChunk(combined) {
-        let index = 0;
-        while (index < combined.length) {
-            if (combined.startsWith('\x1b[200~', index)) {
-                this.inPaste = true;
-                index += 6;
-                continue;
-            }
-            if (combined.startsWith('\x1b[201~', index)) {
-                this.inPaste = false;
-                index += 6;
-                continue;
-            }
-            let end = index;
-            while (end < combined.length
-                && !combined.startsWith('\x1b[200~', end)
-                && !combined.startsWith('\x1b[201~', end)) {
-                end += 1;
-            }
-            if (end > index) {
-                const part = combined.slice(index, end);
-                if (this.inPaste)
-                    this.handlePasteText(part);
-                else
-                    this.handlePlainText(part);
-                index = end;
-            }
-            else {
-                index += 1;
-            }
+    /**
+     * 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.
+     */
+    observe(kind, unit) {
+        const view = this.ownershipView;
+        const screen = this.screen;
+        const surface = this.dialog;
+        view.screenKind = screen?.kind;
+        view.surfaceKind = surface?.kind;
+        view.surfaceHasField = this.borrowedText !== undefined;
+        view.composerEmpty = this.fieldText() === '';
+        view.workspaceCards = screen === undefined && surface === undefined
+            && kind === 'sequence'
+            && (unit === '\x1b[A' || unit === '\x1b[B')
+            && view.composerEmpty
+            && this.collapsibleRows().length > 0;
+    }
+    /**
+     * 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).
+     */
+    isSequenceShape(unit) {
+        return /^\x1b\[[A-D]$/u.test(unit)
+            || SGR_MOUSE_RE.test(unit)
+            || unit === '\x1b[5~' || unit === '\x1b[6~'
+            || unit === '\x1b[H' || unit === '\x1b[1~' || unit === '\x1b[F' || unit === '\x1b[4~'
+            || unit === '\x1b[3~' || unit === '\x1b[99;6u';
+    }
+    /** The unit class of one read, by shape (the Reader's classification, allocation-free). */
+    readKind(combined) {
+        if (combined === '\x1b')
+            return 'escape';
+        if (combined.length === 1)
+            return combined < ' ' || combined === '\x7f' ? 'control' : 'text';
+        return combined.startsWith('\x1b') ? 'sequence' : 'text';
+    }
+    /** The unit class of one character — what `handleChar` routes. */
+    charKind(char) {
+        if (char === '\x1b')
+            return 'escape';
+        return char < ' ' || char === '\x7f' ? 'control' : 'text';
+    }
+    /** One unit, one owner: the Router decides, the owner adapter runs it. */
+    dispatch(kind, unit, moved) {
+        this.observe(kind, unit);
+        this.dispatchWith(this.router.route(kind, unit, this.ownershipView), unit, moved);
+    }
+    /** Run a unit at the owner the Router already named. */
+    dispatchWith(owner, unit, moved) {
+        switch (owner) {
+            case 'screen':
+                this.ownerScreen(unit, moved);
+                return;
+            case 'surface':
+                this.ownerSurface(unit, moved);
+                return;
+            case 'composer':
+                this.ownerComposer(unit, moved);
+                return;
+            case 'workspace':
+                this.ownerWorkspace(unit, moved);
+                return;
         }
     }
     /**
-     * Insert pasted text into the field that owns the keyboard; CR/LF are literal
-     * newlines.
+     * A paste payload: the Router decides, the paste path executes.
      *
-     * A paste is text input, so it goes through the same ownership question ordinary
-     * typing does: into the composer's draft when the composer owns the keyboard, and
-     * into a borrowed field when a surface that has one does. A surface without a
-     * text field (a confirmation, the inspect overlay) takes no paste at all — the
-     * alternative was writing the composer's hidden draft behind it, which is how a
-     * paste into an approval dialog could silently rewrite the message being written.
+     * 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).
      */
-    handlePasteText(text) {
-        const normalized = text.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
-        if (normalized === '')
+    dispatchPaste(text) {
+        this.observe('paste', text);
+        if (this.router.route('paste', text, this.ownershipView) === 'workspace')
             return;
-        if (!this.textIsEditable())
+        this.handlePasteText(text);
+    }
+    /**
+     * 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.
+     */
+    ownerScreen(unit, moved) {
+        this.handleScreenInput(unit, moved ?? this.keymap.sequences.get(unit));
+    }
+    /**
+     * 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.
+     */
+    ownerSurface(unit, moved) {
+        if (unit === '\x1b[A') {
+            this.moveQuestionCursor(-1);
             return;
-        this.leaveHistoryBrowse();
-        const current = this.fieldText();
-        const at = this.fieldCursor();
-        this.setField(`${current.slice(0, at)}${normalized}${current.slice(at)}`, at + normalized.length);
-        if (this.borrowedText === undefined) {
-            const cols = Math.max(10, this.screenColumns());
-            const lineWidth = Math.max(1, cols - 2);
-            if (normalized.includes('\n') || displayWidth(this.fieldText()) > lineWidth)
-                this.inputFolded = true;
         }
-        this.markDirty();
+        if (unit === '\x1b[B') {
+            this.moveQuestionCursor(1);
+            return;
+        }
+        const sgr = SGR_MOUSE_RE.exec(unit);
+        if (sgr !== null) {
+            const button = Number(sgr[1]);
+            if (button === 64 || button === 65)
+                return;
+            this.mouseGesture(sgr);
+            return;
+        }
+        if (unit === '\x1b[H' || unit === '\x1b[1~') {
+            this.moveFieldCursor('start');
+            return;
+        }
+        if (unit === '\x1b[F' || unit === '\x1b[4~') {
+            this.moveFieldCursor('end');
+            return;
+        }
+        if (unit === '\x1b[3~') {
+            // Only a borrowed field can be edited: the draft behind the Surface is not the
+            // field on screen, and an answer the reader cannot see is not an answer.
+            if (this.textIsEditable())
+                this.deleteAtCursor();
+            return;
+        }
+        if (unit.startsWith('\x1b[') || unit.startsWith('\x1bO'))
+            return;
+        this.composerUnit(unit, moved);
     }
     /**
-     * Whether the keys that edit text belong to a field right now.
+     * The Composer adapter.
      *
-     * The composer always has one; an open surface only has one when it borrowed it
-     * (a free-text answer, a setup field). Everything else — a confirmation, a menu,
-     * the inspect overlay — owns the keyboard without owning text, and those keys
-     * must do nothing rather than reach the draft behind the surface.
+     * 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).
      */
-    textIsEditable() {
-        return this.dialog === undefined || this.borrowedText !== undefined;
+    ownerComposer(unit, moved) {
+        if (unit === '\x1b[A') {
+            this.arrowHistory(-1);
+            return;
+        }
+        if (unit === '\x1b[B') {
+            this.arrowHistory(1);
+            return;
+        }
+        if (unit === '\x1b[C') {
+            if (this.textIsEditable())
+                this.moveCursor(1);
+            return;
+        }
+        if (unit === '\x1b[D') {
+            if (this.textIsEditable())
+                this.moveCursor(-1);
+            return;
+        }
+        // The caret keys go through the field the keyboard is editing, like Ctrl+A/Ctrl+E
+        // below: with no Surface up that field *is* the draft, so this is the write it
+        // always was — and it can no longer be the wrong field if a later round routes a
+        // unit here while a field is borrowed.
+        if (unit === '\x1b[H' || unit === '\x1b[1~') {
+            this.moveFieldCursor('start');
+            return;
+        }
+        if (unit === '\x1b[F' || unit === '\x1b[4~') {
+            this.moveFieldCursor('end');
+            return;
+        }
+        if (unit === '\x1b[3~') {
+            this.deleteAtCursor();
+            return;
+        }
+        if (unit === '\x1b[99;6u') {
+            this.copyKey();
+            return;
+        }
+        this.composerUnit(unit, moved);
     }
-    handlePlainText(text) {
-        // Fallback for terminals without bracketed paste: a burst of multiple line
-        // breaks in one chunk is a paste, not repeated Enter presses.
-        let newlines = 0;
-        for (let index = 0; index < text.length; index += 1) {
-            const char = text[index];
-            if (char === '\r' && text[index + 1] !== '\n')
-                newlines += 1;
-            else if (char === '\n' && text[index - 1] !== '\r')
-                newlines += 1;
+    /**
+     * 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).
+     */
+    ownerWorkspace(unit, moved) {
+        void moved;
+        const sgr = SGR_MOUSE_RE.exec(unit);
+        if (sgr !== null) {
+            const button = Number(sgr[1]);
+            if (button === 64) {
+                this.scrollWorkspace(3);
+                return;
+            }
+            if (button === 65) {
+                this.scrollWorkspace(-3);
+                return;
+            }
+            this.mouseGesture(sgr);
+            return;
         }
-        if (newlines > 1) {
-            this.handlePasteText(text);
+        const page = Math.max(3, Math.floor(this.screenRows() / 2));
+        if (unit === '\x1b[5~') {
+            this.scrollWorkspace(page);
             return;
         }
-        let previous = '';
-        for (const char of text) {
-            // Windows terminals may deliver Enter as CRLF; consume only the first half.
-            if (char === '\n' && previous === '\r') {
-                previous = char;
-                continue;
+        if (unit === '\x1b[6~') {
+            this.scrollWorkspace(-page);
+            return;
+        }
+        if (unit === '\x1b[A') {
+            this.moveFocus(-1);
+            return;
+        }
+        if (unit === '\x1b[B') {
+            this.moveFocus(1);
+            return;
+        }
+    }
+    /** An arrow the composer keeps: the suggestion list while it is up, else history. */
+    arrowHistory(direction) {
+        if (this.suggestionsVisible()) {
+            this.suggestionIndex = direction < 0
+                ? Math.max(0, this.suggestionIndex - 1)
+                : Math.min(this.commandSuggestions.length - 1, this.suggestionIndex + 1);
+            this.markDirty();
+            return;
+        }
+        if (direction < 0)
+            this.historyBack();
+        else
+            this.historyForward();
+    }
+    /** Press, motion and release: selection, links and card toggles — the transcript's. */
+    mouseGesture(sgr) {
+        const button = Number(sgr[1]);
+        const x = Number(sgr[2]);
+        const y = Number(sgr[3]);
+        if (sgr[4] === 'M') {
+            // 32 is "motion with the left button held": a drag over a reply. Shift adds 4 to
+            // every button code, and a terminal that still forwards the report while Shift is
+            // down must drag exactly like an unshifted one.
+            if (button === 32 || button === 36) {
+                this.extendMouseSelection(y, x);
+                return;
             }
-            if (char === '\r' && previous === '\n') {
-                previous = char;
-                continue;
+            if (button === 0 || button === 4) {
+                this.beginMouseSelection(y, x);
+                return;
             }
-            this.handleChar(char);
-            previous = char;
+            return;
         }
+        // A release ends either a drag (copy what it covered) or a plain click.
+        if (button === 0 || button === 4)
+            this.endMouseSelection(y, x);
     }
-    handleChar(char) {
-        // A setup Screen owns every key, Enter included: it is the key that submits a
-        // step, and the composer behind the screen must never receive one (B2.6 §4).
-        // Ctrl+C is the exception — it is the terminal's own interrupt and keeps its
-        // global meaning.
-        if (this.screen?.kind === 'setup' && char !== '\x03') {
-            this.handleScreenInput(char, this.keymap.sequences.get(char));
+    /**
+     * 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).
+     */
+    composerUnit(unit, moved) {
+        void moved;
+        // A run of text is split and re-judged per code point; a single one — ASCII, CJK, or
+        // an astral character the Reader framed as one unit — falls through to the switch and
+        // its owner. Counting UTF-16 code units here sent `🚀` back into this method forever
+        // (W-3b.1b), which is why the test is by code point.
+        if (carriesMultipleCodePoints(unit)) {
+            this.handlePlainText(unit);
             return;
         }
-        switch (char) {
+        switch (unit) {
             case '\x1b':
                 this.handleEscape();
                 return;
@@ -11778,16 +11966,11 @@ export class SshTui {
             // exit semantics of its own, and falling through to the process exit left a
             // dialog on screen killing the session it was waiting for.
             case '\x04':
-                if (this.dialog === undefined && this.screen === undefined)
+                if (this.dialog === undefined)
                     void this.requestExit(0);
                 return;
             case '\x0c':
-                this.lastPaintRows = [];
-                this.lastChromeKey = '';
-                this.lastPaintWidth = 0;
-                this.lastPaintHeight = 0;
-                this.dirty = true;
-                this.render();
+                this.repaintNow();
                 return;
             case '\x01':
                 if (this.textIsEditable())
@@ -11819,11 +12002,11 @@ export class SshTui {
             // under it changed what a later copy would take while the screen showed
             // nothing of the sort.
             case '\x0e':
-                if (this.dialog === undefined && this.screen === undefined)
+                if (this.dialog === undefined)
                     this.moveFocus(1);
                 return;
             case '\x10':
-                if (this.dialog === undefined && this.screen === undefined)
+                if (this.dialog === undefined)
                     this.moveFocus(-1);
                 return;
             case '\x12':
@@ -11840,33 +12023,21 @@ export class SshTui {
                 this.markDirty();
                 return;
         }
-        // A Screen owns the keyboard here too. This is the path a plain character
-        // takes (`handleChar`), and the Screen branch must come first or a `y` typed at
-        // a Screen's confirmation would fall through to the composer behind it.
-        if (this.screen !== undefined) {
-            this.handleScreenInput(char, this.keymap.sequences.get(char));
-            return;
-        }
         if (this.dialog !== undefined) {
-            this.handleDialogChar(char);
+            this.handleDialogChar(unit);
             return;
         }
-        if (char === '\x07') {
-            if (this.dialog === undefined)
-                this.stepSearch(1);
+        if (unit === '\x07') {
+            this.stepSearch(1);
             return;
         }
-        if (char === '\x1f') {
-            if (this.dialog !== undefined)
-                return;
+        if (unit === '\x1f') {
             this.input = '/find ';
             this.cursor = this.input.length;
             this.markDirty();
             return;
         }
-        if (char === '\t') {
-            if (this.dialog !== undefined)
-                return;
+        if (unit === '\t') {
             if (this.suggestionsVisible()) {
                 const selected = this.commandSuggestions[this.suggestionIndex];
                 if (selected !== undefined) {
@@ -11883,14 +12054,154 @@ export class SshTui {
             this.markDirty();
             return;
         }
-        if (char >= ' ' && char !== '\x7f') {
+        if (unit >= ' ' && unit !== '\x7f') {
             if (!this.textIsEditable())
                 return;
             this.leaveHistoryBrowse();
-            this.insertIntoField(char);
+            this.insertIntoField(unit);
             this.markDirty();
         }
     }
+    /**
+     * 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.
+     */
+    repaintNow() {
+        this.lastPaintRows = [];
+        this.lastChromeKey = '';
+        this.lastPaintWidth = 0;
+        this.lastPaintHeight = 0;
+        this.dirty = true;
+        this.render();
+    }
+    /**
+     * Insert pasted text into the field that owns the keyboard; CR/LF are literal
+     * newlines.
+     *
+     * A paste is text input, so it goes through the same ownership question ordinary
+     * typing does: into the composer's draft when the composer owns the keyboard, and
+     * into a borrowed field when a surface that has one does. A surface without a
+     * text field (a confirmation, a menu, a report) takes no paste at all — the
+     * alternative was writing the composer's hidden draft behind it, which is how a
+     * paste into an approval dialog could silently rewrite the message being written.
+     *
+     * A **Screen** is that same question with a different answer, and it is asked
+     * first because `textIsEditable()` only ever answers for the composer's field: the
+     * setup Screen keeps a field of its own, which the composer's helpers cannot see
+     * and must never be handed (B2.6 §4).
+     */
+    handlePasteText(text) {
+        const normalized = text.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+        if (normalized === '')
+            return;
+        if (this.screen !== undefined) {
+            this.pasteIntoScreen(normalized);
+            return;
+        }
+        if (!this.textIsEditable())
+            return;
+        this.leaveHistoryBrowse();
+        const current = this.fieldText();
+        const at = this.fieldCursor();
+        this.setField(`${current.slice(0, at)}${normalized}${current.slice(at)}`, at + normalized.length);
+        if (this.borrowedText === undefined) {
+            const cols = Math.max(10, this.screenColumns());
+            const lineWidth = Math.max(1, cols - 2);
+            if (normalized.includes('\n') || displayWidth(this.fieldText()) > lineWidth)
+                this.inputFolded = true;
+        }
+        this.markDirty();
+    }
+    /**
+     * Give a paste to the field the Screen owns, or to nobody.
+     *
+     * The setup Screen is the only Screen with a field, and it is the one place a
+     * paste matters most: an API key, a base URL and a model list are all copied from
+     * somewhere else, and a first run that could only be typed by hand is the
+     * difference between a working session and an empty one. A step without a field —
+     * the model pickers, the confirmation — is not a text field, so the paste is
+     * dropped exactly as a menu drops it: a paste is text, never an answer.
+     */
+    pasteIntoScreen(text) {
+        const state = this.onboarding;
+        if (this.screen?.kind !== 'setup' || state === undefined || state.saving)
+            return;
+        if (!SETUP_FIELD_STEPS.has(state.step))
+            return;
+        // The field is drawn on one row, so it takes the value and not the line breaks
+        // around it: a key copied off a web page carries the newline that ended its
+        // line, and a pasted list or `.env` block means the breaks as separators. Both
+        // are folded here rather than inserted literally, which would leave the field
+        // holding text no step can parse and no row can draw.
+        const flat = text.split('\n').map(part => part.trim()).filter(part => part !== '').join(' ');
+        if (flat === '')
+            return;
+        this.setupInsert(state, flat);
+        this.markDirty();
+    }
+    /**
+     * Whether the keys that edit text belong to a field right now.
+     *
+     * The composer always has one; an open surface only has one when it borrowed it
+     * (a free-text answer). Everything else — a confirmation, a menu, the inspect
+     * overlay, every Screen — owns the keyboard without owning the composer's text,
+     * and those keys must do nothing rather than reach the draft behind the surface.
+     * A Screen is included by name: the setup Screen has a field of its own, and it
+     * is reached through the Screen's own keys, never through the composer's.
+     */
+    textIsEditable() {
+        if (this.screen !== undefined)
+            return false;
+        return this.dialog === undefined || this.borrowedText !== undefined;
+    }
+    handlePlainText(text) {
+        // Fallback for terminals without bracketed paste: a burst of multiple line
+        // breaks in one chunk is a paste, not repeated Enter presses.
+        if (InputReader.looksLikePasteBurst(text)) {
+            this.dispatchPaste(text);
+            return;
+        }
+        // A text unit is delivered one character at a time and each character is routed
+        // again — that is what lets ownership change inside one unit (a Surface answers `y`
+        // and the composer takes the `es` behind it, W-2). A Screen is the one owner that
+        // does not work that way: it owns the read it was sent, and the read-level guard in
+        // `handleInputText` drops the units after it closes. This is the same rule one level
+        // down, for the units that carry several characters: without it a character that
+        // closes the Screen — the `ESC` of a paste tail, a `q`, an Enter — ended the Screen
+        // and the rest of the same unit was typed into the composer behind it (W-3a.1).
+        const dismissals = this.screenDismissals;
+        let previous = '';
+        for (const char of text) {
+            if (this.screenDismissals !== dismissals)
+                return;
+            // Windows terminals may deliver Enter as CRLF; consume only the first half.
+            if (char === '\n' && previous === '\r') {
+                previous = char;
+                continue;
+            }
+            if (char === '\r' && previous === '\n') {
+                previous = char;
+                continue;
+            }
+            this.handleChar(char);
+            previous = char;
+        }
+    }
+    /**
+     * 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.
+     */
+    handleChar(char) {
+        this.dispatch(this.charKind(char), char, this.keymap.sequences.get(char));
+    }
     /**
      * Run one rebindable action.
      * @param action - the action the pressed key was moved to.
@@ -11898,11 +12209,14 @@ export class SshTui {
      */
     runKeyAction(action) {
         switch (action) {
+            // Only reachable with nothing layered over the workspace (the ladder asks this
+            // table first thing, and a Screen returns before it), so the target is the
+            // transcript — named here rather than re-derived inside a shared scroller.
             case 'pageUp':
-                this.scrollActiveSurface(Math.max(3, Math.floor(this.screenRows() / 2)));
+                this.scrollWorkspace(Math.max(3, Math.floor(this.screenRows() / 2)));
                 return true;
             case 'pageDown':
-                this.scrollActiveSurface(-Math.max(3, Math.floor(this.screenRows() / 2)));
+                this.scrollWorkspace(-Math.max(3, Math.floor(this.screenRows() / 2)));
                 return true;
             case 'toggleCard':
                 this.toggleCollapsible();
@@ -12249,13 +12563,6 @@ export class SshTui {
             this.markDirty();
             return;
         }
-        if (combined === '\x0c') {
-            // Ctrl+L still repaints the whole frame: the field is a row like any other,
-            // and a forced repaint is how a reader clears a garbled terminal.
-            this.screenNeedsFullPaint = true;
-            this.markDirty();
-            return;
-        }
         if (combined === '\x15') {
             // Ctrl+U clears the wizard's field, not the workspace's draft.
             this.setupSetField(state, '', 0);
@@ -12725,7 +13032,7 @@ export class SshTui {
                     this.setupMessage(state, 'system', t('onboard.baseSaved', { path: displayDshPath('settings.yaml') }));
                 }
                 if (saved) {
-                    this.setupMessage(state, 'system', t('onboard.officialDone', { model }));
+                    this.onboardDone(t('onboard.officialDone', { model }));
                 }
             }
             else {
@@ -12898,7 +13205,7 @@ export class SshTui {
                     this.onSelectionChanged?.(selection);
                     await this.rememberRoute(selection);
                     await this.syncSubagentToProvider(ownerId, state.models, previousParentProvider !== ownerId);
-                    this.setupMessage(state, 'system', t('onboard.customDone', { id: ownerId, model }));
+                    this.onboardDone(t('onboard.customDone', { id: ownerId, model }));
                 }
             }
         }
@@ -12907,12 +13214,45 @@ export class SshTui {
             this.setupMessage(state, 'error', t('onboard.saveFailed', { error: errorChain(error) }));
         }
         finally {
-            this.onboarding = undefined;
             state.resolve(saved);
+            // The Screen's exit is the answer, and the answer is one of two things.
+            //
+            // **Saved**: the wizard has nothing left to ask, so it hands the workspace back
+            // in the same frame. Cancelling always did this; saving did not, so a completed
+            // setup left the reader on the wizard's own frame until they pressed a key —
+            // and only that key's "no wizard behind this Screen" fallback closed it. Every
+            // confirmation the wizard would have painted on its own row went with the
+            // Screen, which is why the completion line is a transcript row (`onboardDone`).
+            //
+            // **Failed**: the wizard keeps the screen, because the row it just wrote is the
+            // reason and the answer (an API key, a Base URL) has to stay editable to retry.
+            // Dropping the state here is what used to leave a Screen with no wizard behind
+            // it: the error was written and then thrown away with it, and the next keypress
+            // dismissed the whole flow as if nothing had been asked.
+            if (saved) {
+                this.onboarding = undefined;
+                this.closeScreen();
+            }
+            else {
+                state.saving = false;
+            }
             this.showNextDialog();
             this.markDirty();
         }
     }
+    /**
+     * Say the wizard is done, where the reader will still be able to read it.
+     *
+     * A saved wizard closes its Screen in the same frame, so its own notice row would
+     * be painted for no frames at all — and the credential line that goes with it is a
+     * footer echo (`command-feedback`), which expires. This is the durable half of the
+     * answer: `command-status` routes to the transcript, exactly like the boot line
+     * that asked for the setup in the first place.
+     */
+    onboardDone(text) {
+        this.pushRow(represent('command-status', { kind: 'system', text }));
+        this.markDirty();
+    }
     /** Store one credential, falling back to a launch-environment override on shadow/absence. */
     async saveCredential(credentials, envRef, key) {
         const shadowing = process.env[envRef];
@@ -13280,10 +13620,14 @@ export class SshTui {
         // *what* went to the clipboard, and a second press of the copy key must be
         // idempotent. Clearing it here made the next `/copy` silently fall back to
         // "the latest reply" — a different row, with nothing on screen to say so.
-        this.input = '';
-        this.cursor = 0;
-        this.inputFolded = false;
-        this.leaveHistoryBrowse();
+        //
+        // **The composer's draft is not this function's to write** (input-ownership
+        // AD-20, F-2). It used to be: `this.input = ''` + caret + fold + the history
+        // browse reset sat here from the 0.5.5 era, when `/copy` was *text submitted
+        // from the composer* and clearing it was housekeeping. The command line is
+        // `runCommand`'s to consume (it clears the composer for every command), and the
+        // key, a drag, a link click and a Screen's copy are not commands at all — a
+        // reader who typed half a message and then copied a reply lost it.
         this.write(osc52Clipboard(text));
         this.pushRow(represent('copy-feedback', { kind: 'system', text: notice }));
         // The write is a request the terminal may ignore: VTE (GNOME/XFCE/…) has
@@ -13420,13 +13764,7 @@ export class SshTui {
      * inspect overlay owns the keyboard and takes no scroll at all: the transcript
      * behind a dialog must not move.
      */
-    scrollActiveSurface(up) {
-        if (this.screen !== undefined) {
-            this.scrollScreen(up);
-            return;
-        }
-        if (this.dialog !== undefined)
-            return;
+    scrollWorkspace(up) {
         if (this.paintTailBudget > 0) {
             this.paintTailBudget = 0;
             this.forceFullPaint = true;
@@ -13815,7 +14153,7 @@ export class SshTui {
                             break;
                         }
                         const targets = ids.map(id => SessionId(id));
-                        void subagents.drainContinuableChildren(this.agent, targets).then(() => {
+                        void drainChildSubagents(subagents, this.agent, targets).then(() => {
                             this.pushRow(represent('subagent-notice', { kind: 'system', text: t('sub.killRequested', { ids: ids.join(', ') }) }));
                             this.markDirty();
                         }).catch((error) => {
@@ -13995,13 +14333,21 @@ export class SshTui {
         this.inputFolded = false;
         this.markDirty();
     }
-    /** 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.
+     */
     graphemeBefore(cursor) {
         if (cursor <= 0)
             return { start: 0, end: 0 };
         let previousStart = 0;
         let previousEnd = 0;
-        for (const segment of GRAPHEME_SEGMENTER.segment(this.input)) {
+        for (const segment of GRAPHEME_SEGMENTER.segment(this.fieldText())) {
             const start = segment.index;
             const end = start + segment.segment.length;
             if (cursor === start)
@@ -14013,9 +14359,9 @@ export class SshTui {
         }
         return { start: previousStart, end: previousEnd };
     }
-    /** Grapheme cluster containing or following `cursor`. */
+    /** Grapheme cluster containing or following `cursor`, in the field that owns the keyboard. */
     graphemeAfter(cursor) {
-        for (const segment of GRAPHEME_SEGMENTER.segment(this.input)) {
+        for (const segment of GRAPHEME_SEGMENTER.segment(this.fieldText())) {
             const start = segment.index;
             const end = start + segment.segment.length;
             if (cursor === start || (cursor > start && cursor < end))
@@ -14097,8 +14443,19 @@ export class SshTui {
         this.cursor = this.input.length;
         this.markDirty();
     }
-    /** 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 `↓`.
+     */
     leaveHistoryBrowse() {
+        if (this.borrowedText !== undefined)
+            return;
         if (this.historyIndex >= 0 && this.historyIndex < this.history.length) {
             this.historyIndex = this.history.length;
             this.historyDraft = this.input;