@iowarp/clio-coder 0.4.2 → 0.4.3

package/src/domains/observability/compaction-usage.ts

@@ -0,0 +1,118 @@
+/** Preserve spending from summary streams that did not produce a checkpoint. */
+
+import type { CompactionCallObservation } from "../session/compaction/compact.js";
+import { extractReasoningTokens } from "../session/context-accounting.js";
+import type { BackgroundMemoryUsageSink } from "./background-memory-usage.js";
+import { appendOutOfTurnUsageRow, type OutOfTurnUsage, type OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+
+export interface CompactionUsageOrigin {
+	stateDir: string;
+	sessionId: string;
+	repoIdentity: string;
+	target: string;
+	model: string;
+}
+
+/** Failed adapter zeros cannot distinguish absent usage from a reported zero. */
+function observedUsage(call: CompactionCallObservation): OutOfTurnUsage {
+	const raw = isRecord(call.usage) ? call.usage : {};
+	const reading = (value: unknown): number | null =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 && (call.outcome === "success" || value > 0)
+			? value
+			: null;
+	const cost = isRecord(raw.cost) ? reading(raw.cost.total) : null;
+	// Adapter cost is a price estimate, not independent provider billing evidence.
+	const costUsd = cost !== null && cost > 0 ? cost : null;
+	const reasoning = extractReasoningTokens({ ...raw, reasoningTokens: undefined });
+	return {
+		input: reading(raw.input),
+		output: reading(raw.output),
+		cacheRead: reading(raw.cacheRead),
+		cacheWrite: reading(raw.cacheWrite),
+		reasoning: reasoning !== null && reasoning > 0 ? reasoning : null,
+		totalTokens: reading(raw.totalTokens),
+		costUsd,
+		costProvenance: costUsd === null ? "unknown" : "estimated",
+	};
+}
+
+/**
+ * The checkpoint is the sole accounting source on success. Call this only when
+ * no checkpoint exists; each row is one actual stream invocation, not a retry.
+ * Missing amounts remain null on disk. Numeric live counters are known subtotals.
+ */
+export function recordFailedCompactionCalls(
+	origin: CompactionUsageOrigin,
+	calls: ReadonlyArray<CompactionCallObservation>,
+	observability?: BackgroundMemoryUsageSink,
+): void {
+	for (const call of calls) {
+		const usage = observedUsage(call);
+		const row: OutOfTurnUsageRow = {
+			label: "failed-compaction",
+			callOutcome: call.outcome,
+			sessionId: origin.sessionId,
+			repoIdentity: origin.repoIdentity,
+			timestamp: call.timestamp,
+			target: origin.target,
+			attributedModelId: origin.model,
+			usage,
+			timing: { durationMs: call.durationMs },
+		};
+		appendOutOfTurnUsageRow(origin.stateDir, row, { required: true });
+		// Do not create a measured-zero live entry for a wholly unobserved call.
+		if (!Object.values(usage).some((value) => typeof value === "number" && value > 0)) continue;
+		observability?.recordTokens(
+			origin.target,
+			origin.model,
+			usage.totalTokens ?? 0,
+			usage.costUsd ?? 0,
+			{
+				input: usage.input ?? 0,
+				output: usage.output ?? 0,
+				cacheRead: usage.cacheRead ?? 0,
+				cacheWrite: usage.cacheWrite ?? 0,
+				reasoningTokens: usage.reasoning ?? 0,
+				totalTokens: usage.totalTokens ?? 0,
+				apiCalls: 1,
+			},
+			usage.costProvenance,
+			undefined,
+			"failed-compaction",
+		);
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const USAGE_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "reasoning", "totalTokens", "costUsd"] as const;
+type UsageField = (typeof USAGE_FIELDS)[number];
+
+/** Known subtotals and missing-field coverage; zero missing values are never inferred. */
+export function summarizeFailedCompactionUsage(rows: ReadonlyArray<OutOfTurnUsageRow>) {
+	const calls = rows.filter((row) => row.label === "failed-compaction");
+	const knownUsage = Object.fromEntries(USAGE_FIELDS.map((field) => [field, null])) as Record<UsageField, number | null>;
+	const erroredKnownUsage = { ...knownUsage };
+	const unobservedUsageCalls = Object.fromEntries(USAGE_FIELDS.map((field) => [field, 0])) as Record<UsageField, number>;
+	for (const row of calls) {
+		for (const field of USAGE_FIELDS) {
+			const value = row.usage[field];
+			if (value === null) unobservedUsageCalls[field] += 1;
+			else {
+				knownUsage[field] = (knownUsage[field] ?? 0) + value;
+				if (row.callOutcome === "error") erroredKnownUsage[field] = (erroredKnownUsage[field] ?? 0) + value;
+			}
+		}
+	}
+	return {
+		calls: calls.length,
+		successfulCalls: calls.filter((row) => row.callOutcome === "success").length,
+		erroredCalls: calls.filter((row) => row.callOutcome === "error").length,
+		abortedCalls: calls.filter((row) => row.callOutcome === "aborted").length,
+		knownUsage,
+		erroredKnownUsage,
+		unobservedUsageCalls,
+	};
+}

package/src/domains/observability/cost.ts

@@ -137,7 +137,7 @@ export interface UsageBreakdown {
  * the usage surfaces separate these out so an operator can see that money was
  * spent beside the session rather than inside it.
  */
-export type CostEntryLabel = "side-question" | "handoff" | "prewarm" | "background-memory";
+export type CostEntryLabel = "side-question" | "handoff" | "prewarm" | "background-memory" | "failed-compaction";
 
 export interface CostEntry {
 	providerId: string;

package/src/domains/observability/extension.ts

@@ -37,6 +37,11 @@ type DispatchTerminalLike = {
 	[K in keyof DispatchCompletedPayload]?: DispatchCompletedPayload[K] | undefined;
 };
 
+/** Pre-admission failures have an announced run id but never create a run ledger. */
+export function dispatchHasEvidenceLedger(payload: DispatchTerminalLike): boolean {
+	return payload.lineage !== undefined;
+}
+
 function recordDispatchCost(
 	telemetry: ReturnType<typeof createTelemetry>,
 	cost: ReturnType<typeof createCostTracker>,
@@ -222,7 +227,7 @@ export function createObservabilityBundle(
 					recordDispatchCost(telemetry, cost, payload);
 					// A failed run is never a first-pass success; still build the
 					// bundle so its failure-cause tags exist for the index.
-					if (typeof payload.runId === "string" && payload.runId.length > 0) {
+					if (typeof payload.runId === "string" && payload.runId.length > 0 && dispatchHasEvidenceLedger(payload)) {
 						trackBuild(payload.runId, false, payload.lineage?.attempt);
 					}
 				}),

package/src/domains/observability/out-of-turn-usage.ts

@@ -27,7 +27,7 @@
  * skipped, never fatal.
  */
 
-import { closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import { withStateFileLockSync } from "../../core/state-file-lock.js";
@@ -74,13 +74,13 @@ export interface OutOfTurnPromptCache {
 
 /** Provider-reported usage for one out-of-turn call. */
 export interface OutOfTurnUsage {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	reasoning: number;
-	totalTokens: number;
-	costUsd: number;
+	input: number | null;
+	output: number | null;
+	cacheRead: number | null;
+	cacheWrite: number | null;
+	reasoning: number | null;
+	totalTokens: number | null;
+	costUsd: number | null;
 	costProvenance: CostProvenance;
 }
 
@@ -97,6 +97,8 @@ export interface OutOfTurnUsageRow {
 	target: string;
 	attributedModelId: string;
 	usage: OutOfTurnUsage;
+	/** New failed-compaction rows preserve unknown usage as null. Legacy rows are unchanged. */
+	callOutcome?: "success" | "error" | "aborted";
 	/** Present when the caller measured the call. */
 	timing?: OutOfTurnTiming;
 	/** Present when the serving backend reported prefill facts. */
@@ -115,21 +117,31 @@ export function outOfTurnUsagePath(stateDir: string): string {
 let appendsSinceBoundCheck = BOUND_CHECK_INTERVAL;
 
 /**
- * Append one priced out-of-turn call. Never throws: this runs on the same path
- * that answers an operator's side question, and a failed bookkeeping write must
- * not take the answer down with it.
+ * Append one out-of-turn call. Optional bookkeeping keeps its existing diagnostic
+ * write policy. Required failed-compaction records flush the append and throw on
+ * a failed or incomplete write, so their caller cannot report recorded spending.
  */
-export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow): void {
+export function appendOutOfTurnUsageRow(
+	stateDir: string,
+	row: OutOfTurnUsageRow,
+	options: { required?: boolean } = {},
+): void {
 	const path = outOfTurnUsagePath(stateDir);
 	try {
 		mkdirSync(dirname(path), { recursive: true });
 		const fd = openSync(path, "a");
 		try {
-			writeSync(fd, `${JSON.stringify(row)}\n`);
+			const line = `${JSON.stringify(row)}\n`;
+			const written = writeSync(fd, line);
+			if (options.required) {
+				if (written !== Buffer.byteLength(line)) throw new Error("incomplete usage row write");
+				fsyncSync(fd);
+			}
 		} finally {
 			closeSync(fd);
 		}
 	} catch (error) {
+		if (options.required) throw new Error(`compaction usage row not written: ${messageOf(error)}`, { cause: error });
 		process.stderr.write(`[clio-coder:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
 		return;
 	}
@@ -205,11 +217,25 @@ export function readOutOfTurnUsageRows(stateDir: string): OutOfTurnUsageReadResu
 function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 	if (!isRecord(value)) return null;
 	const label = value.label;
-	if (label !== "side-question" && label !== "handoff" && label !== "prewarm" && label !== "background-memory")
+	if (
+		label !== "side-question" &&
+		label !== "handoff" &&
+		label !== "prewarm" &&
+		label !== "background-memory" &&
+		label !== "failed-compaction"
+	)
 		return null;
 	if (typeof value.timestamp !== "string" || value.timestamp.length === 0) return null;
 	if (!isRecord(value.usage)) return null;
 	const usage = value.usage;
+	if (
+		label === "failed-compaction" &&
+		value.callOutcome !== "success" &&
+		value.callOutcome !== "error" &&
+		value.callOutcome !== "aborted"
+	)
+		return null;
+	const reading = label === "failed-compaction" ? nullableNumber : numberOr0;
 	const timing = asTiming(value.timing);
 	const promptCache = asPromptCache(value.promptCache);
 	return {
@@ -223,15 +249,16 @@ function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
 				? value.attributedModelId
 				: "unknown",
 		usage: {
-			input: numberOr0(usage.input),
-			output: numberOr0(usage.output),
-			cacheRead: numberOr0(usage.cacheRead),
-			cacheWrite: numberOr0(usage.cacheWrite),
-			reasoning: numberOr0(usage.reasoning),
-			totalTokens: numberOr0(usage.totalTokens),
-			costUsd: numberOr0(usage.costUsd),
+			input: reading(usage.input),
+			output: reading(usage.output),
+			cacheRead: reading(usage.cacheRead),
+			cacheWrite: reading(usage.cacheWrite),
+			reasoning: reading(usage.reasoning),
+			totalTokens: reading(usage.totalTokens),
+			costUsd: reading(usage.costUsd),
 			costProvenance: asCostProvenance(usage.costProvenance),
 		},
+		...(label === "failed-compaction" ? { callOutcome: value.callOutcome as "success" | "error" | "aborted" } : {}),
 		...(timing === null ? {} : { timing }),
 		...(promptCache === null ? {} : { promptCache }),
 	};
@@ -259,6 +286,10 @@ function asCostProvenance(value: unknown): CostProvenance {
 	return value === "known" || value === "known_free" || value === "estimated" ? value : "unknown";
 }
 
+function nullableNumber(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
 function numberOr0(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }

package/src/domains/providers/contract.ts

@@ -59,6 +59,8 @@ export interface TargetStatus {
 	probeSurfaces?: Readonly<ProbeSurfaceMap>;
 	/** Ids returned by the last successful probeModels() call. */
 	discoveredModels: ReadonlyArray<string>;
+	/** Human-readable live/cache labels keyed by exact model slug. */
+	discoveredModelLabels?: Readonly<Record<string, string>>;
 	/**
 	 * Source for `discoveredModels`. `probe` means the target just returned a
 	 * live catalog, `cache` is a previously probed catalog preserved across a
@@ -93,7 +95,8 @@ export interface ProvidersContract {
 	 * `reasoning: false` skips an inference-based reasoning-capability probe while
 	 * retaining the target's liveness and model-catalog checks.
 	 */
-	probeTarget(id: string, options?: { reasoning?: boolean }): Promise<TargetStatus | null>;
+	/** Optional cancellation covers auth and metadata; a cancelled probe does not publish health. */
+	probeTarget(id: string, options?: { reasoning?: boolean; signal?: AbortSignal }): Promise<TargetStatus | null>;
 
 	/** Clear in-memory live connection state for a configured target. */
 	disconnectTarget(id: string): TargetStatus | null;

package/src/domains/providers/extension.ts

@@ -156,6 +156,7 @@ function sameProbeIdentity(previous: TargetDescriptor, next: TargetDescriptor):
 
 export interface ProbeMerge {
 	discoveredModels: string[];
+	discoveredModelLabels: Readonly<Record<string, string>>;
 	discoveredModelsSource: "probe" | "cache" | "runtime" | "none";
 	discoveredModelStates: NonNullable<TargetStatus["discoveredModelStates"]> | null;
 	probeCapabilities: NonNullable<TargetStatus["probeCapabilities"]> | null;
@@ -179,6 +180,7 @@ function mergeProbeResult(
 	probe: ProbeResult | null,
 	previous: TargetStatus | undefined,
 	cachedModels: ReadonlyArray<string> = [],
+	cachedModelLabels: Readonly<Record<string, string>> = {},
 ): ProbeMerge {
 	const probeSucceeded = probe?.ok ?? false;
 	const preservePrevious = !probeSucceeded && previous !== undefined && sameProbeIdentity(previous.target, target);
@@ -201,8 +203,14 @@ function mergeProbeResult(
 			[],
 	);
 	const discoveredModelStates = probe?.modelStates ?? (preservePrevious ? previous.discoveredModelStates : null) ?? null;
+	const discoveredModelLabels =
+		probe?.modelLabels ??
+		(preservePrevious ? previous.discoveredModelLabels : undefined) ??
+		(cachedModels.length > 0 ? cachedModelLabels : undefined) ??
+		{};
 	const merge: ProbeMerge = {
 		discoveredModels,
+		discoveredModelLabels,
 		discoveredModelsSource: discoveredModelsSource(probe, preservePrevious, previous, cachedModels, desc),
 		discoveredModelStates,
 		probeCapabilities,
@@ -225,14 +233,16 @@ function mergeProbeResult(
  * there is no live evidence either way.
  */
 function unservedDefaultModelReason(
-	desc: Pick<RuntimeDescriptor, "id">,
+	desc: Pick<RuntimeDescriptor, "id" | "externalAgentLoop">,
 	target: Pick<TargetDescriptor, "defaultModel">,
 	merge: Pick<ProbeMerge, "discoveredModels" | "discoveredModelsSource" | "discoveredModelStates">,
 ): string | null {
 	const model = target.defaultModel;
 	if (!model) return null;
 	if (merge.discoveredModelsSource !== "probe" || merge.discoveredModels.length === 0) return null;
-	if (listKnownModelsForRuntime(desc.id).length > 0) return null;
+	if (listKnownModelsForRuntime(desc.id).length > 0 && desc.externalAgentLoop?.modelCatalog !== "live-authoritative") {
+		return null;
+	}
 	if (merge.discoveredModels.includes(model)) return null;
 	// LM Studio lists a loaded model under its instance id and keeps the model
 	// key in the state map; the request path resolves either.
@@ -258,14 +268,22 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 		return readSettings();
 	}
 
-	async function buildProbeContextForTarget(target: TargetDescriptor, desc: RuntimeDescriptor): Promise<ProbeContext> {
+	async function buildProbeContextForTarget(
+		target: TargetDescriptor,
+		desc: RuntimeDescriptor,
+		signal?: AbortSignal,
+	): Promise<ProbeContext> {
 		const probeCtx: ProbeContext = {
 			credentialsPresent: credentialsPresent(),
 			httpTimeoutMs: DEFAULT_PROBE_TIMEOUT_MS,
+			...(signal ? { signal } : {}),
 		};
 		if (!targetRequiresAuth(target, desc)) return probeCtx;
 		try {
-			const resolution = await authStore.resolveForTarget(resolveAuthTarget(target, desc), { includeFallback: false });
+			const resolution = await authStore.resolveForTarget(resolveAuthTarget(target, desc), {
+				includeFallback: false,
+				...(signal ? { signal } : {}),
+			});
 			if (resolution.apiKey) probeCtx.authToken = resolution.apiKey;
 		} catch {
 			// Authenticated probes should still return a runtime-specific missing-auth error.
@@ -325,8 +343,9 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			return out;
 		}
 		const availability = availabilityFor(desc, target, authStatusFor);
-		const cachedModels = readTargetModelSnapshot(target)?.models ?? [];
-		const merge = mergeProbeResult(desc, target, probe, previous, cachedModels);
+		const cachedSnapshot = readTargetModelSnapshot(target);
+		const cachedModels = cachedSnapshot?.models ?? [];
+		const merge = mergeProbeResult(desc, target, probe, previous, cachedModels, cachedSnapshot?.modelLabels ?? {});
 		const { capabilities, contextWindowProvenance } = capabilitiesFor(desc, target, merge, kb);
 		const healthy = probe !== null ? probe.ok : null;
 		const unservedDefault = probe?.ok ? unservedDefaultModelReason(desc, target, merge) : null;
@@ -353,6 +372,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			probeModelCapabilities: merge.probeModelCapabilities,
 			probeModelId: merge.probeModelId,
 			discoveredModels: merge.discoveredModels,
+			discoveredModelLabels: merge.discoveredModelLabels,
 			discoveredModelsSource: merge.discoveredModelsSource,
 			discoveredModelStates: merge.discoveredModelStates,
 		};
@@ -364,8 +384,9 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 	async function probeTargetInternal(
 		target: TargetDescriptor,
 		live: boolean,
-		options?: { reasoning?: boolean },
+		options?: { reasoning?: boolean; signal?: AbortSignal },
 	): Promise<TargetStatus> {
+		options?.signal?.throwIfAborted();
 		const previous = statuses.get(target.id);
 		const desc = registry.get(target.runtime);
 		if (!desc) {
@@ -379,13 +400,15 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			statuses.set(target.id, status);
 			return status;
 		}
-		const probeCtx = await buildProbeContextForTarget(target, desc);
+		const probeCtx = await buildProbeContextForTarget(target, desc, options?.signal);
+		options?.signal?.throwIfAborted();
 		let probeResult: ProbeResult;
 		try {
 			probeResult = await desc.probe(target, probeCtx);
 		} catch (err) {
 			probeResult = { ok: false, error: err instanceof Error ? err.message : String(err) };
 		}
+		options?.signal?.throwIfAborted();
 		if (probeResult.ok && typeof desc.probeModels === "function" && !probeResult.models) {
 			try {
 				const ids = await desc.probeModels(target, probeCtx);
@@ -394,6 +417,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 				// model discovery is best-effort; keep probe as-is.
 			}
 		}
+		options?.signal?.throwIfAborted();
 		if (probeResult.ok && options?.reasoning !== false && typeof desc.probeReasoning === "function") {
 			const settings = readConfig();
 			const orchestratorTarget = settings.chat.target === target.id ? settings.chat.model : null;
@@ -401,6 +425,7 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 			if (candidateModelId) {
 				try {
 					const result = await desc.probeReasoning(target, candidateModelId, probeCtx);
+					options?.signal?.throwIfAborted();
 					reasoningCache.set(reasoningCacheKey(target.id, candidateModelId), result.reasoning);
 					const capabilityModelId = probeResult.capabilityModelId ?? null;
 					if (capabilityModelId === null || capabilityModelId === candidateModelId) {
@@ -422,10 +447,16 @@ export function createProvidersBundle(context: DomainContext): DomainBundle<Prov
 				}
 			}
 		}
+		// A cancelled role preparation must not publish failed/stale target state.
+		options?.signal?.throwIfAborted();
 		const status = buildStatus(target, desc, probeResult, previous);
 		statuses.set(target.id, status);
 		if (probeResult.ok && probeResult.models !== undefined) {
-			recordTargetModelSnapshot(target, probeResult.models);
+			recordTargetModelSnapshot(
+				target,
+				probeResult.models,
+				probeResult.modelLabels ? { modelLabels: probeResult.modelLabels } : {},
+			);
 		}
 		// Durable so the next process resolves this endpoint's real slot count
 		// instead of the conservative default. Fire and forget: the probe's answer

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

@@ -14,6 +14,7 @@ export interface ModelCapabilityPatchTarget {
 	contextWindow?: number;
 	maxTokens?: number;
 	reasoning?: boolean;
+	clioCoder?: Record<string, unknown>;
 }
 
 /**
@@ -30,6 +31,14 @@ export function applyModelCapabilityPatch<T extends ModelCapabilityPatchTarget>(
 	if (typeof caps.contextWindow === "number") model.contextWindow = caps.contextWindow;
 	if (typeof caps.maxTokens === "number") model.maxTokens = caps.maxTokens;
 	if (typeof caps.reasoning === "boolean") model.reasoning = caps.reasoning;
+	// Refresh the probe-only control hint together with the capability snapshot.
+	// Missing metadata after a later probe must not retain an earlier route claim.
+	if (model.clioCoder || caps.thinkingControlRuntime !== undefined) {
+		const metadata = { ...model.clioCoder };
+		delete metadata.thinkingControlRuntime;
+		if (caps.thinkingControlRuntime !== undefined) metadata.thinkingControlRuntime = caps.thinkingControlRuntime;
+		model.clioCoder = metadata;
+	}
 	return model;
 }
 

package/src/domains/providers/model-discovery.ts

@@ -6,6 +6,7 @@ export type ProviderModelSource = "configured" | "live" | "catalog" | "default";
 
 export interface ProviderModelCandidate {
 	id: string;
+	label?: string;
 	source: ProviderModelSource;
 	loadState?: string;
 	loadStateDetail?: string;
@@ -100,6 +101,7 @@ export function modelCandidatesForStatus(status: TargetStatus): ProviderModelCan
 		const state = status.discoveredModelStates?.[trimmed];
 		out.push({
 			id: trimmed,
+			...(status.discoveredModelLabels?.[trimmed] ? { label: status.discoveredModelLabels[trimmed] } : {}),
 			source,
 			...(state ? { loadState: state.state } : {}),
 			...(state?.detail ? { loadStateDetail: state.detail } : {}),

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

@@ -131,6 +131,7 @@ interface ClioRuntimeMetadata {
 		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		family?: string;
+		thinkingControlRuntime?: CapabilityFlags["thinkingControlRuntime"];
 		quirks?: LocalModelQuirks;
 	};
 	/** Released in-memory metadata name accepted at plugin/runtime read boundaries. */
@@ -140,6 +141,7 @@ interface ClioRuntimeMetadata {
 		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		family?: string;
+		thinkingControlRuntime?: CapabilityFlags["thinkingControlRuntime"];
 		quirks?: LocalModelQuirks;
 	};
 	compat?: {
@@ -381,9 +383,10 @@ export function effectiveThinkingLevel(
 	const fallback = available[0] ?? "off";
 	if (!configured) return fallback;
 	if (available.includes(configured)) return configured;
-	// Catalog effort maps intentionally stop at xhigh; `max` must clamp to that
-	// supported ceiling instead of falling through to the generic low fallback.
-	if (configured === "max" && available.includes("xhigh")) return "xhigh";
+	// A family with xhigh but no high keeps the released high alias at its
+	// supported ceiling; neither high nor max may fall through to low.
+	if ((configured === "max" || (configured === "high" && !available.includes("high"))) && available.includes("xhigh"))
+		return "xhigh";
 	if ((configured === "high" || configured === "xhigh" || configured === "max") && available.includes("high")) {
 		return "high";
 	}
@@ -553,7 +556,7 @@ function resolveThinkingCapability(
  */
 const REASONING_EFFORT_ONLY_RUNTIMES: ReadonlySet<string> = new Set(["lmstudio"]);
 
-/** `none` is LM Studio's documented off value; on-off models have no finer dial than `low`. */
+/** `none` is the observed LM Studio HTTP off value; on-off models have no finer dial than `low`. */
 function onOffReasoningEffort(thinkingActive: boolean): string {
 	return thinkingActive ? "low" : "none";
 }
@@ -647,7 +650,12 @@ export function resolveModelRuntimeCapabilities(
 		family,
 		capabilities: input.capabilities,
 		thinking,
-		request: resolveRequestCapability(thinking, parser, input.runtimeId, quirks),
+		request: resolveRequestCapability(
+			thinking,
+			parser,
+			input.runtimeId === "litellm" ? (input.capabilities.thinkingControlRuntime ?? input.runtimeId) : input.runtimeId,
+			quirks,
+		),
 		response: {
 			parser,
 			stripTokenizerSentinels: true,
@@ -735,6 +743,7 @@ function thinkingFormatFromModelApi(api: Api): CapabilityFlags["thinkingFormat"]
 
 function capabilitiesFromModel(model: Model<Api> & ClioRuntimeMetadata): CapabilityFlags {
 	const format = model.compat?.thinkingFormat ?? thinkingFormatFromModelApi(model.api);
+	const controlRuntime = (model.clioCoder ?? model.clio)?.thinkingControlRuntime;
 	const caps: CapabilityFlags = {
 		chat: true,
 		tools: true,
@@ -746,6 +755,7 @@ function capabilitiesFromModel(model: Model<Api> & ClioRuntimeMetadata): Capabil
 		fim: false,
 		contextWindow: model.contextWindow,
 		maxTokens: model.maxTokens,
+		...(controlRuntime ? { thinkingControlRuntime: controlRuntime } : {}),
 	};
 	if (
 		format === "qwen-chat-template" ||

package/src/domains/providers/models/local-models/clio-coder-local-coding-targets.yaml

@@ -561,8 +561,12 @@
       guidance: |
         Ornith 1.5's Qwen3.5 chat template exposes thinking as on or off
         through enable_thinking; intermediate levels coerce to on. LM Studio
-        reads the same switch from reasoning_effort (none or low), which Clio
-        sends for on-off models on that runtime.
+        2026-09-03 exposed a split vocabulary on this exact Q4_K_M: native
+        discovery advertised {off,on}, while its OpenAI-compatible request
+        validator rejected literal `on` and accepted only effort-level values.
+        `low` ran only after a warning and fallback to on, so Clio now omits an
+        active override for this default-on model and sends `reasoning_effort:
+        none` only when disabling it.
     serving: "Ornith-1.5-35B-A3B follows the 1.0 card: 262K context, qwen3 reasoning parsing, qwen3_coder tool parsing, sampler temperature=0.6, top_p=0.95, top_k=20."
 
 - family: qwen3.6-27b
@@ -696,7 +700,7 @@
       "128gb-unified-vulkan": "128 GB unified-memory Vulkan class: IQ4_NL uses about 17.3 GB and fits ctx=262144 with parallel=4. Vulkan backends show much slower prefill than ROCm/CUDA on this family; prefer ROCm where available."
     runtimePreference:
       llamaCpp: "Primary verified path. OpenAI-compatible chat completions with --jinja, --reasoning on, --reasoning-effort medium as server defaults; reasoning_content and tool_calls both confirmed to parse correctly. A request can override to off with chat_template_kwargs.enable_thinking:false, or to a different active level with reasoning_effort in {low, medium, xhigh} (never minimal/high/max on the wire; the stock template raises a fatal jinja exception on those and Clio's landed capability resolver already clamps to this set)."
-      lmstudioOpenaiCompat: "Clio sends reasoning_effort over LM Studio's OpenAI-compatible HTTP port and omits chat_template_kwargs because LM Studio does not use that field for this model. With no override, LM Studio defaults this model to thinking off, unlike raw llama.cpp's template default of thinking on/xhigh. reasoning_effort:'none' explicitly disables it."
+      lmstudioOpenaiCompat: "Clio sends reasoning_effort over LM Studio's OpenAI-compatible HTTP port and omits chat_template_kwargs because LM Studio does not use that field for this model. The upstream template defaults to thinking on/xhigh; an LM Studio deployment may configure another default. reasoning_effort:'none' explicitly disables it. Through LiteLLM, this control also requires allowed_openai_params:['reasoning_effort']; Clio selects the LM Studio spelling only when every deployment of that alias explicitly declares model_info.runtime: lm-studio."
       lmstudioNative: "Clio's LM Studio runtime uses the OpenAI-compatible HTTP chat adapter with native REST model discovery and residency management."
     llamaCpp:
       ctxSize: 131072
@@ -718,7 +722,6 @@
       effortByLevel:
         low: low
         medium: medium
-        high: xhigh
         xhigh: xhigh
       guidance: |
         Official Qwen3.8-27B chat template (chat_template.jinja) validates
@@ -726,19 +729,32 @@
         fatal jinja exception (hard 500, not a graceful fallback) on anything
         else, including minimal/high/max. The 27B card gives no /think or
         /no_think soft switch for this model; unlike Qwen3, that idiom has no
-        effect here. Off must go through chat_template_kwargs.enable_thinking:
-        false, never through reasoning_effort. preserve_thinking should stay
+        effect here. The template defaults to xhigh with thinking enabled.
+        The picker offers off/low/medium/xhigh; released high and max choices
+        normalize to xhigh rather than reaching the strict template unchanged.
+        Template-level off uses chat_template_kwargs.enable_thinking:false.
+        preserve_thinking should stay
         on for an agentic harness (the template's own recommendation for
         agent scenarios; improves KV cache reuse). llama.cpp's own
         reasoning_effort:"none" also disables reasoning at the server layer
         and is a separate mechanism from the template's enable_thinking flag;
-        both were verified independently on llama.cpp and on LM Studio's HTTP
-        port.
+        the none sentinel is consumed before strict template effort validation.
+        LM Studio's HTTP port also accepts none. A 2026-09-05 same-route
+        LiteLLM probe showed none and the template flag alone still reasoned
+        because the generic OpenAI route filtered the effort parameter. Adding
+        allowed_openai_params:["reasoning_effort"] produced zero reasoning
+        twice; an allowed low control still reasoned. Clio forwards only an
+        effort resolved from the model/runtime contract, and never infers the
+        upstream control runtime from a host name, port, or model alias.
 
         Thinking off is verified for this family, and no floor is imposed on
-        it. JetBrains report that Qwen3.8 without reasoning gets stuck in a
+        it. The official card and template were rechecked at revision
+        1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0:
+        https://huggingface.co/Qwen/Qwen3.8-27B/blob/1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/chat_template.jinja
+        JetBrains report that Qwen3.8 without reasoning gets stuck in a
         loop repeating the same tool call indefinitely under Junie. Clio's
-        shipped default is orchestrator.thinkingLevel: off, which on llama.cpp
+        shipped default is chat.thinkingLevel: off, an explicit Clio preference
+        rather than the vendor's template default. On llama.cpp it
         sends chat_template_kwargs.enable_thinking:false and on LM Studio's
         OpenAI-compatible port sends reasoning_effort:"none". Clio 0.3.8 ran
         that configuration on both runtimes (llama.cpp build b226-2115b73d8 on
@@ -746,8 +762,12 @@
         2026-08-29 and 2026-08-30: an interactive build-and-resume session, a
         three-worker fleet step, and a ten-task eval suite totalling 116 model
         calls, none of which repeated a tool call into a loop. The catalog
-        therefore imposes no thinking floor and coerces no level for this
-        family. If a future build or quantization regresses into the loop
+        therefore imposes no thinking floor for this family. A provisional 2026-09-03 LM Studio A/B on the heavily quantized
+        `qwen3.8-27b-gsq-rco` alias corroborated the switch: four thinking-off
+        scenarios reported zero reasoning tokens and no repeated-tool loop,
+        versus visible reasoning at the active level. The host had LM Link
+        enabled, so this records behavior only—not hardware throughput or a
+        controlled quality claim. If a future build or quantization regresses into the loop
         JetBrains describe, the guards that catch it are Clio's own, not a
         catalog setting: the tool-prose-loop detector
         (src/interactive/tool-prose-loop.ts), which is armed on the