@gajae-code/coding-agent 0.11.9 → 0.11.11

package/src/session/agent-session.ts

@@ -172,6 +172,7 @@ import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../a
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
 import type { CasReceipt } from "../config/atomic-yaml-patch";
+import { activateModelProfile } from "../config/model-profile-activation";
 import {
 	GJC_MODEL_ASSIGNMENT_TARGETS,
 	isAuthenticated,
@@ -233,7 +234,7 @@ import type {
 	TurnEndEvent,
 	TurnStartEvent,
 } from "../extensibility/extensions";
-import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
+import type { CompactOptions, ContextUsage, ExtensionTranscriptEntry } from "../extensibility/extensions/types";
 import { ExtensionToolWrapper } from "../extensibility/extensions/wrapper";
 import {
 	type LoadedSubskillActivation,
@@ -243,7 +244,13 @@ import { resolveCurrentPhaseForParent } from "../extensibility/gjc-plugins/injec
 import { readActiveSubskillsForParent, toActiveSubskillEntry } from "../extensibility/gjc-plugins/state";
 import { loadActiveSubskillTools } from "../extensibility/gjc-plugins/tools";
 import type { HookCommandContext } from "../extensibility/hooks/types";
-import { buildSkillPromptMessage, type Skill, type SkillWarning } from "../extensibility/skills";
+import {
+	buildSkillPromptMessage,
+	getSkillSlashCommandName,
+	parseSkillInvocations,
+	type Skill,
+	type SkillWarning,
+} from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { assertDeepInterviewIntentManifest } from "../gjc-runtime/deep-interview-state";
 import { buildGjcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
@@ -341,6 +348,7 @@ import {
 import {
 	type ConfiguredFallbackChain,
 	cappedExponentialWithFullJitter,
+	compactionRetryDelay,
 	effectiveFallbackDelay,
 	FallbackChainController,
 } from "./fallback-chain-controller";
@@ -379,6 +387,7 @@ import type {
 	CompactionEntry,
 	DefaultModelSelectionStage,
 	NewSessionOptions,
+	PreparedNewSession,
 	RecoveryHydrationContext,
 	RecoveryHydrationPromotionFence,
 	SessionContext,
@@ -798,8 +807,14 @@ const KIMI_CODE_FIRST_EVENT_TIMEOUT_MESSAGES = {
 
 const ALIBABA_TOKEN_PLAN_PROVIDER = "alibaba-token-plan";
 const ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MESSAGES = {
-	"openai-responses": "OpenAI responses stream timed out while waiting for the first event",
-	"openai-completions": "OpenAI completions stream timed out while waiting for the first event",
+	"openai-responses": new Set([
+		"Provider stream timed out while waiting for the first event",
+		"OpenAI responses stream timed out while waiting for the first event",
+	]),
+	"openai-completions": new Set([
+		"Provider stream timed out while waiting for the first event",
+		"OpenAI completions stream timed out while waiting for the first event",
+	]),
 } as const;
 
 function hasBareDefaultRetryDisqualifyingFacts(message: AssistantMessage): boolean {
@@ -1043,17 +1058,37 @@ 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.`;
 }
 
+async function discardPreparedNewSessionAfterFailure(
+	sessionManager: SessionManager,
+	prepared: PreparedNewSession,
+	transitionError: unknown,
+): Promise<unknown> {
+	try {
+		await sessionManager.discardPreparedNewSession(prepared);
+	} catch (cleanupError) {
+		throw new AggregateError(
+			[transitionError, cleanupError],
+			"Session transition and staged successor cleanup both failed.",
+		);
+	}
+	return transitionError;
+}
+
 // ============================================================================
 // ACP Permission Gate
 // ============================================================================
 
 /** Tools that require user permission before execution when an ACP client is connected. */
-const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "monitor", "edit", "delete", "move"]);
+const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "monitor", "eval", "edit", "delete", "move"]);
 
 function isShellExecutionPermissionTool(toolName: string): boolean {
 	return toolName === "bash" || toolName === "monitor";
 }
 
+function isExecutionPermissionTool(toolName: string): boolean {
+	return isShellExecutionPermissionTool(toolName) || toolName === "eval";
+}
+
 /** Permission options presented to the client on each gated tool call. */
 const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
 	{ optionId: "allow_once", name: "Allow once", kind: "allow_once" },
@@ -1121,6 +1156,18 @@ function getPermissionIntent(
 		const cmd = getStringProperty(a, "command")?.slice(0, 80);
 		return { toolName, title: cmd || toolName, cacheKey: toolName };
 	}
+	if (toolName === "eval") {
+		const cells = Array.isArray(a.cells) ? a.cells : [];
+		const firstCell = cells.find(cell => cell && typeof cell === "object" && !Array.isArray(cell));
+		const cell = firstCell as Record<string, unknown> | undefined;
+		const title = cell ? getStringProperty(cell, "title") : undefined;
+		const language = cell ? getStringProperty(cell, "language") : undefined;
+		return {
+			toolName,
+			title: title ?? (language ? `Eval ${language}` : "eval"),
+			cacheKey: toolName,
+		};
+	}
 	if (toolName === "delete") {
 		const p = getStringProperty(a, "path");
 		return { toolName, title: p ? `Delete ${p}` : toolName, paths: p ? [p] : undefined, cacheKey: toolName };
@@ -3992,8 +4039,21 @@ export class AgentSession {
 						return;
 					}
 					const predecessorAgentEnd = this.#claimDeferredAgentEndForContinuation(predecessorAgentEndHold);
+					const startsQueuedSuccessor =
+						this.agent.state.messages.at(-1)?.role === "assistant" && this.agent.hasQueuedMessages();
 					try {
-						await this.agent.continue(this.#managedFallbackPromptOptions());
+						await this.agent.continue({
+							...this.#managedFallbackPromptOptions(),
+							// Reset only after continue() has claimed the queued turn. Skipped or stale
+							// continuations retain predecessor accounting, and resetAttemptBudget keeps
+							// the sticky fallback cursor unchanged.
+							onRunAccepted: startsQueuedSuccessor
+								? () => {
+										this.#defaultFallbackChain().resetAttemptBudget();
+										this.#overflowMaintenanceAttempts = 0;
+									}
+								: undefined,
+						});
 					} catch (error) {
 						this.#restoreDeferredAgentEndAfterContinuationFailure(predecessorAgentEnd);
 						throw error;
@@ -4596,13 +4656,13 @@ export class AgentSession {
 		return resolveToCwd(normalized, this.sessionManager.getCwd());
 	}
 
-	#localProtocolOptions(): LocalProtocolOptions {
+	#localProtocolOptions(prepared?: PreparedNewSession): LocalProtocolOptions {
 		return {
-			getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
+			getArtifactsDir: () => prepared?.artifactsDir ?? this.sessionManager.getArtifactsDir(),
 			isManagedDestination: () => this.sessionManager.isManagedDestination(),
-			// Required for verified legacy local:// migration on managed sessions (#2797 / #2925).
-			getManagedLegacyLocalMigrationSource: () => this.sessionManager.getManagedLegacyLocalMigrationSource(),
-			getSessionId: () => this.sessionManager.getSessionId(),
+			getManagedLegacyLocalMigrationSource: () =>
+				prepared?.managedLegacyLocalMigrationSource ?? this.sessionManager.getManagedLegacyLocalMigrationSource(),
+			getSessionId: () => prepared?.sessionId ?? this.sessionManager.getSessionId(),
 		};
 	}
 
@@ -5502,6 +5562,12 @@ export class AgentSession {
 		return undefined;
 	}
 
+	/** Get a registered tool with the same guards used for model-facing execution. */
+	getToolForExecution(name: string): AgentTool | undefined {
+		const tool = this.getToolByName(name);
+		return tool ? this.#prepareToolForExecution(tool) : undefined;
+	}
+
 	/**
 	 * Register a UI/control-plane request handler for a currently foregrounded
 	 * managed bash execution. This is intentionally narrower than generic
@@ -5766,6 +5832,7 @@ export class AgentSession {
 						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
 					}
 					const isShellExecutionTool = isShellExecutionPermissionTool(target.name);
+					const isExecutionTool = isExecutionPermissionTool(target.name);
 					const command =
 						isShellExecutionTool && args && typeof args === "object" && !Array.isArray(args)
 							? getStringProperty(args as Record<string, unknown>, "command")
@@ -5808,7 +5875,7 @@ export class AgentSession {
 								toolCallId,
 								toolName: target.name,
 								title: permissionIntent.title,
-								...(isShellExecutionTool ? { kind: "execute" } : {}),
+								...(isExecutionTool ? { kind: "execute" } : {}),
 								status: "pending",
 								rawInput: args,
 								...(commandContent ? { content: commandContent } : {}),
@@ -6456,6 +6523,15 @@ export class AgentSession {
 		return { ...context, messages: this.#withoutEphemeralCustomMessages(context.messages) };
 	}
 
+	/** Build display context from an unpublished successor without changing active session state. @internal */
+	buildPreparedDisplaySessionContext(prepared: PreparedNewSession): SessionContext {
+		const context = deobfuscateSessionContext(
+			this.sessionManager.buildPreparedNewSessionContext(prepared),
+			this.#obfuscator,
+		);
+		return { ...context, messages: this.#withoutEphemeralCustomMessages(context.messages) };
+	}
+
 	/** Convert session messages using the same pre-LLM pipeline as the active session. */
 	async convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]> {
 		const transformedMessages = await this.#transformContext(messages, signal);
@@ -6563,9 +6639,11 @@ export class AgentSession {
 	/** Live SDK configuration values exposed through the session query surface. */
 	getSdkConfigItems(): Record<string, string> {
 		const model = this.model;
+		const modelPreset = this.getActiveModelProfile() ?? this.settings.get("modelProfile.default");
 		return {
 			mode: this.#planModeState?.enabled ? "plan" : "default",
 			...(model ? { model: `${model.provider}/${model.id}` } : {}),
+			...(modelPreset ? { modelPreset } : {}),
 			thinking: this.#thinkingLevel ?? "off",
 			steeringMode: this.steeringMode,
 			followUpMode: this.followUpMode,
@@ -6584,6 +6662,7 @@ export class AgentSession {
 	async invokeSkill(
 		name: string,
 		args = "",
+		options?: Pick<PromptOptions, "onPreflightAccepted">,
 	): Promise<{ name: string; path: string; args?: string; lineCount?: number }> {
 		const skillName = name.trim();
 		if (!skillName) throw Object.assign(new Error("skill.invoke requires a skill name."), { code: "invalid_input" });
@@ -6616,7 +6695,7 @@ export class AgentSession {
 			attribution: "user" as const,
 		};
 		this.#deepInterviewPreclaimedCustomInputEpochs.set(skillPromptMessage, deepInterviewUserIntentEpoch);
-		await this.promptCustomMessage(skillPromptMessage);
+		await this.promptCustomMessage(skillPromptMessage, options);
 		return {
 			name: skill.name,
 			path: skill.filePath,
@@ -6662,22 +6741,49 @@ export class AgentSession {
 		}
 	}
 
-	getTranscript(): Array<{ id: string; role: string; textSummary: string; ts: string; body: string }> {
+	getTranscript(): ExtensionTranscriptEntry[] {
 		return getEntriesForInternalRead(this.sessionManager).flatMap(entry => {
 			if (entry.type !== "message") return [];
-			const message = entry.message as unknown as { role?: unknown; content?: unknown };
+			const message = entry.message as unknown as {
+				role?: unknown;
+				content?: unknown;
+				toolCallId?: unknown;
+				toolName?: unknown;
+				isError?: unknown;
+			};
+			const content: NonNullable<ExtensionTranscriptEntry["content"]> | undefined = Array.isArray(message.content)
+				? message.content.reduce<NonNullable<ExtensionTranscriptEntry["content"]>>((blocks, part) => {
+						if (typeof part !== "object" || part === null || !("type" in part)) return blocks;
+						if (part.type === "text" && "text" in part && typeof part.text === "string") {
+							blocks.push({ type: "text", text: part.text });
+							return blocks;
+						}
+						if (part.type === "thinking" && "thinking" in part && typeof part.thinking === "string") {
+							blocks.push({ type: "thinking", thinking: part.thinking });
+							return blocks;
+						}
+						if (
+							part.type === "toolCall" &&
+							"id" in part &&
+							typeof part.id === "string" &&
+							"name" in part &&
+							typeof part.name === "string"
+						) {
+							blocks.push({
+								type: "toolCall",
+								id: part.id,
+								name: part.name,
+								arguments: "arguments" in part ? part.arguments : {},
+							});
+						}
+						return blocks;
+					}, [])
+				: undefined;
 			const body =
 				typeof message.content === "string"
 					? message.content
-					: Array.isArray(message.content)
-						? message.content
-								.map(part =>
-									typeof part === "object" && part !== null && "text" in part && typeof part.text === "string"
-										? part.text
-										: "",
-								)
-								.filter(Boolean)
-								.join("\n")
+					: content
+						? content.flatMap(part => (part.type === "text" ? [part.text] : [])).join("\n")
 						: "";
 			return [
 				{
@@ -6686,6 +6792,10 @@ export class AgentSession {
 					textSummary: body.slice(0, 500),
 					ts: entry.timestamp,
 					body,
+					...(content ? { content } : {}),
+					...(typeof message.toolCallId === "string" ? { toolCallId: message.toolCallId } : {}),
+					...(typeof message.toolName === "string" ? { toolName: message.toolName } : {}),
+					...(typeof message.isError === "boolean" ? { isError: message.isError } : {}),
 				},
 			];
 		});
@@ -6723,8 +6833,7 @@ export class AgentSession {
 		return getAskAnswerSourceFromRegistry(this.sessionId);
 	}
 
-	#constructWorkflowGateEmitter(): WorkflowGateEmitter {
-		const sessionId = this.sessionManager.getSessionId();
+	#constructWorkflowGateEmitter(sessionId = this.sessionManager.getSessionId()): WorkflowGateEmitter {
 		assertNonEmptyGjcSessionId(sessionId, "AgentSession workflow-gate session");
 		const gateStore = this.sessionManager.isPersisted()
 			? new FileGateStore(path.join(sessionStateDir(this.sessionManager.getCwd(), sessionId), "workflow-gates.json"))
@@ -7243,6 +7352,22 @@ export class AgentSession {
 	async prompt(text: string, options?: PromptOptions): Promise<void> {
 		const expandPromptTemplates = options?.expandPromptTemplates ?? true;
 
+		if (expandPromptTemplates && text.startsWith("/skill:") && !options?.images?.length) {
+			const skillCommands = new Map(this.skills.map(skill => [getSkillSlashCommandName(skill), skill]));
+			const invocations = parseSkillInvocations(text, skillCommands);
+			if (invocations.length === 1) {
+				const invocation = invocations[0];
+				if (invocation) {
+					await this.invokeSkill(
+						invocation.skill.name,
+						invocation.args,
+						options?.onPreflightAccepted ? { onPreflightAccepted: options.onPreflightAccepted } : undefined,
+					);
+					return;
+				}
+			}
+		}
+
 		// Handle extension commands first (execute immediately, even during streaming)
 		if (expandPromptTemplates && text.startsWith("/")) {
 			const handled = await this.#tryExecuteExtensionCommand(text);
@@ -7422,7 +7547,7 @@ export class AgentSession {
 
 	async promptCustomMessage<T = unknown>(
 		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">,
-		options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy">,
+		options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice" | "followUpQueuePolicy" | "onPreflightAccepted">,
 	): Promise<void> {
 		const textContent =
 			typeof message.content === "string"
@@ -7530,7 +7655,11 @@ export class AgentSession {
 			}
 
 			// Validate API key
-			const apiKey = await this.#modelRegistry.getApiKey(this.model, this.sessionId);
+			const apiKey = await this.#awaitPromptPreflight(
+				generation,
+				preflightSignal,
+				this.#modelRegistry.getApiKey(this.model, this.sessionId, { signal: preflightSignal }),
+			);
 			if (!apiKey) {
 				throw new Error(formatNoCredentialOnboardingError(this.model.provider));
 			}
@@ -7817,6 +7946,7 @@ export class AgentSession {
 				return tool ? { safeSummary: tool.safeSummary, safeSummaryFields: tool.safeSummaryFields } : undefined;
 			},
 			cycleModel: () => this.cycleModel(),
+			setModelProfile: name => this.activateModelProfileForControl(name),
 			cycleThinkingLevel: () => this.cycleThinkingLevel(),
 			setQueueMode: (kind, mode) => {
 				if (kind === "steering" && (mode === "all" || mode === "one-at-a-time")) {
@@ -7844,6 +7974,7 @@ export class AgentSession {
 			getJobs: () => undefined,
 			sdkBindings: () => [
 				"cycleModel",
+				"setModelProfile",
 				"cycleThinkingLevel",
 				"setQueueMode",
 				"getSkillState",
@@ -9012,7 +9143,14 @@ export class AgentSession {
 			this.#rebindProviderSessionState(new Map());
 			this.agent.reset();
 			if (!options?.drop) await this.sessionManager.flush();
-			await this.sessionManager.newSession(options);
+			const prepared = await this.sessionManager.prepareNewSession(options);
+			try {
+				// Last fallible gate while public getters still show the predecessor (#3138).
+				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				this.sessionManager.commitPreparedNewSession(prepared);
+			} catch (error) {
+				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
+			}
 			this.setTodoPhases([]);
 			this.#syncAgentSessionId();
 			this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
@@ -9074,12 +9212,18 @@ export class AgentSession {
 			if (!(await manager.cancelAndSettleOwnerJobs(ownerId))) {
 				throw new Error("Owned async jobs did not settle before session replacement.");
 			}
-
+			const prepared = await this.sessionManager.prepareNewSession(options);
+			try {
+				// Last fallible gate while public getters still show the predecessor (#3138).
+				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				this.sessionManager.commitPreparedNewSession(prepared);
+			} catch (error) {
+				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
+			}
 			this.#disconnectFromAgent();
 			this.#closeAllProviderSessions("new session");
 			this.#rebindProviderSessionState(new Map());
 			this.agent.reset();
-			await this.sessionManager.newSession(options);
 			this.setTodoPhases([]);
 			this.#syncAgentSessionId();
 			this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
@@ -9122,10 +9266,17 @@ export class AgentSession {
 		}
 		this.sessionManager.appendServiceTierChange(this.serviceTier ?? null);
 		if (nextDiscoverySessionToolNames) {
-			await this.#applyActiveToolsByName(nextDiscoverySessionToolNames, {
-				persistMCPSelection: false,
-				nextSelectedDiscoveredBuiltinToolNames: [],
-			});
+			// Avoid a full system-prompt rebuild when the active set is unchanged; rebuild
+			// can block on shared workspace-tree work across repeated /new transitions.
+			const current = this.getActiveToolNames().slice().sort().join("\0");
+			const next = [...new Set(nextDiscoverySessionToolNames.map(n => n.toLowerCase()))].sort().join("\0");
+			if (current !== next) {
+				await this.#applyActiveToolsByName(nextDiscoverySessionToolNames, {
+					persistMCPSelection: false,
+					nextSelectedDiscoveredBuiltinToolNames: [],
+				});
+			} else {
+			}
 		}
 		this.#todoReminderCount = 0;
 		this.#planReferenceSent = false;
@@ -9138,6 +9289,7 @@ export class AgentSession {
 				reason: "new",
 				previousSessionFile,
 			});
+		} else {
 		}
 	}
 
@@ -9217,13 +9369,18 @@ export class AgentSession {
 			// Flush current session to ensure all entries are written
 			await this.sessionManager.flush();
 
-			// Fork the session (creates new session file with same entries)
-			const forkResult = await this.sessionManager.fork();
-			if (!forkResult) {
+			// Prepare the copied successor and complete local:// readiness while all
+			// public manager getters remain bound to the predecessor.
+			const prepared = await this.sessionManager.prepareFork();
+			if (!prepared) {
 				return false;
 			}
-
-			// Update agent session ID
+			try {
+				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				this.sessionManager.commitPreparedNewSession(prepared);
+			} catch (error) {
+				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
+			}
 			this.#syncAgentSessionId();
 			this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
 			this.#rekeyHindsightMemoryForCurrentSessionId();
@@ -9312,6 +9469,17 @@ export class AgentSession {
 		return this.#activeModelProfile;
 	}
 
+	/** Activate a complete model profile through a nonvisual session control. */
+	async activateModelProfileForControl(profileName: string): Promise<boolean> {
+		await activateModelProfile({
+			session: this,
+			modelRegistry: this.#modelRegistry,
+			settings: this.settings,
+			profileName,
+		});
+		return this.getActiveModelProfile() === profileName;
+	}
+
 	/** Return the persisted configured fallback selectors for a model role. */
 	getConfiguredModelChain(role: string): readonly string[] | undefined {
 		return getSessionContextForInternalRead(this.sessionManager).configuredModelChains[role]?.entries;
@@ -10614,22 +10782,36 @@ export class AgentSession {
 			// user work that agent.reset() would otherwise clear.
 			const rollbackAgentSteeringQueue = this.agent.snapshotSteering();
 			const rollbackAgentFollowUpQueue = this.agent.snapshotFollowUp();
-			let successorSessionFile: string | undefined;
 			let savedPath: string | undefined;
 			let committed = false;
-			// Suspend (do not destroy) the workflow-gate emitter so it can be fenced on
-			// commit or resumed on rollback. Suspension runs inside the transaction so a
-			// listener fault during suspension is rolled back like any other prepare step.
-			let suspendedWorkflowGateEmitter: WorkflowGateEmitter | undefined;
+			let prepared: PreparedNewSession | undefined;
 			try {
-				suspendedWorkflowGateEmitter = this.#suspendWorkflowGateEmitter(rollbackSessionState.sessionId);
-				// --- Prepare (reversible): build and persist the successor session
-				// without touching predecessor authority. No irreversible predecessor
-				// teardown or identity publication happens until the commit boundary.
-				await this.sessionManager.newSession(
+				// Prepare successor entries, persistence, display state, and gate
+				// construction without publishing manager identity. Managed local-root
+				// readiness is the last fallible step before the sole commit (#3138).
+				prepared = await this.sessionManager.prepareNewSession(
 					previousSessionFile ? { parentSession: previousSessionFile } : undefined,
 				);
-				successorSessionFile = this.sessionFile;
+				if (model) this.sessionManager.appendPreparedModelChange(prepared, `${model.provider}/${model.id}`);
+				this.sessionManager.appendPreparedThinkingLevelChange(prepared, this.thinkingLevel);
+				this.sessionManager.appendPreparedServiceTierChange(prepared, this.serviceTier ?? null);
+				this.sessionManager.appendPreparedCustomMessageEntry(
+					prepared,
+					"handoff",
+					createHandoffContext(handoffText),
+					true,
+					undefined,
+					"agent",
+				);
+				await this.sessionManager.ensurePreparedNewSessionOnDisk(prepared);
+				const sessionContext = this.buildPreparedDisplaySessionContext(prepared);
+				const successorGateEmitter = this.#constructWorkflowGateEmitter(prepared.sessionId);
+				// Last fallible action: verified local:// readiness from immutable staged options.
+				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+
+				// --- Commit boundary: synchronous adoption is the sole identity publication.
+				this.sessionManager.commitPreparedNewSession(prepared);
+				committed = true;
 				this.agent.reset();
 				this.#syncAgentSessionId();
 				this.#rekeyHindsightMemoryForCurrentSessionId();
@@ -10638,16 +10820,8 @@ export class AgentSession {
 				this.#pendingNextTurnMessages = [];
 				this.#scheduledHiddenNextTurnGeneration = undefined;
 				this.#todoReminderCount = 0;
-				if (model) {
-					this.sessionManager.appendModelChange(`${model.provider}/${model.id}`);
-				}
-				this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
-				this.sessionManager.appendServiceTierChange(this.serviceTier ?? null);
-
-				// Inject the handoff document as a custom message
-				const handoffContent = createHandoffContext(handoffText);
-				this.sessionManager.appendCustomMessageEntry("handoff", handoffContent, true, undefined, "agent");
-				await this.sessionManager.ensureOnDisk();
+				this.agent.replaceMessages(sessionContext.messages);
+				this.#syncTodoPhasesFromBranch();
 				if (options?.autoTriggered && this.settings.get("compaction.handoffSaveToDisk")) {
 					try {
 						const artifactId = await this.sessionManager.saveArtifact(`${handoffText}\n`, "handoff");
@@ -10659,30 +10833,9 @@ export class AgentSession {
 					}
 				}
 
-				// Rebuild agent messages from session
-				const sessionContext = this.buildDisplaySessionContext();
-				this.agent.replaceMessages(sessionContext.messages);
-				this.#syncTodoPhasesFromBranch();
-
-				// Construct the successor workflow-gate emitter in the reversible window:
-				// FileGateStore load / broker init can throw, and a failure here must roll
-				// back rather than corrupt an already-committed switch. Publication is
-				// deferred to the (no-throw) commit step below.
-				const successorGateEmitter = this.#constructWorkflowGateEmitter();
-
-				// --- Commit boundary: the successor is durably persisted and every
-				// reversible, fallible step above has succeeded. Cross the irreversible
-				// commit BEFORE any identity rotation. Fencing the predecessor gate
-				// emitter and rotating provider sessions cannot be undone, so once we
-				// begin them a failure must RETAIN the committed successor rather than
-				// attempt a (now-impossible) rollback that would resume a fenced emitter.
-				committed = true;
+				// The forward-only suffix starts only after the committed successor is live.
 				this.#resetInjectedContextSignatures();
-				this.#publishWorkflowGateEmitter(
-					successorGateEmitter,
-					rollbackSessionState.sessionId,
-					suspendedWorkflowGateEmitter,
-				);
+				this.#publishWorkflowGateEmitter(successorGateEmitter, rollbackSessionState.sessionId);
 				this.#closeAllProviderSessions("session handoff");
 				this.#rebindProviderSessionState(new Map());
 				this.#resetHindsightConversationTrackingIfHindsight();
@@ -10718,12 +10871,12 @@ export class AgentSession {
 				return { document: handoffText, savedPath };
 			} catch (switchError) {
 				if (committed) {
-					// The switch already committed; a post-commit step failed. Do not
-					// tear down the new session — surface success (the handoff exists).
-					logger.warn("Handoff post-commit step failed after the session switch committed", {
-						error: switchError instanceof Error ? switchError.message : String(switchError),
+					throw Object.assign(new Error("Handoff committed but successor initialization was degraded."), {
+						code: "handoff_committed_degraded",
+						cause: switchError,
+						handoffDocument: handoffText,
+						savedPath,
 					});
-					return { document: handoffText, savedPath };
 				}
 				// Reversible window: roll back to the pre-handoff session so the
 				// failure is non-destructive. Predecessor gate emitter, provider
@@ -10731,7 +10884,6 @@ export class AgentSession {
 				// were never mutated before commit, so they survive intact.
 				this.sessionManager.restoreState(rollbackSessionState);
 				this.#syncAgentSessionId(rollbackSessionState.sessionId);
-				this.#restoreWorkflowGateEmitter(suspendedWorkflowGateEmitter);
 				this.#rekeyHindsightMemoryForCurrentSessionId();
 				this.agent.replaceMessages(rollbackAgentMessages);
 				this.agent.clearAllQueues();
@@ -10743,25 +10895,17 @@ export class AgentSession {
 				this.#scheduledHiddenNextTurnGeneration = rollbackScheduledHiddenNextTurnGeneration;
 				this.#todoReminderCount = rollbackTodoReminderCount;
 				this.#syncTodoPhasesFromBranch();
-				// Remove the orphaned successor transcript/artifacts written before the
-				// failure so a rolled-back handoff leaves nothing behind.
-				if (successorSessionFile && successorSessionFile !== previousSessionFile) {
-					try {
-						await this.sessionManager.discardUncommittedSession(successorSessionFile);
-					} catch (cleanupError) {
-						logger.warn("Failed to remove orphaned handoff session after rollback", {
-							path: successorSessionFile,
-							error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
-						});
-					}
-				}
+				// Exact-discard only the staged successor; predecessor state was never adopted.
+				const rollbackError = prepared
+					? await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, switchError)
+					: switchError;
 				// Map to cancellation only for a genuine handoff-signal abort; a
 				// downstream error keeps its cause and the generated document.
 				if (handoffSignal.aborted) {
 					throw new Error("Handoff cancelled");
 				}
 				// Preserve the generated handoff document for copy/retry.
-				throw Object.assign(switchError instanceof Error ? switchError : new Error(String(switchError)), {
+				throw Object.assign(rollbackError instanceof Error ? rollbackError : new Error(String(rollbackError)), {
 					handoffDocument: handoffText,
 				});
 			}
@@ -10769,7 +10913,7 @@ export class AgentSession {
 			// Genuine handoff-signal cancellation maps to a cancellation error.
 			// Errors surfaced by the inner transaction (which already rolled back
 			// and, for non-aborts, attached the generated document) pass through.
-			if (handoffSignal.aborted) {
+			if (handoffSignal.aborted && !(error instanceof AggregateError)) {
 				throw new Error("Handoff cancelled");
 			}
 			throw error;
@@ -12459,8 +12603,14 @@ export class AgentSession {
 								break;
 							}
 
-							const baseDelayMs = retrySettings.baseDelayMs * 2 ** attempt;
-							const delayMs = retryAfterMs !== undefined ? Math.max(baseDelayMs, retryAfterMs) : baseDelayMs;
+							// Legacy parsed Retry-After is capped at retry.maxDelayMs (see
+							// compactionRetryDelay); only managed fallback is uncapped.
+							const delayMs = compactionRetryDelay(
+								retrySettings.baseDelayMs,
+								retrySettings.maxDelayMs,
+								attempt,
+								retryAfterMs,
+							);
 
 							// If retry delay is too long (>30s), try next candidate instead of waiting
 							const maxAcceptableDelayMs = 30_000;
@@ -12653,7 +12803,7 @@ export class AgentSession {
 		);
 	}
 
-	#alibabaTokenPlanCanonicalTimeoutForApi(api: string): string | undefined {
+	#alibabaTokenPlanTimeoutMessagesForApi(api: string): ReadonlySet<string> | undefined {
 		if (api === "openai-responses" || api === "openai-completions") {
 			return ALIBABA_TOKEN_PLAN_FIRST_EVENT_TIMEOUT_MESSAGES[api];
 		}
@@ -12662,18 +12812,23 @@ export class AgentSession {
 
 	#isAlibabaTokenPlanFirstEventTimeout(message: AssistantMessage): boolean {
 		if (message.stopReason !== "error" || message.provider !== ALIBABA_TOKEN_PLAN_PROVIDER) return false;
-		const canonicalMessage = this.#alibabaTokenPlanCanonicalTimeoutForApi(message.api);
-		return canonicalMessage !== undefined && message.errorMessage === canonicalMessage;
+		const timeoutMessages = this.#alibabaTokenPlanTimeoutMessagesForApi(message.api);
+		return timeoutMessages?.has(message.errorMessage ?? "") ?? false;
 	}
 
 	#isAlibabaTokenPlanCompactionTimeout(candidate: Model, errorMessage: string): boolean {
 		if (candidate.provider !== ALIBABA_TOKEN_PLAN_PROVIDER) return false;
-		const canonicalMessage = this.#alibabaTokenPlanCanonicalTimeoutForApi(candidate.api);
-		if (canonicalMessage === undefined) return false;
-		return (
-			errorMessage === `Summarization failed: ${canonicalMessage}` ||
-			errorMessage === `Turn prefix summarization failed: ${canonicalMessage}`
-		);
+		const timeoutMessages = this.#alibabaTokenPlanTimeoutMessagesForApi(candidate.api);
+		if (!timeoutMessages) return false;
+		for (const timeoutMessage of timeoutMessages) {
+			if (
+				errorMessage === `Summarization failed: ${timeoutMessage}` ||
+				errorMessage === `Turn prefix summarization failed: ${timeoutMessage}`
+			) {
+				return true;
+			}
+		}
+		return false;
 	}
 
 	#isTerminalProviderFirstEventTimeout(message: AssistantMessage): boolean {
@@ -13025,7 +13180,7 @@ export class AgentSession {
 		}
 		if (this.#isTerminalProviderFirstEventTimeout(outcome.failure.message)) {
 			// The managed transport discarded this attempt before session policy saw it.
-			// Remove its provisional controller charge and surface the original message.
+			// Remove its provisional charge without changing sticky fallback selection.
 			this.#defaultFallbackChain().discardStartedAttempt();
 			return {
 				type: "terminal",
@@ -14557,6 +14712,12 @@ export class AgentSession {
 
 			try {
 				await this.sessionManager.setSessionFile(sessionPath);
+				// The successor identity is already rotated in the manager but not yet
+				// published; gate its local:// root before publication so the agent,
+				// workflow-gate emitter, and hooks cannot resolve against an ungated
+				// root. The manager-rotation window itself is tracked in #3138
+				// (#2797 / #2925).
+				if (switchingToDifferentSession) await initializeLocalRoot(this.#localProtocolOptions());
 				this.#syncAgentSessionId();
 				this.#rekeyHindsightMemoryForCurrentSessionId();
 
@@ -14633,13 +14794,8 @@ export class AgentSession {
 				await this.sessionManager.ensureOnDisk();
 
 				if (switchingToDifferentSession) {
-					// Interactive /resume (and any other switchSession identity change) must
-					// await verified legacy local:// migration for the *new* session before
-					// post-commit session_switch / local path resolution. createAgentSession
-					// already does this at cold start (#2797); switchSession previously omitted
-					// it, so resolving local:// after /resume could fail-closed with
-					// "legacy migration must complete before path resolution" (#2925).
-					await initializeLocalRoot(this.#localProtocolOptions());
+					// The local:// migration gate for this successor already ran above,
+					// before the identity was published (#2797 / #2925).
 					this.#resetHindsightConversationTrackingIfHindsight();
 					this.#resetIrcRosterDeliveryState();
 				}
@@ -14758,19 +14914,21 @@ export class AgentSession {
 				skipConversationRestore = result?.skipConversationRestore ?? false;
 			}
 
-			// Clear pending messages (bound to old session state)
+			// Flush pending writes before preparing the successor.
+			await this.sessionManager.flush();
+			const prepared = selectedEntry.parentId
+				? await this.sessionManager.prepareBranchedSession(selectedEntry.parentId)
+				: await this.sessionManager.prepareNewSession({ parentSession: previousSessionFile });
+			try {
+				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				this.sessionManager.commitPreparedNewSession(prepared);
+			} catch (error) {
+				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
+			}
 			this.#pendingNextTurnMessages = [];
 			this.#scheduledHiddenNextTurnGeneration = undefined;
-
-			// Flush pending writes before branching
-			await this.sessionManager.flush();
 			this.#cancelOwnAsyncJobs();
 
-			if (!selectedEntry.parentId) {
-				await this.sessionManager.newSession({ parentSession: previousSessionFile });
-			} else {
-				this.sessionManager.createBranchedSession(selectedEntry.parentId);
-			}
 			this.#syncTodoPhasesFromBranch();
 			this.#syncAgentSessionId();
 			this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);