@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/domains/mux/yazi/theme.ts

@@ -0,0 +1,30 @@
+import { tokenHex } from "../../../core/theme-token-hex.js";
+
+/** Render the deliberately small Clio overlay on Yazi's pinned preset theme. */
+export function renderYaziTheme(): string {
+	return `# Generated by Clio Coder. Changes are replaced when the managed profile regenerates.
+
+[mgr]
+cwd = { fg = "${tokenHex("accent")}" }
+find_keyword = { fg = "${tokenHex("warning")}" }
+marker_selected = { fg = "${tokenHex("success")}", bg = "${tokenHex("success")}" }
+marker_copied = { fg = "${tokenHex("accent")}", bg = "${tokenHex("accent")}" }
+marker_cut = { fg = "${tokenHex("error")}", bg = "${tokenHex("error")}" }
+border_style = { fg = "${tokenHex("frame")}" }
+
+[mode]
+normal_main = { bg = "${tokenHex("accent")}" }
+normal_alt = { fg = "${tokenHex("accent")}" }
+select_main = { bg = "${tokenHex("action")}" }
+select_alt = { fg = "${tokenHex("action")}" }
+unset_main = { bg = "${tokenHex("error")}" }
+unset_alt = { fg = "${tokenHex("error")}" }
+
+[tabs]
+active = { bg = "${tokenHex("accent")}" }
+inactive = { fg = "${tokenHex("accent")}" }
+
+[status]
+perm_sep = { fg = "${tokenHex("dim")}" }
+`;
+}

package/src/domains/observability/cost.ts

@@ -101,6 +101,27 @@ export function costAggregateForAmount(usd: number, provenance: CostProvenance |
 	return aggregateCostAmounts([{ usd, provenance: normalizeCostProvenance(provenance) }]);
 }
 
+/**
+ * What a fixed-width surface renders for an already-folded aggregate: the cost
+ * claim when one exists, {@link COST_NOT_MEASURED} when none does. Named here
+ * because the fallback is part of the derivation, not a caller's choice, and a
+ * surface that spells the `?? COST_NOT_MEASURED` out by hand is one edit away
+ * from spelling `$0.00` instead.
+ */
+export function renderCostAggregate(cost: CostAggregate | null | undefined): string {
+	return formatCostAggregate(cost) ?? COST_NOT_MEASURED;
+}
+
+/**
+ * The same render for a single sealed amount, which is the shape a receipt or a
+ * ledger row hands over. A caller that reaches for `usd.toFixed(4)` here drops
+ * the provenance on the floor and turns unpriced work into a measured `$0.0000`,
+ * which is a claim nobody made.
+ */
+export function renderCostAmount(usd: number, provenance: CostProvenance | undefined): string {
+	return renderCostAggregate(costAggregateForAmount(usd, provenance));
+}
+
 export interface UsageBreakdown {
 	input: number;
 	output: number;

package/src/domains/observability/index.ts

@@ -42,6 +42,8 @@ export {
 	costWasMeasured,
 	emptyCostAggregate,
 	formatCostAggregate,
+	renderCostAggregate,
+	renderCostAmount,
 	type UsageBreakdown,
 } from "./cost.js";
 export type { EvidenceIndexRow } from "./evidence-index.js";

package/src/domains/observability/trace-store.ts

@@ -1212,6 +1212,48 @@ export class TraceReader {
 			) as unknown as TraceEventRow[];
 	}
 
