@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/engine/apis/residency.ts

@@ -1,6 +1,6 @@
 /**
  * One capacity-aware model-residency reconciler, shared by every local runtime
- * that pins weights in VRAM. Both the interactive chat loop and the headless
+ * that manages loaded models. Both the interactive chat loop and the headless
  * worker drive the provider stream path, so calling the reconciler at the top
  * of each manageable runtime's stream gives exactly one place that decides
  * load and evict for both paths.
@@ -8,12 +8,12 @@
  * Co-residency is the default. Local servers are multi-model hosts with finite
  * VRAM, not single-model slots: when the runtime advertises capacity (the
  * llama.cpp router's `max_instances`) and a slot is free, Clio loads without
- * evicting anything; when the runtime loads just-in-time and fails an
- * oversized load cleanly (LM Studio), Clio attempts the co-resident load first
- * and swaps only after that failure; when the server schedules fits itself
+ * evicting anything; when the runtime loads just-in-time (LM Studio), Clio
+ * attempts the co-resident load first and considers swapping only after an
+ * explicit capacity rejection; when the server schedules fits itself
  * (Ollama), Clio releases only its own unprotected stragglers. Eviction is the
- * exception, taken only when a slot must be freed, and it never selects a
- * protected resident while an unprotected one is available.
+ * exception, using only Clio-attributed loads. It never selects a protected
+ * resident while an unprotected owned one is available.
  *
  * Protection is symmetric and role-aware. Residents tagged `pinned:true` or
  * `role:scout` by the server operator are never evicted. Residents referenced
@@ -24,12 +24,12 @@
  * when capacity is exhausted. No Clio profile silently evicts another profile's
  * model, and no chat switch silently unloads the memory plane.
  *
- * The reconciler is best-effort and non-blocking. A slow or unreachable
- * server, or a malformed resident listing, degrades to observe-only and never
- * crashes a turn. An explicit target `lifecycle: user-managed` forces
- * observe-only on every runtime path.
- * Every collision or stress case emits a notice over the event bus instead of
- * a thrown error. One reconcile decision holds per (target, model) within a
+ * Failed metadata reads degrade to observe-only. Explicit mutation failures
+ * propagate after rollback, and router adapters must honor a declined plan
+ * before allowing an inference request to trigger an automatic load.
+ * An explicit target `lifecycle: user-managed` forces observe-only.
+ * Collision and stress notices travel over the event bus. One successful
+ * reconcile decision holds per (target, model) within a
  * TTL, and mutations for a target are serialized across processes through a
  * state-dir lock file so a worker and the orchestrator cannot interleave
  * unload/load against the same server.
@@ -37,11 +37,15 @@
 
 import {
 	BusChannels,
+	type DeclaredRuntimeNotice,
 	type ResidencyMutationPayload,
 	type RuntimeNoticeKind,
 	type RuntimeNoticePayload,
 } from "../../core/bus-events.js";
+import { canonicalEndpointUrl } from "../../core/endpoint-key.js";
+import type { SafeEventBus } from "../../core/event-bus.js";
 import type { ProtectedModelRef, ResidencyRole } from "../../core/residency-protection.js";
+import { residencyTargetKey } from "../../core/residency-target-key.js";
 import { getSharedBus } from "../../core/shared-bus.js";
 import { withResidencyLock } from "./residency-lock.js";
 import { type ResidentModelInfo, residentMatchesKeep } from "./resident-models.js";
@@ -54,7 +58,7 @@ export type { RuntimeNoticeKind };
 export type ResidencyNoticeSink = (notice: ResidencyNotice) => void;
 
 function busNoticeSink(notice: ResidencyNotice): void {
-	getSharedBus().emit(BusChannels.RuntimeNotice, notice);
+	getSharedBus().emit(BusChannels.RuntimeNotice, notice as DeclaredRuntimeNotice);
 }
 
 let noticeSink: ResidencyNoticeSink = busNoticeSink;
@@ -69,15 +73,64 @@ export function setResidencyNoticeSink(sink: ResidencyNoticeSink | null): void {
 	noticeSink = sink ?? busNoticeSink;
 }
 
-/** Emit one notice through the active sink. Never throws into a turn. */
-export function emitResidencyNotice(notice: ResidencyNotice): void {
+/**
+ * Deliver one notice through the active sink, or onto `bus` when the producer
+ * was handed one explicitly. Never throws into a turn.
+ */
+function deliverNotice(notice: ResidencyNotice, bus?: Pick<SafeEventBus, "emit">): void {
 	try {
-		noticeSink(notice);
+		if (bus) bus.emit(BusChannels.RuntimeNotice, notice as DeclaredRuntimeNotice);
+		else noticeSink(notice);
 	} catch {
 		// A notice is informational; a sink failure must never escape into a turn.
 	}
 }
 
+// --- notice producers ----------------------------------------------------------
+
+const noticeProducers = new Map<string, ReadonlySet<RuntimeNoticeKind>>();
+
+/**
+ * Emitter bound to the kinds its producer declared; any other kind is a type
+ * error. A producer that owns an injected bus passes it; otherwise the notice
+ * goes to the active sink.
+ */
+export type RuntimeNoticeEmitter<K extends RuntimeNoticeKind> = (
+	notice: ResidencyNotice & { kind: K },
+	bus?: Pick<SafeEventBus, "emit">,
+) => void;
+
+/**
+ * Declare a module as the producer of some {@link RuntimeNoticeKind} members
+ * and get back the only way to emit them. Emission goes exclusively through
+ * these emitters, so a registered kind always has code that emits it, and a
+ * contract test checks that every member of the union is registered by some
+ * producer. Call once at module scope.
+ */
+export function declareRuntimeNoticeProducer<const K extends RuntimeNoticeKind>(
+	producer: string,
+	kinds: ReadonlyArray<K>,
+): RuntimeNoticeEmitter<K> {
+	noticeProducers.set(producer, new Set(kinds));
+	return deliverNotice;
+}
+
+/** Every declared producer with the kinds it emits. */
+export function runtimeNoticeProducers(): ReadonlyMap<string, ReadonlySet<RuntimeNoticeKind>> {
+	return noticeProducers;
+}
+
+type ReconcilerNoticeKind = "will-not-fit" | "about-to-evict" | "swap" | "co-resident" | "stress";
+type ReconcilerNotice = ResidencyNotice & { kind: ReconcilerNoticeKind };
+
+const emitReconcilerNotice = declareRuntimeNoticeProducer<ReconcilerNoticeKind>("residency-reconciler", [
+	"will-not-fit",
+	"about-to-evict",
+	"swap",
+	"co-resident",
+	"stress",
+]);
+
 /** 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() });
@@ -125,12 +178,11 @@ export function residentTagProtected(tags: ReadonlyArray<string> | undefined): b
 
 // Models Clio itself loaded, keyed by a stable per-server target key. The
 // registry is per-process; a resident model absent from it may still be
-// another Clio process's model, which is why eviction relies on the symmetric
-// protection above rather than on attribution alone.
+// another Clio process's model. Those loads are foreign to this session.
 const clioLoaded = new Map<string, Set<string>>();
 
 /** Record that Clio loaded `modelId` on the target identified by `targetKey`. */
-function markClioLoaded(targetKey: string, modelId: string): void {
+export function markClioLoaded(targetKey: string, modelId: string): void {
 	let set = clioLoaded.get(targetKey);
 	if (!set) {
 		set = new Set();
@@ -143,13 +195,196 @@ function forgetClioLoaded(targetKey: string, modelId: string): void {
 	clioLoaded.get(targetKey)?.delete(modelId);
 }
 
-function isClioLoaded(targetKey: string, entry: ResidentModelInfo): boolean {
+/**
+ * Drop a model Clio released outside the reconciler, such as the release on
+ * process exit, so neither the registry nor the TTL fast path still believes
+ * it resident.
+ */
+export function forgetReleasedModel(targetKey: string, modelId: string): void {
+	forgetClioLoaded(targetKey, modelId);
+	workerLoaded.get(targetKey)?.delete(modelId);
+	reconcileCache.delete(targetKey);
+}
+
+export function isClioLoaded(targetKey: string, entry: ResidentModelInfo): boolean {
 	const set = clioLoaded.get(targetKey);
 	if (!set) return false;
 	if (set.has(entry.modelId)) return true;
 	return (entry.aliasIds ?? []).some((id) => set.has(id));
 }
 
+// --- worker-loaded models --------------------------------------------------
+
+// Models a dispatched worker loaded, adopted by the orchestrator so its release
+// on exit covers them (#379). Kept apart from clioLoaded because they carry
+// eviction protection: another dispatch may still be using one.
+const workerLoaded = new Map<string, Set<string>>();
+
+function isWorkerLoaded(targetKey: string, entry: ResidentModelInfo): boolean {
+	const set = workerLoaded.get(targetKey);
+	if (!set) return false;
+	return [entry.modelId, ...(entry.aliasIds ?? [])].some((id) => set.has(id));
+}
+
+/** One model a request loaded and pinned, as a runtime reports it. */
+export interface ClioModelLoad {
+	runtimeId: string;
+	targetId: string;
+	modelId: string;
+	aliasIds: string[];
+}
+
+let loadReportSink: ((load: ClioModelLoad) => void) | null = null;
+
+/**
+ * Where a runtime's load reports go. The worker entry installs a sink that
+ * forwards each report to the orchestrator over the control lane; the
+ * orchestrator installs none, because its own loads are already in its
+ * registries. Passing null removes the sink.
+ */
+export function setModelLoadReportSink(sink: ((load: ClioModelLoad) => void) | null): void {
+	loadReportSink = sink;
+}
+
+/**
+ * Report a model this process loaded and pinned, when both residency
+ * registries attribute it to this process: the reconciler saw it absent before
+ * Clio's request, and the runtime then recorded ownership. A model that was
+ * resident before this process touched it is never reported. Never throws.
+ */
+export function reportClioModelLoad(load: ClioModelLoad, targetKey: string): void {
+	if (!loadReportSink || !isClioLoaded(targetKey, { modelId: load.modelId, aliasIds: load.aliasIds })) return;
+	try {
+		loadReportSink(load);
+	} catch {
+		// A report is best-effort; losing one leaves the model pinned, never a turn failed.
+	}
+}
+
+/** How to reach the server a worker loaded a model on, from the orchestrator's own settings. */
+export interface WorkerModelLoadEndpoint {
+	runtimeId: string;
+	baseUrl: string;
+	headers: Record<string, string>;
+}
+
+type WorkerLoadAdopter = (targetKey: string, endpoint: WorkerModelLoadEndpoint, modelIds: string[]) => void;
+
+const workerLoadAdopters = new Map<string, WorkerLoadAdopter>();
+
+/** Register how a runtime takes ownership of a model a worker loaded. */
+export function registerWorkerLoadAdopter(runtimeId: string, adopter: WorkerLoadAdopter): void {
+	workerLoadAdopters.set(runtimeId, adopter);
+}
+
+/**
+ * Adopt a model a dispatched worker loaded, so this process releases it on
+ * exit and no stream here evicts it first. Returns false when the runtime has
+ * no adopter or the endpoint has no residency key.
+ */
+export function adoptWorkerLoadedModel(
+	endpoint: WorkerModelLoadEndpoint,
+	load: Pick<ClioModelLoad, "modelId" | "aliasIds">,
+): boolean {
+	const adopter = workerLoadAdopters.get(endpoint.runtimeId);
+	const targetKey = residencyTargetKey(endpoint.runtimeId, endpoint.baseUrl);
+	if (!adopter || targetKey === null) return false;
+	const ids = [load.modelId, ...load.aliasIds];
+	let set = workerLoaded.get(targetKey);
+	if (!set) {
+		set = new Set();
+		workerLoaded.set(targetKey, set);
+	}
+	for (const id of ids) {
+		set.add(id);
+		markClioLoaded(targetKey, id);
+	}
+	adopter(targetKey, endpoint, ids);
+	return true;
+}
+
+// --- release on exit ------------------------------------------------------
+
+/** Total time the release on exit may take before shutdown moves on without it. */
+export const EXIT_RELEASE_MS = 2_000;
+
+/**
+ * Narrows a release to some models. Called with the target key and every id
+ * the resident entry answers to; true releases the model.
+ */
+export type ReleaseScope = (targetKey: string, modelIds: ReadonlyArray<string>) => boolean;
+
+/**
+ * A release scope for one probe: the server reached at any of `baseUrls` and
+ * a resident entry answering to any of `modelIds`. Urls are compared by the
+ * same canonical endpoint the residency registry keys on.
+ */
+export function releaseScopeFor(
+	baseUrls: ReadonlyArray<string | null | undefined>,
+	modelIds: ReadonlyArray<string | null | undefined>,
+): ReleaseScope {
+	const keys = new Set(
+		baseUrls
+			.filter((url): url is string => typeof url === "string" && url.length > 0)
+			.map((url) => canonicalEndpointUrl(url) ?? url),
+	);
+	const ids = new Set(modelIds.filter((id): id is string => typeof id === "string" && id.length > 0));
+	return (targetKey, entryIds) => keys.has(targetKey) && entryIds.some((id) => ids.has(id));
+}
+
+const exitReleasers = new Set<(scope?: ReleaseScope) => Promise<void>>();
+
+/**
+ * Register a runtime's release of the models this process loaded and pinned.
+ * A runtime registers when its module loads, so a process that never reached
+ * the runtime has nothing to release and pays nothing at exit.
+ */
+export function registerExitRelease(release: (scope?: ReleaseScope) => Promise<void>): void {
+	exitReleasers.add(release);
+}
+
+/**
+ * Run every registered release. Each release bounds itself by
+ * {@link EXIT_RELEASE_MS}; a failure is swallowed so the exit code never
+ * depends on a server that is gone.
+ */
+export async function releaseClioLoadedModelsOnExit(scope?: ReleaseScope): Promise<void> {
+	await Promise.all(
+		[...exitReleasers].map((release) =>
+			release(scope).catch(() => {
+				// Best-effort: the model stays pinned.
+			}),
+		),
+	);
+}
+
+/**
+ * Run `task`, then release every model that became Clio-loaded while it ran,
+ * whether it settled or threw. A one-shot inference probe uses this so it never
+ * leaves a pinned model behind in a process that has no release on exit (#379).
+ * A model Clio had already loaded before the task stays pinned for the turn
+ * that loaded it, and a model resident before Clio touched it is never
+ * Clio-loaded in the first place (#313). The release is bounded by
+ * {@link EXIT_RELEASE_MS}.
+ *
+ * `scope` narrows the release further. In a process that also runs chat
+ * turns, "became Clio-loaded while the task ran" includes a model a concurrent
+ * turn loaded, so an in-session probe passes the one target and model it
+ * exercised and leaves every other load to the turn that made it.
+ */
+export async function releaseModelsLoadedDuring<T>(task: () => Promise<T>, scope?: ReleaseScope): Promise<T> {
+	const before = new Set<string>();
+	for (const [targetKey, ids] of clioLoaded) for (const id of ids) before.add(`${targetKey}\n${id}`);
+	try {
+		return await task();
+	} finally {
+		await releaseClioLoadedModelsOnExit(
+			(targetKey, ids) =>
+				!ids.some((id) => before.has(`${targetKey}\n${id}`)) && (scope === undefined || scope(targetKey, ids)),
+		);
+	}
+}
+
 // --- TTL fast path ---------------------------------------------------------
 
 /** Skip the listResident round-trip for this long after a clean reconcile. */
@@ -163,10 +398,8 @@ const reconcileCache = new Map<string, { modelId: string; decision: "reconcile"
  * eviction is even on the table:
  *   - "router": Clio must POST an explicit load (llama.cpp router) and the
  *     server advertises a slot capacity. A free slot loads without eviction;
- *     a full server frees exactly the slots needed; unknown capacity falls
- *     back to a conservative swap of unprotected residents.
- *   - "jit": the runtime loads on open and fails an oversized load cleanly
- *     (LM Studio with gpuStrictVramCap). Nothing is evicted up front; the
+ *     a full server frees exactly the slots needed; unknown capacity with existing residents declines the load.
+ *   - "jit": the runtime loads on open. Nothing is evicted up front; the
  *     plan carries ranked `fallbackEvict` candidates for a retry after a
  *     will-not-fit failure.
  *   - "scheduler": the server places and fits models itself (Ollama). Only
@@ -175,8 +408,13 @@ const reconcileCache = new Map<string, { modelId: string; decision: "reconcile"
  */
 export type ResidencyStrategy = "router" | "jit" | "scheduler";
 
-/** Why a resident model may not be evicted, when it may not. */
-export type ResidencyProtection = "tag" | "config";
+/**
+ * Why a resident model may not be evicted, when it may not. `worker` marks a
+ * model a dispatched worker loaded and the orchestrator adopted: a later
+ * dispatch may still use it, so no Clio stream evicts it mid-session and the
+ * release on exit reclaims it instead.
+ */
+export type ResidencyProtection = "tag" | "config" | "worker";
 
 export interface ResidentClassified extends ResidentModelInfo {
 	/** True when this process's Clio-loaded registry attributes the model to Clio. */
@@ -218,7 +456,7 @@ export interface ResidencyPlan {
 	fallbackEvict: ResidentModelInfo[];
 	/** True when the keep model is already resident on the target. */
 	keepResident: boolean;
-	notices: ResidencyNotice[];
+	notices: ReconcilerNotice[];
 }
 
 function gib(bytes: number): string {
@@ -227,12 +465,12 @@ function gib(bytes: number): string {
 
 function makeNotice(
 	facts: ResidencyFacts,
-	kind: RuntimeNoticeKind,
+	kind: ReconcilerNoticeKind,
 	level: ResidencyNotice["level"],
 	message: string,
 	detail?: ResidencyNotice["detail"],
-): ResidencyNotice {
-	const notice: ResidencyNotice = {
+): ReconcilerNotice {
+	const notice: ReconcilerNotice = {
 		kind,
 		level,
 		targetId: facts.targetId,
@@ -244,10 +482,6 @@ function makeNotice(
 	return notice;
 }
 
-function clioLoadedFirst(entries: ReadonlyArray<ResidentClassified>): ResidentClassified[] {
-	return [...entries.filter((entry) => entry.loadedByClio), ...entries.filter((entry) => !entry.loadedByClio)];
-}
-
 /** `the memory model` / `the chat model` for a notice, or the bare id's article. */
 function describeRole(role: ResidencyRole | undefined): string {
 	if (role === "chat") return "the chat model";
@@ -257,7 +491,7 @@ function describeRole(role: ResidencyRole | undefined): string {
 	return "a configured model";
 }
 
-function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): ResidencyNotice {
+function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): ReconcilerNotice {
 	if (entry.protection === "config") {
 		return makeNotice(
 			facts,
@@ -267,24 +501,12 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
 			{ swappedOut: entry.modelId, configProtected: true, ...(entry.role ? { role: entry.role } : {}) },
 		);
 	}
-	if (entry.loadedByClio) {
-		return makeNotice(
-			facts,
-			"about-to-evict",
-			"info",
-			`evicting Clio-loaded model '${entry.modelId}' from '${facts.targetId}' to free a slot for '${facts.keepModelId}'.`,
-			entry.sizeVramBytes !== undefined ? { freedVramBytes: entry.sizeVramBytes } : undefined,
-		);
-	}
 	return makeNotice(
 		facts,
-		"swap",
-		"warning",
-		`swapping resident '${entry.modelId}' for requested '${facts.keepModelId}' on '${facts.targetId}' (Clio did not load it; recorded transition instead of a silent unload; set lifecycle: user-managed to forbid swaps).`,
-		{
-			...(entry.sizeVramBytes !== undefined ? { freedVramBytes: entry.sizeVramBytes } : {}),
-			swappedOut: entry.modelId,
-		},
+		"about-to-evict",
+		"info",
+		`evicting Clio-loaded model '${entry.modelId}' from '${facts.targetId}' to free a slot for '${facts.keepModelId}'.`,
+		entry.sizeVramBytes !== undefined ? { freedVramBytes: entry.sizeVramBytes } : undefined,
 	);
 }
 
@@ -296,7 +518,7 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
  * server.
  */
 function decideResidency(facts: ResidencyFacts): ResidencyPlan {
-	const notices: ResidencyNotice[] = [];
+	const notices: ReconcilerNotice[] = [];
 	const keepResident = facts.resident.some((entry) => residentMatchesKeep(entry, facts.keepModelId));
 	const others = facts.resident.filter((entry) => !residentMatchesKeep(entry, facts.keepModelId));
 
@@ -372,31 +594,38 @@ function decideResidency(facts: ResidencyFacts): ResidencyPlan {
 		return { decision: "reconcile", evict: [], fallbackEvict: [], keepResident, notices };
 	}
 
-	// The keep model is not resident. Rank potential evictions by protection
-	// tier: unprotected residents first (Clio-attributed before foreign), then
-	// config-protected ones as a loud last resort. Tag-pinned residents are
-	// never candidates. A keep model that will itself come back tag-pinned may
-	// not displace the config tier: once resident it is never a candidate, so
-	// the configured role could not reclaim its slot.
-	const tierUnprotected = clioLoadedFirst(others.filter((entry) => entry.protection === undefined));
-	const tierConfig = clioLoadedFirst(others.filter((entry) => entry.protection === "config"));
+	// Only loads attributed to this Clio session may be eviction candidates.
+	// Configured model names describe demand, not ownership of foreign loads.
+	const owned = others.filter((entry) => entry.loadedByClio);
+	const tierUnprotected = owned.filter((entry) => entry.protection === undefined);
+	const tierConfig = owned.filter((entry) => entry.protection === "config");
 	const configEvictable = facts.keepTagProtected !== true;
 
 	let evict: ResidentClassified[] = [];
 	let fallbackEvict: ResidentClassified[] = [];
 
 	if (facts.strategy === "jit") {
-		// Attempt the co-resident load first; the runtime turns an oversized
-		// load into a clean failure, and only that failure justifies a swap.
+		// Attempt co-residency first; only an explicit capacity failure
+		// justifies swapping an owned instance. GPU fit is not guaranteed.
 		fallbackEvict = configEvictable ? [...tierUnprotected, ...tierConfig] : tierUnprotected;
 	} else if (facts.strategy === "scheduler") {
 		// The server fits and places models itself. Release only Clio's own
 		// unprotected stragglers; foreign and protected residents stay.
-		evict = tierUnprotected.filter((entry) => entry.loadedByClio);
-	} else if (facts.capacity === undefined) {
-		// Router without readable capacity: no way to prove a free slot, so
-		// fall back to swapping the unprotected residents before the load.
 		evict = tierUnprotected;
+	} else if (facts.capacity === undefined) {
+		// Without a capacity bound, a load can silently displace another model.
+		// Preserve the current serving set rather than guess how much to evict.
+		if (others.length > 0) {
+			notices.push(
+				makeNotice(
+					facts,
+					"will-not-fit",
+					"error",
+					`cannot load '${facts.keepModelId}' on '${facts.targetId}': router capacity is unknown while other models are resident. Restore capacity inspection or load the model on the server.`,
+				),
+			);
+			return { decision: "decline", evict: [], fallbackEvict: [], keepResident, notices };
+		}
 	} else {
 		const slotsNeeded = facts.resident.length + 1 - facts.capacity;
 		if (slotsNeeded > 0) {
@@ -432,7 +661,7 @@ function decideResidency(facts: ResidencyFacts): ResidencyPlan {
 						facts,
 						"will-not-fit",
 						"error",
-						`cannot load '${facts.keepModelId}' on '${facts.targetId}': all ${facts.capacity} instance slots hold pinned models (${others.map((entry) => entry.modelId).join(", ")}). Unload one manually or raise the server's max instances.`,
+						`cannot load '${facts.keepModelId}' on '${facts.targetId}': its ${facts.capacity} instance slots cannot be freed using Clio-owned, evictable models (${others.map((entry) => entry.modelId).join(", ")}). Unload one manually or raise the server's max instances.`,
 						{ residentCount: facts.resident.length, maxInstances: facts.capacity },
 					),
 				);
@@ -476,6 +705,7 @@ export interface ResidencyAdapter {
 	contextLength?: number;
 	modelMaxContext?: number;
 	listResident(): Promise<ResidentModelInfo[]>;
+	signal?: AbortSignal;
 	/**
 	 * Runtime tags of the keep model itself, when the runtime lists them before
 	 * the load (the llama.cpp router lists tags for unloaded models too). Called
@@ -546,6 +776,7 @@ async function restoreEvictedModels(
 		}
 		try {
 			await adapter.reloadEvicted(entry.modelId);
+			markClioLoaded(adapter.targetKey, entry.modelId);
 			restored.push(entry.modelId);
 			emitResidencyMutation({
 				targetKey: adapter.targetKey,
@@ -559,7 +790,7 @@ async function restoreEvictedModels(
 		}
 	}
 	if (restored.length > 0) {
-		emitResidencyNotice({
+		emitReconcilerNotice({
 			kind: "swap",
 			level: "warning",
 			targetId: adapter.targetId,
@@ -570,7 +801,7 @@ async function restoreEvictedModels(
 		});
 	}
 	if (failed.length > 0) {
-		emitResidencyNotice({
+		emitReconcilerNotice({
 			kind: "will-not-fit",
 			level: "error",
 			targetId: adapter.targetId,
@@ -608,7 +839,12 @@ export class ResidencyPreconditionError extends Error {
  * connection error.
  */
 export async function reconcileResidency(adapter: ResidencyAdapter): Promise<ReconcileResult> {
-	const now = adapter.now ?? Date.now;
+	return reconcileResidencyState(adapter, false);
+}
+
+async function reconcileResidencyState(adapter: ResidencyAdapter, lockHeld: boolean): Promise<ReconcileResult> {
+	adapter.signal?.throwIfAborted();
+	const now = adapter.now ?? (() => performance.now());
 	const ttl = adapter.ttlMs ?? RECONCILE_TTL_MS;
 
 	const cached = reconcileCache.get(adapter.targetKey);
@@ -621,11 +857,20 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 			notices: [],
 		};
 	}
+	// Router capacity and its eviction plan must describe the server after the
+	// previous lock holder finished loading, not a snapshot from before the wait.
+	if (adapter.managed && adapter.strategy === "router" && !lockHeld) {
+		const reconcile = () => reconcileResidencyState(adapter, true);
+		return adapter.withLock
+			? adapter.withLock(adapter.targetKey, reconcile)
+			: withResidencyLock(adapter.targetKey, reconcile, adapter.signal);
+	}
 
 	let resident: ResidentModelInfo[];
 	try {
 		resident = await adapter.listResident();
 	} catch {
+		adapter.signal?.throwIfAborted();
 		// Unreachable or slow server: never block the turn, just observe.
 		return { decision: "observe", evict: [], fallbackEvict: [], keepResident: false, notices: [] };
 	}
@@ -655,7 +900,9 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 			? "tag"
 			: configId !== undefined
 				? "config"
-				: undefined;
+				: isWorkerLoaded(adapter.targetKey, entry)
+					? "worker"
+					: undefined;
 		const role = configId === undefined ? undefined : protectedRoles.get(configId);
 		return {
 			...entry,
@@ -679,19 +926,19 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 	};
 
 	const plan = decideResidency(facts);
+	adapter.signal?.throwIfAborted();
 
 	// An eviction is only justified if the load it makes room for can succeed.
 	// Unloading first and discovering afterwards that the keep model does not
 	// exist leaves the target serving nothing, which took a shared node out of
-	// service on the live fleet (#127). Nothing has mutated yet at this point,
-	// so refusing here is a clean no-op: the turn continues to the provider call
-	// and fails with the server's own error for the unknown model.
+	// service on the live fleet (#127). Nothing has mutated yet at this point;
+	// the adapter can stop the request with the loadability diagnostic.
 	if (plan.decision === "reconcile" && plan.evict.length > 0 && adapter.assertLoadable) {
 		try {
 			await adapter.assertLoadable();
 		} catch (error) {
 			if (!(error instanceof ResidencyPreconditionError)) throw error;
-			const notice: ResidencyNotice = {
+			const notice: ReconcilerNotice = {
 				kind: "will-not-fit",
 				level: "error",
 				targetId: adapter.targetId,
@@ -699,20 +946,21 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 				model: adapter.keepModelId,
 				message: error.message,
 			};
-			emitResidencyNotice(notice);
+			emitReconcilerNotice(notice);
 			return { decision: "decline", evict: [], fallbackEvict: [], keepResident: false, notices: [notice] };
 		}
 	}
 
 	// Emitted after the loadability gate so the operator never reads an eviction
 	// notice for a swap that the gate then refuses.
-	for (const notice of plan.notices) emitResidencyNotice(notice);
+	for (const notice of plan.notices) emitReconcilerNotice(notice);
 
 	if (plan.decision === "reconcile") {
 		const mutate = async (): Promise<void> => {
+			adapter.signal?.throwIfAborted();
 			const evicted: ResidentModelInfo[] = [];
-			for (const entry of plan.evict) {
-				try {
+			try {
+				for (const entry of plan.evict) {
 					await adapter.unload(entry.modelId);
 					forgetClioLoaded(adapter.targetKey, entry.modelId);
 					evicted.push(entry);
@@ -723,12 +971,8 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 						model: entry.modelId,
 						operation: "evict",
 					});
-				} catch {
-					// Best-effort: a failed unload self-heals on the next reconcile.
 				}
-			}
-			if (!adapter.load) return;
-			try {
+				if (!adapter.load) return;
 				await adapter.load(adapter.keepModelId);
 				if (!plan.keepResident) {
 					emitResidencyMutation({
@@ -755,15 +999,21 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 		// Serialize actual mutations across processes; a keep model that is
 		// already fully resident needs no lock (the load hook is a no-op) and
 		// waiting on a still-loading model is read-only polling.
-		if (plan.evict.length > 0 || (adapter.load && !plan.keepResident)) {
-			const lock = adapter.withLock ?? withResidencyLock;
-			await lock(adapter.targetKey, mutate);
+		if (!lockHeld && (plan.evict.length > 0 || (adapter.load && !plan.keepResident))) {
+			if (adapter.withLock) await adapter.withLock(adapter.targetKey, mutate);
+			else await withResidencyLock(adapter.targetKey, mutate, adapter.signal);
 		} else {
 			await mutate();
 		}
 		// Attribute the keep model to Clio only when Clio is the one loading it.
-		if (!plan.keepResident) markClioLoaded(adapter.targetKey, adapter.keepModelId);
-		reconcileCache.set(adapter.targetKey, { modelId: adapter.keepModelId, decision: "reconcile", at: now() });
+		if (!plan.keepResident && adapter.load) markClioLoaded(adapter.targetKey, adapter.keepModelId);
+		// A scheduler/JIT plan does not load anything itself. A failed upcoming
+		// chat must not turn that plan into a cached claim that the model is resident.
+		if (plan.keepResident || adapter.load) {
+			reconcileCache.set(adapter.targetKey, { modelId: adapter.keepModelId, decision: "reconcile", at: now() });
+		} else {
+			reconcileCache.delete(adapter.targetKey);
+		}
 	} else if (plan.decision === "observe" && !adapter.managed) {
 		// Cache the opt-out observation so its notices dedupe per TTL; a
 		// degraded observe (listResident failure) is never cached, so the next