@iowarp/clio-coder 0.3.9 → 0.4.0

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

@@ -178,6 +178,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";

package/src/domains/providers/runtimes/boot-manifest.ts

@@ -42,6 +42,7 @@ export const BUILTIN_RUNTIME_BOOT_MANIFEST: ReadonlyArray<RuntimeBootMetadata> =
 	{ id: "lmstudio", aliases: ["lmstudio-native"], kind: "http", tier: "local-native", auth: "api-key" },
 	{ id: "ollama-native", kind: "http", tier: "local-native", auth: "none" },
 	{ id: "anthropic-compat", kind: "http", tier: "protocol", auth: "api-key" },
+	{ id: "litellm", kind: "http", tier: "protocol", auth: "api-key" },
 	{ id: "openai-compat", kind: "http", tier: "protocol", auth: "api-key" },
 	{ id: "sglang", kind: "http", tier: "local-native", auth: "api-key" },
 	{ id: "vllm", kind: "http", tier: "local-native", auth: "api-key" },

package/src/domains/providers/runtimes/builtins.ts

@@ -36,6 +36,7 @@ import ollamaNative from "./local-native/ollama-native.js";
 import sglang from "./local-native/sglang.js";
 import vllm from "./local-native/vllm.js";
 import anthropicCompat from "./protocol/anthropic-compat.js";
