@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

package/src/session/session-context.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "bun:test";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
 import * as snapcompact from "@oh-my-pi/snapcompact";
-import type { CompactionSummaryMessage } from "./messages";
+import { type CompactionSummaryMessage, INTERRUPTED_THINKING_MESSAGE_TYPE } from "./messages";
 import { buildSessionContext, type StrippedToolCallsMarker } from "./session-context";
 import type { SessionEntry } from "./session-entries";
 
@@ -159,3 +160,225 @@ describe("buildSessionContext dangling toolCalls", () => {
 		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
 	});
 });
+
+const assistantUsage: AssistantMessage["usage"] = {
+	input: 0,
+	output: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+	totalTokens: 0,
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
+function userEntry(id: string, parentId: string | null, content: string, messageTimestamp: number): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp,
+		message: { role: "user", content, timestamp: messageTimestamp } as AgentMessage,
+	};
+}
+
+function assistantEntry(
+	id: string,
+	parentId: string | null,
+	stopReason: AssistantMessage["stopReason"],
+	text: string,
+	messageTimestamp: number,
+): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp,
+		message: {
+			role: "assistant",
+			content: [{ type: "text", text }],
+			api: "anthropic-messages",
+			provider: "anthropic",
+			model: "claude-sonnet-4-5",
+			usage: assistantUsage,
+			stopReason,
+			timestamp: messageTimestamp,
+		} satisfies AssistantMessage,
+	};
+}
+
+function toolCallAssistantEntry(
+	id: string,
+	parentId: string | null,
+	stopReason: AssistantMessage["stopReason"],
+	toolCallId: string,
+	messageTimestamp: number,
+): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp,
+		message: {
+			role: "assistant",
+			content: [{ type: "toolCall", id: toolCallId, name: "write", arguments: { path: "plan.md", content: "x" } }],
+			api: "anthropic-messages",
+			provider: "anthropic",
+			model: "claude-sonnet-4-5",
+			usage: assistantUsage,
+			stopReason,
+			timestamp: messageTimestamp,
+		} satisfies AssistantMessage,
+	};
+}
+
+function syntheticToolResultEntry(
+	id: string,
+	parentId: string | null,
+	toolCallId: string,
+	messageTimestamp: number,
+): SessionEntry {
+	return {
+		type: "message",
+		id,
+		parentId,
+		timestamp,
+		message: {
+			role: "toolResult",
+			toolCallId,
+			toolName: "write",
+			content: [
+				{ type: "text", text: "Tool call was not executed because the provider stream ended with an error." },
+			],
+			details: { __synthetic: true, source: "assistant_stop_error", executed: false },
+			isError: true,
+			timestamp: messageTimestamp,
+		} as AgentMessage,
+	};
+}
+
+function hiddenContinuityEntry(id: string, parentId: string | null): SessionEntry {
+	return {
+		type: "custom_message",
+		id,
+		parentId,
+		timestamp,
+		customType: INTERRUPTED_THINKING_MESSAGE_TYPE,
+		content: "preserved interrupted thinking",
+		display: false,
+		attribution: "agent",
+	};
+}
+
+function expectUserTail(messages: AgentMessage[], content: string): void {
+	const tail = messages.at(-1);
+	expect(tail?.role).toBe("user");
+	if (tail?.role !== "user") {
+		throw new Error(`Expected user tail, received ${tail?.role ?? "none"}`);
+	}
+	expect(tail.content).toBe(content);
+}
+
+describe("buildSessionContext failed replay tails", () => {
+	it("terminates on cyclic parent links and includes each reachable message once", () => {
+		const entries = [userEntry("A", "B", "from A", 1), userEntry("B", "A", "from B", 2)];
+
+		const context = buildSessionContext(entries, "A");
+
+		expect(context.messages.map(message => (message.role === "user" ? message.content : message.role))).toEqual([
+			"from B",
+			"from A",
+		]);
+	});
+
+	it("omits a terminal aborted assistant from normal context", () => {
+		const context = buildSessionContext([
+			userEntry("user", null, "continue", 1),
+			assistantEntry("assistant", "user", "aborted", "partial unsafe replay", 2),
+		]);
+
+		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
+		expectUserTail(context.messages, "continue");
+	});
+
+	it("omits an earlier aborted assistant before a later user from normal context", () => {
+		const context = buildSessionContext([
+			userEntry("user-1", null, "first prompt", 1),
+			assistantEntry("assistant", "user-1", "aborted", "partial unsafe replay", 2),
+			userEntry("user-2", "assistant", "retry", 3),
+		]);
+
+		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
+		expectUserTail(context.messages, "retry");
+	});
+
+	it("preserves a terminal aborted assistant in transcript mode", () => {
+		const context = buildSessionContext(
+			[
+				userEntry("user", null, "continue", 1),
+				assistantEntry("assistant", "user", "aborted", "visible transcript error", 2),
+			],
+			undefined,
+			undefined,
+			{ transcript: true },
+		);
+
+		const assistant = context.messages.find(message => message.role === "assistant");
+		expect(assistant?.role).toBe("assistant");
+		if (assistant?.role !== "assistant") {
+			throw new Error(`Expected transcript assistant, received ${assistant?.role ?? "none"}`);
+		}
+		expect(assistant.stopReason).toBe("aborted");
+		expect(assistant.content).toEqual([{ type: "text", text: "visible transcript error" }]);
+	});
+
+	it("omits a terminal error assistant from normal context", () => {
+		const context = buildSessionContext([
+			userEntry("user", null, "retry with smaller input", 1),
+			assistantEntry("assistant", "user", "error", "provider rejected the request", 2),
+		]);
+
+		expect(context.messages.some(message => message.role === "assistant")).toBe(false);
+		expectUserTail(context.messages, "retry with smaller input");
+	});
+
+	it("keeps an aborted assistant when hidden interrupted-thinking continuity follows it", () => {
+		const context = buildSessionContext([
+			userEntry("user", null, "keep reasoning continuity", 1),
+			assistantEntry("assistant", "user", "aborted", "partial answer before interrupt", 2),
+			hiddenContinuityEntry("continuity", "assistant"),
+		]);
+
+		const assistant = context.messages.find(message => message.role === "assistant");
+		expect(assistant?.role).toBe("assistant");
+		if (assistant?.role !== "assistant") {
+			throw new Error(`Expected assistant before continuity, received ${assistant?.role ?? "none"}`);
+		}
+		expect(assistant.stopReason).toBe("aborted");
+		expect(context.messages.at(-1)?.role).toBe("custom");
+	});
+
+	it("drops synthetic tool results paired with a dropped failed tool-call turn", () => {
+		const context = buildSessionContext([
+			userEntry("user", null, "write the plan", 1),
+			toolCallAssistantEntry("assistant", "user", "error", "call-1", 2),
+			syntheticToolResultEntry("result", "assistant", "call-1", 3),
+		]);
+
+		expect(context.messages.map(message => message.role)).toEqual(["user"]);
+		expectUserTail(context.messages, "write the plan");
+	});
+
+	it("keeps the failed tool-call turn and its result in transcript mode", () => {
+		const context = buildSessionContext(
+			[
+				userEntry("user", null, "write the plan", 1),
+				toolCallAssistantEntry("assistant", "user", "error", "call-1", 2),
+				syntheticToolResultEntry("result", "assistant", "call-1", 3),
+			],
+			undefined,
+			undefined,
+			{ transcript: true, keepDanglingToolCalls: true },
+		);
+
+		expect(context.messages.map(message => message.role)).toEqual(["user", "assistant", "toolResult"]);
+	});
+});

