@oh-my-pi/pi-coding-agent 16.3.2 → 16.3.3

package/src/main.ts

@@ -84,6 +84,7 @@ import {
 	writeLastChangelogVersion,
 } from "./utils/changelog";
 import { EventBus } from "./utils/event-bus";
+import { withTimeoutSignal } from "./utils/fetch-timeout";
 
 type RunAcpMode = (createSession: AcpSessionFactory) => Promise<never>;
 type RunPrintMode = (session: AgentSession, options: PrintModeOptions) => Promise<void>;
@@ -102,7 +103,9 @@ async function checkForNewVersion(currentVersion: string): Promise<string | unde
 		return;
 	}
 	try {
-		const response = await fetch("https://registry.npmjs.org/@oh-my-pi/pi-coding-agent/latest");
+		const response = await fetch("https://registry.npmjs.org/@oh-my-pi/pi-coding-agent/latest", {
+			signal: withTimeoutSignal(5_000),
+		});
 		if (!response.ok) return undefined;
 
 		const data = (await response.json()) as { version?: string };
@@ -1383,6 +1386,9 @@ export async function runRootCommand(
 		}
 
 		if (!isInteractive && !session.model) {
+			if (modelRegistryError) {
+				process.stderr.write(`${chalk.red(modelRegistryError.message)}\n\n`);
+			}
 			if (modelFallbackMessage) {
 				process.stderr.write(`${chalk.red(modelFallbackMessage)}\n`);
 			} else {

package/src/mcp/oauth-flow.ts

@@ -79,6 +79,31 @@ function hasOAuthScope(scopes: string | null | undefined, scope: string): boolea
 	return !!scopes && scopes.split(/\s+/).includes(scope);
 }
 
+/**
+ * Trim a DCR failure body / thrown error message to a single, short line the
+ * caller can splice into an error string. `undefined` when nothing salvageable
+ * remains after stripping whitespace.
+ */
+function truncateDetail(raw: string | undefined): string | undefined {
+	if (!raw) return undefined;
+	const firstLine = raw.split(/\r?\n/, 1)[0]?.trim();
+	if (!firstLine) return undefined;
+	return firstLine.length > 200 ? `${firstLine.slice(0, 200)}…` : firstLine;
+}
+
+/**
+ * Read the response body of a rejected DCR request as a short diagnostic
+ * string. Never throws — the caller is already building an error and cannot
+ * afford to trade the actual failure for a "read body" one.
+ */
+async function readRegistrationFailureDetail(response: Response): Promise<string | undefined> {
+	try {
+		return truncateDetail(await response.text());
+	} catch {
+		return undefined;
+	}
+}
+
 function isLoopbackHostname(hostname: string): boolean {
 	return hostname === "localhost" || hostname === "127.0.0.1";
 }
@@ -294,6 +319,22 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 	#codeVerifier?: string;
 	#fetch: FetchImpl;
 	#resource?: string;
+	/**
+	 * Details of a rejected dynamic client-registration attempt. Populated by
+	 * {@link #tryRegisterClient} when the provider advertises a registration
+	 * endpoint but returns a non-2xx / throws (e.g. Figma's DCR endpoint 403s
+	 * every request because only catalog-approved clients may connect). Reused
+	 * by {@link #missingClientIdError} to explain why the fallback probe now
+	 * requires a manually configured `oauth.clientId`, replacing the opaque
+	 * "OAuth provider requires client_id" message.
+	 */
+	#registrationFailure?: {
+		endpoint: string;
+		/** HTTP status returned by the endpoint; `0` when the request threw. */
+		status: number;
+		/** First line of the response body (or thrown error message), trimmed. */
+		detail?: string;
+	};
 
 	constructor(
 		private config: MCPOAuthConfig,
@@ -507,6 +548,13 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 
 	/**
 	 * Try OAuth dynamic client registration when provider requires a client_id.
+	 *
+	 * Records rejection details on {@link #registrationFailure} so that when
+	 * DCR is intentionally closed (Figma's `mcp:connect` endpoint returns 403 to
+	 * every unlisted client — see https://developers.figma.com/docs/figma-mcp-server/,
+	 * "Only clients listed in the Figma MCP Catalog can connect"), the fallback
+	 * probe surfaces a message that names the endpoint and status instead of
+	 * the historical opaque "OAuth provider requires client_id".
 	 */
 	async #tryRegisterClient(redirectUri: string): Promise<void> {
 		const registrationEndpoint = await this.#resolveRegistrationEndpoint();
@@ -530,7 +578,14 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 				}),
 			});
 
