@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/domains/session/context-ledger.ts

@@ -16,6 +16,7 @@
  * proportional reconciliation the footer bar already performs.
  */
 
+import type { BackendCacheVerdict, BackendCompletionTimings } from "../../core/cache-telemetry.js";
 import type { ContextWindowSlots, ContextWindowSource } from "../providers/index.js";
 import { DEFAULT_COMPACTION_THRESHOLD } from "./compaction/auto.js";
 
@@ -100,6 +101,22 @@ export interface BuildContextLedgerInput {
 	} | null;
 	/** Prompt-cache honesty line; null until a turn has compiled and settled. */
 	promptCache?: PromptCacheStats | null;
+	/** Last pre-warm since the previous settled run; null when none has run. */
+	prewarm?: PrewarmStats | null;
+}
+
+/**
+ * One pre-warm's result. It is deliberately not a token category: the pre-warm
+ * spends no window space and adds no message, it only says the backend has
+ * already prefilled the prefix the next turn will send.
+ */
+export interface PrewarmStats {
+	/** Prompt tokens the backend processed; null when it reported no counts. */
+	tokens: number | null;
+	/** Wall clock the round took. */
+	ms: number;
+	/** True when the operator submitted before the round settled. */
+	aborted: boolean;
 }
 
 /**
@@ -117,13 +134,17 @@ export interface PromptCacheStats {
 	cacheWriteTokens: number | null;
 	/** Provider-reported uncached input tokens for the last run. */
 	uncachedInputTokens: number | null;
+	/** Serving-backend timings for the run's last API call; null when none were captured. */
+	backend: BackendCompletionTimings | null;
+	/** Backend prompt tokens not served from cache, derived only when cache reads were reported. */
+	uncachedPrefillTokens: number | null;
 	/**
-	 * Cache verdict of the run's first API call, classified from the
-	 * provider-reported usage by `backendCacheVerdict`. Null before any
-	 * settled run. "Shell reused but backend cold" is the dishonest
-	 * combination the overlay renders as a warning.
+	 * Cache verdict of the run's first API call, classified by
+	 * `backendCacheVerdict` from normalized provider usage and captured serving
+	 * backend timings when available. Null before any settled run. "Shell reused
+	 * but backend cold" is the dishonest combination the overlay warns about.
 	 */
-	backendVerdict: "hot" | "partial" | "cold" | "small" | null;
+	backendVerdict: BackendCacheVerdict | null;
 	/** Cache disturbances Clio expected before the last settled run. */
 	expectedColdReasons?: ReadonlyArray<string>;
 }
@@ -185,6 +206,8 @@ export interface ContextLedger {
 		trigger: string;
 	} | null;
 	promptCache: PromptCacheStats | null;
+	/** Last pre-warm since the previous settled run; null when none has run. */
+	prewarm: PrewarmStats | null;
 }
 
 /** Maps a prompt segment id to the ledger bucket it belongs to. */
@@ -332,14 +355,6 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 	}
 
 	const meter: ContextLedgerGroup[] = [...groups];
-	if (reserveTokens > 0) {
-		meter.push({
-			category: "reserve",
-			label: CONTEXT_CATEGORY_LABEL.reserve,
-			tokens: reserveTokens,
-			percent: percentOf(reserveTokens, window),
-		});
-	}
 	if (window > 0) {
 		meter.push({
 			category: "free",
@@ -348,6 +363,14 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 			percent: percentOf(freeTokens, window),
 		});
 	}
+	if (reserveTokens > 0) {
+		meter.push({
+			category: "reserve",
+			label: CONTEXT_CATEGORY_LABEL.reserve,
+			tokens: reserveTokens,
+			percent: percentOf(reserveTokens, window),
+		});
+	}
 
 	return {
 		provider: input.provider ?? null,
@@ -369,5 +392,6 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 		meter,
 		lastCompaction: input.lastCompaction ?? null,
 		promptCache: input.promptCache ?? null,
+		prewarm: input.prewarm ?? null,
 	};
 }

package/src/domains/session/index.ts

