@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/session/prompt-manifest.ts

@@ -14,6 +14,21 @@ import type { SessionMeta } from "./contract.js";
  * stay diffable without recompiling anything.
  */
 
+/**
+ * Layout version of the compiled prompt these records describe.
+ *
+ * 1: the order shipped through 0.3.8.
+ * 2: stable-prefix-first ordering with one `# Memory` header, and
+ *    `contextWindowSource` recorded alongside the window the prompt states
+ *    (issue #249).
+ *
+ * A record without a `version` field predates the field and is read as 1, so a
+ * 0.3.8 manifest still parses. Bump this whenever the compiled text moves for a
+ * reason other than its inputs: a resumed session then has the version in hand
+ * to explain the one `promptRecompiled` entry its first compile writes.
+ */
+export const PROMPT_MANIFEST_VERSION = 2;
+
 export interface PromptManifestSection {
 	id: string;
 	tokenEstimate: number;
@@ -27,6 +42,8 @@ export interface PromptManifestFragment {
 }
 
 export interface SessionPromptCompileRecord {
+	/** Prompt layout version; see `PROMPT_MANIFEST_VERSION`. Absent on pre-0.3.9 records. */
+	version?: number;
 	/** ISO timestamp of the compile. */
 	at: string;
 	/** Hash of the previously served prompt, null on the first compile. */
@@ -35,6 +52,14 @@ export interface SessionPromptCompileRecord {
 	tokenEstimate: number;
 	/** Thinking dial applied to the live agent when this prompt was compiled. */
 	thinkingLevel: string | null;
+	/**
+	 * The window the prompt's `Context window: N` states, and the layer that
+	 * answered it. `loaded` is what the backend has this model open at; anything
+	 * else means the figure can still move once a loaded window is observed, and
+	 * a later recompile is then explained rather than mysterious.
+	 */
+	contextWindow?: number | null;
+	contextWindowSource?: string | null;
 	projectPreload: ProjectPreloadClass | null;
 	sections: PromptManifestSection[];
 	fragments: PromptManifestFragment[];
@@ -102,9 +127,21 @@ function isProjectPreloadClass(value: unknown): value is ProjectPreloadClass {
 	);
 }
 
+/** Optional fields added after 0.3.8: absent is valid, present must be well-typed. */
+function isOptional<T>(value: unknown, guard: (candidate: unknown) => candidate is T): boolean {
+	return value === undefined || guard(value);
+}
+
 function isSessionPromptCompileRecord(value: unknown): value is SessionPromptCompileRecord {
 	if (!isRecord(value)) return false;
 	return (
+		isOptional(value.version, isNonNegativeInteger) &&
+		isOptional(value.contextWindow, (candidate): candidate is number | null =>
+			candidate === null ? true : isNonNegativeInteger(candidate),
+		) &&
+		isOptional(value.contextWindowSource, (candidate): candidate is string | null =>
+			candidate === null ? true : typeof candidate === "string",
+		) &&
 		isCanonicalUtcTimestamp(value.at) &&
 		(value.previousHash === null || isSha256(value.previousHash)) &&
 		isSha256(value.systemPromptHash) &&
@@ -118,6 +155,11 @@ function isSessionPromptCompileRecord(value: unknown): value is SessionPromptCom
 	);
 }
 
+/** A record written before the field existed describes the 0.3.8 layout. */
+export function promptManifestVersion(record: SessionPromptCompileRecord): number {
+	return record.version ?? 1;
+}
+
 export function getPromptManifestFilePath(meta: SessionMeta, stateDir?: string): string {
 	const safeMeta = {
 		...meta,

package/src/engine/acp/adapter.ts

@@ -1,8 +1,10 @@
+import { performance } from "node:perf_hooks";
 import {
 	DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS,
 	DEFAULT_DELEGATION_TURN_TIMEOUT_MS,
 	type DelegationAgentConfig,
 } from "../../core/defaults.js";
+import type { HeartbeatStamp } from "../../domains/dispatch/heartbeat.js";
 import type { AutonomyLevel } from "../../domains/safety/autonomy.js";
 import type { SafetyContract } from "../../domains/safety/contract.js";
 import type { AgentEvent } from "../types.js";
@@ -40,6 +42,10 @@ export interface AcpDelegationRunInput {
 	terminationWaitMs?: number;
 	/** Grace for session/cancel before abort escalates into hard termination. */
 	cancelGraceMs?: number;
+	/** Wall clock for the persisted heartbeat anchor. */
+	now?: () => number;
+	/** Monotonic clock for event-inactivity spans. */
+	monotonicNow?: () => number;
 }
 
 export interface AcpDelegationRunHandle {
@@ -54,7 +60,7 @@ export interface AcpDelegationRunHandle {
 	 * final observation bound expires.
 	 */
 	kill(): void;
-	heartbeatAt: { current: number };
+	heartbeatAt: HeartbeatStamp;
 	toolCallLog(): ReturnType<AcpToolMediator["snapshot"]>["toolCallLog"];
 }
 
@@ -176,7 +182,14 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 	// peer into an unbounded request.
 	const connectTimeoutMs = input.agent.connectTimeoutMs ?? DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS;
 	const turnTimeoutMs = input.agent.turnTimeoutMs ?? DEFAULT_DELEGATION_TURN_TIMEOUT_MS;
-	const heartbeatAt = { current: Date.now() };
+	const now = input.now ?? Date.now;
+	const monotonicNow = input.monotonicNow ?? (() => performance.now());
+	const heartbeatWallAnchor = now();
+	const heartbeatMonotonicAnchor = monotonicNow();
+	const heartbeatAt: HeartbeatStamp = {
+		current: heartbeatWallAnchor,
+		monotonic: heartbeatMonotonicAnchor,
+	};
 	const queue = new AsyncEventQueue<AcpRunEvent>();
 	const usage = emptyUsage();
 	const mapper = new AcpEventMapper();
@@ -202,7 +215,9 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 		cancelTimer = null;
 	};
 	const emit = (event: AcpRunEvent): void => {
-		heartbeatAt.current = Date.now();
+		const stamp = monotonicNow();
+		heartbeatAt.monotonic = stamp;
+		heartbeatAt.current = heartbeatWallAnchor + (stamp - heartbeatMonotonicAnchor);
 		queue.push(event);
 	};
 	const mediator = new AcpToolMediator({

package/src/engine/ai.ts

@@ -27,9 +27,11 @@ import {
 	type ToolCall,
 	type Usage,
 } from "@earendil-works/pi-ai";
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
 import {
 	completeEngineSimple,
 	engineStream,
+	engineStreamSimple,
 	registerEngineBuiltins,
 	registerEngineFauxProvider,
 } from "./api-registry.js";
@@ -40,6 +42,14 @@ export { StringEnum };
 
 export const stream = engineStream;
 
+/**
+ * The dispatcher a turn runs on. `createEngineAgent` hands this to pi-agent-core
+ * as its `streamFn`, so a caller that needs a request byte-identical to the one
+ * the next turn would send (the session pre-warm) sends it through here rather
+ * than through `stream`, whose bare-call path has to guess a thinking level.
+ */
+export const streamSimple = engineStreamSimple;
+
 export interface EngineTextCompletionInput {
 	model: EngineModel;
 	systemPrompt: string;
@@ -55,6 +65,21 @@ export interface EngineTextCompletionResult {
 	text: string;
 	inputTokens: number;
 	outputTokens: number;
+	/**
+	 * The provider's full usage record for the call, so a caller that has to
+	 * account for the spend does not have to re-derive it from two token counts.
+	 */
+	usage: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		reasoning: number;
+		totalTokens: number;
+		costUsd: number;
+	};
+	/** Backend prefill and prediction facts when the serving runtime reported them. */
+	backend: BackendCompletionTimings | null;
 }
 
 /** Run one tool-free completion while keeping pi message types at the engine boundary. */
@@ -83,6 +108,16 @@ export async function completeEngineText(input: EngineTextCompletionInput): Prom
 			.join(""),
 		inputTokens: response.usage.input,
 		outputTokens: response.usage.output,
+		usage: {
+			input: response.usage.input,
+			output: response.usage.output,
+			cacheRead: response.usage.cacheRead,
+			cacheWrite: response.usage.cacheWrite,
+			reasoning: response.usage.reasoning ?? 0,
+			totalTokens: response.usage.totalTokens,
+			costUsd: response.usage.cost.total,
+		},
+		backend: response.backendTimings ?? null,
 	};
 }
 

package/src/engine/apis/llamacpp-residency.ts

@@ -1,4 +1,5 @@
 import { performance } from "node:perf_hooks";
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import { sleep } from "../../core/timers.js";
 import {
 	type ResidencyAdapter,
@@ -169,6 +170,26 @@ async function fetchRouterModels(
 	return parseRouterModels(await response.json());
 }
 
+class RouterModelPostError extends Error {
+	constructor(
+		readonly url: string,
+		readonly status: number,
+		readonly responseBody: string,
+	) {
+		super(`llama.cpp router rejected ${url}: HTTP ${status}; response: ${responseBody}`);
+		this.name = "RouterModelPostError";
+	}
+}
+
+async function routerErrorBody(response: Response): Promise<string> {
+	try {
+		const body = (await response.text()).trim();
+		return body.length > 0 ? body : "<empty body>";
+	} catch (error) {
+		return `<unreadable body: ${error instanceof Error ? error.message : String(error)}>`;
+	}
+}
+
 async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: string): Promise<void> {
 	const response = await fetchImpl(url, {
 		method: "POST",
@@ -177,7 +198,38 @@ async function postRouterModel(fetchImpl: typeof fetch, url: string, modelId: st
 		signal: AbortSignal.timeout(LOAD_TIMEOUT_MS),
 	});
 	if (response.ok) return;
-	throw new Error(`llama.cpp router rejected ${url}: HTTP ${response.status}`);
+	throw new RouterModelPostError(url, response.status, await routerErrorBody(response));
+}
+
+function alreadyRunningResponse(body: string): boolean {
+	return body.toLowerCase().includes("already running");
+}
+
+/**
+ * A router wake and Clio's explicit load can cross between the listing and the
+ * POST. In that race the router rejects the duplicate request even though the
+ * requested model now owns a resident slot. Re-read the authoritative listing
+ * before treating a non-2xx as a load failure; only a definitively absent,
+ * unloaded, or failed model preserves the rejection.
+ */
+async function postRouterLoad(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
+	try {
+		await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	} catch (error) {
+		if (!(error instanceof RouterModelPostError)) throw error;
+		let model: LlamaCppRouterModel | undefined;
+		try {
+			model = (await fetchRouterModels(input, fetchImpl)).find((entry) => entry.id === modelId);
+		} catch {
+			// The router's explicit "already running" answer is sufficient even if
+			// the confirming snapshot itself races or is temporarily unavailable.
+			if (alreadyRunningResponse(error.responseBody)) return;
+			throw error;
+		}
+		if (alreadyRunningResponse(error.responseBody)) return;
+		if (model !== undefined && model.state !== "unloaded" && model.state !== "failed") return;
+		throw error;
+	}
 }
 
 async function waitForLoaded(input: LlamaCppResidencyInput, fetchImpl: typeof fetch, modelId: string): Promise<void> {
@@ -206,7 +258,7 @@ async function ensureModelLoaded(
 	// router answers `400 model is already running`, which fails the turn before
 	// it reaches the model.
 	if (knownState === "loaded" || knownState === "sleeping") return;
-	if (knownState !== "loading") await postRouterModel(fetchImpl, loadUrl(input.baseUrl), modelId);
+	if (knownState !== "loading") await postRouterLoad(input, fetchImpl, modelId);
 	await waitForLoaded(input, fetchImpl, modelId);
 }
 
@@ -246,7 +298,7 @@ export async function ensureLlamaCppResidency(input: LlamaCppResidencyInput): Pr
 	const fetchImpl = input.fetchImpl ?? fetch;
 	let snapshot: LlamaCppRouterModel[] = [];
 	const adapter: ResidencyAdapter = {
-		targetKey: `llamacpp|${input.baseUrl}`,
+		targetKey: residencyTargetKey("llamacpp", input.baseUrl),
 		targetId: input.targetId,
 		runtimeId: input.runtimeId,
 		keepModelId: input.keepModelId,

package/src/engine/apis/lmstudio.ts

@@ -1,5 +1,6 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import {
 	type LmStudioCatalog,
 	type LmStudioLoadedInstance,
@@ -11,7 +12,7 @@ import {
 } from "../../domains/providers/runtimes/common/lmstudio-http.js";
 import type { TargetDescriptor } from "../../domains/providers/types/target-descriptor.js";
 import { coResidentContextCeiling, fitLoadContextLength } from "./lmstudio-residency.js";
-import { emitResidencyNotice, reconcileResidency, residencyManagedFor } from "./residency.js";
+import { emitResidencyMutation, emitResidencyNotice, reconcileResidency, residencyManagedFor } from "./residency.js";
 import { withResidencyLock } from "./residency-lock.js";
 
 interface LmStudioModelMetadata {
@@ -205,7 +206,7 @@ export async function ensureLmStudioResidency(
 		entry.loadedInstances.map((instance) => ({ modelKey: entry.key, identifier: instance.id, instance })),
 	);
 	const managed = residencyManagedFor(info.lifecycle);
-	const targetKey = `lmstudio|${lmStudioRootUrl(target.url ?? model.baseUrl)}`;
+	const targetKey = residencyTargetKey("lmstudio", target.url ?? model.baseUrl);
 	const contextLength = target.lmstudio?.load?.contextLength;
 	const plan = await reconcileResidency({
 		targetKey,
@@ -248,17 +249,36 @@ export async function ensureLmStudioResidency(
 			});
 		}
 	}
+	const loadAndReport = async (): Promise<string> => {
+		const instanceId = await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal);
+		emitResidencyMutation({
+			targetKey,
+			targetId: info.targetId,
+			runtimeId: "lmstudio",
+			model: modelKey,
+			operation: "load",
+		});
+		return instanceId ?? model.id;
+	};
 	try {
-		return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+		return await loadAndReport();
 	} catch (error) {
 		if (plan.decision === "observe" || plan.fallbackEvict.length === 0) throw error;
 		return withResidencyLock(targetKey, async () => {
 			for (const candidate of plan.fallbackEvict) {
 				for (const entry of instances.filter((resident) => resident.modelKey === candidate.modelId)) {
-					await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal);
+					if (await unloadOwnedInstance(target, targetKey, entry.identifier, options.apiKey, options.signal)) {
+						emitResidencyMutation({
+							targetKey,
+							targetId: info.targetId,
+							runtimeId: "lmstudio",
+							model: candidate.modelId,
+							operation: "evict",
+						});
+					}
 				}
 			}
-			return (await loadOwnedInstance(target, targetKey, body, options.apiKey, options.signal)) ?? model.id;
+			return loadAndReport();
 		});
 	}
 }

package/src/engine/apis/ollama-native.ts

@@ -24,6 +24,7 @@ import {
 	type Tool as OllamaTool,
 	type ToolCall as OllamaToolCall,
 } from "ollama";
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import {
 	type AppliedThinking,
 	resolveModelRuntimeCapabilitiesForModel,
@@ -75,7 +76,7 @@ async function reconcileOllamaResidency(model: Model<"ollama-native">, headers:
 	if (!baseUrl) return;
 	const metadata = (model as Model<"ollama-native"> & ClioRuntimeMetadata).clio;
 	const adapter: ResidencyAdapter = {
-		targetKey: `ollama-native|${baseUrl}`,
+		targetKey: residencyTargetKey("ollama-native", baseUrl),
 		targetId: ollamaTargetId(model),
 		runtimeId: "ollama-native",
 		keepModelId: model.id,

package/src/engine/apis/openai-completions.ts

@@ -16,6 +16,7 @@ import {
 	type Usage,
 } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import type { BackendCompletionTimings, BackendTimingsSource } from "../../core/cache-telemetry.js";
 import type { ResponseModelIdObservation } from "../../core/response-model-id.js";
 import {
 	type AppliedThinking,
@@ -41,6 +42,8 @@ declare module "@earendil-works/pi-ai" {
 	interface AssistantMessage {
 		/** Direct observation of model-id presence in an OpenAI-compatible response. */
 		responseModelIdObservation?: ResponseModelIdObservation;
+		/** Backend-reported prefill and prediction timings when available. */
+		backendTimings?: BackendCompletionTimings;
 	}
 }
 
@@ -95,13 +98,57 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
 interface ResponseModelIdCapture {
 	reportedModelId: string | null;
 	observed: boolean;
-	done: boolean;
+	modelIdDone: boolean;
+	backendTimings: BackendCompletionTimings | null;
+	backendTimingsSource: BackendTimingsSource | null;
 	buffer: string;
 	decoder: TextDecoder | null;
 }
 
-function observeResponseModelIdLine(line: string, capture: ResponseModelIdCapture): void {
-	if (capture.done) return;
+function nonnegativeFiniteNumber(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * The operator's llama.cpp router reported build b226-2115b73d8. Its nonstream
+ * response placed a `{ prompt_n, prompt_ms, predicted_n, predicted_ms, cache_n }`
+ * timing object at the top level. Its stream placed the timing object on the
+ * final SSE JSON event without `timings_per_token`. Setting
+ * `timings_per_token: true` repeated cumulative timing objects for individual
+ * tokens. LM Studio's OpenAI-compatible stream and nonstream responses omitted
+ * timings both with and without that flag. Its native runtime reported
+ * llama.cpp-win-x86_64-nvidia-cuda12-avx2 2.29.0.
+ */
+function backendCompletionTimings(value: unknown, source: BackendTimingsSource): BackendCompletionTimings | null {
+	if (!isPlainRecord(value)) return null;
+	const promptN = nonnegativeFiniteNumber(value.prompt_n);
+	const predictedN = nonnegativeFiniteNumber(value.predicted_n);
+	const promptMs = nonnegativeFiniteNumber(value.prompt_ms);
+	const predictedMs = nonnegativeFiniteNumber(value.predicted_ms);
+	if (promptN === null || predictedN === null || promptMs === null || predictedMs === null) return null;
+	const cacheN = nonnegativeFiniteNumber(value.cache_n);
+	return {
+		promptTokens: promptN + (cacheN ?? 0),
+		cachedTokens: cacheN,
+		predictedTokens: predictedN,
+		promptMs,
+		predictedMs,
+		source,
+	};
+}
+
+function backendTimingsSourceForModel(model: Model<Api>): BackendTimingsSource | null {
+	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clio;
+	if (model.provider === "llamacpp" && metadata?.runtimeId === "llamacpp") return "llamacpp-timings";
+	if (model.provider === "lmstudio" && metadata?.runtimeId === "lmstudio") return "lmstudio-timings";
+	return null;
+}
+
+function captureCanStopEarly(capture: ResponseModelIdCapture): boolean {
+	return capture.modelIdDone && capture.backendTimingsSource === null;
+}
+
+function observeResponseMetadataLine(line: string, capture: ResponseModelIdCapture): void {
 	const normalized = line.endsWith("\r") ? line.slice(0, -1) : line;
 	if (!normalized.startsWith("data:")) return;
 	const data = normalized.slice("data:".length).trimStart();
@@ -109,10 +156,16 @@ function observeResponseModelIdLine(line: string, capture: ResponseModelIdCaptur
 	try {
 		const payload = JSON.parse(data) as unknown;
 		if (!isPlainRecord(payload)) return;
-		const model = payload.model;
-		if (typeof model === "string" && model.trim().length > 0) {
-			capture.reportedModelId = model.trim();
-			capture.done = true;
+		if (!capture.modelIdDone) {
+			const model = payload.model;
+			if (typeof model === "string" && model.trim().length > 0) {
+				capture.reportedModelId = model.trim();
+				capture.modelIdDone = true;
+			}
+		}
+		if (capture.backendTimingsSource !== null) {
+			const timings = backendCompletionTimings(payload.timings, capture.backendTimingsSource);
+			if (timings !== null) capture.backendTimings = timings;
 		}
 	} catch {
 		// A partial or vendor-specific event is pi-ai's parsing concern. This
@@ -125,14 +178,14 @@ function observeResponseModelIdBytes(
 	capture: ResponseModelIdCapture,
 	flush = false,
 ): void {
-	if (capture.done || !capture.decoder) return;
+	if (!capture.decoder) return;
 	capture.buffer += chunk ? capture.decoder.decode(chunk, { stream: !flush }) : capture.decoder.decode();
 	let newline = capture.buffer.indexOf("\n");
 	while (newline >= 0) {
 		const line = capture.buffer.slice(0, newline);
 		capture.buffer = capture.buffer.slice(newline + 1);
-		observeResponseModelIdLine(line, capture);
-		if (capture.done) {
+		observeResponseMetadataLine(line, capture);
+		if (captureCanStopEarly(capture)) {
 			capture.buffer = "";
 			capture.decoder = null;
 			return;
@@ -140,10 +193,10 @@ function observeResponseModelIdBytes(
 		newline = capture.buffer.indexOf("\n");
 	}
 	if (flush && capture.buffer.length > 0) {
-		observeResponseModelIdLine(capture.buffer, capture);
+		observeResponseMetadataLine(capture.buffer, capture);
 		capture.buffer = "";
 	}
-	if (capture.done || flush) capture.decoder = null;
+	if (captureCanStopEarly(capture) || flush) capture.decoder = null;
 }
 
 function captureResponseModelId(response: Response, capture: ResponseModelIdCapture): Response {
@@ -154,12 +207,12 @@ function captureResponseModelId(response: Response, capture: ResponseModelIdCapt
 		new TransformStream<Uint8Array, Uint8Array>({
 			transform(chunk, controller) {
 				capture.observed = true;
-				if (!capture.done) observeResponseModelIdBytes(chunk, capture);
+				observeResponseModelIdBytes(chunk, capture);
 				controller.enqueue(chunk);
 			},
 			flush() {
 				capture.observed = true;
-				if (!capture.done) observeResponseModelIdBytes(undefined, capture, true);
+				observeResponseModelIdBytes(undefined, capture, true);
 			},
 		}),
 	);
@@ -171,13 +224,16 @@ function captureResponseModelId(response: Response, capture: ResponseModelIdCapt
 }
 
 function withResponseModelIdCapture<TOptions extends StreamOptions>(
+	model: Model<Api>,
 	options: TOptions,
 	sourceFactory: (capturedOptions: TOptions) => AssistantMessageEventStream,
 ): AssistantMessageEventStream {
 	const capture: ResponseModelIdCapture = {
 		reportedModelId: null,
 		observed: false,
-		done: false,
+		modelIdDone: false,
+		backendTimings: null,
+		backendTimingsSource: backendTimingsSourceForModel(model),
 		buffer: "",
 		decoder: new TextDecoder(),
 	};
@@ -197,8 +253,13 @@ function withResponseModelIdCapture<TOptions extends StreamOptions>(
 						? { state: "not-reported" }
 						: { state: "reported", reportedModelId: capture.reportedModelId }
 					: { state: "not-observed" };
-				if (event.type === "done") event.message.responseModelIdObservation = observation;
-				else if (event.type === "error") event.error.responseModelIdObservation = observation;
+				if (event.type === "done") {
+					event.message.responseModelIdObservation = observation;
+					if (capture.backendTimings !== null) event.message.backendTimings = capture.backendTimings;
+				} else if (event.type === "error") {
+					event.error.responseModelIdObservation = observation;
+					if (capture.backendTimings !== null) event.error.backendTimings = capture.backendTimings;
+				}
 				annotated.push(event as AssistantMessageEvent);
 			}
 			annotated.end();
@@ -863,6 +924,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
 							withResponseModelIdCapture(
+								model,
 								withRemainingContextBudget(model, effectiveContext, withSamplers),
 								(capturedOptions) =>
 									withLocalResidency(
@@ -895,6 +957,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 					stripNeverReasoningFromStream(
 						filterGemmaChannelStream(
 							withResponseModelIdCapture(
+								model,
 								withRemainingContextBudget(model, effectiveContext, withSamplers),
 								(capturedOptions) =>
 									withLocalResidency(

package/src/engine/apis/residency-lock.ts

@@ -12,12 +12,14 @@
 import { join } from "node:path";
 import { withStateFileLock } from "../../core/state-file-lock.js";
 import { clioStatePath } from "../../core/xdg.js";
+import { canonicalEndpointKey } from "../../domains/providers/endpoint-capacity.js";
 
 /** Total time one process waits for another's mutation before proceeding unlocked. */
 const LOCK_WAIT_MS = 120_000;
 
 function lockTargetFor(targetKey: string): string {
-	return join(clioStatePath(), "residency-locks", targetKey.replace(/[^a-zA-Z0-9._-]+/g, "_"));
+	const key = canonicalEndpointKey(targetKey) ?? targetKey;
+	return join(clioStatePath(), "residency-locks", key.replace(/[^a-zA-Z0-9._-]+/g, "_"));
 }
 
 /** Run `fn` while holding the per-target residency lock. */

package/src/engine/apis/residency.ts

@@ -35,7 +35,12 @@
  * unload/load against the same server.
  */
 
-import { BusChannels, type RuntimeNoticeKind, type RuntimeNoticePayload } from "../../core/bus-events.js";
+import {
+	BusChannels,
+	type ResidencyMutationPayload,
+	type RuntimeNoticeKind,
+	type RuntimeNoticePayload,
+} from "../../core/bus-events.js";
 import type { ProtectedModelRef, ResidencyRole } from "../../core/residency-protection.js";
 import { getSharedBus } from "../../core/shared-bus.js";
 import { withResidencyLock } from "./residency-lock.js";
@@ -73,6 +78,11 @@ export function emitResidencyNotice(notice: ResidencyNotice): void {
 	}
 }
 
+/** Publish one successful residency mutation to in-process cache telemetry. */
+export function emitResidencyMutation(mutation: Omit<ResidencyMutationPayload, "at">): void {
+	getSharedBus().emit(BusChannels.ResidencyMutation, { ...mutation, at: Date.now() });
+}
+
 // --- configured-model protection ---------------------------------------------
 
 // Wire model ids the operator's own configuration references, with the role
@@ -543,6 +553,13 @@ async function restoreEvictedModels(
 		try {
 			await adapter.reloadEvicted(entry.modelId);
 			restored.push(entry.modelId);
+			emitResidencyMutation({
+				targetKey: adapter.targetKey,
+				targetId: adapter.targetId,
+				runtimeId: adapter.runtimeId,
+				model: entry.modelId,
+				operation: "load",
+			});
 		} catch {
 			failed.push(entry.modelId);
 		}
@@ -705,6 +722,13 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 					await adapter.unload(entry.modelId);
 					forgetClioLoaded(adapter.targetKey, entry.modelId);
 					evicted.push(entry);
+					emitResidencyMutation({
+						targetKey: adapter.targetKey,
+						targetId: adapter.targetId,
+						runtimeId: adapter.runtimeId,
+						model: entry.modelId,
+						operation: "evict",
+					});
 				} catch {
 					// Best-effort: a failed unload self-heals on the next reconcile.
 				}
@@ -712,6 +736,15 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 			if (!adapter.load) return;
 			try {
 				await adapter.load(adapter.keepModelId);
+				if (!plan.keepResident) {
+					emitResidencyMutation({
+						targetKey: adapter.targetKey,
+						targetId: adapter.targetId,
+						runtimeId: adapter.runtimeId,
+						model: adapter.keepModelId,
+						operation: "load",
+					});
+				}
 			} catch (error) {
 				// The eviction bought nothing: the slot it freed is still empty and
 				// the target is now serving less than before the reconcile. Put back