@linxiraos/pi-tui 1.1.7 → 1.1.8

package/src/terminal.ts

@@ -5,6 +5,7 @@ import {
 	$env,
 	isBunTestRuntime,
 	isTerminalHeadless,
+	isWsl,
 	logger,
 	postmortem,
 	restoreTerminalStderr,
@@ -142,62 +143,109 @@ export function chunkForConPTY(data: string, maxChunkBytes: number = MAX_CONPTY_
 }
 
 /**
- * Hard cap on bytes queued to a stalled stdout before its consumer is declared
- * gone. A live terminal drains within milliseconds, so a backlog this large —
- * far above any legitimate paint (a full session resume is a few MiB) — means
- * the PTY reader has stopped consuming entirely. Without the cap, `#safeWrite`
- * keeps handing cosmetic frames (the `hub wait` spinner, 500 ms progress
- * snapshots) to a writable buffer that never drains, growing RSS without bound
- * until the host runs out of memory. See #6854.
+ * Backlog ceiling that arms the stall watchdog. A live terminal keeps this
+ * near zero; crossing it means either a genuinely wedged PTY reader (#6854) or
+ * a single legitimately-huge frame — a `--resume` transcript repaint of many
+ * inline images is one multi-tens-of-MiB write (#10430). The two are told
+ * apart by {@link StdoutStallWatchdog} (drain progress), not by this number
+ * alone: inter-frame production is already gated at 256 KiB
+ * (`TUI.#deferRenderForOutputBacklog`), so the only way to reach this cap is a
+ * lone oversized frame or a reader that has stopped consuming entirely.
  */
 const MAX_STDOUT_BACKLOG_BYTES = 64 * 1024 * 1024;
 
 /**
- * Turns an unbounded, never-draining stdout writable buffer into a bounded
- * disconnect signal.
+ * Backlog at or below which stdout is healthy again: the pump has kept up, the
+ * TUI resumes composing frames, and a {@link StdoutStallWatchdog} episode ends.
+ * The TUI render gate (`TUI.#MAX_PENDING_OUTPUT_BYTES`) is this same value, so
+ * the watchdog stays armed across the entire range where frames are deferred —
+ * otherwise a consumer that wedges between this level and the arm cap is never
+ * re-sampled and the session freezes instead of disconnecting (#10434 review).
+ */
+export const STDOUT_BACKLOG_CLEAR_BYTES = 256 * 1024;
+
+/**
+ * How long an armed backlog may go without any drain progress before the
+ * consumer is declared gone. A slow-but-alive terminal keeps reaching new
+ * low-water marks (so it never trips); a wedged one that flushes nothing is
+ * torn down within this window.
+ */
+const STDOUT_STALL_TIMEOUT_MS = 2_000;
+
+/** Cadence at which {@link ProcessTerminal} re-samples the backlog while an episode is armed. */
+const STDOUT_STALL_POLL_MS = 250;
+
+/**
+ * Bounds a never-draining stdout backlog without killing a single large but
+ * actively-draining frame.
  *
  * `process.stdout.write()` returns `false` once its buffer exceeds the stream
- * high-water mark; the bytes stay queued and are only freed when the consumer
- * drains (the `drain` event). While the consumer keeps up, writes are accepted
- * and nothing accumulates. When it stalls, every subsequent write piles onto
- * the buffer — a stalled-but-alive PTY reader never throws, so the write path
- * has no other signal that output is going nowhere. This guard sums the bytes
- * queued since backpressure began and reports when that backlog crosses the
- * cap, at which point the caller treats the terminal as disconnected.
+ * high-water mark, and the off-thread pump's `pending()` climbs the same way;
+ * a stalled-but-alive PTY reader never throws, so the byte count is the only
+ * signal that output is going nowhere. Tripping on the instantaneous count
+ * alone is wrong: a legitimate oversized frame (a resume repaint of dozens of
+ * inline screenshots, #10430) briefly exceeds the cap and then drains.
+ *
+ * An episode starts when the backlog first exceeds `armBytes` and lasts until
+ * it drains back to `clearBytes` (healthy). The backlog can fall below
+ * `armBytes` while still unhealthy, so the episode must outlive that dip
+ * (#10434): during it the watchdog declares the terminal disconnected only when
+ * the backlog makes no drain progress (no new low-water mark) for `stallMs` —
+ * a draining terminal keeps lowering the mark and never trips, while a wedged
+ * one (#6854) still tears down within the window.
  *
  * Exported for unit testing; `ProcessTerminal` is the sole production user.
  */
-export class OutputBacklogGuard {
-	#bytes = 0;
-	#tracking = false;
-
-	constructor(private readonly capBytes: number = MAX_STDOUT_BACKLOG_BYTES) {}
-
-	/** True once a refused write started a backlog that has not yet drained. */
-	get tracking(): boolean {
-		return this.#tracking;
+export class StdoutStallWatchdog {
+	#lowWater = Number.POSITIVE_INFINITY;
+	#stalledSinceMs = 0;
+	#armed = false;
+
+	constructor(
+		private readonly armBytes: number = MAX_STDOUT_BACKLOG_BYTES,
+		private readonly clearBytes: number = STDOUT_BACKLOG_CLEAR_BYTES,
+		private readonly stallMs: number = STDOUT_STALL_TIMEOUT_MS,
+	) {}
+
+	/** True while an episode is active and the backlog must be polled to completion. */
+	get armed(): boolean {
+		return this.#armed;
 	}
 
 	/**
-	 * Record one `stdout.write()`: `accepted` is that call's return value and
-	 * `bytes` its encoded size. Returns true when the pending backlog now
-	 * exceeds the cap and the terminal should be treated as disconnected.
+	 * Feed the current pending-byte count and clock reading. Returns true once an
+	 * armed episode has gone `stallMs` with no drain progress, at which point the
+	 * caller treats the terminal as disconnected.
 	 */
-	record(accepted: boolean, bytes: number): boolean {
-		if (!this.#tracking) {
-			// Consumer is keeping up; nothing is queued.
-			if (accepted) return false;
-			// First refused write: backpressure has begun.
-			this.#tracking = true;
+	sample(pending: number, nowMs: number): boolean {
+		if (!this.#armed) {
+			// Idle: only an oversized backlog starts an episode.
+			if (pending <= this.armBytes) return false;
+			this.#armed = true;
+			this.#lowWater = pending;
+			this.#stalledSinceMs = nowMs;
+			return false;
+		}
+		if (pending <= this.clearBytes) {
+			// Drained back to a healthy level: the episode is over.
+			this.reset();
+			return false;
 		}
-		this.#bytes += bytes;
-		return this.#bytes > this.capBytes;
+		if (pending < this.#lowWater) {
+			// Drain progress: a new low-water mark restarts the stall clock.
+			this.#lowWater = pending;
+			this.#stalledSinceMs = nowMs;
+			return false;
+		}
+		// Still unhealthy with no new low-water mark since the clock started.
+		return nowMs - this.#stalledSinceMs >= this.stallMs;
 	}
 
-	/** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+	/** Episode ended (drained) or terminal torn down: stop watching. */
 	reset(): void {
-		this.#bytes = 0;
-		this.#tracking = false;
+		this.#armed = false;
+		this.#lowWater = Number.POSITIVE_INFINITY;
+		this.#stalledSinceMs = 0;
 	}
 }
 
@@ -406,6 +454,13 @@ export interface TerminalStartOptions {
 }
 /** Identity of an accepted explicit terminal appearance refresh request. */
 export type TerminalAppearanceRequestToken = number;
+/**
+ * Fired once per DEC private mode when DECRQM support resolves.
+ * `confirmed` is false when only the DA1 sentinel arrived.
+ * `status` is the DECRPM value (0 unrecognized, 1/2 set/reset, 3 permanently
+ * set, 4 permanently reset) when the terminal answered DECRQM.
+ */
+export type PrivateModeReportHandler = (mode: number, supported: boolean, confirmed?: boolean, status?: number) => void;
 export interface Terminal {
 	// Start the terminal with input, resize, and host-disconnect handlers.
 	start(
@@ -529,8 +584,9 @@ export interface Terminal {
 	 * status resolves. `confirmed` is false when the terminal answered the DA1
 	 * sentinel without answering DECRQM, which proves only that querying support
 	 * is unavailable — not that the private mode itself is unsupported.
+	 * `status` is the DECRPM value when the terminal answered DECRQM.
 	 */
-	onPrivateModeReport?(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+	onPrivateModeReport?(callback: PrivateModeReportHandler): void;
 }
 
 /**
@@ -542,9 +598,9 @@ export interface Terminal {
  * single predicate.
  */
 export function isConPTYHosted(): boolean {
-	if (process.platform === "win32") return true;
-	// WSL: stdout still crosses into ConPTY at the `wslhost` boundary.
-	return process.platform === "linux" && (!!$env.WSL_DISTRO_NAME || !!$env.WSL_INTEROP);
+	// win32 always hosts through ConPTY; under WSL stdout still crosses into
+	// ConPTY at the `wslhost` boundary.
+	return process.platform === "win32" || isWsl(process.platform, $env);
 }
 
 /** Discriminated owner of an outstanding DA1 sentinel in the unified probe FIFO. */
@@ -640,22 +696,19 @@ export class ProcessTerminal implements Terminal {
 	#stdoutErrorHandler = (err: Error) => {
 		this.#markTerminalDisconnected("stdout failed", err);
 	};
-	// Bounds the stdout writable buffer against a stalled PTY consumer: a
-	// stalled-but-alive reader never throws, so #safeWrite has no error to catch
-	// and the writable buffer grows without bound as cosmetic frames pile up.
-	// See OutputBacklogGuard and #6854.
-	#stdoutBacklog = new OutputBacklogGuard();
+	// Bounds the stdout backlog against a stalled PTY consumer without killing a
+	// single large-but-draining frame: a stalled-but-alive reader never throws,
+	// so the pending byte count is the only stall signal, and a legitimate
+	// oversized frame (a resume repaint of many inline images) must be allowed
+	// to drain. See StdoutStallWatchdog, #6854, and #10430.
+	#stdoutStall = new StdoutStallWatchdog();
+	#stdoutStallTimer?: Timer;
 	// Off-thread output pump (unix TTYs): Bun's `process.stdout.write` blocks
 	// the event loop until the terminal drains, so a slow/occluded emulator
 	// froze the whole TUI for the duration of a multi-MB repaint. The pump
 	// enqueues frames and performs the blocking write(2) on its own thread;
 	// `pendingOutputBytes` exposes the backlog for render-side frame skipping.
 	#outputPump?: TtyWriter;
-	#stdoutDrainArmed = false;
-	#stdoutDrainHandler = () => {
-		this.#stdoutDrainArmed = false;
-		this.#stdoutBacklog.reset();
-	};
 
 	#windowsVTInputRestore?: () => void;
 	#xtermScrollToBottomRestoreModes = new Set<number>();
@@ -679,7 +732,7 @@ export class ProcessTerminal implements Terminal {
 	#da1SentinelOwners: Da1SentinelOwner[] = [];
 	/** Resolved DECRQM support per private mode (mode → supported). */
 	#privateModeSupport = new Map<number, boolean>();
-	#privateModeCallbacks: Array<(mode: number, supported: boolean, confirmed: boolean) => void> = [];
+	#privateModeCallbacks: PrivateModeReportHandler[] = [];
 	/** Whether DEC 2048 in-band resize notifications are currently enabled. */
 	#inBandResizeActive = false;
 	/** Reassembly buffer for a DEC 2048 in-band resize report split across stdin reads. */
@@ -770,7 +823,7 @@ export class ProcessTerminal implements Terminal {
 		return token;
 	}
 
-	onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void {
+	onPrivateModeReport(callback: PrivateModeReportHandler): void {
 		this.#privateModeCallbacks.push(callback);
 	}
 
@@ -1306,10 +1359,13 @@ export class ProcessTerminal implements Terminal {
 			}
 		});
 
-		// Re-wrap paste content with bracketed paste markers for existing editor handling
-		this.#stdinBuffer.on("paste", (content: string) => {
+		// Re-wrap paste content with bracketed paste markers for existing editor
+		// handling. An Enter that shared the paste's stdin read rides along so
+		// paste and submit reach the component focused right now, not one the
+		// paste itself is about to open.
+		this.#stdinBuffer.on("paste", (content: string, enter?: string) => {
 			if (this.#inputHandler) {
-				this.#inputHandler(`\x1b[200~${content}\x1b[201~`);
+				this.#inputHandler(`\x1b[200~${content}\x1b[201~${enter ?? ""}`);
 			}
 		});
 
@@ -1430,6 +1486,7 @@ export class ProcessTerminal implements Terminal {
 		const mode: TerminalAppearance = luminance < 0.5 ? "dark" : "light";
 		const changed = mode !== this.#appearance;
 		this.#appearance = mode;
+		//DISABLED(biome-unknown-rule) lint/complexity/noUselessSpread: callbacks may unsubscribe while reporting
 		for (const cb of [...this.#appearanceReportCallbacks]) {
 			try {
 				cb(mode, requestToken);
@@ -1491,7 +1548,7 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	#handlePrivateModeReport(mode: number, status: string): void {
-		this.#resolvePrivateMode(mode, isPrivateModeSupported(status), true);
+		this.#resolvePrivateMode(mode, isPrivateModeSupported(status), true, Number.parseInt(status, 10));
 		if (isXtermScrollToBottomMode(mode) && isPrivateModeSet(status)) {
 			this.#disableXtermScrollToBottomMode(mode);
 		}
@@ -1503,12 +1560,12 @@ export class ProcessTerminal implements Terminal {
 	 * unsupported response from an absent response followed by the DA1 sentinel.
 	 * Enables DEC 2048 in-band resize only after positive confirmation.
 	 */
-	#resolvePrivateMode(mode: number, supported: boolean, confirmed: boolean): void {
+	#resolvePrivateMode(mode: number, supported: boolean, confirmed: boolean, status?: number): void {
 		if (this.#privateModeSupport.has(mode)) return;
 		this.#privateModeSupport.set(mode, supported);
 		for (const cb of this.#privateModeCallbacks) {
 			try {
-				cb(mode, supported, confirmed);
+				cb(mode, supported, confirmed, status);
 			} catch {
 				// Ignore subscriber errors — capability reporting must not crash input.
 			}
@@ -1759,11 +1816,7 @@ export class ProcessTerminal implements Terminal {
 			process.stdout.removeListener("resize", this.#stdoutResizeListener);
 			this.#stdoutResizeListener = undefined;
 		}
-		if (this.#stdoutDrainArmed) {
-			process.stdout.removeListener("drain", this.#stdoutDrainHandler);
-			this.#stdoutDrainArmed = false;
-		}
-		this.#stdoutBacklog.reset();
+		this.#disarmStdoutStallWatchdog();
 		this.#resizeHandler = undefined;
 		// Flush the restore sequences enqueued above (bounded — a stalled PTY
 		// must not wedge exit), then retire the pump. Later writes (emergency
@@ -1802,6 +1855,7 @@ export class ProcessTerminal implements Terminal {
 	#markTerminalDisconnected(reason: string, err?: unknown): void {
 		if (this.#dead) return;
 		this.#dead = true;
+		this.#disarmStdoutStallWatchdog();
 		logger.warn("terminal disconnected; stopping interactive rendering", { reason, err });
 
 		const disconnectHandler = this.#disconnectHandler;
@@ -1854,11 +1908,11 @@ export class ProcessTerminal implements Terminal {
 				return;
 			}
 			try {
-				// Same stalled-consumer bound as the stream path (#6854): a PTY reader
-				// that never drains must tear the terminal down, not grow the queue.
-				if (pump.write(data) > MAX_STDOUT_BACKLOG_BYTES) {
-					this.#markTerminalDisconnected("stdout backlog exceeded cap; PTY consumer stalled");
-				}
+				// Feed the live backlog to the stall watchdog rather than tripping on
+				// the instantaneous byte count: a single large-but-draining frame (a
+				// resume repaint of many inline images) must open normally, while a
+				// never-draining reader is still torn down (#6854, #10430).
+				this.#trackStdoutBacklog(pump.write(data));
 			} catch (err) {
 				this.#markTerminalDisconnected("stdout failed", err);
 			}
@@ -1882,26 +1936,19 @@ export class ProcessTerminal implements Terminal {
 			// and a code-unit cap would let CJK transcript rows expand past the
 			// threshold. See #2034 and #2095.
 			const bytes = Buffer.byteLength(data, "utf8");
-			let accepted: boolean;
 			if (this.#conpty && bytes > MAX_CONPTY_WRITE_CHUNK_BYTES) {
-				accepted = true;
 				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK_BYTES)) {
 					if (this.#dead) break;
-					accepted = process.stdout.write(chunk);
+					process.stdout.write(chunk);
 				}
 			} else {
-				accepted = process.stdout.write(data);
-			}
-			// A stalled-but-alive PTY consumer never throws: write() just returns
-			// false and queues the bytes. Bound that never-draining backlog by
-			// declaring the terminal disconnected once it crosses the cap — the
-			// same clean-exit path a dead terminal takes (#6854).
-			if (this.#stdoutBacklog.record(accepted, bytes)) {
-				this.#markTerminalDisconnected("stdout backlog exceeded cap; PTY consumer stalled");
-			} else if (this.#stdoutBacklog.tracking && !this.#stdoutDrainArmed) {
-				this.#stdoutDrainArmed = true;
-				process.stdout.once("drain", this.#stdoutDrainHandler);
+				process.stdout.write(data);
 			}
+			// A stalled-but-alive PTY consumer never throws: write() just queues the
+			// bytes and writableLength grows. Feed that backlog to the stall watchdog
+			// so a genuinely wedged reader is bounded (#6854) without killing a lone
+			// oversized frame that is still draining (#10430).
+			this.#trackStdoutBacklog(process.stdout.writableLength ?? 0);
 		} catch (err) {
 			this.#markTerminalDisconnected("stdout failed", err);
 		}
@@ -1917,6 +1964,47 @@ export class ProcessTerminal implements Terminal {
 		return process.stdout.writableLength ?? 0;
 	}
 
+	/**
+	 * Reconcile the stdout backlog after a write or a poll. The watchdog runs an
+	 * episode from the moment the backlog crosses the arm cap until it drains to
+	 * a healthy level; while an episode is armed we keep a poll running because,
+	 * once the render gate (256 KiB) defers frames, no write is guaranteed to
+	 * re-sample the backlog — so a consumer that wedges anywhere above the
+	 * healthy threshold, even after the backlog dips below the arm cap, is still
+	 * caught. See {@link StdoutStallWatchdog}, #6854, #10430, and #10434.
+	 */
+	#trackStdoutBacklog(pending: number): void {
+		if (this.#stdoutStall.sample(pending, Date.now())) {
+			this.#disarmStdoutStallWatchdog();
+			this.#markTerminalDisconnected("stdout backlog stalled without draining; PTY consumer stalled");
+			return;
+		}
+		if (!this.#stdoutStall.armed) {
+			this.#disarmStdoutStallWatchdog();
+			return;
+		}
+		if (!this.#stdoutStallTimer) {
+			this.#stdoutStallTimer = setInterval(() => this.#pollStdoutStall(), STDOUT_STALL_POLL_MS);
+			this.#stdoutStallTimer.unref?.();
+		}
+	}
+
+	#pollStdoutStall(): void {
+		if (this.#dead) {
+			this.#disarmStdoutStallWatchdog();
+			return;
+		}
+		this.#trackStdoutBacklog(this.pendingOutputBytes);
+	}
+
+	#disarmStdoutStallWatchdog(): void {
+		this.#stdoutStall.reset();
+		if (this.#stdoutStallTimer) {
+			clearInterval(this.#stdoutStallTimer);
+			this.#stdoutStallTimer = undefined;
+		}
+	}
+
 	get rows(): number {
 		if (this.#inBandResizeActive && this.#reportedRows) return this.#reportedRows;
 		return process.stdout.rows || Number(Bun.env.LINES) || 24;