@gajae-code/coding-agent 0.15.5 → 0.15.6

package/src/session/agent-session.ts

@@ -117,6 +117,7 @@ import {
 	modelsAreEqual,
 	streamSimple,
 } from "@gajae-code/ai/core";
+import { normalizeAnthropicBaseUrl } from "@gajae-code/ai/providers/anthropic";
 import {
 	type AuthDisposition,
 	beginAttempt,
@@ -181,8 +182,10 @@ export interface ForkContextSeedOptions {
 }
 
 import type { AuthCredentialSelector } from "@gajae-code/ai/core";
+import { isFoundryEnabled } from "@gajae-code/ai/utils/foundry";
 import type { MacOSPowerAssertion } from "@gajae-code/natives";
 import {
+	$pickCredentialEnv,
 	extractRetryHint,
 	hasFsCode,
 	isEacces,
@@ -314,6 +317,7 @@ import {
 	type CoordinatorToolObservation,
 	ownerTerminalContextFromEnvironment,
 	persistCoordinatorRuntimeStateFromEvent,
+	persistCoordinatorWorkerIntegrationOutcome,
 	registerCoordinatorRuntimeStateFinalizer,
 	UNPROVEN_TOOL_LABEL,
 } from "../gjc-runtime/session-state-sidecar";
@@ -443,6 +447,7 @@ import {
 } from "./contribution-prep";
 import { canonicalCoordinatorToolLabel } from "./coordinator-tool-label";
 import { pruneStaleFileMentions } from "./file-mention-pruning";
+import { describeFoldReceipt, FOLD_WAKE_MERGE_WINDOW_MS, type FoldAdapter, FoldCoordinator } from "./fold-coordinator";
 import type { MemoryGuardRestoreResult } from "./memory-guard-checkpoint-participant";
 import {
 	type BashExecutionMessage,
@@ -457,6 +462,7 @@ import {
 	SKILL_PROMPT_MESSAGE_TYPE,
 } from "./messages";
 import { isLegacyProviderSafetyStopMessage } from "./provider-safety-stop";
+import { readSdkRunCapability } from "./sdk-run-capability";
 import { formatSessionDumpText } from "./session-dump-format";
 import type {
 	BranchSummaryEntry,
@@ -471,7 +477,6 @@ import type {
 	SessionManagerCloseOutcome,
 	SessionMemoryStats,
 } from "./session-manager";
-
 import {
 	createReadonlySessionManager,
 	getLatestCompactionEntry,
@@ -488,6 +493,8 @@ import {
 	bindToolLineage,
 	classifyOwnedEnvelope,
 	isOwnedCompletionEnvelope,
+	isOwnedCompletionEnvelopeAllowed,
+	lookupOwnedRegistration,
 	lookupTerminalScope,
 	mintTurnLineageIdHash,
 	type OwnedCompletionEnvelope,
@@ -496,11 +503,35 @@ import {
 	settleToolLineageRegistrationWindow,
 	unregisterOwnedRegistration,
 } from "./terminal-abort";
-
 import { ToolChoiceQueue } from "./tool-choice-queue";
 import { pruneSupersededMaintenanceReminders, pruneSupersededVolatileProjectContext } from "./volatile-context-pruning";
 import { YieldQueue } from "./yield-queue";
 
+const ASYNC_INLINE_RESULT_MAX_CHARS = 12_000;
+const ASYNC_PREVIEW_MAX_CHARS = 4_000;
+
+async function formatParkedAsyncResult(
+	sessionManager: SessionManager,
+	result: string,
+	allowArtifact = true,
+): Promise<string> {
+	if (result.length <= ASYNC_INLINE_RESULT_MAX_CHARS) return result;
+	const preview = `${result.slice(0, ASYNC_PREVIEW_MAX_CHARS)}\n\n[Output truncated. Showing first ${ASYNC_PREVIEW_MAX_CHARS.toLocaleString()} characters.]`;
+	try {
+		if (!allowArtifact) return preview;
+		const { path: artifactPath, id: artifactId } = await sessionManager.allocateArtifactPath("async");
+		if (artifactPath && artifactId) {
+			await Bun.write(artifactPath, result);
+			return `${preview}\nFull output: artifact://${artifactId}`;
+		}
+	} catch (error) {
+		logger.warn("Failed to persist parked async follow-up artifact", {
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+	return preview;
+}
+
 /**
  * #4560: structured workflow recovery projection from canonical durable
  * Ralplan/Ultragoal state, consumed by the compaction summary context and
@@ -1048,10 +1079,23 @@ export interface PromptOptions {
 	onSkillPrepared?: (meta: { name: string; path: string; lineCount?: number; cleanedArgs?: string }) => void;
 	/** Optional invocation-scoped cancellation fence used before an accepted skill starts execution. */
 	preflightSignal?: AbortSignal;
-	/** Internal SDK lifecycle owner token. */
-	sdkRunToken?: string;
+	/** Internal host capability; ordinary package callers cannot construct the branded value. */
+	sdkRunCapability?: unknown;
 }
 
+type InternalPromptOptions = PromptOptions & { sdkRunToken?: string };
+type InternalCustomMessageOptions = Pick<
+	PromptOptions,
+	| "streamingBehavior"
+	| "toolChoice"
+	| "followUpQueuePolicy"
+	| "onPreflightAccepted"
+	| "onPreflightAcceptCommit"
+	| "preflightSignal"
+> & {
+	sdkRunToken?: string;
+};
+
 function promptPreflightCancelledError(): Error {
 	const error = Object.assign(new Error("Prompt preflight was cancelled before execution."), { code: "busy" });
 	error.name = "PromptPreflightCancelledError";
@@ -1626,14 +1670,44 @@ function buildSessionMetadata(
 	provider: string,
 	authStorage: AuthStorage | undefined,
 	credentialSessionId = sessionId,
+	model?: Model,
+	owner?: object,
 ): Record<string, unknown> {
 	const userId: Record<string, string> = { session_id: sessionId };
 	// Only look up account_uuid when the request is going to Anthropic. Injecting
 	// a Anthropic model OAuth account_uuid into requests bound for other providers (including
 	// Anthropic-format-compatible proxies like cloudflare-ai-gateway or gitlab-duo)
 	// would leak the user's Anthropic identity to unrelated third-party APIs.
-	if (provider === "anthropic") {
-		const accountUuid = authStorage?.getOAuthAccountId("anthropic", credentialSessionId);
+	const effectiveBaseUrl =
+		model?.provider === "anthropic"
+			? (normalizeAnthropicBaseUrl(
+					(isFoundryEnabled() ? $pickCredentialEnv("FOUNDRY_BASE_URL") : undefined) ?? model.baseUrl,
+				) ?? "https://api.anthropic.com")
+			: undefined;
+	let officialAnthropicEndpoint = false;
+	if (provider === "anthropic" && model?.api === "anthropic-messages") {
+		try {
+			const candidate = effectiveBaseUrl ?? "https://api.anthropic.com";
+			const url = new URL(candidate);
+			const authority = candidate.match(/^[a-z][a-z\d+.-]*:\/\/([^/?#]*)/iu)?.[1];
+			officialAnthropicEndpoint =
+				url.protocol === "https:" &&
+				url.hostname === "api.anthropic.com" &&
+				authority?.toLowerCase() === "api.anthropic.com" &&
+				!url.username &&
+				!url.password &&
+				!url.search &&
+				!url.hash &&
+				(url.pathname === "/" || url.pathname === "/v1" || url.pathname === "/v1/");
+		} catch {
+			officialAnthropicEndpoint = false;
+		}
+	}
+	// Without the registry owner, do not query shared auth storage: an unscoped
+	// lookup can attribute a registry-scoped API-key request to another OAuth
+	// account. Compatibility facades therefore retain session_id-only metadata.
+	if (officialAnthropicEndpoint && owner) {
+		const accountUuid = authStorage?.getOAuthAccountId("anthropic", credentialSessionId, { owner });
 		if (typeof accountUuid === "string" && accountUuid.length > 0) {
 			userId.account_uuid = accountUuid;
 			// Derive device_id from account_uuid so the payload matches the real CC
@@ -1914,9 +1988,24 @@ export type BeforeAgentStartContributor = (event: {
 }) => Promise<BeforeAgentStartInternalMessage | undefined>;
 
 const AGENT_END_WORKER_INTEGRATION_TIMEOUT_MS = 5_000;
+const POST_PUBLICATION_ERROR_MAX_BYTES = 512;
+
+export type WorkerIntegrationOutcome =
+	| { status: "completed" }
+	| { status: "failed"; error: string }
+	| { status: "timed_out" };
+
+function sanitizePostPublicationError(error: string | undefined): string | undefined {
+	if (error === undefined) return undefined;
+	const normalized = error
+		.replace(/[\u0000-\u001f\u007f]/gu, " ")
+		.replace(/\s+/gu, " ")
+		.trim();
+	return truncateHeadBytes(normalized || "unknown worker integration error", POST_PUBLICATION_ERROR_MAX_BYTES).text;
+}
 
 export class WorkerIntegrationRequestScheduler {
-	#inFlight: Promise<void> | undefined = undefined;
+	#inFlight: Promise<WorkerIntegrationOutcome> | undefined = undefined;
 	#pending = false;
 
 	constructor(
@@ -1933,9 +2022,15 @@ export class WorkerIntegrationRequestScheduler {
 	}
 
 	async flush(): Promise<void> {
+		await this.flushWithOutcome();
+	}
+
+	async flushWithOutcome(): Promise<WorkerIntegrationOutcome> {
+		let outcome: WorkerIntegrationOutcome = { status: "completed" };
 		while (this.#inFlight) {
-			await this.#inFlight;
+			outcome = await this.#inFlight;
 		}
+		return outcome;
 	}
 
 	#start(): void {
@@ -1945,16 +2040,22 @@ export class WorkerIntegrationRequestScheduler {
 		try {
 			request = this.request(controller.signal);
 		} catch {
-			request = Promise.resolve();
+			request = Promise.reject(new Error("Worker integration request failed before dispatch."));
 		}
 		let timeout: ReturnType<typeof setTimeout> | undefined;
-		const deadline = new Promise<void>(resolve => {
+		const deadline = new Promise<WorkerIntegrationOutcome>(resolve => {
 			timeout = setTimeout(() => {
 				controller.abort(new Error("Worker integration request timed out"));
-				resolve();
+				resolve({ status: "timed_out" });
 			}, this.timeoutMs);
 		});
-		this.#inFlight = Promise.race([request.catch(() => {}), deadline]).finally(() => {
+		this.#inFlight = Promise.race([
+			request.then(
+				() => ({ status: "completed" as const }),
+				error => ({ status: "failed" as const, error: String(error) }),
+			),
+			deadline,
+		]).finally(() => {
 			if (timeout) clearTimeout(timeout);
 			controller.abort();
 			this.#inFlight = undefined;
@@ -2475,6 +2576,22 @@ export class AgentSession {
 		this.#activeAttemptScope = undefined;
 		this.#activeLogicalRunId = undefined;
 	}
+	#acceptSdkAttemptRun(handle: AttemptRunHandle, sdkRunToken?: string): void {
+		const predecessorScope = this.#activeAttemptScope;
+		const predecessorSdkRunToken =
+			predecessorScope === undefined ? undefined : this.#sdkRunTokensByAttemptScope.get(predecessorScope);
+		const carryRecoverySkip =
+			sdkRunToken !== undefined &&
+			predecessorSdkRunToken === sdkRunToken &&
+			predecessorScope !== undefined &&
+			this.#skipPostPromptRecoveryWaitByAttemptScope.delete(predecessorScope);
+		this.#acceptRunHandle(handle);
+		if (sdkRunToken !== undefined) {
+			this.#activeSdkRunToken = sdkRunToken;
+			this.#sdkRunTokensByAttemptScope.set(handle.scope, sdkRunToken);
+		}
+		if (carryRecoverySkip) this.#skipPostPromptRecoveryWaitByAttemptScope.add(handle.scope);
+	}
 	/** Messages queued to be included with the next user prompt as context ("asides"). */
 	#pendingNextTurnMessages: Array<{ message: CustomMessage; origin: "turn" | "external" }> = [];
 	#scheduledHiddenNextTurnGeneration: number | undefined = undefined;
@@ -2608,7 +2725,88 @@ export class AgentSession {
 		onPersisted?: () => void;
 		appendedToAgent: boolean;
 	}> = [];
-	#foregroundBashBackgroundRequestHandler: (() => void) | undefined;
+	/**
+	 * Set by a fold and consumed once by the pause checkpoint, so a fold ends its
+	 * own turn without pausing any later turn.
+	 */
+	#foldStopRequested = false;
+	/**
+	 * The single linearization point for folding a foreground wait. Arrow deps
+	 * capture `this` but are only invoked after construction.
+	 */
+	readonly #foldCoordinator = new FoldCoordinator({
+		hasActiveTurn: () => this.activePromptHandle !== undefined,
+		armSteeringFence: () => {
+			this.agent.setSteeringAdmissionFence(() => true);
+			return () => this.agent.setSteeringAdmissionFence(undefined);
+		},
+		requestStop: () => {
+			this.#foldStopRequested = true;
+		},
+		captureRemainingIntent: () => this.#captureRemainingIntentForFold(),
+		// A parked completion replayed after the fold must schedule its own wake.
+		// This mirrors exactly what the sdk delivery seam does for a live receipt
+		// delivery, so the parked path cannot rely on an unrelated idle rearm.
+		deliverParked: (job, disposition) => {
+			const endpointId = this.#ownedAsyncJobManager
+				? AsyncJobManager.endpointIdOf(this.#ownedAsyncJobManager)
+				: undefined;
+			const registration = lookupOwnedRegistration(job.id, job.generation, endpointId);
+			if (this.#ownedAsyncJobManager?.isDeliverySuppressed(job.id, job.generation)) {
+				this.#ownedAsyncJobManager.clearParkedDelivery(job.generation);
+				return;
+			}
+			if (this.#foldCoordinator.claimCompletionNotice(job)) {
+				this.emitNotice(
+					"info",
+					`Folded job ${disposition.receipt.jobId} (${disposition.receipt.label}) finished.`,
+					"fold",
+				);
+			}
+			const ownedCompletion = registration
+				? {
+						lineageIdHash: registration.lineageIdHash,
+						promptAttemptEpoch: registration.promptAttemptEpoch,
+						registration,
+					}
+				: undefined;
+			const allowArtifact = ownedCompletion === undefined || isOwnedCompletionEnvelopeAllowed(ownedCompletion);
+			void formatParkedAsyncResult(this.sessionManager, disposition.text, allowArtifact)
+				.then(formattedResult => {
+					const manager = this.#ownedAsyncJobManager;
+					if (manager?.isDeliverySuppressed(job.id, job.generation)) {
+						manager.clearParkedDelivery(job.generation);
+						return;
+					}
+					if (!this.#foldCoordinator.claimCompletionDelivery(job)) {
+						manager?.clearParkedDelivery(job.generation);
+						return;
+					}
+					try {
+						manager?.retainDeliveryClaim(job);
+						if (manager?.isDeliverySuppressed(job.id, job.generation)) {
+							manager.releaseDeliveryClaim(job.generation);
+							manager.clearParkedDelivery(job.generation);
+							return;
+						}
+						this.yieldQueue.enqueue("async-result", {
+							jobId: disposition.receipt.jobId,
+							generation: disposition.receipt.jobGeneration,
+							result: `${formattedResult}\n\n${describeFoldReceipt(disposition.receipt)}`,
+							job,
+							durationMs: undefined,
+							ownedCompletion,
+						});
+					} finally {
+						manager?.clearParkedDelivery(job.generation);
+					}
+				})
+				.catch(error => {
+					this.#ownedAsyncJobManager?.clearParkedDelivery(job.generation);
+					logger.warn("Parked folded delivery formatting failed", { error: String(error) });
+				});
+		},
+	});
 
 	// Python execution state
 	#evalAbortControllers = new Set<AbortController>();
@@ -2658,6 +2856,7 @@ export class AgentSession {
 	#extensionRunner: ExtensionRunner | undefined = undefined;
 	/** SDK follow-up ownership by queued message and the attempt that dequeues it. */
 	#sdkRunTokensByQueuedMessage = new WeakMap<AgentMessage, string>();
+	#skipPostPromptRecoveryWaitByAttemptScope = new WeakSet<AttemptScope>();
 	#sdkRunTokensByAttemptScope = new WeakMap<AttemptScope, string>();
 	#activeSdkRunToken: string | undefined;
 	#activeAttemptScope: AttemptScope | undefined;
@@ -3006,6 +3205,7 @@ export class AgentSession {
 	 * orchestrator does not hold it), so there is no self-deadlock.
 	 */
 	#sessionTransitionKind: string | undefined;
+	#coordinatorPersistGeneration = 0;
 
 	#beginSessionTransition(kind: string): void {
 		if (this.#sessionTransitionKind !== undefined) {
@@ -3015,6 +3215,7 @@ export class AgentSession {
 			);
 		}
 		this.#sessionTransitionKind = kind;
+		this.#coordinatorPersistGeneration += 1;
 	}
 
 	#endSessionTransition(): void {
@@ -3614,7 +3815,7 @@ export class AgentSession {
 		// Deferrals behind still-pending selection fences are excluded here: they
 		// cannot settle before their fence resolves, and the fence owner may be
 		// waiting on this very settlement (#4519).
-		if (!predecessorPromptStillInFlight) {
+		if (promptWait !== "publication" && !predecessorPromptStillInFlight) {
 			await this.#waitForSessionSettlement(this.#turnSettlementDeferralFloor());
 		}
 		if (flushError) throw flushError;
@@ -3656,28 +3857,50 @@ export class AgentSession {
 		this.#pendingAgentEndEmit = undefined;
 		const lease = this.#deferredAgentEndLeases.get(pending);
 		if (lease) this.#deferredAgentEndLeases.delete(pending);
+		this.#startAgentEndPublication(pending, lease);
+	}
+	#startAgentEndPublication(pending: AgentSessionEvent, lease?: RunResourceProducerLease): void {
 		this.#agentEndPublicationInFlight++;
-		this.#agentEndPublicationPromise = this.#publishDeferredAgentEnd(pending, lease);
+		const pendingScope = (pending as AgentSessionEvent & { scope?: AttemptScopeRef }).scope as
+			| AttemptScope
+			| undefined;
+		const sdkTerminal = pendingScope !== undefined && this.#sdkRunTokensByAttemptScope.has(pendingScope);
+		this.#agentEndPublicationPromise = this.#publishDeferredAgentEnd(pending, lease, sdkTerminal);
 		void this.#agentEndPublicationPromise;
 	}
 
 	async #publishDeferredAgentEnd(
 		pending: AgentSessionEvent,
 		lease: RunResourceProducerLease | undefined,
+		workerIntegrationSettled: boolean,
 	): Promise<void> {
+		const publicationContext = {
+			sessionId: this.sessionId,
+			cwd: this.sessionManager.getCwd(),
+			sessionFile: this.sessionManager.getSessionFile(),
+		};
+		const publicationScope = (pending as AgentSessionEvent & { scope?: AttemptScopeRef }).scope as
+			| AttemptScope
+			| undefined;
+		const publicationCorrelationId = publicationScope
+			? this.#sdkRunTokensByAttemptScope.get(publicationScope)
+			: undefined;
 		let extensionDelivery: Promise<void> | undefined;
 		const releaseLease = () => {
 			if (!lease) return;
+			this.#deferredAgentEndLeases.delete(pending);
 			if (this.#postPromptLeases.get(lease.resourceRunId) === lease) {
 				this.#postPromptLeases.delete(lease.resourceRunId);
 			}
 			lease.closeDiscovery();
 		};
 		const publish = async () => {
-			// Worker integration is first-party lifecycle persistence, not an extension
-			// hook. Settle it before publishing the terminal boundary while user extension
-			// delivery and coordinator sidecar persistence remain asynchronous.
-			await this.#flushWorkerIntegrationForAgentEnd();
+			let workerIntegration: Promise<WorkerIntegrationOutcome> | undefined;
+			let workerIntegrationOutcome: WorkerIntegrationOutcome | undefined;
+			if (!workerIntegrationSettled) {
+				workerIntegration = this.#flushWorkerIntegrationForAgentEnd();
+				workerIntegrationOutcome = await workerIntegration;
+			}
 			// Reserve persistence before notifying synchronous subscribers: a subscriber
 			// may start a successor prompt from agent_end, whose running state must
 			// serialize after this terminal boundary rather than be overwritten by it.
@@ -3686,16 +3909,72 @@ export class AgentSession {
 			// behind this terminal transition, but do not make the interactive terminal
 			// wait for the filesystem-backed lock/write to settle. On slow or lock-hostile
 			// mounts such as WSL drvfs, waiting here leaves the foreground activity loader
-			// and busy input state visible after the model has already finished.
-			const terminalPersistence = this.#queueCoordinatorRuntimeStatePersist(pending);
+			// and busy input state visible after the model has already finished. The queue
+			// preserves transaction order; terminal publication is the user-visible
+			// authority and must not be suppressed by a secondary persistence failure.
+			const terminalPersistence = this.#queueCoordinatorRuntimeStatePersist(pending, true);
 			this.#emit(pending);
-			await terminalPersistence;
+			void terminalPersistence.then(
+				() => {
+					if (workerIntegrationOutcome) {
+						this.#recordPostPublicationOutcome(
+							publicationContext,
+							publicationCorrelationId,
+							"worker_integration",
+							workerIntegrationOutcome,
+						);
+					}
+					this.#recordPostPublicationOutcome(
+						publicationContext,
+						publicationCorrelationId,
+						"terminal_persistence",
+						{ status: "completed" },
+					);
+				},
+				error => {
+					if (workerIntegrationOutcome) {
+						this.#recordPostPublicationOutcome(
+							publicationContext,
+							publicationCorrelationId,
+							"worker_integration",
+							workerIntegrationOutcome,
+						);
+					}
+					this.#recordPostPublicationOutcome(
+						publicationContext,
+						publicationCorrelationId,
+						"terminal_persistence",
+						{
+							status: "failed",
+							error: String(error),
+						},
+					);
+					logger.warn("Failed to persist terminal coordinator runtime state", { error: String(error) });
+				},
+			);
 			extensionDelivery = this.#queueExtensionEvent(
 				pending,
 				undefined,
 				true,
 				(pending as AgentSessionEvent & { scope?: AttemptScopeRef }).scope,
 			);
+			if (workerIntegrationSettled) {
+				workerIntegration = this.#flushWorkerIntegrationForAgentEnd();
+				void workerIntegration.then(outcome =>
+					this.#recordPostPublicationOutcome(
+						publicationContext,
+						publicationCorrelationId,
+						"worker_integration",
+						outcome,
+					),
+				);
+				await extensionDelivery;
+				void terminalPersistence.catch(error =>
+					logger.warn("Terminal persistence continued after SDK publication", { error }),
+				);
+			} else {
+				// Non-SDK/public publication has already awaited worker integration above.
+			}
 		};
 		try {
 			if (lease) await this.#runResourceLeaseContext.run(lease, publish);
@@ -3891,9 +4170,19 @@ export class AgentSession {
 					this.#resumeFromOwnedCompletion();
 				try {
 					if (survivors.length === 1) {
-						await this.agent.prompt(first, this.#managedFallbackPromptOptions());
+						await this.agent.prompt(first, {
+							...this.#managedFallbackPromptOptions(),
+							onRunAccepted: (handle: AttemptRunHandle) => {
+								if (handle) this.#acceptSdkAttemptRun(handle);
+							},
+						});
 					} else {
-						await this.agent.prompt(survivors, this.#managedFallbackPromptOptions());
+						await this.agent.prompt(survivors, {
+							...this.#managedFallbackPromptOptions(),
+							onRunAccepted: (handle: AttemptRunHandle) => {
+								if (handle) this.#acceptSdkAttemptRun(handle);
+							},
+						});
 					}
 				} finally {
 					// The owned completions were delivered OR the prompt attempt
@@ -3911,11 +4200,32 @@ export class AgentSession {
 					async () => {
 						await run();
 					},
-					{ delayMs: 1 },
+					// One merge window, so staggered completions share a single wake
+					// turn instead of each buying its own.
+					{ delayMs: FOLD_WAKE_MERGE_WINDOW_MS },
 				);
 			},
 		});
 		this.agent.setOnBeforeYield(() => this.yieldQueue.flush("streaming"));
+		// Stop-after-result, never abort: a fold arms this once and the loop ends the
+		// turn at its next checkpoint. Consuming the flag here keeps the pause scoped
+		// to the folded turn instead of pausing everything that follows. The
+		// config-provided checkpoint (subagent requestPause, RLM research) is OR-ed
+		// in, never replaced.
+		// sdk/session.ts threads the config's shouldPause into new Agent, so the
+		// Agent's current checkpoint IS the config-provided one (subagent
+		// requestPause, RLM research). Capture and OR it rather than replace it.
+		const configuredShouldPause = this.agent.shouldPause;
+		this.agent.setShouldPause(() => {
+			if (configuredShouldPause?.() === true) return true;
+			if (!this.#foldStopRequested) return false;
+			this.#foldStopRequested = false;
+			// The folded turn has now actually stopped: steering admission must be
+			// restored so later turns drain their queues normally (the fence stays
+			// armed from the fold until exactly this point).
+			this.agent.setSteeringAdmissionFence(undefined);
+			return true;
+		});
 		this.agent.setMaintainContext((context, lifecycle) =>
 			this.#trackMidRunMaintenance(
 				this.awaitPendingContextTransformations().then(() => this.#runMidRunMaintenance(context, lifecycle)),
@@ -4054,6 +4364,18 @@ export class AgentSession {
 			if (messages.some(message => ownedCompletionResumeAction(message) === "fresh")) {
 				this.#resumeFromOwnedCompletion();
 			}
+			const consumedSdkRunTokenForCurrentRun = messages
+				.map(message => this.#sdkRunTokensByQueuedMessage.get(message))
+				.find((token): token is string => token !== undefined);
+			if (
+				consumedSdkRunTokenForCurrentRun !== undefined &&
+				this.#activeAttemptScope !== undefined &&
+				promotion.startsOwnRun !== true
+			) {
+				this.#sdkRunTokensByAttemptScope.set(this.#activeAttemptScope, consumedSdkRunTokenForCurrentRun);
+				this.#skipPostPromptRecoveryWaitByAttemptScope.add(this.#activeAttemptScope);
+				this.#activeSdkRunToken = consumedSdkRunTokenForCurrentRun;
+			}
 			// Monitor task-notifications now carry the owned-completion envelope
 			// (see tools/monitor.ts), so the general drop + fresh-admission paths
 			// above cover them exactly like async results — no monitor-specific
@@ -4089,6 +4411,18 @@ export class AgentSession {
 		// submitter to the in-flight run instead of parking the correlation for
 		// an unrelated later agent_start (#4668).
 		this.agent.onSteeringConsumed = (messages, promotion = { startsOwnRun: false }) => {
+			const consumedSdkRunToken = messages
+				.map(message => this.#sdkRunTokensByQueuedMessage.get(message))
+				.find((token): token is string => token !== undefined);
+			if (
+				consumedSdkRunToken !== undefined &&
+				this.#activeAttemptScope !== undefined &&
+				promotion.startsOwnRun !== true
+			) {
+				this.#sdkRunTokensByAttemptScope.set(this.#activeAttemptScope, consumedSdkRunToken);
+				this.#skipPostPromptRecoveryWaitByAttemptScope.add(this.#activeAttemptScope);
+				this.#activeSdkRunToken = consumedSdkRunToken;
+			}
 			this.#fireQueuedPromotionHooks(messages, promotion);
 		};
 		this.agent.providerSessionState = this.#providerSessionState;
@@ -5001,6 +5335,10 @@ export class AgentSession {
 	 * seen.
 	 */
 	#coordinatorToolObservations = new WeakMap<object, CoordinatorToolObservation>();
+	#agentEventAdmission = new WeakMap<
+		object,
+		{ scope?: AttemptScope; sdkRunToken?: string; persistGeneration: number }
+	>();
 
 	/**
 	 * Capture what is true at the SYNCHRONOUS agent-event boundary, before any async work.
@@ -5056,6 +5394,11 @@ export class AgentSession {
 	}
 
 	#trackAgentEvent = (event: AgentEvent): Promise<void> => {
+		this.#agentEventAdmission.set(event, {
+			scope: this.#activeAttemptScope,
+			sdkRunToken: this.#activeSdkRunToken,
+			persistGeneration: this.#coordinatorPersistGeneration,
+		});
 		// First statement of the listener: the observation must precede every claim,
 		// reservation, and async hop this handler performs.
 		this.#observeCoordinatorToolEvent(event);
@@ -5125,10 +5468,10 @@ export class AgentSession {
 					this.#postPromptLeases.set(eventLease.resourceRunId, eventLease);
 				if (eventLease) {
 					await this.#runResourceLeaseContext.run(eventLease, () =>
-						this.#handleAgentEvent(event, activePromptHandle, canonicalAdmission),
+						this.#handleAgentEvent(event, activePromptHandle, canonicalAdmission, eventLease),
 					);
 				} else {
-					await this.#handleAgentEvent(event, activePromptHandle, canonicalAdmission);
+					await this.#handleAgentEvent(event, activePromptHandle, canonicalAdmission, undefined);
 				}
 			} catch (error) {
 				logger.warn("Agent event handler failed", { event: event.type, error: String(error) });
@@ -5136,11 +5479,19 @@ export class AgentSession {
 				canonicalAdmission?.release();
 				if (eventLease) {
 					const pendingAgentEnd =
-						event.type === "agent_end" && !maintenanceCheckpoint && this.#pendingAgentEndEmit === event
+						event.type === "agent_end" &&
+						!maintenanceCheckpoint &&
+						(this.#pendingAgentEndEmit === event || this.#deferredAgentEndLeases.has(event))
 							? this.#pendingAgentEndEmit
 							: undefined;
 					if (pendingAgentEnd) {
 						this.#deferredAgentEndLeases.set(pendingAgentEnd, eventLease);
+					} else if (
+						event.type === "agent_end" &&
+						!maintenanceCheckpoint &&
+						this.#deferredAgentEndLeases.has(event)
+					) {
+						// Fast publication took ownership of the lease before the handler unwound.
 					} else {
 						if (event.type === "agent_end" && this.#postPromptLeases.get(eventLease.resourceRunId) === eventLease)
 							this.#postPromptLeases.delete(eventLease.resourceRunId);
@@ -5163,21 +5514,61 @@ export class AgentSession {
 	/** Serializes sidecar writes in publication order, independent of write latency. */
 	#coordinatorPersistQueue: Promise<void> = Promise.resolve();
 
+	#recordPostPublicationOutcome(
+		context: { sessionId: string; cwd: string; sessionFile: string | undefined },
+		correlationId: string | undefined,
+		kind: "worker_integration" | "terminal_persistence",
+		outcome: { status: "completed" | "failed" | "timed_out"; error?: string },
+	): void {
+		if (outcome.status !== "completed") {
+			const correlation = correlationId ?? context.sessionId;
+			const safeError = sanitizePostPublicationError(outcome.error);
+			this.#emit({
+				type: "notice",
+				level: "error",
+				source: kind,
+				message: `${kind} ${outcome.status} for ${correlation}${safeError ? `: ${safeError}` : ""}`,
+			});
+		}
+		const persist = () =>
+			persistCoordinatorWorkerIntegrationOutcome(context, {
+				...outcome,
+				kind,
+				correlationId,
+				error: sanitizePostPublicationError(outcome.error),
+			});
+		const queued = this.#coordinatorPersistQueue.then(persist, persist);
+		this.#coordinatorPersistQueue = queued.catch(() => {});
+		void queued.catch(error =>
+			logger.warn("Failed to persist terminal reconciliation outcome", { error: String(error) }),
+		);
+	}
+
 	/**
 	 * Reserve this event's place in the sidecar write order.
 	 *
 	 * Called immediately BEFORE local delivery so a synchronous subscriber that re-enters
 	 * the session cannot get its own, later event persisted first. The returned promise is
-	 * only awaited where durability must precede delivery (terminal `agent_end`).
+	 * awaited only by callers that explicitly require a durable handoff; interactive
+	 * terminal delivery remains independent of this secondary sink.
 	 *
 	 * A pairing-only tool event takes no place in that order at all — neither its start nor
 	 * its end. It describes a call that was never dispatched, and this file is read as the
 	 * answer to "what is this session doing right now".
 	 */
-	#queueCoordinatorRuntimeStatePersist(event: AgentSessionEvent): Promise<void> {
+	#queueCoordinatorRuntimeStatePersist(event: AgentSessionEvent, propagateFailure = false): Promise<void> {
 		if (isNonDispatchedToolEvent(event)) return Promise.resolve();
 		const observation = this.#coordinatorToolObservations.get(event);
-		const run = () => this.#persistRuntimeStateInBackground(event, observation);
+		const context = {
+			sessionId: this.sessionId,
+			cwd: this.sessionManager.getCwd(),
+			sessionFile: this.sessionManager.getSessionFile(),
+		};
+		const generation = this.#agentEventAdmission.get(event)?.persistGeneration ?? this.#coordinatorPersistGeneration;
+		const run = () =>
+			generation === this.#coordinatorPersistGeneration
+				? this.#persistRuntimeStateInBackground(event, context, observation, propagateFailure)
+				: Promise.resolve();
 		const queued = this.#coordinatorPersistQueue.then(run, run);
 		this.#coordinatorPersistQueue = queued.catch(() => {});
 		return queued;
@@ -5185,24 +5576,19 @@ export class AgentSession {
 
 	async #persistRuntimeStateInBackground(
 		event: AgentSessionEvent,
+		context: { sessionId: string; cwd: string; sessionFile: string | undefined },
 		observation: CoordinatorToolObservation | undefined,
+		propagateFailure: boolean,
 	): Promise<void> {
 		try {
-			await persistCoordinatorRuntimeStateFromEvent(
-				event,
-				{
-					sessionId: this.sessionId,
-					cwd: this.sessionManager.getCwd(),
-					sessionFile: this.sessionManager.getSessionFile(),
-				},
-				observation,
-			);
-		} catch {
+			await persistCoordinatorRuntimeStateFromEvent(event, context, observation);
+		} catch (error) {
 			logger.warn("Failed to persist coordinator runtime state", { event: event.type });
+			if (propagateFailure) throw error;
 		}
 	}
 
-	async #emitSessionEvent(event: AgentSessionEvent): Promise<void> {
+	async #emitSessionEvent(event: AgentSessionEvent, eventLease?: RunResourceProducerLease): Promise<void> {
 		const attemptScope = (event as AgentSessionEvent & { scope?: AttemptScope }).scope;
 		if (event.type === "turn_start") {
 			this.#extensionTurnGeneration++;
@@ -5236,6 +5622,18 @@ export class AgentSession {
 		// have unwound. Subscribers treat this event as the ready signal; flushing it
 		// from abort while either barrier is active permits a successor to race the
 		// prior prompt's cleanup.
+		const sdkTerminal =
+			event.type === "agent_end" && attemptScope !== undefined && this.#sdkRunTokensByAttemptScope.has(attemptScope);
+		if (
+			event.type === "agent_end" &&
+			sdkTerminal &&
+			this.#pendingAgentEndContinuationHolds.size === 0 &&
+			this.#pendingAgentEndEmit === undefined
+		) {
+			if (eventLease) this.#deferredAgentEndLeases.set(event, eventLease);
+			this.#startAgentEndPublication(event, eventLease);
+			return;
+		}
 		if (event.type === "agent_end" && (this.#livePromptsInFlight() > 0 || this.#agentEventHandlersInFlight > 0)) {
 			this.#pendingAgentEndEmit = event;
 			return;
@@ -5244,8 +5642,12 @@ export class AgentSession {
 		if (event.type === "agent_end") {
 			// Start the durable terminal write before synchronous subscribers can
 			// re-enter prompt(), so a successor's running transition serializes after it.
-			await this.#queueCoordinatorRuntimeStatePersist(event);
+			// Do not let a lock-hostile sidecar suppress the terminal event itself.
+			const terminalPersistence = this.#queueCoordinatorRuntimeStatePersist(event);
 			this.#emit(event);
+			void terminalPersistence.catch(error => {
+				logger.warn("Failed to persist terminal coordinator runtime state", { error: String(error) });
+			});
 			await this.#emitExtensionEvent(event);
 			return;
 		}
@@ -5341,6 +5743,7 @@ export class AgentSession {
 		event: AgentEvent,
 		activePromptHandle?: string,
 		canonicalAdmission?: CanonicalMessageAdmission,
+		eventLease?: RunResourceProducerLease,
 	): Promise<void> => {
 		const attemptScope = (event as AgentEvent & { scope?: AttemptScope }).scope;
 
@@ -5680,7 +6083,7 @@ export class AgentSession {
 			});
 		}
 
-		await this.#emitSessionEvent(displayEvent);
+		await this.#emitSessionEvent(displayEvent, eventLease);
 		if (event.type === "message_end" && event.message.role === "assistant") {
 			this.#assistantAttemptScopes.set(event.message, {
 				scope: attemptScope,
@@ -6030,6 +6433,7 @@ export class AgentSession {
 						skipCompactionCheck: true,
 						resourceRunId: activePromptHandle,
 						maintenanceContinuation: true,
+						sdkRunToken: attemptScope ? this.#sdkRunTokensByAttemptScope.get(attemptScope) : undefined,
 					});
 				}
 				return;
@@ -6317,8 +6721,11 @@ export class AgentSession {
 		predecessorAgentEndHold?: symbol;
 		/** Internal predecessor terminal event sequestered while waiting behind selection. */
 		deferredPredecessorAgentEnd?: AgentSessionEvent;
+		/** Internal causal SDK owner captured when this continuation was scheduled. */
+		sdkRunToken?: string;
 	}): Promise<void> {
 		const continuationAdmission = this.#captureScheduledContinuationAdmission();
+		const scheduledSdkRunToken = options?.sdkRunToken;
 		const selectionFenceGeneration =
 			options?.selectionFenceGeneration ??
 			this.#selectionFenceGenerationContext.getStore() ??
@@ -6340,6 +6747,7 @@ export class AgentSession {
 						generation: deferredPromptGeneration,
 						selectionFenceGeneration,
 						deferredPredecessorAgentEnd,
+						sdkRunToken: scheduledSdkRunToken,
 					});
 				} finally {
 					// The recursive call synchronously re-reserved its settlement
@@ -6475,18 +6883,18 @@ export class AgentSession {
 												// agent_start (review P1); their queued messages are in-run
 												// consumptions, not own-run promotions.
 												const startsOwn = options?.maintenanceContinuation !== true;
-												const consumedSdkRunToken = startsOwn
-													? acceptance.consumedQueuedMessages
-															.map(message => this.#sdkRunTokensByQueuedMessage.get(message))
-															.find((token): token is string => token !== undefined)
-													: undefined;
+												const inheritedSdkRunToken = options?.continueQueuedOnly
+													? undefined
+													: (options?.sdkRunToken ?? scheduledSdkRunToken);
+												const consumedSdkRunToken = acceptance.consumedQueuedMessages
+													.map(message => this.#sdkRunTokensByQueuedMessage.get(message))
+													.find((token): token is string => token !== undefined);
+												const sdkRunToken = consumedSdkRunToken ?? inheritedSdkRunToken;
 												this.#fireQueuedPromotionHooks(acceptance.consumedQueuedMessages, {
 													startsOwnRun: startsOwn,
 												});
-												if (consumedSdkRunToken !== undefined)
-													this.#sdkRunTokensByAttemptScope.set(handle.scope, consumedSdkRunToken);
-												if (startsOwn) this.#activeSdkRunToken = consumedSdkRunToken;
-												this.#acceptRunHandle(handle);
+												if (startsOwn) this.#activeSdkRunToken = sdkRunToken;
+												this.#acceptSdkAttemptRun(handle, sdkRunToken);
 												options?.onRunAccepted?.(handle);
 												// Keep the queued token available through the acceptance callback;
 												// SDK follow-up owners bind it to the new attempt scope there.
@@ -6649,8 +7057,12 @@ export class AgentSession {
 		resourceRunId?: string,
 		deferredSelectionFenceGeneration?: number,
 		deferredPredecessorAgentEnd?: AgentSessionEvent,
+		sdkRunToken?: string,
 	): void {
 		const scheduledGeneration = generation;
+		const scheduledSdkRunToken =
+			sdkRunToken ??
+			(this.#activeAttemptScope ? this.#sdkRunTokensByAttemptScope.get(this.#activeAttemptScope) : undefined);
 		const continuationAuthorized = async (
 			signal: AbortSignal,
 			hasPendingNextTurnMessages = false,
@@ -6703,6 +7115,7 @@ export class AgentSession {
 						resourceRunId,
 						selectionFenceGeneration,
 						predecessorAgentEnd,
+						scheduledSdkRunToken,
 					);
 				} finally {
 					this.#endSelectionFenceDeferralTracking(selectionFenceGeneration);
@@ -6750,6 +7163,7 @@ export class AgentSession {
 								promptText,
 								{
 									skipPostPromptRecoveryWait: true,
+									sdkRunToken: scheduledSdkRunToken,
 									skipCompactionCheck: true,
 									predecessorAgentEndHold,
 									onFinalPreflight: ({ hasPendingNextTurnMessages }) =>
@@ -7527,16 +7941,16 @@ export class AgentSession {
 		this.#workerIntegrationScheduler?.enqueue();
 	}
 
-	async #flushWorkerIntegrationAttempt(): Promise<void> {
-		await this.#workerIntegrationScheduler?.flush();
+	async #flushWorkerIntegrationAttempt(): Promise<WorkerIntegrationOutcome> {
+		return (await this.#workerIntegrationScheduler?.flushWithOutcome()) ?? { status: "completed" };
 	}
 
-	async #flushWorkerIntegrationForAgentEnd(): Promise<void> {
+	async #flushWorkerIntegrationForAgentEnd(): Promise<WorkerIntegrationOutcome> {
 		if (!this.#workerIntegrationRequestedForTurn) {
 			this.#requestWorkerIntegrationAttempt();
 		}
 		try {
-			await this.#flushWorkerIntegrationAttempt();
+			return await this.#flushWorkerIntegrationAttempt();
 		} finally {
 			this.#workerIntegrationRequestedForTurn = false;
 		}
@@ -7549,6 +7963,9 @@ export class AgentSession {
 		workerIntegrationSettled = false,
 		scope?: AttemptScopeRef,
 	): Promise<void> {
+		const admission = this.#agentEventAdmission.get(event);
+		const activeAttemptScopeAtEvent = admission === undefined ? this.#activeAttemptScope : admission.scope;
+		const activeSdkRunTokenAtEvent = admission === undefined ? this.#activeSdkRunToken : admission.sdkRunToken;
 		if (event.type === "agent_end" && !workerIntegrationSettled) {
 			await this.#flushWorkerIntegrationForAgentEnd();
 		}
@@ -7559,20 +7976,36 @@ export class AgentSession {
 				? eventToken
 				: deliveryScope
 					? this.#sdkRunTokensByAttemptScope.get(deliveryScope as AttemptScope)
-					: this.#activeSdkRunToken;
+					: undefined;
 		const isTerminalAgentEnd =
 			event.type === "agent_end" && !(event.stopReason === "maintenance" && event.maintenanceOutcome !== "aborted");
 		const finishAttempt = () => {
 			if (!isTerminalAgentEnd) return;
+			// A merged wake batch whose flush fired while still streaming cleared its
+			// pending flag without rescheduling. Returning to idle is exactly when it
+			// becomes deliverable again, so rearm here rather than waiting for an
+			// unrelated enqueue.
+			this.yieldQueue.rearmIdle();
 			const isActiveAttempt =
-				deliveryScope === undefined ||
-				this.#activeAttemptScope === undefined ||
-				deliveryScope === this.#activeAttemptScope;
+				deliveryScope === undefined
+					? this.#activeAttemptScope === activeAttemptScopeAtEvent &&
+						this.#activeSdkRunToken === activeSdkRunTokenAtEvent
+					: deliveryScope === activeAttemptScopeAtEvent &&
+						deliveryScope === this.#activeAttemptScope &&
+						this.#activeSdkRunToken === activeSdkRunTokenAtEvent;
+			if (this.#foldStopRequested) {
+				this.#foldStopRequested = false;
+				this.agent.setSteeringAdmissionFence(undefined);
+			}
 			if (deliveryScope) {
 				this.#attemptRecordStore.retire(deliveryScope as AttemptScope);
-				this.#sdkRunTokensByAttemptScope.delete(deliveryScope as AttemptScope);
+				if (
+					activeSdkRunTokenAtEvent !== undefined &&
+					this.#sdkRunTokensByAttemptScope.get(deliveryScope as AttemptScope) === activeSdkRunTokenAtEvent
+				)
+					this.#sdkRunTokensByAttemptScope.delete(deliveryScope as AttemptScope);
 			}
-			if (isActiveAttempt && sdkRunToken === this.#activeSdkRunToken) this.#activeSdkRunToken = undefined;
+			if (isActiveAttempt) this.#activeSdkRunToken = undefined;
 			if (isActiveAttempt) {
 				this.#activeAttemptScope = undefined;
 				this.#activeLogicalRunId = undefined;
@@ -7840,8 +8273,18 @@ export class AgentSession {
 		const sid = this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
 		this.agent.sessionId = sid;
 		this.agent.providerSessionId = this.#providerCacheSessionId ?? sid;
-		this.agent.setMetadataResolver((provider: string) =>
-			buildSessionMetadata(sid, provider, this.#modelRegistry.authStorage, this.credentialSessionId),
+		this.agent.setMetadataResolver(context =>
+			buildSessionMetadata(
+				sid,
+				context.provider,
+				this.#modelRegistry.authStorage,
+				this.credentialSessionId,
+				context.model ?? this.model,
+				// Optional call: the metadata resolver runs on every prompt, and `owner` is an
+				// optional `buildSessionMetadata` argument. The auth-credential paths keep the
+				// strict call because they genuinely require a real registry owner.
+				this.#modelRegistry.getAuthStorageOwner?.(),
+			),
 		);
 	}
 
@@ -8454,13 +8897,39 @@ export class AgentSession {
 	 * handler, so Ctrl+B-style folding fails closed instead of aborting or
 	 * shell-suspending arbitrary work.
 	 */
-	registerForegroundBashBackgroundRequestHandler(handler: () => void): () => void {
-		this.#foregroundBashBackgroundRequestHandler = handler;
-		return () => {
-			if (this.#foregroundBashBackgroundRequestHandler === handler) {
-				this.#foregroundBashBackgroundRequestHandler = undefined;
-			}
-		};
+	registerForegroundFoldParticipant(adapter: FoldAdapter): () => void {
+		return this.#foldCoordinator.registerParticipant(adapter);
+	}
+
+	/** The session-owned fold coordinator, for delivery-side receipt lookup. */
+	get foldCoordinator(): FoldCoordinator {
+		return this.#foldCoordinator;
+	}
+
+	/**
+	 * Best-effort capture of what the interrupted turn still intended to do, so
+	 * the wake turn can finish the original task instead of only reporting output.
+	 */
+	#captureRemainingIntentForFold(): string | undefined {
+		const messages = this.agent.state.messages;
+		for (let index = messages.length - 1; index >= 0; index--) {
+			const message = messages[index];
+			if (message?.role !== "user") continue;
+			const content = message.content;
+			const text =
+				typeof content === "string"
+					? content
+					: Array.isArray(content)
+						? content
+								.map(block => (typeof block === "object" && block && "text" in block ? String(block.text) : ""))
+								.filter(Boolean)
+								.join("\n")
+						: "";
+			const trimmed = text.trim();
+			if (trimmed.length === 0) return undefined;
+			return trimmed.length > 2000 ? `${trimmed.slice(0, 2000)}…` : trimmed;
+		}
+		return undefined;
 	}
 
 	/**
@@ -8469,7 +8938,7 @@ export class AgentSession {
 	 * no fold target exists.
 	 */
 	hasForegroundBashBackgroundRequestHandler(): boolean {
-		return this.#foregroundBashBackgroundRequestHandler !== undefined;
+		return this.#foldCoordinator.hasFoldableParticipant();
 	}
 
 	/** Set the SDK permission policy used by guarded ACP tool execution. */
@@ -8505,11 +8974,17 @@ export class AgentSession {
 	 * Ask the active managed foreground bash call to return as a background job.
 	 * Returns false when no supported foreground tool is currently backgroundable.
 	 */
-	requestForegroundBashBackground(): boolean {
-		const handler = this.#foregroundBashBackgroundRequestHandler;
-		if (!handler) return false;
-		handler();
-		return true;
+	async requestForegroundBashBackground(): Promise<boolean> {
+		if (!this.#foldCoordinator.hasFoldableParticipant()) return false;
+		try {
+			const result = await this.#foldCoordinator.requestFold();
+			return result.status === "folded";
+		} catch (error) {
+			logger.warn("Foreground fold request failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return false;
+		}
 	}
 
 	/**
@@ -9450,6 +9925,7 @@ export class AgentSession {
 		if (this.#sessionAdmissionClosed || this.#isDisposed) throw this.#sessionAdmissionBusyError();
 		const inFlightPrompt = this.#beginInFlight();
 		let hindsightRecall: string | undefined;
+		let continuationSdkRunToken: string | undefined;
 		try {
 			const volatileProjectContextMessage = await this.#buildVolatileProjectContextMessage();
 			this.agent.appendMessage(volatileProjectContextMessage);
@@ -9485,14 +9961,18 @@ export class AgentSession {
 			await this.agent.continue({
 				...this.#managedFallbackPromptOptions(),
 				onRunAccepted: (handle: AttemptRunHandle) => {
-					this.#acceptRunHandle(handle);
+					continuationSdkRunToken = this.#activeSdkRunToken;
+					this.#acceptSdkAttemptRun(handle, continuationSdkRunToken);
 					if (hindsightRecall) hindsightState?.markRecallSnippetInjected(hindsightRecall);
 				},
 			});
-			await this.#waitForPostPromptRecovery();
+			if (continuationSdkRunToken === undefined) await this.#waitForPostPromptRecovery();
 		} finally {
 			this.#removeEphemeralCustomMessages();
-			await this.#settleEndedInFlight(inFlightPrompt);
+			await this.#settleEndedInFlight(
+				inFlightPrompt,
+				continuationSdkRunToken === undefined ? "full" : "publication",
+			);
 		}
 	}
 
@@ -9620,8 +10100,9 @@ export class AgentSession {
 	async setCredentialPin(provider: string, selector: AuthCredentialSelector): Promise<void> {
 		const scopeId = this.credentialSessionId;
 		const authStorage = this.#modelRegistry.authStorage;
-		const target = authStorage.resolveOAuthPinTarget(provider, selector);
-		authStorage.setSessionCredentialSelector(scopeId, provider, target.canonicalSelector);
+		const authStorageOwner = this.#modelRegistry.getAuthStorageOwner();
+		const target = authStorage.resolveOAuthPinTarget(provider, selector, authStorageOwner);
+		authStorage.setSessionCredentialSelector(scopeId, provider, target.canonicalSelector, authStorageOwner);
 		if (target.canonicalSelector.kind === "id" && !this.#credentialStoreIdentity) return;
 		this.sessionManager.appendCustomEntry("auth-credential-pin", {
 			v: 1,
@@ -9701,9 +10182,13 @@ export class AgentSession {
 		args = "",
 		options?: Pick<
 			PromptOptions,
-			"onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared" | "preflightSignal" | "sdkRunToken"
+			"onPreflightAccepted" | "onPreflightAcceptCommit" | "onSkillPrepared" | "preflightSignal" | "sdkRunCapability"
 		>,
 	): Promise<{ name: string; path: string; args?: string; lineCount?: number }> {
+		const internalOptions = {
+			...options,
+			sdkRunToken: readSdkRunCapability(options?.sdkRunCapability),
+		};
 		if (options?.preflightSignal?.aborted) throw promptPreflightCancelledError();
 		const skillName = name.trim();
 		if (!skillName) throw Object.assign(new Error("skill.invoke requires a skill name."), { code: "invalid_input" });
@@ -9749,7 +10234,7 @@ export class AgentSession {
 			lineCount: built.details.lineCount,
 			cleanedArgs: activation.cleanedArgs || undefined,
 		});
-		await this.promptCustomMessage(skillPromptMessage, options);
+		await this.promptCustomMessage(skillPromptMessage, internalOptions as InternalCustomMessageOptions);
 		return {
 			name: skill.name,
 			path: skill.filePath,
@@ -10439,6 +10924,14 @@ export class AgentSession {
 	 * @throws Error if no model selected or no API key available (when not streaming)
 	 */
 	async prompt(text: string, options?: PromptOptions): Promise<void> {
+		const hasUsableImage =
+			options?.images?.some(image => typeof image?.data === "string" && image.data.trim().length > 0) === true;
+		if (typeof text !== "string" || (text.trim().length === 0 && !hasUsableImage))
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
+		const sdkRunToken = readSdkRunCapability(options?.sdkRunCapability);
+		const internalOptions: InternalPromptOptions | undefined = options
+			? { ...options, ...(sdkRunToken ? { sdkRunToken } : {}) }
+			: undefined;
 		this.#assertRecoveryHydrationPromoted();
 		const owner = this.#sessionAdmissionContext.getStore();
 		if (owner && !owner.released) throw this.#sessionAdmissionBusyError();
@@ -10453,14 +10946,19 @@ export class AgentSession {
 					await this.invokeSkill(
 						invocation.skill.name,
 						invocation.args,
-						options?.onPreflightAccepted || options?.onPreflightAcceptCommit || options?.preflightSignal
+						options?.onPreflightAccepted ||
+							options?.onPreflightAcceptCommit ||
+							options?.preflightSignal ||
+							internalOptions?.sdkRunToken
 							? {
-									...(options.onPreflightAccepted ? { onPreflightAccepted: options.onPreflightAccepted } : {}),
-									...(options.onPreflightAcceptCommit
+									...(options?.onPreflightAccepted
+										? { onPreflightAccepted: options.onPreflightAccepted }
+										: {}),
+									...(options?.onPreflightAcceptCommit
 										? { onPreflightAcceptCommit: options.onPreflightAcceptCommit }
 										: {}),
-									...(options.preflightSignal ? { preflightSignal: options.preflightSignal } : {}),
-									...(options.sdkRunToken ? { sdkRunToken: options.sdkRunToken } : {}),
+									...(options?.preflightSignal ? { preflightSignal: options.preflightSignal } : {}),
+									...(options?.sdkRunCapability ? { sdkRunCapability: options.sdkRunCapability } : {}),
 								}
 							: undefined,
 					);
@@ -10494,6 +10992,10 @@ export class AgentSession {
 
 		// Expand file-based prompt templates if requested
 		const expandedText = expandPromptTemplates ? expandPromptTemplate(text, [...this.#promptTemplates]) : text;
+		const expandedHasUsableImage =
+			options?.images?.some(image => typeof image?.data === "string" && image.data.trim().length > 0) === true;
+		if (expandedText.trim().length === 0 && !expandedHasUsableImage)
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 		assertImagePlaceholdersHavePayload(expandedText, options?.images);
 		const workflowIntentDiff = options?.synthetic ? null : buildWorkflowIntentDiff(expandedText);
 		const claimsGenuineUserIntent = !options?.synthetic && options?.attribution !== "agent";
@@ -10714,9 +11216,13 @@ export class AgentSession {
 			| "onPreflightAccepted"
 			| "onPreflightAcceptCommit"
 			| "preflightSignal"
-			| "sdkRunToken"
+			| "sdkRunCapability"
 		>,
 	): Promise<void> {
+		const sdkRunToken = readSdkRunCapability(options?.sdkRunCapability);
+		const internalOptions: InternalCustomMessageOptions | undefined = options
+			? { ...options, ...(sdkRunToken ? { sdkRunToken } : {}) }
+			: undefined;
 		if (options?.preflightSignal?.aborted) throw promptPreflightCancelledError();
 		const textContent =
 			typeof message.content === "string"
@@ -10785,7 +11291,7 @@ export class AgentSession {
 				};
 				try {
 					await this.#promptWithMessage(customMessage, textContent, {
-						...options,
+						...internalOptions,
 						onPreflightAccepted: undefined,
 						onPreflightAcceptCommit: commitAcceptance,
 						admissionLease: admission,
@@ -10816,8 +11322,8 @@ export class AgentSession {
 			| "onPreflightAccepted"
 			| "onPreflightAcceptCommit"
 			| "preflightSignal"
-			| "sdkRunToken"
 		> & {
+			sdkRunToken?: string;
 			prependMessages?: AgentMessage[];
 			skipPostPromptRecoveryWait?: boolean;
 			predecessorAgentEndHold?: symbol;
@@ -10884,6 +11390,9 @@ export class AgentSession {
 		const rosterClaim = this.#claimIrcRosterCandidate();
 		let hasPendingNextTurnMessages = false;
 		let pendingNextTurnMessageCount = 0;
+		let skipPostPromptRecoveryWait =
+			options?.skipPostPromptRecoveryWait === true || options?.sdkRunToken !== undefined;
+		let promptAttemptScope: AttemptScope | undefined;
 		let hindsightRecall: string | undefined;
 		try {
 			this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
@@ -11152,9 +11661,10 @@ export class AgentSession {
 				...this.#managedFallbackPromptOptions(),
 				...(options?.sdkRunToken ? { sdkRunToken: options.sdkRunToken } : {}),
 				onRunAccepted: (handle: AttemptRunHandle) => {
-					this.#acceptRunHandle(handle);
-					if (options?.sdkRunToken) {
-						this.#sdkRunTokensByAttemptScope.set(handle.scope, options.sdkRunToken);
+					promptAttemptScope = handle?.scope;
+					if (handle) this.#acceptSdkAttemptRun(handle, options?.sdkRunToken);
+					else this.#acceptRunHandle(handle);
+					if (handle && options?.sdkRunToken) {
 						this.#activeSdkRunToken = options.sdkRunToken;
 					}
 					options?.onRunAccepted?.(handle);
@@ -11189,6 +11699,20 @@ export class AgentSession {
 					options?.onPreflightAccepted?.();
 				},
 			});
+			const activeTerminalScope = this.#activeAttemptScope;
+			const terminalAttemptScope =
+				activeTerminalScope !== undefined &&
+				(this.#skipPostPromptRecoveryWaitByAttemptScope.has(activeTerminalScope) ||
+					(options?.sdkRunToken !== undefined &&
+						this.#sdkRunTokensByAttemptScope.get(activeTerminalScope) === options.sdkRunToken))
+					? activeTerminalScope
+					: promptAttemptScope;
+			if (
+				terminalAttemptScope !== undefined &&
+				this.#skipPostPromptRecoveryWaitByAttemptScope.delete(terminalAttemptScope)
+			) {
+				skipPostPromptRecoveryWait = true;
+			}
 			const terminalAssistant = this.#findLastAssistantMessage();
 			if (
 				rosterClaim &&
@@ -11198,7 +11722,7 @@ export class AgentSession {
 			) {
 				this.#commitIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
 			}
-			if (!options?.skipPostPromptRecoveryWait) {
+			if (!skipPostPromptRecoveryWait) {
 				await this.#waitForPostPromptRecovery();
 			}
 		} catch (error) {
@@ -11223,7 +11747,7 @@ export class AgentSession {
 				this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
 			}
 			this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
-			await this.#settleEndedInFlight(inFlightPrompt, options?.skipPostPromptRecoveryWait ? "publication" : "full");
+			await this.#settleEndedInFlight(inFlightPrompt, skipPostPromptRecoveryWait ? "publication" : "full");
 		}
 	}
 
@@ -11427,12 +11951,18 @@ export class AgentSession {
 	 * Queue a steering message to interrupt the agent mid-run.
 	 */
 	async steer(text: string, images?: ImageContent[]): Promise<void> {
+		const hasUsableImage =
+			images?.some(image => typeof image?.data === "string" && image.data.trim().length > 0) === true;
+		if (typeof text !== "string" || (text.trim().length === 0 && !hasUsableImage))
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 		this.#assertRecoveryHydrationPromoted();
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
 		}
 
 		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
+		if (expandedText.trim().length === 0 && !hasUsableImage)
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 		assertImagePlaceholdersHavePayload(expandedText, images);
 		await this.#queueSteer(expandedText, images, { claimsGenuineUserIntent: true });
 	}
@@ -11445,12 +11975,18 @@ export class AgentSession {
 		images?: ImageContent[],
 		options?: Pick<PromptOptions, "followUpQueuePolicy">,
 	): Promise<void> {
+		const hasUsableImage =
+			images?.some(image => typeof image?.data === "string" && image.data.trim().length > 0) === true;
+		if (typeof text !== "string" || (text.trim().length === 0 && !hasUsableImage))
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 		this.#assertRecoveryHydrationPromoted();
 		if (text.startsWith("/")) {
 			this.#throwIfExtensionCommand(text);
 		}
 
 		const expandedText = expandPromptTemplate(text, [...this.#promptTemplates]);
+		if (expandedText.trim().length === 0 && !hasUsableImage)
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 		assertImagePlaceholdersHavePayload(expandedText, images);
 		await this.#queueFollowUp(expandedText, images, {
 			forceOneAtATime: options?.followUpQueuePolicy === "sequential",
@@ -11468,6 +12004,7 @@ export class AgentSession {
 			claimsGenuineUserIntent?: boolean;
 			onPromoted?: (promotion: { startsOwnRun?: boolean; removed?: boolean }) => void;
 			external?: boolean;
+			sdkRunToken?: string;
 		},
 	): Promise<void> {
 		this.#assertNoHandoffTransition();
@@ -11482,6 +12019,7 @@ export class AgentSession {
 			this.#externalSteerAdmissionSeq.set(message, ++this.#steeringAdmissionSeq);
 			if (options.onPromoted) this.#steerPromotionHooks.set(message, options.onPromoted);
 		}
+		if (options?.sdkRunToken) this.#sdkRunTokensByQueuedMessage.set(message, options.sdkRunToken);
 		if (options?.claimsGenuineUserIntent) {
 			const epoch = this.#claimDeepInterviewUserIntent();
 			this.#deepInterviewGenuineUserMessageEpochs.set(message, epoch);
@@ -12064,9 +12602,11 @@ export class AgentSession {
 			/** Internal dispatch disposition used before actual queue consumption. */
 			onDispatchDisposition?: (promotion: { startsOwnRun: boolean }) => void;
 			preflightSignal?: AbortSignal;
-			sdkRunToken?: string;
+			sdkRunCapability?: unknown;
 		},
 	): Promise<void> {
+		const sdkRunToken = readSdkRunCapability(options?.sdkRunCapability);
+		const internalOptions = options ? { ...options, ...(sdkRunToken ? { sdkRunToken } : {}) } : undefined;
 		this.#assertRecoveryHydrationPromoted();
 		const owner = this.#sessionAdmissionContext.getStore();
 		if (owner && !owner.released) throw this.#sessionAdmissionBusyError();
@@ -12087,7 +12627,15 @@ export class AgentSession {
 			const textParts: string[] = [];
 			images = [];
 			for (const part of content) {
+				if (!part || typeof part !== "object" || Array.isArray(part))
+					throw Object.assign(new Error("sendUserMessage content blocks must be objects."), {
+						code: "invalid_input",
+					});
 				if (part.type === "text") {
+					if (typeof part.text !== "string")
+						throw Object.assign(new Error("sendUserMessage text blocks must contain string text."), {
+							code: "invalid_input",
+						});
 					textParts.push(part.text);
 				} else {
 					images.push(part);
@@ -12096,6 +12644,10 @@ export class AgentSession {
 			text = textParts.join("\n");
 			if (images.length === 0) images = undefined;
 		}
+		const hasUsableImage =
+			images?.some(image => typeof image?.data === "string" && image.data.trim().length > 0) === true;
+		if (text.trim().length === 0 && !hasUsableImage)
+			throw Object.assign(new Error("Prompt must not be empty."), { code: "invalid_input" });
 
 		let admissionSignal = options?.preflightSignal
 			? AbortSignal.any([this.#promptPreflightAbortController.signal, options.preflightSignal])
@@ -12189,7 +12741,7 @@ export class AgentSession {
 					claimsGenuineUserIntent: true,
 					forceOneAtATime: Boolean(options?.preflightSignal || options?.queuedAtDispatch),
 					onPromoted: options?.onQueuedPromoted,
-					sdkRunToken: options?.sdkRunToken,
+					sdkRunToken: internalOptions?.sdkRunToken,
 				});
 				const cancelQueuedFollowUp = () => queuedFollowUp.cancel();
 				options?.preflightSignal?.addEventListener("abort", cancelQueuedFollowUp, { once: true });
@@ -12204,6 +12756,7 @@ export class AgentSession {
 					claimsGenuineUserIntent: true,
 					onPromoted: options?.onQueuedPromoted,
 					external: true,
+					sdkRunToken: internalOptions?.sdkRunToken,
 				});
 				options?.onPreflightAccepted?.();
 				return;
@@ -12223,6 +12776,7 @@ export class AgentSession {
 					claimsGenuineUserIntent: true,
 					onPromoted: options?.onQueuedPromoted,
 					external: true,
+					sdkRunToken: internalOptions?.sdkRunToken,
 				});
 				// Dispatch-race disposition (#4668 review P1): the SDK snapshot-decided
 				// this submission starts its own turn (idle at dispatch), but the
@@ -12248,7 +12802,7 @@ export class AgentSession {
 			await this.prompt(text, {
 				expandPromptTemplates: false,
 				images,
-				sdkRunToken: options?.sdkRunToken,
+				sdkRunToken: internalOptions?.sdkRunToken,
 				onPreflightAccepted: () => {
 					options?.onPreflightAccepted?.();
 					fireQueuedPromotion();
@@ -12263,7 +12817,7 @@ export class AgentSession {
 							}
 						: undefined,
 				preflightSignal: options?.preflightSignal,
-			});
+			} as InternalPromptOptions);
 		} finally {
 			releaseFollowUpReservation();
 		}
@@ -12772,6 +13326,7 @@ export class AgentSession {
 			| "tool_abort"
 			| "internal";
 		silent?: boolean;
+		sdkRunToken?: string;
 	}): void {
 		const abortGoalState = this.getGoalModeState();
 		this.#suppressNextGoalReminderAfterAbortGoalId =
@@ -13473,6 +14028,9 @@ export class AgentSession {
 						attribution: "user" as const,
 						timestamp: Date.now(),
 					};
+					const selectedSdkRunToken = selectedMessage
+						? this.#sdkRunTokensByQueuedMessage.get(selectedMessage)
+						: undefined;
 					const messageText =
 						message.role === "custom"
 							? this.#getCustomMessageTextContent(message)
@@ -13491,6 +14049,7 @@ export class AgentSession {
 						await this.#promptWithMessage(message, messageText, {
 							admissionLease: admission,
 							resetRetryReplaySafety: true,
+							sdkRunToken: selectedSdkRunToken,
 							onRunAccepted: () => {
 								runAccepted = true;
 								if (selected) this.#fireQueuedPromotionHooks([message], { startsOwnRun: true });
@@ -19052,6 +19611,9 @@ export class AgentSession {
 							const continuation = this.agent.continue({
 								...this.#managedFallbackPromptOptions(),
 								transientRecoveryMessage: this.#escapedNonAsciiRecoveryMessage(),
+								onRunAccepted: (handle: AttemptRunHandle) => {
+									this.#acceptSdkAttemptRun(handle, this.#activeSdkRunToken);
+								},
 							});
 							if (
 								cancellationSignal?.aborted ||
@@ -19090,6 +19652,9 @@ export class AgentSession {
 					await this.agent.continue({
 						...this.#managedFallbackPromptOptions(),
 						transientRecoveryMessage: this.#escapedNonAsciiRecoveryMessage(),
+						onRunAccepted: (handle: AttemptRunHandle) => {
+							this.#acceptSdkAttemptRun(handle, this.#activeSdkRunToken);
+						},
 					});
 				},
 			};
@@ -19519,11 +20084,13 @@ export class AgentSession {
 			if (!isAuthenticated(activeApiKey)) return "unchanged";
 			remaining = await authStorage.invalidateCredentialMatching(provider, activeApiKey, {
 				sessionId: credentialSessionId,
+				owner: this.#modelRegistry.getAuthStorageOwner(),
 			});
 			if (!remaining) return "unchanged";
 		} else {
 			remaining = await authStorage.markUsageLimitReached(provider, credentialSessionId, {
 				retryAfterMs: trigger.retryAfterMs,
+				owner: this.#modelRegistry.getAuthStorageOwner(),
 			});
 		}
 
@@ -20031,7 +20598,12 @@ export class AgentSession {
 						this.#resolveRetry();
 						return;
 					}
-					await this.agent.continue(this.#managedFallbackPromptOptions());
+					await this.agent.continue({
+						...this.#managedFallbackPromptOptions(),
+						onRunAccepted: (handle: AttemptRunHandle) => {
+							this.#acceptSdkAttemptRun(handle, this.#activeSdkRunToken);
+						},
+					});
 					return;
 				} catch (error) {
 					const attempt = this.#retryAttempt;
@@ -21068,6 +21640,9 @@ export class AgentSession {
 						model.provider,
 						this.#modelRegistry.authStorage,
 						this.credentialSessionId,
+						model,
+						// Optional for the same reason as the main metadata resolver above.
+						this.#modelRegistry.getAuthStorageOwner?.(),
 					),
 					reasoning: toReasoningEffort(this.thinkingLevel),
 					hideThinkingSummary: this.agent.hideThinkingSummary,