@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/interactive/turn-context.ts

@@ -12,9 +12,17 @@ import {
 	type ContextPrunedPayload,
 	type ContextRecalledPayload,
 	type ContextWarningPayload,
+	type MemoryStepCompletedPayload,
+	type ResidencyMutationPayload,
 } from "../core/bus-events.js";
+import {
+	type BackendCacheVerdict,
+	type BackendCompletionTimings,
+	uncachedPrefillTokens,
+} from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import { residencyTargetKey } from "../core/residency-target-key.js";
 import type { ToolName } from "../core/tool-names.js";
 import { buildEvictionFields, planEviction } from "../domains/context/working-set/engine.js";
 import { foldWorkingSet } from "../domains/context/working-set/fold.js";
@@ -26,6 +34,7 @@ import type { PromptsContract } from "../domains/prompts/contract.js";
 import {
 	type ContextWindowDetails,
 	type ContextWindowSource,
+	canonicalEndpointKey,
 	type ProvidersContract,
 	resolveRuntimeTarget,
 } from "../domains/providers/index.js";
@@ -50,18 +59,29 @@ import {
 	contextUsageSnapshot,
 	estimateAgentContextBreakdown,
 	estimateAgentContextTokens,
+	estimateAgentMessageTokens,
 	getLatestContextSnapshot,
+	lastLoadedContextWindow,
 	reconcileSnapshot,
 	snapshotInputTokens,
 } from "../domains/session/context-accounting.js";
-import { buildContextLedger, type ContextLedger, type PromptCacheStats } from "../domains/session/context-ledger.js";
+import {
+	buildContextLedger,
+	type ContextLedger,
+	type PrewarmStats,
+	type PromptCacheStats,
+} from "../domains/session/context-ledger.js";
 import type { SessionContract } from "../domains/session/contract.js";
 import type { CompactionTrigger, SessionEntry } from "../domains/session/entries.js";
