@oh-my-pi/pi-coding-agent 13.15.2 → 13.16.0

package/src/session/agent-session.ts

@@ -53,7 +53,7 @@ import {
 import { abortableSleep, getAgentDbPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
 import type { AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
-import { MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "../config/model-registry";
+import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
 import { extractExplicitThinkingSelector, parseModelString, resolveModelRoleValue } from "../config/model-resolver";
 import { expandPromptTemplate, type PromptTemplate, renderPromptTemplate } from "../config/prompt-templates";
 import type { Settings, SkillsSettings } from "../config/settings";
@@ -269,7 +269,7 @@ export interface ModelCycleResult {
 export interface RoleModelCycleResult {
 	model: Model;
 	thinkingLevel: ThinkingLevel | undefined;
-	role: ModelRole;
+	role: string;
 }
 
 /** Session statistics for /session command */
@@ -1600,16 +1600,29 @@ export class AgentSession {
 			logger.warn("Async job completion deliveries still pending during dispose", { ...deliveryState });
 		}
 		await this.sessionManager.close();
-		for (const state of this.#providerSessionState.values()) {
-			state.close();
-		}
-		this.#providerSessionState.clear();
+		this.#closeAllProviderSessions("dispose");
 		this.#unsubscribePendingActionPush?.();
 		this.#unsubscribePendingActionPush = undefined;
 		this.#disconnectFromAgent();
 		this.#eventListeners = [];
 	}
 
+	#closeAllProviderSessions(reason: string): void {
+		for (const [providerKey, state] of this.#providerSessionState) {
+			try {
+				state.close();
+			} catch (error) {
+				logger.warn("Failed to close provider session state", {
+					providerKey,
+					reason,
+					error: String(error),
+				});
+			}
+		}
+
+		this.#providerSessionState.clear();
+	}
+
 	// =========================================================================
 	// Read-only State Access
 	// =========================================================================
@@ -2026,7 +2039,7 @@ export class AgentSession {
 		);
 	}
 
-	resolveRoleModel(role: ModelRole): Model | undefined {
+	resolveRoleModel(role: string): Model | undefined {
 		return this.#resolveRoleModel(role, this.#modelRegistry.getAvailable(), this.model);
 	}
 
@@ -2962,6 +2975,7 @@ export class AgentSession {
 		this.#disconnectFromAgent();
 		await this.abort();
 		this.#asyncJobManager?.cancelAll();
+		this.#closeAllProviderSessions("new session");
 		this.agent.reset();
 		await this.sessionManager.flush();
 		await this.sessionManager.newSession(options);
@@ -3082,7 +3096,7 @@ export class AgentSession {
 	 * Validates API key, saves to session and settings.
 	 * @throws Error if no API key available for the model
 	 */
-	async setModel(model: Model, role: ModelRole = "default"): Promise<void> {
+	async setModel(model: Model, role: string = "default"): Promise<void> {
 		const apiKey = await this.#modelRegistry.getApiKey(model, this.sessionId);
 		if (!apiKey) {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
@@ -3136,7 +3150,7 @@ export class AgentSession {
 	 * @param options - Optional settings: `temporary` to not persist to settings
 	 */
 	async cycleRoleModels(
-		roleOrder: readonly ModelRole[],
+		roleOrder: readonly string[],
 		options?: { temporary?: boolean },
 	): Promise<RoleModelCycleResult | undefined> {
 		const availableModels = this.#modelRegistry.getAvailable();
@@ -3146,7 +3160,7 @@ export class AgentSession {
 		if (!currentModel) return undefined;
 		const matchPreferences = { usageOrder: this.settings.getStorage()?.getModelUsageOrder() };
 		const roleModels: Array<{
-			role: ModelRole;
+			role: string;
 			model: Model;
 			thinkingLevel?: ThinkingLevel;
 			explicitThinkingLevel: boolean;
@@ -3176,9 +3190,10 @@ export class AgentSession {
 		if (roleModels.length <= 1) return undefined;
 
 		const lastRole = this.sessionManager.getLastModelChangeRole();
-		let currentIndex = lastRole
-			? roleModels.findIndex(entry => entry.role === lastRole)
-			: roleModels.findIndex(entry => modelsAreEqual(entry.model, currentModel));
+		let currentIndex = lastRole ? roleModels.findIndex(entry => entry.role === lastRole) : -1;
+		if (currentIndex === -1) {
+			currentIndex = roleModels.findIndex(entry => modelsAreEqual(entry.model, currentModel));
+		}
 		if (currentIndex === -1) currentIndex = 0;
 
 		const nextIndex = (currentIndex + 1) % roleModels.length;
@@ -4085,29 +4100,181 @@ export class AgentSession {
 	}
 
 	#closeProviderSessionsForModelSwitch(currentModel: Model, nextModel: Model): void {
-		if (currentModel.api !== "openai-codex-responses" && nextModel.api !== "openai-codex-responses") return;
+		const providerKeys = new Set<string>();
+		if (currentModel.api === "openai-codex-responses" || nextModel.api === "openai-codex-responses") {
+			providerKeys.add("openai-codex-responses");
+		}
+		if (currentModel.api === "openai-responses") {
+			providerKeys.add(`openai-responses:${currentModel.provider}`);
+		}
+		if (nextModel.api === "openai-responses") {
+			providerKeys.add(`openai-responses:${nextModel.provider}`);
+		}
 
-		const providerKey = "openai-codex-responses";
-		const state = this.#providerSessionState.get(providerKey);
-		if (!state) return;
+		for (const providerKey of providerKeys) {
+			const state = this.#providerSessionState.get(providerKey);
+			if (!state) continue;
 
-		try {
-			state.close();
-		} catch (error) {
-			logger.warn("Failed to close provider session state during model switch", {
-				providerKey,
-				error: String(error),
-			});
+			try {
+				state.close();
+			} catch (error) {
+				logger.warn("Failed to close provider session state during model switch", {
+					providerKey,
+					error: String(error),
+				});
+			}
+
+			this.#providerSessionState.delete(providerKey);
 		}
+	}
 
-		this.#providerSessionState.delete(providerKey);
+	#normalizeProviderReplayValue(value: unknown): unknown {
+		if (Array.isArray(value)) {
+			return value.map(item => this.#normalizeProviderReplayValue(item));
+		}
+		if (value && typeof value === "object") {
+			return Object.fromEntries(
+				Object.entries(value).map(([key, entryValue]) => [key, this.#normalizeProviderReplayValue(entryValue)]),
+			);
+		}
+		return value;
+	}
+
+	#normalizeSessionMessageForProviderReplay(message: AgentMessage): unknown {
+		switch (message.role) {
+			case "user":
+			case "developer":
+				return {
+					role: message.role,
+					content: this.#normalizeProviderReplayValue(message.content),
+					providerPayload: message.providerPayload,
+				};
+			case "assistant": {
+				const isResponsesFamilyMessage =
+					message.api === "openai-responses" || message.api === "openai-codex-responses";
+				return {
+					role: message.role,
+					content:
+						isResponsesFamilyMessage && Array.isArray(message.content)
+							? message.content.flatMap(block => {
+									if (block.type === "thinking") {
+										return [];
+									}
+									if (block.type === "toolCall") {
+										return [
+											{
+												type: block.type,
+												id: block.id,
+												name: block.name,
+												arguments: block.arguments,
+											},
+										];
+									}
+									if (block.type === "text") {
+										return [{ type: block.type, text: block.text, textSignature: block.textSignature }];
+									}
+									return [this.#normalizeProviderReplayValue(block)];
+								})
+							: this.#normalizeProviderReplayValue(message.content),
+					api: message.api,
+					provider: message.provider,
+					model: message.model,
+					stopReason: message.stopReason,
+					errorMessage: message.errorMessage,
+					providerPayload: isResponsesFamilyMessage ? undefined : message.providerPayload,
+				};
+			}
+			case "toolResult":
+				return {
+					role: message.role,
+					toolName: message.toolName,
+					toolCallId: message.toolCallId,
+					isError: message.isError,
+					content: this.#normalizeProviderReplayValue(message.content),
+				};
+			case "bashExecution":
+				return {
+					role: message.role,
+					command: message.command,
+					output: message.output,
+					exitCode: message.exitCode,
+					cancelled: message.cancelled,
+					meta: message.meta
+						? {
+								truncation: this.#normalizeProviderReplayValue(message.meta.truncation),
+								limits: this.#normalizeProviderReplayValue(message.meta.limits),
+								diagnostics: message.meta.diagnostics
+									? this.#normalizeProviderReplayValue({
+											summary: message.meta.diagnostics.summary,
+											messages: message.meta.diagnostics.messages,
+										})
+									: undefined,
+							}
+						: undefined,
+					excludeFromContext: message.excludeFromContext,
+				};
+			case "pythonExecution":
+				return {
+					role: message.role,
+					code: message.code,
+					output: message.output,
+					exitCode: message.exitCode,
+					cancelled: message.cancelled,
+					meta: message.meta
+						? {
+								truncation: this.#normalizeProviderReplayValue(message.meta.truncation),
+								limits: this.#normalizeProviderReplayValue(message.meta.limits),
+								diagnostics: message.meta.diagnostics
+									? this.#normalizeProviderReplayValue({
+											summary: message.meta.diagnostics.summary,
+											messages: message.meta.diagnostics.messages,
+										})
+									: undefined,
+							}
+						: undefined,
+					excludeFromContext: message.excludeFromContext,
+				};
+			case "custom":
+			case "hookMessage":
+				return {
+					role: message.role,
+					customType: message.customType,
+					content: this.#normalizeProviderReplayValue(message.content),
+				};
+			case "branchSummary":
+				return { role: message.role, summary: message.summary };
+			case "compactionSummary":
+				return {
+					role: message.role,
+					summary: message.summary,
+					providerPayload: message.providerPayload,
+				};
+			case "fileMention":
+				return {
+					role: message.role,
+					files: message.files.map(file => ({
+						path: file.path,
+						content: file.content,
+						image: file.image,
+					})),
+				};
+			default:
+				return this.#normalizeProviderReplayValue(message);
+		}
+	}
+
+	#didSessionMessagesChange(previousMessages: AgentMessage[], nextMessages: AgentMessage[]): boolean {
+		return (
+			JSON.stringify(previousMessages.map(message => this.#normalizeSessionMessageForProviderReplay(message))) !==
+			JSON.stringify(nextMessages.map(message => this.#normalizeSessionMessageForProviderReplay(message)))
+		);
 	}
 
 	#getModelKey(model: Model): string {
 		return `${model.provider}/${model.id}`;
 	}
 
-	#formatRoleModelValue(role: ModelRole, model: Model): string {
+	#formatRoleModelValue(role: string, model: Model): string {
 		const modelKey = `${model.provider}/${model.id}`;
 		const existingRoleValue = this.settings.getModelRole(role);
 		if (!existingRoleValue) return modelKey;
@@ -4129,7 +4296,7 @@ export class AgentSession {
 		return availableModels.find(m => m.provider === currentModel.provider && m.id === configuredTarget);
 	}
 
-	#resolveRoleModel(role: ModelRole, availableModels: Model[], currentModel: Model | undefined): Model | undefined {
+	#resolveRoleModel(role: string, availableModels: Model[], currentModel: Model | undefined): Model | undefined {
 		const roleModelStr =
 			role === "default"
 				? (this.settings.getModelRole("default") ??
@@ -5035,7 +5202,9 @@ export class AgentSession {
 	 */
 	async switchSession(sessionPath: string): Promise<boolean> {
 		const previousSessionFile = this.sessionManager.getSessionFile();
-
+		const switchingToDifferentSession = previousSessionFile
+			? path.resolve(previousSessionFile) !== path.resolve(sessionPath)
+			: true;
 		// Emit session_before_switch event (can be cancelled)
 		if (this.#extensionRunner?.hasHandlers("session_before_switch")) {
 			const result = (await this.#extensionRunner.emit({
@@ -5051,68 +5220,149 @@ export class AgentSession {
 
 		this.#disconnectFromAgent();
 		await this.abort();
+
+		// Flush pending writes before switching so restore snapshots reflect committed state.
+		await this.sessionManager.flush();
+		const previousSessionState = this.sessionManager.captureState();
+		const previousSessionContext = this.sessionManager.buildSessionContext();
+		// switchSession replaces these arrays wholesale during load/rollback, so retaining
+		// the existing message objects is sufficient and avoids structured-clone failures for
+		// extension/custom metadata that is valid to persist but not cloneable.
+		const previousAgentMessages = [...this.agent.state.messages];
+		const previousSteeringMessages = [...this.#steeringMessages];
+		const previousFollowUpMessages = [...this.#followUpMessages];
+		const previousPendingNextTurnMessages = [...this.#pendingNextTurnMessages];
+		const previousScheduledHiddenNextTurnGeneration = this.#scheduledHiddenNextTurnGeneration;
+		const previousModel = this.model;
+		const previousThinkingLevel = this.#thinkingLevel;
+		const previousServiceTier = this.agent.serviceTier;
+		const previousSelectedMCPToolNames = new Set(this.#selectedMCPToolNames);
+		const previousTools = [...this.agent.state.tools];
+		const previousBaseSystemPrompt = this.#baseSystemPrompt;
+		const previousSystemPrompt = this.agent.state.systemPrompt;
+		const previousFallbackSelectedMCPToolNames = previousSessionFile
+			? this.#getSessionDefaultSelectedMCPToolNames(previousSessionFile)
+			: undefined;
+
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
 		this.#pendingNextTurnMessages = [];
 		this.#scheduledHiddenNextTurnGeneration = undefined;
 
-		// Flush pending writes before switching
-		await this.sessionManager.flush();
-
-		// Set new session
-		await this.sessionManager.setSessionFile(sessionPath);
-		this.agent.sessionId = this.sessionManager.getSessionId();
-
-		// Reload messages
-		const sessionContext = this.sessionManager.buildSessionContext();
-		const fallbackSelectedMCPToolNames = this.#getSessionDefaultSelectedMCPToolNames(sessionPath);
-		await this.#restoreMCPSelectionsForSessionContext(sessionContext, { fallbackSelectedMCPToolNames });
+		try {
+			await this.sessionManager.setSessionFile(sessionPath);
+			this.agent.sessionId = this.sessionManager.getSessionId();
 
-		// Emit session_switch event to hooks
-		if (this.#extensionRunner) {
-			await this.#extensionRunner.emit({
-				type: "session_switch",
-				reason: "resume",
-				previousSessionFile,
-			});
-		}
+			const sessionContext = this.sessionManager.buildSessionContext();
+			const didReloadConversationChange =
+				!switchingToDifferentSession &&
+				this.#didSessionMessagesChange(previousSessionContext.messages, sessionContext.messages);
+			const fallbackSelectedMCPToolNames = this.#getSessionDefaultSelectedMCPToolNames(sessionPath);
+			await this.#restoreMCPSelectionsForSessionContext(sessionContext, { fallbackSelectedMCPToolNames });
 
-		this.agent.replaceMessages(sessionContext.messages);
-		this.#syncTodoPhasesFromBranch();
+			// Emit session_switch event to hooks
+			if (this.#extensionRunner) {
+				await this.#extensionRunner.emit({
+					type: "session_switch",
+					reason: "resume",
+					previousSessionFile,
+				});
+			}
 
-		// Restore model if saved
-		const defaultModelStr = sessionContext.models.default;
-		if (defaultModelStr) {
-			const slashIdx = defaultModelStr.indexOf("/");
-			if (slashIdx > 0) {
-				const provider = defaultModelStr.slice(0, slashIdx);
-				const modelId = defaultModelStr.slice(slashIdx + 1);
-				const availableModels = this.#modelRegistry.getAvailable();
-				const match = availableModels.find(m => m.provider === provider && m.id === modelId);
-				if (match) {
-					this.#setModelWithProviderSessionReset(match);
+			this.agent.replaceMessages(sessionContext.messages);
+			this.#syncTodoPhasesFromBranch();
+			if (switchingToDifferentSession) {
+				this.#closeAllProviderSessions("session switch");
+			} else if (didReloadConversationChange) {
+				this.#closeAllProviderSessions("session reload");
+			}
+
+			// Restore model if saved
+			const defaultModelStr = sessionContext.models.default;
+			if (defaultModelStr) {
+				const slashIdx = defaultModelStr.indexOf("/");
+				if (slashIdx > 0) {
+					const provider = defaultModelStr.slice(0, slashIdx);
+					const modelId = defaultModelStr.slice(slashIdx + 1);
+					const availableModels = this.#modelRegistry.getAvailable();
+					const match = availableModels.find(m => m.provider === provider && m.id === modelId);
+					if (match) {
+						const currentModel = this.model;
+						const shouldResetProviderState =
+							switchingToDifferentSession ||
+							(currentModel !== undefined &&
+								(currentModel.provider !== match.provider ||
+									currentModel.id !== match.id ||
+									currentModel.api !== match.api));
+						if (shouldResetProviderState) {
+							this.#setModelWithProviderSessionReset(match);
+						} else {
+							this.agent.setModel(match);
+						}
+					}
 				}
 			}
-		}
 
-		const hasThinkingEntry = this.sessionManager.getBranch().some(entry => entry.type === "thinking_level_change");
-		const hasServiceTierEntry = this.sessionManager.getBranch().some(entry => entry.type === "service_tier_change");
-		const defaultThinkingLevel = this.settings.get("defaultThinkingLevel");
-		const configuredServiceTier = this.settings.get("serviceTier");
-		const nextThinkingLevel = resolveThinkingLevelForModel(
-			this.model,
-			hasThinkingEntry ? (sessionContext.thinkingLevel as ThinkingLevel | undefined) : defaultThinkingLevel,
-		);
-		this.#thinkingLevel = nextThinkingLevel;
-		this.agent.setThinkingLevel(toReasoningEffort(nextThinkingLevel));
-		this.agent.serviceTier = hasServiceTierEntry
-			? sessionContext.serviceTier
-			: configuredServiceTier === "none"
-				? undefined
-				: configuredServiceTier;
+			const hasThinkingEntry = this.sessionManager.getBranch().some(entry => entry.type === "thinking_level_change");
+			const hasServiceTierEntry = this.sessionManager
+				.getBranch()
+				.some(entry => entry.type === "service_tier_change");
+			const defaultThinkingLevel = this.settings.get("defaultThinkingLevel");
+			const configuredServiceTier = this.settings.get("serviceTier");
+			const nextThinkingLevel = resolveThinkingLevelForModel(
+				this.model,
+				hasThinkingEntry ? (sessionContext.thinkingLevel as ThinkingLevel | undefined) : defaultThinkingLevel,
+			);
+			this.#thinkingLevel = nextThinkingLevel;
+			this.agent.setThinkingLevel(toReasoningEffort(nextThinkingLevel));
+			this.agent.serviceTier = hasServiceTierEntry
+				? sessionContext.serviceTier
+				: configuredServiceTier === "none"
+					? undefined
+					: configuredServiceTier;
 
-		this.#reconnectToAgent();
-		return true;
+			this.#reconnectToAgent();
+			return true;
+		} catch (error) {
+			this.sessionManager.restoreState(previousSessionState);
+			this.agent.sessionId = previousSessionState.sessionId;
+			let restoreMcpError: unknown;
+			try {
+				await this.#restoreMCPSelectionsForSessionContext(previousSessionContext, {
+					fallbackSelectedMCPToolNames: previousFallbackSelectedMCPToolNames,
+				});
+			} catch (mcpError) {
+				restoreMcpError = mcpError;
+				logger.warn("Failed to restore MCP selections after switch error", {
+					previousSessionFile,
+					targetSessionFile: sessionPath,
+					error: String(mcpError),
+				});
+				this.#selectedMCPToolNames = new Set(previousSelectedMCPToolNames);
+				this.agent.setTools(previousTools);
+				this.#baseSystemPrompt = previousBaseSystemPrompt;
+				this.agent.setSystemPrompt(previousSystemPrompt);
+			}
+			this.#baseSystemPrompt = previousBaseSystemPrompt;
+			this.agent.setSystemPrompt(previousSystemPrompt);
+			this.agent.replaceMessages(previousAgentMessages);
+			this.#steeringMessages = previousSteeringMessages;
+			this.#followUpMessages = previousFollowUpMessages;
+			this.#pendingNextTurnMessages = previousPendingNextTurnMessages;
+			this.#scheduledHiddenNextTurnGeneration = previousScheduledHiddenNextTurnGeneration;
+			if (previousModel) {
+				this.agent.setModel(previousModel);
+			}
+			this.#thinkingLevel = previousThinkingLevel;
+			this.agent.setThinkingLevel(toReasoningEffort(previousThinkingLevel));
+			this.agent.serviceTier = previousServiceTier;
+			this.#syncTodoPhasesFromBranch();
+			this.#reconnectToAgent();
+			if (restoreMcpError) {
+				throw restoreMcpError;
+			}
+			throw error;
+		}
 	}
 
 	/**
@@ -5124,7 +5374,10 @@ export class AgentSession {
 	 *   - selectedText: The text of the selected user message (for editor pre-fill)
 	 *   - cancelled: True if a hook cancelled the branch
 	 */
-	async branch(entryId: string): Promise<{ selectedText: string; cancelled: boolean }> {
+	async branch(entryId: string): Promise<{
+		selectedText: string;
+		cancelled: boolean;
+	}> {
 		const previousSessionFile = this.sessionFile;
 		const selectedEntry = this.sessionManager.getEntry(entryId);
 
@@ -5202,7 +5455,12 @@ export class AgentSession {
 	async navigateTree(
 		targetId: string,
 		options: { summarize?: boolean; customInstructions?: string } = {},
-	): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }> {
+	): Promise<{
+		editorText?: string;
+		cancelled: boolean;
+		aborted?: boolean;
+		summaryEntry?: BranchSummaryEntry;
+	}> {
 		const oldLeafId = this.sessionManager.getLeafId();
 
 		// No-op if already at target

package/src/session/messages.ts

@@ -6,6 +6,7 @@
  */
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type {
+	AssistantMessage,
 	ImageContent,
 	Message,
 	MessageAttribution,
@@ -213,6 +214,28 @@ export function createCompactionSummaryMessage(
 	};
 }
 
+export function sanitizeRehydratedOpenAIResponsesAssistantMessage(message: AssistantMessage): AssistantMessage {
+	if (message.providerPayload?.type !== "openaiResponsesHistory") {
+		return message;
+	}
+
+	let didSanitize = false;
+	const sanitizedContent = message.content.map(block => {
+		if (block.type !== "thinking" || block.thinkingSignature === undefined) {
+			return block;
+		}
+
+		didSanitize = true;
+		return { ...block, thinkingSignature: undefined };
+	});
+
+	if (!didSanitize) {
+		return message;
+	}
+
+	return { ...message, content: sanitizedContent };
+}
+
 /** Convert CustomMessageEntry to AgentMessage format */
 export function createCustomMessage(
 	customType: string,

package/src/session/session-manager.ts

@@ -46,6 +46,7 @@ import {
 	type FileMentionMessage,
 	type HookMessage,
 	type PythonExecutionMessage,
+	sanitizeRehydratedOpenAIResponsesAssistantMessage,
 } from "./messages";
 import type { SessionStorage, SessionStorageWriter } from "./session-storage";
 import { FileSessionStorage, MemorySessionStorage } from "./session-storage";
@@ -1374,6 +1375,15 @@ export async function resolveResumableSession(
 
 	return { session: globalMatch, scope: "global" };
 }
+interface SessionManagerStateSnapshot {
+	sessionId: string;
+	sessionName: string | undefined;
+	sessionFile: string | undefined;
+	flushed: boolean;
+	needsFullRewriteOnNextPersist: boolean;
+	fileEntries: FileEntry[];
+}
+
 export class SessionManager {
 	#sessionId: string = "";
 	#sessionName: string | undefined;
@@ -1419,6 +1429,39 @@ export class SessionManager {
 		return this.#blobStore.put(data);
 	}
 
+	captureState(): SessionManagerStateSnapshot {
+		return {
+			sessionId: this.#sessionId,
+			sessionName: this.#sessionName,
+			sessionFile: this.#sessionFile,
+			flushed: this.#flushed,
+			needsFullRewriteOnNextPersist: this.#needsFullRewriteOnNextPersist,
+			// Snapshot entry objects by reference: switch/reload replaces the active entry array,
+			// so rollback does not need structured cloning of extension/custom details.
+			fileEntries: [...this.#fileEntries],
+		};
+	}
+
+	restoreState(snapshot: SessionManagerStateSnapshot): void {
+		this.#sessionId = snapshot.sessionId;
+		this.#sessionName = snapshot.sessionName;
+		this.#sessionFile = snapshot.sessionFile;
+		this.#flushed = snapshot.flushed;
+		this.#needsFullRewriteOnNextPersist = snapshot.needsFullRewriteOnNextPersist;
+		this.#fileEntries = [...snapshot.fileEntries];
+		this.#persistWriter = undefined;
+		this.#persistWriterPath = undefined;
+		this.#persistChain = Promise.resolve();
+		this.#persistError = undefined;
+		this.#persistErrorReported = false;
+		this.#artifactManager = null;
+		this.#artifactManagerSessionFile = null;
+		this.#buildIndex();
+		if (this.#sessionFile) {
+			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+		}
+	}
+
 	/** Initialize with a specific session file (used by factory methods) */
 	async #initSessionFile(sessionFile: string): Promise<void> {
 		await this.setSessionFile(sessionFile);
@@ -1445,6 +1488,7 @@ export class SessionManager {
 			this.#needsFullRewriteOnNextPersist = migrateToCurrentVersion(this.#fileEntries);
 
 			await resolveBlobRefsInEntries(this.#fileEntries, this.#blobStore);
+			this.sanitizeLoadedOpenAIResponsesReplayMetadata();
 
 			this.#buildIndex();
 			this.#flushed = true;
@@ -2300,6 +2344,26 @@ export class SessionManager {
 		return buildSessionContext(this.getEntries(), this.#leafId, this.#byId);
 	}
 
+	/** Strip stale OpenAI Responses assistant replay metadata from loaded in-memory entries. */
+	sanitizeLoadedOpenAIResponsesReplayMetadata(): boolean {
+		let didSanitize = false;
+		for (const entry of this.#fileEntries) {
+			if (entry.type !== "message" || entry.message.role !== "assistant") {
+				continue;
+			}
+
+			const sanitizedMessage = sanitizeRehydratedOpenAIResponsesAssistantMessage(entry.message);
+			if (sanitizedMessage === entry.message) {
+				continue;
+			}
+
+			entry.message = sanitizedMessage;
+			didSanitize = true;
+		}
+
+		return didSanitize;
+	}
+
 	/**
 	 * Get session header.
 	 */
@@ -2548,6 +2612,7 @@ export class SessionManager {
 		newHeader.title = sourceHeader?.title;
 		manager.#fileEntries = [newHeader, ...historyEntries];
 		manager.#sessionName = newHeader.title;
+		manager.sanitizeLoadedOpenAIResponsesReplayMetadata();
 		manager.#buildIndex();
 		await manager.#rewriteFile();
 		return manager;