@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/prompts/compiler.ts

@@ -48,12 +48,22 @@ export interface SessionPromptInputs {
 	memorySection?: string;
 }
 
+/**
+ * Which section order `compile()` lays down. `volatility` is the product
+ * order; `legacy-0.3.8` reproduces the order shipped before issue #249 and
+ * exists so a test can prove the change is a pure permutation. Nothing in
+ * `src/` may pass `legacy-0.3.8`; the boundary is the test suite.
+ */
+export type SessionPromptSectionOrder = "volatility" | "legacy-0.3.8";
+
 export interface CompileInputs {
 	identity: string;
 	operatingContract: string;
 	safety: string;
 	sessionInputs: SessionPromptInputs;
 	additionalFragments?: ReadonlyArray<RenderedPromptFragment>;
+	/** Test-only escape hatch; see `SessionPromptSectionOrder`. Defaults to `volatility`. */
+	sectionOrder?: SessionPromptSectionOrder;
 }
 
 /** Stable inputs for one mediated fleet worker's canonical system prompt. */
@@ -439,21 +449,93 @@ function renderProjectBlock(contextFiles: string | undefined): string {
 	return trimmedFiles.length === 0 ? "" : `# Project\n\n${trimmedFiles}`;
 }
 
-function renderMemoryBlock(memorySection: string | undefined): string {
+/**
+ * The rendered memory section already opens with its own `# Memory` heading
+ * (`domains/memory/prompt-section.ts`), so prepending one unconditionally put
+ * the header in the prompt twice. Callers that pass a bare body still get a
+ * header; callers that pass a rendered section keep the one they wrote.
+ *
+ * `legacyDuplicateHeader` reproduces the 0.3.8 behavior and is reachable only
+ * through `sectionOrder: "legacy-0.3.8"`, so the permutation test compares
+ * against the whole prompt 0.3.8 emitted rather than a half-corrected one.
+ */
+function renderMemoryBlock(memorySection: string | undefined, legacyDuplicateHeader = false): string {
 	const trimmed = memorySection?.trim() ?? "";
-	return trimmed.length === 0 ? "" : `# Memory\n\n${trimmed}`;
+	if (trimmed.length === 0) return "";
+	if (legacyDuplicateHeader) return `# Memory\n\n${trimmed}`;
+	return /^#\s+Memory\s*$/.test(trimmed.split("\n", 1)[0] ?? "") ? trimmed : `# Memory\n\n${trimmed}`;
 }
 
 function estimatePromptTokens(text: string): number {
 	return ceilChars(text.trim().length);
 }
 
+/**
+ * The session prompt's section order, stable prefix first (issue #249).
+ *
+ * The rule, and it is the only rule: a section goes as late as its
+ * volatility, and anything that reads a clock, a probe, or a mutable store
+ * goes after everything that does not. Every backend Clio targets caches by
+ * exact prefix and re-prefills from the earliest changed byte, so a section
+ * that can change between two turns must not sit ahead of sections that
+ * cannot. That is why `runtime` is last of the compiled sections: its
+ * `Context window: N` moves when the backend reloads a model or a
+ * co-residency clamp lands, and before this order a single changed digit
+ * re-prefilled the tool contract, the roster, the hints, memory, and the
+ * project context behind it. `memory` sits just ahead of it because an
+ * approved memory record rewrites that section mid-session, and
+ * `project-context` is stable for the session's lifetime.
+ *
+ * The tail fragments (`workspace-root`, `clio-repo-awareness`,
+ * `project-rules`, `operator-profile`) are appended after this list in their
+ * own order: path-scoped project rules grow mid-session by design, which is
+ * exactly why they belong at the very end.
+ *
+ * Moving an entry here is a deliberate cache decision. `tests/contracts/
+ * prompt-prefix-layout.test.ts` pins this list so the move has to be made on
+ * purpose.
+ */
+export const SESSION_PROMPT_SECTION_ORDER: ReadonlyArray<string> = [
+	"identity",
+	"operating-contract",
+	"delegation",
+	"skills",
+	"safety",
+	"tool-contract",
+	"fleet",
+	"retrieval-hints",
+	"project-context",
+	"memory",
+	"runtime",
+];
+
+/**
+ * The order shipped through 0.3.8, kept only so a test can prove the new order
+ * is a permutation of it rather than a rewrite. Never reachable from `src/`.
+ */
+export const LEGACY_SESSION_PROMPT_SECTION_ORDER: ReadonlyArray<string> = [
+	"identity",
+	"operating-contract",
+	"delegation",
+	"skills",
+	"safety",
+	"runtime",
+	"tool-contract",
+	"fleet",
+	"retrieval-hints",
+	"memory",
+	"project-context",
+];
+
 /**
  * Compile the session system prompt. Identity and the operating contract
  * render verbatim from disk fragments; safety renders a one-line directive
  * plus the safety fragment body; everything else renders inline from typed
  * SessionPromptInputs. Output is one string, one sha256, one token estimate,
  * and a flat section breakdown for the /context overlay.
+ *
+ * Sections are laid down in `SESSION_PROMPT_SECTION_ORDER`, whose doc comment
+ * states the volatility rule that fixes it.
  */
 export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSessionPrompt {
 	const identity = lookupFragment(table, inputs.identity, "identity");
@@ -493,17 +575,22 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 	const delegation = sessionCanDispatch(session) ? table.byId.get("operating.delegation") : undefined;
 	const skills = sessionHasContext(session) ? table.byId.get("operating.skills") : undefined;
 
-	push("identity", identityBody);
-	push("operating-contract", operatingContract.body);
-	if (delegation) push("delegation", delegation.body);
-	if (skills) push("skills", skills.body);
-	push("safety", renderSafetySection(safety, autonomyLevel));
-	push("runtime", renderRuntimeBlock(session));
-	push("tool-contract", renderToolContractBlock(session));
-	push("fleet", renderFleetBlock(session));
-	push("retrieval-hints", renderRetrievalHintsBlock(session));
-	push("memory", renderMemoryBlock(session.memorySection));
-	push("project-context", renderProjectBlock(session.contextFiles));
+	const legacy = inputs.sectionOrder === "legacy-0.3.8";
+	const rendered = new Map<string, string>([
+		["identity", identityBody],
+		["operating-contract", operatingContract.body],
+		["delegation", delegation?.body ?? ""],
+		["skills", skills?.body ?? ""],
+		["safety", renderSafetySection(safety, autonomyLevel)],
+		["runtime", renderRuntimeBlock(session)],
+		["tool-contract", renderToolContractBlock(session)],
+		["fleet", renderFleetBlock(session)],
+		["retrieval-hints", renderRetrievalHintsBlock(session)],
+		["memory", renderMemoryBlock(session.memorySection, legacy)],
+		["project-context", renderProjectBlock(session.contextFiles)],
+	]);
+	const order = legacy ? LEGACY_SESSION_PROMPT_SECTION_ORDER : SESSION_PROMPT_SECTION_ORDER;
+	for (const id of order) push(id, rendered.get(id) ?? "");
 	for (const fragment of inputs.additionalFragments ?? []) {
 		push(fragment.id, fragment.body);
 	}

package/src/domains/providers/endpoint-capacity.ts

@@ -0,0 +1,228 @@
+import { canonicalEndpointUrl } from "../../core/endpoint-key.js";
+import type { TargetStatus } from "./contract.js";
+import {
+	type DiscoveredEndpointSlots,
+	readDiscoveredEndpointSlots,
+	recordDiscoveredEndpointSlots,
+} from "./endpoint-slots-store.js";
+import type { RuntimeDescriptor } from "./types/runtime-descriptor.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+/**
+ * Where an endpoint's slot bound came from, weakest first.
+ *
+ * `discovered-prior` is a slot count a previous process probed and persisted
+ * (endpoint-slots-store.ts). It outranks the blind local default because it is
+ * evidence, and it yields to a probe this process ran because that evidence is
+ * newer.
+ */
+export type EndpointCapacitySource = "override" | "discovered" | "discovered-prior" | "local-native-default";
+
+export interface EndpointCapacity {
+	key: string;
+	label: string;
+	limit: number;
+	source: EndpointCapacitySource;
+}
+
+/** Endpoint priors keyed by canonical endpoint key. */
+export type EndpointSlotPriors = Readonly<Record<string, DiscoveredEndpointSlots>>;
+
+/** Runtime ids whose request schedulers are intentionally not modeled as fixed local slots. */
+const UNBOUNDED_LOCAL_NATIVE_RUNTIMES = new Set(["vllm", "sglang"]);
+
+/**
+ * Canonical identity of the inference scheduler behind a configured target.
+ * Scheme, normalized host and port, and normalized base path participate. DNS
+ * aliases do not collapse because Clio cannot prove they reach the same server.
+ */
+export function canonicalEndpointKey(value: TargetDescriptor | string): string | null {
+	return canonicalEndpointUrl(typeof value === "string" ? value : value.url);
+}
+
+/** Compact operator-facing identity. A non-root base path remains visible. */
+export function endpointLabel(endpointKey: string): string {
+	try {
+		const url = new URL(endpointKey);
+		return `${url.host}${url.pathname === "/" ? "" : url.pathname}`;
+	} catch {
+		return endpointKey;
+	}
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+/** The runtime facts capacity resolution needs; a full descriptor satisfies it. */
+export type EndpointRuntimeIdentity = Pick<RuntimeDescriptor, "id" | "tier">;
+
+export interface EndpointCapacityInput {
+	target: TargetDescriptor;
+	/** Null when no runtime descriptor has resolved yet for `target.runtime`. */
+	runtime: EndpointRuntimeIdentity | null;
+	/** Slot count a probe in this process discovered, if one has landed. */
+	discoveredSlots?: number | undefined;
+}
+
+/**
+ * Resolve one endpoint's concurrency bound.
+ *
+ * The order is the whole contract, because it is what makes the answer
+ * independent of when it is asked:
+ *
+ *   1. `maxConcurrentRequests` on the target. The operator said so.
+ *   2. A probe this process ran.
+ *   3. A probe a previous process ran and persisted, still inside its
+ *      staleness bound and still describing the same runtime.
+ *   4. The conservative local-native default of one slot.
+ *
+ * Steps 2 and 3 answer with the same number for the same server, so a dispatch
+ * typed one second after boot and one typed a minute later resolve identically.
+ * Runtimes whose schedulers are not fixed local slots stay unbounded (null).
+ */
+export function endpointCapacityFor(
+	input: EndpointCapacityInput,
+	priors: EndpointSlotPriors = readDiscoveredEndpointSlots(),
+): EndpointCapacity | null {
+	const key = canonicalEndpointKey(input.target);
+	if (key === null) return null;
+	const label = endpointLabel(key);
+	const override = positiveInteger(input.target.maxConcurrentRequests);
+	if (override !== undefined) return { key, label, limit: override, source: "override" };
+	const discovered = positiveInteger(input.discoveredSlots);
+	if (discovered !== undefined) return { key, label, limit: discovered, source: "discovered" };
+	const prior = priors[key];
+	// A record written by another runtime describes another server that once
+	// answered on this host and port, which is not evidence about this one.
+	if (prior !== undefined && prior.runtimeId === (input.runtime?.id ?? input.target.runtime)) {
+		return { key, label, limit: prior.slots, source: "discovered-prior" };
+	}
+	if (input.runtime?.tier !== "local-native" || UNBOUNDED_LOCAL_NATIVE_RUNTIMES.has(input.runtime.id)) return null;
+	return { key, label, limit: 1, source: "local-native-default" };
+}
+
+/** Resolve the endpoint bound from configuration, discovery, priors, or the local-native fallback. */
+export function endpointCapacityForStatus(
+	status: TargetStatus,
+	priors: EndpointSlotPriors = readDiscoveredEndpointSlots(),
+): EndpointCapacity | null {
+	return endpointCapacityFor(
+		{
+			target: status.target,
+			runtime: status.runtime ?? null,
+			discoveredSlots: status.probeCapabilities?.parallelSlots,
+		},
+		priors,
+	);
+}
+
+function sourceRank(source: EndpointCapacitySource): number {
+	switch (source) {
+		case "override":
+			return 3;
+		case "discovered":
+			return 2;
+		case "discovered-prior":
+			return 1;
+		default:
+			return 0;
+	}
+}
+
+/** Strongest evidence wins; among equals the smaller bound wins. */
+function foldCapacity(capacities: Record<string, EndpointCapacity>, candidate: EndpointCapacity | null): void {
+	if (candidate === null) return;
+	const current = capacities[candidate.key];
+	if (
+		current === undefined ||
+		sourceRank(candidate.source) > sourceRank(current.source) ||
+		(sourceRank(candidate.source) === sourceRank(current.source) && candidate.limit < current.limit)
+	) {
+		capacities[candidate.key] = candidate;
+	}
+}
+
+/** Resolve one conservative limit per scheduler, preferring an explicit override. */
+export function endpointCapacitiesForStatuses(
+	statuses: ReadonlyArray<TargetStatus>,
+): Readonly<Record<string, EndpointCapacity>> {
+	const priors = readDiscoveredEndpointSlots();
+	const capacities: Record<string, EndpointCapacity> = {};
+	for (const status of statuses) foldCapacity(capacities, endpointCapacityForStatus(status, priors));
+	return capacities;
+}
+
+/**
+ * Every endpoint the configured fleet can reach, whether or not a probe has
+ * built a status for it yet.
+ *
+ * Resolving from `statuses` alone made the endpoint set depend on how far
+ * provider startup had progressed. An endpoint missing from that set carries no
+ * limit, and a capacity check with no limit is not a conservative check, it is
+ * no check: a plan needing two slots on a one-slot server was admitted whole
+ * when it was typed before the provider domain had finished building statuses,
+ * and denied afterwards. Configured targets fill the gap so the set is the same
+ * at both moments.
+ */
+export function resolveEndpointCapacities(input: {
+	statuses: ReadonlyArray<TargetStatus>;
+	targets?: ReadonlyArray<TargetDescriptor>;
+	runtimeFor?: (runtimeId: string) => EndpointRuntimeIdentity | null | undefined;
+}): Readonly<Record<string, EndpointCapacity>> {
+	const priors = readDiscoveredEndpointSlots();
+	const capacities: Record<string, EndpointCapacity> = {};
+	const covered = new Set<string>();
+	for (const status of input.statuses) {
+		covered.add(status.target.id);
+		foldCapacity(capacities, endpointCapacityForStatus(status, priors));
+	}
+	for (const target of input.targets ?? []) {
+		if (covered.has(target.id)) continue;
+		foldCapacity(
+			capacities,
+			endpointCapacityFor({ target, runtime: input.runtimeFor?.(target.runtime) ?? null }, priors),
+		);
+	}
+	return capacities;
+}
+
+/**
+ * Persist what a live probe just learned about this target's endpoint so the
+ * next process starts with the count instead of the blind default. A status
+ * with no probed slot count writes nothing: absence is not an observation, and
+ * overwriting a good record with silence would lose the fact this exists to
+ * keep.
+ */
+export function recordEndpointSlotsFromStatus(
+	status: TargetStatus,
+	options?: { nowMs?: number; onError?: (error: unknown) => void },
+): Promise<void> {
+	const key = canonicalEndpointKey(status.target);
+	const slots = positiveInteger(status.probeCapabilities?.parallelSlots);
+	const runtimeId = status.runtime?.id ?? status.target.runtime;
+	if (key === null || slots === undefined || runtimeId === undefined) return Promise.resolve();
+	return recordDiscoveredEndpointSlots({ endpointKey: key, runtimeId, slots }, options);
+}
+
+/**
+ * The orchestrator's own request lives only in this process. It deliberately
+ * never enters dispatch-admission.json because process exit releases it.
+ */
+const foregroundStreams = new Map<string, number>();
+
+export function registerForegroundStream(endpointKey: string): () => void {
+	foregroundStreams.set(endpointKey, (foregroundStreams.get(endpointKey) ?? 0) + 1);
+	let held = true;
+	return () => {
+		if (!held) return;
+		held = false;
+		const next = (foregroundStreams.get(endpointKey) ?? 1) - 1;
+		if (next <= 0) foregroundStreams.delete(endpointKey);
+		else foregroundStreams.set(endpointKey, next);
+	};
+}
+
+export function foregroundStreamUsage(): Readonly<Record<string, number>> {
+	return Object.fromEntries(foregroundStreams);
+}

package/src/domains/providers/endpoint-slots-store.ts

@@ -0,0 +1,189 @@
+/**
+ * Durable endpoint slot discovery.
+ *
+ * On-disk layout under `clioStateDir()`:
+ *   endpoint-slots.json          { version: 1, endpoints: { <canonical key>: record } }
+ *
+ * A probe that reads a server's own parallel slot count learns a fact about a
+ * machine, not about the process that asked. Holding it in memory made every
+ * fresh process start ignorant, so a four-slot llama.cpp server resolved at the
+ * conservative local-native default of 1 until something in that process
+ * happened to probe it again. This file is what carries the count across
+ * process boundaries.
+ *
+ * Conventions follow the rest of dispatch state (see dispatch/state.ts and
+ * dispatch/assignment-store.ts): reads are lock-free and tolerate a partially
+ * written or foreign-versioned file by answering empty, writes take the shared
+ * cross-process `withStateFileLock` on the target path and land through the
+ * canonical atomic writer.
+ *
+ * Three things bound what a persisted count may claim:
+ *
+ *   1. Age. A record older than {@link endpointSlotsTtlMs} is not returned and
+ *      is pruned by the next write. A server restarted with a different
+ *      `--parallel` must not keep over-admitting against yesterday's number.
+ *   2. Runtime identity. The record names the runtime that observed it. A
+ *      different inference server now listening on the same host and port is a
+ *      different scheduler, and its predecessor's slot count says nothing about
+ *      it.
+ *   3. Precedence. A fresh probe in this process always outranks the record,
+ *      and an explicit `maxConcurrentRequests` outranks both. See
+ *      endpoint-capacity.ts.
+ *
+ * Reads are deliberately uncached. The file holds at most
+ * MAX_ENDPOINT_SLOT_RECORDS small rows, callers read it once per capacity
+ * resolution rather than once per target, and a cache keyed on mtime would
+ * reintroduce exactly the kind of timing-dependent answer this file exists to
+ * remove.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { withStateFileLock } from "../../core/state-file-lock.js";
+import { clioStateDir, stateRootRemoved } from "../../core/xdg.js";
+
+/**
+ * How long a persisted slot count may answer for an endpoint nothing has
+ * probed in this process. A day spans an ordinary working session while still
+ * expiring across the reconfigure-and-restart cycle that changes the number.
+ */
+export const DEFAULT_ENDPOINT_SLOTS_TTL_MS = 24 * 60 * 60 * 1000;
+
+export const ENDPOINT_SLOTS_TTL_ENV_VAR = "CLIO_CODER_ENDPOINT_SLOTS_TTL_MS";
+
+/** Bounded ring. An operator's target list is small; a runaway file is not. */
+const MAX_ENDPOINT_SLOT_RECORDS = 64;
+
+export interface DiscoveredEndpointSlots {
+	/** Canonical endpoint key, as produced by `canonicalEndpointKey`. */
+	endpointKey: string;
+	/** Runtime that observed the count. A different runtime invalidates it. */
+	runtimeId: string;
+	slots: number;
+	observedAt: string;
+}
+
+interface EndpointSlotsFile {
+	version: 1;
+	endpoints: Record<string, DiscoveredEndpointSlots>;
+}
+
+export function endpointSlotsPath(): string {
+	return join(clioStateDir(), "endpoint-slots.json");
+}
+
+/** env override > built-in default, mirroring core/guardrails.ts resolution order. */
+export function endpointSlotsTtlMs(env: NodeJS.ProcessEnv = process.env): number {
+	const raw = env[ENDPOINT_SLOTS_TTL_ENV_VAR]?.trim();
+	if (raw !== undefined && /^[1-9]\d*$/.test(raw)) {
+		const parsed = Number(raw);
+		if (Number.isSafeInteger(parsed)) return parsed;
+	}
+	return DEFAULT_ENDPOINT_SLOTS_TTL_MS;
+}
+
+function validRecord(key: string, value: unknown): value is DiscoveredEndpointSlots {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Partial<DiscoveredEndpointSlots>;
+	return (
+		record.endpointKey === key &&
+		typeof record.runtimeId === "string" &&
+		record.runtimeId.length > 0 &&
+		typeof record.slots === "number" &&
+		Number.isInteger(record.slots) &&
+		record.slots > 0 &&
+		typeof record.observedAt === "string" &&
+		Number.isFinite(Date.parse(record.observedAt))
+	);
+}
+
+/** Every well-formed row on disk, regardless of age. */
+function readRecords(): DiscoveredEndpointSlots[] {
+	const path = endpointSlotsPath();
+	if (!existsSync(path)) return [];
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as EndpointSlotsFile;
+		if (parsed?.version !== 1 || typeof parsed.endpoints !== "object" || parsed.endpoints === null) return [];
+		return Object.entries(parsed.endpoints)
+			.filter(([key, value]) => validRecord(key, value))
+			.map(([, value]) => ({ ...value }));
+	} catch {
+		// A truncated or hand-edited file cannot bound anything. Answering empty
+		// falls back to the conservative default rather than to a guess.
+		return [];
+	}
+}
+
+function fresh(record: DiscoveredEndpointSlots, nowMs: number, ttlMs: number): boolean {
+	const observedMs = Date.parse(record.observedAt);
+	// A stamp from the future is a clock that moved, not evidence of freshness.
+	return observedMs <= nowMs && nowMs - observedMs < ttlMs;
+}
+
+/**
+ * The slot counts a new process may treat as priors: well-formed, and observed
+ * inside the staleness bound. Keyed by canonical endpoint key.
+ */
+export function readDiscoveredEndpointSlots(options?: {
+	nowMs?: number;
+	ttlMs?: number;
+}): Readonly<Record<string, DiscoveredEndpointSlots>> {
+	const nowMs = options?.nowMs ?? Date.now();
+	const ttlMs = options?.ttlMs ?? endpointSlotsTtlMs();
+	const out: Record<string, DiscoveredEndpointSlots> = {};
+	for (const record of readRecords()) {
+		if (!fresh(record, nowMs, ttlMs)) continue;
+		out[record.endpointKey] = record;
+	}
+	return Object.freeze(out);
+}
+
+function writeRecords(records: ReadonlyArray<DiscoveredEndpointSlots>): void {
+	const kept = [...records]
+		.sort((a, b) => Date.parse(b.observedAt) - Date.parse(a.observedAt))
+		.slice(0, MAX_ENDPOINT_SLOT_RECORDS);
+	const file: EndpointSlotsFile = {
+		version: 1,
+		endpoints: Object.fromEntries(kept.map((record) => [record.endpointKey, { ...record }])),
+	};
+	safeResourceWrite(endpointSlotsPath(), `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8" });
+}
+
+/**
+ * Record what a probe just learned about one endpoint. A fresh observation
+ * always replaces the stored one, including downward: a server restarted with
+ * fewer slots must be able to lower its own bound.
+ *
+ * Never throws. Losing a capacity prior degrades a later process to the
+ * conservative default; failing a probe over it would be worse.
+ */
+export async function recordDiscoveredEndpointSlots(
+	entry: { endpointKey: string; runtimeId: string; slots: number },
+	options?: { nowMs?: number; ttlMs?: number; onError?: (error: unknown) => void },
+): Promise<void> {
+	if (!Number.isInteger(entry.slots) || entry.slots <= 0) return;
+	if (entry.endpointKey.length === 0 || entry.runtimeId.length === 0) return;
+	// Checked before the lock because acquiring it recreates the state root, and
+	// again under it because an uninstall can land while this call waits.
+	if (stateRootRemoved()) return;
+	const nowMs = options?.nowMs ?? Date.now();
+	const ttlMs = options?.ttlMs ?? endpointSlotsTtlMs();
+	try {
+		await withStateFileLock(endpointSlotsPath(), () => {
+			if (stateRootRemoved()) return;
+			const kept = readRecords().filter(
+				(record) => record.endpointKey !== entry.endpointKey && fresh(record, nowMs, ttlMs),
+			);
+			kept.push({
+				endpointKey: entry.endpointKey,
+				runtimeId: entry.runtimeId,
+				slots: entry.slots,
+				observedAt: new Date(nowMs).toISOString(),
+			});
+			writeRecords(kept);
+		});
+	} catch (error) {
+		options?.onError?.(error);
+	}
+}

package/src/domains/providers/extension.ts

@@ -11,12 +11,14 @@ import { mergeCapabilities } from "./capabilities.js";
 import { capabilitiesFromCatalogModel, getCatalogModelForRuntime } from "./catalog.js";
 import type { ContextWindowProvenance, ProvidersContract, TargetHealth, TargetStatus } from "./contract.js";
 import { credentialsPresent } from "./credentials.js";
+import { recordEndpointSlotsFromStatus } from "./endpoint-capacity.js";
 import { resolveProviderKnowledgeBaseRoots } from "./knowledge-base-path.js";
 import { probeCapabilitiesForModel } from "./model-capabilities.js";
 import { loadPluginRuntimes } from "./plugins.js";
 import { getRuntimeRegistry } from "./registry.js";
 import { registerBuiltinRuntimes } from "./runtimes/builtins.js";
 import { listKnownModelsForRuntime } from "./support.js";
+import { readTargetModelSnapshot, recordTargetModelSnapshot } from "./target-model-cache.js";
 import type { CapabilityFlags } from "./types/capability-flags.js";
 import { EMPTY_CAPABILITIES } from "./types/capability-flags.js";
 import {
@@ -133,10 +135,12 @@ function discoveredModelsSource(
 	probe: ProbeResult | null,
 	preservePreviousProbe: boolean,
 	previous: TargetStatus | undefined,
+	cachedModels: ReadonlyArray<string>,
 	desc: RuntimeDescriptor,
 ): "probe" | "cache" | "runtime" | "none" {
 	if (probe?.models !== undefined) return "probe";
 	if (preservePreviousProbe && previous?.discoveredModels && previous.discoveredModels.length > 0) return "cache";
+	if (cachedModels.length > 0) return "cache";
 	if (desc.knownModels && desc.knownModels.length > 0) return "runtime";
 	return "none";
 }
@@ -174,6 +178,7 @@ export function mergeProbeResult(
 	target: TargetDescriptor,
 	probe: ProbeResult | null,
 	previous: TargetStatus | undefined,
+	cachedModels: ReadonlyArray<string> = [],
 ): ProbeMerge {
 	const probeSucceeded = probe?.ok ?? false;
 	const preservePrevious = !probeSucceeded && previous !== undefined && sameProbeIdentity(previous.target, target);
@@ -189,12 +194,16 @@ export function mergeProbeResult(
 		probe?.notes && probe.notes.length > 0 ? probe.notes : preservePrevious ? previous.probeNotes : undefined;
 	const probeSurfaces = probe?.surfaces ?? (preservePrevious ? previous.probeSurfaces : undefined);
 	const discoveredModels = uniqueModels(
-		probe?.models ?? (preservePrevious ? previous.discoveredModels : undefined) ?? desc.knownModels ?? [],
+		probe?.models ??
+			(preservePrevious ? previous.discoveredModels : undefined) ??
+			(cachedModels.length > 0 ? cachedModels : undefined) ??
+			desc.knownModels ??
+			[],
 	);
 	const discoveredModelStates = probe?.modelStates ?? (preservePrevious ? previous.discoveredModelStates : null) ?? null;
 	const merge: ProbeMerge = {
 		discoveredModels,
-		discoveredModelsSource: discoveredModelsSource(probe, preservePrevious, previous, desc),
+		discoveredModelsSource: discoveredModelsSource(probe, preservePrevious, previous, cachedModels, desc),
 		discoveredModelStates,
 		probeCapabilities,
 		probeModelCapabilities,
@@ -316,7 +325,8 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			return out;
 		}
 		const availability = availabilityFor(desc, target, authStatusFor);
-		const merge = mergeProbeResult(desc, target, probe, previous);
+		const cachedModels = readTargetModelSnapshot(target)?.models ?? [];
+		const merge = mergeProbeResult(desc, target, probe, previous, cachedModels);
 		const { capabilities, contextWindowProvenance } = capabilitiesFor(desc, target, merge, kb);
 		const healthy = probe !== null ? probe.ok : null;
 		const unservedDefault = probe?.ok ? unservedDefaultModelReason(desc, target, merge) : null;
@@ -414,6 +424,13 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		}
 		const status = buildStatus(target, desc, probeResult, previous);
 		statuses.set(target.id, status);
+		if (probeResult.ok && probeResult.models !== undefined) {
+			recordTargetModelSnapshot(target, probeResult.models);
+		}
+		// Durable so the next process resolves this endpoint's real slot count
+		// instead of the conservative default. Fire and forget: the probe's answer
+		// is already in `statuses`, and a failed write must not fail the probe.
+		void recordEndpointSlotsFromStatus(status);
 		context.bus.emit(BusChannels.ProviderHealth, { id: target.id, status });
 		return status;
 	}