-import { appendPromptCompileRecord, type SessionPromptCompileRecord } from "../domains/session/prompt-manifest.js";
+import {
+	appendPromptCompileRecord,
+	PROMPT_MANIFEST_VERSION,
+	readPromptCompileRecords,
+	type SessionPromptCompileRecord,
+} from "../domains/session/prompt-manifest.js";
 import type { AgentMessage, Usage } from "../engine/types.js";
 import type { ToolRegistry } from "../tools/registry.js";
 import {
-	type BackendCacheVerdict,
 	backendCacheVerdict,
 	extractUserText,
 	runtimeSupportsTools,
@@ -92,11 +112,43 @@ export interface TurnContextDeps {
 }
 
 export interface LiveContextEstimate {
+	/**
+	 * The figure to budget against: the reconciled total when the provider has
+	 * attested one for this conversation, otherwise the estimate. Never below
+	 * the estimate, because the estimate covers material the last provider call
+	 * did not see.
+	 */
 	tokens: number;
+	/** Pure chars/4 projection, with the pre-existing provider-usage anchor. */
+	estimatedTokens: number;
+	/**
+	 * Provider-attested prompt tokens for the messages up to the last reconciled
+	 * call, plus a chars/4 estimate of everything appended since. Null before the
+	 * first reconcile of a session and after a summary compaction rewrites the
+	 * history the attestation described.
+	 */
+	reconciledTokens: number | null;
 	contextWindow: number;
 	breakdown: ReturnType<typeof estimateAgentContextBreakdown>;
 }
 
+/** Known causes that make the next provider prefix cache miss expected. */
+export type ExpectedColdReason =
+	| "dispatch"
+	| "compaction"
+	| "working_set_evict"
+	| "residency"
+	| "thinking_change"
+	| "tool_surface_change"
+	| "prompt_recompiled"
+	/**
+	 * A proactive-memory step ran between turns on the endpoint this session
+	 * streams against. Its prompt is a trajectory rather than the chat prefix, so
+	 * on a local server that keeps one prefix cache the next turn re-prefills
+	 * (#229).
+	 */
+	| "background_memory";
+
 export interface TurnContext {
 	ensureSessionPrompt(agentRuntime: AgentRuntime): Promise<CompiledSessionPrompt | null>;
 	logPromptCompileIfPending(): void;
@@ -120,6 +172,12 @@ export interface TurnContext {
 	 */
 	promptSideTokens(): number;
 	liveContextEstimate(agentRuntime: AgentRuntime, pendingUserText?: string): LiveContextEstimate;
+	/**
+	 * The loaded context window this session already recorded for a target and
+	 * model, so a resume budgets against it instead of re-probing. Null when the
+	 * ledger has no such measurement.
+	 */
+	rememberedLoadedContextWindow(targetId: string, modelId: string): number | null;
 	refreshAgentMessagesFromSession(agentRuntime: AgentRuntime): ReadonlyArray<SessionEntry>;
 	runAutoCompact(
 		agentRuntime: AgentRuntime,
@@ -142,12 +200,20 @@ export interface TurnContext {
 	contextUsage(): ContextUsageSnapshot;
 	contextLedger(): ContextLedger;
 	emitContextWindowWarningTransition(warning: string | null): void;
+	/** Record one known cache disturbance for the current or next call. */
+	noteColdReason(reason: ExpectedColdReason): void;
 	/** Consume disturbances since the last settled run (T3.3 honesty). */
 	consumeExpectedColdReasons(runtimeId: string): void;
 	/** Prompt-cache record for one persisted assistant call, with cold-reason stamp. */
-	promptCachePayloadForAssistant(usage: Usage): Record<string, unknown>;
+	promptCachePayloadForAssistant(usage: Usage, backend?: BackendCompletionTimings): Record<string, unknown>;
 	/** Record the settled run's cache summary for /context. */
 	noteRunCacheSummary(messages: ReadonlyArray<AgentMessage>, runFirstCallVerdict: BackendCacheVerdict | null): void;
+	/**
+	 * Record one pre-warm for `/context`. It contributes no tokens to the context
+	 * estimate and is never an expected-cold reason: a pre-warm is the opposite
+	 * of a disturbance, it is the prefix the next turn wants already resident.
+	 */
+	notePrewarm(prewarm: PrewarmStats): void;
 	resetForSession(): void;
 	dispose(): void;
 }
@@ -157,12 +223,30 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const compactionTrigger = new AutoCompactionTrigger<CompactResult | null>();
 
 	let currentContextSnapshot: ContextSnapshot | null = null;
+	/**
+	 * The last provider-attested prompt size, and how many agent messages it
+	 * covered (issue #227).
+	 *
+	 * `tokens` is the provider's own prompt count for that call plus the output
+	 * it produced, which together are what the next call's prompt carries for
+	 * the same messages. `anchoredMessageCount` is the length of the live
+	 * message list at that moment, so anything appended since is priced by
+	 * estimate and added on top. Unlike the per-message usage anchor inside
+	 * `estimateAgentContextTokens`, this survives `contextUsageInvalidated`:
+	 * a working-set projection subtracts the tokens it removed rather than
+	 * throwing the attestation away.
+	 */
+	let reconciledAnchor: { tokens: number; anchoredMessageCount: number } | null = null;
 	let lastCompactionEvent: { stage: string; tokensBefore: number; tokensAfter: number; trigger: string } | null = null;
 	// Last settled run's provider cache usage plus whether the compiled system
 	// prompt was reused. Shown together in /context so "prompt reused" can
 	// never imply provider cache reuse the backend did not report.
 	let lastPromptCache: PromptCacheStats | null = null;
 	let lastSystemPromptReused = false;
+	// The last pre-warm, shown by /context until the next settled run answers the
+	// question it was asked about: did the prefix the next turn needs get there
+	// before the operator did.
+	let lastPrewarm: PrewarmStats | null = null;
 	// The session system prompt, compiled once per session. Recompiles happen
 	// only on explicit events: the compile key (target, model, safety level,
 	// session id) changes, or a config hot-reload invalidates the cache. A
@@ -170,6 +254,19 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	// ledger entry so a cold provider cache is always explainable.
 	let sessionPrompt: CompiledSessionPrompt | null = null;
 	let sessionPromptKey: string | null = null;
+	// The hash this process compiled *for the session that is current now*, and
+	// the manifest's `previousHash` whenever it is set. It is not read off
+	// `sessionPrompt`: an in-process `/resume` leaves that compile in place so
+	// the ledger keeps its project-preload labels until the next compile, but
+	// manifest provenance follows the session, so a switch drops the hash here
+	// and the next compile falls through to the incoming session's own manifest
+	// exactly as a cold-start resume does (#249).
+	let sessionPromptHash: string | null = null;
+	// Whether this process has already looked up the resumed session's last
+	// recorded prompt hash. The lookup reads the manifest file, so it happens
+	// once, on the first compile, and never on the reuse path.
+	let resumedPromptHashRead = false;
+	let resumedPromptHash: string | null = null;
 	const sessionWorkingContextPaths = new Set<string>();
 	let pendingPromptLogEntry: SessionPromptCompileRecord | null = null;
 	// A post-tool guard can run after every tool result in one model turn. Once
@@ -178,22 +275,25 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	// and summary probes. A new submitted user turn gets a new id naturally.
 	let emptyAutoCompactTurnId: string | null = null;
 
-	// Cache-disturbance honesty (T3.3). Dispatch traffic and history
-	// compaction invalidate a single-slot local backend's prefix cache.
-	// Accumulate every disturbance since the last settled run; the next
-	// submit consumes the set, stamps `promptCache.expectedColdReasons` on
-	// its first assistant entry, and shows one dim notice.
-	const pendingColdReasons = new Set<string>();
-	let runExpectedColdReasons: string[] = [];
-	let nextAssistantColdReasons: string[] = [];
-	// A working-set eviction changes the prefix itself, so it cools every
-	// tier's cache, not only a single-slot local one. Dispatch and compaction
-	// disturbances keep the local-native gate below.
-	const TIER_INDEPENDENT_COLD_REASONS: ReadonlySet<string> = new Set(["working_set_evict"]);
-	const stampsOnTier = (reason: string, runtimeId: string | undefined): boolean =>
+	// Cache-disturbance honesty (T3.3). Accumulate every known local-runtime
+	// disturbance and prefix-byte change since the last settled run. The next
+	// submit consumes the set, stamps `promptCache.expectedColdReasons` on its
+	// first assistant entry, and shows one dim notice.
+	const pendingColdReasons = new Set<ExpectedColdReason>();
+	let runExpectedColdReasons: ExpectedColdReason[] = [];
+	let nextAssistantColdReasons: ExpectedColdReason[] = [];
+	// Prefix-byte changes cool every tier. Residency, thinking changes, dispatch
+	// traffic, and compaction keep the local-native gate because they disturb a
+	// local server or its rendered template.
+	const TIER_INDEPENDENT_COLD_REASONS: ReadonlySet<ExpectedColdReason> = new Set([
+		"working_set_evict",
+		"tool_surface_change",
+		"prompt_recompiled",
+	]);
+	const stampsOnTier = (reason: ExpectedColdReason, runtimeId: string | undefined): boolean =>
 		TIER_INDEPENDENT_COLD_REASONS.has(reason) ||
 		(runtimeId !== undefined && deps.providers.getRuntime(runtimeId)?.tier === "local-native");
-	const noteColdReason = (reason: string): void => {
+	const noteColdReason = (reason: ExpectedColdReason): void => {
 		if (!state.streaming) {
 			pendingColdReasons.add(reason);
 			return;
@@ -217,6 +317,21 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					noteColdReason("compaction");
 				}) ?? null,
 		),
+		deps.bus?.on(BusChannels.ResidencyMutation, (payload: ResidencyMutationPayload) => {
+			const runtime = state.runtime;
+			const model = runtime?.agent.state.model as { baseUrl?: unknown } | undefined;
+			const baseUrl = typeof model?.baseUrl === "string" ? model.baseUrl : null;
+			if (payload.targetKey !== residencyTargetKey(runtime?.runtimeId ?? "", baseUrl)) return;
+			noteColdReason("residency");
+		}) ?? null,
+		// A memory step on another endpoint disturbs nothing here, so the stamp is
+		// gated on the step having called the very server this session streams to.
+		deps.bus?.on(BusChannels.MemoryStepCompleted, (payload: MemoryStepCompletedPayload) => {
+			const target = state.runtime?.runtimeResolution.target;
+			if (target === undefined) return;
+			if (canonicalEndpointKey(target) !== payload.endpointKey) return;
+			noteColdReason("background_memory");
+		}) ?? null,
 		deps.bus?.on(BusChannels.ContextRecalled, (payload: ContextRecalledPayload) => {
 			middleware.fireCompactionHook("working_set_recall", payload.trigger);
 		}) ?? null,
@@ -322,6 +437,33 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	 * (issue #189). Null when no target is configured or it does not resolve,
 	 * and the overlay's "unknown" is then true.
 	 */
+	const rememberedLoadedContextWindow = (targetId: string, modelId: string): number | null => {
+		const session = deps.session?.current();
+		if (!session) return null;
+		return lastLoadedContextWindow(session, targetId, modelId);
+	};
+
+	/**
+	 * The prompt hash this session last recorded, for the first compile of a
+	 * resumed process. Without it a resume reports `previousHash: null`, which
+	 * reads as "there was no prompt before" when in fact there was one and it
+	 * is exactly what a reader needs to attribute the cold cache to: a layout
+	 * bump, a fragment edit, or a moved context window (issue #249).
+	 */
+	const lastRecordedPromptHash = (): string | null => {
+		if (resumedPromptHashRead) return resumedPromptHash;
+		resumedPromptHashRead = true;
+		const currentSession = deps.session?.current();
+		if (!currentSession) {
+			// No session to read; leave the lookup open for the next compile.
+			resumedPromptHashRead = false;
+			return null;
+		}
+		const records = readPromptCompileRecords(currentSession);
+		resumedPromptHash = records[records.length - 1]?.systemPromptHash ?? null;
+		return resumedPromptHash;
+	};
+
 	const resolveWindowWithoutRuntime = (): ContextWindowDetails | null => {
 		const settings = deps.getSettings();
 		const targetId = settings.orchestrator?.target?.trim();
@@ -334,6 +476,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			use: "orchestrator",
 			requireTools: false,
 			requireOutputBudget: true,
+			knownLoadedContextWindow: rememberedLoadedContextWindow(targetId, wireModelId),
 		});
 		return resolved.ok ? resolved.target.contextWindowDetails : null;
 	};
@@ -383,6 +526,29 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		return { contextWindow: 0, contextWindowSource: null, contextWindowSlots: null };
 	};
 
+	/**
+	 * Carry the reconciled anchor onto the current message list: the attested
+	 * prompt for the messages it covered, plus a chars/4 estimate of everything
+	 * appended since, plus text that has not been submitted yet. The tool
+	 * schemas and the system prompt are inside the attested figure already, so
+	 * they are not added again. Null when there is no attestation, or when the
+	 * list is shorter than the anchor covered, which means the history it
+	 * described was rewritten beneath it.
+	 */
+	const reconciledAnchoredTokens = (agentRuntime: AgentRuntime, pendingUserTokens: number): number | null => {
+		const anchor = reconciledAnchor;
+		if (!anchor) return null;
+		const messages = agentRuntime.agent.state.messages;
+		if (anchor.anchoredMessageCount > messages.length) return null;
+		let tail = 0;
+		for (let i = anchor.anchoredMessageCount; i < messages.length; i += 1) {
+			const message = messages[i];
+			if (message === undefined) continue;
+			tail += estimateAgentMessageTokens(message);
+		}
+		return anchor.tokens + tail + pendingUserTokens;
+	};
+
 	const liveContextEstimate = (agentRuntime: AgentRuntime, pendingUserText?: string): LiveContextEstimate => {
 		const contextWindow = agentRuntime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
 		const estimateInput = {
@@ -391,10 +557,34 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			tools: agentRuntime.agent.state.tools,
 			...(pendingUserText !== undefined ? { pendingUserText } : {}),
 		};
+		const breakdown = estimateAgentContextBreakdown(estimateInput);
+		const estimatedTokens = estimateAgentContextTokens(estimateInput);
+		const reconciledTokens = reconciledAnchoredTokens(agentRuntime, breakdown.pendingUserTokens);
 		return {
-			tokens: estimateAgentContextTokens(estimateInput),
+			// The estimate is a floor, not a competing verdict: it prices material
+			// the attested call never saw, so a provider count below it would be
+			// answering about a smaller conversation.
+			tokens: Math.max(estimatedTokens, reconciledTokens ?? 0),
+			estimatedTokens,
+			reconciledTokens,
 			contextWindow,
-			breakdown: estimateAgentContextBreakdown(estimateInput),
+			breakdown,
+		};
+	};
+
+	/**
+	 * A working-set projection removes tokens from messages the attestation
+	 * covered; it does not make the attestation wrong about the rest. Subtract
+	 * what the planner priced out against the same projection and re-anchor on
+	 * the refreshed list, instead of discarding the figure and falling back to
+	 * pure chars/4 exactly when the accounting matters most (issue #227).
+	 * Call after the message list has been rebuilt.
+	 */
+	const carryReconciledAnchorThroughProjection = (agentRuntime: AgentRuntime, tokensRemoved: number): void => {
+		if (!reconciledAnchor) return;
+		reconciledAnchor = {
+			tokens: Math.max(0, reconciledAnchor.tokens - Math.max(0, tokensRemoved)),
+			anchoredMessageCount: agentRuntime.agent.state.messages.length,
 		};
 	};
 
@@ -414,7 +604,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const emitCompactionActivity = (status: ContextActivityStatus, message: string): void => {
 		deps.bus?.emit(BusChannels.ContextActivity, {
 			kind: "compaction",
-			phase: "done",
+			phase: status === "completed" ? "done" : "compact",
 			status,
 			message,
 			at: Date.now(),
@@ -507,6 +697,8 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 						emitCompactionActivity("started", "compacting context (mask stage)");
 						deps.session.replaceEntries(masked.entries);
 						refreshAgentMessagesFromSession(agentRuntime);
+						// The masked history is not the one the provider counted.
+						reconciledAnchor = null;
 						deps.bus?.emit(BusChannels.CompactionEnd, { trigger, at: Date.now() });
 
 						const postMaskSnapshot = captureRuntimeContextSnapshot(
@@ -591,6 +783,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 							});
 							noteColdReason("working_set_evict");
 							refreshAgentMessagesFromSession(agentRuntime);
+							carryReconciledAnchorThroughProjection(agentRuntime, planned.tokensBefore - planned.tokensAfter);
 
 							const postEvictionSnapshot = captureRuntimeContextSnapshot(
 								agentRuntime,
@@ -683,6 +876,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		recordCompactionUsage(agentRuntime, result);
 
 		refreshAgentMessagesFromSession(agentRuntime);
+		// A summary replaces the conversation the attestation described, so no
+		// arithmetic carries it forward; the next call re-anchors it.
+		reconciledAnchor = null;
 
 		const postCompactSnapshot = captureRuntimeContextSnapshot(
 			agentRuntime,
@@ -741,6 +937,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		captureRuntimeContextSnapshot,
 		persistContextSnapshot,
 		liveContextEstimate,
+		rememberedLoadedContextWindow,
 		refreshAgentMessagesFromSession,
 		runAutoCompact,
 
@@ -754,6 +951,18 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		},
 
 		reconcileUsage(usage: Usage): void {
+			// Cached prompt tokens still occupy the window; providers report them
+			// outside `input`, so the attested prompt is the three summed.
+			const promptTokens = (usage.input || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
+			const messages = state.runtime?.agent.state.messages;
+			if (promptTokens > 0 && messages) {
+				// The output of this call is part of the next call's prompt for the
+				// same messages, which is why it is folded in here.
+				reconciledAnchor = {
+					tokens: promptTokens + (usage.output || 0),
+					anchoredMessageCount: messages.length,
+				};
+			}
 			if (!currentContextSnapshot) return;
 			// Reconcile in memory on every API call so the live meters
 			// track usage; persistence waits for the run to settle.
@@ -787,7 +996,22 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			const modelState = agentRuntime.agent.state.model as
 				| (typeof agentRuntime.agent.state.model & { clio?: { quirks?: LocalModelQuirks } })
 				| undefined;
-			const contextWindow = typeof modelState?.contextWindow === "number" ? modelState.contextWindow : null;
+			// `Context window: N` is the window the backend will actually serve
+			// this session, taken from the resolution the turn already ran rather
+			// than from the model descriptor's copy of it (issue #249). The
+			// ranking that puts a loaded figure ahead of a probed one lives in
+			// `resolveContextWindowDetails`, which tests `loadedContextWindow`
+			// first and only then `probedContextWindow`, so `effectiveContextWindow`
+			// already is the loaded window whenever one is known and the source
+			// already reads "loaded"; brief #227's carry-forward is what puts that
+			// figure in reach on a resume. The source rides into the prompt
+			// manifest, so a recompile after the loaded window is first observed
+			// is explained by the record.
+			const windowDetails = agentRuntime.runtimeResolution.contextWindowDetails;
+			const resolvedWindow = windowDetails.effectiveContextWindow;
+			const contextWindow = typeof resolvedWindow === "number" && resolvedWindow > 0 ? resolvedWindow : null;
+			const contextWindowSource: ContextWindowSource | null =
+				contextWindow === null ? null : windowDetails.contextWindowSource;
 			const guidance = modelState?.clio?.quirks?.thinking?.guidance;
 			// Per-tool prompt hints come from registry metadata, derived once from
 			// the frozen surface per compile. The compiler renders them sorted by
@@ -823,16 +1047,19 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					cwd: process.cwd(),
 					workingContextPaths: [...sessionWorkingContextPaths],
 				});
-				const previousHash = sessionPrompt?.systemPromptHash ?? null;
+				const previousHash = sessionPromptHash ?? lastRecordedPromptHash();
 				const changed = agentRuntime.agent.state.systemPrompt !== result.systemPrompt;
 				if (changed) {
 					agentRuntime.agent.state.systemPrompt = result.systemPrompt;
 					pendingPromptLogEntry = {
+						version: PROMPT_MANIFEST_VERSION,
 						at: new Date().toISOString(),
 						previousHash,
 						systemPromptHash: result.systemPromptHash,
 						tokenEstimate: result.tokenEstimate,
 						thinkingLevel: agentRuntime.agent.state.thinkingLevel ?? null,
+						contextWindow,
+						contextWindowSource,
 						projectPreload: result.projectPreload ?? null,
 						sections: result.sections.map((s) => ({ id: s.id, tokenEstimate: s.tokenEstimate })),
 						fragments: result.fragmentManifest.map((f) => ({
@@ -845,6 +1072,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				}
 				lastSystemPromptReused = !changed;
 				sessionPrompt = result;
+				sessionPromptHash = result.systemPromptHash;
 				sessionPromptKey = key;
 				return result;
 			} catch (err) {
@@ -877,6 +1105,11 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 						tokenEstimate: entry.tokenEstimate,
 					},
 				});
+				// A resumed process names the session's last recorded hash as previousHash (#249), so
+				// the stamp requires the hash to have moved, not merely to have a predecessor.
+				if (entry.previousHash !== null && entry.previousHash !== entry.systemPromptHash) {
+					noteColdReason("prompt_recompiled");
+				}
 			} catch {
 				// Ledger logging is diagnostics, not control flow; never abort a turn.
 			}
@@ -966,6 +1199,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					compactionThreshold,
 					compactionAuto,
 					promptCache: lastPromptCache,
+					prewarm: lastPrewarm,
 				});
 			}
 
@@ -998,6 +1232,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				measured,
 				lastCompaction: lastCompactionEvent,
 				promptCache: lastPromptCache,
+				prewarm: lastPrewarm,
 			});
 		},
 
