@gajae-code/coding-agent 0.12.10 → 0.12.12

package/src/session/agent-session.ts

@@ -184,7 +184,7 @@ import {
 } from "@gajae-code/utils";
 
 import { createAppendOnlyContextManager, resolveAppendOnlyMode } from "../append-only-mode";
-import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager, type OwnerSubagentShutdownLease } from "../async";
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
 import type { CasReceipt } from "../config/atomic-yaml-patch";
@@ -427,6 +427,7 @@ import {
 	getLatestCompactionEntry,
 	getSessionMessageEntryId,
 	getSessionMessageObservationId,
+	SessionAppendPersistenceError,
 	transferSessionMessageIdentity,
 } from "./session-manager";
 import { getEntriesForInternalRead, getSessionContextForInternalRead } from "./session-manager-internal";
@@ -609,6 +610,8 @@ export interface AgentSessionConfig {
 	discoveryMode?: "off" | "mcp-only" | "all";
 	/** MCP tool names to activate for the current session when discovery mode is enabled. */
 	initialSelectedMCPToolNames?: string[];
+	/** Keep persisted MCP names until a deferred exact catalog becomes available. */
+	preserveUnavailableInitialMCPToolSelection?: boolean;
 	/** Built-in discoverable tool names restored for the current all-discovery session. */
 	initialSelectedDiscoveredBuiltinToolNames?: string[];
 	/** Discoverable built-ins active for configured or explicit reasons independently of persisted discovery selection. */
@@ -655,6 +658,8 @@ export interface AgentSessionConfig {
 	 * process-global manager **MUST NOT** dispose it on their own teardown.
 	 */
 	ownedMcpManager?: MCPManager;
+	/** Optional startup dependency that must settle before the first provider turn. */
+	startupTurnBarrier?: Promise<void>;
 	/** Optional fork-context seed used to initialize a child session before its first prompt. */
 	forkContextSeed?: ForkContextSeed;
 	/** Optional provider state override. Fork-context children should omit this by default. */
@@ -1946,6 +1951,7 @@ export class AgentSession {
 	 */
 	readonly #ownedAsyncJobManager: AsyncJobManager | undefined;
 	readonly #ownedMcpManager: MCPManager | undefined;
+	#startupTurnBarrier: Promise<void> | undefined;
 	#pendingPythonMessages: PythonExecutionMessage[] = [];
 	#activeEvalExecutions = new Set<Promise<unknown>>();
 	#evalExecutionDisposing = false;
@@ -1965,6 +1971,8 @@ export class AgentSession {
 	#isDisposed = false;
 	#disposePromise: Promise<void> | undefined;
 	readonly #toolSessionCleanups = new Set<() => Promise<void> | void>();
+	readonly #toolSessionTransitionCleanups = new Set<() => Promise<void> | void>();
+	readonly #deferredOwnerShutdownFinalizations = new Set<Promise<void>>();
 	#newSessionTransition: Promise<boolean> | undefined;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
@@ -2268,10 +2276,23 @@ export class AgentSession {
 		next.ready.resolve();
 	}
 
+	async #awaitStartupTurnBarrier(): Promise<void> {
+		const barrier = this.#startupTurnBarrier;
+		if (!barrier) return;
+		await barrier;
+		if (this.#startupTurnBarrier === barrier) this.#startupTurnBarrier = undefined;
+	}
+	extendStartupTurnBarrier(barrier: Promise<void>): void {
+		const current = this.#startupTurnBarrier;
+		this.#startupTurnBarrier = current ? Promise.all([current, barrier]).then(() => {}) : barrier;
+		void this.#startupTurnBarrier.catch(() => {});
+	}
+
 	async #withSessionAdmission<T>(
 		kind: SessionAdmissionKind,
 		body: (lease: SessionAdmissionLease) => Promise<T>,
 	): Promise<T> {
+		if (kind === "prompt") await this.#awaitStartupTurnBarrier();
 		const owner = this.#sessionAdmissionContext.getStore();
 		if (owner && !owner.released) throw this.#sessionAdmissionBusyError();
 		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
@@ -2600,6 +2621,7 @@ export class AgentSession {
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
 		this.#retainedMemorySampler = config.retainedMemorySampler;
 		this.#ownedMcpManager = config.ownedMcpManager;
+		this.#startupTurnBarrier = config.startupTurnBarrier;
 		this.#scopedModels = config.scopedModels ?? [];
 		this.#thinkingLevel = config.thinkingLevel;
 		this.#promptTemplates = config.promptTemplates ?? [];
@@ -2660,6 +2682,8 @@ export class AgentSession {
 			injectIdle: async messages => {
 				const first = messages[0];
 				if (!first) return;
+				await this.#awaitStartupTurnBarrier();
+				if (this.#isDisposed) return;
 				if (messages.length === 1) {
 					await this.agent.prompt(first, this.#managedFallbackPromptOptions());
 				} else {
@@ -2722,7 +2746,7 @@ export class AgentSession {
 			config.initialDiscoveredBuiltinToolSelectionIsExplicit === true
 				? this.#selectRestorableDiscoveredBuiltinToolNames(config.initialPersistedDiscoveredBuiltinToolNames ?? [])
 				: undefined;
-		this.#pruneSelectedMCPToolNames();
+		if (!config.preserveUnavailableInitialMCPToolSelection) this.#pruneSelectedMCPToolNames();
 		const persistInitialMCPToolSelection =
 			config.persistInitialMCPToolSelection === true && config.initialMCPToolSelectionIsExplicit !== false;
 		const persistInitialDiscoveredBuiltinToolSelection =
@@ -3376,6 +3400,9 @@ export class AgentSession {
 	getAgentId(): string | undefined {
 		return this.#agentId;
 	}
+	get isDisposed(): boolean {
+		return this.#isDisposed;
+	}
 
 	registerToolSessionCleanup(cleanup: () => Promise<void> | void): () => void {
 		if (this.#isDisposed) throw new Error("Cannot register tool cleanup after session disposal has started.");
@@ -3383,6 +3410,23 @@ export class AgentSession {
 		return () => this.#toolSessionCleanups.delete(cleanup);
 	}
 
+	registerToolSessionTransitionCleanup(cleanup: () => Promise<void> | void): () => void {
+		if (this.#isDisposed)
+			throw new Error("Cannot register tool transition cleanup after session disposal has started.");
+		this.#toolSessionTransitionCleanups.add(cleanup);
+		return () => this.#toolSessionTransitionCleanups.delete(cleanup);
+	}
+
+	async #runToolSessionTransitionCleanups(): Promise<void> {
+		const cleanups = Array.from(this.#toolSessionTransitionCleanups);
+		this.#toolSessionTransitionCleanups.clear();
+		const results = await Promise.allSettled(cleanups.map(async cleanup => await cleanup()));
+		for (const result of results) {
+			if (result.status === "rejected")
+				logger.warn("Tool session transition cleanup failed", { error: String(result.reason) });
+		}
+	}
+
 	async #runToolSessionCleanups(): Promise<void> {
 		const cleanups = Array.from(this.#toolSessionCleanups);
 		this.#toolSessionCleanups.clear();
@@ -3435,6 +3479,61 @@ export class AgentSession {
 		manager.cancelAll({ ownerId: this.#agentId });
 	}
 
+	async #settleOwnAsyncJobsBeforeArtifactRetirement(): Promise<void> {
+		const ownerId = this.#agentId;
+		const manager = AsyncJobManager.instance();
+		if (!ownerId || !manager) return;
+		const lease = manager.beginOwnerSubagentShutdown(ownerId);
+		if (!lease) throw new Error("Owned async cleanup is already in progress before artifact retirement.");
+		let committed = false;
+		try {
+			manager.runOwnerProducerCleanupsStrict({ ownerId });
+			const proof = await manager.cancelAndProveOwnerSubagents(lease);
+			if (!proof.confirmed)
+				throw new Error("Owned subagent cleanup could not be confirmed before artifact retirement.");
+			if (!(await manager.waitForOwnerInFlightDeliveries(ownerId)))
+				throw new Error("Owned async deliveries did not settle before artifact retirement.");
+			if (!(await manager.cancelAndSettleOwnerJobs(ownerId)))
+				throw new Error("Owned async jobs did not settle before artifact retirement.");
+			committed = true;
+		} finally {
+			manager.finishOwnerSubagentShutdown(lease, committed ? "commit" : "release");
+		}
+	}
+
+	#scheduleDeferredOwnerShutdownFinalization(
+		manager: AsyncJobManager,
+		lease: OwnerSubagentShutdownLease,
+		ownerId: string,
+	): void {
+		const finalization = (async () => {
+			while (!this.#isDisposed) {
+				try {
+					manager.runOwnerProducerCleanupsStrict({ ownerId });
+					const proof = await manager.cancelAndProveOwnerSubagents(lease);
+					if (!proof.confirmed) throw new Error(`owner_subagent_${proof.reason}`);
+					if (!(await manager.waitForOwnerInFlightDeliveries(ownerId)))
+						throw new Error("owner_delivery_settlement_timeout");
+					if (!(await manager.cancelAndSettleOwnerJobs(ownerId))) throw new Error("owner_job_settlement_timeout");
+					if (this.#isDisposed) break;
+					this.sessionManager.retireEphemeralArtifactsAfterTransition();
+					await this.#runToolSessionTransitionCleanups();
+					manager.finishOwnerSubagentShutdown(lease, "commit");
+					return;
+				} catch (error) {
+					logger.warn("Deferred owner shutdown finalization retry failed", {
+						ownerId,
+						error: error instanceof Error ? error.message : String(error),
+					});
+					await Bun.sleep(25);
+				}
+			}
+			manager.finishOwnerSubagentShutdown(lease, "release");
+		})();
+		this.#deferredOwnerShutdownFinalizations.add(finalization);
+		void finalization.finally(() => this.#deferredOwnerShutdownFinalizations.delete(finalization));
+	}
+
 	#suppressOwnAsyncJobDeliveries(): void {
 		if (!this.#agentId) return;
 		const manager = AsyncJobManager.instance();
@@ -3899,14 +3998,19 @@ export class AgentSession {
 			) {
 				const isRosterReminder = event.message.role === "custom" && event.message.customType === "irc-peer-roster";
 				if (!isRosterReminder) {
-					this.#appendCustomMessageEntry(
-						event.message.customType,
-						event.message.content,
-						event.message.display,
-						event.message.details,
-						event.message.attribution ?? "agent",
-						getSessionMessageObservationId(event.message),
-					);
+					try {
+						this.#appendCustomMessageEntry(
+							event.message.customType,
+							event.message.content,
+							event.message.display,
+							event.message.details,
+							event.message.attribution ?? "agent",
+							getSessionMessageObservationId(event.message),
+						);
+					} catch (error) {
+						this.agent.abort();
+						throw error;
+					}
 				}
 			} else if (
 				event.message.role === "user" ||
@@ -3915,7 +4019,73 @@ export class AgentSession {
 				event.message.role === "toolResult" ||
 				event.message.role === "fileMention"
 			) {
-				this.sessionManager.appendMessage(event.message);
+				try {
+					this.sessionManager.appendMessage(event.message);
+				} catch (error) {
+					if (
+						event.message.role !== "toolResult" ||
+						event.message.toolName !== "todo_write" ||
+						!(error instanceof SessionAppendPersistenceError) ||
+						error.phase !== "current_append"
+					) {
+						this.agent.abort();
+						throw error;
+					}
+					this.agent.abort();
+
+					const failure = error.persistenceError.message;
+					const failedEntryId = error.entryId;
+					this.#syncTodoPhasesFromBranch();
+					event.message.isError = true;
+					event.message.content = [
+						{
+							type: "text",
+							text: `Todo state persistence failed: ${failure}\nDo not change the payload solely because of this failure. The durable outcome is unknown; reconcile the session state before retrying or continuing.`,
+						},
+					];
+					event.message.details = {
+						...(event.message.details && typeof event.message.details === "object" ? event.message.details : {}),
+						phases: this.getTodoPhases(),
+						failureKind: "persistence",
+					};
+					this.agent.touchContext();
+					let recovered = false;
+					try {
+						await this.sessionManager.recoverPersistenceFailure();
+						recovered = true;
+					} catch (recoveryError) {
+						logger.warn("Todo persistence recovery failed", {
+							error: recoveryError instanceof Error ? recoveryError.message : String(recoveryError),
+						});
+					}
+					if (recovered) {
+						const durableTodoResult = this.sessionManager
+							.getBranch()
+							.find(
+								entry =>
+									entry.id === failedEntryId &&
+									entry.type === "message" &&
+									entry.message.role === "toolResult" &&
+									entry.message.toolName === "todo_write",
+							);
+						this.#syncTodoPhasesFromBranch();
+						if (durableTodoResult?.type === "message" && durableTodoResult.message.role === "toolResult") {
+							event.message.content = durableTodoResult.message.content;
+							event.message.details = durableTodoResult.message.details;
+							event.message.isError = durableTodoResult.message.isError;
+						} else {
+							event.message.details = {
+								...(event.message.details && typeof event.message.details === "object"
+									? event.message.details
+									: {}),
+								phases: this.getTodoPhases(),
+								failureKind: "persistence",
+							};
+							this.sessionManager.appendMessage(event.message);
+							this.agent.touchContext();
+						}
+					}
+				}
 			}
 		}
 
@@ -4189,7 +4359,13 @@ export class AgentSession {
 			if (event.message.role === "toolResult") {
 				const { toolName, details, isError, content } = event.message as {
 					toolName?: string;
-					details?: { path?: string; phases?: TodoPhase[]; report?: string; startedAt?: string };
+					details?: {
+						path?: string;
+						phases?: TodoPhase[];
+						report?: string;
+						startedAt?: string;
+						failureKind?: "payload_rejected" | "argument_validation" | "execution" | "persistence";
+					};
 					isError?: boolean;
 					content?: Array<TextContent | ImageContent>;
 				};
@@ -4202,22 +4378,34 @@ export class AgentSession {
 				}
 				if (toolName === "todo_write" && isError) {
 					const errorText = content?.find(part => part.type === "text")?.text;
+					const payloadRejected =
+						details?.failureKind === "payload_rejected" || details?.failureKind === "argument_validation";
 					const reminderText = [
 						"<system-reminder>",
-						"todo_write failed, so todo progress is not visible to the user.",
+						payloadRejected
+							? "todo_write rejected its payload. The requested todo update was not applied."
+							: "todo_write did not complete because the turn aborted during runtime execution or persistence.",
 						errorText ? `Failure: ${errorText}` : "Failure: todo_write returned an error.",
-						"Fix the todo payload and call todo_write again before continuing.",
+						payloadRejected
+							? "Correct the payload and call todo_write again before continuing."
+							: "Do not change the payload solely because of this failure. The durable outcome is unknown; reconcile the session state before retrying or continuing.",
 						"</system-reminder>",
 					].join("\n");
-					await this.sendCustomMessage(
-						{
-							customType: "todo-write-error-reminder",
-							content: reminderText,
-							display: false,
-							details: { toolName, errorText },
-						},
-						{ deliverAs: "nextTurn" },
-					);
+					try {
+						await this.sendCustomMessage(
+							{
+								customType: "todo-write-error-reminder",
+								content: reminderText,
+								display: false,
+								details: { toolName, errorText },
+							},
+							{ deliverAs: "nextTurn" },
+						);
+					} catch (error) {
+						logger.warn("Todo write error reminder persistence failed", {
+							error: error instanceof Error ? error.message : String(error),
+						});
+					}
 				}
 				if (toolName === "checkpoint" && !isError) {
 					const checkpointEntryId = this.sessionManager.getLeafId();
@@ -4557,6 +4745,11 @@ export class AgentSession {
 						settleLease();
 						return;
 					}
+					await this.#awaitStartupTurnBarrier();
+					if (!canContinue()) {
+						settleLease();
+						return;
+					}
 					try {
 						if (!options?.skipCompactionCheck) {
 							await this.#checkEstimatedContextBeforePrompt();
@@ -5906,6 +6099,7 @@ export class AgentSession {
 		// the session that owns the manager goes on to dispose it (which itself
 		// nukes any leftover jobs and pending deliveries).
 		this.#cancelOwnAsyncJobs();
+		await Promise.allSettled(this.#deferredOwnerShutdownFinalizations);
 		const ownedAsyncManager = this.#ownedAsyncJobManager;
 		if (ownedAsyncManager) {
 			const drained = await ownedAsyncManager.dispose({ timeoutMs: 3_000 });
@@ -5917,6 +6111,7 @@ export class AgentSession {
 				AsyncJobManager.setInstance(undefined);
 			}
 		}
+		await this.#runToolSessionTransitionCleanups();
 		await this.#runToolSessionCleanups();
 		// Only disconnect the MCP manager THIS session owns (top-level sessions that
 		// connected plugin-bundle MCP servers). Subagents and callers that merely
@@ -6744,6 +6939,12 @@ export class AgentSession {
 				const built = await this.#runAdmittedBaseSystemPromptRebuild(() =>
 					this.#rebuildSystemPrompt!(validToolNames, this.#toolRegistry),
 				);
+				if (this.#isDisposed) {
+					if (generation === this.#baseSystemPromptGeneration) {
+						this.#pendingAppliedToolSignature = undefined;
+					}
+					return;
+				}
 				if (generation === this.#baseSystemPromptGeneration) {
 					this.#baseSystemPrompt = built.systemPrompt;
 					this.agent.setSystemPrompt(this.#baseSystemPrompt);
@@ -7229,6 +7430,8 @@ export class AgentSession {
 		if (!canContinuePersistedHistory(this.agent.state.messages)) {
 			throw new Error("Cannot continue from persisted message history");
 		}
+		await this.#awaitStartupTurnBarrier();
+		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
 		this.#beginInFlight();
 		let hindsightRecall: string | undefined;
 		try {
@@ -10093,6 +10296,7 @@ export class AgentSession {
 				// Last fallible gate while public getters still show the predecessor (#3138).
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -10162,6 +10366,7 @@ export class AgentSession {
 				// Last fallible gate while public getters still show the predecessor (#3138).
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -10328,7 +10533,9 @@ export class AgentSession {
 			}
 			try {
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
@@ -11445,6 +11652,7 @@ export class AgentSession {
 		const artifactManager = this.sessionManager.getArtifactManager();
 		const prunedArtifacts: Array<{ entryId: string; id: string; toolType: string; originalText: string }> = [];
 		let reservedArtifactId: string | undefined;
+		let artifactAllocationAvailable = artifactManager !== null;
 		if (artifactManager) {
 			try {
 				reservedArtifactId = (await artifactManager.allocatePath("tool-output")).id;
@@ -11452,14 +11660,24 @@ export class AgentSession {
 				logger.warn("Failed to reserve artifact ID for pruned tool output", {
 					error: error instanceof Error ? error.message : String(error),
 				});
+				artifactAllocationAvailable = false;
 			}
 		}
 		const result = pruneToolOutputs(branchEntries, DEFAULT_PRUNE_CONFIG, {
 			relaxedMinimum: overThreshold ? 0 : undefined,
 			artifactRefMaxChars: PRUNED_ARTIFACT_REF_MAX_CHARS,
 			artifactRef: candidate => {
-				if (!artifactManager) return undefined;
-				const id = reservedArtifactId ?? String(artifactManager.allocateId());
+				if (!artifactManager || !artifactAllocationAvailable) return undefined;
+				let id: string;
+				try {
+					id = reservedArtifactId ?? String(artifactManager.allocateId());
+				} catch (error) {
+					artifactAllocationAvailable = false;
+					logger.warn("Failed to allocate artifact ID for pruned tool output", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+					return undefined;
+				}
 				reservedArtifactId = undefined;
 				const toolType = (candidate.toolName ?? "tool-output").replace(/[^a-zA-Z0-9_-]/g, "_") || "tool-output";
 				prunedArtifacts.push({ entryId: candidate.entryId, id, toolType, originalText: candidate.originalText });
@@ -12071,10 +12289,12 @@ export class AgentSession {
 				const successorGateEmitter = this.#constructWorkflowGateEmitter(prepared.sessionId);
 				// Last fallible action: verified local:// readiness from immutable staged options.
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 
 				// --- Commit boundary: synchronous adoption is the sole identity publication.
 				this.sessionManager.commitPreparedNewSession(prepared);
 				committed = true;
+				await this.#runToolSessionTransitionCleanups();
 				this.agent.reset();
 				this.#syncAgentSessionId();
 				this.#rekeyHindsightMemoryForCurrentSessionId();
@@ -12105,7 +12325,6 @@ export class AgentSession {
 				this.#resetIrcRosterDeliveryState();
 				this.#planReferenceSent = false;
 				this.#planReferencePath = "local://PLAN.md";
-				this.#cancelOwnAsyncJobs();
 				// The predecessor's fenced async-job results (queued while the
 				// transition held the delivery fence) belong to the handed-off session,
 				// not the successor. Suppress and drop ONLY the async-result kind so they
@@ -14847,6 +15066,17 @@ export class AgentSession {
 		// before the failure. This bypasses #hasCleanRetryReplaySafety because the
 		// content-free check is the replay-safety guarantee for credential rotation.
 		const canReplayRotatedCredential = credentialRotated;
+		// Universal automatic replay-safety gate (#3791): once the failed attempt
+		// carries observable assistant text, thinking, or tool-call content,
+		// automatic session retry must not re-issue the request. This covers
+		// configured legacy retry (which previously only gated first-event
+		// timeouts) as well as bare defaults. Managed fallback keeps its
+		// provisional discard path (events never published to the session).
+		// Content-free credential rotation remains eligible above; first-event
+		// timeout keeps its additional typed/scope checks earlier in this method.
+		if (!managedFallback && assistantMessageHasVisibleOrToolContent(message)) {
+			return false;
+		}
 		// Bare defaults retain their narrow watchdog and Codex admissions. A
 		// first-event timeout adds the typed, content-free, current-clean-scope
 		// requirement above; other transient watchdogs preserve legacy behavior.
@@ -16210,6 +16440,10 @@ export class AgentSession {
 			onTransitionMutationStarted?: () => void;
 		},
 	): Promise<boolean> {
+		let ownerShutdownManager: AsyncJobManager | undefined;
+		let ownerShutdownLease: OwnerSubagentShutdownLease | undefined;
+		let ownerShutdownTransitionCommitted = false;
+		let ownerShutdownFinalizationDeferred = false;
 		this.#beginSessionTransition("switch-session");
 		try {
 			const previousSessionFile = this.sessionManager.getSessionFile();
@@ -16230,9 +16464,31 @@ export class AgentSession {
 			}
 			options?.onTransitionMutationStarted?.();
 
-			this.#disconnectFromAgent();
+			const asyncManager = AsyncJobManager.instance();
+			const ownerId = this.#agentId;
+			const lease =
+				switchingToDifferentSession && asyncManager && ownerId
+					? asyncManager.beginOwnerSubagentShutdown(ownerId)
+					: undefined;
+			if (switchingToDifferentSession && asyncManager && ownerId && !lease) {
+				this.emitNotice(
+					"error",
+					"Cannot switch sessions while owned subagent cleanup is already in progress.",
+					"switch-session-subagent-cleanup",
+				);
+				return false;
+			}
+			if (lease && asyncManager) {
+				ownerShutdownManager = asyncManager;
+				ownerShutdownLease = lease;
+			}
 			await this.abort();
+			if (this.isCompacting) {
+				this.abortCompaction();
+				while (this.isCompacting) await Bun.sleep(10);
+			}
 
+			this.#disconnectFromAgent();
 			// Flush pending writes before switching so restore snapshots reflect committed state.
 			await this.sessionManager.flush();
 			const previousSessionState = this.sessionManager.captureState();
@@ -16263,9 +16519,13 @@ export class AgentSession {
 				? this.#suspendWorkflowGateEmitter(previousSessionState.sessionId)
 				: undefined;
 			let unavailableDefaultChainMessage: string | undefined;
+			let transitionCleanupCommitted = false;
 
 			try {
-				await this.sessionManager.setSessionFile(sessionPath);
+				await this.sessionManager.setSessionFile(sessionPath, {
+					deferEphemeralArtifactRetirement: switchingToDifferentSession,
+				});
+				if (switchingToDifferentSession) this.sessionManager.stageAdoptedArtifactManagerForTransition();
 				// 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
@@ -16365,6 +16625,38 @@ export class AgentSession {
 					this.#resetIrcRosterDeliveryState();
 				}
 
+				if (switchingToDifferentSession) {
+					let ownerShutdownSettled = true;
+					if (ownerShutdownManager && ownerShutdownLease && ownerId) {
+						try {
+							ownerShutdownManager.runOwnerProducerCleanupsStrict({ ownerId });
+							const proof = await ownerShutdownManager.cancelAndProveOwnerSubagents(ownerShutdownLease);
+							if (!proof.confirmed)
+								throw new Error("Owned subagent cleanup could not be confirmed after successor validation.");
+							if (!(await ownerShutdownManager.waitForOwnerInFlightDeliveries(ownerId)))
+								throw new Error("Owned async deliveries did not settle after successor validation.");
+							if (!(await ownerShutdownManager.cancelAndSettleOwnerJobs(ownerId)))
+								throw new Error("Owned async jobs did not settle after successor validation.");
+						} catch (error) {
+							ownerShutdownSettled = false;
+							ownerShutdownFinalizationDeferred = true;
+							this.#scheduleDeferredOwnerShutdownFinalization(ownerShutdownManager, ownerShutdownLease, ownerId);
+							this.#suppressOwnAsyncJobDeliveries();
+							this.emitNotice(
+								"error",
+								`Successor session is active, but predecessor async cleanup did not settle: ${error instanceof Error ? error.message : String(error)}`,
+								"switch-session-subagent-cleanup",
+							);
+						}
+					}
+					transitionCleanupCommitted = true;
+					// Different files may intentionally carry the same copied session id; pathname transition is the commit signal.
+					ownerShutdownTransitionCommitted = true;
+					if (ownerShutdownSettled) {
+						this.sessionManager.retireEphemeralArtifactsAfterTransition();
+						await this.#runToolSessionTransitionCleanups();
+					}
+				}
 				this.#reconnectToAgent();
 				// Fence predecessor continuations before session_switch starts SDK runtime
 				// teardown. The previous runtime waits for those continuations to settle;
@@ -16373,7 +16665,8 @@ export class AgentSession {
 					this.#bindWorkflowGateEmitter(previousSessionState.sessionId, suspendedWorkflowGateEmitter);
 				// session_switch is the post-commit identity signal. SDK authority and
 				// other identity-bound integrations must not observe the successor until
-				// messages, model state, MCP selections, and the agent subscription are live.
+				// messages, model state, MCP selections, the agent subscription, and
+				// session-scoped tool cleanup are complete.
 				if (this.#extensionRunner) {
 					await this.#extensionRunner.emit({
 						type: "session_switch",
@@ -16384,6 +16677,7 @@ export class AgentSession {
 				}
 				return true;
 			} catch (error) {
+				if (transitionCleanupCommitted) throw error;
 				this.sessionManager.restoreState(previousSessionState);
 				this.#defaultFallbackController = undefined;
 				this.#syncAgentSessionId(previousSessionState.sessionId);
@@ -16442,6 +16736,12 @@ export class AgentSession {
 				throw error;
 			}
 		} finally {
+			if (ownerShutdownManager && ownerShutdownLease && !ownerShutdownFinalizationDeferred) {
+				ownerShutdownManager.finishOwnerSubagentShutdown(
+					ownerShutdownLease,
+					ownerShutdownTransitionCommitted ? "commit" : "release",
+				);
+			}
 			this.#endSessionTransition();
 		}
 	}
@@ -16493,13 +16793,14 @@ export class AgentSession {
 				: await this.sessionManager.prepareNewSession({ parentSession: previousSessionFile });
 			try {
 				await initializeLocalRoot(this.#localProtocolOptions(prepared));
+				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
 				this.sessionManager.commitPreparedNewSession(prepared);
+				await this.#runToolSessionTransitionCleanups();
 			} catch (error) {
 				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
 			}
 			this.#pendingNextTurnMessages = [];
 			this.#scheduledHiddenNextTurnGeneration = undefined;
-			this.#cancelOwnAsyncJobs();
 
 			this.#syncTodoPhasesFromBranch();
 			this.#syncAgentSessionId();