package/src/session/session-context.ts

@@ -5,6 +5,7 @@ import {
 	createBranchSummaryMessage,
 	createCompactionSummaryMessage,
 	createCustomMessage,
+	INTERRUPTED_THINKING_MESSAGE_TYPE,
 	isCustomMessageContent,
 	normalizeCustomMessagePayload,
 } from "./messages";
@@ -17,6 +18,8 @@ import { type CompactionEntry, EPHEMERAL_MODEL_CHANGE_ROLE, type SessionEntry }
 const LEGACY_SNAPCOMPACT_FRAME_COUNT_GUARD = 16;
 const LEGACY_SNAPCOMPACT_ARCHIVE_TEXT_GUARD = 250_000;
 const LEGACY_SNAPCOMPACT_TRUNCATED_CHARS_GUARD = 1_000_000;
+const SUPERSEDED_COMPACTION_SUMMARY = "[Superseded compaction summary elided after a newer compaction]";
+const SUPERSEDED_COMPACTION_SHORT_SUMMARY = "Superseded compaction elided";
 
 function hasLegacySnapcompactFrames(archive: snapcompact.Archive): boolean {
 	return archive.frames.some(frame => frame.font === undefined && frame.variant === undefined);
@@ -197,10 +200,13 @@ export function buildSessionContext(
 		};
 	}
 
-	// Walk from leaf to root, collecting path
+	// Walk from leaf to root, collecting path. Corrupt/pre-fix files can contain
+	// parent cycles; stop at the first repeat so session load is bounded.
 	const path: SessionEntry[] = [];
+	const seenPathIds = new Set<string>();
 	let current: SessionEntry | undefined = leaf;
-	while (current) {
+	while (current && !seenPathIds.has(current.id)) {
+		seenPathIds.add(current.id);
 		path.push(current);
 		current = current.parentId ? byId.get(current.parentId) : undefined;
 	}
@@ -340,13 +346,14 @@ export function buildSessionContext(
 		for (const entry of path) {
 			handleEntryResetTracking(entry);
 			if (entry.type === "compaction") {
-				const snapcompactArchive = snapcompact.getPreservedArchive(entry.preserveData);
+				const active = entry.id === compaction?.id;
+				const snapcompactArchive = active ? snapcompact.getPreservedArchive(entry.preserveData) : undefined;
 				pushMessage(
 					createCompactionSummaryMessage(
-						entry.summary,
+						active ? entry.summary : SUPERSEDED_COMPACTION_SUMMARY,
 						entry.tokensBefore,
 						entry.timestamp,
-						entry.shortSummary,
+						active ? entry.shortSummary : SUPERSEDED_COMPACTION_SHORT_SUMMARY,
 						undefined,
 						undefined,
 						snapcompactHistoryBlocksForContext(snapcompactArchive, options),
@@ -498,6 +505,41 @@ export function buildSessionContext(
 		}
 	}
 
+	// Error/abort assistant turns are transcript events, not safe assistant
+	// turns to replay into the next provider request. Drop them even when a
+	// later user message follows through non-context entries (`session_exit`,
+	// labels, etc.); otherwise a resumed session replays a dead partial turn
+	// and can spend minutes reprocessing old context before the new prompt.
+	// Keep the interrupted-thinking continuity pair: convertToLlm strips the
+	// unsafe trailing thinking from that assistant and sends the hidden
+	// continuity note instead.
+	if (!options?.transcript) {
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const message = messages[i];
+			if (message?.role !== "assistant") continue;
+			if (message.stopReason !== "aborted" && message.stopReason !== "error") continue;
+			const next = messages[i + 1];
+			if (next?.role === "custom" && next.customType === INTERRUPTED_THINKING_MESSAGE_TYPE) continue;
+			// A failed turn that emitted tool calls persists paired synthetic
+			// tool_result placeholders after it. Dropping only the assistant would
+			// strand those results with no preceding tool_use — a shape providers
+			// reject — so remove the paired results alongside the turn.
+			const droppedToolCallIds = new Set<string>();
+			for (const block of message.content) {
+				if (block.type === "toolCall") droppedToolCallIds.add(block.id);
+			}
+			messages.splice(i, 1);
+			if (droppedToolCallIds.size > 0) {
+				for (let j = messages.length - 1; j >= i; j--) {
+					const candidate = messages[j];
+					if (candidate?.role === "toolResult" && droppedToolCallIds.has(candidate.toolCallId)) {
+						messages.splice(j, 1);
+					}
+				}
+			}
+		}
+	}
+
 	return {
 		messages,
 		cacheMissExplainedAt: options?.transcript ? cacheMissExplainedAt : undefined,

package/src/session/session-entries.ts

@@ -32,6 +32,12 @@ export interface SessionHeader {
 	titleSource?: SessionTitleSource;
 	timestamp: string;
 	cwd: string;
+	/**
+	 * Additional workspace directories beyond `cwd` (multi-root workspace).
+	 * Absolute, normalized, deduplicated. Absent on legacy single-cwd sessions.
+	 * See {@link SessionWorkspace} in `./session-workspace`.
+	 */
+	additionalDirectories?: string[];
 	parentSession?: string;
 	/** Provider prompt-cache identity inherited by exact-route full forks. */
 	providerPromptCacheKey?: string;
@@ -43,6 +49,8 @@ export interface NewSessionOptions {
 	providerPromptCacheKey?: string;
 	/** Skip flushing the current session and delete it instead of saving. */
 	drop?: boolean;
+	/** Additional workspace directories to seed on the new session. */
+	additionalDirectories?: string[];
 }
 
 export interface SessionEntryBase {

package/src/session/session-handoff.ts

@@ -0,0 +1,308 @@
+/** Handoff generation and session transition orchestration. */
+
+import * as path from "node:path";
+import {
+	type Agent,
+	type AgentMessage,
+	resolveTelemetry,
+	type StreamFn,
+	type ThinkingLevel,
+} from "@oh-my-pi/pi-agent-core";
+import { generateHandoffFromContext, renderHandoffPrompt } from "@oh-my-pi/pi-agent-core/compaction";
+import type { Message, Model, ServiceTier, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { ExtensionRunner, SessionBeforeSwitchResult } from "../extensibility/extensions";
+import { obfuscateProviderContext, type SecretObfuscator } from "../secrets/obfuscator";
+import type { HandoffResult, SessionHandoffOptions } from "./agent-session-types";
+import type { BashSessionTransition } from "./bash-runner";
+import type { SessionContext } from "./session-context";
+import type { SessionManager } from "./session-manager";
+
+function createHandoffContext(document: string): string {
+	return `<handoff-context>\n${document}\n</handoff-context>\n\nThe above is a handoff document from a previous session. Use this context to continue the work seamlessly.`;
+}
+
+function createHandoffFileName(date = new Date()): string {
+	const fileTimestamp = date.toISOString().replace(/[:.]/g, "-");
+	return `handoff-${fileTimestamp}.md`;
+}
+
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionHandoffHost {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	extensionRunner: ExtensionRunner | undefined;
+	sideStreamFn: StreamFn;
+	obfuscator: SecretObfuscator | undefined;
+	model(): Model | undefined;
+	thinkingLevel(): ThinkingLevel | undefined;
+	sessionId(): string;
+	sessionFile(): string | undefined;
+	baseSystemPrompt(): string[];
+	assertVibeSessionTransitionAllowed(action: string): void;
+	setSkipPostTurnMaintenance(timestamp: number | undefined): void;
+	obfuscateTextForProvider(text: string | undefined): string | undefined;
+	deobfuscateFromProvider(text: string): string;
+	convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
+	prepareSimpleStreamOptions(options: SimpleStreamOptions, provider?: string): SimpleStreamOptions;
+	effectiveServiceTier(model: Model | undefined): ServiceTier | undefined;
+	flushPendingBash(): Promise<void>;
+	beginBashSessionTransition(): BashSessionTransition;
+	markBashSessionTransition(transition: BashSessionTransition): void;
+	finishBashSessionTransition(transition: BashSessionTransition, success: boolean): void;
+	cancelOwnAsyncJobs(): void;
+	clearCheckpointRuntimeState(): void;
+	clearSessionScopedToolState(): void;
+	clearFreshProviderSessionId(): void;
+	syncAgentSessionId(): void;
+	rekeyMemoryForCurrentSessionId(): void;
+	resetMemoryContextForNewTranscript(): Promise<void>;
+	clearPendingNextTurnMessages(): void;
+	resetTodoCycle(): void;
+	buildDisplaySessionContext(): SessionContext;
+	resetAdvisorRuntimes(): void;
+	syncTodoPhasesFromBranch(): void;
+}
+
+/** Generates handoff documents and owns the handoff session transition. */
+export class SessionHandoff {
+	#handoffAbortController: AbortController | undefined;
+	readonly #host: SessionHandoffHost;
+
+	constructor(host: SessionHandoffHost) {
+		this.#host = host;
+	}
+	/**
+	 * Cancel in-progress handoff generation.
+	 */
+	abortHandoff(): void {
+		this.#handoffAbortController?.abort();
+	}
+
+	/**
+	 * Check if handoff generation is in progress.
+	 */
+	get isGeneratingHandoff(): boolean {
+		return this.#handoffAbortController !== undefined;
+	}
+
+	/**
+	 * Generate a handoff document with a oneshot LLM call, then start a new session with it.
+	 *
+	 * @param customInstructions Optional focus for the handoff document
+	 * @param options Handoff execution options
+	 * @returns The handoff document text, or undefined if cancelled/failed
+	 */
+	async handoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined> {
+		this.#host.assertVibeSessionTransitionAllowed("handoff to a new session");
+		const entries = this.#host.sessionManager.getBranch();
+		const messageCount = entries.filter(e => e.type === "message").length;
+
+		if (messageCount < 2) {
+			throw new Error("Nothing to hand off (no messages yet)");
+		}
+
+		this.#host.setSkipPostTurnMaintenance(undefined);
+
+		this.#handoffAbortController = new AbortController();
+		const handoffAbortController = this.#handoffAbortController;
+		const handoffSignal = handoffAbortController.signal;
+		const sourceSignal = options?.signal;
+		const onSourceAbort = () => {
+			if (!handoffSignal.aborted) {
+				handoffAbortController.abort();
+			}
+		};
+		if (sourceSignal) {
+			sourceSignal.addEventListener("abort", onSourceAbort, { once: true });
+			if (sourceSignal.aborted) {
+				onSourceAbort();
+			}
+		}
+
+		try {
+			if (handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+
+			const model = this.#host.model();
+			if (!model) {
+				throw new Error("No model selected for handoff");
+			}
+			const apiKey = await this.#host.modelRegistry.getApiKey(model, this.#host.sessionId());
+			if (!apiKey) {
+				throw new Error(`No API key for ${model.provider}`);
+			}
+
+			// Build the handoff request through the SAME pipeline a live turn uses
+			// (`runEphemeralTurn` / `/btw` share it) so the oneshot reads the
+			// provider prompt cache the main turn populated instead of cold-missing
+			// the whole prefix: identical system prompt, normalized tools, and
+			// transform-/obfuscation-matched message history via
+			// `convertMessagesToLlm` + `buildSideRequestContext`, plus the live turn's
+			// effective provider cache key with a unique side `sessionId` so
+			// OpenAI/Codex append-only state never mixes with the live turn.
+			const cacheSessionId = this.#host.sessionId();
+			// The loop sends `promptCacheKey` (providerPromptCacheKey) and falls back to
+			// the provider session id; providers route on `promptCacheKey ?? sessionId`.
+			// Both can diverge from this.#host.sessionId() (tan/subagent/shared sessions), so
+			// mirror exactly what the live turn populated the cache under.
+			const handoffPromptCacheKey = this.#host.agent.promptCacheKey ?? this.#host.agent.sessionId;
+			const handoffPromptText = renderHandoffPrompt(this.#host.obfuscateTextForProvider(customInstructions));
+			const handoffSnapshot: AgentMessage[] = [
+				...this.#host.agent.state.messages,
+				{
+					role: "user",
+					content: [{ type: "text", text: handoffPromptText }],
+					attribution: "agent",
+					timestamp: Date.now(),
+				},
+			];
+			const handoffLlmMessages = await this.#host.convertMessagesToLlm(handoffSnapshot, handoffSignal);
+			// Base system prompt, not a per-turn `before_agent_start` hook override —
+			// the handoff seeds a fresh session and must not carry prompt-specific
+			// hook state. Matches the prompt the old handoff path sent.
+			const handoffContext = await this.#host.agent.buildSideRequestContext(
+				handoffLlmMessages,
+				this.#host.baseSystemPrompt(),
+			);
+			const handoffStreamOptions = this.#host.prepareSimpleStreamOptions(
+				{
+					apiKey: this.#host.modelRegistry.resolver(model, cacheSessionId),
+					sessionId: `${cacheSessionId}:side:${Snowflake.next()}`,
+					promptCacheKey: handoffPromptCacheKey,
+					preferWebsockets: false,
+					serviceTier: this.#host.effectiveServiceTier(model),
+					hideThinkingSummary: this.#host.agent.hideThinkingSummary,
+					initiatorOverride: "agent",
+					signal: handoffSignal,
+				},
+				model.provider,
+			);
+			const rawHandoffText = await generateHandoffFromContext(
+				obfuscateProviderContext(this.#host.obfuscator, handoffContext),
+				model,
+				{
+					streamOptions: handoffStreamOptions,
+					completeImpl: async (requestModel, requestContext, requestOptions) => {
+						const stream = await this.#host.sideStreamFn(requestModel, requestContext, requestOptions);
+						return stream.result();
+					},
+					telemetry: resolveTelemetry(this.#host.agent.telemetry, this.#host.sessionId()),
+					// Honor the user's /model thinking selection on the handoff path.
+					// Clamped per-model inside generateHandoffFromContext via
+					// resolveCompactionEffort so unsupported-effort models don't trip
+					// requireSupportedEffort.
+					thinkingLevel: this.#host.thinkingLevel(),
+				},
+			);
+			const handoffText = this.#host.deobfuscateFromProvider(rawHandoffText);
+
+			if (handoffSignal.aborted) {
+				throw new Error("Handoff cancelled");
+			}
+			if (!handoffText) {
+				return undefined;
+			}
+
+			// Start a new session
+			const previousSessionFile = this.#host.sessionFile();
+			if (this.#host.extensionRunner?.hasHandlers("session_before_switch")) {
+				const result = (await this.#host.extensionRunner.emit({
+					type: "session_before_switch",
+					reason: "handoff",
+				})) as SessionBeforeSwitchResult | undefined;
+
+				if (result?.cancel) {
+					options?.onSwitchCancelled?.();
+					return undefined;
+				}
+			}
+			await this.#host.flushPendingBash();
+			await this.#host.sessionManager.flush();
+			const bashTransition = this.#host.beginBashSessionTransition();
+			this.#host.cancelOwnAsyncJobs();
+			let sessionTransitioned = false;
+			try {
+				await this.#host.sessionManager.newSession(
+					previousSessionFile ? { parentSession: previousSessionFile } : undefined,
+				);
+				this.#host.markBashSessionTransition(bashTransition);
+				sessionTransitioned = true;
+			} finally {
+				this.#host.finishBashSessionTransition(bashTransition, sessionTransitioned);
+			}
+
+			this.#host.clearSessionScopedToolState();
+
+			this.#host.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
+			// pre-loader TUI steer) so they survive into the post-handoff session instead of
+			// being silently dropped. Capture is synchronous immediately before reset and
+			// restore is synchronous immediately after — no await gap — so a steer arriving
+			// later (during ensureOnDisk/Bun.write below) appends to the restored queue
+			// rather than being clobbered.
+			const preservedSteering = this.#host.agent.peekSteeringQueue().slice();
+			const preservedFollowUp = this.#host.agent.peekFollowUpQueue().slice();
+			this.#host.agent.reset();
+			this.#host.agent.replaceQueues(preservedSteering, preservedFollowUp);
+			this.#host.clearFreshProviderSessionId();
+			this.#host.syncAgentSessionId();
+			this.#host.rekeyMemoryForCurrentSessionId();
+			await this.#host.resetMemoryContextForNewTranscript();
+			this.#host.clearPendingNextTurnMessages();
+			this.#host.resetTodoCycle();
+
+			// Inject the handoff document as a custom message
+			const handoffContent = createHandoffContext(handoffText);
+			this.#host.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");
+			await this.#host.sessionManager.ensureOnDisk();
+			let savedPath: string | undefined;
+			if (options?.autoTriggered && this.#host.settings.get("compaction.handoffSaveToDisk")) {
+				const artifactsDir = this.#host.sessionManager.getArtifactsDir();
+				if (artifactsDir) {
+					const handoffFilePath = path.join(artifactsDir, createHandoffFileName());
+					try {
+						await Bun.write(handoffFilePath, `${handoffText}\n`);
+						savedPath = handoffFilePath;
+					} catch (error) {
+						logger.warn("Failed to save handoff document to disk", {
+							path: handoffFilePath,
+							error: error instanceof Error ? error.message : String(error),
+						});
+					}
+				} else {
+					logger.debug("Skipping handoff document save because session is not persisted");
+				}
+			}
+
+			// Rebuild agent messages from session
+			const sessionContext = this.#host.buildDisplaySessionContext();
+			this.#host.agent.replaceMessages(sessionContext.messages);
+			this.#host.resetAdvisorRuntimes();
+			this.#host.syncTodoPhasesFromBranch();
+			if (this.#host.extensionRunner) {
+				await this.#host.extensionRunner.emit({
+					type: "session_switch",
+					reason: "handoff",
+					previousSessionFile,
+				});
+			}
+
+			return { document: handoffText, savedPath };
+		} catch (error) {
+			if (handoffSignal.aborted || (error instanceof Error && error.name === "AbortError")) {
+				throw new Error("Handoff cancelled");
+			}
+			throw error;
+		} finally {
+			sourceSignal?.removeEventListener("abort", onSourceAbort);
+			this.#handoffAbortController = undefined;
+		}
+	}
+}