@oh-my-pi/pi-tui 18.9.0 → 18.9.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.9.2] - 2026-10-11
+
+### Added
+
+- Added native TSP rendering support for Tern terminal sessions running inside tmux, with automatic session detection and safe title-setting behavior.
+
+### Fixed
+
+- Improved responsiveness when inserting assistant messages after tool calls in long transcripts.
+
+## [18.9.1] - 2026-10-11
+
+### Fixed
+
+- Fixed inline charts and images leaving overlapping copies over text when moved, resized, replaced, or hidden, while preserving images in scrollback.
+
 ## [18.9.0] - 2026-10-11
 
 ### Added

package/dist/types/chrome/transcript-container.d.ts

@@ -63,6 +63,11 @@ export interface TranscriptViewportSpan {
 export declare class TranscriptContainer extends Container {
     #private;
     addChild(component: Component): void;
+    /**
+     * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+     * pays a full O(n) rebuild.
+     */
+    insertChildAt(component: Component, index: number): void;
     /** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
     removeChild(component: Component): void;
     clear(): void;

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

@@ -149,50 +149,8 @@ export declare class ImageBudget {
      * the image is purged from the terminal store.
      */
     registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void;
-    /**
-     * Record this frame's native-scrollback commit target (the frame-row count
-     * that is committed once the frame's writes land). Called once per rendered
-     * frame — including frames that emit no placements — so an epoch whose rows
-     * commit while its line is never rewritten is still flagged before the next
-     * re-emission.
-     */
-    observeCommitWatermark(committedTo: number): void;
-    /**
-     * End the physical-row coordinate epoch after observing its final commit
-     * watermark. Placement ids and latched archive state survive, but attachment
-     * rows do not: the next placement emit records them in the new-width frame.
-     */
-    beginPlacementCoordinateEpoch(): void;
-    /**
-     * Resolve the placement id and geometry for a direct-placement emit whose
-     * topmost attached cell sits at `attachTopFrameRow` — the first frame row
-     * the placement covers, i.e. the block's first *visible* row, not its
-     * origin (-1 when the writer has no frame-space position: alt-screen,
-     * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
-     * target in the same frame-row space (-1 when unknown).
-     *
-     * Invariant: a placement id may be re-used (Kitty replace strips that id's
-     * cells everywhere, scrollback included) only while none of the cells it
-     * attached have entered native scrollback. The epoch — the `p=` id —
-     * advances exactly when the archived flag says otherwise; rewrites with no
-     * commit progression keep replacing the same id in place.
-     */
-    resolvePlacementEmit(imageId: number, attachTopFrameRow: number, committedTo: number): {
-        placementId: number;
-        widthPx: number;
-        heightPx: number;
-    } | null;
-    /**
-     * Restart every placement epoch after a destructive history clear (`CSI 3 J`
-     * full paint). The clear destroys all placement cells — scrollback rows are
-     * gone and the replay rewrites the viewport — so no archive remains to
-     * protect. Reverting to epoch 1 lets the replay recreate every visible
-     * placement after the terminal-wide cleanup.
-     */
-    resetPlacementEpochs(): ReadonlyArray<{
-        imageId: number;
-        lastEpoch: number;
-    }>;
+    /** Source dimensions used by the frame writer to clip a direct placement. */
+    getPlacementGeometry(imageId: number): ImageDimensions | undefined;
     /**
      * Queue a one-time transmit for `imageId` on the surface the in-flight pass
      * paints. No-op if that surface already holds the data, so a repeated call

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

@@ -323,7 +323,7 @@ export interface ParsedKittyPlacementLine {
 /**
  * Parse a frame line that consists solely of a Kitty direct placement (the
  * last line of an {@link Image} block). Returns null for anything else —
- * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * placeholder grids, sixel/iTerm2 payloads — so
  * callers fall back to writing the line verbatim.
  */
 export declare function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null;
@@ -363,8 +363,8 @@ export declare function encodeKittyDeleteAllImages(): string;
 /**
  * Delete a single placement of an image (`d=i`, lowercase): removes its cells
  * and registry entry but keeps the transmitted data, so a later `a=p` under a
- * fresh placement id needs no retransmit. Used to clear stale placement-epoch
- * entries after a destructive history clear.
+ * fresh placement id needs no retransmit. The frame writer uses this before
+ * replacing a live image without deleting its archived copies.
  */
 export declare function encodeKittyDeletePlacement(imageId: number, placementId: number): string;
 export declare function encodeITerm2(base64Data: string, options?: {

package/dist/types/tmux.d.ts

@@ -1,6 +1,16 @@
 export { wrapTmuxPassthrough } from "./multiplexers/tmux.js";
 /** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
 export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether the terminal hosting this tmux session draws TSP programs natively:
+ * it sets the session user option `@tern-tsp` while it watches the session.
+ */
+export declare function tmuxSessionSpeaksTsp(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Stop (`on` false) or restore (`on` true) tmux turning this pane's APC
+ * strings into its title, which would otherwise swallow every TSP message.
+ */
+export declare function setTmuxPaneApcTitles(on: boolean, env?: NodeJS.ProcessEnv): void;
 /**
  * Resolve the terminal emulator name recorded for this tmux client.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.9.0",
+	"version": "18.9.2",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -41,14 +41,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.9.0",
-		"@oh-my-pi/pi-agent-core": "18.9.0",
-		"@oh-my-pi/pi-ai": "18.9.0",
-		"@oh-my-pi/pi-catalog": "18.9.0",
-		"@oh-my-pi/pi-natives": "18.9.0",
-		"@oh-my-pi/pi-utils": "18.9.0",
-		"@oh-my-pi/pi-wire": "18.9.0",
-		"@oh-my-pi/snapcompact": "18.9.0"
+		"@oh-my-pi/omptype": "18.9.2",
+		"@oh-my-pi/pi-agent-core": "18.9.2",
+		"@oh-my-pi/pi-ai": "18.9.2",
+		"@oh-my-pi/pi-catalog": "18.9.2",
+		"@oh-my-pi/pi-natives": "18.9.2",
+		"@oh-my-pi/pi-utils": "18.9.2",
+		"@oh-my-pi/pi-wire": "18.9.2",
+		"@oh-my-pi/snapcompact": "18.9.2"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"

package/src/chrome/transcript-container.ts

@@ -227,11 +227,31 @@ export class TranscriptContainer extends Container {
 			emitted: 0,
 			stableFrozen: false,
 		});
-		// Callers may splice a just-added block into place (insert after an
-		// anchor); re-check the whole list once instead of trusting positions.
+		// `children` is public and may be edited externally; re-check the whole
+		// list once instead of trusting positions. Insert-after-anchor callers
+		// use insertChildAt, which keeps both arrays in lockstep.
 		this.#entriesUnverified = true;
 	}
 
+	/**
+	 * `#entries` mirrors `children`; move both together or the next `#syncEntries`
+	 * pays a full O(n) rebuild.
+	 */
+	insertChildAt(component: Component, index: number): void {
+		this.addChild(component);
+		const from = this.children.length - 1;
+		if (index >= from) {
+			this.#entriesUnverified = false;
+			return;
+		}
+		const [moved] = this.children.splice(from, 1);
+		if (moved) this.children.splice(index, 0, moved);
+		const [entry] = this.#entries.splice(this.#entries.length - 1, 1);
+		if (entry) this.#entries.splice(index, 0, entry);
+		// Both arrays moved in lockstep, so the live-tail check applies again.
+		this.#entriesUnverified = false;
+	}
+
 	/** Removes `component` if {@link canRemoveBlock} allows it; otherwise does nothing. */
 	override removeChild(component: Component): void {
 		const index = this.#removableIndex(component);

package/src/components/image.ts

@@ -57,7 +57,6 @@ export function renderForScrollback<T>(render: () => T): T {
 
 const EMPTY_IDS: readonly number[] = [];
 const EMPTY_TRANSMITS: readonly string[] = [];
-const EMPTY_STALE_EPOCHS: ReadonlyArray<{ imageId: number; lastEpoch: number }> = [];
 const SAVE_CURSOR = "\x1b7";
 const RESTORE_CURSOR = "\x1b8";
 // Direct placements reserve height with leading zero-width rows. Keep them
@@ -72,25 +71,6 @@ export function imageMaxColumns(width: number): number {
 /** Default count of inline images kept as live graphics before older ones fall back to text. */
 export const DEFAULT_MAX_INLINE_IMAGES = 8;
 
-/** Per-image direct-placement emit state tracked by {@link ImageBudget}. */
-interface PlacementEmitState {
-	widthPx: number;
-	heightPx: number;
-	/** Current placement-id (`p=`) generation. */
-	epoch: number;
-	/** First frame row the current epoch's last emit attached cells to. */
-	lastAttachTopFrameRow: number | undefined;
-	/**
-	 * Whether any cell attached by the current epoch's last emit has entered
-	 * native scrollback. Set by {@link ImageBudget.observeCommitWatermark}
-	 * comparing each frame's raw commit target against the attach top —
-	 * era-local comparisons, so a divergence recommit that rewinds and
-	 * re-advances the ledger is detected the moment it re-crosses the attach
-	 * top, and a stale pre-rewind peak can never re-trigger.
-	 */
-	cellsArchived: boolean;
-}
-
 /** A surface the renderer paints frames on. */
 type Surface = "screen" | "alt";
 const SURFACES: readonly Surface[] = ["screen", "alt"];
@@ -222,22 +202,8 @@ export class ImageBudget {
 	 * fullscreen overlay keeps its placements and is restored from cache on exit.
 	 */
 	#liveIds: Record<Surface, Set<number>> = { screen: new Set(), alt: new Set() };
-	/**
-	 * Per-image direct-placement emit state: source pixel geometry for the
-	 * renderer's clipped source rectangle, plus the placement-id epoch (see
-	 * {@link resolvePlacementEmit}). Entries deliberately live as long as the
-	 * terminal's own placement registry for the image — they are the ledger the
-	 * destructive-clear sweep uses to delete every registry entry an image ever
-	 * placed — and die with it on demotion purge (`d=I`) or full cleanup.
-	 */
-	#placementState = new Map<number, PlacementEmitState>();
-	/**
-	 * States with an un-archived live attach top — the only ones a frame's
-	 * commit watermark can affect. {@link observeCommitWatermark} runs every
-	 * rendered frame, so it scans this set (bounded by concurrently live
-	 * placements) instead of every image ever registered.
-	 */
-	#watchedPlacements = new Set<PlacementEmitState>();
+	/** Source pixel dimensions for clipping direct placements at the viewport edge. */
+	#placementGeometry = new Map<number, ImageDimensions>();
 	/** Ids whose owner replaced them for good ({@link release}); retired once no frame shows them. */
 	#released = new Set<number>();
 
@@ -480,7 +446,7 @@ export class ImageBudget {
 		// terminal, so cancel it instead of transmitting then purging.
 		if (!this.#pendingTransmits[this.#surface].delete(imageId)) this.#purgeIds.push(imageId);
 		this.#transmitted[this.#surface].delete(imageId);
-		if (!this.#isTransmitted(imageId)) this.#deletePlacementState(imageId);
+		if (!this.#isTransmitted(imageId)) this.#placementGeometry.delete(imageId);
 		this.#forgetKeyForId(imageId);
 		return true;
 	}
@@ -523,8 +489,7 @@ export class ImageBudget {
 		this.#resetPurgeIds = [];
 		this.#keyToId.clear();
 		this.#idToKey.clear();
-		this.#placementState.clear();
-		this.#watchedPlacements.clear();
+		this.#placementGeometry.clear();
 		this.#released.clear();
 		for (const surface of SURFACES) this.#liveIds[surface].clear();
 		return [...ids];
@@ -541,115 +506,18 @@ export class ImageBudget {
 	 * the image is purged from the terminal store.
 	 */
 	registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void {
-		const state = this.#placementState.get(imageId);
-		if (state) {
-			state.widthPx = widthPx;
-			state.heightPx = heightPx;
-			return;
-		}
-		this.#placementState.set(imageId, {
-			widthPx,
-			heightPx,
-			epoch: 1,
-			lastAttachTopFrameRow: undefined,
-			cellsArchived: false,
-		});
-	}
-
-	/**
-	 * Record this frame's native-scrollback commit target (the frame-row count
-	 * that is committed once the frame's writes land). Called once per rendered
-	 * frame — including frames that emit no placements — so an epoch whose rows
-	 * commit while its line is never rewritten is still flagged before the next
-	 * re-emission.
-	 */
-	observeCommitWatermark(committedTo: number): void {
-		if (committedTo < 0 || this.#watchedPlacements.size === 0) return;
-		for (const state of this.#watchedPlacements) {
-			if (state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
-				// Latched: the flag only clears when the next emit consumes it,
-				// so the state needs no further per-frame scans until then.
-				state.cellsArchived = true;
-				this.#watchedPlacements.delete(state);
-			}
-		}
-	}
-
-	/**
-	 * End the physical-row coordinate epoch after observing its final commit
-	 * watermark. Placement ids and latched archive state survive, but attachment
-	 * rows do not: the next placement emit records them in the new-width frame.
-	 */
-	beginPlacementCoordinateEpoch(): void {
-		for (const state of this.#placementState.values()) state.lastAttachTopFrameRow = undefined;
-		this.#watchedPlacements.clear();
-	}
-
-	/**
-	 * Resolve the placement id and geometry for a direct-placement emit whose
-	 * topmost attached cell sits at `attachTopFrameRow` — the first frame row
-	 * the placement covers, i.e. the block's first *visible* row, not its
-	 * origin (-1 when the writer has no frame-space position: alt-screen,
-	 * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
-	 * target in the same frame-row space (-1 when unknown).
-	 *
-	 * Invariant: a placement id may be re-used (Kitty replace strips that id's
-	 * cells everywhere, scrollback included) only while none of the cells it
-	 * attached have entered native scrollback. The epoch — the `p=` id —
-	 * advances exactly when the archived flag says otherwise; rewrites with no
-	 * commit progression keep replacing the same id in place.
-	 */
-	resolvePlacementEmit(
-		imageId: number,
-		attachTopFrameRow: number,
-		committedTo: number,
-	): { placementId: number; widthPx: number; heightPx: number } | null {
-		const state = this.#placementState.get(imageId);
-		if (!state) return null;
-		// Frames that commit as they write (seam/full-paint chunk passes) pass
-		// their own commit target; fold it in before deciding, so a commit that
-		// lands in the same frame as the re-emission still advances the epoch.
-		if (committedTo >= 0 && state.lastAttachTopFrameRow !== undefined && committedTo > state.lastAttachTopFrameRow) {
-			state.cellsArchived = true;
-			this.#watchedPlacements.delete(state);
-		}
-		if (state.cellsArchived) {
-			state.epoch += 1;
-			state.cellsArchived = false;
-			state.lastAttachTopFrameRow = undefined;
-		}
-		if (attachTopFrameRow >= 0) {
-			state.lastAttachTopFrameRow = attachTopFrameRow;
-			this.#watchedPlacements.add(state);
-		}
-		return { placementId: state.epoch, widthPx: state.widthPx, heightPx: state.heightPx };
-	}
-
-	/**
-	 * Restart every placement epoch after a destructive history clear (`CSI 3 J`
-	 * full paint). The clear destroys all placement cells — scrollback rows are
-	 * gone and the replay rewrites the viewport — so no archive remains to
-	 * protect. Reverting to epoch 1 lets the replay recreate every visible
-	 * placement after the terminal-wide cleanup.
-	 */
-	resetPlacementEpochs(): ReadonlyArray<{ imageId: number; lastEpoch: number }> {
-		let stale: Array<{ imageId: number; lastEpoch: number }> | undefined;
-		for (const [imageId, state] of this.#placementState) {
-			stale ??= [];
-			stale.push({ imageId, lastEpoch: state.epoch });
-			state.epoch = 1;
-			state.lastAttachTopFrameRow = undefined;
-			state.cellsArchived = false;
+		const geometry = this.#placementGeometry.get(imageId);
+		if (geometry) {
+			geometry.widthPx = widthPx;
+			geometry.heightPx = heightPx;
+		} else {
+			this.#placementGeometry.set(imageId, { widthPx, heightPx });
 		}
-		this.#watchedPlacements.clear();
-		return stale ?? EMPTY_STALE_EPOCHS;
 	}
 
-	#deletePlacementState(imageId: number): void {
-		const state = this.#placementState.get(imageId);
-		if (!state) return;
-		this.#watchedPlacements.delete(state);
-		this.#placementState.delete(imageId);
+	/** Source dimensions used by the frame writer to clip a direct placement. */
+	getPlacementGeometry(imageId: number): ImageDimensions | undefined {
+		return this.#placementGeometry.get(imageId);
 	}
 
 	/**

package/src/render/composite.ts

@@ -11,6 +11,8 @@ export function compositeLineAt(
 	overlayWidth: number,
 	totalWidth: number,
 ): string {
+	// A full-width image row owns its terminal row; the writer must see its exact placement shape.
+	if (startCol === 0 && overlayWidth >= totalWidth && TERMINAL.isImageLine(overlayLine)) return overlayLine;
 	if (TERMINAL.isImageLine(baseLine)) {
 		// Full-width overlays such as /switch are opaque: replace the
 		// Unicode placeholder cells so the image cannot cover the modal.

package/src/terminal-capabilities.ts

@@ -917,8 +917,7 @@ export function encodeKittyPlacement(options: {
 /**
  * Exact shape of the direct-placement line {@link Image} emits as its block's
  * last row: optional `ESC 7` + `CUU(rows-1)` prefix, the {@link encodeKittyPlacement}
- * APC, optional `ESC 8` suffix. tmux-passthrough-wrapped lines deliberately do
- * not match (passthrough placements stay untouched).
+ * APC, optional `ESC 8` suffix. The parser unwraps tmux passthrough first.
  */
 const KITTY_DIRECT_PLACEMENT_LINE =
 	/^(?:\x1b7(?:\x1b\[(\d+)A)?)?\x1b_Ga=p,q=2,C=1,i=(\d+)(?:,p=(\d+))?(?:,c=(\d+))?(?:,r=(\d+))?\x1b\\(?:\x1b8)?$/;
@@ -933,10 +932,15 @@ export interface ParsedKittyPlacementLine {
 /**
  * Parse a frame line that consists solely of a Kitty direct placement (the
  * last line of an {@link Image} block). Returns null for anything else —
- * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * placeholder grids, sixel/iTerm2 payloads — so
  * callers fall back to writing the line verbatim.
  */
 export function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null {
+	if (line.includes("\x1bPtmux;")) {
+		line = line.replace(/\x1bPtmux;((?:[^\x1b]|\x1b\x1b)*)\x1b\\/g, (_match, payload: string) =>
+			payload.replaceAll("\x1b\x1b", "\x1b"),
+		);
+	}
 	const m = KITTY_DIRECT_PLACEMENT_LINE.exec(line);
 	if (!m) return null;
 	const columns = m[4] !== undefined ? Number(m[4]) : 0;
@@ -981,9 +985,7 @@ export function encodeKittyPlacementLine(options: {
 		const srcY = Math.floor((options.imageHeightPx * hiddenRows) / options.rows);
 		params.push(`y=${srcY}`, `h=${Math.max(1, options.imageHeightPx - srcY)}`);
 	}
-	// No tmux passthrough: inside tmux the component's own line arrives
-	// wrapped, never parses, and never reaches this rewrite.
-	const apc = `\x1b_G${params.join(",")}\x1b\\`;
+	const apc = wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 	const cuu = visibleRows - 1;
 	return cuu > 0 ? `\x1b7\x1b[${cuu}A${apc}\x1b8` : apc;
 }
@@ -1010,8 +1012,8 @@ export function encodeKittyDeleteAllImages(): string {
 /**
  * Delete a single placement of an image (`d=i`, lowercase): removes its cells
  * and registry entry but keeps the transmitted data, so a later `a=p` under a
- * fresh placement id needs no retransmit. Used to clear stale placement-epoch
- * entries after a destructive history clear.
+ * fresh placement id needs no retransmit. The frame writer uses this before
+ * replacing a live image without deleting its archived copies.
  */
 export function encodeKittyDeletePlacement(imageId: number, placementId: number): string {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=i,i=${imageId},p=${placementId},q=2\x1b\\`);

package/src/terminal.ts

@@ -28,8 +28,10 @@ import {
 	setTerminalGlyphProtocol,
 	TERMINAL,
 } from "./terminal-capabilities";
+import { tmuxMultiplexer } from "./multiplexers/tmux";
 import type { TerminalMultiplexerBackgroundColorCache } from "./multiplexers/types";
 import { terminalMultiplexerSessions } from "./terminal-multiplexer";
+import { setTmuxPaneApcTitles, tmuxSessionSpeaksTsp } from "./tmux";
 import { setHangulCompatibilityJamoWidth } from "./utils";
 import { translateWindowsAltGrSequence } from "./windows-altgr";
 import { Win32InputModeDecoder, Win32PasteMarkerNormalizer } from "./windows-input-mode";
@@ -50,6 +52,9 @@ const WIN32_RELAYED_ESCAPE_TIMEOUT_MS = 75;
  */
 const TSP_OSC_PREFIX = `\x1b]877;${TSP_PREFIX.slice(2)}`;
 
+/** How long a TSP hello waits for its reply inside tmux, which answers DA1 itself. */
+const TSP_TMUX_HELLO_TIMEOUT_MS = 1000;
+
 /**
  * The TSP message a reassembled input string holds, in APC form, or
  * `undefined` while its terminator has not arrived. An OSC 877 message may end
@@ -874,6 +879,10 @@ export class ProcessTerminal implements Terminal {
 	#tspPending = false;
 	#tspResult: TspHello | null | undefined;
 	#tspCallbacks: TspHelloHandler[] = [];
+	/** Hello deadline inside tmux, where no DA1 sentinel can end the probe. */
+	#tspTimeout: NodeJS.Timeout | undefined;
+	/** This tmux pane's APC titles are off for TSP and must be restored. */
+	#tspTmuxPaneGated = false;
 	#tspReplyBuffer = "";
 	#privateCsiResponseBuffer = "";
 	#da1SentinelOwners: Da1SentinelOwner[] = [];
@@ -1831,6 +1840,9 @@ export class ProcessTerminal implements Terminal {
 	#shouldQueryTspSupport(): boolean {
 		const override = $env.PI_TUI_NATIVE;
 		if (override === "0") return false;
+		// tmux makes APC bodies the pane title unless the hosting terminal asked
+		// for TSP through `@tern-tsp`: no override may force the probe there.
+		if (tmuxMultiplexer.isInside($env)) return tmuxSessionSpeaksTsp($env);
 		if (override === "1") return true;
 		// Multiplexers swallow APC, so the reply could never arrive.
 		if (isInsideTerminalMultiplexer($env)) return false;
@@ -1848,10 +1860,30 @@ export class ProcessTerminal implements Terminal {
 			return;
 		}
 		this.#tspPending = true;
+		if (tmuxMultiplexer.isInside($env)) {
+			// tmux answers DA1 itself, ahead of any reply: wait for the reply instead.
+			this.#tspTmuxPaneGated = true;
+			setTmuxPaneApcTitles(false, $env);
+			this.#tspTimeout = setTimeout(() => {
+				this.#tspTimeout = undefined;
+				this.#resolveTspSupport(null);
+			}, TSP_TMUX_HELLO_TIMEOUT_MS);
+			this.#safeWrite(encodeTspHelloQuery());
+			return;
+		}
 		this.#da1SentinelOwners.push({ kind: "tsp" });
 		this.#safeWrite(`${encodeTspHelloQuery()}\x1b[c`);
 	}
 
+	/** Hand APC titles back to tmux once this pane stops speaking TSP. */
+	#endTspTmuxPane(): void {
+		clearTimeout(this.#tspTimeout);
+		this.#tspTimeout = undefined;
+		if (!this.#tspTmuxPaneGated) return;
+		this.#tspTmuxPaneGated = false;
+		setTmuxPaneApcTitles(true, $env);
+	}
+
 	#handleTspMessage(sequence: string): void {
 		const message = parseTspMessage(sequence);
 		if (message?.verb === "r" && message.reply.r === "hello") {
@@ -1867,6 +1899,12 @@ export class ProcessTerminal implements Terminal {
 		this.#tspPending = false;
 		const result = hello !== null && hello.v === TSP_VERSION ? hello : null;
 		if (hello !== null && result === null) logger.warn("TSP: unsupported protocol version", { v: hello.v });
+		if (result === null) {
+			this.#endTspTmuxPane();
+		} else {
+			clearTimeout(this.#tspTimeout);
+			this.#tspTimeout = undefined;
+		}
 		this.#tspResult = result;
 		for (const cb of this.#tspCallbacks) {
 			try {
@@ -2255,6 +2293,7 @@ export class ProcessTerminal implements Terminal {
 		this.#sixelSupportCallbacks = [];
 		setTerminalGlyphProtocol(false);
 		this.#tspPending = false;
+		this.#endTspTmuxPane();
 		this.#tspResult = undefined;
 		this.#tspReplyBuffer = "";
 		this.#tspCallbacks = [];

package/src/tmux.ts

@@ -31,6 +31,49 @@ function queryTmuxClientTerminalName(env: NodeJS.ProcessEnv): string | null {
 	}
 }
 
+const TMUX_COMMAND_TIMEOUT_MS = 500;
+
+/** Run a tmux command against the current server; its stdout, or null on failure. */
+function runTmux(args: string[], env: NodeJS.ProcessEnv): string | null {
+	const tmux = $which("tmux", { PATH: env.PATH });
+	if (!tmux) return null;
+	try {
+		const result = Bun.spawnSync([tmux, ...args], {
+			env,
+			stdout: "pipe",
+			stderr: "ignore",
+			timeout: TMUX_COMMAND_TIMEOUT_MS,
+			killSignal: "SIGKILL",
+		});
+		return result.exitCode === 0 ? result.stdout.toString() : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether the terminal hosting this tmux session draws TSP programs natively:
+ * it sets the session user option `@tern-tsp` while it watches the session.
+ */
+export function tmuxSessionSpeaksTsp(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return (runTmux(["show-options", "-qv", "@tern-tsp"], env)?.trim() ?? "") !== "";
+}
+
+/**
+ * Stop (`on` false) or restore (`on` true) tmux turning this pane's APC
+ * strings into its title, which would otherwise swallow every TSP message.
+ */
+export function setTmuxPaneApcTitles(on: boolean, env: NodeJS.ProcessEnv = Bun.env): void {
+	const pane = env.TMUX_PANE;
+	if (!pane) return;
+	runTmux(
+		on
+			? ["set-option", "-pu", "-t", pane, "allow-set-title"]
+			: ["set-option", "-p", "-t", pane, "allow-set-title", "off"],
+		env,
+	);
+}
+
 /**
  * Resolve the terminal emulator name recorded for this tmux client.
  *

package/src/tui.ts

@@ -33,6 +33,7 @@ import { classifyTerminalMultiplexerModule, terminalMultiplexerSessions } from "
 import {
 	encodeKittyDeleteAllImages,
 	encodeKittyDeleteImage,
+	encodeKittyDeletePlacement,
 	encodeKittyPlacementLine,
 	ImageProtocol,
 	isImageProtocolForced,
@@ -642,6 +643,13 @@ interface HardwareCursorState {
 	visible: boolean;
 }
 
+/** A cursor-positioned image owned by a mutable viewport, never by history. */
+interface LiveImagePlacement {
+	imageId: number;
+	placementId: number;
+	line: string;
+}
+
 interface PreparedLine {
 	raw: string;
 	width: number;
@@ -981,6 +989,9 @@ export class TUI extends Container {
 	// Caps how many inline images render as live graphics; older ones fall back
 	// to text via a purge + full redraw. Cap is configured by the host app.
 	#imageBudget = new ImageBudget(DEFAULT_MAX_INLINE_IMAGES, () => this.requestRender());
+	#screenImagePlacements = new Map<number, LiveImagePlacement>();
+	#altImagePlacements = new Map<number, LiveImagePlacement>();
+	#nextImagePlacementId = 1;
 	#ghosttyInitialImageDelayDone = false;
 	#ghosttyInitialImageDelayTimer: RenderTimer | undefined;
 	#ghosttyImageReadyAtMs = 0;
@@ -1162,6 +1173,8 @@ export class TUI extends Container {
 
 	#purgeInlineImages(): void {
 		const transmittedIds = this.#imageBudget.takeAllTransmittedIds();
+		this.#screenImagePlacements.clear();
+		this.#altImagePlacements.clear();
 		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return;
 		for (const id of transmittedIds) {
 			this.terminal.write(encodeKittyDeleteImage(id));
@@ -3148,34 +3161,49 @@ export class TUI extends Container {
 	}
 
 	/**
-	 * Rewrite a Kitty direct-placement line for the viewport row it is written
-	 * at, clipping to the visible slice (see {@link encodeKittyPlacementLine})
-	 * under the placement id resolved by the budget's epoch tracking (see
-	 * {@link ImageBudget.resolvePlacementEmit}). `screenRow` -1 (write position
-	 * unknown) and non-placement image lines (placeholder grids, sixel, iTerm2,
-	 * tmux-wrapped) pass through verbatim.
+	 * Remove placements before their viewport cells are replaced. History uses
+	 * separate placement ids, so deleting a live copy cannot erase scrollback.
 	 */
-	#imageLineSequence(line: string, screenRow: number, frameRow: number, committedTo: number): string {
+	#retireImagePlacements(
+		placements: Map<number, LiveImagePlacement>,
+		lines: readonly string[],
+		top: number,
+		repaint: boolean,
+	): string {
+		let output = "";
+		for (const [row, placement] of placements) {
+			if (!repaint && lines[row - top] === placement.line) continue;
+			output += encodeKittyDeletePlacement(placement.imageId, placement.placementId);
+			placements.delete(row);
+		}
+		return output;
+	}
+
+	/** Clip a direct placement and record its live owner; history placements have no mutable owner. */
+	#imageLineSequence(
+		line: string,
+		screenRow: number,
+		placements: Map<number, LiveImagePlacement> | undefined,
+		placementRow: number,
+	): string {
 		if (screenRow < 0) return line;
 		const parsed = parseKittyDirectPlacementLine(line);
 		if (!parsed) return line;
-		// The emitted placement attaches from the block's first *visible* row
-		// (the clip drops the rows above the viewport), so epoch tracking keys
-		// on that row — not the block origin, which may be long committed.
-		const placement = this.#imageBudget.resolvePlacementEmit(
-			parsed.imageId,
-			frameRow >= 0 ? frameRow - Math.min(parsed.rows - 1, screenRow) : -1,
-			committedTo,
+		const previous = placements?.get(placementRow);
+		const placementId = previous?.placementId ?? this.#nextImagePlacementId++;
+		const erase = previous ? encodeKittyDeletePlacement(previous.imageId, previous.placementId) : "";
+		placements?.set(placementRow, { imageId: parsed.imageId, placementId, line });
+		return (
+			erase +
+			encodeKittyPlacementLine({
+				imageId: parsed.imageId,
+				placementId,
+				columns: parsed.columns,
+				rows: parsed.rows,
+				screenRow,
+				imageHeightPx: this.#imageBudget.getPlacementGeometry(parsed.imageId)?.heightPx ?? 0,
+			})
 		);
-		if (!placement) return line;
-		return encodeKittyPlacementLine({
-			imageId: parsed.imageId,
-			placementId: placement.placementId,
-			columns: parsed.columns,
-			rows: parsed.rows,
-			screenRow,
-			imageHeightPx: placement.heightPx,
-		});
 	}
 
 	#terminalLine(line: PreparedLine): string {
@@ -3449,7 +3477,7 @@ export class TUI extends Container {
 			// reset forgot are named explicitly here — their tracking is gone, so
 			// nothing downstream could find them again.
 			for (const id of this.#imageBudget.takeResetPurgeIds()) buffer += encodeKittyDeleteImage(id);
-			this.#imageBudget.resetPlacementEpochs();
+			this.#screenImagePlacements.clear();
 		}
 		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
 			for (const id of this.#imageBudget.takePurgeIds()) buffer += encodeKittyDeleteImage(id);
@@ -3472,7 +3500,6 @@ export class TUI extends Container {
 		// image the terminal no longer had and every inline image vanished
 		// after a settled width resize.
 		if (destructiveReset) buffer += `${LINE_TERMINATOR}\x1b[H\x1b[2J\x1b[3J`;
-		for (const sequence of this.#imageBudget.takeTransmits()) append(sequence);
 		const diffable =
 			geometryStable &&
 			historyRows.length === 0 &&
@@ -3480,6 +3507,8 @@ export class TUI extends Container {
 			!this.#forceViewportRepaintOnNextRender &&
 			!destructiveReset &&
 			this.#providerWindow.length > 0;
+		buffer += this.#retireImagePlacements(this.#screenImagePlacements, prepared.lines, newTop, !diffable);
+		for (const sequence of this.#imageBudget.takeTransmits()) append(sequence);
 		if (diffable) {
 			for (let index = 0; index < rows; index++) {
 				if (
@@ -3498,9 +3527,8 @@ export class TUI extends Container {
 					current,
 					width,
 					newTop + index,
-					-1,
-					-1,
 					this.#osc66SpacerGlyphWidth(prepared.lines, index),
+					{ imagePlacements: this.#screenImagePlacements },
 				)}`;
 			}
 			if (this.#providerWindow.length > rows && newTop + rows < height) {
@@ -3525,8 +3553,6 @@ export class TUI extends Container {
 						preparedHistory.rows[index]!,
 						width,
 						Math.min(screenRow, height - 1),
-						-1,
-						-1,
 						this.#osc66SpacerGlyphWidth(preparedHistory.lines, index),
 						{ blankRow: compactReplay },
 					),
@@ -3540,10 +3566,12 @@ export class TUI extends Container {
 						prepared.rows[index]!,
 						width,
 						Math.min(screenRow, height - 1),
-						-1,
-						-1,
 						this.#osc66SpacerGlyphWidth(prepared.lines, index),
-						{ blankRow: compactReplay },
+						{
+							blankRow: compactReplay,
+							imagePlacements: index < replayViewportRows ? undefined : this.#screenImagePlacements,
+							imageRow: newTop + index,
+						},
 					),
 				);
 				screenRow++;
@@ -4164,10 +4192,8 @@ export class TUI extends Container {
 		line: PreparedLine,
 		width: number,
 		screenRow = -1,
-		frameRow = -1,
-		committedTo = -1,
 		spacerGlyphWidth = -1,
-		options?: { blankRow?: boolean },
+		options?: { blankRow?: boolean; imagePlacements?: Map<number, LiveImagePlacement>; imageRow?: number },
 	): string {
 		// End every rewrite at column zero. ConPTY can materialize a pending
 		// wrap before a following cursor-addressing sequence even while DECAWM is
@@ -4184,7 +4210,9 @@ export class TUI extends Container {
 		if (spacerGlyphWidth >= 0) {
 			rewrite = spacerGlyphWidth >= width ? "" : `${SEGMENT_RESET}\x1b[${spacerGlyphWidth}C${ERASE_TO_END_OF_LINE}`;
 		} else if (line.isImage) {
-			rewrite = ERASE_LINE + this.#imageLineSequence(line.line, screenRow, frameRow, committedTo);
+			rewrite =
+				ERASE_LINE +
+				this.#imageLineSequence(line.line, screenRow, options?.imagePlacements, options?.imageRow ?? screenRow);
 		} else {
 			const terminalLine = this.#terminalLine(line);
 			if (options?.blankRow) {
@@ -4331,6 +4359,7 @@ export class TUI extends Container {
 				prepared.rows.some((_row, r) =>
 					this.#rowNeedsRewrite(this.#altPreviousLines, this.#altPreparedRows, prepared.lines, prepared.rows, r),
 				));
+		prelude += this.#retireImagePlacements(this.#altImagePlacements, prepared.lines, 0, full);
 		let rowsBuffer = "";
 		for (let r = 0; r < height; r++) {
 			if (full) {
@@ -4346,9 +4375,8 @@ export class TUI extends Container {
 				prepared.rows[r]!,
 				width,
 				r,
-				-1,
-				-1,
 				this.#osc66SpacerGlyphWidth(prepared.lines, r),
+				{ imagePlacements: this.#altImagePlacements },
 			);
 		}
 		this.#altPreviousLines = prepared.lines;