+	/**
+	 * Per-kind event tallies for one run.
+	 *
+	 * Aggregated in SQL rather than by reading rows, so `payload_json` and the
+	 * free-form event name are never loaded at all. That is the point: a caller
+	 * that only ever wants shapes should not be holding the payloads in memory
+	 * on the way to counting them.
+	 */
+	eventKindCounts(runId: string): Array<{ type: string; count: number }> {
+		return this.db
+			.prepare("SELECT type, COUNT(*) AS count FROM events WHERE run_id=? GROUP BY type ORDER BY count DESC, type")
+			.all(runId) as unknown as Array<{ type: string; count: number }>;
+	}
+
+	/** Total events and the wall span they cover, without reading one of them. */
+	eventSpan(runId: string): { total: number; firstAt: string | null; lastAt: string | null } {
+		const row = this.db
+			.prepare(
+				`SELECT COUNT(*) AS total, MIN(started_at) AS firstAt,
+					MAX(COALESCE(ended_at, started_at)) AS lastAt FROM events WHERE run_id=?`,
+			)
+			.get(runId) as unknown as { total: number; firstAt: string | null; lastAt: string | null } | undefined;
+		return row ?? { total: 0, firstAt: null, lastAt: null };
+	}
+
+	/**
+	 * Per-kind process tallies for one run.
+	 *
+	 * Same reason as {@link eventKindCounts}, and more sharply: a process row
+	 * carries the command line, the pid, and the host, none of which a shape
+	 * count needs.
+	 */
+	processKindCounts(runId: string): Array<{ kind: string; total: number; running: number }> {
+		return this.db
+			.prepare(
+				`SELECT kind, COUNT(*) AS total,
+					SUM(CASE WHEN ended_at IS NULL THEN 1 ELSE 0 END) AS running
+				 FROM processes WHERE run_id=? GROUP BY kind ORDER BY total DESC, kind`,
+			)
+			.all(runId) as unknown as Array<{ kind: string; total: number; running: number }>;
+	}
+
 	processes(runId: string): TraceProcessRow[] {
 		return this.db
 			.prepare("SELECT * FROM processes WHERE run_id=? ORDER BY ended_at IS NOT NULL, id")

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

@@ -1,8 +1,22 @@
 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";
 
-export type EndpointCapacitySource = "override" | "discovered" | "local-native-default";
+/**
+ * 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;
@@ -11,6 +25,9 @@ export interface EndpointCapacity {
 	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"]);
 
@@ -37,42 +54,157 @@ function positiveInteger(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
 }
 
-/** Resolve the endpoint bound from configuration, cached discovery, or the local-native fallback. */
-export function endpointCapacityForStatus(status: TargetStatus): EndpointCapacity | null {
-	const key = canonicalEndpointKey(status.target);
+/** 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 override = positiveInteger(status.target.maxConcurrentRequests);
-	if (override !== undefined) return { key, label: endpointLabel(key), limit: override, source: "override" };
-	const discovered = positiveInteger(status.probeCapabilities?.parallelSlots);
-	if (discovered !== undefined) return { key, label: endpointLabel(key), limit: discovered, source: "discovered" };
-	if (status.runtime?.tier !== "local-native" || UNBOUNDED_LOCAL_NATIVE_RUNTIMES.has(status.runtime.id)) return null;
-	return { key, label: endpointLabel(key), limit: 1, source: "local-native-default" };
+	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 {
-	return source === "override" ? 2 : source === "discovered" ? 1 : 0;
+	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> = {};
-	for (const status of statuses) {
-		const candidate = endpointCapacityForStatus(status);
-		if (candidate === null) continue;
-		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;
-		}
+	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.

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;
 	}

package/src/domains/providers/index.ts

@@ -30,13 +30,28 @@ export { isDispatchEligibleRuntime, isOrchestratorEligibleRuntime, isTargetEligi
 export {
 	canonicalEndpointKey,
 	type EndpointCapacity,
+	type EndpointCapacityInput,
 	type EndpointCapacitySource,
+	type EndpointRuntimeIdentity,
+	type EndpointSlotPriors,
 	endpointCapacitiesForStatuses,
+	endpointCapacityFor,
 	endpointCapacityForStatus,
 	endpointLabel,
 	foregroundStreamUsage,
+	recordEndpointSlotsFromStatus,
 	registerForegroundStream,
+	resolveEndpointCapacities,
 } from "./endpoint-capacity.js";
+export {
+	DEFAULT_ENDPOINT_SLOTS_TTL_MS,
+	type DiscoveredEndpointSlots,
+	ENDPOINT_SLOTS_TTL_ENV_VAR,
+	endpointSlotsPath,
+	endpointSlotsTtlMs,
+	readDiscoveredEndpointSlots,
+	recordDiscoveredEndpointSlots,
+} from "./endpoint-slots-store.js";
 export { ProvidersManifest } from "./manifest.js";
 export type { ModelCapabilityPatchTarget } from "./model-capabilities.js";
 export { applyModelCapabilityPatch, resolveModelCapabilities } from "./model-capabilities.js";
@@ -126,6 +141,13 @@ export {
 	runtimeModelListSource,
 	supportGroupLabel,
 } from "./support.js";
+export {
+	readTargetModelSnapshot,
+	recordTargetModelSnapshot,
+	TARGET_MODEL_CACHE_TTL_MS,
+	type TargetModelSnapshot,
+	targetModelSnapshotPath,
+} from "./target-model-cache.js";
 export type {
 	CapabilityFlags,
 	StructuredOutputMode,