@oh-my-pi/pi-tui 15.9.3 → 15.9.5

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [15.9.5] - 2026-06-05
+
+### Changed
+
+- Changed terminal resize handling so any width or height change always performs a clean reset + redraw: the renderer now unconditionally clears the viewport and native scrollback (`CSI 2 J` / `CSI 3 J`) and replays the full transcript at the new geometry, replacing the previous matrix of conditional viewport-repaint / history-rebuild / deferred-mutation branches. Multiplexer panes still repaint the visible window in place (pane scrollback cannot be erased), but a resize during active ED3-risk foreground streaming now performs the same clean rebuild rather than downgrading to a non-destructive viewport repaint: the terminal already re-wrapped its saved lines at the old width, so the rebuild must erase them (ED 3) instead of leaving the mis-wrapped history on screen. As a deliberate tradeoff this drops the prior no-overflow and confirmed-scrolled guards on resize: a reader scrolled into history snaps back to the bottom and preexisting shell scrollback above the UI is cleared.
+
+### Fixed
+
+- Fixed ED3-risk foreground streaming dropping the scrolled-off head of an append-only live block that alone overflows the viewport (a long streamed assistant reply). The live-region pin again committed native scrollback only up to the live-region start, so once the live block grew past the viewport its earlier rows scrolled above the viewport top but were committed nowhere and repainted nowhere — they vanished, leaving the reply looking like a ~viewport-tall circular buffer. The `NativeScrollbackLiveRegion` seam now also reports an optional append-only `getNativeScrollbackCommitSafeEnd`, and the pinned commit boundary is the deeper of the sealed start and that append-only end: rows in `[liveRegionStart, commitSafeEnd)` above the viewport top commit to scrollback, while volatile live blocks (tool previews that collapse) omit the boundary and keep their mutable rows deferred — preserving the pending-box-above-running-box fix.
+
+## [15.9.4] - 2026-06-05
+### Added
+
+- Added `PI_TUI_SYNC_OUTPUT=0` and `PI_TUI_SYNC_OUTPUT=1` to explicitly disable or force-enable DEC 2026 synchronized-output mode, alongside `PI_FORCE_SYNC_OUTPUT=1` as a force-on alias
+- Added `PI_TUI_ED3_SAFE=1` environment override to treat a terminal as non-ED3-risk for eager native scrollback rebuilds on unknown POSIX hosts
+
+### Changed
+
+- Changed native-scrollback safety defaults to treat unknown POSIX, SSH, and multiplexer-shaped terminals as ED3-risk for passive rendering; checkpoint replay now requires a positive at-tail viewport proof instead of assuming prompt submit makes host scrollback safe.
+- Changed synchronized-output defaults to a conservative opt-in profile: DEC 2026 paint wrappers stay disabled for remote/multiplexer/VTE/unknown terminals unless explicitly forced, while the autowrap guards remain active.
+
+### Fixed
+
+- Fixed ED3-risk unknown-viewport renders repainting offscreen structural edits over stale native scrollback, which could duplicate or shift rows when async blocks collapsed or middle rows were deleted.
+- Fixed ED3-risk foreground streams committing mutable live-region rows into native scrollback, which could leave a stale `pending` tool box above the `running` box after the preview re-rendered.
+- Fixed TUI shutdown leaving paint-time terminal state and Kitty image data behind by restoring synchronized-output/autowrap modes and purging all transmitted Kitty image ids on stop.
+- Fixed stdin buffering splitting surrogate-pair text into UTF-16 halves and reduced timing sensitivity for incomplete escape sequences.
+- Fixed terminal content not reflowing after a resize on terminals using DEC 2048 in-band resize (kitty/Ghostty/iTerm2/WezTerm). `ProcessTerminal.columns`/`rows` returned the last cached in-band report even after the OS already knew the new size, so a SIGWINCH whose in-band report was dropped or malformed (split past the stdin flush window, `:`-subparameter fields) re-rendered the whole transcript at the stale width. OS resize events now reconcile cached in-band geometry against the live `process.stdout` dimensions, dropping a stale cached value so the next render uses the true size; a valid in-band report still re-seeds pixel sizing.
+
 ## [15.9.3] - 2026-06-05
 
 ### Fixed
@@ -1043,4 +1072,4 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ### Fixed
 
-- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))
+- **Readline-style Ctrl+W**: Now skips trailing whitespace before deleting the preceding word, matching standard readline behavior. ([#306](https://github.com/badlogic/pi-mono/pull/306) by [@kim0](https://github.com/kim0))

package/dist/types/components/image.d.ts

@@ -64,6 +64,8 @@ export declare class ImageBudget {
     endPass(): boolean;
     /** Image ids to delete from the terminal this frame; clears the pending set. */
     takePurgeIds(): readonly number[];
+    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    takeAllTransmittedIds(): readonly number[];
     /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
     shouldTransmit(imageId: number): boolean;
     /**

package/dist/types/stdin-buffer.d.ts

@@ -19,8 +19,8 @@
 import { EventEmitter } from "events";
 export type StdinBufferOptions = {
     /**
-     * Maximum time to wait for sequence completion (default: 10ms)
-     * After this time, the buffer is flushed even if incomplete
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
      */
     timeout?: number;
 };

package/dist/types/terminal-capabilities.d.ts

@@ -36,28 +36,23 @@ export declare function isNotificationSuppressed(): boolean;
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
- * Whether eager live-frame native scrollback rebuilds are unsafe when the
- * terminal viewport position is unobservable.
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * viewport position is unobservable.
  *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
- * terminals below, ED3 can disturb a reader parked in native scrollback during
- * streaming: kitty/ghostty/alacritty/VTE clamp the scroll offset back to the
- * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
- * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
- * invalidates a reader's scrollback position during live streaming.
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
  *
- * Windows Terminal erases its host scrollback on ED3 and repositions the
- * viewport against the shortened buffer, so a scrolled-up reader is yanked.
- * Native win32 is excluded here because the renderer guards it with dedicated
- * platform checks (the viewport position is never observable on Windows — see
- * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
- * platform means the outer host is Windows Terminal fronting a WSL distro (WT
- * propagates the variable into the Linux environment), where the same ED3
- * yank applies. See #1610.
- *
- * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, terminalId?: TerminalId): boolean;
 /**
  * Whether the terminal applies Kitty-style DECCARA rectangular SGR changes
  * (`CSI Pt ; Pl ; Pb ; Pr ; <sgr> $ r`) extended to background color, so large

package/dist/types/tui.d.ts

@@ -48,9 +48,21 @@ export interface Component {
  * line index where that suffix begins after each render. TUI treats that suffix
  * — and every root child rendered below it — as not yet safe to commit to native
  * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ *
+ * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
+ * inside that live suffix: the line index up to which the live region is
+ * append-only (its earlier rows never re-layout, only new rows append at the
+ * bottom — a streaming assistant message). Rows in `[liveRegionStart,
+ * commitSafeEnd)` that scroll above the viewport are safe to commit to native
+ * scrollback even though they are technically live, because they will never
+ * change. Without this, a single live block that alone overflows the viewport
+ * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
+ * live blocks (tool previews that collapse) omit it, so their mutable rows stay
+ * deferred. Defaults to `liveRegionStart` when absent.
  */
 export interface NativeScrollbackLiveRegion {
     getNativeScrollbackLiveRegionStart(): number | undefined;
+    getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
 /**
  * Interface for components that can receive focus and display a cursor.
@@ -86,9 +98,8 @@ export interface RenderRequestOptions {
      */
     allowUnknownViewportMutation?: boolean;
 }
-/** Options for deferred native scrollback rebuild checkpoints. */
+/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
 export interface NativeScrollbackRefreshOptions {
-    /** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
     allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
@@ -204,8 +215,8 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     /**
      * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-     * paints. Starts from `PI_NO_SYNC_OUTPUT` and is force-disabled at runtime if
-     * the terminal reports mode 2026 unsupported via DECRQM.
+     * paints. Starts from conservative terminal/env detection and is force-disabled
+     * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
      */
     get synchronizedOutput(): boolean;
     /**
@@ -252,6 +263,6 @@ export declare class TUI extends Container {
      * Callers should only invoke this at checkpoints where the user is expected to be
      * at the terminal bottom, such as after submitting a new prompt.
      */
-    refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean;
+    refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean;
     requestRender(force?: boolean, options?: RenderRequestOptions): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.9.3",
+	"version": "15.9.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.9.3",
-		"@oh-my-pi/pi-utils": "15.9.3",
+		"@oh-my-pi/pi-natives": "15.9.5",
+		"@oh-my-pi/pi-utils": "15.9.5",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},

package/src/components/image.ts

@@ -163,6 +163,16 @@ export class ImageBudget {
 		return ids;
 	}
 
+	/** All image ids believed to be loaded in the terminal store; clears tracking. */
+	takeAllTransmittedIds(): readonly number[] {
+		if (this.#transmitted.size === 0) return EMPTY_IDS;
+		const ids = [...this.#transmitted];
+		this.#transmitted.clear();
+		this.#purgeIds = [];
+		this.#pendingTransmits = [];
+		return ids;
+	}
+
 	/** Whether `imageId`'s data still needs to be transmitted to the terminal. */
 	shouldTransmit(imageId: number): boolean {
 		return !this.#transmitted.has(imageId);

package/src/stdin-buffer.ts

@@ -233,9 +233,10 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 				return { sequences, remainder: remaining };
 			}
 		} else {
-			// Not an escape sequence - take a single character
-			sequences.push(remaining[0]!);
-			pos++;
+			// Not an escape sequence - take one Unicode scalar, not a UTF-16 code unit.
+			const char = Array.from(remaining)[0] ?? "";
+			sequences.push(char);
+			pos += char.length;
 		}
 	}
 
@@ -244,8 +245,8 @@ function extractCompleteSequences(buffer: string): { sequences: string[]; remain
 
 export type StdinBufferOptions = {
 	/**
-	 * Maximum time to wait for sequence completion (default: 10ms)
-	 * After this time, the buffer is flushed even if incomplete
+	 * Maximum time to wait for sequence completion (default: 75ms).
+	 * After this time, a genuinely incomplete escape is flushed.
 	 */
 	timeout?: number;
 };
@@ -269,7 +270,7 @@ export class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
 
 	constructor(options: StdinBufferOptions = {}) {
 		super();
-		this.#timeoutMs = options.timeout ?? 10;
+		this.#timeoutMs = options.timeout ?? 75;
 	}
 
 	process(data: string | Buffer): void {

package/src/terminal-capabilities.ts

@@ -118,33 +118,44 @@ export function isWindowsTerminalPreviewSixelSupported(
 }
 
 /**
- * Whether eager live-frame native scrollback rebuilds are unsafe when the
- * terminal viewport position is unobservable.
+ * Whether live-frame native scrollback rebuilds are unsafe when the terminal
+ * viewport position is unobservable.
  *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). On the
- * terminals below, ED3 can disturb a reader parked in native scrollback during
- * streaming: kitty/ghostty/alacritty/VTE clamp the scroll offset back to the
- * active tail when saved lines are erased. WezTerm, macOS Terminal.app, and
- * iTerm2 expose scrollback-only clears via ED3/terminfo E3; that still
- * invalidates a reader's scrollback position during live streaming.
+ * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
+ * terminals either clamp a scrolled reader back to the active tail or erase host
+ * scrollback when ED3 lands. The important property is not the brand name — it
+ * is that an unknown viewport position cannot be proven safe. Environment
+ * markers are therefore only used to prove *risk* or a strongly-known profile;
+ * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
  *
- * Windows Terminal erases its host scrollback on ED3 and repositions the
- * viewport against the shortened buffer, so a scrolled-up reader is yanked.
- * Native win32 is excluded here because the renderer guards it with dedicated
- * platform checks (the viewport position is never observable on Windows — see
- * `Terminal.isNativeViewportAtBottom`); a `WT_SESSION` sighting on any other
- * platform means the outer host is Windows Terminal fronting a WSL distro (WT
- * propagates the variable into the Linux environment), where the same ED3
- * yank applies. See #1610.
- *
- * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
+ * Native win32 is excluded here because the renderer has dedicated ConPTY
+ * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
+ * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
  */
 export function detectTerminalEagerEraseScrollbackRisk(
 	env: NodeJS.ProcessEnv = Bun.env,
 	platform: NodeJS.Platform = process.platform,
 ): boolean {
 	if (platform === "win32") return false;
+
+	const term = env.TERM?.toLowerCase() ?? "";
+	const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+	const colorTerm = env.COLORTERM?.toLowerCase() ?? "";
+
+	if (env.PI_TUI_ED3_SAFE === "1") return false;
 	if (env.WT_SESSION) return true;
+	if (
+		env.SSH_CONNECTION ||
+		env.SSH_CLIENT ||
+		env.SSH_TTY ||
+		env.TMUX ||
+		env.STY ||
+		env.ZELLIJ ||
+		term.startsWith("tmux") ||
+		term.startsWith("screen")
+	) {
+		return true;
+	}
 	if (
 		env.WEZTERM_PANE ||
 		env.KITTY_WINDOW_ID ||
@@ -155,17 +166,62 @@ export function detectTerminalEagerEraseScrollbackRisk(
 	) {
 		return true;
 	}
-	switch (env.TERM_PROGRAM?.toLowerCase()) {
+	switch (termProgram) {
 		case "alacritty":
 		case "apple_terminal":
 		case "ghostty":
+		case "gnome-terminal":
 		case "iterm.app":
+		case "kgx":
 		case "kitty":
+		case "ptyxis":
 		case "wezterm":
+		case "xfce4-terminal":
 			return true;
 		default:
+			break;
+	}
+	if (platform === "linux" && (colorTerm === "truecolor" || colorTerm === "24bit")) return true;
+	// Unknown POSIX terminals have no scroll-position oracle. Treat them as risky
+	// for passive ED3 until a positive terminal-specific integration proves safe.
+	return true;
+}
+
+/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
+export function shouldEnableSynchronizedOutputByDefault(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+	terminalId: TerminalId = TERMINAL_ID,
+): boolean {
+	if (env.PI_NO_SYNC_OUTPUT || env.PI_TUI_SYNC_OUTPUT === "0") return false;
+	if (env.PI_FORCE_SYNC_OUTPUT === "1" || env.PI_TUI_SYNC_OUTPUT === "1") return true;
+	if (platform === "win32") return false;
+
+	const term = env.TERM?.toLowerCase() ?? "";
+	const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+	if (
+		env.SSH_CONNECTION ||
+		env.SSH_CLIENT ||
+		env.SSH_TTY ||
+		env.TMUX ||
+		env.STY ||
+		env.ZELLIJ ||
+		term.startsWith("tmux") ||
+		term.startsWith("screen")
+	) {
+		return false;
+	}
+	if (env.VTE_VERSION) return false;
+	switch (termProgram) {
+		case "gnome-terminal":
+		case "kgx":
+		case "ptyxis":
+		case "xfce4-terminal":
 			return false;
+		default:
+			break;
 	}
+	return terminalId === "kitty" || terminalId === "ghostty" || terminalId === "wezterm" || terminalId === "iterm2";
 }
 
 /**

package/src/terminal.ts

@@ -35,7 +35,9 @@ export function emergencyTerminalRestore(): void {
 			// Blind restore only if we know a terminal was started but lost track of it
 			// This avoids writing escape sequences for non-TUI commands (grep, commit, etc.)
 			process.stdout.write(
-				"\x1b[?2004l" + // Disable bracketed paste
+				"\x1b[?2026l" + // End synchronized output
+					"\x1b[?7h" + // Restore autowrap
+					"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[?2048l" + // Disable in-band resize notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
@@ -173,6 +175,7 @@ export class ProcessTerminal implements Terminal {
 	#wasRaw = false;
 	#inputHandler?: (data: string) => void;
 	#resizeHandler?: () => void;
+	#stdoutResizeListener?: () => void;
 	#kittyProtocolActive = false;
 	#modifyOtherKeysActive = false;
 	#modifyOtherKeysTimeout?: Timer;
@@ -239,8 +242,14 @@ export class ProcessTerminal implements Terminal {
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
 		this.#safeWrite("\x1b[?2004h");
 
-		// Set up resize handler immediately
-		process.stdout.on("resize", this.#resizeHandler);
+		// Set up resize handler immediately. The OS refreshes process.stdout
+		// dimensions before firing `resize`, so it is authoritative for geometry:
+		// reconcile any stale cached DEC 2048 report before notifying the renderer.
+		this.#stdoutResizeListener = () => {
+			this.#reconcileInBandGeometryOnResize();
+			this.#resizeHandler?.();
+		};
+		process.stdout.on("resize", this.#stdoutResizeListener);
 
 		// Refresh terminal dimensions - they may be stale after suspend/resume
 		// (SIGWINCH is lost while process is stopped). Unix only.
@@ -845,6 +854,31 @@ export class ProcessTerminal implements Terminal {
 		}
 	}
 
+	/**
+	 * Reconcile cached in-band geometry with the OS on an OS-level resize.
+	 *
+	 * SIGWINCH (POSIX) and ConPTY (Windows) refresh `process.stdout.columns`/
+	 * `rows` before the `resize` event fires, so they are authoritative for the
+	 * new cell geometry. A cached DEC 2048 report can be stale: the matching
+	 * post-resize report may be dropped (split across stdin reads past the flush
+	 * window) or carry `:`-subparameters the parser skips, leaving the getters
+	 * pinned to the old size — which freezes the rendered width because the
+	 * renderer reflows against {@link columns}/{@link rows}, not the live OS
+	 * value. Drop a cached dimension that disagrees with the live OS value; the
+	 * terminal's next valid in-band report re-seeds pixel sizing.
+	 */
+	#reconcileInBandGeometryOnResize(): void {
+		if (!this.#inBandResizeActive) return;
+		const osColumns = process.stdout.columns;
+		const osRows = process.stdout.rows;
+		if (this.#reportedColumns !== undefined && osColumns > 0 && this.#reportedColumns !== osColumns) {
+			this.#reportedColumns = undefined;
+		}
+		if (this.#reportedRows !== undefined && osRows > 0 && this.#reportedRows !== osRows) {
+			this.#reportedRows = undefined;
+		}
+	}
+
 	async drainInput(maxMs = 1000, idleMs = 50): Promise<void> {
 		if (this.#kittyProtocolActive) {
 			// Disable Kitty keyboard protocol first so any late key releases
@@ -897,6 +931,10 @@ export class ProcessTerminal implements Terminal {
 			this.#safeWrite(TERMINAL_PROGRESS_CLEAR_SEQUENCE);
 		}
 
+		// Leave paint-time terminal modes even if the process exits between the
+		// begin/end halves of a frame. Safe no-ops on terminals that ignored them.
+		this.#safeWrite("\x1b[?2026l\x1b[?7h");
+
 		// Disable bracketed paste mode
 		this.#safeWrite("\x1b[?2004l");
 
@@ -958,10 +996,11 @@ export class ProcessTerminal implements Terminal {
 		}
 		this.#inputHandler = undefined;
 		this.#appearance = undefined;
-		if (this.#resizeHandler) {
-			process.stdout.removeListener("resize", this.#resizeHandler);
-			this.#resizeHandler = undefined;
+		if (this.#stdoutResizeListener) {
+			process.stdout.removeListener("resize", this.#stdoutResizeListener);
+			this.#stdoutResizeListener = undefined;
 		}
+		this.#resizeHandler = undefined;
 
 		// Pause stdin to prevent any buffered input (e.g., Ctrl+D) from being
 		// re-interpreted after raw mode is disabled. This fixes a race condition

package/src/tui.ts

@@ -14,6 +14,7 @@ import {
 	ImageProtocol,
 	setCellDimensions,
 	setTerminalImageProtocol,
+	shouldEnableSynchronizedOutputByDefault,
 	TERMINAL,
 } from "./terminal-capabilities";
 import {
@@ -123,15 +124,31 @@ export interface Component {
  * line index where that suffix begins after each render. TUI treats that suffix
  * — and every root child rendered below it — as not yet safe to commit to native
  * scrollback on ED3-risk terminals whose viewport position is unobservable.
+ *
+ * `getNativeScrollbackCommitSafeEnd` optionally reports a *deeper* boundary
+ * inside that live suffix: the line index up to which the live region is
+ * append-only (its earlier rows never re-layout, only new rows append at the
+ * bottom — a streaming assistant message). Rows in `[liveRegionStart,
+ * commitSafeEnd)` that scroll above the viewport are safe to commit to native
+ * scrollback even though they are technically live, because they will never
+ * change. Without this, a single live block that alone overflows the viewport
+ * loses its scrolled-off head (committed nowhere, repainted nowhere). Volatile
+ * live blocks (tool previews that collapse) omit it, so their mutable rows stay
+ * deferred. Defaults to `liveRegionStart` when absent.
  */
 export interface NativeScrollbackLiveRegion {
 	getNativeScrollbackLiveRegionStart(): number | undefined;
+	getNativeScrollbackCommitSafeEnd?(): number | undefined;
 }
 
 function getNativeScrollbackLiveRegionStart(component: Component): number | undefined {
 	return (component as Component & Partial<NativeScrollbackLiveRegion>).getNativeScrollbackLiveRegionStart?.();
 }
 
+function getNativeScrollbackCommitSafeEnd(component: Component): number | undefined {
+	return (component as Component & Partial<NativeScrollbackLiveRegion>).getNativeScrollbackCommitSafeEnd?.();
+}
+
 /**
  * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
@@ -168,9 +185,8 @@ export interface RenderRequestOptions {
 	allowUnknownViewportMutation?: boolean;
 }
 
-/** Options for deferred native scrollback rebuild checkpoints. */
+/** Options for deferred native scrollback rebuild checkpoints. Reserved for API stability. */
 export interface NativeScrollbackRefreshOptions {
-	/** Allow replay when the terminal cannot report viewport state. Use only for explicit user submit checkpoints. */
 	allowUnknownViewport?: boolean;
 }
 /** Type guard to check if a component implements Focusable */
@@ -387,7 +403,7 @@ export class TUI extends Container {
 	#sixelProbeUnsubscribe?: () => void;
 	#showHardwareCursor = $flag("PI_HARDWARE_CURSOR");
 	#clearOnShrink = $flag("PI_CLEAR_ON_SHRINK"); // Clear empty rows when content shrinks (default: off)
-	#synchronizedOutputEnabled = !$flag("PI_NO_SYNC_OUTPUT");
+	#synchronizedOutputEnabled = shouldEnableSynchronizedOutputByDefault();
 	#paintBeginSequence = this.#synchronizedOutputEnabled ? PAINT_BEGIN : PAINT_BEGIN_NO_SYNC;
 	#paintEndSequence = this.#synchronizedOutputEnabled ? PAINT_END : PAINT_END_NO_SYNC;
 	#cursorBeginSequence = this.#synchronizedOutputEnabled ? CURSOR_BEGIN : CURSOR_BEGIN_NO_SYNC;
@@ -403,6 +419,7 @@ export class TUI extends Container {
 	// not scroll replayed live chrome (status/editor) into fresh history.
 	#suppressNextSuffixScroll = false;
 	#nativeScrollbackLiveRegionStart: number | undefined;
+	#nativeScrollbackCommitSafeEnd: number | undefined;
 	#nativeScrollbackDirty = false;
 	// Highest `#maxLinesRendered` reached during a foreground tool turn while
 	// intermediate frames were prevented from committing to terminal scrollback.
@@ -456,6 +473,7 @@ export class TUI extends Container {
 	override render(width: number): string[] {
 		width = Math.max(1, width);
 		this.#nativeScrollbackLiveRegionStart = undefined;
+		this.#nativeScrollbackCommitSafeEnd = undefined;
 		const lines: string[] = [];
 		for (const child of this.children) {
 			const offset = lines.length;
@@ -466,6 +484,13 @@ export class TUI extends Container {
 					? Math.max(0, Math.min(childLines.length, Math.trunc(liveRegionStart)))
 					: childLines.length;
 				this.#nativeScrollbackLiveRegionStart = offset + boundedStart;
+				const commitSafeEnd = getNativeScrollbackCommitSafeEnd(child);
+				if (commitSafeEnd !== undefined) {
+					const boundedEnd = Number.isFinite(commitSafeEnd)
+						? Math.max(boundedStart, Math.min(childLines.length, Math.trunc(commitSafeEnd)))
+						: childLines.length;
+					this.#nativeScrollbackCommitSafeEnd = offset + boundedEnd;
+				}
 			}
 			lines.push(...childLines);
 		}
@@ -525,8 +550,8 @@ export class TUI extends Container {
 
 	/**
 	 * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-	 * paints. Starts from `PI_NO_SYNC_OUTPUT` and is force-disabled at runtime if
-	 * the terminal reports mode 2026 unsupported via DECRQM.
+	 * paints. Starts from conservative terminal/env detection and is force-disabled
+	 * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
 	 */
 	get synchronizedOutput(): boolean {
 		return this.#synchronizedOutputEnabled;
@@ -874,6 +899,11 @@ export class TUI extends Container {
 	}
 
 	stop(): void {
+		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+			for (const id of this.#imageBudget.takeAllTransmittedIds()) {
+				this.terminal.write(encodeKittyDeleteImage(id));
+			}
+		}
 		this.#clearSixelProbeState();
 		this.#stopped = true;
 		if (this.#renderTimer) {
@@ -908,7 +938,7 @@ export class TUI extends Container {
 	 * Callers should only invoke this at checkpoints where the user is expected to be
 	 * at the terminal bottom, such as after submitting a new prompt.
 	 */
-	refreshNativeScrollbackIfDirty(options?: NativeScrollbackRefreshOptions): boolean {
+	refreshNativeScrollbackIfDirty(_options?: NativeScrollbackRefreshOptions): boolean {
 		if (!this.#nativeScrollbackDirty || this.#stopped) return false;
 		// Multiplexer panes preserve their own history and never receive a
 		// destructive clear, so a checkpoint "replay" cannot reconcile anything —
@@ -918,18 +948,11 @@ export class TUI extends Container {
 			this.#clearNativeScrollbackDirty();
 			return false;
 		}
-		let nativeViewportAtBottom = this.#readNativeViewportAtBottom();
-		const allowUnknownViewport = options?.allowUnknownViewport === true;
-		if (nativeViewportAtBottom === false && allowUnknownViewport) {
-			const retriedViewportAtBottom = this.#readNativeViewportAtBottom();
-			if (this.#canReplayNativeScrollbackAtCheckpoint(retriedViewportAtBottom, allowUnknownViewport)) {
-				nativeViewportAtBottom = retriedViewportAtBottom;
-			}
-		}
-		if (!this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom, allowUnknownViewport)) {
+		const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
+		if (!this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom)) {
 			return false;
 		}
-		this.#prepareForcedRender(true, allowUnknownViewport);
+		this.#prepareForcedRender(true, false);
 		this.#renderRequested = false;
 		this.#lastRenderAt = this.#renderScheduler.now();
 		this.#doRender();
@@ -957,7 +980,7 @@ export class TUI extends Container {
 		this.#renderScheduler.scheduleImmediate(() => this.#scheduleRender());
 	}
 
-	#prepareForcedRender(clearScrollback: boolean, allowUnknownViewportMutation: boolean): void {
+	#prepareForcedRender(clearScrollback: boolean, _allowUnknownViewportMutation: boolean): void {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
 			(this.#previousHeight > 0 && this.#previousHeight !== this.terminal.rows);
@@ -967,7 +990,7 @@ export class TUI extends Container {
 		const replayGeometry =
 			geometryChanged &&
 			!isMultiplexerSession() &&
-			this.#canReplayNativeScrollbackAtCheckpoint(this.#readNativeViewportAtBottom(), allowUnknownViewportMutation);
+			this.#canReplayNativeScrollbackAtCheckpoint(this.#readNativeViewportAtBottom());
 		this.#clearScrollbackOnNextRender ||= clearScrollback || replayGeometry;
 		this.#forceViewportRepaintOnNextRender = true;
 		if (this.#renderTimer) {
@@ -1457,6 +1480,7 @@ export class TUI extends Container {
 			overlayVisibilityReduced,
 			allowUnknownViewportMutation,
 			this.#nativeScrollbackLiveRegionStart,
+			this.#nativeScrollbackCommitSafeEnd,
 		);
 		// 3b. Defer scrollback commits during foreground streaming, but only on
 		// ED3-risk terminals whose committed scrollback cannot be rewritten without
@@ -1476,8 +1500,18 @@ export class TUI extends Container {
 		if (streamingWasActive && eagerEraseScrollbackRisk) {
 			const streamingActive =
 				this.#eagerNativeScrollbackRebuild && !this.#eagerNativeScrollbackRebuildDisablePending;
+			// A terminal resize reflowed native scrollback at the OLD geometry, so the
+			// saved rows are already mis-wrapped garbage. The planned historyRebuild
+			// must stand and erase them (ED 3) — capping to a viewport repaint would
+			// leave the corrupt history on screen. Like the other reconciles, a resize
+			// is an explicit user action that snaps the host to the bottom, so there is
+			// no scrolled reader to yank.
+			const geometryChanged = widthChanged || heightChanged;
 			const explicitReconcile =
-				explicitViewportMutation || this.#clearScrollbackOnNextRender || overlayVisibilityReduced;
+				explicitViewportMutation ||
+				this.#clearScrollbackOnNextRender ||
+				overlayVisibilityReduced ||
+				geometryChanged;
 			// The defer below exists only to avoid `\r\n`-scrolling transient frames
 			// past a reader parked in native scrollback. When the terminal can report
 			// that the viewport is at the tail, there is no scrolled reader to yank,
@@ -1536,10 +1570,31 @@ export class TUI extends Container {
 				this.#previousWidth = width;
 				this.#previousHeight = height;
 				return;
-			case "initial":
-				this.#emitFullPaint(lines, width, height, cursorPos, { clearViewport: true, clearScrollback: false });
+			case "initial": {
+				const liveRegionStart = this.#nativeScrollbackLiveRegionStart;
+				if (
+					this.#eagerNativeScrollbackRebuild &&
+					eagerEraseScrollbackRisk &&
+					!allowUnknownViewportMutation &&
+					liveRegionStart !== undefined &&
+					liveRegionStart < lines.length &&
+					!isMultiplexerSession() &&
+					this.#readNativeViewportAtBottom() === undefined
+				) {
+					this.#emitInitialLiveRegionPinnedPaint(
+						lines,
+						width,
+						height,
+						cursorPos,
+						liveRegionStart,
+						this.#nativeScrollbackCommitSafeEnd,
+					);
+				} else {
+					this.#emitFullPaint(lines, width, height, cursorPos, { clearViewport: true, clearScrollback: false });
+				}
 				this.#hasEverRendered = true;
 				return;
+			}
 			case "sessionReplace":
 				this.#clearScrollbackOnNextRender = false;
 				this.#clearNativeScrollbackDirty();
@@ -1613,11 +1668,11 @@ export class TUI extends Container {
 
 	/**
 	 * Map the current frame onto a single render intent. Order matters: forced
-	 * resets and session replacement short-circuit before any diff work. A real
-	 * resize (geometry change) that invalidates native scrollback rebuilds it now;
-	 * a pure content mutation that does the same marks scrollback dirty and
-	 * repaints only the viewport, deferring the destructive clear+replay to an
-	 * explicit checkpoint so users scrolled into history are not yanked.
+	 * resets and session replacement short-circuit first, then a terminal resize
+	 * (width or height change) always reduces to a clean reset + redraw at the new
+	 * geometry — `historyRebuild` normally, `viewportRepaint` inside a multiplexer
+	 * whose pane scrollback cannot be erased. Pure content mutations fall through
+	 * to the differential machinery below.
 	 */
 	#planRender(
 		newLines: string[],
@@ -1629,6 +1684,7 @@ export class TUI extends Container {
 		overlayVisibilityReduced: boolean,
 		allowUnknownViewportMutation: boolean,
 		liveRegionStart: number | undefined,
+		commitSafeEnd: number | undefined,
 	): RenderIntent {
 		// Initial paint after start(): scrollback must keep its prior shell
 		// content, but the viewport must be cleared so stale rows do not bleed
@@ -1643,6 +1699,25 @@ export class TUI extends Container {
 		if (overlayVisibilityReduced && !isMultiplexerSession()) {
 			return hasVisibleOverlay ? { kind: "overlayRebuild" } : { kind: "historyRebuild" };
 		}
+
+		// A terminal resize (width or height change) reflows the terminal's own
+		// buffer, moving rows between the viewport and native scrollback and
+		// invalidating every cursor/viewport anchor the diff and append emitters
+		// rely on. Always reset cleanly at the new geometry and redraw. Inside a
+		// multiplexer the pane's saved lines cannot be erased (ED 3 is a no-op there
+		// and a full replay only duplicates the transcript), so repaint the visible
+		// window in place; a visible overlay rebuilds with its composite. This
+		// deliberately drops the no-overflow and confirmed-scrolled guards — a
+		// resize is an explicit user action, so a scrolled reader snaps to the
+		// bottom and preexisting shell scrollback above the UI is cleared. The
+		// streaming cap above explicitly exempts geometry changes, so even during
+		// active ED3-risk foreground streaming this rebuild stands and erases the
+		// scrollback the terminal just re-wrapped at the old size.
+		if (widthChanged || heightChanged) {
+			if (isMultiplexerSession()) return { kind: "viewportRepaint" };
+			return hasVisibleOverlay ? { kind: "overlayRebuild" } : { kind: "historyRebuild" };
+		}
+
 		if (hasVisibleOverlay) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 			// Multiplexer panes never get a destructive scrollback clear
@@ -1665,9 +1740,9 @@ export class TUI extends Container {
 			newLines,
 			height,
 			liveRegionStart,
+			commitSafeEnd,
 			eagerEraseScrollbackRisk,
 			allowUnknownViewportMutation,
-			widthChanged || heightChanged,
 		);
 		if (liveRegionPinnedIntent) return liveRegionPinnedIntent;
 
@@ -1712,14 +1787,11 @@ export class TUI extends Container {
 				this.#markNativeScrollbackDirty();
 				return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 			}
-			// A width change rewraps the whole transcript, so committed scrollback is
-			// mis-wrapped at the old width. Yank is acceptable on an explicit resize, so
-			// rebuild even when the viewport position is unknown (POSIX); the
-			// known-scrolled case already deferred above.
-			if (
-				widthChanged ||
-				this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, allowUnknownViewportMutation)
-			) {
+			// A shrink that re-exposes rows already committed to native scrollback
+			// must rebuild so the stale committed copy is cleared. Rebuild only with a
+			// positive at-tail proof; unknown viewports stay dirty because the host
+			// scroll position is not observable and ED3 can yank readers.
+			if (this.#canRebuildNativeScrollbackLive(nativeViewportAtBottom, false)) {
 				return { kind: "historyRebuild" };
 			}
 			// POSIX terminals — and Windows Terminal/ConPTY — that cannot report the
@@ -1744,16 +1816,17 @@ export class TUI extends Container {
 				return this.#eagerNativeScrollbackRebuild ? { kind: "viewportRepaint" } : { kind: "deferredMutation" };
 			}
 
-			// Non-ED3-risk POSIX with an unobservable viewport. If the shrink still
-			// leaves enough rows to cover the previous viewport top, `deferredShrink`
-			// can repaint that stable slice without committing duplicate rows to
-			// native scrollback. When the shrink jumps above that padded viewport
-			// top, `deferredShrink` would draw only blank padding and hide the live
-			// prompt, so rebuild history instead (ED3 is safe on these terminals).
+			// Non-ED3-risk POSIX with an unobservable viewport. `deferredShrink` is
+			// safe only when changed rows are at or below the previous viewport top.
+			// Middle/offscreen deletes renumber rows above the viewport and padding
+			// the old length would repaint shifted rows or blank tail cells.
 			if (newLines.length <= paddedViewportTop) {
 				return { kind: "historyRebuild" };
 			}
 			this.#markNativeScrollbackDirty();
+			if (diff.firstChanged < prevViewportTop) {
+				return { kind: "deferredMutation" };
+			}
 			return { kind: "deferredShrink", paddedLength: this.#previousLines.length };
 		}
 
@@ -1813,8 +1886,6 @@ export class TUI extends Container {
 		this.#suppressNextSuffixScroll = false;
 		if (
 			suppressSuffixScroll &&
-			!widthChanged &&
-			!heightChanged &&
 			diff.appendedLines &&
 			diff.firstChanged < this.#previousLines.length &&
 			!isMultiplexerSession()
@@ -1843,51 +1914,13 @@ export class TUI extends Container {
 		}
 
 		if (diff.firstChanged === -1) {
-			// A geometry change reflows the terminal's own buffer, moving rows between
-			// the viewport and native scrollback. When content overflows and the
-			// viewport position is unobservable (POSIX/ED3-risk/Windows), an in-place
-			// repaint can leave native history out of sync with the transcript, and —
-			// unlike a content-bearing resize, which rebuilds via the geometry branch
-			// below — nothing flags it. Mark scrollback dirty so the next checkpoint
-			// (refreshNativeScrollbackIfDirty) reconciles it; a known-at-bottom reader
-			// rebuilds unconditionally at its checkpoint and needs no flag.
-			if (
-				(widthChanged || heightChanged) &&
-				!isMultiplexerSession() &&
-				newLines.length > height &&
-				this.#readNativeViewportAtBottom() !== true
-			) {
-				this.#markNativeScrollbackDirty();
-			}
-			// Content unchanged. A forced render still needs to refresh the visible
-			// viewport, but it must keep the existing diff basis so later coalesced
-			// content mutations can still update native scrollback correctly.
+			// Content unchanged. A forced render still refreshes the visible viewport
+			// but keeps the existing diff basis so later coalesced content mutations
+			// can still update native scrollback correctly.
 			if (forceViewportRepaint) return { kind: "viewportRepaint" };
-			// Width changes alter wrapping geometry; height changes expose or hide
-			// viewport rows. Repaint any non-multiplexer resize, including Termux
-			// software-keyboard toggles: leaving the new rows blank creates phantom
-			// viewport space that later appends can fill without growing scrollback.
-			if (widthChanged) return { kind: "viewportRepaint" };
-			if (heightChanged && !isMultiplexerSession()) return { kind: "viewportRepaint" };
 			return { kind: "noop" };
 		}
 
-		// Width changes rewrap native history. Any non-append content change must
-		// rebuild the committed transcript when the viewport is safe; a viewport
-		// repaint can leave old-width wrapped fragments above the live frame, and
-		// later appends then splice new rows onto stale history.
-		if (widthChanged) {
-			const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
-			if (!pureAppend) {
-				const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
-				if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
-					this.#markNativeScrollbackDirty();
-					return { kind: "viewportRepaint" };
-				}
-				return isMultiplexerSession() ? { kind: "viewportRepaint" } : { kind: "historyRebuild" };
-			}
-		}
-
 		const contentGrew = newLines.length > this.#previousLines.length;
 		const pureAppend = diff.appendedLines && diff.firstChanged === this.#previousLines.length;
 		const structuralMutation = newLines.length !== this.#previousLines.length || diff.firstChanged < prevViewportTop;
@@ -1909,10 +1942,11 @@ export class TUI extends Container {
 				return { kind: "viewportRepaint" };
 			}
 		}
-		// Geometry changes invalidate the terminal's cursor and viewport anchors;
-		// even if the same coalesced frame also edits offscreen content for a scrolled
-		// reader, the resize-specific branch below must repaint/clamp at the new size.
-		if (!pureAppend && structuralMutation && !heightChanged && !widthChanged && !isMultiplexerSession()) {
+		// A structural mutation (offscreen edit or inserted rows) while bottom-
+		// anchored: when the reader is scrolled, repaint/clamp without trusting the
+		// stale viewport anchors; otherwise rebuild native history when a safe
+		// checkpoint allows.
+		if (!pureAppend && structuralMutation && !isMultiplexerSession()) {
 			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
 			if (this.#nativeViewportIsScrolled(nativeViewportAtBottom, allowUnknownViewportMutation)) {
 				this.#markNativeScrollbackDirty();
@@ -1955,67 +1989,6 @@ export class TUI extends Container {
 			}
 		}
 
-		// Height changes shift the visible window. Repaint when content didn't grow,
-		// but skip inside multiplexers (panes manage their own redraws — handled by
-		// the multiplexer geometry branch below). Termux is deliberately included:
-		// a resize with no content change still exposes or hides viewport rows, and
-		// leaving those rows blank lets later appends fill phantom space instead of
-		// growing native scrollback.
-		if (heightChanged && !contentGrew && !isMultiplexerSession()) {
-			return { kind: "viewportRepaint" };
-		}
-
-		// A height change that also grew the content into a frame that now fits
-		// entirely on screen cannot use the diff or append-tail emitters below:
-		// both position scrolled rows against the previous viewport top and
-		// hardware cursor row, which the reflow just invalidated, so the appended
-		// tail lands `height`-delta rows too low. With no overflow there is no
-		// native scrollback to preserve, so repaint the viewport at the new
-		// geometry. (Height changes with overflow keep the existing deferral.)
-		if (heightChanged && newLines.length <= height && !isMultiplexerSession()) {
-			return { kind: "viewportRepaint" };
-		}
-
-		// Any other geometry change (height shrink with content overflowing the
-		// viewport, or a width change carrying a pure append) must not reach the
-		// anchor-relative diff/append emitters below either. The terminal reflowed
-		// its own buffer on resize — a height shrink moves committed rows between
-		// scrollback and viewport — so the previous frame's viewport-top and
-		// hardware-cursor anchors no longer describe the screen, and scrolling
-		// relative to them splices phantom blank rows into native scrollback
-		// (stress repro: darwin-normal-large seed 0x5eed1234 op 1062, a
-		// resizeHeight coalesced with a streamed append). A resize is an explicit
-		// user action, so rebuilding history at the new geometry is the
-		// established tradeoff (see the width-change branch above); a reader
-		// confirmed scrolled into history is still never yanked. Termux is included
-		// (it is not a multiplexer and ED3 clears its own scrollback): a content-
-		// bearing resize must not reach the stale-anchor emitters below.
-		if ((heightChanged || widthChanged) && !isMultiplexerSession()) {
-			// No overflow → nothing of ours in native scrollback to reconcile; an
-			// in-place repaint also keeps preexisting shell scrollback intact.
-			if (newLines.length <= height) {
-				return { kind: "viewportRepaint" };
-			}
-			const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
-			if (this.#nativeViewportIsKnownScrolled(nativeViewportAtBottom)) {
-				this.#markNativeScrollbackDirty();
-				return { kind: "viewportRepaint" };
-			}
-			return { kind: "historyRebuild" };
-		}
-
-		// The same geometry hazard inside a multiplexer: tmux reflows the pane
-		// grid (visible rows AND pane history) on resize, so the anchor-relative
-		// diff/append emitters below are equally invalid — but a destructive
-		// rebuild is impossible there (pane history cannot be cleared; a full
-		// replay only appends a duplicate transcript copy). Repaint the visible
-		// window in place at the new geometry. Applies even under Termux: a
-		// repaint per keyboard-toggle resize is cheaper than splicing phantom
-		// rows into the pane.
-		if ((heightChanged || widthChanged) && isMultiplexerSession()) {
-			return { kind: "viewportRepaint" };
-		}
-
 		// Configurable shrink-clear: opt-in path that repaints to wipe rows the
 		// diff path would leave behind.
 		if (this.#clearOnShrink && newLines.length < this.#previousLines.length && this.overlayStack.length === 0) {
@@ -2043,6 +2016,14 @@ export class TUI extends Container {
 				return { kind: "historyRebuild" };
 			}
 			this.#markNativeScrollbackDirty();
+			if (
+				nativeViewportAtBottom === undefined &&
+				eagerEraseScrollbackRisk &&
+				!cleanTailAppend &&
+				!this.#eagerNativeScrollbackRebuild
+			) {
+				return { kind: "deferredMutation" };
+			}
 			return { kind: "viewportRepaint", appendFrom: cleanTailAppend ? this.#previousLines.length : undefined };
 		}
 
@@ -2149,15 +2130,8 @@ export class TUI extends Container {
 	#nativeViewportIsKnownScrolled(nativeViewportAtBottom: boolean | undefined): boolean {
 		return nativeViewportAtBottom === false;
 	}
-
-	#canReplayNativeScrollbackAtCheckpoint(
-		nativeViewportAtBottom: boolean | undefined,
-		allowUnknownViewport: boolean,
-	): boolean {
-		return (
-			nativeViewportAtBottom === true ||
-			(nativeViewportAtBottom === undefined && (allowUnknownViewport || process.platform !== "win32"))
-		);
+	#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom: boolean | undefined): boolean {
+		return nativeViewportAtBottom === true;
 	}
 
 	/**
@@ -2167,10 +2141,9 @@ export class TUI extends Container {
 	 * the native viewport) is safe to emit *during ordinary rendering*. POSIX
 	 * terminals cannot report whether the user has scrolled up
 	 * (`isNativeViewportAtBottom()` is `undefined`), so an unknown position is
-	 * treated as unsafe: defer to a non-destructive viewport repaint, mark
-	 * scrollback dirty, and reconcile history at the next explicit checkpoint
-	 * ({@link refreshNativeScrollbackIfDirty} on prompt submit) where the
-	 * editor keystroke has already pinned the terminal to the bottom. Without
+	 * treated as unsafe: defer to a non-destructive viewport repaint and keep
+	 * scrollback dirty until a later render has a positive at-tail proof. A prompt
+	 * submit is no longer treated as proof for unobservable host scrollback.
 	 * this, every offscreen transcript edit while streaming wiped scrollback and
 	 * yanked a scrolled-up reader out of their current context.
 	 * `allowUnknownViewportMutation` (autocomplete/IME) opts directly
@@ -2192,21 +2165,16 @@ export class TUI extends Container {
 		newLines: string[],
 		height: number,
 		liveRegionStart: number | undefined,
+		commitSafeEnd: number | undefined,
 		eagerEraseScrollbackRisk: boolean,
 		allowUnknownViewportMutation: boolean,
-		geometryChanged: boolean,
 	): RenderIntent | undefined {
-		// A width/height change reflows the whole terminal: the relative cursor
-		// positioning this emitter relies on is computed from the pre-resize
-		// geometry and would land on the wrong rows. Defer to the geometry branch
-		// (a full reflow rebuild), which is the established behavior for resizes.
 		if (
 			liveRegionStart === undefined ||
 			liveRegionStart >= newLines.length ||
 			!this.#eagerNativeScrollbackRebuild ||
 			!eagerEraseScrollbackRisk ||
 			allowUnknownViewportMutation ||
-			geometryChanged ||
 			isMultiplexerSession()
 		) {
 			return undefined;
@@ -2216,25 +2184,28 @@ export class TUI extends Container {
 
 		this.#markNativeScrollbackDirty();
 		const naturalViewportTop = Math.max(0, newLines.length - height);
-		// Rows before the live-region boundary are sealed. If a live-region
-		// collapse moves the bottom-anchored viewport back across rows already
-		// written to native scrollback, repainting those sealed rows duplicates
-		// them in history. Clamp only to the committed sealed boundary: mutable
-		// rows inside the live region must remain visible even when an earlier
-		// taller live frame pushed their old contents into native scrollback. The
-		// dirty checkpoint later reconciles those stale mutable saved lines.
-		const committedSealedEnd = Math.min(this.#scrollbackHighWater, liveRegionStart);
-		const renderViewportTop = Math.max(naturalViewportTop, committedSealedEnd);
-		// Every row above the natural viewport top has physically scrolled out of
-		// the live viewport, so the terminal has already pushed it into native
-		// scrollback — there is nowhere else for an off-screen row to live. It must
-		// therefore be committed as real content, *including the head of the live
-		// block itself* when that block alone overflows the viewport (a tall tool
-		// result, a long streamed reply). Only the live tail that remains *within*
-		// the natural viewport stays transient (repainted in place, deferred to the
-		// checkpoint rebuild).
-		const appendTo = naturalViewportTop;
+		// Rows before the live-region boundary are sealed. The commit boundary is
+		// the deeper of the sealed start and the append-only `commitSafeEnd`: a
+		// streaming assistant block reports a `commitSafeEnd` spanning its whole
+		// body, so its head rows that scroll above the viewport commit to native
+		// scrollback instead of vanishing (committed nowhere, repainted nowhere).
+		// A volatile live block (a tool preview that later collapses) omits
+		// `commitSafeEnd`, so the boundary falls back to `liveRegionStart` and its
+		// mutable rows stay deferred — otherwise a pending box that later collapses
+		// to its running/final shape leaves the old top half in scrollback and
+		// repaints the new tail below it, visually splitting one box across the
+		// scrollback seam.
+		const commitBoundary = commitSafeEnd ?? liveRegionStart;
+		const sealedAppendTo = Math.min(naturalViewportTop, commitBoundary);
+		const appendTo = Math.max(0, sealedAppendTo);
 		const appendFrom = Math.min(this.#scrollbackHighWater, appendTo);
+		// If the live-region collapse would re-expose committed rows already written
+		// to native scrollback, clamp the repaint below that committed prefix so
+		// committed rows are not duplicated. Mutable rows beyond the commit boundary
+		// may remain hidden above the viewport until the next checkpoint rebuild;
+		// that is safer than committing transient rows that can later re-layout.
+		const committedSealedEnd = Math.min(this.#scrollbackHighWater, commitBoundary);
+		const renderViewportTop = Math.max(naturalViewportTop, committedSealedEnd);
 		return { kind: "liveRegionPinned", appendFrom, appendTo, renderViewportTop };
 	}
 
@@ -2355,6 +2326,56 @@ export class TUI extends Container {
 		this.#commit(lines, width, height, Math.max(0, this.#maxLinesRendered - height), toRow);
 	}
 
+	/**
+	 * Initial foreground-stream paint on ED3-risk hosts with unknown viewport
+	 * position. Clears only the visible screen, commits the stable prefix, and
+	 * paints the mutable live tail without first writing hidden live rows into
+	 * native scrollback.
+	 */
+	#emitInitialLiveRegionPinnedPaint(
+		lines: string[],
+		width: number,
+		height: number,
+		cursorPos: { row: number; col: number } | null,
+		liveRegionStart: number,
+		commitSafeEnd: number | undefined,
+	): void {
+		this.#fullRedrawCount += 1;
+		this.#markNativeScrollbackDirty();
+		const naturalViewportTop = Math.max(0, lines.length - height);
+		const commitBoundary = commitSafeEnd ?? liveRegionStart;
+		const appendTo = Math.max(0, Math.min(naturalViewportTop, commitBoundary, lines.length));
+		const viewportTop = naturalViewportTop;
+
+		let buffer = this.#paintBeginSequence;
+		if (TERMINAL.supportsScreenToScrollback) buffer += "\x1b[22J";
+		buffer += "\x1b[2J\x1b[H";
+
+		let wroteLine = false;
+		for (let i = 0; i < appendTo; i++) {
+			if (wroteLine) buffer += "\r\n";
+			buffer += this.#fitLineToWidth(lines[i] ?? "", width);
+			wroteLine = true;
+		}
+		for (let screenRow = 0; screenRow < height; screenRow++) {
+			if (wroteLine) buffer += "\r\n";
+			buffer += this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width);
+			wroteLine = true;
+		}
+
+		const viewportBottomRow = viewportTop + height - 1;
+		const contentBottomRow = Math.min(viewportBottomRow, Math.max(viewportTop, lines.length - 1));
+		const parkUp = viewportBottomRow - contentBottomRow;
+		if (parkUp > 0) buffer += `\x1b[${parkUp}A`;
+		const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, contentBottomRow);
+		buffer += seq;
+		buffer += this.#paintEndSequence;
+		this.terminal.write(buffer);
+
+		this.#maxLinesRendered = Math.max(lines.length, viewportTop + height);
+		this.#scrollbackHighWater = appendTo;
+		this.#commit(lines, width, height, viewportTop, toRow);
+	}
 	/**
 	 * Rewrite the visible viewport in place. Cursor home, clear each row,
 	 * emit the bottom-anchored slice of `lines`. No scrollback growth.