@gajae-code/coding-agent 0.12.19 → 0.12.21

package/src/session/agent-session.ts

@@ -431,8 +431,8 @@ import type {
 	RecoveryHydrationPromotionFence,
 	SessionContext,
 	SessionEntry,
-	SessionManager,
 	SessionManagerCloseOutcome,
+	SessionMemoryStats,
 } from "./session-manager";
 
 import {
@@ -441,6 +441,8 @@ import {
 	getSessionMessageEntryId,
 	getSessionMessageObservationId,
 	SessionAppendPersistenceError,
+	SessionContextTooLargeError,
+	SessionManager,
 	transferSessionMessageIdentity,
 } from "./session-manager";
 import { getEntriesForInternalRead, getSessionContextForInternalRead } from "./session-manager-internal";
@@ -744,6 +746,17 @@ type AutoCompactionTerminalStatus =
 	| { kind: "skipped"; continuationScheduled?: boolean }
 	| { kind: "failed" };
 
+/**
+ * R3.2 pre-submit seam: `build` assembles the attempt messages (Phase A once,
+ * Phase B per attempt) and may throw the typed overflow error; `reset` drops the
+ * cached Phase B attempt messages so the next `build` rebuilds them (used after a
+ * forced compaction retry).
+ */
+type PreSubmitBuilder = {
+	build: () => Promise<AgentMessage[] | null>;
+	reset: () => void;
+};
+
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
 	/** Whether to expand file-based prompt templates (default: true) */
@@ -769,8 +782,8 @@ export interface PromptOptions {
 	 */
 	onPreflightAccepted?: () => void;
 	/**
-	 * Awaitable durable-accept fence. Called after preflight and before queue mutation
-	 * or `#promptAgentWithIdleRetry`. SDK bus installs a closure that fsyncs acceptance.
+	 * Awaitable durable-accept fence. Called after preflight and immediately before
+	 * agent execution begins. SDK bus installs a closure that fsyncs acceptance.
 	 */
 	onPreflightAcceptCommit?: () => void | Promise<void>;
 	/** Skill-only: prepared metadata before the durable fence (path/lineCount/cleanedArgs). */
@@ -904,6 +917,7 @@ export interface SessionStats {
 	premiumRequests: number;
 	cost: number;
 	costBreakdown?: Usage["cost"];
+	sessionMemory: SessionMemoryStats;
 }
 
 /** Internal marker for hook messages queued through the agent loop */
@@ -1798,7 +1812,7 @@ function deobfuscateSessionContext(context: SessionContext, obfuscator: SecretOb
 
 export class AgentSession {
 	readonly agent: Agent;
-	readonly sessionManager: SessionManager;
+	sessionManager: SessionManager;
 	readonly settings: Settings;
 	readonly memoryBackend: LazyService<MemoryBackend>;
 	readonly notificationSessionController: NotificationSessionController | undefined;
@@ -2015,7 +2029,11 @@ export class AgentSession {
 
 	// Bash execution state
 	#bashAbortControllers = new Set<AbortController>();
-	#pendingBashMessages: BashExecutionMessage[] = [];
+	#pendingBashMessages: Array<{
+		message: BashExecutionMessage;
+		onPersisted?: () => void;
+		appendedToAgent: boolean;
+	}> = [];
 	#foregroundBashBackgroundRequestHandler: (() => void) | undefined;
 
 	// Python execution state
@@ -2024,6 +2042,7 @@ export class AgentSession {
 	/** Idempotent unregister handle for this session's resource-GC registration. */
 	#unregisterResourceGc?: () => void;
 	#unregisterRuntimeStateFinalizer?: () => void;
+	#unregisterSessionMemorySettings?: () => void;
 	/**
 	 * AsyncJobManager owned by this session (top-level only). Subagents leave
 	 * this undefined and **MUST NOT** dispose the global instance on teardown.
@@ -2031,7 +2050,11 @@ export class AgentSession {
 	readonly #ownedAsyncJobManager: AsyncJobManager | undefined;
 	readonly #ownedMcpManager: MCPManager | undefined;
 	#startupTurnBarrier: Promise<void> | undefined;
-	#pendingPythonMessages: PythonExecutionMessage[] = [];
+	#pendingPythonMessages: Array<{
+		message: PythonExecutionMessage;
+		onPersisted?: () => void;
+		appendedToAgent: boolean;
+	}> = [];
 	#activeEvalExecutions = new Set<Promise<unknown>>();
 	#evalExecutionDisposing = false;
 
@@ -2584,14 +2607,62 @@ export class AgentSession {
 		}
 	}
 
-	#endInFlight(): void {
+	#endInFlight(): unknown {
 		this.#promptInFlightCount = Math.max(0, this.#promptInFlightCount - 1);
-		if (this.#promptInFlightCount === 0) {
-			this.#releasePowerAssertion();
-			this.#refreshTeamWorkerHeartbeat();
+		if (this.#promptInFlightCount !== 0) return undefined;
+
+		this.#releasePowerAssertion();
+		this.#refreshTeamWorkerHeartbeat();
+		let flushError: unknown;
+		try {
+			// The turn is over, so nothing can split a tool_use/tool_result pair any
+			// more: a `!`/`$` block that finished mid-stream must own its place in
+			// agent state and the session now, not at the next prompt. Until it does,
+			// the TUI shows output the transcript lacks and `onPersisted` stays unfired,
+			// so a rebuild in that gap drops the only rendering of the execution.
+			this.#flushPendingPromptMessages();
+		} catch (error) {
+			flushError = error;
+		}
+		this.#flushPendingAgentEnd();
+		return flushError;
+	}
+	async #settleEndedInFlight(promptWait?: "publication" | "full"): Promise<void> {
+		const flushError = this.#endInFlight();
+		const predecessorPromptStillInFlight = this.#promptInFlightCount > 0;
+		if (promptWait === "publication") {
+			await this.#agentEndPublicationPromise;
+		} else if (promptWait === "full") {
+			await this.#agentEndHandlingPromise;
+			await this.#waitForPostPromptRecovery();
+			await this.#agentEndPublicationPromise;
+		}
+		// A post-prompt continuation runs before its predecessor prompt returns. Its
+		// publication must settle, but session-wide settlement can still be owned by
+		// that predecessor; waiting here would make each prompt wait on the other.
+		if (!predecessorPromptStillInFlight) await this.#waitForSessionSettlement();
+		if (flushError) throw flushError;
+	}
+
+	#flushPendingPromptMessages(): void {
+		const errors: unknown[] = [];
+		try {
+			this.#flushPendingBashMessages();
+		} catch (error) {
+			errors.push(error);
+		}
+		try {
+			this.#flushPendingPythonMessages();
+		} catch (error) {
+			errors.push(error);
+		}
+		try {
 			this.#flushPendingBackgroundExchanges();
-			this.#flushPendingAgentEnd();
+		} catch (error) {
+			errors.push(error);
 		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "Multiple deferred prompt messages failed to flush");
 	}
 
 	#refreshTeamWorkerHeartbeat(): void {
@@ -2670,6 +2741,12 @@ export class AgentSession {
 		this.agent.bindRunCancellationDomainBridge(this.#runCancellationDomains, this.#agentSessionClaimKey);
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;
+		this.sessionManager.setSessionMemoryMode(this.settings.get("sessionMemory.mode"));
+		this.#unregisterSessionMemorySettings = this.settings.onChanged(settingPath => {
+			if (settingPath === "sessionMemory.mode") {
+				this.sessionManager.setSessionMemoryMode(this.settings.get("sessionMemory.mode"));
+			}
+		});
 		this.memoryBackend = config.memoryBackend ?? createMemoryBackendService(this.settings);
 		this.#workerIntegrationScheduler = new WorkerIntegrationRequestScheduler(
 			config.workerIntegrationRequest ??
@@ -6256,6 +6333,8 @@ export class AgentSession {
 		// No-op when this session opened no tabs. Failure is logged, not thrown.
 		this.#unregisterResourceGc?.();
 		this.#unregisterResourceGc = undefined;
+		this.#unregisterSessionMemorySettings?.();
+		this.#unregisterSessionMemorySettings = undefined;
 		if (ownerTerminalContextFromEnvironment() === null) this.#unregisterRuntimeStateFinalizer?.();
 		this.#unregisterRuntimeStateFinalizer = undefined;
 		await releaseTabsForOwner(this.sessionManager.getSessionId()).catch((error: unknown) =>
@@ -6320,6 +6399,8 @@ export class AgentSession {
 		const kernelOwnerId = this.#evalKernelOwnerId;
 		this.#unregisterResourceGc?.();
 		this.#unregisterResourceGc = undefined;
+		this.#unregisterSessionMemorySettings?.();
+		this.#unregisterSessionMemorySettings = undefined;
 		this.#unregisterTeamWorkerAsyncJobChange?.();
 		this.#unregisterTeamWorkerAsyncJobChange = undefined;
 		this.#teamWorkerHeartbeat?.dispose();
@@ -7604,8 +7685,7 @@ export class AgentSession {
 			await this.#waitForPostPromptRecovery();
 		} finally {
 			this.#removeEphemeralCustomMessages();
-			this.#endInFlight();
-			await this.#waitForSessionSettlement();
+			await this.#settleEndedInFlight();
 		}
 	}
 
@@ -8799,10 +8879,8 @@ export class AgentSession {
 				this.#overflowMaintenanceAttempts = 0;
 				this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
 			}
-			// Flush any pending bash messages before the new prompt
-			this.#flushPendingBashMessages();
-			this.#flushPendingPythonMessages();
-			this.#flushPendingBackgroundExchanges();
+			// Retry anything whose previous post-turn persistence failed before the new prompt.
+			this.#flushPendingPromptMessages();
 
 			// Reset todo reminder count on new user prompt
 			this.#todoReminderCount = 0;
@@ -8837,160 +8915,206 @@ export class AgentSession {
 				]);
 			}
 
-			// Build messages array (session context, eager todo prelude, then active prompt message)
-			const messages: AgentMessage[] = [];
-			const planReferenceMessage = await this.#buildPlanReferenceMessage?.();
-			if (planReferenceMessage) {
-				messages.push(planReferenceMessage);
-			}
-			const planModeMessage = await this.#buildAutomaticPlanModeMessage();
-			if (planModeMessage) {
-				messages.push(planModeMessage);
-			}
-			const goalModeMessage = this.#buildAutomaticGoalModeMessage();
-			if (goalModeMessage) {
-				messages.push(goalModeMessage);
-			}
-			const volatileProjectContextMessage = await this.#buildVolatileProjectContextMessage();
-			messages.push(volatileProjectContextMessage);
-			const untrustedMcpServerInstructionsMessage = this.#buildUntrustedMcpServerInstructionsMessage();
-			if (untrustedMcpServerInstructionsMessage) messages.push(untrustedMcpServerInstructionsMessage);
-
-			if (rosterClaim && this.#isCurrentIrcRosterClaim(rosterClaim.token, rosterClaim.epoch)) {
-				messages.push(rosterClaim.message);
-			} else if (rosterClaim) {
-				this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
-			}
-			if (options?.prependMessages) {
-				messages.push(...options.prependMessages);
-			}
-
-			messages.push(message);
-
-			// Early bail-out: a generation change or cancellation during setup must
-			// terminate preflight rather than retaining SDK prompt authority.
-			if (this.#isPromptPreflightCancelled(generation, preflightSignal)) {
-				this.#resetInjectedContextSignatures();
-				// A newer abort/prompt cycle superseded this preflight. Callers awaiting
-				// acceptance (onPreflightAccepted) must be told it never ran; direct
-				// callers (e.g. prompt() aborted during a TTSR wait) resolve gracefully.
-				if (options?.onPreflightAccepted || options?.onPreflightAcceptCommit) throw promptPreflightCancelledError();
-				return;
-			}
-
-			// Inject any pending "nextTurn" messages as context alongside the user message
+			// R3.2: one-time Phase A products are captured inside the closure and
+			// executed once after admission acceptance; Phase B reassembles the
+			// attempt messages after every idle wait / compact retry. Pending
+			// next-turn messages are captured WITHOUT draining — the drain moves to
+			// the run-accepted wrapper (R3.3) so AgentBusy/idle/compact-before-
+			// acceptance never consume them.
 			pendingNextTurnMessageCount = this.#pendingNextTurnMessages.length;
 			hasPendingNextTurnMessages = pendingNextTurnMessageCount > 0;
-			for (const msg of this.#pendingNextTurnMessages.slice(0, pendingNextTurnMessageCount)) {
-				messages.push(msg);
-			}
-
-			// Auto-read @filepath mentions
-			const fileMentions = extractFileMentions(expandedText);
-			if (fileMentions.length > 0) {
-				const cwd = this.sessionManager.getCwd();
-				// Collect resolved paths already shown (read or mentioned) in the recent
-				// window so a repeat @mention emits a compact note instead of the full body.
-				const RECENT_MENTION_WINDOW = 40;
-				const recentlyShownPaths = new Set<string>();
-				for (const entry of this.sessionManager.getBranch().slice(-RECENT_MENTION_WINDOW)) {
-					if (entry.type !== "message") continue;
-					const msg = entry.message;
-					if (msg.role === "fileMention") {
-						for (const file of msg.files) {
-							if (!file.duplicate && !file.pruned) recentlyShownPaths.add(resolveReadPath(file.path, cwd));
-						}
-					} else if (msg.role === "toolResult") {
-						const resolved = (msg.details as { resolvedPath?: unknown } | undefined)?.resolvedPath;
-						if (typeof resolved === "string" && resolved) recentlyShownPaths.add(resolveReadPath(resolved, cwd));
-					}
-				}
-				const fileMentionMessages = await generateFileMentionMessages(fileMentions, cwd, {
-					autoResizeImages: this.settings.get("images.autoResize"),
-					useHashLines: resolveFileDisplayMode(this).hashLines,
-					maxInlineBytes: this.settings.get("tools.fileMentionInlineBytes") * 1024,
-					recentlyShownPaths,
-				});
-				messages.push(...fileMentionMessages);
-			}
-
-			const beforeAgentStartSystemPrompt = await this.#buildSystemPromptForAgentStart(expandedText);
-			hindsightRecall = this.getHindsightSessionState()?.getRecallSnippetForInjection();
-			if (hindsightRecall) {
-				// Recall is provider-only context for this request. It must precede the
-				// actual prompt but never become part of durable session history.
-				const promptIndex = messages.lastIndexOf(message);
-				messages.splice(promptIndex, 0, {
-					role: "custom",
-					customType: "hindsight-recall",
-					content: hindsightRecall,
-					display: false,
-					attribution: "agent",
-					timestamp: Date.now(),
-				});
-			}
-
 			const promptAttribution: "user" | "agent" | undefined =
 				"attribution" in message ? message.attribution : undefined;
-
-			// Emit before_agent_start extension event. Race hook completion with prompt
-			// cancellation so a wedged hook cannot retain SDK prompt authority.
-			if (this.#extensionRunner?.hasHandlers("before_agent_start")) this.#markRetryReplayUnsafe();
-
-			if (this.#extensionRunner) {
-				const result = await this.#awaitPromptPreflight(
-					generation,
-					preflightSignal,
-					this.#extensionRunner.emitBeforeAgentStart(expandedText, options?.images, beforeAgentStartSystemPrompt),
-				);
-				if (result?.messages) {
-					this.#appendBeforeAgentStartCustomMessages(messages, result.messages, promptAttribution, message.role);
-				}
-
-				if (result?.systemPrompt !== undefined) {
-					this.agent.setSystemPrompt(result.systemPrompt);
-				} else {
-					this.agent.setSystemPrompt(beforeAgentStartSystemPrompt);
+			let phaseACompleted = false;
+			let fileMentionMessages: AgentMessage[] = [];
+			let beforeAgentStartResultMessages: BeforeAgentStartInternalMessage[] = [];
+			const contributedMessages: BeforeAgentStartInternalMessage[] = [];
+			let recallMarked = false;
+			let planReferenceMessage: CustomMessage | null = null;
+			// Phase B attempt cache. AgentBusy/idle and forced-compaction retries clear
+			// this cache so live plan/goal/volatile/MCP overlays are rebuilt. One-shot
+			// Phase A products (including the plan reference) remain stable.
+			let attemptMessages: AgentMessage[] | undefined;
+
+			const buildPreSubmit = async (): Promise<AgentMessage[] | null> => {
+				this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+				if (options?.onFinalPreflight && !(await options.onFinalPreflight({ hasPendingNextTurnMessages }))) {
+					this.#resetInjectedContextSignatures();
+					return null;
 				}
-			} else {
-				this.agent.setSystemPrompt(beforeAgentStartSystemPrompt);
-			}
-
-			// Invoke first-party internal before-agent-start contributors. These run
-			// alongside the extension runner (not via user-loaded hooks) and append
-			// through the same custom-message attribution path. Errors are nonfatal.
-			if (this.#beforeAgentStartContributors.length > 0) {
-				const contributed: BeforeAgentStartInternalMessage[] = [];
-				for (const contributor of this.#beforeAgentStartContributors) {
-					try {
-						const msg = await this.#awaitPromptPreflight(
+				if (!phaseACompleted) {
+					phaseACompleted = true;
+					// Phase A (one-time side-effectful products; runs once).
+					const fileMentions = extractFileMentions(expandedText);
+					if (fileMentions.length > 0) {
+						const cwd = this.sessionManager.getCwd();
+						// Collect resolved paths already shown (read or mentioned) in the
+						// recent window so a repeat @mention emits a compact note instead
+						// of the full body.
+						const RECENT_MENTION_WINDOW = 40;
+						const recentlyShownPaths = new Set<string>();
+						for (const entry of this.sessionManager.getBranch().slice(-RECENT_MENTION_WINDOW)) {
+							if (entry.type !== "message") continue;
+							const msg = entry.message;
+							if (msg.role === "fileMention") {
+								for (const file of msg.files) {
+									if (!file.duplicate && !file.pruned) recentlyShownPaths.add(resolveReadPath(file.path, cwd));
+								}
+							} else if (msg.role === "toolResult") {
+								const resolved = (msg.details as { resolvedPath?: unknown } | undefined)?.resolvedPath;
+								if (typeof resolved === "string" && resolved)
+									recentlyShownPaths.add(resolveReadPath(resolved, cwd));
+							}
+						}
+						fileMentionMessages = await generateFileMentionMessages(fileMentions, cwd, {
+							autoResizeImages: this.settings.get("images.autoResize"),
+							useHashLines: resolveFileDisplayMode(this).hashLines,
+							maxInlineBytes: this.settings.get("tools.fileMentionInlineBytes") * 1024,
+							recentlyShownPaths,
+						});
+					}
+					const beforeAgentStartSystemPrompt = await this.#buildSystemPromptForAgentStart(expandedText);
+					hindsightRecall = this.getHindsightSessionState()?.getRecallSnippetForInjection();
+					planReferenceMessage = await this.#buildPlanReferenceMessage();
+					// Emit before_agent_start extension event. Race hook completion with
+					// prompt cancellation so a wedged hook cannot retain SDK prompt authority.
+					if (this.#extensionRunner?.hasHandlers("before_agent_start")) this.#markRetryReplayUnsafe();
+					if (this.#extensionRunner) {
+						const result = await this.#awaitPromptPreflight(
 							generation,
 							preflightSignal,
-							contributor({
-								prompt: expandedText,
-								images: options?.images,
-								sessionId: this.sessionId,
-							}),
+							this.#extensionRunner.emitBeforeAgentStart(
+								expandedText,
+								options?.images,
+								beforeAgentStartSystemPrompt,
+							),
 						);
-						if (msg) contributed.push(msg);
-					} catch (err) {
-						if (this.#isPromptPreflightCancelled(generation, preflightSignal))
-							throw promptPreflightCancelledError();
-						logger.debug("before_agent_start contributor failed", { error: String(err) });
+						if (result?.messages) beforeAgentStartResultMessages = [...result.messages];
+						if (result?.systemPrompt !== undefined) {
+							this.agent.setSystemPrompt(result.systemPrompt);
+						} else {
+							this.agent.setSystemPrompt(beforeAgentStartSystemPrompt);
+						}
+					} else {
+						this.agent.setSystemPrompt(beforeAgentStartSystemPrompt);
+					}
+					// Invoke first-party internal before-agent-start contributors. These
+					// run alongside the extension runner (not via user-loaded hooks) and
+					// append through the same custom-message attribution path. Errors are nonfatal.
+					if (this.#beforeAgentStartContributors.length > 0) {
+						for (const contributor of this.#beforeAgentStartContributors) {
+							try {
+								const msg = await this.#awaitPromptPreflight(
+									generation,
+									preflightSignal,
+									contributor({
+										prompt: expandedText,
+										images: options?.images,
+										sessionId: this.sessionId,
+									}),
+								);
+								if (msg) contributedMessages.push(msg);
+							} catch (err) {
+								if (this.#isPromptPreflightCancelled(generation, preflightSignal))
+									throw promptPreflightCancelledError();
+								logger.debug("before_agent_start contributor failed", { error: String(err) });
+							}
+						}
 					}
+					this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
 				}
-				this.#appendBeforeAgentStartCustomMessages(messages, contributed, promptAttribution, message.role);
-			}
 
-			// Abort can race asynchronous preflight work. The injection signatures were
-			// consumed while building context, but no prompt was accepted, so reset them.
-			if (this.#isPromptPreflightCancelled(generation, preflightSignal)) {
-				this.#resetInjectedContextSignatures();
-				// Ack-waiting callers are told the preflight never ran; direct callers
-				// (aborted after setup) resolve gracefully as before f24f46ff5.
-				if (options?.onPreflightAccepted || options?.onPreflightAcceptCommit) throw promptPreflightCancelledError();
-				return;
-			}
+				// Phase B (attempt-dependent; re-runs after every idle wait / compact retry).
+				// R3.2 overflow preflight: materialize the session context synchronously so
+				// an over-budget graph throws SessionContextTooLargeError before any prompt.
+				this.sessionManager.buildSessionContext();
+				if (attemptMessages) {
+					// Idle/AgentBusy retry: reuse the previously assembled attempt
+					// messages; a superseded roster claim releases and the prompt
+					// proceeds without it, matching the pre-seam reuse behavior.
+					if (rosterClaim && !this.#isCurrentIrcRosterClaim(rosterClaim.token, rosterClaim.epoch)) {
+						this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
+					}
+					return attemptMessages;
+				}
+				const messages: AgentMessage[] = [];
+				const currentPlanReferenceMessage = planReferenceMessage;
+				if (currentPlanReferenceMessage) {
+					messages.push(currentPlanReferenceMessage);
+				}
+				const planModeMessage = await this.#buildAutomaticPlanModeMessage();
+				if (planModeMessage) {
+					messages.push(planModeMessage);
+				}
+				const goalModeMessage = this.#buildAutomaticGoalModeMessage();
+				if (goalModeMessage) {
+					messages.push(goalModeMessage);
+				}
+				const volatileProjectContextMessage = await this.#buildVolatileProjectContextMessage();
+				messages.push(volatileProjectContextMessage);
+				const untrustedMcpServerInstructionsMessage = this.#buildUntrustedMcpServerInstructionsMessage();
+				if (untrustedMcpServerInstructionsMessage) messages.push(untrustedMcpServerInstructionsMessage);
+
+				// Roster: one Phase A claim, revalidated and reused on every attempt;
+				// a superseded claim releases and the prompt proceeds without it.
+				if (rosterClaim && this.#isCurrentIrcRosterClaim(rosterClaim.token, rosterClaim.epoch)) {
+					messages.push(rosterClaim.message);
+				} else if (rosterClaim) {
+					this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
+				}
+				if (options?.prependMessages) {
+					messages.push(...options.prependMessages);
+				}
+
+				const promptIndex = messages.length;
+				messages.push(message);
+
+				// Re-present captured pending next-turn messages (never drained here).
+				for (const msg of this.#pendingNextTurnMessages.slice(0, pendingNextTurnMessageCount)) {
+					messages.push(msg);
+				}
+				messages.push(...fileMentionMessages);
+				if (hindsightRecall) {
+					// Recall is provider-only context for this request. It must precede
+					// the actual prompt but never become part of durable session history.
+					messages.splice(promptIndex, 0, {
+						role: "custom",
+						customType: "hindsight-recall",
+						content: hindsightRecall,
+						display: false,
+						attribution: "agent",
+						timestamp: Date.now(),
+					});
+				}
+				if (beforeAgentStartResultMessages.length > 0) {
+					this.#appendBeforeAgentStartCustomMessages(
+						messages,
+						beforeAgentStartResultMessages,
+						promptAttribution,
+						message.role,
+					);
+				}
+				if (contributedMessages.length > 0) {
+					this.#appendBeforeAgentStartCustomMessages(
+						messages,
+						contributedMessages,
+						promptAttribution,
+						message.role,
+					);
+				}
+				if (options?.onFinalPreflight && !(await options.onFinalPreflight({ hasPendingNextTurnMessages }))) {
+					this.#resetInjectedContextSignatures();
+					return null;
+				}
+				attemptMessages = messages;
+				return messages;
+			};
+			const preSubmit: PreSubmitBuilder = {
+				build: buildPreSubmit,
+				reset: () => {
+					attemptMessages = undefined;
+				},
+			};
 
 			const agentPromptOptions = {
 				...(options?.toolChoice ? { toolChoice: options.toolChoice } : undefined),
@@ -8999,21 +9123,27 @@ export class AgentSession {
 					this.#acceptRunHandle(handle);
 					options?.onRunAccepted?.(handle);
 					options?.admissionLease?.release();
-					if (hindsightRecall) this.getHindsightSessionState()?.markRecallSnippetInjected(hindsightRecall);
+					// R3.3: the accepted-run wrapper is the exact acceptance boundary —
+					// pending next-turn drain and the exactly-once recall mark live here.
+					if (hindsightRecall && !recallMarked) {
+						recallMarked = true;
+						this.getHindsightSessionState()?.markRecallSnippetInjected(hindsightRecall);
+					}
+					if (pendingNextTurnMessageCount > 0) {
+						this.#pendingNextTurnMessages.splice(0, pendingNextTurnMessageCount);
+					}
+					if (this.#cancelAndSubmitInProgress) this.#cancelAndSubmitPendingNextTurnDrained = true;
 				},
 			};
-			if (options?.onPreflightAcceptCommit) await options.onPreflightAcceptCommit();
-			else options?.onPreflightAccepted?.();
-			if (options?.onFinalPreflight && !(await options.onFinalPreflight({ hasPendingNextTurnMessages }))) {
-				this.#resetInjectedContextSignatures();
-				return;
-			}
-			this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
-			if (pendingNextTurnMessageCount > 0) {
-				this.#pendingNextTurnMessages.splice(0, pendingNextTurnMessageCount);
-			}
-			if (this.#cancelAndSubmitInProgress) this.#cancelAndSubmitPendingNextTurnDrained = true;
-			await this.#promptAgentWithIdleRetry(messages, agentPromptOptions, predecessorAgentEndHold);
+			await this.#promptAgentWithIdleRetry(preSubmit, agentPromptOptions, predecessorAgentEndHold, {
+				signal: preflightSignal,
+				resourceRunId: this.#runResourceLeaseContext.getStore()?.resourceRunId,
+				onPreflightAccepted: () => {
+					this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+					if (options?.onPreflightAcceptCommit) return options.onPreflightAcceptCommit();
+					options?.onPreflightAccepted?.();
+				},
+			});
 			const terminalAssistant = this.#findLastAssistantMessage();
 			if (
 				rosterClaim &&
@@ -9048,14 +9178,7 @@ export class AgentSession {
 				this.#releaseIrcRosterClaim(rosterClaim.token, rosterClaim.epoch);
 			}
 			this.#releaseDeferredAgentEndContinuation(predecessorAgentEndHold);
-			this.#endInFlight();
-			if (options?.skipPostPromptRecoveryWait) {
-				await this.#agentEndPublicationPromise;
-			} else {
-				await this.#agentEndHandlingPromise;
-				await this.#waitForPostPromptRecovery();
-				await this.#agentEndPublicationPromise;
-			}
+			await this.#settleEndedInFlight(options?.skipPostPromptRecoveryWait ? "publication" : "full");
 		}
 	}
 
@@ -10712,19 +10835,56 @@ export class AgentSession {
 			// Flush current session to ensure all entries are written
 			await this.sessionManager.flush();
 
-			// Prepare the copied successor and complete local:// readiness while all
-			// public manager getters remain bound to the predecessor.
-			const prepared = await this.sessionManager.prepareFork();
-			if (!prepared) {
-				return false;
-			}
-			try {
-				await initializeLocalRoot(this.#localProtocolOptions(prepared));
-				await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
-				this.sessionManager.commitPreparedNewSession(prepared);
+			const boundedColdForkEligible =
+				this.sessionManager.getSessionMemoryStats().coldRetirementActive &&
+				!this.sessionManager.isManagedDestination() &&
+				previousSessionFile !== undefined;
+			if (boundedColdForkEligible) {
+				const previousManager = this.sessionManager;
+				const forkedManager = await SessionManager.forkFrom(
+					previousSessionFile,
+					previousManager.getCwd(),
+					SessionManager.explicitDestination(previousManager.getSessionDir()),
+					undefined,
+					"copy-retain",
+					this.settings.get("sessionMemory.mode"),
+				);
+				try {
+					await initializeLocalRoot({
+						getArtifactsDir: () => forkedManager.getArtifactsDir(),
+						isManagedDestination: () => false,
+						getManagedLegacyLocalMigrationSource: () => null,
+						getSessionId: () => forkedManager.getSessionId(),
+					});
+					await this.#settleOwnAsyncJobsBeforeArtifactRetirement();
+				} catch (error) {
+					const forkedFile = forkedManager.getSessionFile();
+					await forkedManager.close();
+					if (forkedFile) await previousManager.discardUncommittedSession(forkedFile);
+					throw error;
+				}
+				this.sessionManager = forkedManager;
+				try {
+					await previousManager.close();
+				} catch (error) {
+					logger.warn("Previous session close failed after bounded fork adoption", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
 				await this.#runToolSessionTransitionCleanups();
-			} catch (error) {
-				throw await discardPreparedNewSessionAfterFailure(this.sessionManager, prepared, error);
+			} else {
+				// Prepare the copied successor and complete local:// readiness while all
+				// public manager getters remain bound to the predecessor.
+				const prepared = await this.sessionManager.prepareFork();
+				if (!prepared) return false;
+				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.#syncAgentSessionId();
 			this.#bindWorkflowGateEmitter(previousWorkflowGateSessionId);
@@ -13363,13 +13523,15 @@ export class AgentSession {
 				}
 			}
 		}
+		const sessionMemory = this.sessionManager.getSessionMemoryStats();
 		return {
 			heapUsedBytes: process.memoryUsage().heapUsed,
 			providerBytes,
 			messageCount: this.state.messages.length,
 			imageBytes,
 			sessionResidentImageBytes: this.sessionManager.getResidentImageBytes(),
-			materializedResidentBytes: this.#streamingEditFileCache.totalBytes,
+			materializedResidentBytes:
+				this.#streamingEditFileCache.totalBytes + sessionMemory.hotRegionBytes + sessionMemory.metaDescriptorBytes,
 			tuiChatChildren: retainedMemory.tuiChatChildren ?? 0,
 			tuiCachedRenderBytes: retainedMemory.tuiCachedRenderBytes ?? 0,
 		};
@@ -13777,11 +13939,6 @@ export class AgentSession {
 			`(Reminder ${this.#todoReminderCount}/${remindersMax})\n` +
 			`</system-reminder>`;
 
-		logger.debug("Todo completion: sending reminder", {
-			incomplete: incomplete.length,
-			attempt: this.#todoReminderCount,
-		});
-
 		// Emit event for UI to render notification
 		await this.#emitSessionEvent({
 			type: "todo_reminder",
@@ -13790,7 +13947,27 @@ export class AgentSession {
 			maxAttempts: remindersMax,
 		});
 
-		// Inject reminder and continue the conversation
+		// Consumers that cannot represent a server-initiated turn (ACP v1 clients, SDK
+		// hosts) keep reporting the prompt as running until the terminal `agent_end` is
+		// published. Injecting here would park that terminal behind a continuation hold
+		// (`#scheduleAgentContinue` -> `#reserveDeferredAgentEndForContinuation`), so a
+		// turn that already delivered its final answer would never settle — and there is
+		// no interactive consumer to act on the nudge. Those hosts get the advisory
+		// event above and nothing else.
+		if (this.#clientBridge?.deferAgentInitiatedTurns && !this.#allowAcpAgentInitiatedTurns) {
+			logger.debug("Todo completion: advisory reminder only", {
+				incomplete: incomplete.length,
+				attempt: this.#todoReminderCount,
+			});
+			return;
+		}
+
+		logger.debug("Todo completion: sending reminder", {
+			incomplete: incomplete.length,
+			attempt: this.#todoReminderCount,
+		});
+
+		// Inject reminder and continue conversation
 		this.agent.appendMessage({
 			role: "developer",
 			content: [{ type: "text", text: reminder }],
@@ -15077,6 +15254,9 @@ export class AgentSession {
 			)
 		);
 	}
+	#isIdleStreamStallErrorMessage(errorMessage: string): boolean {
+		return /stream stalled while waiting for the next event/i.test(errorMessage);
+	}
 
 	#isFirstEventTimeoutErrorMessage(errorMessage: string): boolean {
 		// First-event timeout: the stream watchdog aborted because no event
@@ -15133,8 +15313,8 @@ export class AgentSession {
 	/**
 	 * Ordered retry classification: typed safety stop (surface) -> legacy safety stop
 	 * (surface) -> overflow (compaction) -> terminal (surface) -> usage_limit
-	 * (rotation) -> first_event_timeout (bounded retry) -> transient (unbounded retry) ->
-	 * unknown (bounded retry).
+	 * (rotation) -> first_event_timeout (bounded retry) -> transient (unbounded retry,
+	 * except canonical idle-stream stalls bounded downstream) -> unknown (bounded retry).
 	 */
 	#classifyErrorForRetry(message: AssistantMessage): RetryErrorClassification {
 		if (message.stopReason !== "error") return "none";
@@ -15692,7 +15872,10 @@ export class AgentSession {
 				return false;
 			}
 		}
-		const legacyUnbounded = !managedFallback && classification === "transient";
+		const legacyUnbounded =
+			!managedFallback &&
+			classification === "transient" &&
+			!this.#isIdleStreamStallErrorMessage(message.errorMessage ?? "");
 		const attemptsUsed = managedFallback ? controller.attemptsUsed || 1 : this.#retryAttempt + 1;
 		const failedSelector = managedFallback ? controller.currentSelector() : undefined;
 		let outcome = managedFallback
@@ -15958,16 +16141,25 @@ export class AgentSession {
 	}
 
 	async #promptAgentWithIdleRetry(
-		messages: AgentMessage[],
+		preSubmit: PreSubmitBuilder,
 		options?: {
 			toolChoice?: ToolChoice;
 			fallbackManaged?: boolean;
 			onRunAccepted?: (handle: AttemptRunHandle) => void;
 		},
 		predecessorAgentEndHold?: symbol,
+		seam?: {
+			signal?: AbortSignal;
+			resourceRunId?: string;
+			onPreflightAccepted?: () => void | Promise<void>;
+		},
 	): Promise<void> {
 		const deadline = Date.now() + 30_000;
 		let continuationHold = predecessorAgentEndHold;
+		// R3.2 helper-local compact-once flag: fresh per prompt; the inline retry
+		// re-runs Phase B via preSubmit after the forced compaction.
+		let overflowRetried = false;
+		let preflightAccepted = false;
 		for (;;) {
 			try {
 				const predecessorAgentEnd = this.#claimDeferredAgentEndForContinuation(
@@ -15975,11 +16167,50 @@ export class AgentSession {
 				);
 				continuationHold = undefined;
 				try {
+					const messages = await preSubmit.build();
+					if (messages === null) {
+						this.#restoreDeferredAgentEndAfterContinuationFailure(predecessorAgentEnd);
+						return;
+					}
+					if (!preflightAccepted) {
+						await seam?.onPreflightAccepted?.();
+						preflightAccepted = true;
+					}
 					await this.agent.prompt(messages, options);
 					this.#releaseDeferredAgentEndLease(predecessorAgentEnd);
 					return;
 				} catch (error) {
 					this.#restoreDeferredAgentEndAfterContinuationFailure(predecessorAgentEnd);
+					if (
+						error instanceof SessionContextTooLargeError &&
+						!overflowRetried &&
+						this.settings.get("sessionMemory.contextOverflowRecovery")
+					) {
+						// D7: exactly one forced, no-continuation compaction
+						// (`willRetry:false`, `continueAfterMaintenance:false`), then
+						// exactly one inline retry. Any other terminal status rethrows
+						// the ORIGINAL typed error with measurements.
+						overflowRetried = true;
+						let compacted = false;
+						try {
+							const status = await this.#runAutoCompaction("overflow", false, false, {
+								force: true,
+								continueAfterMaintenance: false,
+								signal: seam?.signal,
+								resourceRunId: seam?.resourceRunId,
+							});
+							compacted = status.kind === "compacted";
+						} catch {
+							compacted = false;
+						}
+						if (compacted) {
+							// Post-compaction Phase B must rebuild overlays (the
+							// injected-context signatures were reset by
+							// #applyCompactionPostAppend), so drop the cached attempt.
+							preSubmit.reset();
+							continue;
+						}
+					}
 					throw error;
 				}
 			} catch (err) {
@@ -15990,6 +16221,7 @@ export class AgentSession {
 					throw new Error("Timed out waiting for prior agent run to finish before prompting.");
 				}
 				await this.agent.waitForIdle();
+				preSubmit.reset();
 			}
 		}
 	}
@@ -16086,11 +16318,13 @@ export class AgentSession {
 	 * @param command The bash command to execute
 	 * @param onChunk Optional streaming callback for output
 	 * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+	 * @param options.onPersisted Called once the execution's message is in session state
+	 *   (immediately when idle, at the post-turn flush while streaming)
 	 */
 	async executeBash(
 		command: string,
 		onChunk?: (chunk: string) => void,
-		options?: { excludeFromContext?: boolean },
+		options?: { excludeFromContext?: boolean; onPersisted?: () => void },
 	): Promise<BashResult> {
 		const excludeFromContext = options?.excludeFromContext === true;
 		this.#markRetryReplayUnsafe();
@@ -16145,7 +16379,11 @@ export class AgentSession {
 	 * Record a bash execution result in session history.
 	 * Used by executeBash and by extensions that handle bash execution themselves.
 	 */
-	recordBashResult(command: string, result: BashResult, options?: { excludeFromContext?: boolean }): void {
+	recordBashResult(
+		command: string,
+		result: BashResult,
+		options?: { excludeFromContext?: boolean; onPersisted?: () => void },
+	): void {
 		const meta = outputMeta().truncationFromSummary(result, { direction: "tail" }).get();
 		const bashMessage: BashExecutionMessage = {
 			role: "bashExecution",
@@ -16162,13 +16400,18 @@ export class AgentSession {
 		// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
 		if (this.isStreaming) {
 			// Queue for later - will be flushed on agent_end
-			this.#pendingBashMessages.push(bashMessage);
+			this.#pendingBashMessages.push({
+				message: bashMessage,
+				onPersisted: options?.onPersisted,
+				appendedToAgent: false,
+			});
 		} else {
 			// Add to agent state immediately
 			this.agent.appendMessage(bashMessage);
 
 			// Save to session
 			this.sessionManager.appendMessage(bashMessage);
+			options?.onPersisted?.();
 		}
 	}
 
@@ -16196,17 +16439,7 @@ export class AgentSession {
 	 * Called after agent turn completes to maintain proper message ordering.
 	 */
 	#flushPendingBashMessages(): void {
-		if (this.#pendingBashMessages.length === 0) return;
-
-		for (const bashMessage of this.#pendingBashMessages) {
-			// Add to agent state
-			this.agent.appendMessage(bashMessage);
-
-			// Save to session
-			this.sessionManager.appendMessage(bashMessage);
-		}
-
-		this.#pendingBashMessages = [];
+		this.#flushPendingExecutionMessages(this.#pendingBashMessages, "bash");
 	}
 
 	// =========================================================================
@@ -16219,11 +16452,13 @@ export class AgentSession {
 	 * @param code The Python code to execute
 	 * @param onChunk Optional streaming callback for output
 	 * @param options.excludeFromContext If true, execution won't be sent to LLM ($$ prefix)
+	 * @param options.onPersisted Called once the execution's message is in session state
+	 *   (immediately when idle, at the post-turn flush while streaming)
 	 */
 	async executePython(
 		code: string,
 		onChunk?: (chunk: string) => void,
-		options?: { excludeFromContext?: boolean },
+		options?: { excludeFromContext?: boolean; onPersisted?: () => void },
 	): Promise<PythonResult> {
 		const excludeFromContext = options?.excludeFromContext === true;
 		this.#markRetryReplayUnsafe();
@@ -16291,7 +16526,11 @@ export class AgentSession {
 	/**
 	 * Record a Python execution result in session history.
 	 */
-	recordPythonResult(code: string, result: PythonResult, options?: { excludeFromContext?: boolean }): void {
+	recordPythonResult(
+		code: string,
+		result: PythonResult,
+		options?: { excludeFromContext?: boolean; onPersisted?: () => void },
+	): void {
 		const meta = outputMeta().truncationFromSummary(result, { direction: "tail" }).get();
 		const pythonMessage: PythonExecutionMessage = {
 			role: "pythonExecution",
@@ -16307,10 +16546,15 @@ export class AgentSession {
 
 		// If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
 		if (this.isStreaming) {
-			this.#pendingPythonMessages.push(pythonMessage);
+			this.#pendingPythonMessages.push({
+				message: pythonMessage,
+				onPersisted: options?.onPersisted,
+				appendedToAgent: false,
+			});
 		} else {
 			this.agent.appendMessage(pythonMessage);
 			this.sessionManager.appendMessage(pythonMessage);
+			options?.onPersisted?.();
 		}
 	}
 
@@ -16369,14 +16613,84 @@ export class AgentSession {
 	 * Flush pending Python messages to agent state and session.
 	 */
 	#flushPendingPythonMessages(): void {
-		if (this.#pendingPythonMessages.length === 0) return;
+		this.#flushPendingExecutionMessages(this.#pendingPythonMessages, "python");
+	}
 
-		for (const pythonMessage of this.#pendingPythonMessages) {
-			this.agent.appendMessage(pythonMessage);
-			this.sessionManager.appendMessage(pythonMessage);
+	#flushPendingExecutionMessages<T extends BashExecutionMessage | PythonExecutionMessage>(
+		pendingMessages: Array<{ message: T; onPersisted?: () => void; appendedToAgent: boolean }>,
+		kind: "bash" | "python",
+	): void {
+		if (pendingMessages.length === 0) return;
+
+		const total = pendingMessages.length;
+		const remaining: typeof pendingMessages = [];
+		const errors: unknown[] = [];
+		const persisted: string[] = [];
+		let callbackFailureCount = 0;
+		let persistenceBlocked = false;
+		let agentAppendBlocked = false;
+		for (const pending of pendingMessages) {
+			if (!pending.appendedToAgent) {
+				if (agentAppendBlocked) {
+					remaining.push(pending);
+					continue;
+				}
+				try {
+					this.agent.appendMessage(pending.message);
+					pending.appendedToAgent = true;
+				} catch (error) {
+					agentAppendBlocked = true;
+					persistenceBlocked = true;
+					remaining.push(pending);
+					errors.push(error);
+					continue;
+				}
+			}
+
+			if (persistenceBlocked) {
+				remaining.push(pending);
+				continue;
+			}
+
+			try {
+				this.sessionManager.appendMessage(pending.message);
+			} catch (error) {
+				// Session entries form a leaf-linked transcript. Once one append fails,
+				// later entries must remain queued behind it or a retry would append the
+				// failed entry after messages that originally followed it.
+				persistenceBlocked = true;
+				remaining.push(pending);
+				errors.push(error);
+				continue;
+			}
+
+			persisted.push("command" in pending.message ? pending.message.command : pending.message.code);
+			try {
+				pending.onPersisted?.();
+			} catch (error) {
+				callbackFailureCount++;
+				errors.push(error);
+			}
 		}
 
-		this.#pendingPythonMessages = [];
+		pendingMessages.splice(0, pendingMessages.length, ...remaining);
+		if (errors.length === 0) return;
+
+		const persistedCount = total - remaining.length;
+		const persistenceFailureCount = remaining.length;
+		const persistenceSummary =
+			persistenceFailureCount > 0
+				? `Failed to persist ${persistenceFailureCount} of ${total} deferred ${kind} execution message${total === 1 ? "" : "s"}; ${persistedCount} persisted, failed messages remain pending for retry`
+				: `Persisted all ${total} deferred ${kind} execution message${total === 1 ? "" : "s"}`;
+		const callbackSummary =
+			callbackFailureCount > 0
+				? `; ${callbackFailureCount} onPersisted callback${callbackFailureCount === 1 ? "" : "s"} failed`
+				: "";
+		const pending = remaining.map(item => ("command" in item.message ? item.message.command : item.message.code));
+		throw new AggregateError(
+			errors,
+			`${persistenceSummary}${callbackSummary}; persisted: ${JSON.stringify(persisted)}; pending: ${JSON.stringify(pending)}`,
+		);
 	}
 
 	// =========================================================================
@@ -17816,6 +18130,7 @@ export class AgentSession {
 			cost: totalCost,
 			...(hasCompleteCostBreakdown ? { costBreakdown: totalCostBreakdown } : {}),
 			premiumRequests: totalPremiumRequests,
+			sessionMemory: this.sessionManager.getSessionMemoryStats(),
 		};
 	}