@iowarp/clio-coder 0.3.9 → 0.4.1

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 {
@@ -86,7 +88,7 @@ function positiveWindow(value: unknown): number | undefined {
  * `n_ctx: 0` still discovers the window it did publish, instead of silently
  * falling back to the runtime descriptor's placeholder.
  */
-export function capabilitiesFor(
+function capabilitiesFor(
 	desc: RuntimeDescriptor,
 	target: TargetDescriptor,
 	probe: ProbeMerge,
@@ -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";
 }
@@ -169,11 +173,12 @@ export interface ProbeMerge {
  * `cache`, while health and availability (decided by the caller from `probe`)
  * reflect the failure. Only a successful probe replaces the catalog.
  */
-export function mergeProbeResult(
+function mergeProbeResult(
 	desc: RuntimeDescriptor,
 	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,
@@ -215,7 +224,7 @@ export function mergeProbeResult(
  * Returns the reason when the default is not served, null when it is or when
  * there is no live evidence either way.
  */
-export function unservedDefaultModelReason(
+function unservedDefaultModelReason(
 	desc: Pick<RuntimeDescriptor, "id">,
 	target: Pick<TargetDescriptor, "defaultModel">,
 	merge: Pick<ProbeMerge, "discoveredModels" | "discoveredModelsSource" | "discoveredModelStates">,
@@ -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;
@@ -386,7 +396,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		}
 		if (probeResult.ok && options?.reasoning !== false && typeof desc.probeReasoning === "function") {
 			const settings = readConfig();
-			const orchestratorTarget = settings.orchestrator.target === target.id ? settings.orchestrator.model : null;
+			const orchestratorTarget = settings.chat.target === target.id ? settings.chat.model : null;
 			const candidateModelId = orchestratorTarget ?? target.defaultModel ?? null;
 			if (candidateModelId) {
 				try {
@@ -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;
 	}
@@ -465,7 +482,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			registerClioOAuthProviders();
 			registerBuiltinRuntimes(registry);
 			const settings = readConfig();
-			setGlobalDefaultMaxOutputTokens(settings.defaults.maxTokens);
+			setGlobalDefaultMaxOutputTokens(settings.chat.maxOutputTokens);
 			await loadPluginRuntimes(registry, settings);
 			await probeAll();
 			const config = context.getContract<ConfigContract>("config");

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,

package/src/domains/providers/knowledge-base-path.ts

@@ -72,7 +72,7 @@ function envOverlayDirs(): string[] {
 		.filter((entry) => entry.length > 0);
 }
 
-export function resolveProviderModelCatalogDirs(
+function resolveProviderModelCatalogDirs(
 	importMetaUrl: string,
 	options: { cwd?: string } = {},
 ): ProviderModelCatalogDirs {

package/src/domains/providers/model-runtime-capabilities.ts

@@ -1,3 +1,4 @@
+import { warnLegacyNaming } from "../../core/naming-compat.js";
 import type { Api, Model } from "../../engine/types.js";
 import { getCatalogModelForRuntime } from "./catalog.js";
 import type { ProvidersContract, TargetStatus } from "./contract.js";
@@ -111,10 +112,19 @@ function capabilityHints(input: {
 }
 
 interface ClioRuntimeMetadata {
+	clioCoder?: {
+		targetId?: string;
+		runtimeId?: string;
+		lifecycle?: "user-managed" | "clio-coder-managed";
+		gateway?: boolean;
+		family?: string;
+		quirks?: LocalModelQuirks;
+	};
+	/** Released in-memory metadata name accepted at plugin/runtime read boundaries. */
 	clio?: {
 		targetId?: string;
 		runtimeId?: string;
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		family?: string;
 		quirks?: LocalModelQuirks;
@@ -178,6 +188,38 @@ export function harmonyReasoningEffort(level: string | undefined): HarmonyReason
  */
 export type ReasoningClass = "never" | "switchable" | "always";
 
+/**
+ * Minimum completion room for a memory envelope on an always-on-thinking
+ * model. A 9B local route has been measured reasoning for more than 1,800
+ * tokens before its first `<operations>` byte, while an always-on 35B spent a
+ * 400-token allowance entirely on reasoning and ended at length. Four thousand
+ * leaves the configured 2,000-token content budget after that preamble.
+ */
+export const MEMORY_ALWAYS_ON_MODEL_MIN_OUTPUT_TOKENS = 4_000;
+
+/**
+ * Derive the memory step's request budget from the resolved model capability.
+ * Switchable models are requested with thinking off and need only the normal
+ * content budget. An always-on mechanism cannot honor that request, so it gets
+ * explicit reasoning headroom. The runtime's known cap remains authoritative.
+ */
+export function memoryInterventionModelMaxTokens(input: {
+	configuredMaxTokens: number;
+	thinkingMechanism: ThinkingMechanism;
+	modelMaxTokens?: number;
+}): number {
+	const configured =
+		Number.isSafeInteger(input.configuredMaxTokens) && input.configuredMaxTokens > 0 ? input.configuredMaxTokens : 1;
+	const requested =
+		input.thinkingMechanism === "always-on"
+			? Math.max(configured * 2, MEMORY_ALWAYS_ON_MODEL_MIN_OUTPUT_TOKENS)
+			: configured;
+	const modelCap = input.modelMaxTokens;
+	return typeof modelCap === "number" && Number.isSafeInteger(modelCap) && modelCap > 0
+		? Math.min(requested, modelCap)
+		: requested;
+}
+
 export function reasoningClassForMechanism(mechanism: ThinkingMechanism | null | undefined): ReasoningClass {
 	if (mechanism === "none") return "never";
 	if (mechanism === "always-on") return "always";
@@ -659,7 +701,9 @@ export function resolveModelRuntimeCapabilitiesForModel<TApi extends Api>(
 	model: Model<TApi>,
 	configuredThinkingLevel?: ThinkingLevel,
 ): ResolvedModelRuntimeCapabilities {
-	const metadata = (model as Model<TApi> & ClioRuntimeMetadata).clio;
+	const runtimeModel = model as Model<TApi> & ClioRuntimeMetadata;
+	if (runtimeModel.clio !== undefined) warnLegacyNaming("model.clio", "model.clioCoder");
+	const metadata = runtimeModel.clioCoder ?? runtimeModel.clio;
 	const caps = capabilitiesFromModel(model as Model<Api> & ClioRuntimeMetadata);
 	return resolveModelRuntimeCapabilities({
 		targetId: metadata?.targetId ?? null,

package/src/domains/providers/models/cloud-models/alcf.yaml

@@ -1,7 +1,7 @@
 # ALCF (Argonne) inference-gateway model knowledge base.
 #
 # GPT-OSS models served through ALCF are already covered by the existing
-# openai-gpt-oss family in local-models/clio-local-coding-targets.yaml.
+# openai-gpt-oss family in local-models/clio-coder-local-coding-targets.yaml.
 
 - family: meta-llama-4-maverick
   matchPatterns: