@oh-my-pi/pi-coding-agent 16.3.5 → 16.3.7

package/src/session/agent-session.ts

@@ -81,6 +81,8 @@ import type { ProtectedToolMatcher } from "@oh-my-pi/pi-agent-core/compaction/to
 import type {
 	AssistantMessage,
 	AssistantMessageEvent,
+	AssistantRetryRecovery,
+	AssistantRetryRecoveryKind,
 	Context,
 	ImageContent,
 	Message,
@@ -219,6 +221,7 @@ import { createExtensionModelQuery } from "../extensibility/extensions/model-api
 import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
 import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import type { HookCommandContext } from "../extensibility/hooks/types";
+import type { RecoveredRetryError } from "../extensibility/shared-events";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { GoalRuntime } from "../goals/runtime";
@@ -334,11 +337,16 @@ import {
 import {
 	type BashExecutionMessage,
 	type CustomMessage,
+	type CustomMessagePayload,
 	convertToLlm,
 	demoteInterruptedThinking,
+	type FileMentionMessage,
+	type HookMessage,
 	INTERRUPTED_THINKING_MESSAGE_TYPE,
 	type InterruptedThinkingDetails,
+	isEmptyErrorTurn,
 	isUserInterruptAbort,
+	normalizeCustomMessagePayload,
 	type PythonExecutionMessage,
 	readQueueChipText,
 	SILENT_ABORT_MARKER,
@@ -497,7 +505,13 @@ export type AgentSessionEvent =
 			errorMessage: string;
 			errorId?: number;
 	  }
-	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| {
+			type: "auto_retry_end";
+			success: boolean;
+			attempt: number;
+			finalError?: string;
+			recoveredErrors?: RecoveredRetryError[];
+	  }
 	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
 	| { type: "retry_fallback_succeeded"; model: string; role: string }
 	| { type: "ttsr_triggered"; rules: Rule[] }
@@ -837,6 +851,16 @@ export interface PromptOptions {
 	skipCompactionCheck?: boolean;
 }
 
+/** Options for AgentSession.followUp() */
+export interface FollowUpOptions {
+	/** Enqueue as a hidden developer message (agent-attributed by default) instead of a user follow-up. */
+	synthetic?: boolean;
+	/** Whether to expand file-based prompt templates (default: true). */
+	expandPromptTemplates?: boolean;
+	/** Explicit billing/initiator attribution. Defaults to `agent` for synthetic follow-ups. */
+	attribution?: MessageAttribution;
+}
+
 /** Result from a handoff operation. */
 export interface HandoffResult {
 	document: string;
@@ -1425,6 +1449,13 @@ type MessageEndPersistenceSlot = {
 	persist: (persistMessage: () => void) => Promise<void>;
 	release: () => void;
 };
+type PendingRecoveredRetryError = {
+	entryId: string;
+	persistenceKey: string;
+	recovery: AssistantRetryRecoveryKind;
+	attempt: number;
+	note: string;
+};
 
 type PostPromptSkipReason = "aborted" | "stale-generation";
 
@@ -1581,6 +1612,7 @@ export class AgentSession {
 	#retryPromise: Promise<void> | undefined = undefined;
 	#retryResolve: (() => void) | undefined = undefined;
 	#activeRetryFallback: ActiveRetryFallbackState | undefined = undefined;
+	#pendingRecoveredRetryErrors: PendingRecoveredRetryError[] = [];
 	// Todo completion reminder state
 	#todoReminderCount = 0;
 	/**
@@ -1654,6 +1686,7 @@ export class AgentSession {
 	#turnIndex = 0;
 	#messageEndPersistenceTail: Promise<void> = Promise.resolve();
 	#pendingMessageEndPersistence = new Map<string, Promise<void>>();
+	#persistedMessageKeys: { anchor: string; keys: Set<string> } | undefined;
 
 	#skills: Skill[];
 	#skillWarnings: SkillWarning[];
@@ -2322,7 +2355,19 @@ export class AgentSession {
 				model = sel.model;
 				thinkingLevel = concreteThinkingLevel(sel.thinkingLevel);
 			}
-			const advisorThinkingLevel = thinkingLevel ?? ThinkingLevel.Medium;
+			// Clamp the effort against the resolved model. Historically we defaulted
+			// to `ThinkingLevel.Medium` unconditionally, which threw at first stream
+			// on reasoning models that expose no controllable effort surface
+			// (e.g. `devin-agent`: Cascade routes by sibling model id, not a wire
+			// param; `getSupportedEfforts` returns `[]`). `resolveThinkingLevelForModel`
+			// preserves an explicit `off`, clamps a concrete effort into the model's
+			// supported range, and returns `undefined` for reasoning models without
+			// controllable efforts — for that case we forward `Inherit` so no effort
+			// is sent and reasoning stays enabled (matching the `auto`-path fix for
+			// Devin models via `clampAutoThinkingEffort`). See #4579.
+			const requestedLevel = thinkingLevel ?? ThinkingLevel.Medium;
+			const resolvedLevel = resolveThinkingLevelForModel(model, requestedLevel);
+			const advisorThinkingLevel: ThinkingLevel = resolvedLevel ?? ThinkingLevel.Inherit;
 			descriptors.push({
 				config,
 				name: config.name,
@@ -3256,13 +3301,20 @@ export class AgentSession {
 	/**
 	 * Index every message entry on the current branch by persistence key, so
 	 * the mid-run-compaction planner can ask "is this turn message already on
-	 * the branch?" in O(1) instead of re-walking the branch per check.
+	 * the branch?" in O(1). The set is memoized through the current leaf path
+	 * and validated at use time against a (session file, leaf id) anchor.
 	 *
 	 * The mid-run ordering check uses key identity alone: same-key content
 	 * variants are one logical message at this boundary, because otherwise a
 	 * display-side rewrite can make the assistant look missing after its tool
 	 * results have already persisted.
 	 *
+	 * Coherency is anchor-based, not invalidation-based: every branch mutation
+	 * (rewind, branch switch, new session, custom-entry append) changes the
+	 * session manager's leaf id or session file, so `#ensurePersistedMessageKeys`
+	 * detects staleness itself and rebuilds. No mutation call site has to
+	 * remember to invalidate anything.
+	 *
 	 * Pre-#3629 the equivalent was `sessionManager.getBranch()` called twice
 	 * per turn message, each call rebuilding the path via O(n²) `unshift` and
 	 * structurally JSON-comparing every entry — seconds of synchronous work
@@ -3270,6 +3322,24 @@ export class AgentSession {
 	 * `ui.loop-blocked` warnings in the bug report.
 	 */
 	#indexPersistedMessageKeys(): Set<string> {
+		return this.#ensurePersistedMessageKeys();
+	}
+
+	#persistedMessageKeysAnchor(): string {
+		return `${this.sessionManager.getSessionFile() ?? ""}\u0000${this.sessionManager.getLeafId() ?? ""}`;
+	}
+
+	#ensurePersistedMessageKeys(): Set<string> {
+		const anchor = this.#persistedMessageKeysAnchor();
+		let cache = this.#persistedMessageKeys;
+		if (cache === undefined || cache.anchor !== anchor) {
+			cache = { anchor, keys: this.#buildPersistedMessageKeySet() };
+			this.#persistedMessageKeys = cache;
+		}
+		return cache.keys;
+	}
+
+	#buildPersistedMessageKeySet(): Set<string> {
 		const keys = new Set<string>();
 		for (const entry of this.sessionManager.getBranch()) {
 			if (entry.type !== "message") continue;
@@ -3281,20 +3351,16 @@ export class AgentSession {
 
 	/**
 	 * True when {@link message} is structurally identical to a message already
-	 * appended to the current branch. Pairs a fast persistence-key lookup with
-	 * a content-equality fallback so two logically distinct messages that
-	 * happen to collide on the cheap key (e.g. two assistant turns at the same
-	 * millisecond with `undefined` responseId) still count as DISTINCT.
+	 * appended to the current branch. Uses the current branch's memoized
+	 * persistence-key cache for the common missing-key case, and only walks the
+	 * branch to verify content when a key hit could be a rare collision.
 	 */
 	#sessionMessageAlreadyPersisted(message: AgentMessage): boolean {
 		const key = sessionMessagePersistenceKey(message);
 		if (key === undefined) return false;
+		const keys = this.#ensurePersistedMessageKeys();
+		if (!keys.has(key)) return false;
 		const branch = this.sessionManager.getBranch();
-		// Reverse walk: recently-appended entries are at the tail, so the common
-		// "is the message I just emitted already in the branch?" lookup short-
-		// circuits in O(1) hot, O(branch) cold. Cheap-key compare for every
-		// entry; content compare only when the cheap check matches, so the
-		// expensive `JSON.stringify(content)` path stays off the hot loop.
 		for (let index = branch.length - 1; index >= 0; index--) {
 			const entry = branch[index];
 			if (entry.type !== "message") continue;
@@ -3304,6 +3370,26 @@ export class AgentSession {
 		return false;
 	}
 
+	#appendSessionMessage(
+		message:
+			| Message
+			| CustomMessage
+			| HookMessage
+			| BashExecutionMessage
+			| PythonExecutionMessage
+			| FileMentionMessage,
+	): string {
+		const cache = this.#persistedMessageKeys;
+		const wasFresh = cache !== undefined && cache.anchor === this.#persistedMessageKeysAnchor();
+		const entryId = this.sessionManager.appendMessage(message);
+		const key = sessionMessagePersistenceKey(message);
+		if (wasFresh && cache && key) {
+			cache.keys.add(key);
+			cache.anchor = this.#persistedMessageKeysAnchor();
+		}
+		return entryId;
+	}
+
 	#persistSessionMessageIfMissing(message: AgentMessage): void {
 		if (
 			message.role !== "user" &&
@@ -3318,6 +3404,7 @@ export class AgentSession {
 		if (message.role === "assistant") {
 			const assistantMsg = message as AssistantMessage;
 			if (this.#isClassifierRefusal(assistantMsg)) return;
+			if (isEmptyErrorTurn(assistantMsg)) return;
 			if (assistantMsg.stopReason !== "aborted" && assistantMsg.stopReason !== "error" && assistantMsg.usage) {
 				assistantMsg.contextSnapshot = {
 					promptTokens: calculatePromptTokens(assistantMsg.usage),
@@ -3330,7 +3417,7 @@ export class AgentSession {
 			message.toolName === "rewind" &&
 			this.#rewoundToolResultIds.delete(message.toolCallId);
 		if (!skipPersistedRewindResult) {
-			this.sessionManager.appendMessage(message);
+			this.#appendSessionMessage(message);
 		}
 	}
 
@@ -3663,11 +3750,14 @@ export class AgentSession {
 							role: this.#activeRetryFallback.role,
 						});
 					}
+					const recoveredErrors = await this.#markPendingRecoveredRetryErrors(assistantMsg);
 					await this.#emitSessionEvent({
 						type: "auto_retry_end",
 						success: true,
 						attempt: this.#retryAttempt,
+						recoveredErrors,
 					});
+					this.#clearPendingRecoveredRetryErrors();
 					this.#retryAttempt = 0;
 				}
 				if (assistantMsg.provider === "opencode-go") {
@@ -5337,6 +5427,7 @@ export class AgentSession {
 				success: event.success,
 				attempt: event.attempt,
 				finalError: event.finalError,
+				recoveredErrors: event.recoveredErrors,
 			});
 		} else if (event.type === "ttsr_triggered") {
 			await this.#extensionRunner.emit({ type: "ttsr_triggered", rules: event.rules });
@@ -7569,15 +7660,22 @@ export class AgentSession {
 					const promptAttribution: "user" | "agent" | undefined =
 						"attribution" in message ? message.attribution : undefined;
 					for (const msg of result.messages) {
+						const normalized = normalizeCustomMessagePayload(msg);
+						const hasExplicitAttribution =
+							msg !== null &&
+							typeof msg === "object" &&
+							!Array.isArray(msg) &&
+							(msg.attribution === "user" || msg.attribution === "agent");
 						messages.push(
 							await this.#normalizeAgentMessageImages({
 								role: "custom",
-								customType: msg.customType,
-								content: msg.content,
-								display: msg.display,
-								details: msg.details,
-								attribution:
-									msg.attribution ?? promptAttribution ?? (message.role === "user" ? "user" : "agent"),
+								customType: normalized.customType,
+								content: normalized.content,
+								display: normalized.display,
+								details: normalized.details,
+								attribution: hasExplicitAttribution
+									? normalized.attribution
+									: (promptAttribution ?? (message.role === "user" ? "user" : "agent")),
 								timestamp: Date.now(),
 							}),
 						);
@@ -7792,14 +7890,42 @@ export class AgentSession {
 
 	/**
 	 * Queue a follow-up message to process after the agent would otherwise stop.
+	 * Set `options.synthetic` to enqueue a hidden developer message (agent-attributed
+	 * by default) instead of a user-attributed follow-up; the plan-approval flow
+	 * uses this to land its execution directive behind a queued user turn without
+	 * flipping advisor auto-resume.
 	 */
-	async followUp(text: string, images?: ImageContent[]): Promise<void> {
+	async followUp(text: string, images?: ImageContent[], options?: FollowUpOptions): Promise<void> {
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
 		}
 
-		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
-		await this.#queueUserMessage(expandedText, images, "followUp");
+		const expandedText =
+			options?.expandPromptTemplates === false ? text : expandPromptTemplate(text, [...this.#promptTemplates]);
+		if (!options?.synthetic) {
+			await this.#queueUserMessage(expandedText, images, "followUp");
+			return;
+		}
+		// Synthetic branch: agent-initiated hidden developer message. Bypass
+		// #queueUserMessage (which clears advisor auto-resume suppression and
+		// enqueues as a user-attributed message) and place the developer message
+		// directly on the follow-up queue.
+		const normalizedImages = await this.#normalizeImagesForModel(images);
+		const content: (TextContent | ImageContent)[] = [{ type: "text", text: expandedText }];
+		if (normalizedImages?.length) {
+			content.push(...normalizedImages);
+		}
+		const imageDescriptionNotice = normalizedImages?.length
+			? await this.#buildImageDescriptionNotice(normalizedImages)
+			: undefined;
+		if (imageDescriptionNotice) this.agent.followUp(imageDescriptionNotice);
+		this.agent.followUp({
+			role: "developer",
+			content,
+			attribution: options.attribution ?? "agent",
+			timestamp: Date.now(),
+		});
+		this.#scheduleIdleQueueDrain();
 	}
 
 	async #queueUserMessage(
@@ -8040,26 +8166,26 @@ export class AgentSession {
 	 * use this to avoid acting on a turn that never ran.
 	 */
 	async sendCustomMessage<T = unknown>(
-		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">,
+		message: CustomMessagePayload<T>,
 		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn"; queueChipText?: string },
 	): Promise<boolean> {
+		const normalizedPayload = normalizeCustomMessagePayload<T>(message);
 		const details =
 			options?.queueChipText && options.deliverAs !== "nextTurn"
 				? ({
-						...((message.details && typeof message.details === "object" ? message.details : {}) as Record<
-							string,
-							unknown
-						>),
+						...((normalizedPayload.details && typeof normalizedPayload.details === "object"
+							? normalizedPayload.details
+							: {}) as Record<string, unknown>),
 						__queueChipText: options.queueChipText,
 					} as T)
-				: message.details;
+				: normalizedPayload.details;
 		const appMessage: CustomMessage<T> = {
 			role: "custom",
-			customType: message.customType,
-			content: message.content,
-			display: message.display,
+			customType: normalizedPayload.customType,
+			content: normalizedPayload.content,
+			display: normalizedPayload.display,
 			details,
-			attribution: message.attribution ?? "agent",
+			attribution: normalizedPayload.attribution,
 			timestamp: Date.now(),
 		};
 		const normalizedAppMessage = await this.#normalizeAgentMessageImages(appMessage);
@@ -8091,9 +8217,9 @@ export class AgentSession {
 			this.sessionManager.appendCustomMessageEntry(
 				normalizedAppMessage.customType,
 				normalizedAppMessage.content,
-				message.display,
-				message.details,
-				message.attribution ?? "agent",
+				normalizedAppMessage.display,
+				normalizedAppMessage.details,
+				normalizedAppMessage.attribution,
 			);
 			return false;
 		}
@@ -8111,9 +8237,9 @@ export class AgentSession {
 		this.sessionManager.appendCustomMessageEntry(
 			normalizedAppMessage.customType,
 			normalizedAppMessage.content,
-			message.display,
-			message.details,
-			message.attribution ?? "agent",
+			normalizedAppMessage.display,
+			normalizedAppMessage.details,
+			normalizedAppMessage.attribution,
 		);
 		return false;
 	}
@@ -8507,6 +8633,7 @@ export class AgentSession {
 			await this.sessionManager.flush();
 		}
 		await this.sessionManager.newSession(options);
+
 		this.#clearCheckpointRuntimeState();
 		this.setTodoPhases([]);
 		this.#freshProviderSessionId = undefined;
@@ -9122,24 +9249,26 @@ export class AgentSession {
 
 	/**
 	 * `/fast on|off` targets the family of the currently selected model: it sets
-	 * (or clears) that family's `priority` tier. Models without a service-tier
-	 * family (Fireworks, or providers with no tier knob) have nothing to toggle.
+	 * (or clears) that family's `priority` tier. Returns `false` when the model
+	 * has no service-tier family, so callers can report that fast mode is
+	 * unavailable instead of claiming success.
 	 */
-	setFastMode(enabled: boolean): void {
+	setFastMode(enabled: boolean): boolean {
 		const family = this.model ? serviceTierFamily(this.model) : undefined;
 		if (!family) {
 			this.emitNotice("info", "The current model has no service-tier control for /fast to toggle.", "priority");
-			return;
+			return false;
 		}
 		if (!enabled) {
 			if (this.#serviceTierByFamily[family] === "priority") this.setServiceTierFamily(family, undefined);
-			return;
+			return true;
 		}
 		this.setServiceTierFamily(family, "priority");
+		return true;
 	}
 
 	toggleFastMode(): boolean {
-		this.setFastMode(!this.isFastModeEnabled());
+		if (!this.setFastMode(!this.isFastModeEnabled())) return false;
 		return this.isFastModeEnabled();
 	}
 
@@ -9417,7 +9546,11 @@ export class AgentSession {
 		// Modes that produce no LLM summary (snapcompact) have nothing to focus.
 		// Reject focus text loudly so programmatic callers don't silently lose
 		// instructions (the slash path pre-validates via parseCompactArgs).
-		if (compactMode?.rejectsFocus && customInstructions) {
+		// `internalGuidance` counts the same way — plan-mode approval never
+		// combines with a rejects-focus mode, but reject early if a caller ever
+		// wires it up so we don't silently drop the directive on the snapcompact
+		// fallback (issue #4359).
+		if (compactMode?.rejectsFocus && (customInstructions || options?.internalGuidance)) {
 			throw new Error(`/compact ${compactMode.name} does not take focus instructions.`);
 		}
 		const compactionAbortController = new AbortController();
@@ -9498,12 +9631,16 @@ export class AgentSession {
 
 			const compactionPrep = await this.#prepareCompactionFromHooks(preparation, hookCompaction);
 
-			// Strategy honored on manual /compact too. Custom instructions imply a
-			// directed LLM summary; a text-only model cannot read snapcompact frames.
-			// When snapcompact itself was requested, fail locally instead of silently
+			// Strategy honored on manual /compact too. Custom instructions (public
+			// user focus OR internal plan-mode guidance) imply a directed LLM
+			// summary; a text-only model cannot read snapcompact frames. When
+			// snapcompact itself was requested, fail locally instead of silently
 			// converting the "no LLM call" path into a provider-backed summary.
 			const wantsSnapcompact =
-				compactionPrep.kind !== "fromHook" && effectiveSettings.strategy === "snapcompact" && !customInstructions;
+				compactionPrep.kind !== "fromHook" &&
+				effectiveSettings.strategy === "snapcompact" &&
+				!customInstructions &&
+				!options?.internalGuidance;
 			const snapcompactReady = wantsSnapcompact;
 			const snapcompactShapeSetting = this.settings.get("snapcompact.shape");
 			let snapcompactShape: snapcompact.Shape | undefined;
@@ -9529,11 +9666,11 @@ export class AgentSession {
 					const percent = (renderScan.unrenderableRatio * 100).toFixed(1);
 					this.emitNotice(
 						"warning",
-						`snapcompact disabled: high non-ASCII rate detected (${percent}%). No LLM fallback was attempted.`,
+						`snapcompact disabled: unsupported characters for selected snapcompact font (${percent}%). No LLM fallback was attempted.`,
 						"compaction",
 					);
 					throw new Error(
-						`snapcompact cannot render this conversation locally: high non-ASCII rate detected (${percent}%).`,
+						`snapcompact cannot render this conversation locally: unsupported characters for selected snapcompact font (${percent}%).`,
 					);
 				}
 			}
@@ -9636,7 +9773,7 @@ export class AgentSession {
 				try {
 					const result = await this.#compactWithFallbackModel(
 						preparation,
-						customInstructions,
+						options?.internalGuidance ?? customInstructions,
 						compactionAbortController.signal,
 						{
 							promptOverride: this.#obfuscateTextForProvider(compactionPrep.hookPrompt),
@@ -9904,6 +10041,7 @@ export class AgentSession {
 			await this.sessionManager.flush();
 			this.#cancelOwnAsyncJobs();
 			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
+
 			this.#clearCheckpointRuntimeState();
 			// agent.reset() clears the core steering/follow-up queues. Preserve any queued
 			// steers/follow-ups (RPC/SDK steer()/followUp() issued during the handoff, or a
@@ -10386,6 +10524,133 @@ export class AgentSession {
 		return undefined;
 	}
 
+	#clearPendingRecoveredRetryErrors(): void {
+		this.#pendingRecoveredRetryErrors = [];
+	}
+
+	async #persistRetryLifecycleErrorMessage(message: AssistantMessage): Promise<void> {
+		await this.#waitForSessionMessagePersistence(message);
+		if (!isEmptyErrorTurn(message)) return;
+		if (this.#sessionMessageAlreadyPersisted(message)) return;
+		this.#appendSessionMessage(message);
+	}
+
+	#retryRecoveryKind(
+		id: number,
+		switchedCredential: boolean,
+		switchedModel: boolean,
+		delayMs: number,
+	): AssistantRetryRecoveryKind {
+		if (switchedCredential) return "credential";
+		if (switchedModel) return "model";
+		if (AIError.is(id, AIError.Flag.UsageLimit) && delayMs > 0) return "wait";
+		return "plain";
+	}
+
+	#retryRecoveryNote(recovery: AssistantRetryRecoveryKind, rateLimited: boolean): string {
+		const parts: string[] = [];
+		if (rateLimited) {
+			parts.push("rate-limited");
+		} else if (recovery === "plain") {
+			parts.push("error");
+		}
+		if (recovery === "credential") {
+			parts.push("switched account");
+		} else if (recovery === "model") {
+			parts.push("switched model");
+		} else if (recovery === "wait") {
+			parts.push("waited");
+		}
+		parts.push("retried");
+		return parts.join("; ");
+	}
+
+	async #recordPendingRecoveredRetryError(
+		message: AssistantMessage,
+		id: number,
+		options: { switchedCredential: boolean; switchedModel: boolean; delayMs: number },
+	): Promise<void> {
+		await this.#persistRetryLifecycleErrorMessage(message);
+		const persistenceKey = sessionMessagePersistenceKey(message);
+		if (!persistenceKey) return;
+		let branchEntry: SessionEntry | undefined;
+		for (const entry of this.sessionManager.getBranch().slice().reverse()) {
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+			if (sessionMessagePersistenceKey(entry.message) !== persistenceKey) continue;
+			if (!sameMessageContent(entry.message, message) && !this.#isSameAssistantMessage(entry.message, message)) {
+				continue;
+			}
+			branchEntry = entry;
+			break;
+		}
+		if (!branchEntry) return;
+		if (this.#pendingRecoveredRetryErrors.some(error => error.entryId === branchEntry.id)) return;
+		const rateLimited = AIError.is(id, AIError.Flag.UsageLimit);
+		const recovery = this.#retryRecoveryKind(id, options.switchedCredential, options.switchedModel, options.delayMs);
+		const note = this.#retryRecoveryNote(recovery, rateLimited);
+		this.#pendingRecoveredRetryErrors.push({
+			entryId: branchEntry.id,
+			persistenceKey,
+			recovery,
+			attempt: this.#retryAttempt,
+			note,
+		});
+	}
+
+	async #markPendingRecoveredRetryErrors(supersedingMessage: AssistantMessage): Promise<RecoveredRetryError[]> {
+		if (this.#pendingRecoveredRetryErrors.length === 0) return [];
+		const branch = this.sessionManager.getBranch();
+		const branchById = new Map<string, SessionEntry>();
+		for (const entry of branch) {
+			branchById.set(entry.id, entry);
+		}
+		const recoveredAt = new Date().toISOString();
+		const supersededBy: AssistantRetryRecovery["supersededBy"] = {
+			timestamp: supersedingMessage.timestamp,
+			provider: supersedingMessage.provider,
+			model: supersedingMessage.model,
+		};
+		if (supersedingMessage.responseId) {
+			supersededBy.responseId = supersedingMessage.responseId;
+		}
+		const recoveredErrors: RecoveredRetryError[] = [];
+		for (const pending of this.#pendingRecoveredRetryErrors) {
+			let entry = branchById.get(pending.entryId);
+			if (entry?.type !== "message" || entry.message.role !== "assistant") {
+				entry = branch
+					.slice()
+					.reverse()
+					.find(
+						candidate =>
+							candidate.type === "message" &&
+							candidate.message.role === "assistant" &&
+							sessionMessagePersistenceKey(candidate.message) === pending.persistenceKey,
+					);
+			}
+			if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
+			const retryRecovery: AssistantRetryRecovery = {
+				kind: "auto-retry",
+				status: "recovered",
+				attempt: pending.attempt,
+				recoveredAt,
+				recovery: pending.recovery,
+				note: pending.note,
+				supersededBy,
+			};
+			entry.message.retryRecovery = retryRecovery;
+			recoveredErrors.push({
+				entryId: entry.id,
+				persistenceKey: pending.persistenceKey,
+				note: retryRecovery.note,
+				retryRecovery,
+			});
+		}
+		if (recoveredErrors.length > 0) {
+			await this.sessionManager.rewriteEntries();
+		}
+		return recoveredErrors;
+	}
+
 	async #handleEmptyAssistantStop(assistantMessage: AssistantMessage): Promise<boolean> {
 		if (!this.#isEmptyAssistantStop(assistantMessage)) {
 			this.#emptyStopRetryCount = 0;
@@ -10406,6 +10671,7 @@ export class AgentSession {
 					attempt: this.#retryAttempt,
 					finalError: "Assistant returned empty stop after retry cap",
 				});
+				this.#clearPendingRecoveredRetryErrors();
 				this.#retryAttempt = 0;
 			}
 			this.#resolveRetry();
@@ -10593,7 +10859,7 @@ export class AgentSession {
 	}
 
 	#restoreFailedAssistantTurn(assistantMessage: AssistantMessage): void {
-		this.sessionManager.appendMessage(assistantMessage);
+		if (!isEmptyErrorTurn(assistantMessage)) this.sessionManager.appendMessage(assistantMessage);
 		const lastMessage = this.agent.state.messages.at(-1);
 		if (
 			lastMessage?.role === "assistant" &&
@@ -10696,6 +10962,7 @@ export class AgentSession {
 			});
 			this.sessionManager.branchWithSummary(null, report, { startedAt: checkpointState.startedAt });
 		}
+
 		const rewoundAt = new Date().toISOString();
 		const details = { report, startedAt: checkpointState.startedAt, rewoundAt };
 		this.sessionManager.appendCustomMessageEntry(
@@ -12188,7 +12455,7 @@ export class AgentSession {
 			// + a summary message carrying the imaged archive at FRAME_TOKEN_ESTIMATE
 			// per frame; #computeSnapcompactMaxFrames sizes the frame cap from the
 			// live window so we don't run snapcompact just to overflow every threshold
-			// tick. Any local blocker (non-ASCII transcript, kept-history too large,
+			// tick. Any local blocker (unsupported snapcompact glyphs, kept-history too large,
 			// post-render overflow) downgrades auto maintenance to a context-full LLM
 			// summary instead of wedging the session (#3659) — auto runs the default
 			// strategy on the user's behalf, so a fallback that lets the session keep
@@ -12210,11 +12477,11 @@ export class AgentSession {
 				const renderScan = snapcompact.scanRenderability(probeText, { shape });
 				if (!renderScan.isSafe) {
 					const percent = (renderScan.unrenderableRatio * 100).toFixed(1);
-					logger.warn("Snapcompact disabled: high non-ASCII rate detected", {
+					logger.warn("Snapcompact disabled: unsupported characters for selected snapcompact font", {
 						model: this.model?.id,
 						unrenderableRatio: renderScan.unrenderableRatio,
 					});
-					snapcompactBlocker = `snapcompact disabled: high non-ASCII rate detected (${percent}%); using context-full auto-compaction instead.`;
+					snapcompactBlocker = `snapcompact disabled: unsupported characters for selected snapcompact font (${percent}%); using context-full auto-compaction instead.`;
 				} else {
 					const maxFrames = this.#computeSnapcompactMaxFrames(preparation, compactionSettings);
 					if (maxFrames < 1) {
@@ -13258,6 +13525,7 @@ export class AgentSession {
 		}
 
 		if (this.#retryAttempt > retrySettings.maxRetries) {
+			await this.#persistRetryLifecycleErrorMessage(message);
 			// Max retries exceeded, emit final failure and reset
 			await this.#emitSessionEvent({
 				type: "auto_retry_end",
@@ -13265,6 +13533,7 @@ export class AgentSession {
 				attempt: this.#retryAttempt - 1,
 				finalError: message.errorMessage,
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#retryAttempt = 0;
 			this.#resolveRetry(); // Resolve so waitForRetry() completes
 			return false;
@@ -13376,6 +13645,7 @@ export class AgentSession {
 		// can act on it.
 		const maxDelayMs = retrySettings.maxDelayMs;
 		if (maxDelayMs > 0 && delayMs > maxDelayMs && !switchedCredential && !switchedModel) {
+			await this.#persistRetryLifecycleErrorMessage(message);
 			const attempt = this.#retryAttempt;
 			this.#retryAttempt = 0;
 			await this.#emitSessionEvent({
@@ -13384,10 +13654,13 @@ export class AgentSession {
 				attempt,
 				finalError: `Provider requested ${delayMs}ms wait, exceeds retry.maxDelayMs (${maxDelayMs}ms). Original error: ${errorMessage}`,
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#resolveRetry();
 			return false;
 		}
 
+		await this.#recordPendingRecoveredRetryError(message, id, { switchedCredential, switchedModel, delayMs });
+
 		await this.#emitSessionEvent({
 			type: "auto_retry_start",
 			attempt: this.#retryAttempt,
@@ -13425,6 +13698,7 @@ export class AgentSession {
 				attempt,
 				finalError: "Retry cancelled",
 			});
+			this.#clearPendingRecoveredRetryErrors();
 			this.#resolveRetry();
 			return false;
 		}
@@ -14097,9 +14371,17 @@ export class AgentSession {
 				continue;
 			}
 			if (event.type === "done") {
+				// A well-formed provider "done" event carries `content: AssistantContentBlock[]`,
+				// but a proxy/wrapper (custom extension providers, gateway-wrapped OAuth streams,
+				// see #4323) can hand back a message whose `content` was dropped or replaced with
+				// `undefined`. Downstream `.content.filter` at the sanitize step below would then
+				// crash the recap turn with `TypeError: undefined is not an object (evaluating
+				// 'H.content.filter')`. Normalize to `[]` so the recap surfaces an empty reply
+				// instead of turning a malformed side-channel response into a session-mute crash.
+				const rawContent = Array.isArray(event.message.content) ? event.message.content : [];
 				assistantMessage = this.#obfuscator?.hasSecrets()
-					? { ...event.message, content: deobfuscateAssistantContent(this.#obfuscator, event.message.content) }
-					: event.message;
+					? { ...event.message, content: deobfuscateAssistantContent(this.#obfuscator, rawContent) }
+					: { ...event.message, content: rawContent };
 				break;
 			}
 			if (event.type === "error") {
@@ -14133,7 +14415,7 @@ export class AgentSession {
 	#buildEphemeralSnapshot(promptText: string): AgentMessage[] {
 		const messages = [...this.messages];
 		const streaming = this.agent.state.streamMessage;
-		if (streaming && streaming.role === "assistant") {
+		if (streaming && streaming.role === "assistant" && Array.isArray(streaming.content)) {
 			const preservedBlocks: AssistantMessage["content"] = [];
 			// Preserve thinking blocks: DeepSeek-class encoders replay them as
 			// `reasoning_content` and reject the request (HTTP 400) when the field
@@ -14602,6 +14884,7 @@ export class AgentSession {
 		this.#cancelOwnAsyncJobs();
 
 		this.sessionManager.createBranchedSession(leafId);
+
 		this.#rehydrateCheckpointRewindState();
 		this.sessionManager.appendMessage({
 			role: "user",
@@ -14785,6 +15068,7 @@ export class AgentSession {
 		if (summaryText) {
 			// Create summary at target position (can be null for root)
 			const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);
+
 			summaryEntry = this.sessionManager.getEntry(summaryId) as BranchSummaryEntry;
 		} else if (newLeafId === null) {
 			// No summary, navigating to root - reset leaf
@@ -14869,6 +15153,7 @@ export class AgentSession {
 		let totalCacheRead = 0;
 		let totalReasoning = 0;
 		let totalCacheWrite = 0;
+		let totalTokens = 0;
 		let totalCost = 0;
 		let totalPremiumRequests = 0;
 
@@ -14889,6 +15174,7 @@ export class AgentSession {
 				totalReasoning += assistantMsg.usage.reasoningTokens ?? 0;
 				totalCacheRead += assistantMsg.usage.cacheRead;
 				totalCacheWrite += assistantMsg.usage.cacheWrite;
+				totalTokens += assistantMsg.usage.totalTokens;
 				totalPremiumRequests += assistantMsg.usage.premiumRequests ?? 0;
 				totalCost += assistantMsg.usage.cost.total;
 			}
@@ -14901,6 +15187,7 @@ export class AgentSession {
 					totalReasoning += usage.reasoningTokens ?? 0;
 					totalCacheRead += usage.cacheRead;
 					totalCacheWrite += usage.cacheWrite;
+					totalTokens += usage.totalTokens;
 					totalPremiumRequests += usage.premiumRequests ?? 0;
 					totalCost += usage.cost.total;
 				}
@@ -14921,7 +15208,7 @@ export class AgentSession {
 				reasoning: totalReasoning,
 				cacheRead: totalCacheRead,
 				cacheWrite: totalCacheWrite,
-				total: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
+				total: totalTokens,
 			},
 			cost: totalCost,
 			premiumRequests: totalPremiumRequests,
@@ -15567,6 +15854,7 @@ export class AgentSession {
 		let reasoning = 0;
 		let cacheRead = 0;
 		let cacheWrite = 0;
+		let totalTokens = 0;
 		let cost = 0;
 		let user = 0;
 		let assistant = 0;
@@ -15580,6 +15868,7 @@ export class AgentSession {
 				reasoning += assistantMsg.usage.reasoningTokens ?? 0;
 				cacheRead += assistantMsg.usage.cacheRead;
 				cacheWrite += assistantMsg.usage.cacheWrite;
+				totalTokens += assistantMsg.usage.totalTokens;
 				cost += assistantMsg.usage.cost.total;
 			}
 		}
@@ -15588,7 +15877,7 @@ export class AgentSession {
 			model,
 			contextWindow: model.contextWindow ?? 0,
 			contextTokens,
-			tokens: { input, output, reasoning, cacheRead, cacheWrite, total: input + output + cacheRead + cacheWrite },
+			tokens: { input, output, reasoning, cacheRead, cacheWrite, total: totalTokens },
 			cost,
 			messages: { user, assistant, total: messages.length },
 		};