@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/turn-context.ts

@@ -12,12 +12,21 @@ 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";
+import { isTurnStart } from "../domains/context/working-set/horizon.js";
 import { resolveWorkingSetPolicy } from "../domains/context/working-set/policies/index.js";
 import { selectVisibleEntries } from "../domains/context/working-set/visible.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
@@ -26,6 +35,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 +60,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,
@@ -69,7 +90,7 @@ import {
 	toolNamesFromAgentState,
 } from "./chat-loop-messages.js";
 import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
-import { renderCompactionSummaryLine } from "./renderers/compaction-summary.js";
+import { renderCompactionSummaryLine, renderEvictionSkipLine } from "./renderers/compaction-summary.js";
 import type { TurnMiddleware } from "./turn-middleware.js";
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
 
@@ -92,11 +113,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 +173,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,27 +201,74 @@ 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;
 }
 
+/**
+ * Why the working-set stage declined, said in the terms the operator can act
+ * on. The two cases are worth separating: a session whose every turn is inside
+ * `protectLastTurns` was never offered a candidate, while a longer one was
+ * offered candidates the policy refused. The first is the shape smoke pass 2
+ * found (G1), and the setting it names is the one that changes it.
+ */
+function evictionSkipMessage(
+	visibleEntries: ReadonlyArray<SessionEntry>,
+	workingSet: Readonly<{ protectLastTurns: number; policy: string }>,
+	policyId: string,
+): string {
+	const turns = visibleEntries.filter(isTurnStart).length;
+	return renderEvictionSkipLine({
+		reason: turns <= workingSet.protectLastTurns ? "all-protected" : "nothing-evictable",
+		turns,
+		protectLastTurns: workingSet.protectLastTurns,
+		policyId,
+	});
+}
+
 export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const { state, middleware } = deps;
 	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 +276,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 +297,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 +339,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 +459,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 +498,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 +548,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 +579,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 +626,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(),
@@ -471,6 +683,12 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		const autoEnabled = cfg?.auto !== false;
 		if (!force && !autoEnabled) return false;
 		let preSummaryStageActed = false;
+		// G1 from smoke pass 2: a short session generates all its pressure inside
+		// the protection window, the non-destructive layer finds nothing, and the
+		// destructive summary ran with nothing in the transcript saying eviction
+		// was considered and declined. Held here and emitted only if a summary
+		// actually follows.
+		let evictionSkipNotice: string | null = null;
 		const rememberEmptyAutomaticAttempt = (): void => {
 			if (!force && !preSummaryStageActed && activeAutoTurnId) emptyAutoCompactTurnId = activeAutoTurnId;
 		};
@@ -507,6 +725,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(
@@ -551,12 +771,16 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					}
 				} else if (settings.context.workingSet.enabled) {
 					let planned: ReturnType<typeof planEviction>;
+					let visibleEntries: ReadonlyArray<SessionEntry> = [];
+					let policyId = settings.context.workingSet.policy;
 					try {
 						const entries = deps.readSessionEntries() ?? [];
 						const view = foldWorkingSet(entries, state.lastTurnId ?? undefined);
 						const policy = resolveWorkingSetPolicy(settings.context.workingSet.policy);
+						policyId = policy.id;
+						visibleEntries = selectVisibleEntries(entries, state.lastTurnId ?? undefined);
 						planned = (deps.planEviction ?? planEviction)(policy, {
-							entries: selectVisibleEntries(entries, state.lastTurnId ?? undefined),
+							entries: visibleEntries,
 							view,
 							cwd: deps.session.current()?.cwd ?? null,
 							settings: settings.context.workingSet,
@@ -591,6 +815,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 							});
 							noteColdReason("working_set_evict");
 							refreshAgentMessagesFromSession(agentRuntime);
+							carryReconciledAnchorThroughProjection(agentRuntime, planned.tokensBefore - planned.tokensAfter);
 
 							const postEvictionSnapshot = captureRuntimeContextSnapshot(
 								agentRuntime,
@@ -637,7 +862,16 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 							emitCompactionActivity("failed", compactionFailureMessage(error));
 							throw error;
 						}
+					} else {
+						evictionSkipNotice = evictionSkipMessage(visibleEntries, settings.context.workingSet, policyId);
 					}
+				} else {
+					evictionSkipNotice = renderEvictionSkipLine({
+						reason: "disabled",
+						turns: 0,
+						protectLastTurns: settings.context.workingSet.protectLastTurns,
+						policyId: settings.context.workingSet.policy,
+					});
 				}
 			}
 		}
@@ -654,6 +888,10 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			summaryLifecycleStarted = true;
 		};
 		if (force) startSummaryLifecycle();
+		// Said before the summary call, not after it: the operator is about to wait
+		// on a destructive stage, and the reason the cheap one was skipped is only
+		// useful ahead of it.
+		if (evictionSkipNotice) deps.emitNotice(evictionSkipNotice);
 		let result: CompactResult | null = null;
 		const beforeSnapshotId = currentContextSnapshot?.snapshotId ?? null;
 		try {
@@ -683,6 +921,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 +982,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		captureRuntimeContextSnapshot,
 		persistContextSnapshot,
 		liveContextEstimate,
+		rememberedLoadedContextWindow,
 		refreshAgentMessagesFromSession,
 		runAutoCompact,
 
@@ -754,6 +996,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 +1041,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 +1092,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 +1117,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				}
 				lastSystemPromptReused = !changed;
 				sessionPrompt = result;
+				sessionPromptHash = result.systemPromptHash;
 				sessionPromptKey = key;
 				return result;
 			} catch (err) {
@@ -877,6 +1150,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 +1244,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 					compactionThreshold,
 					compactionAuto,
 					promptCache: lastPromptCache,
+					prewarm: lastPrewarm,
 				});
 			}
 
@@ -998,6 +1277,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 				measured,
 				lastCompaction: lastCompactionEvent,
 				promptCache: lastPromptCache,
+				prewarm: lastPrewarm,
 			});
 		},
 
@@ -1007,12 +1287,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 +1308,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 +1319,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 +1329,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 +1360,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;
 		},