@@ -61,6 +61,12 @@ export type {
 export { isSessionEntry, isSessionHeader, SESSION_ENTRY_KINDS } from "./entries.js";
 export { SessionManifest } from "./manifest.js";
 export { CURRENT_SESSION_FORMAT_VERSION, runMigrations } from "./migrations/index.js";
+export type { ExpectedColdReasonCount, PromptCacheTelemetry } from "./prompt-cache.js";
+export {
+	foldPromptCacheTelemetry,
+	hasPromptCacheTelemetry,
+	topExpectedColdReason,
+} from "./prompt-cache.js";
 export {
 	protectedArtifactEntryFromArtifact,
 	protectedArtifactFromSessionEntry,

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

@@ -0,0 +1,140 @@
+import {
+	type BackendCacheVerdict,
+	type BackendCompletionTimings,
+	type CacheVerdictCounts,
+	emptyCacheVerdictCounts,
+	uncachedPrefillTokens,
+} from "../../core/cache-telemetry.js";
+import type { SessionEntry } from "./entries.js";
+
+/** Durable prompt-cache facts folded across assistant calls in one ledger slice. */
+export interface PromptCacheTelemetry {
+	/** Sum of authoritative backend prefill work, or null when no call reported cache reads. */
+	uncachedPrefillTokens: number | null;
+	/** Calls contributing to `uncachedPrefillTokens`; distinguishes no evidence from a measured zero. */
+	uncachedPrefillCalls: number;
+	/** Counts of the verdict persisted on each assistant call. */
+	verdictCounts: CacheVerdictCounts;
+	/** Number of assistant calls carrying a recognized persisted verdict. */
+	verdictCalls: number;
+	/** How often each expected cache disturbance was stamped. */
+	expectedColdReasonCounts: Readonly<Record<string, number>>;
+}
+
+export interface ExpectedColdReasonCount {
+	reason: string;
+	count: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNonNegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function backendTimings(value: unknown): BackendCompletionTimings | null {
+	if (!isRecord(value)) return null;
+	if (
+		!finiteNonNegative(value.promptTokens) ||
+		!finiteNonNegative(value.predictedTokens) ||
+		!finiteNonNegative(value.promptMs) ||
+		!finiteNonNegative(value.predictedMs) ||
+		(value.source !== "llamacpp-timings" && value.source !== "lmstudio-timings")
+	) {
+		return null;
+	}
+	const cachedTokens = value.cachedTokens;
+	if (cachedTokens !== null && !finiteNonNegative(cachedTokens)) return null;
+	if (typeof cachedTokens === "number" && cachedTokens > value.promptTokens) return null;
+	return {
+		promptTokens: value.promptTokens,
+		cachedTokens,
+		predictedTokens: value.predictedTokens,
+		promptMs: value.promptMs,
+		predictedMs: value.predictedMs,
+		source: value.source,
+	};
+}
+
+function cacheVerdict(value: unknown): BackendCacheVerdict | null {
+	switch (value) {
+		case "hot":
+		case "partial":
+		case "cold":
+		case "small":
+			return value;
+		default:
+			return null;
+	}
+}
+
+/** True when the fold contains at least one durable cache fact. */
+export function hasPromptCacheTelemetry(telemetry: PromptCacheTelemetry): boolean {
+	return (
+		telemetry.verdictCalls > 0 ||
+		telemetry.uncachedPrefillCalls > 0 ||
+		Object.keys(telemetry.expectedColdReasonCounts).length > 0
+	);
+}
+
+/** Most frequent expected disturbance, with deterministic lexical tie-breaking. */
+export function topExpectedColdReason(telemetry: PromptCacheTelemetry): ExpectedColdReasonCount | null {
+	const ranked = Object.entries(telemetry.expectedColdReasonCounts).sort(
+		([leftReason, leftCount], [rightReason, rightCount]) =>
+			rightCount - leftCount || leftReason.localeCompare(rightReason),
+	);
+	const first = ranked[0];
+	return first === undefined ? null : { reason: first[0], count: first[1] };
+}
+
+/**
+ * Fold persisted assistant `promptCache` payloads without reclassifying them.
+ * Callers provide the ledger slice they mean, such as one active branch or one
+ * report window, so every surface shares parsing while retaining its own scope.
+ */
+export function foldPromptCacheTelemetry(entries: ReadonlyArray<SessionEntry>): PromptCacheTelemetry {
+	const verdictCounts = emptyCacheVerdictCounts();
+	const expectedColdReasonCounts: Record<string, number> = {};
+	let verdictCalls = 0;
+	let uncachedTotal = 0;
+	let uncachedPrefillCalls = 0;
+
+	for (const entry of entries) {
+		if (entry.kind !== "message" || entry.role !== "assistant" || !isRecord(entry.payload)) continue;
+		const promptCache = entry.payload.promptCache;
+		if (!isRecord(promptCache)) continue;
+
+		const verdict = cacheVerdict(promptCache.backendVerdict);
+		if (verdict !== null) {
+			verdictCounts[verdict] += 1;
+			verdictCalls += 1;
+		}
+
+		const backend = backendTimings(promptCache.backend);
+		const uncached = uncachedPrefillTokens(backend);
+		if (uncached !== null) {
+			uncachedTotal += uncached;
+			uncachedPrefillCalls += 1;
+		}
+
+		if (!Array.isArray(promptCache.expectedColdReasons)) continue;
+		const reasons = new Set(
+			promptCache.expectedColdReasons.filter(
+				(reason): reason is string => typeof reason === "string" && reason.trim().length > 0,
+			),
+		);
+		for (const reason of reasons) {
+			expectedColdReasonCounts[reason] = (expectedColdReasonCounts[reason] ?? 0) + 1;
+		}
+	}
+
+	return {
+		uncachedPrefillTokens: uncachedPrefillCalls > 0 ? uncachedTotal : null,
+		uncachedPrefillCalls,
+		verdictCounts,
+		verdictCalls,
+		expectedColdReasonCounts,
+	};
+}

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/acp/server.ts

@@ -1233,7 +1233,10 @@ function safeProbeReason(
 	} catch {
 		return "not-configured";
 	}
-	return status.available && status.health.status === "healthy" ? null : "unreachable";
+	// Degraded is reachable with a default the server does not serve; a client
+	// that names its own model can still use the target.
+	const reachable = status.health.status === "healthy" || status.health.status === "degraded";
+	return status.available && reachable ? null : "unreachable";
 }
 
 interface AcpPermissionBridge {

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,