@oh-my-pi/pi-tui 18.0.3 → 18.0.5

package/src/terminal-capabilities.ts

@@ -34,6 +34,7 @@ export type TerminalId =
 	| "vscode"
 	| "alacritty"
 	| "warp"
+	| "orca"
 	| "base"
 	| "trueColor";
 
@@ -107,7 +108,7 @@ export class TerminalInfo {
 		/** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
 		public readonly supportsTextSizing: boolean = false,
 		/**
-		 * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty follows
+		 * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty and Orca follow
 		 * UAX#11 (2 cells); Warp paints 1; "platform" keeps the OS default
 		 * (macOS narrow, otherwise UAX#11).
 		 */
@@ -493,6 +494,7 @@ const KNOWN_TERMINALS = Object.freeze({
 	iterm2: new TerminalInfo("iterm2", ImageProtocol.Iterm2, true, true, NotifyProtocol.Osc9),
 	vscode: new TerminalInfo("vscode", null, true, true, NotifyProtocol.Bell),
 	alacritty: new TerminalInfo("alacritty", null, true, true, NotifyProtocol.Bell),
+	orca: new TerminalInfo("orca", null, true, false, NotifyProtocol.Bell, false, false, false, 2),
 	// Warp identifies via TERM_PROGRAM=WarpTerminal and ships the Kitty graphics
 	// protocol on macOS/Linux (direct placement only — no Unicode placeholders, so
 	// detectKittyUnicodePlaceholdersSupport correctly excludes it). It does not
@@ -534,6 +536,7 @@ export function detectTerminalId(env: NodeJS.ProcessEnv = Bun.env): TerminalId {
 		if (caseEq(TERM_PROGRAM, "vscode")) return "vscode";
 		if (caseEq(TERM_PROGRAM, "alacritty")) return "alacritty";
 		if (caseEq(TERM_PROGRAM, "warpterminal")) return "warp";
+		if (caseEq(TERM_PROGRAM, "orca")) return "orca";
 	}
 
 	if (TERM?.toLowerCase().includes("ghostty")) return "ghostty";

package/src/tui.ts

@@ -2,8 +2,8 @@
  * Minimal TUI implementation with explicit history batches.
  *
  * Two output channels: a product-owned {@link TerminalFrameProvider} returns,
- * per frame, an optional immutable {@link HistoryBatch} (finalized transcript
- * rows appended to native history exactly once, gated by a monotonic id and
+ * per frame, an optional immutable {@link HistoryBatch} (finalized or naturally
+ * emitted stable rows, or one complete replay, gated by a monotonic id and
  * acknowledgement) plus the complete mutable viewport. The writer anchors the
  * viewport directly below whatever history remains visible, diffs
  * viewport-only frames, and never infers finality from a row's position.
@@ -109,13 +109,20 @@ export interface ViewportSize {
 	readonly rows: number;
 }
 
-/** Immutable finalized rows offered until the terminal accepts this identifier. */
+/** Immutable append or complete replay offered until the terminal accepts this identifier. */
 export interface HistoryBatch {
 	readonly id: number;
 	readonly rows: readonly string[];
+	/**
+	 * `append` (the default) adds finalized or naturally emitted rows. `replay`
+	 * is the complete logical ledger; the writer bottom-splits it against the
+	 * leading blank viewport and serializes the remainder plus final viewport in
+	 * one synchronous terminal write.
+	 */
+	readonly kind?: "append" | "replay";
 }
 
-/** One history append and the complete mutable viewport for a terminal frame. */
+/** One history append or complete replay plus the mutable viewport for a terminal frame. */
 export interface TerminalFramePlan {
 	readonly history?: HistoryBatch;
 	readonly viewport: readonly string[];
@@ -128,7 +135,9 @@ export interface TerminalFrameProvider {
 	/** Full semantic viewport used only on the transient resize buffer. */
 	renderResizeFrame?(viewport: ViewportSize): readonly string[];
 	/** Re-offer finalized history after a display reset or resize replay. */
-	resetHistory?(): void;
+	beginHistoryReplay?(): void;
+	/** Force every currently eligible finalized prefix to retire before stop. */
+	beginHistoryFlush?(): void;
 }
 
 export interface TUIStartOptions {
@@ -640,9 +649,50 @@ export class TUI extends Container {
 	#parkedViewportOffset = 0;
 	// In-flight post-resize anchor probe: the stale viewport snapshot and park
 	// offset captured when CSI 6n was written, plus the no-reply fallback timer.
-	#resizeProbe: { window: readonly string[]; offset: number; timer: RenderTimer } | undefined;
-	// Unanswered CSI 6n probes; CPR replies are consumed from input while > 0.
-	#pendingCprReplies = 0;
+	#resizeProbe:
+		| {
+				window: readonly string[];
+				offset: number;
+				timer: RenderTimer;
+				epoch: number;
+				retried: boolean;
+		  }
+		| undefined;
+	// Pre-erase viewport snapshot for the settled resize-anchor probe: the erase
+	// in #beginResizeAltPaint empties #providerWindow, so the probe must bound
+	// the anchor with the window that was actually on screen when the resize
+	// began (see #resolveResizeAnchor's `height - staleRows` clamp).
+	#resizeProbeWindow: readonly string[] = [];
+	#resizeProbeOffset = 0;
+	// Direction tracking for the current coalesced resize burst (reset when a
+	// plan frame commits, alongside #previousHeight). A burst containing any
+	// height grow invalidates the multiplexer clip model in
+	// #resolveResizeAnchor: the grow pulls scrollback into the pane and moves
+	// the parked logical row, so the net shrink no longer telescopes from
+	// pre-burst state.
+	#resizeBurstGrew = false;
+	#resizeBurstLastHeight: number | undefined;
+	// Sum of every grow step in the burst: bounds how much scrollback a
+	// multiplexer can have pulled down across the whole burst, including a
+	// shrink-then-regrow that never exceeds the pre-burst height (see the
+	// CPR-timeout fallback in #resolveResizeAnchor).
+	#resizeBurstPull = 0;
+	// Geometry epoch: bumped on every resize transaction entry, so each CSI 6n
+	// request records the geometry it was parked under.
+	#geometryEpoch = 0;
+	// CPR attribution: each request parks a distinct column (CHA) before its
+	// CSI 6n; the terminal processes requests serially, so every reply carries
+	// its own request's column. That makes attribution exact even when replies
+	// are dropped or arbitrarily delayed — anonymous FIFO counting cannot
+	// survive drops (forgetting retired requests eagerly misattributes late
+	// replies, remembering them forever poisons later probes with phantoms,
+	// and age expiry is unsound because replies carry no lifetime guarantee).
+	// A rewrap can only invalidate a reply's row via a width-change SIGWINCH,
+	// which bumps the geometry epoch and discards the reply anyway, so the
+	// scheme is sound on direct terminals too. Tags are never expired; a late
+	// reply to a dead tag is stripped and discarded by column.
+	#cprColumnTags = new Map<number, number>();
+	#cprProbeSeq = 0;
 	// Prepared rows painted by the previous provider frame, for row diffing.
 	#providerWindow: string[] = [];
 	#previousFrameLength = 0;
@@ -1004,7 +1054,7 @@ export class TUI extends Container {
 				if (this.#resizeProbe) {
 					// The anchor being probed is already stale; restart the transaction.
 					this.#cancelResizeProbe();
-					this.#beginResizeAltPaint();
+					this.#beginResizeAltPaint(true);
 					return;
 				}
 				if (this.#renderScheduler.now() < this.#suppressResizeUntil) {
@@ -1032,12 +1082,23 @@ export class TUI extends Container {
 		}
 		this.requestRender(true, { clearScrollback: options?.clearScrollback === true });
 	}
-	/** Borrow the alternate buffer for stable, history-free resize repainting. */
-	#beginResizeAltPaint(): void {
+	/**
+	 * Borrow the alternate buffer for stable, history-free resize repainting.
+	 * `restartingProbe` marks a transaction restarted by a SIGWINCH that
+	 * arrived while the settled anchor probe was in flight: the live window
+	 * was already stashed and emptied, so the snapshot below must be skipped
+	 * to keep the good stash.
+	 */
+	#beginResizeAltPaint(restartingProbe = false): void {
 		if (this.#altActive) {
 			this.requestRender(true);
 			return;
 		}
+		const burstLastHeight = this.#resizeBurstLastHeight ?? this.#previousHeight;
+		if (this.terminal.rows > burstLastHeight) this.#resizeBurstGrew = true;
+		this.#resizeBurstLastHeight = this.terminal.rows;
+		this.#resizeBurstPull += Math.max(0, this.terminal.rows - burstLastHeight);
+		this.#geometryEpoch++;
 		if (!this.#resizeAltActive) {
 			this.#resizeAltActive = true;
 			setAltScreenActive(true);
@@ -1056,10 +1117,19 @@ export class TUI extends Container {
 			// cursor-relative movement lands on the viewport's top row. On height
 			// shrink kitty clamps the cursor instead of moving it with pushed rows,
 			// so cursor-relative addressing would start rows late; fall back to the
-			// same bottom-preserving bound as resize-anchor recovery. The blank top
-			// row then anchors the settled CPR probe (empty window means staleRows 0).
+			// same bottom-preserving bound as resize-anchor recovery. The pre-erase
+			// window is stashed for the settled CPR probe: its reflowed row count
+			// bounds the anchor to `height - staleRows`, so a mis-parked cursor (a
+			// single-step tmux zoom re-lays the pane before SIGWINCH delivery,
+			// moving the park target under us) cannot anchor the settled repaint
+			// over pulled-back history rows or scroll-push the frame into
+			// scrollback again.
 			let erase = "";
-			if (this.#hasEverRendered && this.#providerWindow.length > 0) {
+			if (!restartingProbe) {
+				this.#resizeProbeWindow = this.#providerWindow;
+				this.#resizeProbeOffset = this.#parkedViewportOffset;
+			}
+			if (this.#hasEverRendered && this.#providerWindow.length > 0 && !isInsideTerminalMultiplexer()) {
 				if (this.terminal.rows < this.#previousHeight) {
 					const staleRows = this.#reflowedRowCount(
 						this.#providerWindow,
@@ -1078,6 +1148,22 @@ export class TUI extends Container {
 					);
 					erase = `\x1b[?25l${up > 0 ? `\x1b[${up}A` : ""}\r\x1b[J`;
 				}
+				// Both erase paths leave the cursor on the viewport's top row, so the
+				// parked offset no longer applies; carrying a stale nonzero offset
+				// into the probe would anchor the settled repaint above the real
+				// viewport top and overwrite visible committed rows.
+				this.#resizeProbeOffset = 0;
+				this.#providerWindow = [];
+				this.#parkedViewportOffset = 0;
+			}
+			if (this.#hasEverRendered && this.#providerWindow.length > 0 && isInsideTerminalMultiplexer()) {
+				// Multiplexers apply the pane re-layout on their own schedule relative
+				// to SIGWINCH delivery, so an immediate erase races it: with the pane
+				// already re-laid the stale coordinates blank pulled-back committed
+				// rows (destroying popped scrollback), and with the pane not yet
+				// re-laid the erase lands on rows about to move. Skip it — the
+				// settled repaint overwrites the live region at the clip-model anchor
+				// and erases below it, race-free after the quiet window.
 				this.#providerWindow = [];
 				this.#parkedViewportOffset = 0;
 			}
@@ -1103,14 +1189,60 @@ export class TUI extends Container {
 	 * trip against the parked cursor reports where the viewport's logical line
 	 * landed. The settled repaint waits for the reply (or a short timeout).
 	 */
-	#beginResizeAnchorProbe(): void {
+	#beginResizeAnchorProbe(retry = false): void {
 		this.#cancelResizeProbe();
 		const timer = this.#renderScheduler.scheduleRender(() => {
+			const probe = this.#resizeProbe;
+			if (probe !== undefined && !probe.retried && (isInsideTerminalMultiplexer() || this.#resizeBurstGrew)) {
+				// A CPR-less resolve is heuristic: a grow's pull span is unknown
+				// on any terminal, and SIGWINCH coalescing can hide intermediate
+				// grows entirely, so even an observed-monotonic multiplexer
+				// shrink cannot be modeled with certainty. A dropped DSR reply
+				// is a transient race — multiplexers in particular answer DSR
+				// themselves — so ask once more before falling back.
+				this.#beginResizeAnchorProbe(true);
+				return;
+			}
 			this.#resolveResizeAnchor(undefined);
 		}, TUI.#RESIZE_PROBE_TIMEOUT_MS);
-		this.#resizeProbe = { window: this.#providerWindow, offset: this.#parkedViewportOffset, timer };
-		this.#pendingCprReplies++;
-		this.terminal.write("\x1b[6n");
+		this.#resizeProbe = {
+			window: this.#resizeProbeWindow,
+			offset: this.#resizeProbeOffset,
+			timer,
+			epoch: this.#geometryEpoch,
+			retried: retry,
+		};
+		// Tags are never expired by age: a reply has no lifetime guarantee, and
+		// freeing a column while its reply may still arrive would let that
+		// reply match a newer tag on the reused column. Dead tags only
+		// accumulate from genuinely dropped replies; a terminal that drops
+		// enough of them to exhaust the span earns the timeout-only fallback.
+		// Park a distinct column for this request so its reply is
+		// self-identifying, then return the cursor to column 1 immediately:
+		// the reply snapshots the column when the terminal processes the CSI
+		// 6n, but a cursor RESTING on a nonzero column would reflow onto a
+		// later visual row if a direct terminal's width later shrank below it,
+		// corrupting the next probe's cursor-relative math. Columns 1-16 are
+		// never used as tags: column 1 cannot be told apart from a spurious or
+		// clamped reply, and modified F3 keys encode as CSI 1;<mod>R with
+		// modifier codes 2-16, which is byte-identical to a CPR for row 1 on
+		// those columns. A column may not be reused while its tag is live —
+		// the old request's delayed reply would be attributed to the new
+		// epoch — so scan for a free slot.
+		const span = Math.min(30, this.terminal.columns - 16);
+		if (span >= 4) {
+			for (let index = 0; index < span; index++) {
+				const candidate = 17 + ((this.#cprProbeSeq + index) % span);
+				if (this.#cprColumnTags.has(candidate)) continue;
+				this.#cprProbeSeq += index + 1;
+				this.#cprColumnTags.set(candidate, this.#geometryEpoch);
+				this.terminal.write(`\x1b[${candidate}G\x1b[6n\x1b[1G`);
+				return;
+			}
+		}
+		// Degenerate span or full occupancy: an untagged reply could never be
+		// attributed, so no DSR is sent at all; the timeout anchors
+		// conservatively on its own.
 	}
 
 	#cancelResizeProbe(): void {
@@ -1121,19 +1253,25 @@ export class TUI extends Container {
 
 	/**
 	 * Anchor the settled post-resize repaint. `reportedRow` is the 0-based CPR
-	 * row of the parked cursor (undefined = probe timed out). The viewport top
-	 * is `min(reported - parkOffset, height - staleRows)`: terminals track the
+	 * row of the parked cursor (undefined = probe timed out). Direct terminals
+	 * use `min(reported - parkOffset, height - staleRows)`: they track the
 	 * cursor exactly through width rewrap, and the second bound reconstructs
-	 * height-shrink scrollback pushes that leave the cursor behind (kitty clamps
-	 * the cursor instead of scrolling it) — bottom-preserving resize guarantees
-	 * the stale viewport ends on the last screen row whenever a push happened.
-	 * Validated against kitty's real core in resize-anchor-recovery.test.ts.
+	 * height-shrink scrollback pushes that leave the cursor behind (kitty
+	 * clamps the cursor instead of scrolling it) — bottom-preserving resize
+	 * guarantees the stale viewport ends on the last screen row whenever a
+	 * push happened; validated against kitty's real core in
+	 * resize-anchor-recovery.test.ts. Multiplexers clip on height changes
+	 * (though they reflow on width changes), so that bound never applies:
+	 * monotonic shrinks use the deterministic clip model below, everything
+	 * else trusts the CPR directly.
 	 */
 	#resolveResizeAnchor(reportedRow: number | undefined): void {
 		const probe = this.#resizeProbe;
 		if (!probe) return;
 		probe.timer.cancel();
 		this.#resizeProbe = undefined;
+		// Column tags stay live across resolves: their replies are
+		// self-identifying and discarded by tag whenever they arrive.
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
 		const staleRows = this.#reflowedRowCount(probe.window, 0, probe.window.length, width);
@@ -1141,7 +1279,58 @@ export class TUI extends Container {
 			reportedRow === undefined
 				? this.#providerViewportTop
 				: reportedRow - this.#reflowedRowCount(probe.window, 0, probe.offset, width);
-		const top = Math.max(0, Math.min(reportedTop, height - staleRows));
+		let top: number;
+		if (isInsideTerminalMultiplexer()) {
+			if (reportedRow !== undefined) {
+				// The parked cursor's reply is exact under multiplexer clipping:
+				// discards leave the cursor in place, pushes only occur after
+				// everything below it is discarded (the bottom row IS the
+				// attached position), and grow pull-down rides it down. It
+				// therefore also reflects intermediate geometries that SIGWINCH
+				// coalescing hid from the burst tracker, and always outranks the
+				// clip model. The `height - staleRows` bound must NOT apply here:
+				// it encodes bottom-preserving rewrap, but a multiplexer shrink
+				// may have discarded stale rows below the cursor instead of
+				// pushing the top ones. Frame-size clamping happens when the
+				// settled plan frame is emitted.
+				top = Math.max(0, reportedTop);
+			} else if (height < this.#previousHeight && !this.#resizeBurstGrew) {
+				// Last resort after the retry: model the clip deterministically
+				// from the saved parked cursor. Rows strictly below the cursor
+				// are discarded first (even non-blank ones — measured against
+				// real tmux), and only the remainder of the shrink pushes top
+				// rows into scrollback; across an observed burst the totals
+				// telescope from pre-burst state. SIGWINCH coalescing can hide a
+				// grow from this model, which is why a reply always wins above.
+				const parkedRow = this.#providerViewportTop + this.#reflowedRowCount(probe.window, 0, probe.offset, width);
+				const shrink = this.#previousHeight - height;
+				const discardedBelow = Math.min(shrink, Math.max(0, this.#previousHeight - 1 - parkedRow));
+				const pushed = Math.max(0, shrink - discardedBelow);
+				top = Math.max(0, this.#providerViewportTop - pushed);
+			} else {
+				// CPR-less grow or reversed burst: the pre-resize top is
+				// stale-low, every grow step already pulled scrollback down.
+				// Anchor at the conservative upper bound — pull never exceeds
+				// the burst's accumulated growth, and pushes/discards only lower
+				// the top. Exact when scrollback covers the pull; when it does
+				// not, the repaint lands below the real viewport and leaves
+				// stale rows above rather than overwriting committed ones.
+				top = Math.max(0, this.#providerViewportTop + this.#resizeBurstPull);
+			}
+		} else {
+			// Direct terminals rewrap bottom-preserving: with `staleRows` stale
+			// rows on screen the viewport top cannot exceed `height - staleRows`
+			// whenever a push happened, so the bound reconstructs height-shrink
+			// pushes that leave the cursor behind (kitty clamps the cursor
+			// instead of scrolling it). A CPR-less grow is stale-low like the
+			// multiplexer case — grow pull-down moved the real viewport — so it
+			// anchors at the accumulated pull bound, still under the clamp.
+			const fallbackTop =
+				reportedRow === undefined && this.#resizeBurstGrew
+					? this.#providerViewportTop + this.#resizeBurstPull
+					: reportedTop;
+			top = Math.max(0, Math.min(fallbackTop, height - staleRows));
+		}
 		if ($flag("PI_DEBUG_REDRAW")) {
 			const msg = `[${new Date().toISOString()}] resize anchor: size=${width}x${height} cpr=${reportedRow ?? "timeout"} park=${probe.offset} stale=${staleRows} old=${this.#providerViewportTop} top=${top}\n`;
 			fs.appendFileSync(getDebugLogPath(), msg);
@@ -1152,14 +1341,17 @@ export class TUI extends Container {
 	}
 
 	/**
-	 * Rows `[start, end)` of a previously painted window re-measured at `width`.
-	 * Direct terminals rewrap on resize (a row spans ceil(cells/width) rows);
-	 * multiplexers clip in place, so every row still spans exactly one row.
+	 * Rows `[start, end)` of a previously painted window re-measured at
+	 * `width`. Every terminal rewraps content on a width change — including
+	 * multiplexers: tmux clips in place on height changes only, and reflows
+	 * the pane (scrollback included) when the width moves, so a row painted
+	 * wider than the current width spans ceil(cells/width) physical rows
+	 * everywhere. For height-only resizes the painted rows already fit the
+	 * width and the count is unchanged.
 	 */
 	#reflowedRowCount(window: readonly string[], start: number, end: number, width: number): number {
 		const stop = Math.min(end, window.length);
 		const from = Math.max(0, start);
-		if (isInsideTerminalMultiplexer()) return Math.max(0, stop - from);
 		let rows = 0;
 		for (let index = from; index < stop; index++) {
 			rows += Math.max(1, Math.ceil(visibleWidth(window[index]!) / Math.max(1, width)));
@@ -1340,6 +1532,28 @@ export class TUI extends Container {
 		this.#paintEndSequence = enabled ? PAINT_END : PAINT_END_NO_SYNC;
 	}
 
+	#flushHistoryBeforeStop(): void {
+		const provider = this.#frameProvider;
+		if (provider?.beginHistoryFlush === undefined) return;
+		const width = this.terminal.columns;
+		const height = this.terminal.rows;
+		if (width <= 0 || height <= 0) return;
+		provider.beginHistoryFlush();
+		while (true) {
+			this.#imageBudget.beginPass();
+			const plan = provider.renderFrame({ columns: width, rows: height });
+			this.#imageBudget.endPass();
+			if (plan.history === undefined) return;
+			let viewport = Array.from(plan.viewport);
+			if (viewport.length > height) viewport = viewport.slice(0, height);
+			const acceptedBefore = this.#acceptedHistoryBatchId;
+			this.#emitPlanFrame(width, height, viewport, plan.history, provider);
+			if (plan.history.id > acceptedBefore && this.#acceptedHistoryBatchId === acceptedBefore) {
+				throw new Error("History flush did not accept the offered batch");
+			}
+		}
+	}
+
 	stop(): void {
 		this.#resizeSettleTimer?.cancel();
 		this.#resizeSettleTimer = undefined;
@@ -1359,6 +1573,12 @@ export class TUI extends Container {
 			this.#altPreviousLines = [];
 			this.#pendingAltExit = "";
 		}
+		// A latched destructive reset (settled rebuild-mode resize, /clear) pairs
+		// ED3 with a complete-ledger replay. Running that pair during stop would
+		// erase native history and re-stream the whole transcript at quit; drop
+		// the latch so the flush below writes only un-retired rows.
+		this.#clearScrollbackOnNextRender = false;
+		this.#flushHistoryBeforeStop();
 		// Deliberately leave transmitted images in the terminal's graphics store:
 		// placeholder cells committed to native scrollback render only while their
 		// image data lives, so a delete-by-id here blanks every transcript image
@@ -1492,7 +1712,7 @@ export class TUI extends Container {
 	}
 	#prepareForcedRender(clearScrollback: boolean): void {
 		if (clearScrollback && !this.#clearScrollbackOnNextRender) {
-			this.#frameProvider?.resetHistory?.();
+			this.#frameProvider?.beginHistoryReplay?.();
 			if (TERMINAL.imageProtocol === ImageProtocol.Kitty) this.#imageBudget.forgetTransmitted();
 		}
 		this.#clearScrollbackOnNextRender ||= clearScrollback;
@@ -1568,12 +1788,39 @@ export class TUI extends Container {
 		// Consume CPR replies (CSI row;col R) while an anchor probe is unanswered;
 		// they are terminal reports, never keystrokes, and must not reach the
 		// focused component.
-		while (this.#pendingCprReplies > 0) {
-			const match = data.match(/\x1b\[(\d+);(\d+)R/);
+		let searchFrom = 0;
+		while (this.#cprColumnTags.size > 0) {
+			const match = data.slice(searchFrom).match(/\x1b\[(\d+);(\d+)R/);
 			if (!match || match.index === undefined) break;
-			this.#pendingCprReplies--;
-			this.#resolveResizeAnchor(Number(match[1]) - 1);
-			data = data.slice(0, match.index) + data.slice(match.index + match[0].length);
+			const row = Number(match[1]);
+			const column = Number(match[2]);
+			if (!this.#cprColumnTags.has(column) && row === 1 && column >= 2) {
+				// CSI 1;<mod>R with no live tag is modified F3: the modifier
+				// parameter spans 2-256 once the lock-state bits (caps 64,
+				// num 128) and hyper/meta are included, so no practical tag
+				// range escapes it entirely. Anything row-1 we did not tag is
+				// treated as a keystroke and left for the focused component;
+				// a tagged column hit by a hyper/meta-modified F3 (params
+				// 17-64, practically unused) is still gated by the epoch check
+				// below.
+				searchFrom += match.index + match[0].length;
+				continue;
+			}
+			if (this.#cprColumnTags.has(column)) {
+				// Column-tagged reply: exact attribution. Resolve only when its
+				// request was parked under the active probe's geometry; a reply
+				// from an older epoch is stale and discarded.
+				const tagEpoch = this.#cprColumnTags.get(column);
+				this.#cprColumnTags.delete(column);
+				const probe = this.#resizeProbe;
+				if (probe !== undefined && tagEpoch === probe.epoch) {
+					this.#resolveResizeAnchor(Number(match[1]) - 1);
+				}
+			}
+			// Other unknown-column replies while expecting tagged ones are our
+			// requests answered with a clamped or mangled column: strip and
+			// discard; the probe timeout covers recovery.
+			data = data.slice(0, searchFrom + match.index) + data.slice(searchFrom + match.index + match[0].length);
 		}
 		if (data.length === 0) return;
 		// Ctrl+C/Esc use app-level double-press windows. Give those gestures one
@@ -1983,7 +2230,7 @@ export class TUI extends Container {
 			return;
 		}
 		const provider = this.#frameProvider;
-		if (!provider?.resetHistory) return;
+		if (!provider?.beginHistoryReplay) return;
 		this.#resizeReplaySize = size;
 		if (this.#clearScrollbackOnNextRender) {
 			this.#forceViewportRepaintOnNextRender = true;
@@ -1993,15 +2240,14 @@ export class TUI extends Container {
 			this.#prepareForcedRender(true);
 			return;
 		}
-		provider.resetHistory();
+		provider.beginHistoryReplay();
 		this.#forceViewportRepaintOnNextRender = true;
 	}
 
 	/**
-	 * Physical write transaction: append an unacknowledged history batch above
-	 * the anchored mutable viewport, repaint the viewport, and erase stale rows
-	 * below. Appending K rows scrolls at most K rows off the top — the oldest
-	 * visible history — and the viewport anchor follows the retained history.
+	 * Physical write transaction: append an ordinary batch, or bottom-split one
+	 * complete replay into a history remainder and final viewport, then serialize
+	 * the whole result in one terminal write before acknowledgement.
 	 */
 	#emitPlanFrame(
 		width: number,
@@ -2015,11 +2261,28 @@ export class TUI extends Container {
 			while (viewport.length < height) viewport.push("");
 			viewport = this.#compositeOverlaysIntoWindow(viewport, width, height);
 		}
-		const markers = this.#extractCursorMarkers(viewport);
-		const prepared = this.#prepareLinesArray(viewport, width);
 		const history = offered !== undefined && offered.id > this.#acceptedHistoryBatchId ? offered : undefined;
 		if (offered !== undefined && offered.id <= this.#acceptedHistoryBatchId) provider?.acknowledgeHistory(offered.id);
-		const historyRows = history?.rows ?? [];
+
+		let historyRows = history?.rows ?? [];
+		let replayViewportRows = 0;
+		if (history?.kind === "replay") {
+			// Providers may omit unused leading rows from a short viewport. Make
+			// that logical space explicit before the bottom-first replay split.
+			while (viewport.length < height) viewport.unshift("");
+			let leadingBlankRows = 0;
+			while (leadingBlankRows < viewport.length && !/\S/.test(viewport[leadingBlankRows]!)) {
+				leadingBlankRows++;
+			}
+			const moved = Math.min(historyRows.length, leadingBlankRows);
+			if (moved > 0) {
+				viewport = [...historyRows.slice(historyRows.length - moved), ...viewport.slice(moved)];
+				historyRows = historyRows.slice(0, historyRows.length - moved);
+				replayViewportRows = moved;
+			}
+		}
+		const markers = this.#extractCursorMarkers(viewport);
+		const prepared = this.#prepareLinesArray(viewport, width);
 		const preparedHistory = this.#prepareLinesArray(historyRows, width);
 		const rows = prepared.length;
 		// Destructive reset (session replace, /tree, explicit clear, or a settled
@@ -2051,7 +2314,14 @@ export class TUI extends Container {
 		} else {
 			this.#imageBudget.takePurgeIds();
 		}
-		if (destructiveReset) buffer += "\x1b[H\x1b[3J\x1b[2J";
+		// ED2 MUST precede ED3: tmux implements ED2 by scrolling the live screen
+		// into pane history (so cleared content stays reachable), so erasing
+		// history first would let ED2 refill it with a copy of the old screen —
+		// which the replay then repaints, duplicating one full frame per reset.
+		// ED2-then-ED3 clears the screen, then wipes history including that
+		// push. On xterm-family terminals the two erases are independent and
+		// the order is irrelevant.
+		if (destructiveReset) buffer += "\x1b[H\x1b[2J\x1b[3J";
 		const diffable =
 			geometryStable &&
 			historyRows.length === 0 &&
@@ -2112,6 +2382,8 @@ export class TUI extends Container {
 			}
 			if (newTop + rows < height) buffer += `\x1b[${newTop + rows + 1};1H\x1b[J`;
 		}
+		const mutableTop = newTop + replayViewportRows;
+		const mutablePrepared = replayViewportRows > 0 ? prepared.slice(replayViewportRows) : prepared;
 		const marker = markers[0];
 		const target =
 			marker !== undefined && rows > 0
@@ -2119,23 +2391,26 @@ export class TUI extends Container {
 				: null;
 		if (target) {
 			buffer += `\x1b[${target.row + 1};${target.col + 1}H${target.visible ? "\x1b[?25h" : "\x1b[?25l"}`;
-			this.#parkedViewportOffset = Math.max(0, target.row - newTop);
+			this.#parkedViewportOffset = Math.max(0, target.row - mutableTop);
 		} else {
 			// Park the hidden cursor on the viewport's top row: terminals keep the
 			// cursor attached to its logical line through resize reflow, so the
 			// post-resize anchor probe can recover where the viewport landed.
-			buffer += `\x1b[?25l\x1b[${newTop + 1};1H`;
+			buffer += `\x1b[?25l\x1b[${mutableTop + 1};1H`;
 			this.#parkedViewportOffset = 0;
 		}
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 		if (target) this.#recordHardwareCursorState(target);
 		else this.#recordHardwareCursorHidden();
-		this.#providerWindow = prepared;
-		this.#providerViewportTop = newTop;
+		this.#providerWindow = mutablePrepared;
+		this.#providerViewportTop = mutableTop;
 		this.#previousWidth = width;
 		this.#previousHeight = height;
-		this.#previousFrameLength = rows;
+		this.#resizeBurstGrew = false;
+		this.#resizeBurstLastHeight = undefined;
+		this.#resizeBurstPull = 0;
+		this.#previousFrameLength = mutablePrepared.length;
 		this.#clearScrollbackOnNextRender = false;
 		this.#forceViewportRepaintOnNextRender = false;
 		this.#hasEverRendered = true;
@@ -2143,10 +2418,9 @@ export class TUI extends Container {
 		if (history !== undefined) {
 			this.#acceptedHistoryBatchId = history.id;
 			provider?.acknowledgeHistory(history.id);
-			// Draining is one batch per frame; the provider may hold further
-			// finalized prefixes (large resumed transcripts). Pump the next frame
-			// instead of waiting for an unrelated render request.
-			this.requestRender();
+			// Normal retirement may hold another ordered batch. Replay is always
+			// complete, so pumping it would create a second visible redraw/write.
+			if (history.kind !== "replay") this.requestRender();
 		}
 	}