@oh-my-pi/pi-coding-agent 15.9.1 → 15.9.5

package/src/internal-urls/omp-protocol.ts

@@ -64,9 +64,15 @@ export class OmpProtocolHandler implements ProtocolHandler {
 			throw new Error("Path traversal (..) is not allowed in omp:// URLs");
 		}
 
-		const content = EMBEDDED_DOCS[normalized];
+		const docPath =
+			normalized === "docs" ? "" : normalized.startsWith("docs/") ? normalized.slice("docs/".length) : normalized;
+		if (!docPath) {
+			return this.#listDocs(url);
+		}
+
+		const content = EMBEDDED_DOCS[docPath];
 		if (content === undefined) {
-			const lookup = normalized.replace(/\.md$/, "");
+			const lookup = docPath.replace(/\.md$/, "");
 			const suggestions = EMBEDDED_DOC_FILENAMES.filter(
 				f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")),
 			).slice(0, 5);

package/src/main.ts

@@ -285,7 +285,13 @@ async function runInteractiveMode(
 		})
 		.catch(() => {});
 
-	mode.renderInitialMessages(undefined, { preserveExistingChat: true });
+	// Cold-launch cleanup: wipe the terminal scrollback before painting the
+	// resumed/new transcript. The TUI's initial paint deliberately preserves
+	// native scrollback (prior shell content), but on `omp`/`omp -c` that leaves
+	// the previous run's welcome + transcript stacked above the fresh one. Every
+	// in-process session load already clears via `clearTerminalHistory`; the cold
+	// launch is the lone path that did not.
+	mode.renderInitialMessages(undefined, { preserveExistingChat: true, clearTerminalHistory: true });
 
 	for (const notify of notifs) {
 		if (!notify) {

package/src/mcp/manager.ts

@@ -6,7 +6,7 @@
  */
 import * as path from "node:path";
 import * as url from "node:url";
-import type { TSchema } from "@oh-my-pi/pi-ai";
+import { isDefinitiveOAuthFailure, type TSchema } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { SourceMeta } from "../capability/types";
 import { resolveConfigValue } from "../config/resolve-config-value";
@@ -1184,29 +1184,48 @@ export class MCPManager {
 							await this.#authStorage.set(credentialId, refreshedCredential);
 							credential = refreshedCredential;
 						} catch (refreshError) {
-							logger.warn("MCP OAuth refresh failed, using existing token", {
-								credentialId,
-								error: refreshError,
-							});
+							const errorMsg = refreshError instanceof Error ? refreshError.message : String(refreshError);
+							if (isDefinitiveOAuthFailure(errorMsg)) {
+								// `invalid_grant` / `invalid_token` / 401 from the token endpoint means
+								// the server has retired this credential — keeping the stale access
+								// token would just re-fail with 401 on every MCP request and leave a
+								// poisoned row in agent.db that survives restarts. Drop it now so the
+								// next connect attempt surfaces a clean "needs reauth" failure and
+								// the user can recover with `/mcp reauth <server>` (or `/mcp unauth`
+								// to forget the server entirely).
+								logger.warn("MCP OAuth refresh failed definitively; cleared credential", {
+									credentialId,
+									error: errorMsg,
+								});
+								await this.#authStorage.remove(credentialId);
+								credential = undefined;
+							} else {
+								logger.warn("MCP OAuth refresh failed, using existing token", {
+									credentialId,
+									error: refreshError,
+								});
+							}
 						}
 					}
 
-					if (resolved.type === "http" || resolved.type === "sse") {
-						resolved = {
-							...resolved,
-							headers: {
-								...resolved.headers,
-								Authorization: `Bearer ${credential.access}`,
-							},
-						};
-					} else {
-						resolved = {
-							...resolved,
-							env: {
-								...resolved.env,
-								OAUTH_ACCESS_TOKEN: credential.access,
-							},
-						};
+					if (credential?.type === "oauth") {
+						if (resolved.type === "http" || resolved.type === "sse") {
+							resolved = {
+								...resolved,
+								headers: {
+									...resolved.headers,
+									Authorization: `Bearer ${credential.access}`,
+								},
+							};
+						} else {
+							resolved = {
+								...resolved,
+								env: {
+									...resolved.env,
+									OAUTH_ACCESS_TOKEN: credential.access,
+								},
+							};
+						}
 					}
 				}
 			} catch (error) {

package/src/modes/components/assistant-message.ts

@@ -17,6 +17,7 @@ export class AssistantMessageComponent extends Container {
 	#usageInfo?: Usage;
 	#convertedKittyImages = new Map<string, ImageContent>();
 	#kittyConversionsInFlight = new Set<string>();
+	#transcriptBlockFinalized: boolean;
 
 	constructor(
 		message?: AssistantMessage,
@@ -26,6 +27,7 @@ export class AssistantMessageComponent extends Container {
 		private readonly imageBudget?: ImageBudget,
 	) {
 		super();
+		this.#transcriptBlockFinalized = message !== undefined;
 
 		// Container for text/thinking content
 		this.#contentContainer = new Container();
@@ -47,6 +49,26 @@ export class AssistantMessageComponent extends Container {
 		this.hideThinkingBlock = hide;
 	}
 
+	isTranscriptBlockFinalized(): boolean {
+		return this.#transcriptBlockFinalized;
+	}
+
+	/**
+	 * Assistant text/thinking streams in append-only: earlier rendered rows never
+	 * re-layout, new content only grows the block at the bottom. The transcript
+	 * reports this so the renderer may commit scrolled-off head rows of a long
+	 * streamed reply to native scrollback instead of dropping them (see
+	 * `NativeScrollbackLiveRegion#getNativeScrollbackCommitSafeEnd`). Volatile
+	 * blocks (tool previews that collapse) intentionally do not implement this.
+	 */
+	isTranscriptBlockAppendOnly(): boolean {
+		return true;
+	}
+
+	markTranscriptBlockFinalized(): void {
+		this.#transcriptBlockFinalized = true;
+	}
+
 	setToolResultImages(toolCallId: string, images: ImageContent[]): void {
 		if (!toolCallId) return;
 		const validImages = images.filter(img => img.type === "image" && img.data && img.mimeType);

package/src/modes/components/custom-editor.ts

@@ -1,6 +1,8 @@
 import { Editor, type KeyId, matchesKey, parseKittySequence } from "@oh-my-pi/pi-tui";
 import type { AppKeybinding } from "../../config/keybindings";
+import { imageReferenceHyperlink, renderImageReferences } from "../image-references";
 import { highlightMagicKeywords } from "../magic-keywords";
+import { theme } from "../theme/theme";
 
 type ConfigurableEditorAction = Extract<
 	AppKeybinding,
@@ -47,9 +49,19 @@ const DEFAULT_ACTION_KEYS: Record<ConfigurableEditorAction, KeyId[]> = {
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
 export class CustomEditor extends Editor {
+	imageLinks?: readonly (string | undefined)[];
+
 	/** Gradient-highlight the "ultrathink" / "orchestrate" / "workflow" keywords as the user types
-	 *  them, skipping any occurrence inside code spans, fenced blocks, or XML sections. */
-	decorateText = (text: string): string => highlightMagicKeywords(text);
+	 *  them, skipping any occurrence inside code spans, fenced blocks, or XML sections. Also make
+	 *  pasted image placeholders visually distinct and hyperlink them once their blob file exists. */
+	decorateText = (text: string): string =>
+		renderImageReferences(text, {
+			renderText: value => highlightMagicKeywords(value),
+			renderReference: (value, index) =>
+				imageReferenceHyperlink(value, index, this.imageLinks, label =>
+					theme.fg("accent", `\x1b[1m\x1b[4m${label}\x1b[24m\x1b[22m`),
+				),
+		});
 	onEscape?: () => void;
 	onClear?: () => void;
 	onExit?: () => void;

package/src/modes/components/error-banner.ts

@@ -0,0 +1,33 @@
+import { Container, Spacer, Text } from "@oh-my-pi/pi-tui";
+import { getPreviewLines, TRUNCATE_LENGTHS } from "../../tools/render-utils";
+import { theme } from "../theme/theme";
+import { DynamicBorder } from "./dynamic-border";
+
+/** Max lines of the error message shown in the pinned banner. */
+const MAX_BANNER_LINES = 3;
+
+/**
+ * A persistent error banner pinned above the editor. Unlike the transcript
+ * "Error: …" line (which scrolls away as the conversation grows), this stays in
+ * the fixed region directly above the input so a turn that ended on a provider
+ * error — e.g. Anthropic's "Output blocked by content filtering policy" — cannot
+ * be missed. It is cleared when the next turn starts.
+ */
+export class ErrorBannerComponent extends Container {
+	constructor(message: string) {
+		super();
+		const lines = getPreviewLines(message, MAX_BANNER_LINES, TRUNCATE_LENGTHS.LINE);
+		if (lines.length === 0) {
+			lines.push("Unknown error");
+		}
+
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder(str => theme.fg("error", str)));
+		this.addChild(new Text(theme.bold(theme.fg("error", `${theme.status.error} ${lines[0]}`)), 1, 0));
+		for (const line of lines.slice(1)) {
+			this.addChild(new Text(theme.fg("error", `  ${line}`), 1, 0));
+		}
+		this.addChild(new Text(theme.fg("dim", "Dismissed when you send your next message."), 1, 0));
+		this.addChild(new DynamicBorder(str => theme.fg("error", str)));
+	}
+}

package/src/modes/components/tool-execution.ts

@@ -197,6 +197,11 @@ export class ToolExecutionComponent extends Container {
 	#todoStrikeInterval?: NodeJS.Timeout;
 	// Track if args are still being streamed (for edit/write spinner)
 	#argsComplete = false;
+	// Sealed once the tool reaches a terminal state (result delivered, or the
+	// turn abandoned it without one). Drives `isTranscriptBlockFinalized`: until
+	// sealed the block stays in the transcript's repaintable live region so a
+	// late result still repaints instead of stranding the streaming preview.
+	#sealed = false;
 	#renderState: {
 		spinnerFrame?: number;
 		expanded: boolean;
@@ -448,6 +453,13 @@ export class ToolExecutionComponent extends Container {
 		} else if (!needsSpinner && this.#spinnerInterval) {
 			clearInterval(this.#spinnerInterval);
 			this.#spinnerInterval = undefined;
+			// Clear the last drawn frame so a non-live renderCall (e.g. a write whose
+			// args just completed) stops showing a frozen spinner glyph. Skip when a
+			// todo strike owns the frame — it sets its own value right after this.
+			if (!this.#todoStrikeInterval) {
+				this.#spinnerFrame = undefined;
+				this.#renderState.spinnerFrame = undefined;
+			}
 		}
 	}
 
@@ -488,6 +500,37 @@ export class ToolExecutionComponent extends Container {
 		}
 	}
 
+	/**
+	 * Whether this block has reached a terminal state for transcript freezing.
+	 * Reports `false` while it can still visually change so the
+	 * {@link TranscriptContainer} keeps it inside the repaintable live region:
+	 * a foreground tool awaiting its result, or one streaming partial output.
+	 * A final (non-partial) result, a background-async tool the agent has moved
+	 * past, or an explicit {@link seal} flips it to `true`.
+	 */
+	isTranscriptBlockFinalized(): boolean {
+		if (this.#sealed) return true;
+		if (this.#result === undefined) return false;
+		if (!this.#isPartial) return true;
+		// Partial result: a background async tool is accepted to freeze (the agent
+		// continues while it runs and would otherwise pin an unbounded live region);
+		// a foreground tool streaming partial output stays live until it finishes.
+		return (this.#result.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
+	}
+
+	/**
+	 * Mark the tool terminal even though no result arrived (the turn aborted or
+	 * abandoned it) and stop animating, so it can freeze and stops pinning the
+	 * transcript live region.
+	 */
+	seal(): void {
+		if (this.#sealed) return;
+		this.#sealed = true;
+		this.stopAnimation();
+		this.#updateDisplay();
+		this.#ui.requestRender();
+	}
+
 	/**
 	 * Stop spinner animation and cleanup resources.
 	 */
@@ -496,6 +539,7 @@ export class ToolExecutionComponent extends Container {
 			clearInterval(this.#spinnerInterval);
 			this.#spinnerInterval = undefined;
 			this.#spinnerFrame = undefined;
+			this.#renderState.spinnerFrame = undefined;
 		}
 		this.#stopTodoStrikeAnimation();
 		this.#editDiffAbort?.abort();

package/src/modes/components/transcript-container.ts

@@ -1,4 +1,4 @@
-import { type Component, Container, TERMINAL } from "@oh-my-pi/pi-tui";
+import { type Component, Container, type NativeScrollbackLiveRegion, TERMINAL } from "@oh-my-pi/pi-tui";
 
 const kSnapshot = Symbol("transcript.frozenRender");
 
@@ -12,6 +12,33 @@ interface SnapshotCarrier {
 	[kSnapshot]?: FrozenRender;
 }
 
+/**
+ * A transcript block that is still mutating (a foreground tool awaiting its
+ * result, an assistant message mid-stream) reports `false` so the container
+ * keeps it inside the live (repaintable) region instead of freezing it. Blocks
+ * without the method are treated as finalized — the default, stable behavior.
+ *
+ * `isTranscriptBlockAppendOnly` marks a still-live block whose rendered rows
+ * only grow at the bottom and never re-layout (a streaming assistant reply).
+ * Such a block's scrolled-off head is safe to commit to native scrollback even
+ * while live; blocks that omit it (tool previews that collapse to a compact
+ * result) keep their mutable rows deferred. Default is `false`.
+ */
+interface FinalizableBlock {
+	isTranscriptBlockFinalized?(): boolean;
+	isTranscriptBlockAppendOnly?(): boolean;
+}
+
+function isBlockFinalized(child: Component): boolean {
+	const fn = (child as Component & FinalizableBlock).isTranscriptBlockFinalized;
+	return fn ? fn.call(child) : true;
+}
+
+function isBlockAppendOnly(child: Component): boolean {
+	const fn = (child as Component & FinalizableBlock).isTranscriptBlockAppendOnly;
+	return fn ? fn.call(child) : false;
+}
+
 /**
  * Transcript container that freezes the rendered output of every block except
  * the bottom-most (live) one on terminals where committed native scrollback is
@@ -34,15 +61,28 @@ interface SnapshotCarrier {
  * and any drift reconciles safely. On terminals that can rebuild history this
  * freezing is unnecessary, so it renders every block live for full fidelity.
  */
-export class TranscriptContainer extends Container {
+export class TranscriptContainer extends Container implements NativeScrollbackLiveRegion {
 	// Bumped to invalidate every block's snapshot at once; a snapshot is only
 	// honored when its stored generation still matches.
 	#generation = 0;
-	// The block that was bottom-most (live) on the previous render. When the live
-	// position moves past it, its snapshot was last refreshed mid-stream and may
-	// predate content that finalized in the same coalesced frame that appended the
-	// block now below it — so it must recompute once on the live→frozen transition.
-	#prevLiveChild: Component | undefined;
+	// Line index where the live (repaintable) region began on the previous
+	// render — the start of the earliest still-mutating block, or the bottom
+	// block when everything is finalized. A block leaves the live region only
+	// once it has finalized AND a finalized block sits below it; the frame it
+	// crosses out is recomputed so it freezes at its true final content, not the
+	// mid-stream snapshot it last rendered while live (TUI render coalescing can
+	// advance a block's content in the very frame it stops being live).
+	#prevLiveStartIndex = 0;
+	// Local line index where the current live region begins in the most recent
+	// render. TUI extends the native-scrollback pinned region from this point
+	// through the live blocks and the root chrome rendered below them.
+	#nativeScrollbackLiveRegionStart: number | undefined;
+	// Local line index up to which the leading run of live blocks is append-only
+	// (a streaming assistant reply): everything in [liveRegionStart,
+	// commitSafeEnd) only grows at the bottom and never re-layouts, so its
+	// scrolled-off head is safe to commit to native scrollback. `undefined` when
+	// the first live block is volatile (a tool preview).
+	#nativeScrollbackCommitSafeEnd: number | undefined;
 
 	override invalidate(): void {
 		// A theme/global invalidation forces a full recompute on the rebuild that
@@ -56,6 +96,14 @@ export class TranscriptContainer extends Container {
 		super.clear();
 	}
 
+	getNativeScrollbackLiveRegionStart(): number | undefined {
+		return this.#nativeScrollbackLiveRegionStart;
+	}
+
+	getNativeScrollbackCommitSafeEnd(): number | undefined {
+		return this.#nativeScrollbackCommitSafeEnd;
+	}
+
 	/**
 	 * Retire all frozen snapshots so the next render reflects each block's current
 	 * state. Call at reconciliation checkpoints (prompt submit) where the whole
@@ -68,39 +116,63 @@ export class TranscriptContainer extends Container {
 
 	override render(width: number): string[] {
 		width = Math.max(1, width);
+		this.#nativeScrollbackLiveRegionStart = undefined;
+		this.#nativeScrollbackCommitSafeEnd = undefined;
 		if (!TERMINAL.eagerEraseScrollbackRisk) return super.render(width);
 
+		const count = this.children.length;
+		// The live region spans from the earliest still-mutating block through the
+		// bottom. A block that has not finalized must stay repaintable: out-of-band
+		// inserts (TTSR/todo cards) can append a finalized block *below* a tool that
+		// is still awaiting its result, and freezing the tool there would strand its
+		// committed rows on the mid-stream preview the late result never reaches.
+		let liveStartIndex = count - 1;
+		for (let i = 0; i < count; i++) {
+			if (!isBlockFinalized(this.children[i]!)) {
+				liveStartIndex = i;
+				break;
+			}
+		}
+		// Blocks at [prevLiveStart, liveStart) just crossed out of the live region;
+		// recompute them so they freeze at their final content. Everything below
+		// the lower of the two cutoffs was already frozen last frame and replays.
+		const replayCutoff = Math.min(liveStartIndex, this.#prevLiveStartIndex);
+		this.#prevLiveStartIndex = liveStartIndex;
+
 		const lines: string[] = [];
-		const liveIndex = this.children.length - 1;
-		const liveChild = this.children[liveIndex];
-		const prevLiveChild = this.#prevLiveChild;
-		this.#prevLiveChild = liveChild;
-		for (let i = 0; i < this.children.length; i++) {
+		// Tracks whether we are still inside the leading run of append-only live
+		// blocks. The first non-append-only live block (or a finalized block below
+		// the live region's start, which cannot happen for a leading run) closes it.
+		let commitSafeOpen = true;
+		for (let i = 0; i < count; i++) {
 			const child = this.children[i]! as Component & SnapshotCarrier;
-			if (child !== liveChild) {
+			if (i >= liveStartIndex) {
+				if (i === liveStartIndex) this.#nativeScrollbackLiveRegionStart = lines.length;
+			} else {
 				const snapshot = child[kSnapshot];
-				// Replay the block's last render from while it was live. A stale
-				// generation (post-thaw) or width mismatch (resize in flight, an
-				// explicit rebuild that reconciles history anyway) recomputes instead.
-				// The block that was live on the previous render is also recomputed
-				// here: TUI render coalescing can advance its content (final streamed
-				// tokens) in the very frame that appends the block now below it, so its
-				// cached snapshot predates that final content. Recomputing on the
-				// transition seals the block at its true final state, not a mid-stream one.
-				if (
-					child !== prevLiveChild &&
-					snapshot &&
-					snapshot.generation === this.#generation &&
-					snapshot.width === width
-				) {
+				// Replay a frozen block's last live render. A stale generation
+				// (post-thaw) or width mismatch (resize, explicit rebuild) recomputes
+				// instead, as does a block that was still live last frame (i >= cutoff).
+				if (i < replayCutoff && snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
 					lines.push(...snapshot.lines);
 					continue;
 				}
 			}
 			const rendered = child.render(width);
-			// Cache every block's latest render. While a block is live this keeps its
-			// snapshot current; on the frame it stops being live the recompute above
-			// refreshes it to the final state before it freezes.
+			// Extend the commit-safe boundary through each leading append-only live
+			// block. `lines.length` here is this block's start offset; the boundary
+			// runs to the end of its rendered rows. The first volatile live block
+			// closes the run so its mutable rows stay deferred.
+			if (i >= liveStartIndex && commitSafeOpen) {
+				if (isBlockAppendOnly(child)) {
+					this.#nativeScrollbackCommitSafeEnd = lines.length + rendered.length;
+				} else {
+					commitSafeOpen = false;
+				}
+			}
+			// Cache every block's latest render. While a block is in the live region
+			// this keeps its snapshot current; on the frame it crosses out, the
+			// recompute above refreshes it to the final state before it freezes.
 			child[kSnapshot] = { width, lines: rendered, generation: this.#generation };
 			lines.push(...rendered);
 		}

package/src/modes/components/tree-selector.ts

@@ -441,8 +441,35 @@ class TreeList implements Component {
 		const lines: string[] = [];
 
 		if (this.#filteredNodes.length === 0) {
-			lines.push(truncateToWidth(theme.fg("muted", "  No entries found"), width));
-			lines.push(truncateToWidth(theme.fg("muted", `  (0/0)${this.#getFilterLabel()}`), width));
+			// Three empty-state shapes:
+			//  - flatNodes empty               → no entries at all (truly fresh session).
+			//  - search query rejects everything → tell the user the search is the cause.
+			//  - filter mode rejects everything  → tell the user the filter is the cause and
+			//    how to widen it. Otherwise fresh sessions whose only persisted entries are
+			//    `model_change` + `thinking_level_change` (both hidden by the default filter)
+			//    read as "broken /tree" — see #1909.
+			if (this.#flatNodes.length === 0) {
+				lines.push(truncateToWidth(theme.fg("muted", "  No entries found"), width));
+				lines.push(truncateToWidth(theme.fg("muted", `  (0/0)${this.#getFilterLabel()}`), width));
+			} else if (this.#searchQuery.length > 0) {
+				lines.push(truncateToWidth(theme.fg("muted", `  No entries match search "${this.#searchQuery}"`), width));
+				lines.push(truncateToWidth(theme.fg("muted", "  Press Backspace to clear the search"), width));
+				lines.push(
+					truncateToWidth(theme.fg("muted", `  (0/${this.#flatNodes.length})${this.#getFilterLabel()}`), width),
+				);
+			} else {
+				const filterLabel = this.#getFilterLabel().trim() || "[default]";
+				lines.push(
+					truncateToWidth(
+						theme.fg("muted", `  ${this.#flatNodes.length} entries hidden by the current filter ${filterLabel}`),
+						width,
+					),
+				);
+				lines.push(truncateToWidth(theme.fg("muted", "  Press Alt+A to show all, Alt+D for default"), width));
+				lines.push(
+					truncateToWidth(theme.fg("muted", `  (0/${this.#flatNodes.length})${this.#getFilterLabel()}`), width),
+				);
+			}
 			return lines;
 		}
 

package/src/modes/components/user-message.ts

@@ -1,5 +1,6 @@
 import { Container, Markdown, Spacer } from "@oh-my-pi/pi-tui";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
+import { imageReferenceHyperlink, renderImageReferences } from "../image-references";
 import { highlightMagicKeywords } from "../magic-keywords";
 
 // OSC 133 shell integration: marks prompt zones for terminal multiplexers
@@ -11,7 +12,7 @@ const OSC133_ZONE_FINAL = "\x1b]133;C\x07";
  * Component that renders a user message
  */
 export class UserMessageComponent extends Container {
-	constructor(text: string, synthetic = false) {
+	constructor(text: string, synthetic = false, imageLinks?: readonly (string | undefined)[]) {
 		super();
 		const bgColor = (value: string) => theme.bg("userMessageBg", value);
 		// Paint the magic keywords ("ultrathink"/"orchestrate"/"workflow") inside the rendered
@@ -20,9 +21,15 @@ export class UserMessageComponent extends Container {
 		// `highlightMagicKeywords` additionally restores the bubble's own foreground after each
 		// painted keyword so the gradient never bleeds into the rest of the line.
 		const keywordReset = theme.getFgAnsi("userMessageText") || "\x1b[39m";
-		const color = synthetic
+		const baseText = synthetic
 			? (value: string) => theme.fg("dim", value)
 			: (value: string) => theme.fg("userMessageText", highlightMagicKeywords(value, keywordReset));
+		const imageLabel = (value: string) => theme.fg("accent", `\x1b[1m\x1b[4m${value}\x1b[24m\x1b[22m`);
+		const color = (value: string) =>
+			renderImageReferences(value, {
+				renderText: baseText,
+				renderReference: (label, index) => imageReferenceHyperlink(label, index, imageLinks, imageLabel),
+			});
 		this.addChild(new Spacer(1));
 		this.addChild(
 			new Markdown(text, 1, 1, getMarkdownTheme(), {

package/src/modes/controllers/event-controller.ts

@@ -204,6 +204,7 @@ export class EventController {
 		this.#readToolCallAssistantComponents.clear();
 		this.#assistantMessageStreaming = false;
 		this.#lastAssistantComponent = undefined;
+		this.ctx.clearPinnedError();
 		if (this.ctx.retryEscapeHandler) {
 			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
 			this.ctx.retryEscapeHandler = undefined;
@@ -241,16 +242,28 @@ export class EventController {
 			this.ctx.ui.requestRender();
 		} else if (event.message.role === "user") {
 			const textContent = this.ctx.getUserMessageText(event.message);
-			const imageCount =
+			const imageBlocks =
 				typeof event.message.content === "string"
-					? 0
-					: event.message.content.filter(content => content.type === "image").length;
+					? []
+					: event.message.content.filter(
+							(content): content is ImageContent =>
+								content.type === "image" &&
+								typeof content.data === "string" &&
+								typeof content.mimeType === "string",
+						);
+			const imageCount = imageBlocks.length;
 			const signature = `${textContent}\u0000${imageCount}`;
 
 			this.#resetReadGroup();
 			const wasOptimistic = this.ctx.optimisticUserMessageSignature === signature;
 			const wasLocallySubmitted = this.ctx.locallySubmittedUserSignatures.delete(signature) || wasOptimistic;
 			if (!wasOptimistic) {
+				// Append synchronously: #emit dispatches to this listener fire-and-forget
+				// (see AgentSession.#emit), so any await between the user message_start and
+				// addMessageToChat lets later events (assistant message_start, tool execution
+				// start/end) append their components first and scramble transcript order /
+				// live-region block boundaries. addMessageToChat materializes clickable image
+				// links via the synchronous putBlobSync fallback, so no await is needed here.
 				this.ctx.addMessageToChat(event.message);
 			}
 			if (wasOptimistic) {
@@ -462,11 +475,32 @@ export class EventController {
 				for (const [toolCallId, component] of this.ctx.pendingTools.entries()) {
 					component.setArgsComplete(toolCallId);
 				}
+			} else {
+				// The turn ended without running these calls (abort/error/TTSR rewind),
+				// so they will never produce a result. Seal them so they stop animating
+				// and freeze instead of pinning the transcript live region while a retry
+				// streams fresh blocks below them. Background tools keep updating.
+				for (const [toolCallId, component] of this.ctx.pendingTools.entries()) {
+					if (!this.#backgroundToolCallIds.has(toolCallId) && component instanceof ToolExecutionComponent) {
+						component.seal();
+					}
+				}
 			}
 			this.#lastAssistantComponent = this.ctx.streamingComponent;
 			this.#lastAssistantComponent.setUsageInfo(event.message.usage);
+			this.#lastAssistantComponent.markTranscriptBlockFinalized();
 			this.ctx.streamingComponent = undefined;
 			this.ctx.streamingMessage = undefined;
+			// Pin a turn-ending provider error (e.g. Anthropic content-filter block)
+			// above the editor so it survives transcript scroll. Cleared at the next
+			// turn's agent_start.
+			if (
+				event.message.stopReason === "error" &&
+				event.message.errorMessage &&
+				!isSilentAbort(event.message.errorMessage)
+			) {
+				this.ctx.showPinnedError(event.message.errorMessage);
+			}
 			this.ctx.statusLine.invalidate();
 			this.ctx.updateEditorTopBorder();
 		}
@@ -626,6 +660,11 @@ export class EventController {
 		await this.ctx.flushPendingModelSwitch();
 		for (const toolCallId of Array.from(this.ctx.pendingTools.keys())) {
 			if (!this.#backgroundToolCallIds.has(toolCallId)) {
+				// A foreground tool still pending at turn end never delivered a result;
+				// seal it so it freezes (and stops animating) rather than lingering in
+				// the transcript live region as a streaming preview until the next thaw.
+				const component = this.ctx.pendingTools.get(toolCallId);
+				if (component instanceof ToolExecutionComponent) component.seal();
 				this.ctx.pendingTools.delete(toolCallId);
 			}
 		}