-			if (!response.ok) return;
+			if (!response.ok) {
+				this.#registrationFailure = {
+					endpoint: registrationEndpoint,
+					status: response.status,
+					detail: await readRegistrationFailureDetail(response),
+				};
+				return;
+			}
 
 			const data = (await response.json()) as {
 				client_id?: string;
@@ -543,8 +598,14 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 			if (data.client_secret && data.client_secret.trim() !== "") {
 				this.#registeredClientSecret = data.client_secret;
 			}
-		} catch {
-			// Ignore registration failures and continue without client registration.
+		} catch (error) {
+			// Distinguish real transport/parse failures from a benign no-DCR
+			// response so #missingClientIdError can surface what went wrong.
+			this.#registrationFailure = {
+				endpoint: registrationEndpoint,
+				status: 0,
+				detail: error instanceof Error ? truncateDetail(error.message) : undefined,
+			};
 		}
 	}
 
@@ -609,7 +670,7 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 			if (response.status < 400) return;
 			const body = await response.text();
 			if (/client[_-]?id/i.test(body) && /(required|missing|invalid)/i.test(body)) {
-				throw new Error("OAuth provider requires client_id");
+				throw this.#missingClientIdError();
 			}
 		} catch (error) {
 			if (error instanceof Error && /client[_-]?id/i.test(error.message)) {
@@ -618,6 +679,34 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 			// Ignore network/probe failures to avoid blocking flows that still work.
 		}
 	}
