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

package/lib/display-sock.js

@@ -30,10 +30,13 @@ import { createConnection, createServer } from 'node:net';
 import { mkdir, readFile, unlink } from 'node:fs/promises';
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { RTT_SLOW_SAMPLE_TIMEOUT_MS, TerminalInputFilter, TerminalInputPump, } from './terminal-input.js';
+import { INPUT_HOLD_MS, RTT_SLOW_SAMPLE_TIMEOUT_MS, TerminalInputFilter, TerminalInputPump, } from './terminal-input.js';
 import { dirname, join, resolve } from 'node:path';
 import { bootstrapEnv, hostBootstrapCommand, hostSpawnOptions, restrictPathToUserSync, usesSigwinch, } from './platform.js';
 import { terminalCapabilities } from './terminal-caps.js';
+import { createParentResizeFilter } from './display-mode.js';
+import { ambiguousWidthIsTwo, setAmbiguousWidthMeasured, setAmbiguousWidthReserve } from './term-text.js';
+import { measureAmbiguousGlyphWidth } from './glyph-measure.js';
 export const FRAME_STDIN = 1;
 export const FRAME_STDOUT = 2;
 export const FRAME_RESIZE = 3;
@@ -49,14 +52,16 @@ export const FRAME_PROBE_REPLY = 9;
 export const FRAME_QUERY = 10;
 /** Host → prober: the answer to {@link FRAME_QUERY}. */
 export const FRAME_QUERY_REPLY = 11;
-const MAX_FRAME = 1024 * 1024;
 /**
- * Grace period for a kicked relay to read FRAME_REPLACED before its socket is
- * torn down. Without the frame the relay only saw `close`, read it as "the
- * Host is going away", and re-attached — two SSH windows then kicked each
- * other off the display forever, repainting the whole screen on every lap.
+ * Relay → host: what this terminal does with the ambiguous glyphs.
+ *
+ * Payload: one byte, bit 0 = the terminal advances two cells, bit 1 = the second
+ * cell has to be reserved by us with a space. Sent right after HELLO, because the
+ * Host decides every width in the session and it is the relay — not the Host —
+ * that owns the terminal to measure on.
  */
-const REPLACED_GRACE_MS = 250;
+export const FRAME_METRICS = 12;
+const MAX_FRAME = 1024 * 1024;
 /**
  * How long a connection may stay silent before the Host treats it as a
  * liveness probe and drops it.
@@ -76,6 +81,32 @@ const DISPLAY_HELLO_GRACE_MS = 6_000;
  * for a slow link), so this only has to cover those plus the socket hop.
  */
 const DISPLAY_PROBE_TIMEOUT_MS = 3_000;
+/**
+ * How long a farewell frame may hold its socket open before the backstop reaps
+ * it: `FRAME_REPLACED` to a kicked relay, `FRAME_GOODBYE` on the way out.
+ *
+ * The frame is what tells the other end *why* the socket is going — a bare close
+ * reads as a crash, and the launcher re-attaches over it. A write only queues on
+ * libuv until that end drains it, so the socket is reaped on the write callback
+ * and this is the bound that keeps a stalled reader from holding the shutdown
+ * (`launcher-exit.ts` bounds the whole graceful exit at 2 s anyway).
+ */
+const FAREWELL_FLUSH_MS = 250;
+/**
+ * How long the glyph probe may hold the Host's output waiting for an answer.
+ *
+ * The timing measurement immediately before it already says what a round trip
+ * costs on this link, so the glyph probe does not need a fixed generous window:
+ * two round trips plus a margin covers a terminal that answers late, and a
+ * terminal that answers nothing costs the attach this budget once rather than
+ * the full {@link DISPLAY_PROBE_TIMEOUT_MS}.
+ * @param rttMs - the round trip just measured, if the terminal answered.
+ */
+function glyphProbeTimeoutMs(rttMs) {
+    if (rttMs === undefined || !Number.isFinite(rttMs) || rttMs <= 0)
+        return 200;
+    return Math.min(DISPLAY_PROBE_TIMEOUT_MS, Math.max(120, Math.ceil(rttMs * 2 + 80)));
+}
 /**
  * The link is measured again this soon after an attach, then on the slower
  * cadence below.
@@ -87,6 +118,28 @@ const DISPLAY_PROBE_TIMEOUT_MS = 3_000;
  * that case without waiting a full cadence.
  */
 const RTT_RECHECK_FIRST_MS = 8_000;
+/**
+ * How often a relay re-reads its own terminal's size.
+ *
+ * The resize *event* is the fast path and this is the backstop. A geometry the
+ * Host never learns about is not a cosmetic bug: the Host composes rows for the
+ * width it believes in, so a terminal that grew keeps the new columns filled with
+ * whatever was there before — the "half the screen is stale" report — and one
+ * that shrank gets its rows truncated at the edge. Resize events can be missed
+ * (a multiplexer that does not forward them, a window manager that moves a window
+ * between monitors, a console that only reports the *initial* size), and a
+ * one-second poll of two integers costs nothing next to being wrong all session.
+ */
+const SIZE_RECHECK_MS = 1_000;
+/**
+ * How long a burst of resize events is collapsed before the geometry is sent.
+ *
+ * The first event of a burst bypasses it: a lone resize is reported at once, and
+ * only a *dragged* edge (an event every few milliseconds) pays the wait — that is
+ * where collapsing matters, because the Host would otherwise be told about every
+ * intermediate geometry the pointer passed through.
+ */
+const RELAY_RESIZE_DEBOUNCE_MS = 20;
 /** How often an attached relay re-measures the link for the Host's chip. */
 const RTT_RECHECK_MS = 20_000;
 /** After this many silent measurements, stop asking so often. */
@@ -331,6 +384,30 @@ export function encodeFrame(type, payload = Buffer.alloc(0)) {
     header.writeUInt8(type, 4);
     return Buffer.concat([header, payload]);
 }
+/**
+ * The size a relay should report.
+ *
+ * A terminal knows its own size; a parent that speaks the protocol on pipes is
+ * not a terminal, so it declares one through `COLUMNS`/`LINES` — the convention
+ * every shell and TUI already shares — and corrects it later with a resize frame
+ * if the window changes. Without either, the historical 80×24 stands.
+ * @param stdout - the stream that may be a terminal.
+ * @param env - the environment to read.
+ * @returns the columns and rows to send as the first resize.
+ */
+export function relayTerminalSize(stdout = process.stdout, env = process.env) {
+    const fromEnv = (name, fallback) => {
+        const raw = Number.parseInt(String(env[name] ?? ''), 10);
+        return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+    };
+    const columns = Number.isFinite(stdout.columns) && (stdout.columns ?? 0) > 0
+        ? Number(stdout.columns)
+        : fromEnv('COLUMNS', 80);
+    const rows = Number.isFinite(stdout.rows) && (stdout.rows ?? 0) > 0
+        ? Number(stdout.rows)
+        : fromEnv('LINES', 24);
+    return { columns, rows };
+}
 export function encodeResize(columns, rows) {
     const payload = Buffer.alloc(4);
     payload.writeUInt16BE(Math.max(0, Math.min(0xffff, columns)), 0);
@@ -370,6 +447,17 @@ export function decodeProbeReply(payload) {
     const value = decodeVerdict(payload);
     return value === 1 ? 'live' : value === 2 ? 'silent' : 'unknown';
 }
+/** Encode {@link FRAME_METRICS}. */
+export function encodeMetrics(metrics) {
+    return encodeFrame(FRAME_METRICS, Buffer.from([(metrics.wide ? 1 : 0) | (metrics.reserve ? 2 : 0)]));
+}
+/** Decode {@link FRAME_METRICS}; undefined when the payload is not one byte. */
+export function decodeMetrics(payload) {
+    if (payload.length < 1)
+        return undefined;
+    const flags = payload[0] ?? 0;
+    return { wide: (flags & 1) !== 0, reserve: (flags & 2) !== 0 };
+}
 export function encodeQuery() {
     return encodeFrame(FRAME_QUERY);
 }
@@ -499,7 +587,7 @@ export class DisplayHost {
                     catch {
                         // already gone
                     }
-                }, REPLACED_GRACE_MS);
+                }, FAREWELL_FLUSH_MS);
                 reap.unref?.();
                 try {
                     previous.end(encodeFrame(FRAME_REPLACED), () => {
@@ -574,6 +662,11 @@ export class DisplayHost {
                     if (size !== undefined)
                         this.handlers.onResize(size.columns, size.rows);
                 }
+                else if (frame.type === FRAME_METRICS) {
+                    const metrics = decodeMetrics(frame.payload);
+                    if (metrics !== undefined)
+                        this.handlers.onMetrics?.(metrics);
+                }
                 else if (frame.type === FRAME_RTT) {
                     this.handlers.onRtt?.(decodeRtt(frame.payload));
                 }
@@ -669,6 +762,30 @@ export class DisplayHost {
         this.probeSettle = undefined;
         settle?.(verdict);
     }
+    /**
+     * How many bytes are queued for the terminal and still undelivered.
+     *
+     * The Host composes every frame, and on a resize it is the only one that can
+     * decide whether there is room for another one: the socket the frames travel on
+     * belongs to this object. Without the number the Host can only *guess* how fast
+     * the link is (from the measured round trip) and pace itself conservatively,
+     * which is what made a drag lag behind the pointer on a fast link. With it, the
+     * rule becomes the honest one: paint the new size now, unless the previous frame
+     * has not left yet.
+     * @returns queued bytes, or undefined when no display is attached.
+     */
+    pendingBytes() {
+        const socket = this.socket;
+        if (socket === undefined || this.attached !== true)
+            return undefined;
+        try {
+            const size = Number(socket.writableLength);
+            return Number.isFinite(size) ? size : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     sendStdout(bytes) {
         const socket = this.socket;
         if (socket === undefined || this.attached !== true)
@@ -693,12 +810,49 @@ export class DisplayHost {
             // ignore
         }
     }
+    /**
+     * Say goodbye and let the frame leave before the socket is reaped.
+     *
+     * The frame is what tells the launcher to exit instead of reading the close as
+     * a crash and re-attaching (`attach.ts`) — the replacement path flushes
+     * `FRAME_REPLACED` for exactly the same reason. A write only *queues* on libuv
+     * until the peer drains it, and reaping the socket cancels what is still
+     * queued: on a busy link, with a starting session still painting into that
+     * socket, the goodbye was dropped along with those frames and the launcher
+     * re-attached over the user's own `/exit` instead of exiting.
+     */
+    async farewellAndReap(socket) {
+        await new Promise(resolve => {
+            let settled = false;
+            const done = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(reap);
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    // already gone
+                }
+                resolve();
+            };
+            const reap = setTimeout(done, FAREWELL_FLUSH_MS);
+            reap.unref?.();
+            try {
+                socket.end(encodeFrame(FRAME_GOODBYE), done);
+            }
+            catch {
+                done();
+            }
+        });
+    }
     async close() {
-        this.sendGoodbye();
         const socket = this.socket;
         this.socket = undefined;
         this.attached = false;
-        socket?.destroy();
+        if (socket !== undefined)
+            await this.farewellAndReap(socket);
         const server = this.server;
         this.server = undefined;
         await new Promise(resolve => {
@@ -1058,6 +1212,47 @@ export function restoreTerminalInput(stdin = process.stdin) {
         // ignore
     }
 }
+/**
+ * The environment a detached Host is started with.
+ *
+ * Notable entries: the marker that tells the child it *is* the Host, and the
+ * ambiguous-width decision. The Host paints, but its own stdout is the relay
+ * socket, so it cannot look at a TTY to know how wide the window's terminal
+ * draws `①` or `—`; this process has that terminal, so it decides and hands the
+ * answer over. An explicit value in the environment still wins.
+ * @param env - the parent environment (a test passes its own).
+ * @param onTerminal - whether *this* process owns a terminal; it is the evidence
+ *   the width table is chosen from, and a test harness is not a terminal.
+ * @returns the child environment.
+ */
+export function hostChildEnv(env = process.env, onTerminal = process.stdout?.isTTY === true, measuredAmbiguousWide) {
+    // Two facts travel, because they are two facts: how many cells the terminal
+    // *advances* for these glyphs, and whether the second one has to be spent by
+    // us with a reserving space (the glyph drawn wider than its cell). Sending only
+    // the advance would leave the Host painting the collision the measurement was
+    // taken to fix.
+    const envValue = env.DSH_TUI_AMBIGUOUS_WIDTH;
+    const measured = measuredAmbiguousWide === undefined
+        ? undefined
+        : (measuredAmbiguousWide
+            ? { width: '2', reserve: '0' }
+            : { width: '1', reserve: '1' });
+    const fallback = measured === undefined
+        ? { width: ambiguousWidthIsTwo(env, onTerminal) ? '2' : '1', reserve: '0' }
+        : measured;
+    return {
+        ...env,
+        [TUI_HOST_ENV]: '1',
+        DSH_HOME: resolveDshHome(),
+        // An explicit setting is the reader's, and is left alone in both directions.
+        ...(envValue === undefined
+            ? {
+                DSH_TUI_AMBIGUOUS_WIDTH: fallback.width,
+                DSH_TUI_AMBIGUOUS_RESERVE: fallback.reserve,
+            }
+            : {}),
+    };
+}
 /**
  * Start the Host through the hidden-console bootstrap and return its pid, or
  * `undefined` when the bootstrap could not report one.
@@ -1148,7 +1343,7 @@ export function spawnDetachedHost(sessionId, platform = process.platform, option
     // session's working directory before it listens, so an unset, blank or
     // relative home would otherwise resolve differently there and the two
     // processes would compute different channel names.
-    const env = { ...process.env, [TUI_HOST_ENV]: '1', DSH_HOME: resolveDshHome() };
+    const env = hostChildEnv(process.env, process.stdout?.isTTY === true, options.ambiguousWide);
     const argv = hostArgvForSession(sessionId);
     // Without the stderr log there is nowhere to redirect the Host's stderr, and
     // leaving it un-redirected would hand it this process's stdio; the direct
@@ -1263,27 +1458,89 @@ export async function runDisplayRelay(path, options = {}) {
         let replaced = false;
         const pending = [];
         let pendingBytes = 0;
+        // The Host's output while the glyph probe owns the terminal. Writing a frame
+        // between the probe's print and its erase is what puts the erase on the
+        // frame's row and leaves the glyphs on the screen the shell comes back to.
+        let holdingOutput = false;
+        let heldOutput = [];
+        let heldOutputBytes = 0;
+        const heldOutputLimit = 256 * 1024;
+        const flushHeldOutput = () => {
+            const held = heldOutput;
+            heldOutput = [];
+            heldOutputBytes = 0;
+            for (const payload of held) {
+                try {
+                    stdout.write(payload);
+                }
+                catch {
+                    finish('signal');
+                    return;
+                }
+            }
+        };
+        /** Drop the frames held for the glyph probe without writing them. */
+        const discardHeldOutput = () => {
+            heldOutput = [];
+            heldOutputBytes = 0;
+        };
         if (options.seed !== undefined && options.seed !== '') {
             const seed = Buffer.from(options.seed, 'utf8');
             pending.push(seed);
             pendingBytes += seed.length;
         }
+        /**
+         * Say out loud what settled the relay, under `DSH_TUI_DEBUG=1`.
+         *
+         * The reason decides whether the launcher exits or re-attaches
+         * (`attach.ts`), and nothing on either side of the socket prints it: a red
+         * probe shows frames and a process that never went, with no way to tell "the
+         * Host said goodbye and the launcher ignored it" from "the link broke before
+         * the goodbye arrived". One line each way is what makes that readable, and
+         * it is off unless the variable is set.
+         */
+        const note = (message) => {
+            if (process.env.DSH_TUI_DEBUG === '1')
+                process.stderr.write(`dsh-ssh-tui: display relay ${message}\n`);
+        };
         const finish = (reason) => {
             if (settled)
                 return;
             settled = true;
-            cleanup();
-            resolve({ reason });
+            note(`settling: ${reason}`);
+            void releaseTerminal().then(() => {
+                cleanup();
+                resolve({ reason });
+            });
         };
         /** Reject like `finish`, but restore the terminal first. */
         const fail = (error) => {
             if (settled)
                 return;
             settled = true;
-            cleanup();
-            reject(error);
+            note(`failed: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`);
+            void releaseTerminal().then(() => {
+                cleanup();
+                reject(error);
+            });
+        };
+        /**
+         * One more round trip in raw mode before the shell gets the TTY back.
+         *
+         * A reply to a probe we have already given up on would otherwise be echoed
+         * by the tty as `^[[25;1R` text at the user's prompt — the leaked escape
+         * sequence readers report after leaving a session over a slow link.
+         */
+        const releaseTerminal = async () => {
+            const grace = reportedRtt === undefined
+                ? 0
+                : Math.min(400, Math.max(60, Math.ceil(reportedRtt * 2 + 40)));
+            await pump.handBack(grace);
         };
         const cleanup = () => {
+            if (sizeTimer !== undefined)
+                clearTimeout(sizeTimer);
+            sizeTimer = undefined;
             if (rttTimer !== undefined)
                 clearTimeout(rttTimer);
             rttTimer = undefined;
@@ -1295,7 +1552,7 @@ export async function runDisplayRelay(path, options = {}) {
             signals.removeListener('SIGHUP', onLocalHangup);
             signals.removeListener('SIGTERM', onLocalHangup);
             try {
-                stdin.setRawMode(false);
+                stdin.setRawMode?.(false);
             }
             catch {
                 // ignore
@@ -1304,6 +1561,14 @@ export async function runDisplayRelay(path, options = {}) {
                 clearTimeout(resizeTimer);
                 resizeTimer = undefined;
             }
+            // A run still held for a report that never came is dropped, not forwarded:
+            // the relay is going away, and every path here has already stopped reading
+            // stdin (`handBack` above marks the pump as dropping), so nothing can turn
+            // it into a report now.
+            if (parentResizeTimer !== undefined) {
+                clearTimeout(parentResizeTimer);
+                parentResizeTimer = undefined;
+            }
             stdout.off('resize', onResize);
             if (usesSigwinch()) {
                 signals.off('SIGWINCH', onResize);
@@ -1339,7 +1604,9 @@ export async function runDisplayRelay(path, options = {}) {
          * on the floor: the probe owned the only stdin listener and the forwarder
          * was attached afterwards. Hold them (bounded) and flush on HELLO.
          */
-        const deliver = (text) => {
+        const parentResize = createParentResizeFilter();
+        let parentResizeTimer;
+        const forwardInput = (text) => {
             if (text === '')
                 return;
             const bytes = Buffer.from(text, 'utf8');
@@ -1358,34 +1625,139 @@ export async function runDisplayRelay(path, options = {}) {
                 finish('host-closed');
             }
         };
-        const pump = new TerminalInputPump({
-            stdin,
-            stdout,
-            onInput: deliver,
-            ...(options.ssh === undefined ? {} : { ssh: options.ssh }),
-            // Only while the boot splash is up: the TUI is not painted yet, so a
-            // diagnostic line cannot garble a live screen.
-            ...(process.env.DSH_TUI_DEBUG === '1'
-                ? { debug: (message) => { process.stderr.write(`dsh-ssh-tui: ${message}\n`); } }
-                : {}),
-        });
+        /**
+         * Hand a held run over once its window passes.
+         *
+         * A lone `ESC` is the case this exists for: it is the first byte of a report
+         * that could still be split across two reads, but it is far more often the
+         * user's Escape key — and the pump in front of this filter has already given
+         * it the same window. Held without a deadline of its own, Escape reached the
+         * Host only when another key arrived, and then glued to it as an Alt chord:
+         * cancelling a dialog or interrupting a running turn did nothing.
+         */
+        const releaseParentResize = () => {
+            if (parentResizeTimer !== undefined) {
+                clearTimeout(parentResizeTimer);
+                parentResizeTimer = undefined;
+            }
+            const held = parentResize.flush();
+            // A relay that has been replaced (or told goodbye) writes nothing more —
+            // not even a key it was still holding. `finish` only settles the relay and
+            // then waits out a round trip before `cleanup`, so this deadline can fire
+            // inside that window; the key goes with the link it was typed on.
+            if (settled)
+                return;
+            forwardInput(held);
+        };
         let resizeTimer;
+        /**
+         * The geometry to report, resolved at the moment it is sent.
+         *
+         * Two callers own the size in two different ways, and conflating them is what
+         * made a window resize do nothing at all:
+         *
+         * - a **pipe parent** has no `resize` event and no SIGWINCH; it declares the
+         *   panel's geometry with `CSI 8 ; rows ; cols t`, which arrives on the input
+         *   pipe and is remembered here (`reported`), and
+         * - a **terminal we own** is read *now*. Snapshotting `relayTerminalSize` once
+         *   per relay and re-sending it from the debounced handler meant every resize
+         *   after the first reported the attach-time geometry, so the Host saw no
+         *   change, skipped the repaint, and the frame stayed at the old width while
+         *   the user dragged the window.
+         *
+         * Reading at send time also collapses a burst of events to the newest size,
+         * which is the point of the debounce in the first place.
+         */
+        let reportedSize;
+        /** What the Host was told last, so a re-check only speaks when it moved. */
+        let lastSentSize = { columns: 0, rows: 0 };
+        let sizeTimer;
+        const currentSize = () => reportedSize ?? relayTerminalSize(stdout);
         const sendResize = () => {
+            const size = currentSize();
+            lastSentSize = { columns: size.columns, rows: size.rows };
             try {
-                socket.write(encodeResize(stdout.columns || 80, stdout.rows || 24));
+                socket.write(encodeResize(size.columns, size.rows));
             }
             catch {
                 finish('host-closed');
             }
         };
+        /**
+         * Report the size again if it moved without an event saying so.
+         *
+         * Only the terminal this relay owns is polled: a pipe parent's geometry is
+         * the parent's to declare, and reading `columns` there would answer with a
+         * default the parent never chose.
+         */
+        const recheckSize = () => {
+            if (settled)
+                return;
+            if (reportedSize === undefined) {
+                const now = relayTerminalSize(stdout);
+                if (now.columns !== lastSentSize.columns || now.rows !== lastSentSize.rows)
+                    sendResize();
+            }
+            sizeTimer = setTimeout(recheckSize, options.sizeRecheckMs ?? SIZE_RECHECK_MS);
+            sizeTimer.unref?.();
+        };
+        /**
+         * Report a resize, collapsing a burst.
+         *
+         * The first event of a burst goes out at once: a single resize (a window
+         * snap, a `tmux` pane change) has nothing to be collapsed with, and making it
+         * wait 20 ms added that delay to every one of them for no benefit. The
+         * debounce is for the rest of the burst — a dragged edge emits events every
+         * few milliseconds, and the Host only needs the geometry the drag lands on.
+         */
         const onResize = () => {
-            if (resizeTimer !== undefined)
-                clearTimeout(resizeTimer);
+            if (resizeTimer === undefined) {
+                sendResize();
+                resizeTimer = setTimeout(() => {
+                    resizeTimer = undefined;
+                }, RELAY_RESIZE_DEBOUNCE_MS);
+                return;
+            }
+            clearTimeout(resizeTimer);
             resizeTimer = setTimeout(() => {
                 resizeTimer = undefined;
                 sendResize();
-            }, 20);
+            }, RELAY_RESIZE_DEBOUNCE_MS);
+        };
+        const deliver = (text) => {
+            // A pipe parent has no `resize` event to fire and no SIGWINCH to raise:
+            // `CSI 8 ; rows ; cols t` on the input pipe is how it says the panel is
+            // now a different size. Those bytes are not typing, and the rest of the
+            // read is.
+            const { forward, sizes } = parentResize.push(text);
+            for (const reported of sizes) {
+                // The parent's declaration outranks the terminal we cannot see: a pipe
+                // parent may not even have a `columns` for this process to read.
+                reportedSize = { columns: reported.columns, rows: reported.rows };
+                sendResize();
+            }
+            if (parentResize.pending) {
+                if (parentResizeTimer !== undefined)
+                    clearTimeout(parentResizeTimer);
+                // Referenced on purpose, like the pump's own hold timer: this timer
+                // *completes* an operation the caller started (releasing a held key),
+                // and an unref'd one would let the event loop drain with the release
+                // still pending.
+                parentResizeTimer = setTimeout(releaseParentResize, INPUT_HOLD_MS);
+            }
+            forwardInput(forward);
         };
+        const pump = new TerminalInputPump({
+            stdin,
+            stdout,
+            onInput: deliver,
+            ...(options.ssh === undefined ? {} : { ssh: options.ssh }),
+            // Only while the boot splash is up: the TUI is not painted yet, so a
+            // diagnostic line cannot garble a live screen.
+            ...(process.env.DSH_TUI_DEBUG === '1'
+                ? { debug: (message) => { process.stderr.write(`dsh-ssh-tui: ${message}\n`); } }
+                : {}),
+        });
         /**
          * Keep the Host's picture of the link current.
          *
@@ -1396,6 +1768,10 @@ export async function runDisplayRelay(path, options = {}) {
          * user typed meanwhile to the Host as usual.
          */
         const recheckRtt = async () => {
+            // Never probe a terminal we have already given back: the request would be
+            // answered by the shell's tty in cooked mode, which echoes it as text.
+            if (settled)
+                return;
             const measured = await pump.measure();
             if (settled)
                 return;
@@ -1469,7 +1845,10 @@ export async function runDisplayRelay(path, options = {}) {
         socket.on('connect', () => {
             void (async () => {
                 try {
-                    stdin.setRawMode(true);
+                    // Optional: a pipe parent (`DSH_TUI_DISPLAY=stdio`) has no line
+                    // discipline to put in raw mode, and calling it unguarded threw here —
+                    // before the relay could say hello, which made the mode unusable.
+                    stdin.setRawMode?.(true);
                     stdin.resume();
                     // Subscribed before the first await: an EOF that lands during the
                     // probe (SSH dropped while the TTY was quiet) used to be missed
@@ -1501,15 +1880,78 @@ export async function runDisplayRelay(path, options = {}) {
                     // tells us nothing (see `TerminalVerdict`).
                     terminalAnswered = rtt !== undefined;
                     reportedRtt = rtt;
-                    const columns = stdout.columns || 80;
-                    const rows = stdout.rows || 24;
+                    // The handshake carries the geometry as it is *now*: a parent that
+                    // declared a size on the input pipe before HELLO has already won
+                    // (`reportedSize`), and a terminal is read fresh.
+                    const { columns, rows } = currentSize();
+                    // The handshake *is* a resize report, and the size poll compares
+                    // against what the Host was told: leave this out and the first poll
+                    // speaks up to repeat a geometry the Host already has.
+                    lastSentSize = { columns, rows };
                     socket.write(Buffer.concat([
                         encodeFrame(FRAME_HELLO),
                         encodeResize(columns, rows),
                         encodeRtt(rtt),
                     ]));
                     live = true;
+                    // Measure what this terminal does with `①` and friends, now that the
+                    // pump is running and the reply will be swallowed rather than echoed.
+                    // `DSH_TUI_NO_GLYPH_PROBE=1` keeps the write out of the stream entirely
+                    // for a harness that asserts the exact bytes of an attach.
+                    // The Host decides every width in the session, so the verdict travels
+                    // as a frame; it is sent after HELLO, because the Host ignores
+                    // everything that arrives before the claim.
+                    //
+                    // The probe prints the glyphs and then asks where the cursor ended up:
+                    // both writes belong to the terminal, and nothing else may land between
+                    // them. On a slow SSH link the answer takes longer than the Host takes
+                    // to paint its first frame, so the frame used to arrive inside that
+                    // window — the erase then wiped a row of it, and the glyphs stayed on
+                    // the screen for the shell to show again on the way out. Hold the
+                    // Host's output for the round trip instead; it is one frame, and the
+                    // boot splash is what the user is looking at.
+                    // A terminal that never answered the timing probe will not answer this
+                    // one either: asking would only cost the reply budget at every attach.
+                    if (terminalAnswered && process.env.DSH_TUI_NO_GLYPH_PROBE !== '1') {
+                        holdingOutput = true;
+                        let measured;
+                        try {
+                            measured = await measureAmbiguousGlyphWidth({
+                                pump,
+                                timeoutMs: glyphProbeTimeoutMs(rtt ?? reportedRtt),
+                            });
+                        }
+                        finally {
+                            holdingOutput = false;
+                            // A relay that was replaced (or told goodbye) while the probe was
+                            // waiting owes this link nothing — that is the replacement path's
+                            // whole contract. Flushing here put the old Host's queued frame
+                            // back on a window the user has left: a live one shows a stale
+                            // frame, and a dropped SSH link buffers it until it comes back,
+                            // where it paints over the session that took over.
+                            if (settled)
+                                discardHeldOutput();
+                            else
+                                flushHeldOutput();
+                        }
+                        if (settled)
+                            return;
+                        if (measured !== undefined) {
+                            const reserve = measured.wide === false;
+                            setAmbiguousWidthReserve(reserve);
+                            setAmbiguousWidthMeasured(measured.wide);
+                            try {
+                                socket.write(encodeMetrics({ wide: measured.wide, reserve }));
+                            }
+                            catch {
+                                // The link is gone; the Host keeps the locale default.
+                            }
+                        }
+                    }
                     scheduleRttRecheck(options.rttFirstRecheckMs ?? RTT_RECHECK_FIRST_MS);
+                    // The size backstop, started with the geometry the handshake claimed:
+                    // every later poll compares against what the Host was actually told.
+                    recheckSize();
                     if (options.announce === true) {
                         try {
                             stdout.write('\r\x1b[2K');
@@ -1549,6 +1991,19 @@ export async function runDisplayRelay(path, options = {}) {
             }
             for (const frame of frames) {
                 if (frame.type === FRAME_STDOUT) {
+                    if (holdingOutput) {
+                        // Bound the hold: a Host that streams into a probe that never comes
+                        // back must not be able to grow this without bound.
+                        if (heldOutputBytes + frame.payload.length > heldOutputLimit) {
+                            holdingOutput = false;
+                            flushHeldOutput();
+                        }
+                        else {
+                            heldOutput.push(frame.payload);
+                            heldOutputBytes += frame.payload.length;
+                            continue;
+                        }
+                    }
                     try {
                         stdout.write(frame.payload);
                     }