@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/interactive/chat-loop.ts

@@ -29,7 +29,13 @@ import { appendOutOfTurnUsageRow, type OutOfTurnUsageRow } from "../domains/obse
 import type { PromptsContract } from "../domains/prompts/contract.js";
 import { toContextOverflowError } from "../domains/providers/errors.js";
 import type { ProvidersContract } from "../domains/providers/index.js";
-import { normalizeCostProvenance, runtimeTargetSnapshot, targetRequiresAuth } from "../domains/providers/index.js";
+import {
+	canonicalEndpointKey,
+	normalizeCostProvenance,
+	registerForegroundStream,
+	runtimeTargetSnapshot,
+	targetRequiresAuth,
+} from "../domains/providers/index.js";
 import type { ProtectedArtifactState } from "../domains/safety/protected-artifacts.js";
 import type { CompactResult } from "../domains/session/compaction/compact.js";
 import type { ContextSnapshot, ContextUsageSnapshot } from "../domains/session/context-accounting.js";
@@ -42,7 +48,7 @@ import { isRetryableErrorMessage, type RetrySettings } from "../domains/session/
 import { createEngineAgent } from "../engine/agent.js";
 import { resolveReservedOutputTokens } from "../engine/apis/output-budget.js";
 import { cwdHash } from "../engine/session.js";
-import type { AgentEvent, AgentMessage, ImageContent } from "../engine/types.js";
+import type { AgentEvent, AgentMessage, ImageContent, Usage } from "../engine/types.js";
 import { resolveSessionTools } from "../tools/agent-tools.js";
 import { finalizeAskUserInterviewForHost } from "../tools/ask-user.js";
 import type { AskUserToolPolicy, ToolInvokeOptions, ToolRegistry } from "../tools/registry.js";
@@ -57,13 +63,15 @@ import {
 	toolSignatureFromState,
 } from "./chat-loop-messages.js";
 import { normalizeRetrySettings } from "./chat-loop-policy.js";
-import { runHandoffRound } from "./handoff-round.js";
+import { type HandoffRepairInput, runHandoffRound } from "./handoff-round.js";
 import type { ApprovalRequestView } from "./permission-overlay.js";
-import { runSideQuestion, type SideQuestionResult } from "./side-question.js";
+import type { runPrewarmRound } from "./prewarm.js";
+import { runSideQuestion, type SideQuestionResult, sideQuestionUsage } from "./side-question.js";
 import type { AgentStatusEvent } from "./status/types.js";
 import { createTurnContext } from "./turn-context.js";
 import { createTurnMiddleware } from "./turn-middleware.js";
 import { createTurnPersistence } from "./turn-persistence.js";
+import { createTurnPrewarm, type PrewarmOutcome, subscribePrewarmToCompaction } from "./turn-prewarm.js";
 import {
 	createTurnQueues,
 	DEFAULT_STEERING_MODE,
@@ -78,13 +86,18 @@ import {
 	rewriteStallAbortMessage,
 } from "./turn-recovery.js";
 import { type AssistantDeltaEvent, createTurnRuntime, TurnAdmissionError } from "./turn-runtime.js";
-import { type AgentRuntime, type ChatLoopRunSnapshot, createTurnState } from "./turn-state.js";
+import {
+	type AgentRuntime,
+	type ChatLoopRunSnapshot,
+	createTurnState,
+	type TurnPreparationPhase,
+} from "./turn-state.js";
 import { isWorkerShareNote } from "./worker-share.js";
 
 export type { QueuedChatMessage, QueuedMessageKind, QueuedMessagesSnapshot, SteeringMode } from "./turn-queues.js";
 export type { RetryStatusEvent, RetryStatusPayload, RetryStatusPhase } from "./turn-recovery.js";
 export type { AssistantDeltaEvent } from "./turn-runtime.js";
-export type { ChatLoopRunSnapshot } from "./turn-state.js";
+export type { ChatLoopRunSnapshot, TurnPreparationPhase } from "./turn-state.js";
 
 export interface QueueUpdateEvent {
 	type: "queue_update";
@@ -182,6 +195,13 @@ export interface ChatSubmitOptions {
 	 * for the two states in which it degrades to `next-slot` instead.
 	 */
 	steering?: SteeringMode;
+	/**
+	 * Commits the presentation of a consumed prompt after preparation opens and
+	 * before admission work can make the turn durable. Interactive uses this to
+	 * guarantee that even a fast probe or prompt compile paints one pending
+	 * frame instead of opening and closing entirely between renderer ticks.
+	 */
+	onPreparationVisible?: () => Promise<void>;
 	/**
 	 * Fires once this submit owns the live turn (`isStreaming()` is true) and
 	 * the next queued submit may use streaming queue routing. Stage 0 replay
@@ -232,6 +252,15 @@ export interface SideQuestionOptions {
 	onDelta?: (partialText: string) => void;
 }
 
+export interface HandoffRoundOptions extends SideQuestionOptions {
+	/**
+	 * Run the second and last extraction round, quoting the parser's complaint
+	 * and what the first round returned. Both rounds bill through the same
+	 * out-of-turn usage store (issue #223).
+	 */
+	repair?: HandoffRepairInput;
+}
+
 /**
  * How a `/btw` round ended. `refused` is a round that never started (a turn was
  * in flight, or no orchestrator target is configured); `failed` is a round that
@@ -263,6 +292,15 @@ export interface ChatLoop {
 	getSessionId(): string | null;
 	lastRunSnapshot?(): ChatLoopRunSnapshot | null;
 	isStreaming(): boolean;
+	/**
+	 * Where a consumed prompt currently is between the editor and the stream.
+	 * The composer and the footer read it so the window in which the prompt has
+	 * been taken but the turn has not been admitted is never rendered as idle
+	 * (issue #251).
+	 */
+	turnPreparation(): { phase: TurnPreparationPhase; since: number };
+	/** Fires on every preparation transition, including back to `idle`. */
+	onTurnPreparation(handler: (phase: TurnPreparationPhase) => void): () => void;
 	contextUsage(): ContextUsageSnapshot;
 	/**
 	 * Categorized context-window ledger for the `/context` overlay: where every
@@ -302,7 +340,7 @@ export interface ChatLoop {
 	 * caller; this method only owns the provider call. Refused outright while a
 	 * turn is in flight rather than queued.
 	 */
-	extractHandoff(goal: string, options?: SideQuestionOptions): Promise<SideQuestionOutcome>;
+	extractHandoff(goal: string, options?: HandoffRoundOptions): Promise<SideQuestionOutcome>;
 	/**
 	 * Drop or replace the chat-loop's in-memory state after a session switch
 	 * (/resume, /fork, /new). `leafTurnId` is the id the next user turn
@@ -310,6 +348,12 @@ export interface ChatLoop {
 	 * from the selected session entries; omit it for a fresh session.
 	 */
 	resetForSession(leafTurnId: string | null, replayMessages?: ReadonlyArray<AgentMessage>): void;
+	/**
+	 * Resolves once the queued or in-flight session pre-warm has settled, with
+	 * the outcome, or null when none ran. Diagnostics and contracts only: no
+	 * turn path waits on a pre-warm.
+	 */
+	whenPrewarmSettled(): Promise<PrewarmOutcome | null>;
 	/** Abort the live agent and release pi-ai session-scoped resources before shutdown. */
 	dispose(): void;
 	/**
@@ -453,6 +497,34 @@ export interface CreateChatLoopDeps {
 	 * background registry, which holds exactly the attached calls.
 	 */
 	hasAttachedDispatch?: () => boolean;
+	/**
+	 * True while any dispatched worker run is outstanding, attached or detached.
+	 * The session pre-warm stands down in that state so it never competes for the
+	 * endpoint a worker is already using. Defaults to `hasAttachedDispatch`, which
+	 * is the narrower fact a bare composition has.
+	 */
+	hasActiveDispatch?: () => boolean;
+	/**
+	 * True on a surface where a person is about to type the next turn. The
+	 * orchestrator wires this false for headless `run`: the pre-warm buys latency
+	 * that an unattended run never spends. Defaults to true.
+	 */
+	isLatencySurface?: () => boolean;
+	/** The session pre-warm round. Injectable for the same reason `runSideQuestion` is. */
+	runPrewarm?: typeof runPrewarmRound;
+	/**
+	 * Whether a submit aborts the in-flight pre-warm's request or only lets go of
+	 * it. Defaults to what the measured local backend does with a cancelled
+	 * request; see `ABORT_ROUND_ON_SUBMIT` in `turn-prewarm.ts`.
+	 */
+	abortPrewarmOnSubmit?: boolean;
+	/**
+	 * Claim one in-flight request on the pre-warm's endpoint for the duration of
+	 * the round. Wired from the endpoint-capacity registry once #250 lands, so a
+	 * pre-warm counts against the same per-endpoint bound the orchestrator's
+	 * streaming turn does; see `registerEndpointSlot` in `turn-prewarm.ts`.
+	 */
+	registerPrewarmEndpointSlot?: (runtime: AgentRuntime) => (() => void) | null;
 }
 
 export function reloadProtectedArtifactsForSession(
@@ -478,6 +550,56 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	const state = createTurnState(deps.getSettings().orchestrator.thinkingLevel ?? "off");
 	const toolStartTimes = new Map<string, number>();
 
+	const preparationListeners = new Set<(phase: TurnPreparationPhase) => void>();
+	/**
+	 * Move the consumed prompt to a new preparation phase and tell everything
+	 * that renders it. Idempotent, so the two compaction sites and the two
+	 * clearing sites (admission and settlement, because a refusal never reaches
+	 * admission) can all set the phase they mean without ordering rules.
+	 */
+	const setTurnPreparation = (phase: TurnPreparationPhase): void => {
+		if (state.turnPreparation === phase) return;
+		// `since` is the age of the whole window, not of its current sub-state:
+		// what the operator is judging is how long ago they pressed Enter.
+		if (state.turnPreparation === "idle") state.turnPreparationSince = Date.now();
+		if (phase === "idle") state.turnPreparationSince = 0;
+		state.turnPreparation = phase;
+		for (const listener of preparationListeners) {
+			try {
+				listener(phase);
+			} catch {
+				// Preparation observers are presentation only and cannot fail a turn.
+			}
+		}
+	};
+
+	/**
+	 * Submits currently holding a consumed prompt. The FIFO gate lets a second
+	 * submit open its window while the first is still settling, so the phase is
+	 * refcounted rather than owned: the last one out turns the light off.
+	 */
+	let preparingSubmits = 0;
+	const enterPreparation = (): void => {
+		preparingSubmits += 1;
+		// Opening a window never narrows one that is already open: a second submit
+		// arriving while the first is compacting must not flip the composer from
+		// COMPACTING back to PREPARING while the compaction is still running.
+		if (state.turnPreparation === "idle") setTurnPreparation("preparing");
+	};
+	const leavePreparation = (): void => {
+		preparingSubmits = Math.max(0, preparingSubmits - 1);
+		if (preparingSubmits === 0) setTurnPreparation("idle");
+	};
+	/**
+	 * Return to the plain preparing state after a compaction inside the window.
+	 * Refcount-aware, because two submits share the window and the slower one's
+	 * compaction can finish after the window has already closed; restoring
+	 * `preparing` there would re-open it with nothing left to prepare.
+	 */
+	const endPreparationCompaction = (): void => {
+		setTurnPreparation(preparingSubmits > 0 ? "preparing" : "idle");
+	};
+
 	const emit = (event: ChatLoopEvent): void => {
 		for (const listener of listeners) {
 			listener(event);
@@ -589,7 +711,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		middlewareToolChoice,
 		consumePersistedEcho: (text) => queues.consumePersistedEcho(text),
 		removeQueuedMirrorEntry: (text) => queues.removeQueuedMirrorEntry(text),
-		promptCachePayloadForAssistant: (usage) => context.promptCachePayloadForAssistant(usage),
+		promptCachePayloadForAssistant: (usage, backend) => context.promptCachePayloadForAssistant(usage, backend),
 		promptSideTokens: () => context.promptSideTokens(),
 		observability: deps.observability,
 	});
@@ -702,6 +824,23 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		}
 	};
 
+	/**
+	 * Run one out-of-turn round while holding a slot on the endpoint it streams
+	 * to, exactly as the turn and the pre-warm do. A `/btw` or `/handoff` round
+	 * is a full request against the same inference scheduler, so endpoint
+	 * capacity (#250) has to count it for as long as it is out, and the
+	 * background-memory tier has to read that endpoint as busy (#229).
+	 */
+	const withEndpointSlot = async <T>(runtime: AgentRuntime, round: () => Promise<T>): Promise<T> => {
+		const endpointKey = canonicalEndpointKey(runtime.runtimeResolution.target);
+		const release = endpointKey === null ? () => {} : registerForegroundStream(endpointKey);
+		try {
+			return await round();
+		} finally {
+			release();
+		}
+	};
+
 	const writeOutOfTurnUsageRow =
 		deps.recordOutOfTurnUsageRow ?? ((row: OutOfTurnUsageRow): void => appendOutOfTurnUsageRow(clioStateDir(), row));
 
@@ -764,6 +903,50 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 		});
 	};
 
+	// A submit owns the turn state machine from the moment it starts running,
+	// which is well before `state.streaming` flips: the probe, auto-compaction,
+	// and the prompt compile all happen first. The pre-warm reads this flag, not
+	// `streaming`, so it can never be the request the operator's turn queues
+	// behind.
+	let turnActive = false;
+
+	const prewarm = createTurnPrewarm({
+		state,
+		getSettings: deps.getSettings,
+		providers: deps.providers,
+		context,
+		bus: deps.bus,
+		...(deps.session ? { session: deps.session } : {}),
+		isLatencySurface: () => deps.isLatencySurface?.() !== false,
+		isTurnActive: () => turnActive,
+		hasActiveDispatch: () => (deps.hasActiveDispatch ?? deps.hasAttachedDispatch)?.() === true,
+		prepareRuntime: async (signal) => {
+			// The same probe a submit awaits, so the pre-warm resolves the model the
+			// next turn will resolve rather than a stale catalog entry.
+			await turnRuntime.ensureLiveCapabilitiesForSelectedModel().catch(() => {});
+			return prepareOutOfTurnRound("a turn is in flight", signal);
+		},
+		applySessionTools: (runtime) => {
+			runtime.agent.state.tools = resolveSessionTools(
+				runtime,
+				deps.toolRegistry,
+				currentToolInvokeOptions,
+				turnRuntime.toolTelemetry,
+			);
+		},
+		recordUsage: (runtime, usage: Usage | null) => {
+			recordOutOfTurnUsage(runtime, sideQuestionUsage(usage), "prewarm");
+		},
+		...(deps.runPrewarm ? { runPrewarm: deps.runPrewarm } : {}),
+		...(deps.abortPrewarmOnSubmit === undefined ? {} : { abortRoundOnSubmit: deps.abortPrewarmOnSubmit }),
+		...(deps.registerPrewarmEndpointSlot ? { registerEndpointSlot: deps.registerPrewarmEndpointSlot } : {}),
+	});
+	const unsubscribePrewarmCompaction = subscribePrewarmToCompaction(deps.bus, prewarm);
+	// The prompt this process will send is known now: the session prompt compiles
+	// against the configured target, and a boot-time resume rebuilds the message
+	// array in the same tick, which the scheduler collapses onto one round.
+	prewarm.schedule("session-start");
+
 	const api: ChatLoop = {
 		steer: (text) => queues.steer(text),
 		queueFollowUp: (text) => queues.queueFollowUp(text),
@@ -813,8 +996,11 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 						// lands as a user message before the next model turn.
 						// alt+enter (queueFollowUp) keeps the after-this-run intent.
 						if (isWorkerShareNote(trimmed)) state.turnSharedWorkerNote = true;
-						if (mode === "end-of-turn") queues.queueFollowUp(trimmed);
-						else queues.steer(trimmed);
+						// The queue carries the submitted bytes, not the trimmed copy the
+						// guard above reads: a steer is a model-facing turn and the
+						// payload contract applies to it too (issue #244).
+						if (mode === "end-of-turn") queues.queueFollowUp(text);
+						else queues.steer(text);
 						return;
 					}
 					emitNotice("[Clio Coder] response already in progress. Press Esc to cancel the active run.");
@@ -822,7 +1008,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				}
 			}
 
-			state.lastRunSnapshot = null;
+			const previousRunSnapshot = state.lastRunSnapshot;
 			let agentRuntime: AgentRuntime | null;
 			try {
 				await turnRuntime.ensureLiveCapabilitiesForSelectedModel();
@@ -858,6 +1044,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				currentToolInvokeOptions,
 				turnRuntime.toolTelemetry,
 			);
+			const toolSignature = toolSignatureFromState(agentRuntime.agent.state.tools);
 			const askUserPolicy = createAskUserToolPolicy(agentRuntime.agent.state.tools);
 			// turn_start: the prompt is accepted; registrations may inject
 			// context for this request. Accumulated reminders (turn_end
@@ -887,9 +1074,12 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			// 2. Pre-submit auto-compaction trigger
 			const forceNow = process.env.CLIO_CODER_FORCE_COMPACT === "1";
 			try {
+				setTurnPreparation("compacting");
 				await context.runAutoCompact(agentRuntime, forceNow, undefined, undefined, submittedText);
 			} catch (err) {
 				emitNotice(`[Clio Coder] auto-compaction failed: ${err instanceof Error ? err.message : String(err)}`);
+			} finally {
+				endPreparationCompaction();
 			}
 
 			// 3. Ensure the session prompt (compiles only on explicit events)
@@ -907,20 +1097,33 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 					pendingUserInput: submittedText,
 					images,
 					promptHash: compiledPrompt?.systemPromptHash,
-					toolSignature: toolSignatureFromState(agentRuntime.agent.state.tools),
+					toolSignature,
 				});
 
 			const reservedOutput = resolveReservedOutputTokens(agentRuntime.runtimeResolution.capabilityDecisions.maxTokens);
 			const effectiveWindow = agentRuntime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
 			const pendingInputTokens = ceilChars(submittedText.length);
 			let turnSnapshot = captureTurnSnapshot("pending");
-			const totalEstimate = snapshotInputTokens(turnSnapshot) + pendingInputTokens + reservedOutput;
+			// The snapshot prices the prompt at chars/4. When the provider has
+			// already attested a larger prompt for this conversation, that figure
+			// is what the request will actually cost, so the overflow guard reads
+			// the higher of the two (issue #227). Both already carry the pending
+			// user text and the tool schema estimate.
+			const budgetedPromptTokens = (snapshot: ContextSnapshot): number =>
+				Math.max(
+					snapshotInputTokens(snapshot) + pendingInputTokens,
+					context.liveContextEstimate(agentRuntime, submittedText).tokens,
+				);
+			const totalEstimate = budgetedPromptTokens(turnSnapshot) + reservedOutput;
 
 			if (effectiveWindow > 0 && totalEstimate > effectiveWindow) {
 				emitNotice(
-					`[Clio Coder] Estimated request size ${totalEstimate} tokens (input ${snapshotInputTokens(turnSnapshot) + pendingInputTokens} + output budget ${reservedOutput}) exceeds the effective context window of ${effectiveWindow} tokens. Running compaction before sending...`,
+					`[Clio Coder] Estimated request size ${totalEstimate} tokens (input ${totalEstimate - reservedOutput} + output budget ${reservedOutput}) exceeds the effective context window of ${effectiveWindow} tokens. Running compaction before sending...`,
 				);
-				const compacted = await context.runAutoCompact(agentRuntime, true, undefined, undefined, submittedText);
+				setTurnPreparation("compacting");
+				const compacted = await context
+					.runAutoCompact(agentRuntime, true, undefined, undefined, submittedText)
+					.finally(endPreparationCompaction);
 				if (!compacted) {
 					emitNotice(
 						"[Clio Coder] Compaction could not reclaim enough space. Request blocked; trim the prompt, reduce active tools, or start a fresh session.",
@@ -929,7 +1132,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				}
 				context.refreshAgentMessagesFromSession(agentRuntime);
 				turnSnapshot = captureTurnSnapshot("pending");
-				const postTotalEstimate = snapshotInputTokens(turnSnapshot) + pendingInputTokens + reservedOutput;
+				const postTotalEstimate = budgetedPromptTokens(turnSnapshot) + reservedOutput;
 				if (postTotalEstimate > effectiveWindow) {
 					emitNotice(
 						`[Clio Coder] Request still exceeds the effective window after compaction (${postTotalEstimate} > ${effectiveWindow}). Request blocked.`,
@@ -956,6 +1159,16 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			// cancelled run's leftovers, which is the order the ledger has.
 			if (interrupted) emit({ type: "queued_user_turn", text, kind: "interrupt" });
 			context.logPromptCompileIfPending();
+			const previousThinkingLevel = previousRunSnapshot?.runtimeResolution?.effectiveThinkingLevel;
+			if (
+				previousThinkingLevel !== undefined &&
+				previousThinkingLevel !== agentRuntime.runtimeResolution.effectiveThinkingLevel
+			) {
+				context.noteColdReason("thinking_change");
+			}
+			if (typeof previousRunSnapshot?.toolSignature === "string" && previousRunSnapshot.toolSignature !== toolSignature) {
+				context.noteColdReason("tool_surface_change");
+			}
 			turnSnapshot = { ...turnSnapshot, turnId: userTurnId ?? "unknown" };
 			context.setCurrentSnapshot(turnSnapshot);
 			context.persistContextSnapshot(turnSnapshot);
@@ -970,7 +1183,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				compiledPromptHash: promptHash,
 				staticCompositionHash: promptHash,
 				promptSignature: promptHash,
-				toolSignature: toolSignatureFromState(agentRuntime.agent.state.tools),
+				toolSignature,
 				runtimeResolution: runtimeTargetSnapshot(agentRuntime.runtimeResolution),
 				sessionId: deps.session?.current()?.id ?? null,
 				cwd: process.cwd(),
@@ -988,6 +1201,8 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 
 			// 7. Run the prompt, then route the settled state through recovery.
 			state.streaming = true;
+			const endpointKey = canonicalEndpointKey(agentRuntime.runtimeResolution.target);
+			const releaseForeground = endpointKey === null ? () => {} : registerForegroundStream(endpointKey);
 			try {
 				options.onAdmitted?.();
 			} catch {
@@ -1051,6 +1266,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 				}
 				await recovery.runCompactAndRetry(agentRuntime, runtimePromptText, overflow, images);
 			} finally {
+				releaseForeground();
 				if (askUserPolicy) {
 					try {
 						await finalizeAskUserInterviewForHost(
@@ -1151,9 +1367,21 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			return state.streaming;
 		},
 
+		turnPreparation() {
+			return { phase: state.turnPreparation, since: state.turnPreparationSince };
+		},
+
+		onTurnPreparation(handler) {
+			preparationListeners.add(handler);
+			return () => {
+				preparationListeners.delete(handler);
+			};
+		},
+
 		contextUsage: () => context.contextUsage(),
 		contextLedger: () => context.contextLedger(),
 		whenSettled: () => activeSubmit,
+		whenPrewarmSettled: () => prewarm.settled(),
 
 		resetForSession(leafTurnId: string | null, replayMessages?: ReadonlyArray<AgentMessage>): void {
 			if (state.runtime) {
@@ -1166,6 +1394,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			middleware.clearPendingReminders();
 			middlewareToolChoice.reset();
 			state.lastTurnId = leafTurnId;
+			state.lastRunSnapshot = null;
 			context.resetForSession();
 			// The resumed ledger renders before the first new turn (issue #189),
 			// and the window it renders against should be the probed one rather
@@ -1180,11 +1409,17 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			if (deps.protectedArtifacts) {
 				reloadProtectedArtifactsForSession(deps.protectedArtifacts, deps.readSessionEntries);
 			}
+			// A resume replays a history the backend has never seen; a fresh session
+			// replays nothing but still compiles a prompt and a tool surface. Both
+			// leave a prefix the next turn will pay for unless it is sent now.
+			prewarm.schedule(replayMessages && replayMessages.length > 0 ? "resume" : "session-start");
 		},
 
 		dispose(): void {
 			unsubscribeConfigReload?.();
 			unsubscribeSynthesisLock?.();
+			unsubscribePrewarmCompaction();
+			prewarm.dispose();
 			context.dispose();
 			if (state.runtime) {
 				state.runtime.agent.abort();
@@ -1211,16 +1446,18 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
 			let result: SideQuestionResult;
 			try {
-				result = await sideQuestionRound({
-					model: prepared.runtime.agent.state.model,
-					// Read-only: runSideQuestion copies before appending its own
-					// message, so the live agent's history is untouched.
-					messages: prepared.runtime.agent.state.messages,
-					question: text,
-					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
-					...(options.signal ? { signal: options.signal } : {}),
-					...(options.onDelta ? { onDelta: options.onDelta } : {}),
-				});
+				result = await withEndpointSlot(prepared.runtime, () =>
+					sideQuestionRound({
+						model: prepared.runtime.agent.state.model,
+						// Read-only: runSideQuestion copies before appending its own
+						// message, so the live agent's history is untouched.
+						messages: prepared.runtime.agent.state.messages,
+						question: text,
+						...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+						...(options.signal ? { signal: options.signal } : {}),
+						...(options.onDelta ? { onDelta: options.onDelta } : {}),
+					}),
+				);
 			} catch (err) {
 				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
 			}
@@ -1228,7 +1465,7 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			return result.aborted ? { status: "aborted", text: result.text } : { status: "answered", text: result.text };
 		},
 
-		async extractHandoff(goal: string, options: SideQuestionOptions = {}): Promise<SideQuestionOutcome> {
+		async extractHandoff(goal: string, options: HandoffRoundOptions = {}): Promise<SideQuestionOutcome> {
 			const text = goal.trim();
 			if (text.length === 0) {
 				return { status: "refused", reason: "a handoff needs a goal" };
@@ -1243,14 +1480,20 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			if (!prepared.ok) return { status: "refused", reason: prepared.reason };
 			let result: SideQuestionResult;
 			try {
-				result = await handoffRound({
-					model: prepared.runtime.agent.state.model,
-					// Read-only, exactly as the side-question round treats it.
-					messages: prepared.runtime.agent.state.messages,
-					goal: text,
-					...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
-					...(options.signal ? { signal: options.signal } : {}),
-				});
+				result = await withEndpointSlot(prepared.runtime, () =>
+					handoffRound({
+						model: prepared.runtime.agent.state.model,
+						// Read-only, exactly as the side-question round treats it.
+						messages: prepared.runtime.agent.state.messages,
+						goal: text,
+						// The runtime id is what decides whether the schema can be bound
+						// on the wire rather than only stated in the prompt.
+						runtimeId: prepared.runtime.runtimeResolution.runtime.id,
+						...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
+						...(options.signal ? { signal: options.signal } : {}),
+						...(options.repair ? { repair: options.repair } : {}),
+					}),
+				);
 			} catch (err) {
 				return { status: "failed", reason: err instanceof Error ? err.message : String(err) };
 			}
@@ -1295,7 +1538,13 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	const submitInner = api.submit.bind(api);
 	const submitTracked: ChatLoop["submit"] = (text, options) => {
 		priorSubmit = activeSubmit;
-		const run = submitInner(text, options);
+		// The flag brackets the whole submit, including the early returns an
+		// admission failure takes, so a refused turn does not leave the pre-warm
+		// believing a turn is still running.
+		turnActive = true;
+		const run = submitInner(text, options).finally(() => {
+			turnActive = false;
+		});
 		activeSubmit = run.catch(() => {});
 		return run;
 	};
@@ -1312,6 +1561,11 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 	// released at admission, not settlement, so steering stays immediate.
 	let admissionTail: Promise<void> | null = null;
 	api.submit = (text, options = {}) => {
+		// The operator owns the slot from the keystroke, not from admission. The
+		// prefix the pre-warm already pushed through stays in it either way, so
+		// aborting here costs nothing and stops the real turn from queueing behind
+		// a request nobody is waiting on.
+		prewarm.cancel();
 		const previous = admissionTail;
 		let release: () => void = () => {};
 		const ticket = new Promise<void>((resolve) => {
@@ -1322,15 +1576,38 @@ export function createChatLoop(deps: CreateChatLoopDeps): ChatLoop {
 			release();
 			if (admissionTail === ticket) admissionTail = null;
 		};
-		const start = (): Promise<void> =>
-			submitTracked(text, {
-				...options,
+		// The window opens here, not at admission: the caller has already cleared
+		// the editor and painted the prompt, and a submit that queues behind the
+		// FIFO gate is still a prompt Clio is holding. It closes once, at
+		// whichever of admission and settlement comes first, so a refused probe
+		// and a blocked overflow preflight close it as reliably as a turn that
+		// reaches the stream.
+		enterPreparation();
+		let leftPreparation = false;
+		const leaveOnce = (): void => {
+			if (leftPreparation) return;
+			leftPreparation = true;
+			leavePreparation();
+		};
+		const start = async (): Promise<void> => {
+			const { onPreparationVisible, ...submitOptions } = options;
+			try {
+				await onPreparationVisible?.();
+			} catch {
+				// A presentation observer cannot refuse a turn after the editor has
+				// consumed it. The ordinary render path can recover on its next tick.
+			}
+			return submitTracked(text, {
+				...submitOptions,
 				onAdmitted: () => {
 					releaseTicket();
+					leaveOnce();
 					options.onAdmitted?.();
 				},
 			}).finally(releaseTicket);
-		return previous ? previous.then(start) : start();
+		};
+		const run = previous ? previous.then(start) : start();
+		return run.finally(leaveOnce);
 	};
 
 	return api;