+
+	/**
+	 * Build the error thrown when the authorize probe confirms the provider
+	 * demands a `client_id`. When dynamic client registration was attempted and
+	 * rejected (e.g. Figma's 403 for unlisted clients), fold the endpoint + HTTP
+	 * status into the message and point the user at the manual `oauth.clientId`
+	 * workaround. Refs issue #4307.
+	 */
+	#missingClientIdError(): Error {
+		const failure = this.#registrationFailure;
+		const manualHint =
+			"Configure `oauth.clientId` (and `oauth.clientSecret` if the flow needs one) on the MCP server entry in mcp.json.";
+		if (!failure) {
+			return new Error(
+				`OAuth provider requires client_id, and no dynamic-client-registration endpoint was advertised. ${manualHint}`,
+			);
+		}
+		const outcome =
+			failure.status > 0
+				? `HTTP ${failure.status}${failure.detail ? ` — ${failure.detail}` : ""}`
+				: failure.detail
+					? `network error — ${failure.detail}`
+					: "network error";
+		return new Error(
+			`OAuth provider requires client_id, and dynamic client registration was rejected ` +
+				`(POST ${failure.endpoint} → ${outcome}). The server likely restricts registration to pre-approved clients. ${manualHint}`,
+		);
+	}
 }
 
 /**

package/src/mcp/smithery-auth.ts

@@ -2,9 +2,11 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent, logger } from "@oh-my-pi/pi-utils";
 import { getAgentDir } from "@oh-my-pi/pi-utils/dirs";
+import { withTimeoutSignal } from "../utils/fetch-timeout";
 
 const SMITHERY_AUTH_FILENAME = "smithery.json";
 const SMITHERY_URL = process.env.SMITHERY_URL || "https://smithery.ai";
+const SMITHERY_AUTH_TIMEOUT_MS = 10_000;
 
 type SmitheryCliAuthSession = {
 	sessionId: string;
@@ -38,6 +40,7 @@ export function getSmitheryLoginUrl(): string {
 export async function createSmitheryCliAuthSession(): Promise<SmitheryCliAuthSession> {
 	const response = await fetch(`${SMITHERY_URL}/api/auth/cli/session`, {
 		method: "POST",
+		signal: withTimeoutSignal(SMITHERY_AUTH_TIMEOUT_MS),
 	});
 	if (!response.ok) {
 		throw new Error(`Failed to create Smithery auth session: ${response.status} ${response.statusText}`);

package/src/mcp/smithery-connect.ts

@@ -1,4 +1,7 @@
+import { withTimeoutSignal } from "../utils/fetch-timeout";
+
 const SMITHERY_API_BASE_URL = (process.env.SMITHERY_API_URL || "https://api.smithery.ai").replace(/\/+$/, "");
+const SMITHERY_CONNECT_TIMEOUT_MS = 10_000;
 
 export class SmitheryConnectError extends Error {
 	status: number;
@@ -62,6 +65,7 @@ export function getSmitheryApiBaseUrl(): string {
 export async function listSmitheryNamespaces(apiKey: string): Promise<SmitheryNamespace[]> {
 	const response = await fetch(toApiUrl("/namespaces"), {
 		headers: buildAuthHeaders(apiKey),
+		signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 	});
 	await expectOk(response, "Failed to list Smithery namespaces");
 	const payload = (await response.json()) as SmitheryNamespacesResponse;
@@ -72,6 +76,7 @@ export async function createSmitheryNamespace(apiKey: string): Promise<SmitheryN
 	const response = await fetch(toApiUrl("/namespaces"), {
 		method: "POST",
 		headers: buildAuthHeaders(apiKey),
+		signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 	});
 	await expectOk(response, "Failed to create Smithery namespace");
 	return (await response.json()) as SmitheryNamespace;
@@ -95,6 +100,7 @@ export async function listSmitheryConnectionsByUrl(
 	endpoint.searchParams.set("mcpUrl", mcpUrl);
 	const response = await fetch(endpoint.toString(), {
 		headers: buildAuthHeaders(apiKey),
+		signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 	});
 	await expectOk(response, "Failed to list Smithery connections");
 	const payload = (await response.json()) as SmitheryConnectionsResponse;
@@ -109,6 +115,7 @@ export async function createSmitheryConnection(
 	const response = await fetch(toApiUrl(`/connect/${encodeURIComponent(namespace)}`), {
 		method: "POST",
 		headers: buildAuthHeaders(apiKey),
+		signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 		body: JSON.stringify({
 			mcpUrl: params.mcpUrl,
 			name: params.name,
@@ -127,6 +134,7 @@ export async function getSmitheryConnection(
 		toApiUrl(`/connect/${encodeURIComponent(namespace)}/${encodeURIComponent(connectionId)}`),
 		{
 			headers: buildAuthHeaders(apiKey),
+			signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 		},
 	);
 	await expectOk(response, "Failed to get Smithery connection");
@@ -139,6 +147,7 @@ export async function deleteSmitheryConnection(apiKey: string, namespace: string
 		{
 			method: "DELETE",
 			headers: buildAuthHeaders(apiKey),
+			signal: withTimeoutSignal(SMITHERY_CONNECT_TIMEOUT_MS),
 		},
 	);
 	await expectOk(response, "Failed to delete Smithery connection");

package/src/mcp/smithery-registry.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it, vi } from "bun:test";
+import { searchSmitheryRegistry } from "./smithery-registry";
+
+type FetchInput = string | URL | Request;
+type FetchInit = RequestInit | BunFetchRequestInit;
+
+describe("searchSmitheryRegistry fetch cancellation", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("adds timeout signals to search and detail requests", async () => {
+		const signals: AbortSignal[] = [];
+		const fetchStub = Object.assign(
+			async (input: FetchInput, init?: FetchInit) => {
+				if (init?.signal instanceof AbortSignal) signals.push(init.signal);
+				const url = String(input);
+				if (url.includes("?")) {
+					return Response.json({
+						servers: [
+							{
+								id: "srv_1",
+								namespace: "smithery-ai",
+								slug: "filesystem",
+								qualifiedName: "@smithery-ai/filesystem",
+								displayName: "Filesystem",
+								description: "File access",
+								useCount: 1,
+							},
+						],
+					});
+				}
+				return Response.json({
+					qualifiedName: "@smithery-ai/filesystem",
+					displayName: "Filesystem",
+					description: "File access",
+					connections: [{ type: "http", deploymentUrl: "https://mcp.example" }],
+					tools: [],
+				});
+			},
+			{ preconnect: globalThis.fetch.preconnect },
+		);
+		vi.spyOn(globalThis, "fetch").mockImplementation(fetchStub);
+
+		const results = await searchSmitheryRegistry("filesystem", { limit: 1 });
+
+		expect(results[0]?.name).toBe("smithery-ai/filesystem");
+		expect(signals).toHaveLength(2);
+		expect(signals.every(signal => signal instanceof AbortSignal)).toBe(true);
+	});
+});

package/src/mcp/smithery-registry.ts

@@ -1,7 +1,9 @@
 import { logger } from "@oh-my-pi/pi-utils";
+import { isTimeoutError, withTimeoutSignal } from "../utils/fetch-timeout";
 import type { MCPServerConfig } from "./types";
 
 const SMITHERY_REGISTRY_BASE_URL = "https://registry.smithery.ai";
+const SMITHERY_REGISTRY_TIMEOUT_MS = 10_000;
 
 type SmitherySearchEntry = {
 	id?: string;
@@ -106,6 +108,7 @@ export interface SmitherySearchOptions {
 	limit?: number;
 	apiKey?: string;
 	includeSemantic?: boolean;
+	signal?: AbortSignal;
 }
 
 export class SmitheryRegistryError extends Error {
@@ -307,13 +310,17 @@ function createConfig(
 	};
 }
 
-async function fetchServerDetails(path: string, options?: { apiKey?: string }): Promise<SmitheryServerDetails | null> {
+async function fetchServerDetails(
+	path: string,
+	options?: { apiKey?: string; signal?: AbortSignal },
+): Promise<SmitheryServerDetails | null> {
 	const headers = new Headers();
 	if (options?.apiKey) {
 		headers.set("Authorization", `Bearer ${options.apiKey}`);
 	}
 	const response = await fetch(`${SMITHERY_REGISTRY_BASE_URL}/servers/${path}`, {
 		headers,
+		signal: withTimeoutSignal(SMITHERY_REGISTRY_TIMEOUT_MS, options?.signal),
 	});
 	if (!response.ok) return null;
 	return (await response.json()) as SmitheryServerDetails;
@@ -321,7 +328,7 @@ async function fetchServerDetails(path: string, options?: { apiKey?: string }):
 
 async function fetchServerDetailsFromEntry(
 	entry: SmitherySearchEntry,
-	options?: { apiKey?: string },
+	options?: { apiKey?: string; signal?: AbortSignal },
 ): Promise<SmitheryServerDetails | null> {
 	const candidates = resolveDetailPathCandidates(entry);
 	for (const candidate of candidates) {
@@ -329,6 +336,7 @@ async function fetchServerDetailsFromEntry(
 			const details = await fetchServerDetails(candidate, options);
 			if (details) return details;
 		} catch (error) {
+			if (options?.signal?.aborted) throw error;
 			logger.debug("Smithery detail fetch candidate failed", { candidate, error: String(error) });
 		}
 	}
@@ -411,7 +419,18 @@ export async function searchSmitheryRegistry(
 		url.searchParams.set("q", query);
 		url.searchParams.set("pageSize", String(pageSize));
 		if (page > 1) url.searchParams.set("page", String(page));
-		const response = await fetch(url.toString(), { headers });
+		let response: Response;
+		try {
+			response = await fetch(url.toString(), {
+				headers,
+				signal: withTimeoutSignal(SMITHERY_REGISTRY_TIMEOUT_MS, options?.signal),
+			});
+		} catch (err) {
+			if (isTimeoutError(err)) {
+				throw new SmitheryRegistryError("Smithery search timed out after 10s", 0);
+			}
+			throw err;
+		}
 		if (!response.ok) {
 			throw new SmitheryRegistryError(`Smithery search failed with status ${response.status}`, response.status);
 		}
@@ -448,10 +467,14 @@ export async function searchSmitheryRegistry(
 	const results = await Promise.all(
 		uniqueEntries.map(async entry => {
 			try {
-				const details = await fetchServerDetailsFromEntry(entry, { apiKey: options?.apiKey });
+				const details = await fetchServerDetailsFromEntry(entry, {
+					apiKey: options?.apiKey,
+					signal: options?.signal,
+				});
 				if (!details) return null;
 				return toSearchResult(entry, details);
 			} catch (error) {
+				if (options?.signal?.aborted) throw error;
 				detailFailures.push({
 					identity: getEntryIdentityKey(entry) ?? entry.id ?? "unknown",
 					error: String(error),

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

@@ -7,7 +7,7 @@ import {
 	type ToolUIColor,
 	wrapTextWithAnsi,
 } from "../../tools/render-utils";
-import { Ellipsis, renderStatusLine, truncateToWidth } from "../../tui";
+import { Ellipsis, truncateToWidth } from "../../tui";
 import type { Theme } from "../theme/theme";
 
 const COLLAPSED_NOTES = 3;
@@ -42,8 +42,10 @@ function severityColor(severity: AdvisorSeverity | undefined): ToolUIColor {
 
 /**
  * Display-only transcript card for advisor notes injected into the primary
- * session. Mirrors the IRC card's glyph + quote-border conventions so passive
- * advice reads as a distinct, non-interrupting aside rather than a user turn.
+ * session. Styled as a distinct voice so notes never blend into thinking
+ * output (whose `thinkingText` color equals `toolOutput` in most themes):
+ * a bold `customMessageLabel` header tag (skill-card convention), a heavy
+ * rail tinted per-note severity, and the note body on the default text color.
  */
 export function createAdvisorMessageCard(
 	details: AdvisorMessageDetails | undefined,
@@ -58,9 +60,9 @@ export function createAdvisorMessageCard(
 	return createCachedComponent(
 		getExpanded,
 		(width, expanded) => {
-			const glyph = uiTheme.styledSymbol("status.info", "accent");
-			const lines = [renderStatusLine({ iconOverride: glyph, title: "Advisor", meta }, uiTheme)];
-			const quote = uiTheme.fg("dim", uiTheme.md.quoteBorder);
+			const tag = uiTheme.fg("customMessageLabel", uiTheme.bold(`${uiTheme.status.info} Advisor`));
+			const lines = [`${tag} ${uiTheme.fg("dim", meta.join(uiTheme.sep.dot))}`];
+			const railGlyph = uiTheme.symbol("advisor.rail");
 			const shown = expanded ? notes : notes.slice(0, COLLAPSED_NOTES);
 			for (const entry of shown) {
 				const badge = entry.severity
@@ -72,8 +74,8 @@ export function createAdvisorMessageCard(
 					entry.advisor && entry.advisor !== "default"
 						? `${uiTheme.fg("dim", `[${replaceTabs(entry.advisor)}]`)} `
 						: "";
-				const quotePrefix = `  ${quote} `;
-				const quoteWidth = visibleWidth(quotePrefix);
+				const rail = uiTheme.fg(severityColor(entry.severity), railGlyph);
+				const quoteWidth = visibleWidth(`  ${railGlyph} `);
 				const badgeWidth = visibleWidth(badge);
 				const whoWidth = visibleWidth(who);
 				const w1 = Math.max(10, Math.min(NOTE_LINE_WIDTH, width) - quoteWidth - badgeWidth - whoWidth);
@@ -92,12 +94,13 @@ export function createAdvisorMessageCard(
 
 				bodyLines.forEach((line, index) => {
 					const prefix = index === 0 ? `${badge}${who}` : "";
-					lines.push(`  ${quote} ${prefix}${uiTheme.fg("toolOutput", replaceTabs(line))}`);
+					lines.push(`  ${rail} ${prefix}${uiTheme.fg("customMessageText", replaceTabs(line))}`);
 				});
 			}
 			const hidden = notes.length - shown.length;
 			if (hidden > 0) {
-				lines.push(`  ${quote} ${uiTheme.fg("dim", `… +${hidden} more ${hidden === 1 ? "note" : "notes"}`)}`);
+				const rail = uiTheme.fg("dim", railGlyph);
+				lines.push(`  ${rail} ${uiTheme.fg("dim", `… +${hidden} more ${hidden === 1 ? "note" : "notes"}`)}`);
 			}
 			return lines.map(line => truncateToWidth(line, width, Ellipsis.Unicode));
 		},

package/src/modes/components/status-line/component.ts

@@ -4,7 +4,6 @@ import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, UsageLimit, UsageReport } from "@oh-my-pi/pi-ai";
 import { type Component, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
 import { getProjectDir } from "@oh-my-pi/pi-utils";
-import { $ } from "bun";
 import { settings } from "../../../config/settings";
 import type { AgentSession } from "../../../session/agent-session";
 import type { OAuthAccountIdentity } from "../../../session/auth-storage";
@@ -707,14 +706,22 @@ export class StatusLineComponent implements Component {
 				}
 			};
 			try {
-				// Requires `gh repo set-default` to be configured; fails gracefully if not
-				const result = await $`gh pr view --json number,url`.cwd(lookupCwd).quiet().nothrow();
+				// Route through the shared `gh` helper so the child inherits
+				// `GH_NON_INTERACTIVE_ENV` (disables terminal/keychain prompts) and
+				// hard-terminates on the git command deadline instead of stalling
+				// the status-line indefinitely (#4234). Requires `gh repo set-default`;
+				// non-zero exit still falls through to the null cache below.
+				const result = await git.github.run(
+					lookupCwd,
+					["pr", "view", "--json", "number,url"],
+					AbortSignal.timeout(git.GIT_COMMAND_TIMEOUT_MS),
+				);
 				if (this.#disposed) return;
 				if (result.exitCode !== 0) {
 					setCachedPr(null);
 					return;
 				}
-				const pr = JSON.parse(result.stdout.toString()) as { number: number; url: string };
+				const pr = JSON.parse(result.stdout) as { number: number; url: string };
 				if (typeof pr.number === "number") {
 					setCachedPr({ number: pr.number, url: pr.url });
 				} else {

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

@@ -182,12 +182,14 @@ export interface ToolExecutionHandle {
 	setExpanded(expanded: boolean): void;
 }
 
-/** Drive pending-tool redraws at 30fps for live tool headers and displaceable
- * poll blocks. The TUI throttles at the same cadence, and static frames diff to
- * a no-op redraw at ~zero cost. */
-export const SPINNER_RENDER_INTERVAL_MS = 1000 / 30;
-/** Advance the spinner glyph at its classic ~12.5fps step, decoupled from the
- * render cadence (mirrors `Loader`). */
+/** Redraw live tool blocks at the spinner's glyph-advance rate. Rendering more
+ * often produced identical frames — the previous 30fps cadence emitted ~2.4
+ * paints per glyph step, and although the terminal I/O layer dedupes those, the
+ * compose pipeline still ran end-to-end per frame (issue #4353). Matching the
+ * render tick to the glyph tick halves the paints during tool execution with no
+ * visible change. */
+export const SPINNER_RENDER_INTERVAL_MS = 80;
+/** Advance the spinner glyph at its classic ~12.5fps step (mirrors `Loader`). */
 export const SPINNER_GLYPH_ADVANCE_MS = 80;
 
 /** Phase-locked spinner glyph index shared by every live tool block so parallel
@@ -281,6 +283,14 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 	// history, so progress renders static gray and further partial snapshots are
 	// dropped (see #maybeFreezeBackgroundTask).
 	#backgroundTaskFrozen = false;
+	// Set on each `render()` when the last painted shape carried the streamed
+	// SSH-style placeholder / partial-result chrome. Reset gates key off these
+	// so a topology-changing update that lands before the shape reaches the
+	// terminal never triggers a full-viewport replay (which on direct terminals
+	// wipes native scrollback and flashes the user's history — reviewer note on
+	// PR #4315).
+	#placeholderShapePainted = false;
+	#partialResultShapePainted = false;
 	#renderState: {
 		spinnerFrame?: number;
 		expanded: boolean;
@@ -485,6 +495,12 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		if (isPartial && this.#toolName === "task" && this.#maybeFreezeBackgroundTask()) {
 			return;
 		}
+		const hadNoResult = this.#result === undefined;
+		const wasPartialResult = this.#result !== undefined && this.#isPartial;
+		const placeholderPainted = this.#placeholderShapePainted;
+		const partialResultPainted = this.#partialResultShapePainted;
+		this.#placeholderShapePainted = false;
+		this.#partialResultShapePainted = false;
 		this.#result = result;
 		this.#resultVersion++;
 		this.#isPartial = isPartial;
@@ -496,6 +512,11 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		this.#updateSpinnerAnimation();
 		this.#updateTodoStrikeAnimation();
 		this.#updateDisplay();
+		this.#resetDisplayForResultTopologyChange(
+			hadNoResult && placeholderPainted,
+			wasPartialResult && partialResultPainted,
+			isPartial,
+		);
 		// Convert non-PNG images to PNG for Kitty protocol (async)
 		this.#maybeConvertImagesForKitty();
 	}
@@ -830,6 +851,49 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 		this.#displayBuilt = true;
 	}
 
+	#rendererFlag(name: "forceFirstResultViewportRepaint" | "forceResultViewportRepaintOnSettle"): boolean {
+		const toolValue = (this.#tool as Record<string, unknown> | undefined)?.[name];
+		const rendererValue = toolRenderers[this.#toolName]?.[name];
+		return toolValue === true || (toolValue === undefined && rendererValue === true);
+	}
+
+	/**
+	 * True while the last painted shape uses the streamed placeholder path
+	 * (`⏳ SSH: […]` / `$ …`) — the render call ran with `__partialJson` args
+	 * and no result. Kept as a per-paint fact so a topology-changing update
+	 * that lands before the placeholder reaches the terminal skips the reset.
+	 */
+	#isPlaceholderShapeAtRender(): boolean {
+		if (this.#result !== undefined) return false;
+		if (!this.#rendererFlag("forceFirstResultViewportRepaint")) return false;
+		return partialJsonOf(this.#args) !== undefined;
+	}
+
+	#resetDisplayForResultTopologyChange(
+		firstResultAfterPlaceholderPaint: boolean,
+		partialResultPaintedBeforeSettle: boolean,
+		isPartial: boolean,
+	): void {
+		const firstResultReplacesStreamedPlaceholder =
+			firstResultAfterPlaceholderPaint && this.#rendererFlag("forceFirstResultViewportRepaint");
+		const provisionalResultSettled =
+			partialResultPaintedBeforeSettle && !isPartial && this.#rendererFlag("forceResultViewportRepaintOnSettle");
+		if (firstResultReplacesStreamedPlaceholder || provisionalResultSettled) {
+			this.#ui.resetDisplay();
+		}
+	}
+
+	override render(width: number): readonly string[] {
+		const lines = super.render(width);
+		// Update the paint-tracking flags after `super.render(width)` — the
+		// override runs on every compose the parent Container performs, so a
+		// frame that never gets composed leaves the flags false and prevents a
+		// spurious `resetDisplay()`.
+		this.#placeholderShapePainted = this.#isPlaceholderShapeAtRender();
+		this.#partialResultShapePainted = this.#result !== undefined && this.#isPartial;
+		return lines;
+	}
+
 	// Viewport-/settings-dependent image sizing folded into the memo key only when
 	// the last rebuild actually emitted images, so a terminal resize re-shapes an
 	// image-bearing result (to rescale it) without re-shaping every image-free
@@ -873,7 +937,8 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 			if (shouldRenderCall) {
 				if (tool.renderCall) {
 					try {
-						const callComponent = tool.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
+						const callArgs = this.#getCallArgsForRender();
+						const callComponent = tool.renderCall(callArgs, this.#renderState, theme);
 						if (callComponent) this.#contentBox.addChild(callComponent as Component);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
@@ -1007,7 +1072,8 @@ export class ToolExecutionComponent extends Container implements NativeScrollbac
 				if (shouldRenderCall) {
 					// Render call component
 					try {
-						const callComponent = renderer.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
+						const callArgs = this.#getCallArgsForRender();
+						const callComponent = renderer.renderCall(callArgs, this.#renderState, theme);
 						if (callComponent) this.#contentBox.addChild(callComponent);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });