dsh-ssh-tui 0.7.2 → 0.7.4

package/lib/display-sock.js

@@ -6,7 +6,9 @@
  * and a named pipe at `\\.\pipe\dsh-tui-<home>-<id>` on Windows. Node requires
  * the `\\.\pipe\` form there — a plain file path cannot be listened on — and
  * `fs.access()` cannot see pipes, so channel liveness always goes through
- * `displaySockExists()` instead of a raw filesystem check.
+ * `displaySockExists()` instead of a raw filesystem check. The POSIX name is
+ * budgeted against `sun_path` (107 bytes on Linux, 103 on macOS): a deep
+ * `DSH_HOME` shortens the readable label, it never fails `listen()`.
  *
  * Frame: u32be length | u8 type | payload
  *   1 stdin   — relay → host (key bytes)
@@ -16,16 +18,22 @@
  *   5 goodbye — host → relay, then close (user /exit)
  *   6 rtt     — relay → host (u32be milliseconds; 0xffffffff = unknown)
  *   7 replaced — host → relay, then close (a newer Display took the session)
+ *   8 probe   — host → relay: round-trip your terminal and report it
+ *   9 probe?  — relay → host: 1 live, 2 silent (answered before, not now), 0 unknown
+ *  10 query   — any process → host: is a window really on this session?
+ *  11 query?  — host → that process: 1 attached, 2 detached, 0 cannot tell
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import { createHash } from 'node:crypto';
 import { createConnection, createServer } from 'node:net';
 import { mkdir, readFile, unlink } from 'node:fs/promises';
-import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { TerminalInputFilter, TerminalInputPump } from './terminal-input.js';
+import { 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';
 export const FRAME_STDIN = 1;
 export const FRAME_STDOUT = 2;
 export const FRAME_RESIZE = 3;
@@ -33,6 +41,14 @@ export const FRAME_HELLO = 4;
 export const FRAME_GOODBYE = 5;
 export const FRAME_RTT = 6;
 export const FRAME_REPLACED = 7;
+/** Host → relay: round-trip your terminal now and say what it answered. */
+export const FRAME_PROBE = 8;
+/** Relay → Host: the answer to {@link FRAME_PROBE}. */
+export const FRAME_PROBE_REPLY = 9;
+/** A prober → Host: is a window *really* on this session? Does not claim it. */
+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
@@ -53,6 +69,40 @@ const REPLACED_GRACE_MS = 250;
  * attach at all — hence the wider grace.
  */
 const DISPLAY_HELLO_GRACE_MS = 6_000;
+/**
+ * How long the Host waits for a relay's terminal round trip.
+ *
+ * The relay's own probe is two windows at most (a fast one, then a widened one
+ * for a slow link), so this only has to cover those plus the socket hop.
+ */
+const DISPLAY_PROBE_TIMEOUT_MS = 3_000;
+/**
+ * The link is measured again this soon after an attach, then on the slower
+ * cadence below.
+ *
+ * The first measurement is taken while the session is still booting, and a
+ * jittery moment there used to be the only measurement there ever was: the
+ * footer chip stayed red and the paint cadence — with the per-frame byte budget
+ * — stayed at the slowest tier for hours. The early re-check corrects exactly
+ * that case without waiting a full cadence.
+ */
+const RTT_RECHECK_FIRST_MS = 8_000;
+/** 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. */
+const RTT_RECHECK_MAX_MISSES = 3;
+/** A terminal that does not answer DSR is asked again only this rarely. */
+const RTT_RECHECK_BACKOFF_MS = 600_000;
+/**
+ * A measurement that moved by at least this much is confirmed soon after.
+ *
+ * The Host smooths over the last few measurements, so the *second* sample is
+ * what makes a real change stick — or what retires a one-off spike — and waiting
+ * a whole cadence for it keeps the chip on the wrong tier for that long.
+ */
+const RTT_MOVED_MS = 50;
+/** How soon a moved measurement is confirmed. */
+const RTT_RECHECK_CONFIRM_MS = 5_000;
 /**
  * Drop launcher SIGTERM/SIGINT/SIGHUP so closing SSH cannot dispose the tree
  * before hangup handling. Leaving the session with setsid() is best-effort:
@@ -82,8 +132,36 @@ export function isTuiHostProcess(env = process.env) {
  * path fails with ENOENT/EACCES and the Host never listens.
  */
 export const WINDOWS_PIPE_PREFIX = '\\\\.\\pipe\\';
+/**
+ * How long the hidden-console bootstrap may take to report the Host's pid. It
+ * covers a cold PowerShell start on a busy machine, and nothing of the Host's
+ * own boot: `Start-Process -PassThru` returns as soon as the process exists.
+ */
+const HOST_BOOTSTRAP_TIMEOUT_MS = 15_000;
 /** Windows rejects pipe names longer than 256 chars; leave generous headroom. */
 const WINDOWS_PIPE_MAX = 200;
+/**
+ * `sockaddr_un.sun_path` counts its NUL terminator, so a POSIX socket address
+ * may occupy 107 bytes on Linux and 103 on macOS. Overrunning it fails
+ * `listen()` with EINVAL before the Host can print anything, which the launcher
+ * could only report as "the socket did not appear" — hence the budget below.
+ */
+function posixSocketPathMax(platform) {
+    return platform === 'darwin' ? 103 : 107;
+}
+/** Every socket name ends in this; it is never part of the head budget. */
+const SOCK_SUFFIX = '.sock';
+/**
+ * Longest readable head a socket name asks for. A home shallow enough to have
+ * room for it keeps exactly the name it had before the budget existed.
+ */
+const SOCK_LABEL_MAX = 80;
+/**
+ * Shortest socket name worth emitting: a five-character head, the separator and
+ * the digest. Below this the head is noise and the address is refused with the
+ * real reason instead of being handed to `listen()` to fail on.
+ */
+const SOCK_LABEL_MIN = 14;
 /** True for a Windows named-pipe address (`\\.\pipe\x`, `\\?\pipe\x`, `//./pipe/x`). */
 export function isPipePath(path) {
     const normalized = path.replaceAll('/', '\\').toLowerCase();
@@ -112,6 +190,13 @@ export function safeSessionId(sessionId) {
     const safe = sessionId.replaceAll(/[^A-Za-z0-9._-]/g, '_');
     return safe === '' ? 'session' : safe;
 }
+/**
+ * Digest that keeps two sessions with collapsing names apart. It is appended to
+ * every label, however much head a tight path budget has to cut.
+ */
+function sessionDigest(sessionId) {
+    return createHash('sha1').update(sessionId).digest('hex').slice(0, 8);
+}
 /**
  * Readable, collision-free short label for one session: a sanitized head plus a
  * digest of the raw id. The digest is always appended because sanitizing alone
@@ -121,13 +206,36 @@ export function safeSessionId(sessionId) {
  * the wrong session.
  */
 export function sessionLabel(sessionId, maxLength) {
-    const digest = createHash('sha1').update(sessionId).digest('hex').slice(0, 8);
+    const digest = sessionDigest(sessionId);
     const head = safeSessionId(sessionId)
         .replaceAll(/\.{2,}/gu, '_')
         .replace(/^[._-]+|[._-]+$/gu, '')
         .slice(0, Math.max(0, maxLength - digest.length - 1));
     return `${head === '' ? 'session' : head}-${digest}`;
 }
+/**
+ * One POSIX socket *name* (the directory is prepended by the caller).
+ *
+ * The directory is measured in bytes, not characters: `sun_path` counts the
+ * encoded address, and a home with non-ASCII characters spends more than one
+ * byte per character. As the directory grows the readable head shrinks — a deep
+ * `DSH_HOME` loses the label, never the channel — while a home that used to fit
+ * keeps its old name byte for byte. A home too deep even for a short head is
+ * refused here, with the real reason, instead of by `listen()` EINVAL.
+ */
+function posixSocketName(sessionId, dir, platform) {
+    const limit = posixSocketPathMax(platform);
+    // The separator and the suffix are not negotiable; only the head is.
+    const room = limit - Buffer.byteLength(dir) - 1 - SOCK_SUFFIX.length;
+    if (room < SOCK_LABEL_MIN) {
+        throw new Error(`dsh-ssh-tui: ${dir} is too deep for a Unix socket: only ${Math.max(0, room)} of the ${limit} bytes `
+            + `sun_path allows are left for the name, and a usable name needs ${SOCK_LABEL_MIN}. `
+            + 'Point DSH_HOME at a shorter path.');
+    }
+    // Safe session ids are ASCII by construction (`safeSessionId`), so the label's
+    // length in characters is its length in bytes.
+    return `${sessionLabel(sessionId, Math.min(SOCK_LABEL_MAX, room))}${SOCK_SUFFIX}`;
+}
 /**
  * Named pipes live in one flat, machine-wide namespace, so the DSH_HOME is
  * folded into the name (two homes must not fight over one session id) and the
@@ -135,9 +243,12 @@ export function sessionLabel(sessionId, maxLength) {
  * into collisions.
  */
 function windowsPipePath(sessionId, dshHome) {
-    const homeTag = createHash('sha1').update(resolve(dshHome).toLowerCase()).digest('hex').slice(0, 8);
-    const room = WINDOWS_PIPE_MAX - WINDOWS_PIPE_PREFIX.length - 'dsh-tui-'.length - homeTag.length - 1;
-    return `${WINDOWS_PIPE_PREFIX}dsh-tui-${homeTag}-${sessionLabel(sessionId, room)}`;
+    const homeTag = sessionDigest(resolve(dshHome).toLowerCase());
+    // `\\.\pipe\` is a flat, machine-wide namespace with a 256-character name
+    // limit; WINDOWS_PIPE_MAX keeps the whole address well inside it, and the
+    // label's digest keeps two long ids apart however much head gets cut.
+    const head = `${WINDOWS_PIPE_PREFIX}dsh-tui-${homeTag}-`;
+    return `${head}${sessionLabel(sessionId, WINDOWS_PIPE_MAX - head.length)}`;
 }
 /**
  * Address of the per-session display channel: a filesystem path on POSIX, a
@@ -147,8 +258,8 @@ function windowsPipePath(sessionId, dshHome) {
 export function sessionSockPath(sessionId, dshHome = defaultDshHome(), platform = process.platform) {
     if (platform === 'win32')
         return windowsPipePath(sessionId, dshHome);
-    // UNIX_PATH_MAX is 108 on Linux; leave headroom for the directory prefix.
-    return join(sessionSockDir(dshHome), `${sessionLabel(sessionId, 80)}.sock`);
+    const dir = sessionSockDir(dshHome);
+    return join(dir, posixSocketName(sessionId, dir, platform));
 }
 /**
  * Pre-digest POSIX socket path (`tui-socks/<safeId>.sock`).
@@ -188,6 +299,19 @@ export function sessionErrPath(sessionId, dshHome = defaultDshHome(), platform =
         return join(sessionSockDir(dshHome), `${sessionLabel(sessionId, 64)}.err`);
     return `${sock}.err`;
 }
+/**
+ * Where the hidden-console bootstrap writes the Host's pid.
+ *
+ * On `\\.\pipe\` Windows there is no socket file to derive a name from, and the
+ * state directory already holds the per-session lock and stderr log, so the pid
+ * file lives beside them. It is removed as soon as it has been read.
+ */
+export function sessionBootstrapPidPath(sessionId, dshHome = defaultDshHome()) {
+    // Same label budget as the stderr log next to it: these live in the state
+    // directory rather than next to a socket file, and a long name here is
+    // MAX_PATH budget spent for nothing.
+    return join(sessionSockDir(dshHome), `${sessionLabel(sessionId, 64)}.boot.pid`);
+}
 /** Pre-digest Host stderr log next to the 0.7.1 socket, when that name differs. */
 export function legacySessionErrPath(sessionId, dshHome = defaultDshHome(), platform = process.platform) {
     const legacy = legacySessionSockPath(sessionId, dshHome, platform);
@@ -229,6 +353,33 @@ export function decodeRtt(payload) {
     const value = payload.readUInt32BE(0);
     return value === 0xffffffff ? undefined : value;
 }
+/** One byte of verdict: 1 live, 2 silent, 0 anything else (unknown). */
+function encodeVerdict(type, value) {
+    return encodeFrame(type, Buffer.from([value]));
+}
+function decodeVerdict(payload) {
+    return payload.length > 0 ? payload.readUInt8(0) : 0;
+}
+export function encodeProbe() {
+    return encodeFrame(FRAME_PROBE);
+}
+export function encodeProbeReply(verdict) {
+    return encodeVerdict(FRAME_PROBE_REPLY, verdict === 'live' ? 1 : verdict === 'silent' ? 2 : 0);
+}
+export function decodeProbeReply(payload) {
+    const value = decodeVerdict(payload);
+    return value === 1 ? 'live' : value === 2 ? 'silent' : 'unknown';
+}
+export function encodeQuery() {
+    return encodeFrame(FRAME_QUERY);
+}
+export function encodeQueryReply(verdict) {
+    return encodeVerdict(FRAME_QUERY_REPLY, verdict === 'attached' ? 1 : verdict === 'detached' ? 2 : 0);
+}
+export function decodeQueryReply(payload) {
+    const value = decodeVerdict(payload);
+    return value === 1 ? 'attached' : value === 2 ? 'detached' : 'unknown';
+}
 /** Incremental decoder for one socket. */
 export class FrameReader {
     buffer = Buffer.alloc(0);
@@ -276,8 +427,12 @@ export class DisplayHost {
     socket;
     reader = new FrameReader();
     attached = false;
+    /** Set while a {@link FRAME_PROBE} round trip is waiting for its answer. */
+    probeSettle;
+    probeInFlight;
     constructor(path, handlers, 
-    /** Test seam: how long a silent connection may wait for its HELLO. */
+    /** Test seams: how long a silent connection may wait for its HELLO, and
+     *  how long a relay may take to report its terminal round trip. */
     options = {}) {
         this.path = path;
         this.handlers = handlers;
@@ -404,6 +559,12 @@ export class DisplayHost {
             for (const frame of frames) {
                 if (frame.type === FRAME_HELLO)
                     claim();
+                else if (frame.type === FRAME_QUERY) {
+                    // A prober asking whether a window is really on this session. It is
+                    // deliberately not a claim: answering must never steal the display
+                    // from the window the question is about.
+                    void this.answerQuery(socket);
+                }
                 else if (!claimed)
                     continue;
                 else if (frame.type === FRAME_STDIN)
@@ -416,6 +577,9 @@ export class DisplayHost {
                 else if (frame.type === FRAME_RTT) {
                     this.handlers.onRtt?.(decodeRtt(frame.payload));
                 }
+                else if (frame.type === FRAME_PROBE_REPLY) {
+                    this.settleProbe(decodeProbeReply(frame.payload));
+                }
             }
         });
         socket.on('close', () => {
@@ -432,6 +596,79 @@ export class DisplayHost {
         const probeGrace = setTimeout(dropProbe, this.options.helloGraceMs ?? DISPLAY_HELLO_GRACE_MS);
         probeGrace.unref?.();
     }
+    /**
+     * Whether a window is really on this session — asked of the window itself.
+     *
+     * "The socket answers" is not evidence. A relay whose SSH link was cut stays
+     * connected (its launcher sees no hangup until sshd does), and the Host then
+     * truthfully reports a display that no longer has a screen behind it. Only the
+     * far end can settle it, so this round-trips the terminal through the relay.
+     */
+    async attachmentVerdict() {
+        if (this.socket === undefined || this.attached !== true)
+            return 'detached';
+        const terminal = await this.probeTerminal();
+        if (terminal === 'live')
+            return 'attached';
+        if (terminal === 'silent')
+            return 'detached';
+        return 'unknown';
+    }
+    /** One answer to one prober; never claims the display, never throws. */
+    async answerQuery(socket) {
+        const verdict = await this.attachmentVerdict();
+        try {
+            socket.write(encodeQueryReply(verdict));
+        }
+        catch {
+            // The prober gave up on its own deadline; nothing left to answer to.
+        }
+    }
+    /**
+     * Ask the claimed relay to round-trip its terminal, with a deadline.
+     *
+     * Sharing one in-flight round trip matters: a second question while the first
+     * is unanswered would be settled by the first reply, and two windows asking at
+     * once is a normal resume, not an error.
+     */
+    async probeTerminal() {
+        if (this.probeInFlight !== undefined)
+            return await this.probeInFlight;
+        const socket = this.socket;
+        if (socket === undefined)
+            return 'unknown';
+        const pending = new Promise(resolve => {
+            // Referenced on purpose: the timer *completes* the round trip, and an
+            // unref'd one would let the loop drain with the caller still waiting.
+            const timer = setTimeout(() => {
+                this.probeSettle = undefined;
+                resolve('unknown');
+            }, this.options.probeTimeoutMs ?? DISPLAY_PROBE_TIMEOUT_MS);
+            this.probeSettle = verdict => {
+                clearTimeout(timer);
+                this.probeSettle = undefined;
+                resolve(verdict);
+            };
+        });
+        this.probeInFlight = pending;
+        try {
+            socket.write(encodeProbe());
+        }
+        catch {
+            this.settleProbe('unknown');
+        }
+        try {
+            return await pending;
+        }
+        finally {
+            this.probeInFlight = undefined;
+        }
+    }
+    settleProbe(verdict) {
+        const settle = this.probeSettle;
+        this.probeSettle = undefined;
+        settle?.(verdict);
+    }
     sendStdout(bytes) {
         const socket = this.socket;
         if (socket === undefined || this.attached !== true)
@@ -506,6 +743,65 @@ function isPidAlive(pid) {
 export async function displaySockExists(path, timeoutMs = 250) {
     return await probeDisplaySock(path, timeoutMs);
 }
+/**
+ * How long a prober waits for the Host's answer to {@link FRAME_QUERY}.
+ *
+ * It has to cover the relay's own two probe windows (see
+ * {@link DISPLAY_PROBE_TIMEOUT_MS}) plus the hop; the answer only takes this
+ * long when the display really is silent.
+ */
+export const DISPLAY_QUERY_TIMEOUT_MS = 4_000;
+/**
+ * Ask a live Host whether a window is really on its session.
+ *
+ * `undefined` means the Host did not answer — an older Host that does not know
+ * the frame, or one whose event loop is stuck. Every caller must read that as
+ * "cannot tell" and never as "free": the cost of the doubt is one confirmation
+ * prompt, and the cost of guessing wrong is taking a session away from a window
+ * somebody is still typing in.
+ */
+export async function queryDisplayAttachment(path, timeoutMs = DISPLAY_QUERY_TIMEOUT_MS) {
+    return await new Promise(resolve => {
+        const socket = createConnection(path);
+        const reader = new FrameReader();
+        let settled = false;
+        const finish = (verdict) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(verdict);
+        };
+        const timer = setTimeout(() => finish(undefined), timeoutMs);
+        socket.once('connect', () => {
+            try {
+                socket.write(encodeQuery());
+            }
+            catch {
+                finish(undefined);
+            }
+        });
+        socket.on('data', chunk => {
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch {
+                finish(undefined);
+                return;
+            }
+            for (const frame of frames) {
+                if (frame.type === FRAME_QUERY_REPLY) {
+                    finish(decodeQueryReply(frame.payload));
+                    return;
+                }
+            }
+        });
+        socket.once('error', () => finish(undefined));
+        socket.once('close', () => finish(undefined));
+    });
+}
 function watchHostExit(child) {
     let settle = () => { };
     const exited = new Promise(resolve => { settle = resolve; });
@@ -521,6 +817,52 @@ function watchHostExit(child) {
         },
     };
 }
+/**
+ * Watch a Host this process did not spawn itself.
+ *
+ * The hidden-console bootstrap (see `hostBootstrapCommand`) starts the Host
+ * through PowerShell, so there is no `ChildProcess` handle to listen on — the
+ * only handle on the Host is the pid it printed. Polling that pid is enough for
+ * what the watch is for: a Host that dies before its display socket appears
+ * should be reported at once instead of after the whole boot timeout. The code
+ * is unknown here (null), and the poll interval is the detection delay; the
+ * watch is disposed as soon as the channel is up, so it never runs for the life
+ * of the session.
+ *
+ * The poll timer is deliberately **not** unref'd. `exited` is a promise this
+ * watch is the only thing that can resolve, and an unref'd timer does not keep
+ * the event loop alive: a caller that awaits nothing else — a test, or a
+ * launcher whose only remaining work is the boot — let the loop drain first and
+ * never saw the answer (node:test reports that as "Promise resolution is still
+ * pending but the event loop has already resolved", which is how this was
+ * found). Every caller disposes the watch once the channel is up, and
+ * `waitForDisplaySock` disposes it in its `finally`, so holding the loop for the
+ * boot window is the point rather than a leak.
+ */
+const HOST_PID_POLL_MS = 250;
+/** Exported for the test that pins its loop-ref behaviour; not public API. */
+export function watchHostPid(pid) {
+    let settle = () => { };
+    const exited = new Promise(resolve => { settle = resolve; });
+    let timer;
+    const tick = () => {
+        if (!isPidAlive(pid)) {
+            timer = undefined;
+            settle(null);
+            return;
+        }
+        timer = setTimeout(tick, HOST_PID_POLL_MS);
+    };
+    tick();
+    return {
+        exited,
+        dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}
 /**
  * How long a dead-pid report waits for the child's `exit` event before giving
  * up on its code. The event is normally delivered within a tick; the bound only
@@ -717,32 +1059,75 @@ export function restoreTerminalInput(stdin = process.stdin) {
     }
 }
 /**
- * How to start the background Host so it outlives this process *and* does not
- * make its own children flash console windows on Windows.
- *
- * POSIX wants `detached: true` (setsid) so the Host survives the launcher and a
- * hung-up terminal.
+ * Start the Host through the hidden-console bootstrap and return its pid, or
+ * `undefined` when the bootstrap could not report one.
  *
- * Windows is the opposite: `detached: true` maps to DETACHED_PROCESS, which
- * gives the Host **no console at all**, and Windows ignores CREATE_NO_WINDOW
- * (what `windowsHide` sets) when DETACHED_PROCESS is present. Every console
- * child the Host then starts — each tool call, every shell, node, git — has to
- * allocate its own console, which is a visible window flashing over the TUI.
- * Dropping `detached` there lets `windowsHide` do its job: the Host gets its
- * own invisible console, and descendants inherit it instead of creating one.
- * The Host still outlives the launcher: Windows does not kill children with
- * their parent, and its console is its own, so closing the user's terminal does
- * not reach it either.
+ * `spawnSync` on purpose. The pid has to be in hand before this function
+ * returns (the caller watches it, and the fallback must never leave two Hosts
+ * for one session), and the cost is one bounded wait while the boot splash is
+ * already on screen. PowerShell exits as soon as `Start-Process` has created the
+ * Host, so the wait is its own start-up, not the Host's.
  *
- * Pure and platform-parameterised so the Windows branch can be asserted from
- * Linux (see docs/platform.md).
+ * Falling back is safe exactly when nothing was printed: `Start-Process -PassThru`
+ * either starts the Host and prints its id, or throws before starting anything
+ * (`$ErrorActionPreference = 'Stop'`). A *timeout* is the one case where a Host
+ * might exist and the pid was lost, so it does not fall back — it reports.
  */
-export function hostSpawnOptions(platform = process.platform) {
-    const windows = platform === 'win32';
-    return { detached: !windows, windowsHide: true };
+export function spawnHostThroughBootstrap(bootstrap, options) {
+    // A pid file left by an earlier boot would be read as this one's answer.
+    try {
+        rmSync(options.pidFile, { force: true });
+    }
+    catch { /* best effort */ }
+    const result = spawnSync(bootstrap.command, bootstrap.args, {
+        env: options.env,
+        ...hostSpawnOptions(options.platform),
+        // No pipes at all. `Start-Process` may hand this script's stdio to the Host,
+        // and a live reader of that pipe would wait for the Host to exit instead of
+        // for the bootstrap: measured here as a 15 s stall before the pid was read.
+        // The pid travels through a file, and the Host's own stderr is redirected by
+        // the script itself.
+        stdio: ['ignore', 'ignore', 'ignore'],
+        timeout: options.timeoutMs,
+    });
+    let written = '';
+    try {
+        written = readFileSync(options.pidFile, 'utf8').trim();
+    }
+    catch {
+        // No file: nothing was started (or the script failed before writing it).
+    }
+    try {
+        rmSync(options.pidFile, { force: true });
+    }
+    catch { /* best effort */ }
+    const match = /^(\d+)$/u.exec(written);
+    if (match !== null) {
+        const pid = Number(match[1]);
+        // Checked before the timeout: a bootstrap that wrote the pid and then hung
+        // still started exactly one Host, and that pid is the answer.
+        if (Number.isInteger(pid) && pid > 0)
+            return { pid };
+    }
+    const timedOut = result.error?.code === 'ETIMEDOUT';
+    if (timedOut || result.signal !== null) {
+        throw new Error(`dsh-ssh-tui: the hidden-console bootstrap did not report a host pid in ${options.timeoutMs}ms;`
+            + ' refusing to start a second host for this session');
+    }
+    return undefined;
 }
-/** Spawn a detached Host copy of this `dsh` invocation and return its sock path. */
-export function spawnDetachedHost(sessionId, platform = process.platform) {
+/**
+ * Spawn a detached Host copy of this `dsh` invocation and return its sock path.
+ *
+ * On Windows the Host goes through {@link hostBootstrapCommand} when the OS
+ * PowerShell is available: a direct spawn there cannot both survive the
+ * launcher (libuv's `KILL_ON_JOB_CLOSE` job takes a non-detached child with it)
+ * and avoid flashing console windows (`detached` is DETACHED_PROCESS, which makes
+ * Windows ignore `CREATE_NO_WINDOW`). The bootstrap gives the Host a console of
+ * its own, hidden — see `docs/platform.md`. Without it, the direct spawn below
+ * is still what runs, with the old semantics.
+ */
+export function spawnDetachedHost(sessionId, platform = process.platform, options = {}) {
     const sock = sessionSockPath(sessionId);
     // On Windows the channel is a pipe name, which is not a file path: the log
     // must live in the state directory next to the locks instead.
@@ -750,17 +1135,63 @@ export function spawnDetachedHost(sessionId, platform = process.platform) {
     let errFd;
     try {
         mkdirSync(dirname(errFile), { recursive: true, mode: 0o700 });
+        // The Host's stderr can quote a provider error; the directory and the log
+        // both get the intent applied, since `mode` is POSIX-only.
+        restrictPathToUserSync(dirname(errFile), { mode: 0o700, directory: true });
         errFd = openSync(errFile, 'w');
+        restrictPathToUserSync(errFile, { mode: 0o600 });
     }
     catch {
         errFd = undefined;
     }
-    const child = spawn(process.execPath, hostArgvForSession(sessionId), {
-        // DSH_HOME is pinned to the resolved absolute path: the Host chdirs into
-        // the 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.
-        env: { ...process.env, [TUI_HOST_ENV]: '1', DSH_HOME: resolveDshHome() },
+    // DSH_HOME is pinned to the resolved absolute path: the Host chdirs into the
+    // 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 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
+    // spawn is the honest fallback there.
+    const pidFile = sessionBootstrapPidPath(sessionId);
+    const bootstrap = options.bootstrap === null
+        ? undefined
+        : options.bootstrap ?? (errFd === undefined ? undefined : hostBootstrapCommand({
+            platform,
+            execPath: process.execPath,
+            argv,
+            stderrFile: errFile,
+            pidFile,
+        }));
+    let started;
+    if (bootstrap !== undefined) {
+        started = spawnHostThroughBootstrap(bootstrap, {
+            // The marker rides the bootstrap's environment, which `Start-Process`
+            // passes on to the Host.
+            env: bootstrapEnv(env),
+            platform,
+            timeoutMs: options.bootstrapTimeoutMs ?? HOST_BOOTSTRAP_TIMEOUT_MS,
+            pidFile,
+        });
+        if (started !== undefined) {
+            // The bootstrap redirects the Host's stderr to this path itself, so this
+            // process must not keep a descriptor on it.
+            if (errFd !== undefined) {
+                try {
+                    closeSync(errFd);
+                }
+                catch { /* ignore */ }
+            }
+            return {
+                pid: started.pid,
+                sock,
+                exitWatch: watchHostPid(started.pid),
+                ...errFd === undefined ? {} : { errFile },
+            };
+        }
+    }
+    const child = spawn(process.execPath, argv, {
+        env,
         ...hostSpawnOptions(platform),
         stdio: ['ignore', 'ignore', errFd ?? 'ignore'],
     });
@@ -808,13 +1239,21 @@ export async function runDisplayRelay(path, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdout = options.stdout ?? process.stdout;
     const signals = options.signals ?? process;
-    const useAltScreen = process.env.DSH_TUI_NO_ALT_SCREEN !== '1'
-        && process.env.DSH_TUI_NO_ALT_SCREEN !== 'true';
+    // The relay and the Host must agree on the screen: both ask the capability
+    // table, so a console without an alternate screen never gets half of one.
+    const useAltScreen = terminalCapabilities().alternateScreen;
     return await new Promise((resolve, reject) => {
         const socket = createConnection(path);
         const reader = new FrameReader();
         let settled = false;
         let live = false;
+        /** Whether this terminal has ever answered a cursor probe. */
+        let terminalAnswered = false;
+        let probeInFlight = false;
+        /** The value the Host already has, so only real changes are reported. */
+        let reportedRtt;
+        let recheckMisses = 0;
+        let rttTimer;
         // Set when the Host tells us a newer Display took this session over. The
         // terminal restore below is the one write that must NOT happen then: this
         // relay no longer owns any screen, and if the link is dead (window killed,
@@ -845,6 +1284,9 @@ export async function runDisplayRelay(path, options = {}) {
             reject(error);
         };
         const cleanup = () => {
+            if (rttTimer !== undefined)
+                clearTimeout(rttTimer);
+            rttTimer = undefined;
             pump.stop();
             stdout.removeListener('resize', onResize);
             stdin.removeListener('end', onLocalHangup);
@@ -863,7 +1305,7 @@ export async function runDisplayRelay(path, options = {}) {
                 resizeTimer = undefined;
             }
             stdout.off('resize', onResize);
-            if (process.platform !== 'win32') {
+            if (usesSigwinch()) {
                 signals.off('SIGWINCH', onResize);
             }
             try {
@@ -881,7 +1323,10 @@ export async function runDisplayRelay(path, options = {}) {
                 try {
                     stdout.write('\x1b]0;\x07');
                     stdout.write('\x1b[0m\x1b[2J\x1b[3J\x1b[H');
-                    stdout.write(`\x1b[?1000l\x1b[?1002l\x1b[?1006l\x1b[?2004l\x1b[?25h${useAltScreen ? '\x1b[?1049l' : ''}`);
+                    // Leaving is always safe (an unused mode is ignored) and skipping it
+                    // is not: this relay may be the only one that gets to restore a screen
+                    // the Host entered under a different classification.
+                    stdout.write(`\x1b[?1000l\x1b[?1002l\x1b[?1006l\x1b[?2004l\x1b[?25h\x1b[?1049l`);
                 }
                 catch {
                     // TTY may already be gone
@@ -941,6 +1386,80 @@ export async function runDisplayRelay(path, options = {}) {
                 sendResize();
             }, 20);
         };
+        /**
+         * Keep the Host's picture of the link current.
+         *
+         * The chip and the paint cadence (and the byte budget per frame) all come
+         * from this number, and a link measured once at attach is a link measured at
+         * its worst moment forever. The probe is a cursor round trip on a quiet
+         * line: it costs one write and one reply, and the pump routes anything the
+         * user typed meanwhile to the Host as usual.
+         */
+        const recheckRtt = async () => {
+            const measured = await pump.measure();
+            if (settled)
+                return;
+            if (measured === undefined) {
+                recheckMisses += 1;
+                // A terminal that never answers DSR (a pipe, a dumb terminal) must not
+                // be probed every twenty seconds for the rest of the session; one that
+                // answers sometimes — a flapping link — keeps the normal cadence.
+                scheduleRttRecheck(recheckMisses >= RTT_RECHECK_MAX_MISSES ? RTT_RECHECK_BACKOFF_MS : (options.rttRecheckMs ?? RTT_RECHECK_MS));
+                return;
+            }
+            recheckMisses = 0;
+            const moved = reportedRtt !== undefined && Math.abs(measured - reportedRtt) >= RTT_MOVED_MS;
+            reportedRtt = measured;
+            // Reported every time, even when it did not move: the Host takes the
+            // median of the last few measurements, and a value sent once can never
+            // outvote the stale one it replaced. An unchanged frame costs the screen
+            // nothing (the painter is incremental), so the repetition is free.
+            try {
+                socket.write(encodeRtt(measured));
+            }
+            catch {
+                // The socket is gone; the close handler settles the relay.
+            }
+            scheduleRttRecheck(moved
+                ? RTT_RECHECK_CONFIRM_MS
+                : (options.rttRecheckMs ?? RTT_RECHECK_MS));
+        };
+        const scheduleRttRecheck = (delayMs) => {
+            if (settled)
+                return;
+            rttTimer = setTimeout(() => {
+                rttTimer = undefined;
+                void recheckRtt();
+            }, delayMs);
+            rttTimer.unref?.();
+        };
+        /**
+         * The Host asking whether this display still has a terminal.
+         *
+         * The answer has to come from a real round trip. A cut SSH link leaves this
+         * relay connected and its event loop healthy — the launcher sees no hangup
+         * until sshd does, which can be hours — so anything cheaper (a ping its own
+         * loop answers) would keep reporting a window nobody can see any more.
+         */
+        const answerProbe = async () => {
+            if (probeInFlight)
+                return;
+            probeInFlight = true;
+            try {
+                // A slow link gets the widened window before its silence is believed:
+                // "silent" is what lets a resume take the session over, and a live
+                // window must never be misread into it.
+                const alive = await pump.measureOnce() || await pump.measureOnce(RTT_SLOW_SAMPLE_TIMEOUT_MS);
+                terminalAnswered ||= alive;
+                socket.write(encodeProbeReply(alive ? 'live' : terminalAnswered ? 'silent' : 'unknown'));
+            }
+            catch {
+                // The socket is gone; the close handler settles the relay.
+            }
+            finally {
+                probeInFlight = false;
+            }
+        };
         const onLocalHangup = () => {
             finish('signal');
         };
@@ -977,6 +1496,11 @@ export async function runDisplayRelay(path, options = {}) {
                     const rtt = await pump.measure();
                     if (settled)
                         return;
+                    // The baseline a liveness check is compared against: a terminal that
+                    // answered once and is silent later is gone, one that never answered
+                    // tells us nothing (see `TerminalVerdict`).
+                    terminalAnswered = rtt !== undefined;
+                    reportedRtt = rtt;
                     const columns = stdout.columns || 80;
                     const rows = stdout.rows || 24;
                     socket.write(Buffer.concat([
@@ -985,6 +1509,7 @@ export async function runDisplayRelay(path, options = {}) {
                         encodeRtt(rtt),
                     ]));
                     live = true;
+                    scheduleRttRecheck(options.rttFirstRecheckMs ?? RTT_RECHECK_FIRST_MS);
                     if (options.announce === true) {
                         try {
                             stdout.write('\r\x1b[2K');
@@ -1004,7 +1529,7 @@ export async function runDisplayRelay(path, options = {}) {
                     }
                     pendingBytes = 0;
                     stdout.on('resize', onResize);
-                    if (process.platform !== 'win32') {
+                    if (usesSigwinch()) {
                         signals.on('SIGWINCH', onResize);
                     }
                 }
@@ -1044,6 +1569,9 @@ export async function runDisplayRelay(path, options = {}) {
                     finish('replaced');
                     return;
                 }
+                else if (frame.type === FRAME_PROBE) {
+                    void answerProbe();
+                }
             }
         });
         socket.on('close', () => finish('host-closed'));