+import litellm from "./protocol/litellm.js";
 import openaiCompat from "./protocol/openai-compat.js";
 
 const BUILTIN_RUNTIMES: ReadonlyArray<RuntimeDescriptor> = [
@@ -60,6 +61,7 @@ const BUILTIN_RUNTIMES: ReadonlyArray<RuntimeDescriptor> = [
 	lmstudio,
 	ollamaNative,
 	anthropicCompat,
+	litellm,
 	openaiCompat,
 	sglang,
 	vllm,

package/src/domains/providers/runtimes/protocol/litellm.ts

@@ -0,0 +1,375 @@
+/**
+ * LiteLLM proxy: an OpenAI-compatible gateway that fronts a fleet.
+ *
+ * This is a separate runtime from `openai-compat` rather than a target flag on
+ * it, because a gateway answers two questions the generic protocol cannot.
+ *
+ * First, capability discovery. A gateway publishes semantic aliases: the client
+ * asks for `code` and the proxy decides that means `katcoder2.5-35b-moe` on one
+ * particular host. LiteLLM's `/v1/models` is the plain OpenAI listing, so every
+ * row flattens to a bare id and the context window, tool support, and modality
+ * of the model actually behind the alias are all erased. Reached over
+ * `openai-compat`, a 262k tool-calling coder is indistinguishable from a 4k
+ * chat toy, and Clio plans the session against its own assumed floor. LiteLLM
+ * publishes the real numbers on `/v1/model/info` instead, which is what this
+ * probe reads.
+ *
+ * Second, routed-deployment attribution. Which physical model answered is a
+ * per-response fact behind an alias, and LiteLLM returns it in `x-litellm-*`
+ * response headers. See {@link routedDeploymentFromHeaders}.
+ *
+ * Structured output is the one property worth stating explicitly, because
+ * getting it wrong is silent. `src/core/response-schema.ts` deliberately keys
+ * the schema dialect on runtime id and not on api family, since a generic
+ * OpenAI-compatible gateway answers HTTP 200 to a `response_format` spelling it
+ * does not implement and returns unconstrained JSON. LiteLLM earns its entry in
+ * that table by measurement rather than by assumption: against the homelab
+ * gateway on 2026-08-30, `{"type":"json_schema", json_schema:{...}}` was
+ * grammar-enforced end to end on both a llama.cpp upstream and an LM Studio
+ * upstream, `{"type":"json_object", schema:{...}}` was enforced on llama.cpp
+ * and rejected HTTP 400 by LM Studio, and the same prompt with no
+ * `response_format` returned plain prose. `drop_params: true` did not strip
+ * either spelling. The standard `json_schema` dialect is therefore the one that
+ * holds across every upstream, and it is what this runtime declares.
+ */
+
+import { CLIO_MIN_CONTEXT_WINDOW, CLIO_MIN_MAX_OUTPUT_TOKENS } from "../../../../core/context-floor.js";
+import type { Api, Model } from "../../../../engine/types.js";
+import { probeJson } from "../../probe/http.js";
+import type { CapabilityFlags } from "../../types/capability-flags.js";
+import type { KnowledgeBaseHit } from "../../types/knowledge-base.js";
+import type { ProbeContext, ProbeModelStatus, ProbeResult, RuntimeDescriptor } from "../../types/runtime-descriptor.js";
+import type { TargetDescriptor } from "../../types/target-descriptor.js";
+import { stripTrailingSlash, synthLocalModel, withV1 } from "../common/local-synth.js";
+
+const LITELLM_PROVIDER = "litellm";
+
+/**
+ * Conservative until the probe answers. A gateway that does not publish
+ * `model_info` has told Clio nothing, and claiming tools on a target whose tool
+ * surface is unknown produces a worker that fails on its first tool call rather
+ * than one that is never admitted.
+ */
+const defaultCapabilities: CapabilityFlags = {
+	chat: true,
+	tools: false,
+	reasoning: false,
+	vision: false,
+	audio: false,
+	embeddings: false,
+	rerank: false,
+	fim: false,
+	structuredOutputs: "json-schema",
+	contextWindow: CLIO_MIN_CONTEXT_WINDOW,
+	maxTokens: CLIO_MIN_MAX_OUTPUT_TOKENS,
+};
+
+/** The server root. This runtime's own paths carry `/v1` where they need it. */
+function rootUrl(target: TargetDescriptor): string | null {
+	if (!target.url) return null;
+	const trimmed = stripTrailingSlash(target.url);
+	return trimmed.endsWith("/v1") ? trimmed.slice(0, -"/v1".length) : trimmed;
+}
+
+function bearerHeaders(target: TargetDescriptor, ctx: ProbeContext): Record<string, string> {
+	const headers: Record<string, string> = { ...(target.auth?.headers ?? {}) };
+	const envName = target.auth?.apiKeyEnvVar;
+	const fromEnv = envName && ctx.credentialsPresent.has(envName) ? process.env[envName]?.trim() : undefined;
+	const token = ctx.authToken?.trim() || fromEnv;
+	if (token) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
+
+interface LiteLLMModelInfoRow {
+	model_name?: unknown;
+	litellm_params?: { model?: unknown; api_base?: unknown };
+	model_info?: Record<string, unknown>;
+}
+
+interface LiteLLMModelInfoResponse {
+	data?: ReadonlyArray<LiteLLMModelInfoRow>;
+}
+
+interface LiteLLMModelsResponse {
+	data?: ReadonlyArray<{ id?: unknown }>;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+function boolean(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+/**
+ * Project one LiteLLM `model_info` block onto Clio's capability flags.
+ *
+ * Only fields the gateway actually filled in are returned. A `model_info` that
+ * declares nothing leaves the whole record empty rather than reporting zeros,
+ * so the caller can tell "the gateway says this model has no vision" apart from
+ * "the gateway did not say", and merge accordingly.
+ */
+export function capabilitiesFromLiteLLMModelInfo(info: Record<string, unknown>): Partial<CapabilityFlags> {
+	const caps: Partial<CapabilityFlags> = {};
+	const contextWindow = positiveInteger(info.max_input_tokens) ?? positiveInteger(info.max_tokens);
+	if (contextWindow !== undefined) caps.contextWindow = contextWindow;
+	const maxTokens = positiveInteger(info.max_output_tokens);
+	if (maxTokens !== undefined) caps.maxTokens = maxTokens;
+	const tools = boolean(info.supports_function_calling);
+	if (tools !== undefined) caps.tools = tools;
+	const vision = boolean(info.supports_vision);
+	if (vision !== undefined) caps.vision = vision;
+	const reasoning = boolean(info.supports_reasoning);
+	if (reasoning !== undefined) caps.reasoning = reasoning;
+	const audio = boolean(info.supports_audio_input);
+	if (audio !== undefined) caps.audio = audio;
+	// `mode` is LiteLLM's own surface discriminator. An embedding deployment is
+	// not a chat deployment, and admitting it as one produces a run that fails
+	// at the first completion rather than at selection.
+	if (info.mode === "embedding") {
+		caps.chat = false;
+		caps.embeddings = true;
+	}
+	if (info.mode === "rerank") {
+		caps.chat = false;
+		caps.rerank = true;
+	}
+	if (info.mode === "chat") caps.chat = true;
+	// Measured, not inferred: see the module header.
+	if (boolean(info.supports_response_schema) === true) caps.structuredOutputs = "json-schema";
+	return caps;
+}
+
+interface LiteLLMCatalog {
+	models: string[];
+	modelCapabilities: Record<string, Partial<CapabilityFlags>>;
+	modelStates: Record<string, ProbeModelStatus>;
+	/** Physical deployment behind each alias, for display. */
+	deployments: Record<string, { model: string; apiBase?: string }>;
+}
+
+const EMPTY_CATALOG: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+
+/**
+ * Read the catalog from `/v1/model/info`, falling back to `/v1/models`.
+ *
+ * The detail endpoint is the only one that carries capabilities, but it can be
+ * refused for a virtual key with narrower permissions than the master key. A
+ * gateway that answers the plain listing and refuses the detail is still usable;
+ * it just cannot tell Clio anything beyond which aliases exist, so the target
+ * falls back to its declared capabilities exactly as `openai-compat` would.
+ */
+async function fetchCatalog(base: string, ctx: ProbeContext, headers: Record<string, string>): Promise<LiteLLMCatalog> {
+	const detailOpts = { url: `${base}/v1/model/info`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
+	const detail = await (ctx.signal
+		? probeJson<LiteLLMModelInfoResponse>({ ...detailOpts, signal: ctx.signal })
+		: probeJson<LiteLLMModelInfoResponse>(detailOpts));
+
+	if (detail.ok && Array.isArray(detail.data?.data)) {
+		const catalog: LiteLLMCatalog = { models: [], modelCapabilities: {}, modelStates: {}, deployments: {} };
+		for (const row of detail.data.data) {
+			if (typeof row?.model_name !== "string" || row.model_name.length === 0) continue;
+			const alias = row.model_name;
+			// One alias can carry several deployments. They share a name and Clio
+			// addresses them as one model, so the first row establishes the entry
+			// and later rows for the same alias are the load-balancing pool behind
+			// it rather than separate models.
+			if (catalog.deployments[alias] !== undefined) continue;
+			catalog.models.push(alias);
+			const caps = row.model_info ? capabilitiesFromLiteLLMModelInfo(row.model_info) : {};
+			if (Object.keys(caps).length > 0) catalog.modelCapabilities[alias] = caps;
+			const upstream = row.litellm_params?.model;
+			const apiBase = row.litellm_params?.api_base;
+			catalog.deployments[alias] = {
+				model: typeof upstream === "string" ? upstream : alias,
+				...(typeof apiBase === "string" ? { apiBase } : {}),
+			};
+		}
+		if (catalog.models.length > 0) return catalog;
+	}
+
+	const listOpts = { url: `${base}/v1/models`, timeoutMs: ctx.httpTimeoutMs, headers } as const;
+	const list = await (ctx.signal
+		? probeJson<LiteLLMModelsResponse>({ ...listOpts, signal: ctx.signal })
+		: probeJson<LiteLLMModelsResponse>(listOpts));
+	if (!list.ok || !Array.isArray(list.data?.data)) return EMPTY_CATALOG;
+	const models = list.data.data
+		.map((row) => (typeof row?.id === "string" ? row.id : null))
+		.filter((id): id is string => id !== null && id.length > 0);
+	return { models, modelCapabilities: {}, modelStates: {}, deployments: {} };
+}
+
+/**
+ * The routed deployment LiteLLM reports for one response.
+ *
+ * Behind an alias the physical model is a per-request fact: a fallback, a
+ * context-window promotion, or an ordinary load-balancing choice all change it
+ * without changing what the client asked for. Reporting the alias back as the
+ * model is how a gateway hides an outage, and it is exactly what an operator
+ * needs to see. LiteLLM answers in headers on every completion.
+ */
+export interface RoutedDeployment {
+	/** The alias the client asked for, e.g. `code`. */
+	group?: string;
+	/** The physical model that answered, e.g. `openai/katcoder2.5-35b-moe`. */
+	model?: string;
+	/** The upstream that served it. */
+	apiBase?: string;
+	/** Stable id of the specific deployment inside the group. */
+	deploymentId?: string;
+	/** Non-zero when the request did not reach its first-choice deployment. */
+	attemptedFallbacks?: number;
+	attemptedRetries?: number;
+}
+
+function headerValue(headers: { get(name: string): string | null }, name: string): string | undefined {
+	const raw = headers.get(name)?.trim();
+	return raw && raw.length > 0 ? raw : undefined;
+}
+
+function headerInteger(headers: { get(name: string): string | null }, name: string): number | undefined {
+	const raw = headerValue(headers, name);
+	if (raw === undefined) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Extract the routed deployment from a LiteLLM response, or null when the
+ * headers are absent. Absent is the normal answer for every non-LiteLLM target,
+ * so callers treat null as "no attribution available" rather than an error.
+ */
+export function routedDeploymentFromHeaders(headers: { get(name: string): string | null }): RoutedDeployment | null {
+	const routed: RoutedDeployment = {};
+	const group = headerValue(headers, "x-litellm-model-group");
+	if (group !== undefined) routed.group = group;
+	const model = headerValue(headers, "x-litellm-model-name");
+	if (model !== undefined) routed.model = model;
+	const apiBase = headerValue(headers, "x-litellm-model-api-base");
+	if (apiBase !== undefined) routed.apiBase = apiBase;
+	const deploymentId = headerValue(headers, "x-litellm-model-id");
+	if (deploymentId !== undefined) routed.deploymentId = deploymentId;
+	const fallbacks = headerInteger(headers, "x-litellm-attempted-fallbacks");
+	if (fallbacks !== undefined) routed.attemptedFallbacks = fallbacks;
+	const retries = headerInteger(headers, "x-litellm-attempted-retries");
+	if (retries !== undefined) routed.attemptedRetries = retries;
+	return Object.keys(routed).length > 0 ? routed : null;
+}
+
+/**
+ * One-line attribution for a routed response.
+ *
+ * A request that fell back says so. `code -> openai/qwen3.8-27b-dense @
+ * mini.tail78f300.ts.net:8080 (fallback)` is the whole point of the runtime:
+ * the operator asked for the coder, the coder was asleep, and something else
+ * answered.
+ */
+export function formatRoutedDeployment(routed: RoutedDeployment): string {
+	const parts: string[] = [];
+	if (routed.group && routed.model && routed.group !== routed.model) {
+		parts.push(`${routed.group} -> ${routed.model}`);
+	} else if (routed.model ?? routed.group) {
+		parts.push((routed.model ?? routed.group) as string);
+	}
+	if (routed.apiBase) {
+		let host = routed.apiBase;
+		try {
+			host = new URL(routed.apiBase).host;
+		} catch {
+			// A non-URL api_base is displayed verbatim.
+		}
+		parts.push(`@ ${host}`);
+	}
+	if ((routed.attemptedFallbacks ?? 0) > 0) parts.push("(fallback)");
+	else if ((routed.attemptedRetries ?? 0) > 0) parts.push("(retried)");
+	return parts.join(" ");
+}
+
+const litellmRuntime: RuntimeDescriptor = {
+	id: "litellm",
+	displayName: "LiteLLM gateway",
+	kind: "http",
+	tier: "protocol",
+	apiFamily: "openai-completions",
+	auth: "api-key",
+	defaultCapabilities,
+
+	async probe(target: TargetDescriptor, ctx: ProbeContext): Promise<ProbeResult> {
+		const base = rootUrl(target);
+		if (!base) return { ok: false, error: "target has no url" };
+		const headers = bearerHeaders(target, ctx);
+
+		// Liveness first, and deliberately on the unauthenticated endpoint. A
+		// gateway with authentication enforced answers 401 to `/v1/models` when
+		// credentials are missing or wrong, which is indistinguishable from an
+		// unreachable host if that is the only thing probed. `/health/liveliness`
+		// separates "the gateway is down" from "this key is not valid", and the
+		// two have completely different remedies.
+		const liveOpts = { url: `${base}/health/liveliness`, timeoutMs: ctx.httpTimeoutMs } as const;
+		const live = await (ctx.signal
+			? probeJson<unknown>({ ...liveOpts, signal: ctx.signal })
+			: probeJson<unknown>(liveOpts));
+		if (!live.ok) return { ok: false, error: live.error ?? "gateway is not reachable" };
+
+		const catalog = await fetchCatalog(base, ctx, headers);
+		if (catalog.models.length === 0) {
+			const result: ProbeResult = {
+				ok: false,
+				error: "gateway is live but served no model catalog; check the target's API key",
+			};
+			if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
+			return result;
+		}
+
+		const result: ProbeResult = { ok: true, models: catalog.models };
+		if (live.latencyMs !== undefined) result.latencyMs = live.latencyMs;
+		if (Object.keys(catalog.modelCapabilities).length > 0) {
+			result.modelCapabilities = catalog.modelCapabilities;
+			const selected = target.defaultModel?.trim();
+			const selectedCaps = selected ? catalog.modelCapabilities[selected] : undefined;
+			if (selected && selectedCaps) {
+				result.discoveredCapabilities = selectedCaps;
+				result.capabilityModelId = selected;
+			}
+		}
+		const notes: string[] = [];
+		const configured = target.defaultModel?.trim();
+		if (configured && !catalog.models.includes(configured)) {
+			notes.push(`configured model '${configured}' is not in the gateway catalog`);
+		}
+		// Naming the physical model behind each alias is the difference between a
+		// catalog an operator can audit and a list of words.
+		const routed = Object.entries(catalog.deployments)
+			.map(([alias, deployment]) => `${alias}=${deployment.model}`)
+			.sort();
+		if (routed.length > 0) notes.push(`routes: ${routed.join(", ")}`);
+		if (notes.length > 0) result.notes = notes;
+		return result;
+	},
+
+	async probeModels(target: TargetDescriptor, ctx: ProbeContext): Promise<string[]> {
+		const base = rootUrl(target);
+		if (!base) return [];
+		return (await fetchCatalog(base, ctx, bearerHeaders(target, ctx))).models;
+	},
+
+	synthesizeModel(target: TargetDescriptor, wireModelId: string, kb: KnowledgeBaseHit | null): Model<Api> {
+		return synthLocalModel({
+			// A LiteLLM target is a gateway whether or not settings said so. The
+			// residency layer reads this to stay observe-only: the models behind an
+			// alias are the proxy's to load and evict, and a Clio stream that tried
+			// to manage them would be issuing load commands to a host that does not
+			// take them.
+			target: { ...target, gateway: true },
+			wireModelId,
+			kb,
+			defaultCapabilities,
+			apiFamily: "openai-completions",
+			provider: LITELLM_PROVIDER,
+			baseUrlForTarget: withV1,
+		});
+	},
+};
+
+export default litellmRuntime;

package/src/domains/providers/support.ts

@@ -59,6 +59,7 @@ const SUMMARY_BY_RUNTIME_ID: Readonly<Record<string, string>> = {
 	llamacpp: "llama.cpp server (auto-detect surface)",
 	"anthropic-compat": "Generic Anthropic-compatible REST",
 	"openai-compat": "Generic OpenAI-compatible REST",
+	litellm: "LiteLLM gateway with per-alias capability discovery and routed-model attribution",
 };
 
 function groupPriority(group: ProviderSupportGroup): number {

package/src/domains/providers/target-model-cache.ts

@@ -0,0 +1,124 @@
+/**
+ * Disposable per-target model catalogs discovered by provider probes.
+ *
+ * A live endpoint catalog is machine state, not operator policy. Persisting it
+ * in settings.yaml made a three-target config carry hundreds of volatile model
+ * ids. Cache files keep that snapshot available to a new process without
+ * turning the hand-edited settings file into a probe transcript.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { clioCacheDir } from "../../core/xdg.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+export const TARGET_MODEL_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+const TARGET_MODEL_CACHE_VERSION = 1;
+const TARGET_MODEL_CACHE_MAX_MODELS = 4_096;
+const TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS = 1_024;
+
+export interface TargetModelSnapshot {
+	version: 1;
+	targetId: string;
+	runtimeId: string;
+	url: string | null;
+	models: string[];
+	observedAt: string;
+}
+
+interface TargetModelCacheOptions {
+	cacheDir?: string;
+	nowMs?: number;
+	ttlMs?: number;
+}
+
+function targetCacheKey(targetId: string): string {
+	return createHash("sha256").update(targetId).digest("hex").slice(0, 24);
+}
+
+export function targetModelSnapshotPath(targetId: string, cacheDir = clioCacheDir()): string {
+	return join(cacheDir, "provider-target-models", `${targetCacheKey(targetId)}.json`);
+}
+
+function normalizedModels(models: ReadonlyArray<string>): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const raw of models) {
+		const model = raw.trim();
+		if (model.length === 0 || model.length > TARGET_MODEL_CACHE_MAX_MODEL_ID_CHARS || seen.has(model)) continue;
+		seen.add(model);
+		out.push(model);
+		if (out.length >= TARGET_MODEL_CACHE_MAX_MODELS) break;
+	}
+	return out;
+}
+
+function parseSnapshot(value: unknown): TargetModelSnapshot | null {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	const row = value as Partial<TargetModelSnapshot>;
+	if (row.version !== TARGET_MODEL_CACHE_VERSION) return null;
+	if (typeof row.targetId !== "string" || row.targetId.length === 0) return null;
+	if (typeof row.runtimeId !== "string" || row.runtimeId.length === 0) return null;
+	if (row.url !== null && typeof row.url !== "string") return null;
+	if (!Array.isArray(row.models) || row.models.some((model) => typeof model !== "string")) return null;
+	if (typeof row.observedAt !== "string" || !Number.isFinite(Date.parse(row.observedAt))) return null;
+	const models = normalizedModels(row.models);
+	if (models.length !== row.models.length) return null;
+	return {
+		version: TARGET_MODEL_CACHE_VERSION,
+		targetId: row.targetId,
+		runtimeId: row.runtimeId,
+		url: row.url,
+		models,
+		observedAt: row.observedAt,
+	};
+}
+
+/** Read a fresh snapshot only when it still describes this target identity. */
+export function readTargetModelSnapshot(
+	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
+	options: TargetModelCacheOptions = {},
+): TargetModelSnapshot | null {
+	const path = targetModelSnapshotPath(target.id, options.cacheDir);
+	if (!existsSync(path)) return null;
+	try {
+		const snapshot = parseSnapshot(JSON.parse(readFileSync(path, "utf8")) as unknown);
+		if (snapshot === null) return null;
+		if (snapshot.targetId !== target.id || snapshot.runtimeId !== target.runtime) return null;
+		if (snapshot.url !== (target.url ?? null)) return null;
+		const observedMs = Date.parse(snapshot.observedAt);
+		const nowMs = options.nowMs ?? Date.now();
+		const ttlMs = options.ttlMs ?? TARGET_MODEL_CACHE_TTL_MS;
+		if (observedMs > nowMs || nowMs - observedMs >= ttlMs) return null;
+		return snapshot;
+	} catch {
+		return null;
+	}
+}
+
+/** Best-effort atomic replacement of one target's disposable probe snapshot. */
+export function recordTargetModelSnapshot(
+	target: Pick<TargetDescriptor, "id" | "runtime" | "url">,
+	models: ReadonlyArray<string>,
+	options: Pick<TargetModelCacheOptions, "cacheDir" | "nowMs"> = {},
+): boolean {
+	if (target.id.length === 0 || target.runtime.length === 0) return false;
+	const snapshot: TargetModelSnapshot = {
+		version: TARGET_MODEL_CACHE_VERSION,
+		targetId: target.id,
+		runtimeId: target.runtime,
+		url: target.url ?? null,
+		models: normalizedModels(models),
+		observedAt: new Date(options.nowMs ?? Date.now()).toISOString(),
+	};
+	try {
+		safeResourceWrite(targetModelSnapshotPath(target.id, options.cacheDir), `${JSON.stringify(snapshot, null, 2)}\n`, {
+			encoding: "utf8",
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/domains/resources/index.ts

@@ -68,11 +68,14 @@ export {
 	parsePendingSkillRequests,
 	parseSkillCommand,
 	type Skill,
+	type SkillCatalogInvalidReason,
+	type SkillCatalogValidity,
 	type SkillExpansion,
 	type SkillList,
 	type SkillProvenance,
 	type SkillRoot,
 	type SkillSource,
+	skillCatalogValidity,
 } from "./skills/loader.js";
 export {
 	type DiscoverMarketplaceOptions,

package/src/domains/resources/skills/loader.ts

@@ -893,6 +893,39 @@ export function modelVisibleSkills(skills: ReadonlyArray<Skill>): Skill[] {
 	return skills.filter((skill) => skill.trusted && !skill.disableModelInvocation);
 }
 
+/** Why a loaded skill catalog is not valid. Ordered by which failure to report first. */
+export type SkillCatalogInvalidReason = "load-error" | "collision" | "unloadable-file" | "no-skills";
+
+export interface SkillCatalogValidity {
+	ok: boolean;
+	reason: SkillCatalogInvalidReason | null;
+}
+
+/**
+ * The rule `clio-coder skills validate` applies, in one place.
+ *
+ * A scanned file that produced no loaded skill is malformed, and a collision
+ * drops a skill: both make the catalog invalid, as does any hard error. Benign
+ * warnings (name/path mismatch, name format, description length) attach to a
+ * file that still loaded, so their path is among the loaded skills and they do
+ * not fail validation.
+ *
+ * Lives here rather than in the CLI because two callers now need the same
+ * answer, and a verdict that drifts between the terminal and a GUI is worse
+ * than no verdict at all.
+ */
+export function skillCatalogValidity(list: SkillList): SkillCatalogValidity {
+	if (list.diagnostics.some((diag) => diag.type === "error")) return { ok: false, reason: "load-error" };
+	if (list.diagnostics.some((diag) => diag.type === "collision")) return { ok: false, reason: "collision" };
+	const loadedPaths = new Set(list.items.map((skill) => skill.filePath));
+	const unloadable = list.diagnostics.some(
+		(diag) => diag.type === "warning" && diag.path !== undefined && !loadedPaths.has(diag.path),
+	);
+	if (unloadable) return { ok: false, reason: "unloadable-file" };
+	if (list.items.length === 0) return { ok: false, reason: "no-skills" };
+	return { ok: true, reason: null };
+}
+
 export function parseSkillCommand(input: string): { name: string; args: string } | null {
 	const trimmed = input.trim();
 	if (!trimmed.startsWith("/skill ")) return null;

package/src/domains/safety/action-classifier.ts

@@ -104,6 +104,12 @@ function baseClassify(tool: string): ActionClass | null {
 		// local mirror. Neither touches the workspace, so it is never gated
 		// behind a confirmation.
 		case ToolNames.Ledger:
+		// panes focuses, opens, and closes terminal panes Clio itself created, in
+		// a pane host that lives outside the workspace. Nothing it does writes a
+		// file, runs a model-supplied command (its schema exposes presets only),
+		// or survives the session, so it is reversible, local, and never gated
+		// behind a confirmation.
+		case ToolNames.Panes:
 			return "read";
 		case ToolNames.Write:
 		case ToolNames.Edit: