@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/interactive/turn-context.ts

@@ -1,3 +1,4 @@
+import { replaceEngineMessages, setEngineSystemPrompt } from "../engine/agent.js";
 /**
  * Turn context ownership: the session-prompt compile cache, context-snapshot
  * accounting, prompt-cache honesty, and compaction. `runAutoCompact` is the
@@ -101,6 +102,7 @@ import type { TurnMiddleware } from "./turn-middleware.js";
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
 
 export interface TurnContextDeps {
+	interactiveGuidance?: boolean;
 	state: ChatTurnState;
 	getSettings: () => Readonly<ClioSettings>;
 	providers: ProvidersContract;
@@ -120,6 +122,7 @@ export interface TurnContextDeps {
 	/** Test seam for the eviction planner; production uses `planEviction` from the working-set engine. */
 	planEviction?: typeof planEviction;
 	getMemorySection?: (() => string) | undefined;
+	getReadySkillCount?: (() => number) | undefined;
 	middleware: TurnMiddleware;
 	emitNotice: (text: string) => void;
 }
@@ -205,9 +208,11 @@ export interface TurnContext {
 	postToolContinuationGuard(
 		agentRuntime: AgentRuntime,
 		signal?: AbortSignal,
+		/** A completed background reminder was just appended to the context tail. */
+		contextChanged?: boolean,
 	): Promise<
 		| {
-				context: { systemPrompt: string; messages: AgentMessage[]; tools: AgentRuntime["agent"]["state"]["tools"] };
+				context: { messages: AgentMessage[]; tools: AgentRuntime["agent"]["state"]["tools"] };
 				model: AgentRuntime["agent"]["state"]["model"];
 				thinkingLevel: AgentRuntime["agent"]["state"]["thinkingLevel"];
 		  }
@@ -350,7 +355,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		if (!runExpectedColdReasons.includes(reason)) runExpectedColdReasons.push(reason);
 		if (nextAssistantColdReasons.includes(reason)) return;
 		nextAssistantColdReasons.push(reason);
-		deps.emitNotice(`[context engine] backend prefix cache likely cold this turn: ${reason}`);
+		deps.emitNotice(`[context engine] ${reason} may affect cache reuse; actual reuse is reported with the response.`);
 	};
 	const unsubscribeColdReasonSources = [
 		...[BusChannels.DispatchStarted, BusChannels.DispatchCompleted, BusChannels.DispatchFailed].map(
@@ -428,7 +433,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			runtimeId: agentRuntime.runtimeId,
 			modelId: agentRuntime.wireModelId,
 			systemPrompt: agentRuntime.agent.state.systemPrompt,
-			conversationMessages: agentRuntime.agent.state.messages,
+			conversationMessages: agentRuntime.agent.state.messages.filter((message) => message.role !== "system"),
 			activeToolSchemas: agentRuntime.agent.state.tools,
 			desiredContextWindow: details.desiredContextWindow,
 			effectiveContextWindow: details.effectiveContextWindow,
@@ -446,7 +451,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const liveStreamingOutputTokens = (): number => {
 		if (!state.runtime) return 0;
 		if (state.streaming) {
-			const messages = state.runtime.agent.state.messages;
+			const messages = state.runtime.agent.state.messages.filter((message) => message.role !== "system");
 			const lastMsg = messages[messages.length - 1] as { role?: string; payload?: unknown; content?: unknown } | undefined;
 			if (lastMsg && lastMsg.role === "assistant") {
 				return ceilChars(contentChars(lastMsg.payload ?? lastMsg.content));
@@ -583,7 +588,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const reconciledHistoryTokens = (agentRuntime: AgentRuntime): number | null => {
 		const anchor = reconciledAnchor;
 		if (!anchor) return null;
-		const messages = agentRuntime.agent.state.messages;
+		const messages = agentRuntime.agent.state.messages.filter((message) => message.role !== "system");
 		if (
 			anchor.runtime !== agentRuntime ||
 			anchor.model !== agentRuntime.agent.state.model ||
@@ -610,7 +615,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		const contextWindow = agentRuntime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
 		const estimateInput = {
 			systemPrompt: agentRuntime.agent.state.systemPrompt,
-			messages: agentRuntime.agent.state.messages,
+			messages: agentRuntime.agent.state.messages.filter((message) => message.role !== "system"),
 			tools: agentRuntime.agent.state.tools,
 			...(pendingUserText !== undefined ? { pendingUserText } : {}),
 		};
@@ -662,15 +667,18 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		reconciledAnchor = {
 			...reconciledAnchor,
 			tokens: Math.max(0, historyTokens - Math.max(0, tokensRemoved)),
-			anchoredMessages: [...agentRuntime.agent.state.messages],
+			anchoredMessages: [...agentRuntime.agent.state.messages.filter((message) => message.role !== "system")],
 		};
 	};
 
 	const refreshAgentMessagesFromSession = (agentRuntime: AgentRuntime): ReadonlyArray<SessionEntry> => {
 		const refreshedEntries = deps.readSessionEntries?.() ?? [];
-		agentRuntime.agent.state.messages = buildModelReplayAgentMessagesFromTurns(refreshedEntries, {
-			...(state.lastTurnId ? { activeLeafTurnId: state.lastTurnId } : {}),
-		});
+		replaceEngineMessages(
+			agentRuntime.agent,
+			buildModelReplayAgentMessagesFromTurns(refreshedEntries, {
+				...(state.lastTurnId ? { activeLeafTurnId: state.lastTurnId } : {}),
+			}),
+		);
 		state.replayedContextMessages = [];
 		return refreshedEntries;
 	};
@@ -770,7 +778,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 								entries: deps.readSessionEntries(),
 								context: {
 									systemPrompt: agentRuntime.agent.state.systemPrompt,
-									messages: agentRuntime.agent.state.messages,
+									messages: agentRuntime.agent.state.messages.filter((message) => message.role !== "system"),
 									tools: agentRuntime.agent.state.tools,
 									model: agentRuntime.agent.state.model,
 									thinkingLevel: agentRuntime.agent.state.thinkingLevel,
@@ -1125,14 +1133,13 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	};
 
 	const toolResultTail = (agentRuntime: AgentRuntime): boolean => {
-		const messages = agentRuntime.agent.state.messages;
+		const messages = agentRuntime.agent.state.messages.filter((message) => message.role !== "system");
 		const tail = messages[messages.length - 1] as AgentMessage | undefined;
 		return !!tail && typeof tail === "object" && tail !== null && "role" in tail && tail.role === "toolResult";
 	};
 
 	const continuationContextUpdate = (agentRuntime: AgentRuntime) => ({
 		context: {
-			systemPrompt: agentRuntime.agent.state.systemPrompt,
 			messages: [...agentRuntime.agent.state.messages],
 			tools: [...agentRuntime.agent.state.tools],
 		},
@@ -1169,7 +1176,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				// same messages, which is why it is folded in here.
 				reconciledAnchor = {
 					tokens: promptTokens + (usage.output || 0),
-					anchoredMessages: [...runtime.agent.state.messages],
+					anchoredMessages: [...runtime.agent.state.messages.filter((message) => message.role !== "system")],
 					runtime,
 					model: runtime.agent.state.model,
 					modelKey: anchorModelKey(runtime),
@@ -1183,6 +1190,22 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			if (!currentContextSnapshot) return;
 			// Reconcile in memory on every API call so the live meters
 			// track usage; persistence waits for the run to settle.
+			if (runtime) {
+				const messages = runtime.agent.state.messages.filter((message) => message.role !== "system");
+				// The just-completed response is output, not part of its own prompt.
+				const promptMessages = messages.at(-1)?.role === "assistant" ? messages.slice(0, -1) : messages;
+				currentContextSnapshot = captureRuntimeContextSnapshot(
+					runtime,
+					currentContextSnapshot.turnId,
+					deps.getSettings().context.compaction?.threshold ?? null,
+					{
+						conversationMessages: promptMessages,
+						promptSegments: currentContextSnapshot.promptSegments,
+						promptHash: currentContextSnapshot.promptHash,
+						toolSignature: currentContextSnapshot.toolSignature,
+					},
+				);
+			}
 			currentContextSnapshot = reconcileSnapshot(currentContextSnapshot, usage);
 			snapshotPersistPending = true;
 		},
@@ -1235,6 +1258,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				return hint ? [{ tool: name, hint }] : [];
 			});
 			const sessionInputs: SessionPromptInputs = {
+				...(state.currentTurnConstraints ? { turnConstraints: state.currentTurnConstraints } : {}),
+				...(deps.getReadySkillCount ? { readySkillCount: deps.getReadySkillCount() } : {}),
+				demo: deps.interactiveGuidance === true && settings.interface.demo,
 				provider: agentRuntime.targetId,
 				model: agentRuntime.wireModelId,
 				contextWindow,
@@ -1281,7 +1307,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				const previousHash = sessionPromptHash ?? lastRecordedPromptHash();
 				const changed = agentRuntime.agent.state.systemPrompt !== result.systemPrompt;
 				if (changed) {
-					agentRuntime.agent.state.systemPrompt = result.systemPrompt;
+					setEngineSystemPrompt(agentRuntime.agent, result.systemPrompt);
 					pendingPromptLogEntry = {
 						version: PROMPT_MANIFEST_VERSION,
 						at: new Date().toISOString(),
@@ -1355,8 +1381,12 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			for (const path of paths) sessionWorkingContextPaths.add(path);
 		},
 
-		async postToolContinuationGuard(agentRuntime: AgentRuntime, signal?: AbortSignal) {
-			if (signal?.aborted || !toolResultTail(agentRuntime)) return undefined;
+		async postToolContinuationGuard(agentRuntime: AgentRuntime, signal?: AbortSignal, contextChanged = false) {
+			if (signal?.aborted || (!contextChanged && !toolResultTail(agentRuntime))) return undefined;
+			// A background reminder has its own middleware receipt, not a user
+			// ledger turn. Preserve its newly appended context tail if compaction
+			// rebuilds messages from the ledger, and count it in both estimates.
+			const reminder = contextChanged ? agentRuntime.agent.state.messages.at(-1) : undefined;
 			const before = liveContextEstimate(agentRuntime);
 			if (before.contextWindow <= 0 || before.tokens <= 0) return undefined;
 
@@ -1374,6 +1404,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				}
 			}
 
+			if (reminder && !agentRuntime.agent.state.messages.includes(reminder)) {
+				agentRuntime.agent.state.messages.push(reminder);
+			}
 			const after = liveContextEstimate(agentRuntime);
 			if (after.tokens >= after.contextWindow) {
 				throw new Error(
@@ -1395,7 +1428,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			const totalUsed = snapshotInputTokens(currentContextSnapshot) + pendingTokens + liveStreamingOutputTokens();
 			const breakdown: ContextUsageBreakdown = {
 				systemPromptTokens: currentContextSnapshot.categories.system,
-				messageTokens: currentContextSnapshot.categories.messages,
+				messageTokens: currentContextSnapshot.categories.messages + (currentContextSnapshot.categories.toolResults ?? 0),
 				pendingUserTokens: pendingTokens,
 				toolSchemaTokens: currentContextSnapshot.categories.tools,
 			};
@@ -1451,6 +1484,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				// the live agent state after a session resume.
 				toolCount: currentContextSnapshot.activeToolSchemas?.length ?? liveToolCount,
 				messageTokens: currentContextSnapshot.categories.messages,
+				toolResultTokens: currentContextSnapshot.categories.toolResults ?? 0,
 				agentsTokens: currentContextSnapshot.categories.agents,
 				skillsTokens: currentContextSnapshot.categories.skills,
 				memoryTokens: currentContextSnapshot.categories.memory,
@@ -1489,7 +1523,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				if (reasons.length > 0) {
 					runExpectedColdReasons = reasons;
 					nextAssistantColdReasons = reasons;
-					deps.emitNotice(`[context engine] backend prefix cache likely cold this turn: ${reasons.join(", ")}`);
+					deps.emitNotice(
+						`[context engine] ${reasons.join(", ")} may affect cache reuse; actual reuse is reported with the response.`,
+					);
 				}
 			}
 		},
@@ -1505,7 +1541,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				input,
 				cacheRead,
 				cacheWrite,
-				backendVerdict: backendCacheVerdict(input, cacheRead, backend),
+				backendVerdict: backendCacheVerdict(input, cacheRead, backend, usage.cacheReadReported),
 			};
 			if (backend !== undefined) promptCache.backend = { ...backend };
 			if (nextAssistantColdReasons.length > 0) {

package/src/interactive/turn-middleware.ts

@@ -5,6 +5,7 @@
  * nudge. Owns every `deps.middleware` interaction of the loop.
  */
 
+import { turnAllowsContinuation } from "../core/turn-constraints.js";
 import {
 	MIDDLEWARE_HOOK_TEXT_MAX_CHARS,
 	type MiddlewareContract,
@@ -30,6 +31,8 @@ export interface TurnMiddlewareDeps {
 }
 
 export interface TurnMiddleware {
+	/** Async-only completed tool-batch observation and delivery of already-finished background reminders. */
+	prepareToolContinuation(agentRuntime: AgentRuntime, signal?: AbortSignal): Promise<boolean>;
 	fireTurnStart(
 		agentRuntime: AgentRuntime,
 		promptText: string,
@@ -71,13 +74,13 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 	// Reminders accumulated from middleware `inject_reminder` effects
 	// (turn_end advisories, hard-block recovery guidance, turn_start
 	// injections). The next accepted prompt flushes them into the model
-	// request as one system-reminder block; the buffer clears on session
-	// switch.
-	const pendingReminders: Array<{ message: string; severity: MiddlewareReminderSeverity }> = [];
+	// request as one system-reminder block. Completed background reminders
+	// can also drain at a native tool-batch boundary; session switches clear all.
+	const pendingReminders: Array<{ message: string; severity: MiddlewareReminderSeverity; deferred: boolean }> = [];
 
-	const bufferReminder = (message: string, severity: MiddlewareReminderSeverity): void => {
+	const bufferReminder = (message: string, severity: MiddlewareReminderSeverity, deferred = false): void => {
 		if (pendingReminders.some((entry) => entry.message === message && entry.severity === severity)) return;
-		pendingReminders.push({ message, severity });
+		pendingReminders.push({ message, severity, deferred });
 	};
 
 	const runMiddlewareTurnHook = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
@@ -170,6 +173,40 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 	};
 
 	return {
+		async prepareToolContinuation(agentRuntime, signal): Promise<boolean> {
+			const sessionId = deps.session?.current()?.id;
+			const userTurnId = state.activeUserTurnId;
+			const current = () =>
+				!signal?.aborted &&
+				state.activeInterruptReason === null &&
+				deps.session?.current()?.id === sessionId &&
+				state.activeUserTurnId === userTurnId;
+			if (!current()) return false;
+			// This is not a user-turn finish: run only the async observation phase,
+			// never completion assessors or foreground continuation effects.
+			await runMiddlewareTurnHookAsync(
+				{
+					hook: "after_tool",
+					...(sessionId ? { sessionId } : {}),
+					...(state.lastTurnId ? { turnId: state.lastTurnId } : {}),
+					metadata: { stage: "tool_batch_end", ...(userTurnId ? { userTurnId } : {}) },
+				},
+				[],
+			);
+			if (!current()) return false;
+			const ready = pendingReminders.filter((entry) => entry.deferred);
+			if (ready.length === 0) return false;
+			const content = `<system-reminder>\n${[...new Set(ready.map((entry) => entry.message))].join("\n\n")}\n</system-reminder>`;
+			// injectDeferredReminder already persisted a middleware receipt. Update
+			// context directly: message events would invent a new operator turn and
+			// reset task/tool authority in appendQueuedUserTurn.
+			agentRuntime.agent.state.messages.push({ role: "user", content, timestamp: Date.now() });
+			for (let index = pendingReminders.length - 1; index >= 0; index--) {
+				if (pendingReminders[index]?.deferred) pendingReminders.splice(index, 1);
+			}
+			return true;
+		},
+
 		fireTurnStart(agentRuntime, promptText, pendingSkillRequestCount = 0, requestContinuation = false): void {
 			const sessionId = deps.session?.current()?.id;
 			const input: MiddlewareHookInput = {
@@ -183,10 +220,11 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 					promptChars: promptText.length,
 					queued: false,
 					requestContinuation,
+					turnMode: state.currentTurnConstraints?.mode ?? "",
 					activeToolNames: toolNamesFromAgentState(agentRuntime.agent.state.tools).join(","),
 					// First-substantive-turn signal for once-per-session reminders:
 					// a fresh session's opening turn has an empty conversation.
-					conversationMessages: agentRuntime.agent.state.messages.length,
+					conversationMessages: agentRuntime.agent.state.messages.filter((message) => message.role !== "system").length,
 					pendingSkillRequests: pendingSkillRequestCount,
 				},
 			};
@@ -204,7 +242,8 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			const message = terminalToolResult === undefined ? lastAssistantMessage(messages) : null;
 			if (message === null && terminalToolResult === undefined) return;
 			const text = message === null ? "" : extractText(message);
-			if (terminalToolResult === undefined && text.trim().length === 0) return;
+			// Empty error/abort completions still close a tool-bearing turn. Let
+			// lifecycle observers settle their state even without final prose.
 			const stopReason = message === null ? "stop" : (message as { stopReason?: unknown }).stopReason;
 			const metadata: Record<string, MiddlewareMetadataValue> = {
 				assistantTextChars: text.length,
@@ -215,6 +254,7 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 				turnToolCalls: state.turnToolCalls,
 				turnToolNames: state.turnToolNames.join(","),
 				sharedWorkerNote: state.turnSharedWorkerNote,
+				turnMode: state.currentTurnConstraints?.mode ?? "",
 			};
 			if (terminalToolResult !== undefined) {
 				metadata.terminalToolResult = true;
@@ -237,12 +277,20 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			};
 			const syncEffects = runMiddlewareTurnHook(input);
 			const effects = [...syncEffects, ...(await runMiddlewareTurnHookAsync(input, syncEffects))];
+			// Observation is not recovery authority. No reminder or continuation
+			// may restart a failed or operator-canceled foreground turn.
+			if (stopReason === "aborted") {
+				for (let index = pendingReminders.length - 1; index >= 0; index--) {
+					if (pendingReminders[index]?.deferred) pendingReminders.splice(index, 1);
+				}
+			}
+			if (stopReason === "error" || stopReason === "aborted") return;
 			for (const effect of effects) {
 				if (effect.kind === "inject_reminder") {
 					applyTurnEndReminder(agentRuntime, effect.message, effect.severity ?? "info");
 					continue;
 				}
-				if (effect.kind === "request_continuation") {
+				if (effect.kind === "request_continuation" && turnAllowsContinuation(state.currentTurnConstraints)) {
 					applyRequestContinuation(effect.message);
 				}
 			}
@@ -286,7 +334,7 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			// could have interrupted is already over.
 			const level: MiddlewareReminderSeverity = severity === "hard-block" ? "advisory" : severity;
 			if (pendingReminders.some((entry) => entry.message === text)) return;
-			bufferReminder(text, level);
+			bufferReminder(text, level, true);
 			appendMiddlewareReminderEntry(text, level);
 			deps.emitNotice(text);
 		},

package/src/interactive/turn-prewarm.ts

@@ -15,6 +15,7 @@ import { BusChannels } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import { endpointCapacityUsage } from "../domains/dispatch/index.js";
+import { registerForegroundStream } from "../domains/providers/endpoint-capacity.js";
 import {
 	type CacheDeploymentObservation,
 	observeCacheDeployment,
@@ -23,6 +24,7 @@ import {
 import type { SessionContract } from "../domains/session/contract.js";
 import type { Usage } from "../engine/types.js";
 import { type PrewarmTrigger, prewarmPromptTokens, runPrewarmRound } from "./prewarm.js";
+import { recordStartupDiagnostic } from "./startup-diagnostics.js";
 import type { TurnContext } from "./turn-context.js";
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
 
@@ -203,27 +205,104 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 		if (!target) return { ran: false, reason: "unresolved" };
 		const targetSettings = JSON.stringify(target);
 		const started = Date.now();
+		if (target.cache?.deployment?.backend === "lmstudio" && target.cache.warm?.startup !== true)
+			return { ran: false, reason: "disabled", detail: "local-warming-not-enabled" };
 		if (target.cache?.retention === "none") return { ran: false, reason: "disabled" };
 		if (target.pricing && Object.values(target.pricing).some((rate) => rate > 0))
 			return { ran: false, reason: "deployment", detail: "paid-warming-disabled" };
 		const cooldown = Math.max(1000, target.cache?.warm?.cooldownMs ?? 60000);
 		if (Date.now() - lastFinished < cooldown) return { ran: false, reason: "cooldown" };
 		const observe = deps.observeDeployment ?? observeCacheDeployment;
-		let deployment: CacheDeploymentObservation = await observe(target, deps.getSettings().chat.model ?? "", {
-			signal: controller.signal,
-		});
-		if (deployment.warm !== "bounded") return { ran: false, reason: "deployment", detail: deployment.reason };
+		const descriptor = deps.providers.getRuntime(target.runtime);
+		if (!descriptor) return { ran: false, reason: "unresolved" };
+		const auth = await deps.providers.auth.resolveForTarget(target, descriptor, { signal: controller.signal });
+		const observeOptions = { signal: controller.signal, ...(auth.apiKey ? { gatewayApiKey: auth.apiKey } : {}) };
+		const selectedModel = deps.getSettings().chat.model ?? target.defaultModel ?? "";
+		const stillSelected = () =>
+			JSON.stringify(deps.providers.getTarget(target.id)) === targetSettings &&
+			deps.getSettings().chat.target === target.id &&
+			(deps.getSettings().chat.model ?? target.defaultModel ?? "") === selectedModel;
+		const canSend = () =>
+			!admissionRefusal() && !detached.has(controller) && !controller.signal.aborted && stillSelected();
+		let deployment: CacheDeploymentObservation = await observe(target, selectedModel, observeOptions);
+		if (
+			deployment.warm !== "bounded" &&
+			!(
+				deployment.backend === "lmstudio" &&
+				deployment.reason === "model-not-loaded" &&
+				target.cache?.warm?.startup === true
+			)
+		)
+			return { ran: false, reason: "deployment", detail: deployment.reason };
 
+		if (admissionRefusal() || detached.has(controller) || controller.signal.aborted)
+			return { ran: false, reason: "superseded" };
 		const prepared = await deps.prepareRuntime(controller.signal);
 		if (!prepared.ok) return { ran: false, reason: "unresolved" };
 		const runtime = prepared.runtime;
-		if (deps.providers.getRuntime(runtime.runtimeId)?.tier !== "local-native") {
+		if (runtime.targetId !== target.id || runtime.wireModelId !== selectedModel || runtime.runtimeId !== target.runtime)
+			return { ran: false, reason: "superseded" };
+		if (
+			deps.providers.getRuntime(runtime.runtimeId)?.tier !== "local-native" &&
+			!(
+				runtime.runtimeId === "litellm" &&
+				deployment.backend === "lmstudio" &&
+				(deployment.warm === "bounded" || deployment.reason === "model-not-loaded")
+			)
+		) {
 			// Off on every other tier regardless of the setting. A cloud provider
 			// caches by exact prefix on its own schedule and bills the request; a
 			// pre-warm there is spend without a latency win.
 			return { ran: false, reason: "tier" };
 		}
 
+		if (
+			deployment.backend === "lmstudio" &&
+			deployment.reason === "model-not-loaded" &&
+			target.cache?.warm?.startup === true &&
+			!admissionRefusal() &&
+			!controller.signal.aborted &&
+			!detached.has(controller) &&
+			stillSelected() &&
+			deployment.endpoint &&
+			(endpointCapacityUsage()[deployment.endpoint] ?? 0) === 0
+		) {
+			// Wake-up is a tiny separate request; exact-prefix work follows only
+			// after residency is observed. Neither operation gates TUI startup.
+			const release = registerForegroundStream(deployment.endpoint);
+			const deadline = setTimeout(() => controller.abort(), Math.min(target.cache.warm.maxDurationMs ?? 30000, 120000));
+			try {
+				const wake = await round({
+					model: runtime.agent.state.model,
+					state: { systemPrompt: "", messages: [], tools: [], thinkingLevel: "off" },
+					...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+					signal: controller.signal,
+					maxInputTokens: Math.min(256, target.cache.warm.maxInputTokens ?? 256),
+					canSend,
+				});
+				deps.recordUsage(runtime, wake.usage);
+				recordStartupDiagnostic({
+					kind: "model-wake",
+					target: target.id,
+					model: selectedModel,
+					timing: wake.timing,
+					usage: wake.usage,
+					aborted: wake.aborted,
+					failed: Boolean(wake.errorMessage),
+				});
+				if (wake.aborted || wake.errorMessage) return { ran: false, reason: "deployment", detail: "wake-incomplete" };
+			} finally {
+				clearTimeout(deadline);
+				release();
+			}
+			deployment = await observe(target, selectedModel, observeOptions);
+		}
+
+		if (deployment.warm !== "bounded") return { ran: false, reason: "deployment", detail: deployment.reason };
+
+		if (admissionRefusal() || detached.has(controller) || controller.signal.aborted || !stillSelected())
+			return { ran: false, reason: "superseded" };
+
 		deps.applySessionTools(runtime);
 		await deps.context.ensureSessionPrompt(runtime);
 
@@ -235,15 +314,11 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 		if (detached.has(controller) || controller.signal.aborted) return { ran: false, reason: "superseded" };
 		// Binding/residency can change during preparation. Discovery itself never
 		// loads models and missing evidence leaves ordinary inference untouched.
-		deployment = await observe(target, runtime.wireModelId, { signal: controller.signal });
+		deployment = await observe(target, runtime.wireModelId, observeOptions);
 		if (deployment.warm !== "bounded") return { ran: false, reason: "deployment", detail: deployment.reason };
 		const finalRefusal = admissionRefusal();
 		if (finalRefusal) return { ran: false, reason: finalRefusal };
-		if (
-			detached.has(controller) ||
-			controller.signal.aborted ||
-			JSON.stringify(deps.providers.getTarget(target.id)) !== targetSettings
-		)
+		if (detached.has(controller) || controller.signal.aborted || !stillSelected())
 			return { ran: false, reason: "superseded" };
 		if (Date.now() - started > 30000) return { ran: false, reason: "expired" };
 		// This includes shared dispatch leases/reservations and this process's
@@ -269,6 +344,8 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 		// finally, including on the detach path, because the request the server is
 		// still finishing is the one occupying the slot.
 		const releaseEndpointSlot = deps.registerEndpointSlot?.(runtime) ?? null;
+		const releaseBackend =
+			runtime.runtimeId === "litellm" && deployment.endpoint ? registerForegroundStream(deployment.endpoint) : null;
 		let result: Awaited<ReturnType<typeof round>>;
 		const deadline = setTimeout(() => controller.abort(), Math.min(target.cache?.warm?.maxDurationMs ?? 30000, 120000));
 		try {
@@ -284,11 +361,13 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 				...(prepared.apiKey !== undefined ? { apiKey: prepared.apiKey } : {}),
 				signal: controller.signal,
 				maxInputTokens: target.cache?.warm?.maxInputTokens ?? 8192,
+				canSend,
 			});
 		} finally {
 			clearTimeout(deadline);
 			lastFinished = Date.now();
 			releaseEndpointSlot?.();
+			releaseBackend?.();
 		}
 		lastPrefix = result.aborted || result.errorMessage ? null : prefix;
 
@@ -307,6 +386,17 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 			});
 		}
 		deps.recordUsage(runtime, result.usage);
+		recordStartupDiagnostic({
+			kind: "prompt-warm",
+			target: runtime.targetId,
+			model: runtime.wireModelId,
+			trigger,
+			timing: result.timing,
+			promptTokens,
+			aborted: result.aborted,
+			detached: wasDetached,
+			failed: Boolean(result.errorMessage),
+		});
 
 		try {
 			deps.session?.appendEntry({
@@ -362,6 +452,7 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 		pendingTrigger = null;
 		if (trigger === null) return;
 		const controller = new AbortController();
+		const diagnosticStart = performance.now();
 		active = controller;
 		running = controller;
 		inFlight = (
@@ -370,6 +461,15 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 				: runOnce(trigger, controller)
 		)
 			.then((outcome) => {
+				if (deps.isLatencySurface())
+					recordStartupDiagnostic({
+						kind: "warm-admission",
+						trigger,
+						target: deps.getSettings().chat.target,
+						model: deps.getSettings().chat.model,
+						durationMs: Math.round(performance.now() - diagnosticStart),
+						...outcome,
+					});
 				if (!outcome.ran && deps.getSettings().chat.prewarm && outcome.reason !== "surface") {
 					const key = `${outcome.reason}:${outcome.detail ?? ""}`;
 					if (lastSkip !== key) {
@@ -389,11 +489,16 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 				} else if (outcome.ran) lastSkip = null;
 				return outcome;
 			})
-			.catch(() => null)
+			.catch(() => {
+				if (deps.isLatencySurface())
+					recordStartupDiagnostic({ kind: "warm-admission", trigger, ran: false, reason: "preparation-failed" });
+				return null;
+			})
 			.finally(() => {
 				if (active === controller) active = null;
 				running = null;
-				if (!disposed && pendingTrigger !== null && timer === null) timer = setTimeout(fire, 0);
+				if (!disposed && pendingTrigger !== null && timer === null)
+					timer = setTimeout(fire, pendingTrigger === "session-start" && deps.isLatencySurface() ? 1000 : 0);
 			});
 	};
 
@@ -406,11 +511,9 @@ export function createTurnPrewarm(deps: TurnPrewarmDeps): TurnPrewarm {
 			pendingTrigger = trigger;
 			pendingSince = Date.now();
 			if (timer !== null || running !== null) return;
-			// Ref'd on purpose, same reasoning as `settled()` below: the timer is due
-			// in 0 ms, so it holds the event loop for one tick at most, and a Node 22
-			// loop that drains past a due unref'd timer would otherwise never start
-			// the round a test or caller is already awaiting.
-			timer = setTimeout(fire, 0);
+			// Give startup a quiet second before speculative work. Headless surfaces
+			// never schedule model work; other triggers coalesce on the next tick.
+			timer = setTimeout(fire, trigger === "session-start" && deps.isLatencySurface() ? 1000 : 0);
 		},
 
 		cancel(): void {

package/src/interactive/turn-recovery.ts

@@ -6,6 +6,7 @@
  * terminal failure.
  */
 
+import { isLiteLLMConnectionFailure } from "../core/gateway-routing.js";
 import type { toContextOverflowError } from "../domains/providers/errors.js";
 import {
 	computeRetryDelayMs,
@@ -217,17 +218,18 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 		text: string,
 		initialFailure: TerminalAssistantFailure,
 	): Promise<boolean> => {
-		// A LiteLLM model id can be a deliberate physical route. Retrying it in
-		// Clio obscures the failure, delays operator recovery, and can multiply
-		// attempts beneath a gateway. Preserve and emit the one terminal failure;
-		// the operator can choose another advertised route with /model.
-		if (agentRuntime.runtimeId === "litellm") {
+		// Retry only a client connection failure before output on this exact
+		// route. Keep HTTP gateway/backend failures terminal and never substitute
+		// a model. The SDK itself still performs no hidden gateway retries.
+		const canRetry = (message: string): boolean =>
+			agentRuntime.runtimeId === "litellm" ? isLiteLLMConnectionFailure(message) : isRetryableErrorMessage(message);
+		if (agentRuntime.runtimeId === "litellm" && !canRetry(initialFailure.errorMessage)) {
 			ensureFailureVisibleAndPersisted(initialFailure);
 			return true;
 		}
 		const settings = deps.retrySettings();
 		if (!settings.enabled || settings.maxRetries <= 0) return false;
-		if (initialFailure.stopReason === "aborted" || !isRetryableErrorMessage(initialFailure.errorMessage)) return false;
+		if (initialFailure.stopReason === "aborted" || !canRetry(initialFailure.errorMessage)) return false;
 
 		let failure = initialFailure;
 		for (let attempt = 1; attempt <= settings.maxRetries; attempt += 1) {
@@ -268,7 +270,7 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 				await agentRuntime.agent.continue();
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
-				if (!isRetryableErrorMessage(message) || attempt >= settings.maxRetries) {
+				if (!canRetry(message) || attempt >= settings.maxRetries) {
 					recordRetryStatus({
 						phase: "exhausted",
 						attempt,
@@ -304,7 +306,7 @@ export function createTurnRecovery(deps: TurnRecoveryDeps): TurnRecovery {
 			// watchdog's abort as an operator cancel and stop one rung in.
 			const nextFailure = reclassifyStallAbort(state, settled);
 			ensureFailureVisibleAndPersisted(nextFailure);
-			if (nextFailure.stopReason === "aborted" || !isRetryableErrorMessage(nextFailure.errorMessage)) {
+			if (nextFailure.stopReason === "aborted" || !canRetry(nextFailure.errorMessage)) {
 				pruneFailedAssistantFromContext(agentRuntime.agent);
 				return true;
 			}