@linxiraos/pi-tui 1.1.7 → 1.1.8

package/CHANGELOG.md

@@ -2,14 +2,10 @@
 
 ## [Unreleased]
 
-## [1.1.7] - 2026-09-01
+## [1.1.8] - 2026-09-04
 
-- 同步上游 OMP v18.0.11（`b8ce33a58911c26bed1d84f0db9a5e2e727c49a2`）。
-
-## [1.1.6] - 2026-08-30
-
-- 同步上游 OMP v18.0.10（`33cc6b9a043a`）。
-- 同步上游 OMP v18.0.9（`cc14e04f075d`）。
+- Restored the sidebar gutter engine + `SidebarComponent` + `/sidebar` command (Zeta-only surface dropped by an earlier upstream merge).
+- OMP sync v18.1.2–v18.1.5: sub-frame history ownership (the frame provider owns history), CoW worktree cloning support, and renderer fixes.
 
 ## [1.1.3] - 2026-08-25
 

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

@@ -57,6 +57,11 @@ export interface EditorTextAssistProvider {
     /** Return replacement candidates for the misspelled word at the cursor. */
     getWordReplacements?(lines: string[], cursorLine: number, cursorCol: number): EditorWordReplacements | null | Promise<EditorWordReplacements | null>;
 }
+/** What the paste transport knew about the input burst before the editor inserts the payload. */
+export interface PasteOptions {
+    /** A submit keypress arrived in the same input burst and will be dispatched right after the paste. */
+    submitAfterPaste?: boolean;
+}
 export declare class Editor implements Component, Focusable {
     #private;
     /** Focusable interface - set by TUI when focus changes */
@@ -89,8 +94,9 @@ export declare class Editor implements Component, Focusable {
      *  the editor inserts nothing and records no undo state, leaving insertion to the host (e.g. a
      *  "wrap in a code block / XML / attach as file" menu for very large pastes), which re-inserts
      *  via {@link insertPaste} or {@link insertText}. Return `false` (or leave unset) for the
-     *  default collapse-to-marker behavior. `lineCount` is the sanitized paste's line count. */
-    onLargePaste?: (text: string, lineCount: number) => boolean;
+     *  default collapse-to-marker behavior. `lineCount` is the sanitized paste's line count;
+     *  `options` carries what the paste transport knew about the burst. */
+    onLargePaste?: (text: string, lineCount: number, options: PasteOptions) => boolean;
     onAutocompleteCancel?: () => void;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
@@ -210,7 +216,7 @@ export declare class Editor implements Component, Focusable {
     /** Drop any volatile preview, then insert `text` as a single undoable edit. */
     commitVolatileText(text: string): void;
     /** Apply terminal paste semantics to text from non-bracketed paste transports. */
-    pasteText(text: string): void;
+    pasteText(text: string, options?: PasteOptions): void;
     /** Insert `content` as a collapsed `[Paste #N]` marker (stored for expansion on submit via
      *  {@link getExpandedText}). Hosts that intercept large pastes through {@link onLargePaste} use
      *  this to re-insert a (possibly transformed) paste without re-triggering the interception hook. */

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

@@ -29,9 +29,9 @@ export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
- * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
- * reports display order via {@link observe}, and the TUI drives the purge +
- * redraw on the frame after a new image pushes the count past the cap.
+ * rewritten) plus an explicit graphics purge of the demoted ids. {@link Image}
+ * reports display order via {@link observe}; when that reveals a stricter split,
+ * the TUI repeats the pass before emitting its terminal frame.
  *
  * `cap <= 0` disables budgeting: every image stays a live graphic.
  */
@@ -67,9 +67,8 @@ export declare class ImageBudget {
      */
     observe(imageId: number): boolean;
     /**
-     * End a render pass. Returns true when this frame must purge graphics and
-     * fully repaint to apply a stricter budget; read the ids via
-     * {@link takePurgeIds}.
+     * End a render pass. Returns true when the pass discovered a stricter budget
+     * and must be repeated before its terminal frame is emitted.
      */
     endPass(): boolean;
     /** Image ids to delete from the terminal this frame; clears the pending set. */

package/dist/types/keys.d.ts

@@ -63,7 +63,7 @@ export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
  * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
  * is `"ctrl+c"`, not just `string`). This mirrors the upstream
  * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
- * scope alias (`@mariozechner`, `@earendil-works`, `@oh-my-pi`) keep working
+ * scope alias (`@mariozechner`, `@earendil-works`, `@linxiraos`) keep working
  * once the specifier shim remaps them to this package.
  */
 export declare const Key: {

package/dist/types/kitty-graphics.d.ts

@@ -26,12 +26,12 @@ export interface KittyGraphicsFeatures {
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
  * U+10EEEE with row/column diacritics).
  *
- * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * Kitty and Ghostty advertise placeholder support directly. A multiplexer
  * cannot use cursor-positioned placements because the outer terminal does not
- * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
- * also opts into placeholders there — matching `timg -pk`. Automatic tmux
- * fallback stays off because the unknown outer terminal may render U+10EEEE as
- * literal PUA boxes (#1877).
+ * know pane scroll/reflow state. An explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * opts into placeholders under any multiplexer — matching `timg -pk`.
+ * Automatic Herdr fallback stays off because its pane marker does not prove
+ * that the experimental Kitty renderer is enabled.
  *
  * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
  * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.

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

@@ -43,7 +43,12 @@ export type StdinBufferOptions = {
 };
 export type StdinBufferEventMap = {
     data: [string];
-    paste: [string];
+    /**
+     * A completed bracketed paste. `enter` carries an Enter keypress that shared
+     * the paste's stdin read, so the terminal can dispatch paste and submit to
+     * the same focused component before a paste-triggered overlay can take focus.
+     */
+    paste: [content: string, enter?: string];
 };
 /**
  * Buffers stdin input and emits complete sequences via the 'data' event.

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

@@ -1,4 +1,5 @@
 import type { HangulCompatibilityJamoWidth } from "./utils.js";
+export * from "./terminal-multiplexer.js";
 export { isInsideTmux, wrapTmuxPassthrough } from "./tmux.js";
 export declare enum ImageProtocol {
     Kitty = "\u001B_G",
@@ -48,8 +49,6 @@ export declare class TerminalInfo {
     formatNotification(message: string | TerminalNotification): string;
     sendNotification(message: string | TerminalNotification): void;
 }
-/** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
-export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether the agent process is running inside a Zellij session. Read fresh on
  * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
@@ -86,9 +85,15 @@ export declare function synchronizedOutputUserOverride(env?: NodeJS.ProcessEnv):
  *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
  *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
  *      WSL/SSH-fronted host alike.
- *   4. Known direct terminals with confirmed support. SSH does *not* disable —
+ *   4. Herdr panes. Herdr is otherwise treated as a multiplexer so leaked
+ *      kitty/ghostty identities cannot enable placeholder graphics, but its
+ *      pane VTE is libghostty and already suppresses compositing while DEC 2026
+ *      is set. Leaving sync off lets CUP-diff paints and split write(2) chunks
+ *      composite as dirty-row patches — the live viewport tears, with the top
+ *      frozen while only the bottom refreshes.
+ *   5. Known direct terminals with confirmed support. SSH does *not* disable —
  *      DEC 2026 passes through SSH when the outer terminal honors it.
- *   5. Everything else starts off, including risky multiplexers; the runtime
+ *   6. Everything else starts off, including risky multiplexers; the runtime
  *      DECRQM probe upgrades any of them when the terminal actually reports
  *      `?2026` supported (current zellij, tmux master, foot, contour, mintty…).
  */
@@ -165,9 +170,9 @@ export declare function isPaseoEmbedder(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Resolve the image protocol for a non-forced runtime: static per-terminal
  * support (with Warp's platform carve-out), then the multiplexer fallback,
- * then the Paseo embedder carve-out. `isTTY` is injectable because the
- * fallback only fires on a real TTY — a piped subprocess cannot exercise
- * that path, so regression tests call this directly.
+ * then host carve-outs. `isTTY` is injectable because the fallback only fires
+ * on a real TTY — a piped subprocess cannot exercise that path, so regression
+ * tests call this directly.
  */
 export declare function resolveImageProtocol(terminalId: TerminalId, env?: NodeJS.ProcessEnv, isTTY?: boolean): ImageProtocol | null;
 /** Resolve terminal identity from environment markers used by common emulators. */

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

@@ -0,0 +1,4 @@
+/** True when this process is running inside a Herdr pane. */
+export declare function isInsideHerdr(env?: NodeJS.ProcessEnv): boolean;
+/** Detect whether a terminal multiplexer owns the current screen grid. */
+export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;

package/dist/types/terminal.d.ts

@@ -20,33 +20,50 @@
  */
 export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
 /**
- * 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 declare const STDOUT_BACKLOG_CLEAR_BYTES: number;
+/**
+ * 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 declare class OutputBacklogGuard {
+export declare class StdoutStallWatchdog {
     #private;
-    private readonly capBytes;
-    constructor(capBytes?: number);
-    /** True once a refused write started a backlog that has not yet drained. */
-    get tracking(): boolean;
+    private readonly armBytes;
+    private readonly clearBytes;
+    private readonly stallMs;
+    constructor(armBytes?: number, clearBytes?: number, stallMs?: number);
+    /** True while an episode is active and the backlog must be polled to completion. */
+    get armed(): boolean;
     /**
-     * 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;
-    /** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+    sample(pending: number, nowMs: number): boolean;
+    /** Episode ended (drained) or terminal torn down: stop watching. */
     reset(): void;
 }
 /** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
@@ -82,6 +99,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(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     /**
@@ -160,8 +184,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;
 }
 /**
  * True when stdout flows through a ConPTY pseudo-console (native win32, or
@@ -206,7 +231,7 @@ export declare class ProcessTerminal implements Terminal {
      * probes remain direct. Suppressed while inactive, headless, or after teardown.
      */
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
-    onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+    onPrivateModeReport(callback: PrivateModeReportHandler): void;
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     enableInput(): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;

package/dist/types/tui.d.ts

@@ -285,6 +285,24 @@ export declare class TUI extends Container {
      * plus a full redraw on the frame after a new image exceeds the cap.
      */
     setMaxInlineImages(cap: number): void;
+    /**
+     * Yield `width` columns from the right edge of the terminal as a sidebar
+     * margin, repainted per frame from the gutter component (see
+     * {@link setGutterComponent}). The main area composes and paints at
+     * `terminal.columns - width`, which keeps every committed row — and
+     * therefore native scrollback — free of gutter text. `null` restores
+     * full-width rendering. Frames where that would drop the main area below
+     * {@link MIN_MAIN_AREA_COLUMNS}, or where a fullscreen-capable overlay is
+     * visible, ignore the reservation and paint at the physical width.
+     */
+    setMainWidth(width: number | null): void;
+    /**
+     * Component rendered into the right-hand margin created by
+     * {@link setMainWidth}. Its rows are painted viewport-only via absolute
+     * cursor addressing inside each frame's synchronized block; they never enter
+     * the composed frame or scrollback. `null` clears the margin.
+     */
+    setGutterComponent(component: Component | null): void;
     /** Return how settled resizes refresh native scrollback. */
     getResizeScrollback(): ResizeScrollbackMode;
     /** Set how settled resizes refresh native scrollback. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-tui",
-	"version": "1.1.7",
+	"version": "1.1.8",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.7",
-		"@linxiraos/pi-utils": "1.1.7"
+		"@linxiraos/pi-natives": "1.1.8",
+		"@linxiraos/pi-utils": "1.1.8"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/autocomplete.ts

@@ -382,7 +382,7 @@ function buildSlashCommandCompletions(
 			// Equal text-match scores fall back to usage frequency, then to the
 			// stable registry order.
 			.sort((a, b) => b.score - a.score || b.usage - a.usage)
-			.map(({ score: _, usage: _usage, ...rest }) => rest)
+			.map(({ score: _score, usage: _usage, ...rest }) => rest)
 	);
 }
 

package/src/components/editor.ts

@@ -467,6 +467,12 @@ export interface EditorTextAssistProvider {
 type HistoryCursorAnchor = "start" | "end";
 type AutocompleteRequest = { kind: "regular"; explicitTab: boolean } | { kind: "force" };
 
+/** What the paste transport knew about the input burst before the editor inserts the payload. */
+export interface PasteOptions {
+	/** A submit keypress arrived in the same input burst and will be dispatched right after the paste. */
+	submitAfterPaste?: boolean;
+}
+
 export class Editor implements Component, Focusable {
 	#state: EditorState = {
 		lines: [""],
@@ -581,8 +587,9 @@ export class Editor implements Component, Focusable {
 	 *  the editor inserts nothing and records no undo state, leaving insertion to the host (e.g. a
 	 *  "wrap in a code block / XML / attach as file" menu for very large pastes), which re-inserts
 	 *  via {@link insertPaste} or {@link insertText}. Return `false` (or leave unset) for the
-	 *  default collapse-to-marker behavior. `lineCount` is the sanitized paste's line count. */
-	onLargePaste?: (text: string, lineCount: number) => boolean;
+	 *  default collapse-to-marker behavior. `lineCount` is the sanitized paste's line count;
+	 *  `options` carries what the paste transport knew about the burst. */
+	onLargePaste?: (text: string, lineCount: number, options: PasteOptions) => boolean;
 	onAutocompleteCancel?: () => void;
 	disableSubmit: boolean = false;
 
@@ -2148,8 +2155,8 @@ export class Editor implements Component, Focusable {
 	}
 
 	/** Apply terminal paste semantics to text from non-bracketed paste transports. */
-	pasteText(text: string): void {
-		this.#handlePaste(text);
+	pasteText(text: string, options: PasteOptions = {}): void {
+		this.#handlePaste(text, options);
 	}
 
 	/** Insert `content` as a collapsed `[Paste #N]` marker (stored for expansion on submit via
@@ -2289,7 +2296,7 @@ export class Editor implements Component, Focusable {
 		}
 	}
 
-	#handlePaste(pastedText: string): void {
+	#handlePaste(pastedText: string, options: PasteOptions = {}): void {
 		let filteredText = this.#sanitizePastedText(pastedText);
 
 		// If pasting a file path (starts with /, ~, or .) and the character before
@@ -2311,7 +2318,7 @@ export class Editor implements Component, Focusable {
 		// Let the host intercept marker-sized pastes (e.g. the large-paste menu). When it takes
 		// over, the editor inserts nothing and records no undo state — the host re-inserts via
 		// `insertPaste`/`insertText` once the user chooses.
-		if (isMarkerSized && this.onLargePaste?.(filteredText, pastedLines.length)) {
+		if (isMarkerSized && this.onLargePaste?.(filteredText, pastedLines.length, options)) {
 			return;
 		}
 

package/src/components/image.ts

@@ -73,9 +73,9 @@ function nextImageIdSeed(): number {
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
- * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
- * reports display order via {@link observe}, and the TUI drives the purge +
- * redraw on the frame after a new image pushes the count past the cap.
+ * rewritten) plus an explicit graphics purge of the demoted ids. {@link Image}
+ * reports display order via {@link observe}; when that reveals a stricter split,
+ * the TUI repeats the pass before emitting its terminal frame.
  *
  * `cap <= 0` disables budgeting: every image stays a live graphic.
  */
@@ -87,6 +87,8 @@ export class ImageBudget {
 	#idToKey = new Map<number, string>();
 	/** Display-order image ids observed during the in-flight pass. */
 	#passIds: number[] = [];
+	/** Per-id suppression decision from the first observation in this pass. */
+	#passSuppression = new Map<number, boolean>();
 	/**
 	 * Suppress threshold reflected in the frame currently on the terminal: images
 	 * at display indices `[0, #onTerminal)` are shown as text there.
@@ -104,7 +106,7 @@ export class ImageBudget {
 	/** Image ids whose data is believed to be loaded in the terminal's store. */
 	#transmitted = new Set<number>();
 	/** Transmit sequences (full base64) to write once, before this frame's placements. */
-	#pendingTransmits: string[] = [];
+	#pendingTransmits = new Map<number, string>();
 	// True while the in-flight pass is a partial/throwaway pass (the
 	// non-multiplexer resize viewport fast path) that walks only the visible
 	// tail, bottom-up. Such a pass cannot derive display order from observe()
@@ -185,6 +187,7 @@ export class ImageBudget {
 	 */
 	beginPass(stable = false): void {
 		this.#passIds.length = 0;
+		this.#passSuppression.clear();
 		this.#stablePass = stable;
 		this.#applyingReset = !stable && this.#cap > 0 && this.#planned > this.#onTerminal;
 	}
@@ -199,47 +202,49 @@ export class ImageBudget {
 	 * (`#suppressedIds`) keyed by id — order- and partiality-independent.
 	 */
 	observe(imageId: number): boolean {
+		const existing = this.#passSuppression.get(imageId);
+		if (existing !== undefined) return existing;
 		if (this.#stablePass) {
 			const suppressed = this.#cap > 0 && this.#suppressedIds.has(imageId);
+			this.#passSuppression.set(imageId, suppressed);
 			if (suppressed) this.#forgetKeyForId(imageId);
 			return suppressed;
 		}
 		const index = this.#passIds.length;
 		this.#passIds.push(imageId);
 		const suppressed = this.#cap > 0 && index < this.#planned;
+		this.#passSuppression.set(imageId, suppressed);
 		if (suppressed) this.#forgetKeyForId(imageId);
 		return suppressed;
 	}
 
 	/**
-	 * End a render pass. Returns true when this frame must purge graphics and
-	 * fully repaint to apply a stricter budget; read the ids via
-	 * {@link takePurgeIds}.
+	 * End a render pass. Returns true when the pass discovered a stricter budget
+	 * and must be repeated before its terminal frame is emitted.
 	 */
 	endPass(): boolean {
 		const total = this.#passIds.length;
 		this.#lastTotal = total;
-		let reset = false;
 		if (this.#applyingReset) {
 			for (let i = this.#onTerminal; i < this.#planned && i < total; i++) {
 				const id = this.#passIds[i];
-				this.#purgeIds.push(id);
-				// d=I frees the data too, so the image must re-transmit if it returns.
+				// A transmit queued by a discarded discovery pass never reached
+				// the terminal, so cancel it instead of transmitting then purging.
+				if (!this.#pendingTransmits.delete(id)) this.#purgeIds.push(id);
 				this.#transmitted.delete(id);
 				this.#deletePlacementState(id);
 				this.#forgetKeyForId(id);
 			}
 			this.#onTerminal = this.#planned;
 			this.#applyingReset = false;
-			reset = true;
 		}
-		this.#reconcile(total);
+		const retry = this.#reconcile(total);
 		// Snapshot the committed display-order suppression by id: the prefix
 		// [0, #onTerminal) is what the terminal currently shows as text. Partial
 		// passes replay this per id (see #stablePass) instead of re-deriving it
 		// from a reversed, tail-only walk.
 		this.#suppressedIds = new Set(this.#passIds.slice(0, this.#onTerminal));
-		return reset;
+		return retry;
 	}
 
 	/** Image ids to delete from the terminal this frame; clears the pending set. */
@@ -256,7 +261,7 @@ export class ImageBudget {
 		const ids = [...this.#transmitted];
 		this.#transmitted.clear();
 		this.#purgeIds = [];
-		this.#pendingTransmits = [];
+		this.#pendingTransmits.clear();
 		this.#keyToId.clear();
 		this.#idToKey.clear();
 		this.#placementState.clear();
@@ -393,12 +398,12 @@ export class ImageBudget {
 	enqueueTransmit(imageId: number, sequence: string): void {
 		if (this.#transmitted.has(imageId)) return;
 		this.#transmitted.add(imageId);
-		this.#pendingTransmits.push(sequence);
+		this.#pendingTransmits.set(imageId, sequence);
 	}
 
 	/** Whether a frame has image data queued but not yet written to the terminal. */
 	hasPendingTransmits(): boolean {
-		return this.#pendingTransmits.length > 0;
+		return this.#pendingTransmits.size > 0;
 	}
 
 	/**
@@ -410,7 +415,7 @@ export class ImageBudget {
 	get quiescent(): boolean {
 		return (
 			this.#lastTotal === 0 &&
-			this.#pendingTransmits.length === 0 &&
+			this.#pendingTransmits.size === 0 &&
 			this.#purgeIds.length === 0 &&
 			this.#planned === this.#onTerminal
 		);
@@ -418,9 +423,9 @@ export class ImageBudget {
 
 	/** Transmit sequences to write before this frame's placements; clears the queue. */
 	takeTransmits(): readonly string[] {
-		if (this.#pendingTransmits.length === 0) return EMPTY_TRANSMITS;
-		const sequences = this.#pendingTransmits;
-		this.#pendingTransmits = [];
+		if (this.#pendingTransmits.size === 0) return EMPTY_TRANSMITS;
+		const sequences = [...this.#pendingTransmits.values()];
+		this.#pendingTransmits.clear();
 		return sequences;
 	}
 
@@ -433,9 +438,9 @@ export class ImageBudget {
 	 * re-emit together; keeps no base64 in budget state (the transmit-once design).
 	 */
 	forgetTransmitted(): void {
-		if (this.#transmitted.size === 0 && this.#pendingTransmits.length === 0) return;
+		if (this.#transmitted.size === 0 && this.#pendingTransmits.size === 0) return;
 		this.#transmitted.clear();
-		this.#pendingTransmits = [];
+		this.#pendingTransmits.clear();
 	}
 
 	#forgetKeyForId(id: number): void {
@@ -445,15 +450,16 @@ export class ImageBudget {
 		if (this.#keyToId.get(key) === id) this.#keyToId.delete(key);
 	}
 
-	#reconcile(total: number): void {
+	#reconcile(total: number): boolean {
 		const desired = this.#cap > 0 ? Math.max(0, total - this.#cap) : 0;
 		if (desired === this.#planned) {
 			// Budget relaxed without a stricter frame (cap raised or images
 			// removed): surviving graphics are untouched and re-exposed rows
 			// repaint normally, so just track the looser threshold.
 			if (this.#planned < this.#onTerminal) this.#onTerminal = this.#planned;
-			return;
+			return false;
 		}
+		const retry = desired > this.#onTerminal;
 		this.#planned = desired;
 		// More images must be demoted than the terminal shows: schedule the purge +
 		// full-redraw frame. Fewer: no ghosts to clear, so just catch the tracking
@@ -461,6 +467,7 @@ export class ImageBudget {
 		// render is needed to apply the new threshold.
 		if (desired <= this.#onTerminal) this.#onTerminal = desired;
 		this.#requestRender();
+		return retry;
 	}
 }