@@ -1007,12 +1242,14 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			deps.bus?.emit(BusChannels.ContextWarning, { warning } satisfies ContextWarningPayload);
 		},
 
+		noteColdReason,
+
 		consumeExpectedColdReasons(runtimeId: string): void {
 			// Cache-disturbance honesty (T3.3): consume disturbances since
 			// the last settled run. Only single-slot local backends lose their
-			// prefix cache to interleaved work, so dispatch and compaction
-			// stamp only on local-native targets; a working-set eviction moved
-			// the prefix itself and stamps on every tier (see stampsOnTier).
+			// prefix cache to interleaved work, so residency, thinking changes,
+			// dispatch, and compaction stamp only on local-native targets. Reasons
+			// that change the prefix bytes stamp every tier (see stampsOnTier).
 			runExpectedColdReasons = [];
 			nextAssistantColdReasons = [];
 			if (pendingColdReasons.size > 0) {
@@ -1026,10 +1263,10 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			}
 		},
 
-		promptCachePayloadForAssistant(usage: Usage): Record<string, unknown> {
-			// Per-call prompt-cache record (T3.2): provider-reported numbers only,
-			// classified by backendCacheVerdict in chat-loop-messages.ts. The
-			// run's first persisted call also carries any expected-cold reasons.
+		promptCachePayloadForAssistant(usage: Usage, backend?: BackendCompletionTimings): Record<string, unknown> {
+			// Per-call prompt-cache record (T3.2) keeps normalized provider usage
+			// beside any timings captured from the server response. The run's first
+			// persisted call also carries any expected-cold reasons.
 			const input = typeof usage.input === "number" ? usage.input : 0;
 			const cacheRead = typeof usage.cacheRead === "number" ? usage.cacheRead : 0;
 			const cacheWrite = typeof usage.cacheWrite === "number" ? usage.cacheWrite : 0;
@@ -1037,8 +1274,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				input,
 				cacheRead,
 				cacheWrite,
-				backendVerdict: backendCacheVerdict(input, cacheRead),
+				backendVerdict: backendCacheVerdict(input, cacheRead, backend),
 			};
+			if (backend !== undefined) promptCache.backend = { ...backend };
 			if (nextAssistantColdReasons.length > 0) {
 				promptCache.expectedColdReasons = [...nextAssistantColdReasons];
 				nextAssistantColdReasons = [];
@@ -1046,14 +1284,30 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			return promptCache;
 		},
 
+		notePrewarm(prewarm: PrewarmStats): void {
+			lastPrewarm = prewarm;
+		},
+
 		noteRunCacheSummary(messages, runFirstCallVerdict): void {
+			// The settled run is the answer to the pre-warm's question, so the
+			// pre-warm line stops being the newest fact about the prefix here.
+			lastPrewarm = null;
 			const cacheSummary = sumRunUsage(messages);
 			if (cacheSummary.hadUsage) {
+				let lastBackend: BackendCompletionTimings | null = null;
+				for (let index = messages.length - 1; index >= 0; index -= 1) {
+					const message = messages[index];
+					if (message?.role !== "assistant") continue;
+					lastBackend = (message as { backendTimings?: BackendCompletionTimings }).backendTimings ?? null;
+					break;
+				}
 				lastPromptCache = {
 					shellReused: lastSystemPromptReused,
 					cacheReadTokens: cacheSummary.cacheRead > 0 || cacheSummary.cacheWrite > 0 ? cacheSummary.cacheRead : null,
 					cacheWriteTokens: cacheSummary.cacheRead > 0 || cacheSummary.cacheWrite > 0 ? cacheSummary.cacheWrite : null,
 					uncachedInputTokens: cacheSummary.input,
+					backend: lastBackend,
+					uncachedPrefillTokens: uncachedPrefillTokens(lastBackend),
 					backendVerdict: runFirstCallVerdict,
 					...(runExpectedColdReasons.length > 0 ? { expectedColdReasons: [...runExpectedColdReasons] } : {}),
 				};
@@ -1061,12 +1315,26 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		},
 
 		resetForSession(): void {
+			// An in-process switch replaces the whole prefix: the backend's slot
+			// still holds the outgoing session's prompt and history, so the first
+			// turn on the incoming one is expected-cold on every tier, exactly as
+			// a recompile is. The manifest can no longer say so on its own once
+			// provenance follows the session, because the incoming session's last
+			// recorded hash usually equals its fresh compile, so the stamp comes
+			// from here. Only when this process had actually applied a prompt:
+			// before the first compile there is nothing in the slot to have lost.
+			if (sessionPromptHash !== null) noteColdReason("prompt_recompiled");
 			lastPromptCache = null;
+			lastPrewarm = null;
 			lastSystemPromptReused = false;
+			sessionPromptHash = null;
 			sessionPromptKey = null;
+			resumedPromptHashRead = false;
+			resumedPromptHash = null;
 			sessionWorkingContextPaths.clear();
 			pendingPromptLogEntry = null;
 			emptyAutoCompactTurnId = null;
+			reconciledAnchor = null;
 			const session = deps.session?.current();
 			currentContextSnapshot = session ? getLatestContextSnapshot(session) : null;
 		},

package/src/interactive/turn-persistence.ts

@@ -5,6 +5,7 @@
  * append advances `state.lastTurnId`.
  */
 
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import type { ClioSettings } from "../core/config.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
@@ -39,7 +40,7 @@ export interface TurnPersistenceDeps {
 	/** Remove a queued-mirror entry once the engine injects it. */
 	removeQueuedMirrorEntry: (text: string) => void;
 	/** Prompt-cache record for a persisted assistant call (T3.2 + cold stamp). */
-	promptCachePayloadForAssistant: (usage: Usage) => Record<string, unknown>;
+	promptCachePayloadForAssistant: (usage: Usage, backend?: BackendCompletionTimings) => Record<string, unknown>;
 	/**
 	 * Prompt-side tokens the live context accounting holds for the turn in
 	 * flight. Used only to record what an interrupted call is known to have
@@ -228,7 +229,8 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		if (timing) payload.timing = timing;
 		const usage = (message as { usage?: Usage }).usage;
 		if (usage && typeof usage === "object") {
-			payload.promptCache = deps.promptCachePayloadForAssistant(usage);
+			const backendTimings = (message as { backendTimings?: BackendCompletionTimings }).backendTimings;
+			payload.promptCache = deps.promptCachePayloadForAssistant(usage, backendTimings);
 		}
 		// A cancelled turn's provider usage is the object the stream started with
 		// and never updated. Record what the call is known to have spent instead of
@@ -278,8 +280,16 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 
 		appendQueuedUserTurn(message: AgentMessage): void {
 			if (message?.role !== "user") return;
-			const text = extractUserText(message).trim();
-			if (text.length === 0) return;
+			// Byte-exact. Trimming here wrote a second, shortened row that the
+			// assistant then parented to, so the model's parent turn disagreed with
+			// the expansion the operator actually submitted: `/raw   bar` produced a
+			// correct 5-byte row and a 3-byte one, and the 3-byte one won (issue
+			// #244). Only the emptiness test reads the trimmed form, and the
+			// echo/mirror lookups match on the same bytes the engine was given, so a
+			// payload with edge whitespace is recognized as the echo it is instead
+			// of being persisted a second time.
+			const text = extractUserText(message);
+			if (text.trim().length === 0) return;
 			if (deps.consumePersistedEcho(text)) return;
 			deps.removeQueuedMirrorEntry(text);
 			if (!deps.session) return;