@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/cli/config-inspect.ts

@@ -1,7 +1,7 @@
 /**
  * The effective-customization graph behind `clio-coder config inspect`. This is the
  * "why is Clio behaving this way" surface: it answers what settings, context
- * files, rules, skills, prompts, agents, extensions, safety, memory, hooks, and
+ * files, rules, skills, prompts, agents, fleets, extensions, safety, memory, hooks, and
  * the operator profile loaded, from where, with what precedence, and what each
  * costs in context.
  *
@@ -12,8 +12,9 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { basename } from "node:path";
+import { basename, join } from "node:path";
 import type { ClioSettings } from "../core/config.js";
+import { resolvePackageRoot } from "../core/package-root.js";
 import { readLayeredSettings, type SettingsOrigin, settingsSourceFor } from "../core/settings-layers.js";
 import { clioDataDir } from "../core/xdg.js";
 import {
@@ -39,7 +40,8 @@ export type CustomizationCategory =
 	| "extension"
 	| "skill-root"
 	| "prompt-root"
-	| "agents"
+	| "agent-root"
+	| "fleet-root"
 	| "safety"
 	| "memory";
 
@@ -265,18 +267,43 @@ function inspectResourceRoots(cwd: string, graph: CustomizationGraph): void {
 	for (const [kind, category] of [
 		["skills", "skill-root"],
 		["prompts", "prompt-root"],
+		["agents", "agent-root"],
+		["fleets", "fleet-root"],
 	] as const) {
 		try {
+			if (kind === "agents" || kind === "fleets") {
+				const builtinPath = join(
+					resolvePackageRoot(),
+					"src",
+					"domains",
+					"agents",
+					kind === "agents" ? "builtins" : "fleets",
+				);
+				graph.entries.push({
+					category,
+					id: `${kind}:builtin`,
+					scope: "builtin",
+					sourcePath: builtinPath,
+					trust: "trusted",
+					precedence: "layer",
+					reloadClass: "next-turn",
+					detail: { present: existsSync(builtinPath), source: "builtin", resourcePrecedence: 0 },
+				});
+			}
 			for (const root of defaultScopedResourceRoots(kind, cwd)) {
 				graph.entries.push({
 					category,
 					id: `${kind}:${root.scope}`,
-					scope: root.scope,
+					scope: root.scope === "package" ? "extension" : root.scope,
 					sourcePath: root.path,
 					trust: root.scope === "package" ? "untrusted" : "trusted",
-					precedence: "single",
+					precedence: "layer",
 					reloadClass: "next-turn",
-					detail: { present: existsSync(root.path), source: root.source },
+					detail: {
+						present: existsSync(root.path),
+						source: root.source,
+						...(root.precedence === undefined ? {} : { resourcePrecedence: root.precedence }),
+					},
 				});
 			}
 		} catch (err) {

package/src/cli/config.ts

@@ -4,7 +4,7 @@ import { printError } from "./shared.js";
 const HELP = `clio-coder config inspect [--json]
 
 Print the effective-customization graph: what settings, context files, rules,
-skills, prompts, agents, extensions, safety, memory, hooks, and the operator
+skills, prompts, agents, fleets, extensions, safety, memory, hooks, and the operator
 profile loaded, from where, with what precedence, trust, reload class, and
 context cost. Read-only; nothing is created.
 

package/src/cli/doctor-state-size.ts

@@ -0,0 +1,82 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { resolveClioDirs } from "../core/xdg.js";
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+
+interface MeasuredEntry {
+	bytes: number;
+	error: string | null;
+}
+
+/** Report aggregate state usage and the largest top-level contributor. */
+export function stateStorageFinding(stateDir = resolveClioDirs().state): DoctorFinding {
+	let names: string[];
+	try {
+		names = readdirSync(stateDir);
+	} catch (error) {
+		return {
+			ok: false,
+			name: "state storage",
+			detail: `${stateDir} could not be measured: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+
+	let total = 0;
+	let largest: { name: string; bytes: number } | null = null;
+	for (const name of names.sort()) {
+		const measured = measureEntry(join(stateDir, name));
+		if (measured.error !== null) {
+			return { ok: false, name: "state storage", detail: measured.error };
+		}
+		total += measured.bytes;
+		if (largest === null || measured.bytes > largest.bytes) largest = { name, bytes: measured.bytes };
+	}
+
+	return {
+		ok: true,
+		name: "state storage",
+		detail:
+			largest === null
+				? `${formatBytes(total)} (${total.toLocaleString("en-US")} bytes); largest contributor none`
+				: `${formatBytes(total)} (${total.toLocaleString("en-US")} bytes); largest contributor ${largest.name} at ${formatBytes(largest.bytes)} (${largest.bytes.toLocaleString("en-US")} bytes)`,
+	};
+}
+
+function measureEntry(path: string): MeasuredEntry {
+	let stats: ReturnType<typeof lstatSync>;
+	try {
+		stats = lstatSync(path);
+	} catch (error) {
+		return {
+			bytes: 0,
+			error: `${path} could not be inspected: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (!stats.isDirectory() || stats.isSymbolicLink()) return { bytes: stats.size, error: null };
+
+	let names: string[];
+	try {
+		names = readdirSync(path);
+	} catch (error) {
+		return { bytes: 0, error: `${path} could not be listed: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	let bytes = 0;
+	for (const name of names) {
+		const child = measureEntry(join(path, name));
+		if (child.error !== null) return child;
+		bytes += child.bytes;
+	}
+	return { bytes, error: null };
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KiB", "MiB", "GiB", "TiB"];
+	let value = bytes;
+	let unit = -1;
+	do {
+		value /= 1024;
+		unit += 1;
+	} while (value >= 1024 && unit < units.length - 1);
+	return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unit]}`;
+}

package/src/cli/doctor.ts

@@ -7,6 +7,7 @@ import {
 	runDoctorModelChecks,
 	runDoctorRuntimeChecks,
 } from "../domains/lifecycle/doctor.js";
+import { stateStorageFinding } from "./doctor-state-size.js";
 import { printError } from "./shared.js";
 
 const HELP = `clio-coder doctor [--fix] [--json]
@@ -35,6 +36,7 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	// gets every check on the home it just built.
 	const untouched = !fix && isUninitializedHome();
 	const findings = runDoctor({ fix });
+	const storageChecks = untouched ? [] : [stateStorageFinding()];
 	const runtimeChecks = await runDoctorRuntimeChecks();
 	// Every model pointer is checked against what its target advertises, so a
 	// placeholder id saved by configure is reported here and not on the first turn.
@@ -47,7 +49,7 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	// Fleet preflight probes each configured node over SSH and persists the
 	// per-node eligibility verdicts dispatch placement enforces.
 	const fleetChecks = untouched ? [] : await runDoctorFleetChecks();
-	const all = [...findings, ...runtimeChecks, ...modelChecks, ...interopChecks, ...fleetChecks];
+	const all = [...findings, ...storageChecks, ...runtimeChecks, ...modelChecks, ...interopChecks, ...fleetChecks];
 	const ok = all.every((f) => f.ok);
 	if (json) {
 		process.stdout.write(`${JSON.stringify({ ok, fix, findings: all }, null, 2)}\n`);

package/src/cli/eval.ts

@@ -2,10 +2,10 @@ import { resolve } from "node:path";
 import { InvalidIdError } from "../core/safe-id.js";
 import { clioDataDir } from "../core/xdg.js";
 import { loadEvalArtifactV4, writeEvalArtifactV4 } from "../domains/eval/artifacts/store.js";
-import { compareEvalArtifactsV4, renderEvalComparisonV4 } from "../domains/eval/compare/compare.js";
-import { evaluateGate, renderGateFailure } from "../domains/eval/compare/gates.js";
+import { compareEvalArtifactsV4 } from "../domains/eval/compare/compare.js";
+import { evaluateGate, renderGateFailure, renderInformationalBudget } from "../domains/eval/compare/gates.js";
 import { loadThresholds } from "../domains/eval/compare/thresholds.js";
-
+import { type EvalComparisonReportFormat, renderEvalComparisonReportV1 } from "../domains/eval/reports/comparison.js";
 import { renderEvalJsonReportV4 } from "../domains/eval/reports/json.js";
 import { renderEvalJunitReportV4 } from "../domains/eval/reports/junit.js";
 import { renderEvalMarkdownReportV4 } from "../domains/eval/reports/markdown.js";
@@ -22,10 +22,10 @@ const HELP = `clio-coder eval <command>
 
 Commands:
   clio-coder eval validate --suite <suite.yaml>
-  clio-coder eval run --suite <suite.yaml> [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
-  clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
+	  clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
+	  clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
   clio-coder eval report <evalId> --format text|json|md|swe-jsonl|junit
-  clio-coder eval compare <baselineEvalId> <candidateEvalId>
+	  clio-coder eval compare <baselineEvalId> <candidateEvalId> [--metric <name>] [--format text|json|md|junit] [--allow-config-drift]
   clio-coder eval gate <candidateEvalId> --baseline <baselineEvalId> [--thresholds <file>]
 `;
 
@@ -37,6 +37,7 @@ interface ParsedEvalArgs {
 	suite?: string;
 	taskFile?: string;
 	repeat: number;
+	trials?: number;
 	target?: string;
 	model?: string;
 	out?: string;
@@ -44,13 +45,21 @@ interface ParsedEvalArgs {
 	evalId?: string;
 	format: EvalReportFormat;
 	compareIds: string[];
+	metric?: string;
+	allowConfigDrift: boolean;
 	baseline?: string;
 	thresholds?: string;
 	help: boolean;
 }
 
 function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
-	const parsed: ParsedEvalArgs = { repeat: 1, compareIds: [], format: "text", help: false };
+	const parsed: ParsedEvalArgs = {
+		repeat: 1,
+		compareIds: [],
+		format: "text",
+		allowConfigDrift: false,
+		help: false,
+	};
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) continue;
@@ -110,6 +119,11 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 				index += 1;
 				continue;
 			}
+			if (arg === "--trials") {
+				parsed.trials = positiveInteger(requiredValue(args, index, "--trials"), "--trials");
+				index += 1;
+				continue;
+			}
 			throw new Error(`unknown eval run argument: ${arg}`);
 		}
 		if (parsed.command === "report") {
@@ -125,6 +139,20 @@ function parseEvalArgs(args: ReadonlyArray<string>): ParsedEvalArgs {
 			throw new Error(`unexpected eval report argument: ${arg}`);
 		}
 		if (parsed.command === "compare") {
+			if (arg === "--format") {
+				parsed.format = comparisonFormat(requiredValue(args, index, "--format"));
+				index += 1;
+				continue;
+			}
+			if (arg === "--metric") {
+				parsed.metric = requiredValue(args, index, "--metric");
+				index += 1;
+				continue;
+			}
+			if (arg === "--allow-config-drift") {
+				parsed.allowConfigDrift = true;
+				continue;
+			}
 			if (!arg.startsWith("-")) {
 				parsed.compareIds.push(arg);
 				continue;
@@ -202,15 +230,21 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 		const loaded =
 			parsed.suite !== undefined
 				? await loadEvalSuiteFile(parsed.suite)
-				: await loadV1TaskFileAsSuite(parsed.taskFile ?? "", parsed.repeat);
+				: await loadV1TaskFileAsSuite(parsed.taskFile ?? "", parsed.trials ?? parsed.repeat);
 		const resolveOptions: { target?: string; model?: string } = {};
 		if (parsed.target !== undefined) resolveOptions.target = parsed.target;
 		if (parsed.model !== undefined) resolveOptions.model = parsed.model;
-		const suite = resolveSuiteForRun(loaded.suite, resolveOptions);
+		const suite = resolveSuiteForRun(loaded.suite, {
+			...resolveOptions,
+			...(parsed.trials ? { trials: parsed.trials } : {}),
+		});
 		// Runner commands execute with cwd inside prepared eval workspaces, so a
 		// relative --clio-coder-entry must be pinned to the invoking directory here.
 		const clioEntry = resolve(parsed.clioEntry ?? process.argv[1] ?? "dist/cli/index.js");
-		const artifact = await runEvalSuiteV2({ ...loaded, suite }, { clioEntry });
+		const artifact = await runEvalSuiteV2(
+			{ ...loaded, suite },
+			{ clioEntry, freshWorkspaces: parsed.trials !== undefined },
+		);
 		const artifactPath = await writeEvalArtifactV4(clioDataDir(), artifact, parsed.out);
 		process.stdout.write(`${renderEvalTextReportV4(artifact)}artifact: ${artifactPath}\n`);
 		// A suite that declares thresholds is gated by them here, on the artifact
@@ -221,6 +255,10 @@ async function runEvalRun(parsed: ParsedEvalArgs): Promise<number> {
 			process.stdout.write(`gate: fail (${gate.failures.length} threshold failure)\n`);
 			for (const failure of gate.failures) process.stdout.write(renderGateFailure(failure));
 		}
+		if (gate !== null && gate.informational.length > 0) {
+			process.stdout.write(`informational budgets: ${gate.informational.length} notice\n`);
+			for (const finding of gate.informational) process.stdout.write(renderInformationalBudget(finding));
+		}
 		return artifact.summary.failed === 0 && (gate === null || gate.pass) ? 0 : 1;
 	} catch (error) {
 		return handleEvalLoadError(error, 1);
@@ -246,8 +284,12 @@ async function runEvalCompareCommand(parsed: ParsedEvalArgs): Promise<number> {
 		const dataDir = clioDataDir();
 		const baseline = await loadEvalArtifactV4(dataDir, baselineEvalId);
 		const candidate = await loadEvalArtifactV4(dataDir, candidateEvalId);
-		process.stdout.write(renderEvalComparisonV4(compareEvalArtifactsV4(baseline, candidate)));
-		return 0;
+		const summary = compareEvalArtifactsV4(baseline, candidate, {
+			allowConfigDrift: parsed.allowConfigDrift,
+			...(parsed.metric === undefined ? {} : { metric: parsed.metric }),
+		});
+		process.stdout.write(renderEvalComparisonReportV1(summary, parsed.format as EvalComparisonReportFormat));
+		return summary.hardGate.pass ? 0 : 1;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
 		return error instanceof InvalidIdError ? 2 : 1;
@@ -258,18 +300,35 @@ async function runEvalGateCommand(parsed: ParsedEvalArgs): Promise<number> {
 	try {
 		const dataDir = clioDataDir();
 		const candidate = await loadEvalArtifactV4(dataDir, parsed.evalId ?? "");
-		await loadEvalArtifactV4(dataDir, parsed.baseline ?? "");
+		const baseline = await loadEvalArtifactV4(dataDir, parsed.baseline ?? "");
 		const thresholds =
 			parsed.thresholds === undefined
-				? { fail: [{ metric: "result.pass", op: "eq" as const, value: false }] }
+				? { fail: [{ metric: "result.pass", op: "eq" as const, value: false }], informational: [] }
 				: loadThresholds(parsed.thresholds);
 		const gate = evaluateGate(candidate, thresholds);
-		if (gate.pass) {
+		const comparison = compareEvalArtifactsV4(baseline, candidate);
+		if (gate.informational.length > 0) {
+			process.stdout.write(`informational budgets: ${gate.informational.length} notice\n`);
+			for (const finding of gate.informational) process.stdout.write(renderInformationalBudget(finding));
+		}
+		if (gate.pass && comparison.hardGate.pass) {
 			process.stdout.write("gate: pass\n");
 			return 0;
 		}
-		process.stdout.write(`gate: fail (${gate.failures.length} threshold failure)\n`);
+		const failureCount =
+			gate.failures.length + comparison.hardGate.failures.length + comparison.hardGate.envelopeFailures.length;
+		process.stdout.write(`gate: fail (${failureCount} hard failure)\n`);
 		for (const failure of gate.failures) process.stdout.write(renderGateFailure(failure));
+		for (const failure of comparison.hardGate.failures) {
+			process.stdout.write(
+				`  ${failure.metric} [${failure.scenarioId}:${failure.role}:${failure.target.id}/${failure.target.model ?? "none"}]: ${failure.change} (hard behavioral gate)\n`,
+			);
+		}
+		for (const failure of comparison.hardGate.envelopeFailures) {
+			process.stdout.write(
+				`  execution envelope [${failure.scenarioId}:${failure.role}:${failure.target.id}/${failure.target.model ?? "none"}]: incomparable fields ${failure.fields.join(", ")}\n`,
+			);
+		}
 		return 1;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
@@ -313,3 +372,8 @@ function reportFormat(value: string): EvalReportFormat {
 	if (value === "text" || value === "json" || value === "md" || value === "swe-jsonl" || value === "junit") return value;
 	throw new Error("--format must be text, json, md, swe-jsonl, or junit");
 }
+
+function comparisonFormat(value: string): EvalComparisonReportFormat {
+	if (value === "text" || value === "json" || value === "md" || value === "junit") return value;
+	throw new Error("eval compare --format must be text, json, md, or junit");
+}

package/src/cli/extensions.ts

@@ -91,6 +91,7 @@ function resourceSummary(extension: InstalledExtension): string {
 }
 
 function stateLabel(extension: InstalledExtension): string {
+	if (!extension.compatible) return "incompatible";
 	if (!extension.enabled) return "disabled";
 	if (!extension.effective) return `shadowed:${extension.overriddenBy ?? "higher"}`;
 	return "active";
@@ -143,7 +144,10 @@ export function runExtensionsCommand(argv: ReadonlyArray<string>): number {
 		case "list": {
 			const items = listInstalledExtensions(process.cwd(), { ...scopeOptions, all: parsed.all });
 			if (parsed.json) process.stdout.write(`${JSON.stringify({ extensions: items }, null, 2)}\n`);
-			else printList(items);
+			else {
+				printList(items);
+				for (const item of items) printDiagnostics(item.diagnostics);
+			}
 			return 0;
 		}
 		case "discover": {

package/src/cli/fleet.ts

@@ -47,8 +47,8 @@ import {
 	type RunToolBudgetEnvelope,
 } from "../domains/dispatch/budget-envelope.js";
 import { type CapacityDrain, capacityDrain, setCapacityDraining } from "../domains/dispatch/capacity-lease.js";
-import type { DispatchContract } from "../domains/dispatch/contract.js";
-import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
+import { bindExecutionPlanEndpoints, type ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { agentRoleFactsResolver, requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
 import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
 import {
@@ -67,7 +67,7 @@ import { ensureClioState, LifecycleDomainModule } from "../domains/lifecycle/ind
 import { MiddlewareDomainModule } from "../domains/middleware/index.js";
 import { ObservabilityDomainModule } from "../domains/observability/index.js";
 import { createPromptsDomainModule } from "../domains/prompts/index.js";
-import { ProvidersDomainModule } from "../domains/providers/index.js";
+import { foregroundStreamUsage, ProvidersDomainModule } from "../domains/providers/index.js";
 import { ResourcesDomainModule } from "../domains/resources/index.js";
 import type { SafetyContract } from "../domains/safety/contract.js";
 import { SafetyDomainModule } from "../domains/safety/index.js";
@@ -372,6 +372,35 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		await loaded.stop();
 		return fail(err instanceof Error ? err.message : String(err));
 	}
+	if (dispatch.preview !== undefined) {
+		try {
+			const foreground = foregroundStreamUsage();
+			const bindings: Record<string, { key: string; limit: number; foregroundHeld?: number } | undefined> = {};
+			for (const step of plan.steps) {
+				if (step.kind === "code") continue;
+				const request: DispatchRequest = {
+					agentId: step.agentId,
+					executionRole: step.executionRole,
+					task: step.task,
+					...(step.scope === "readonly" ? { autonomy: "read-only" as const } : {}),
+					...(step.target !== undefined ? { target: step.target } : {}),
+					...(step.profile !== undefined ? { workerProfile: step.profile } : {}),
+				};
+				const endpoint = dispatch.preview(request).endpoint;
+				if (endpoint === undefined) continue;
+				const foregroundHeld = foreground[endpoint.key] ?? 0;
+				bindings[step.id] = {
+					key: endpoint.key,
+					limit: endpoint.limit,
+					...(foregroundHeld > 0 ? { foregroundHeld } : {}),
+				};
+			}
+			plan = bindExecutionPlanEndpoints(plan, bindings);
+		} catch (err) {
+			await loaded.stop();
+			return fail(`route preflight failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 	try {
 		preflightWriteBoundaries(plan, process.cwd());
 	} catch (err) {

package/src/cli/targets.ts

@@ -14,6 +14,7 @@ import { ConfigDomainModule } from "../domains/config/index.js";
 import { ensureClioState } from "../domains/lifecycle/index.js";
 import type { ProvidersContract, TargetStatus } from "../domains/providers/contract.js";
 import {
+	endpointCapacityForStatus,
 	isDispatchEligibleRuntime,
 	isOrchestratorEligibleRuntime,
 	ProvidersDomainModule,
@@ -24,7 +25,7 @@ import type { CapabilityFlags } from "../domains/providers/types/capability-flag
 import type { RuntimeTier } from "../domains/providers/types/runtime-descriptor.js";
 import { runConfigureCommand, runTargetRemove, runTargetRename } from "./configure.js";
 import { printError, printOk } from "./shared.js";
-import { column, terminalColumns, truncate } from "./text-layout.js";
+import { column, terminalColumns, truncate, wrapPlain } from "./text-layout.js";
 
 const HEADER: ReadonlyArray<string> = ["id", "tier", "runtime", "auth", "url", "model", "health", "caps", "notes"];
 type ProviderOutputTier = RuntimeTier | "unknown";
@@ -805,9 +806,11 @@ export interface TargetTableRow {
 	health: string;
 	caps: string;
 	notes: string;
+	/** Full degraded-health reason, kept separately so a narrow table can repeat it below the row. */
+	diagnostic?: string;
 }
 
-type TargetTableColumn = keyof TargetTableRow;
+type TargetTableColumn = Exclude<keyof TargetTableRow, "diagnostic">;
 type TargetTableWidths = Record<TargetTableColumn, number>;
 
 const TABLE_COLUMNS: ReadonlyArray<TargetTableColumn> = [
@@ -918,20 +921,35 @@ export function formatTargetTable(
 	rows: ReadonlyArray<TargetTableRow>,
 	width: number,
 	paintHealth: (cell: string, row: TargetTableRow) => string = (cell) => cell,
-): { header: string; rows: ReadonlyArray<string> } {
+): { header: string; rows: ReadonlyArray<string>; details: ReadonlyArray<ReadonlyArray<string>> } {
 	const widths = tableWidths(rows, width);
 	const line = (cells: ReadonlyArray<string>): string => cells.join(" ".repeat(TABLE_GAP)).trimEnd();
+	const formatted = rows.map((row) => {
+		const cells = TABLE_COLUMNS.map((key) => column(row[key], widths[key]));
+		const plain = line(cells);
+		const rendered =
+			plain.length > width
+				? truncate(plain, width)
+				: line(cells.map((cell, index) => (TABLE_COLUMNS[index] === "health" ? paintHealth(cell, row) : cell)));
+		const diagnosticFits = !row.diagnostic || (plain.length <= width && widths.notes >= row.diagnostic.length);
+		const details = diagnosticFits ? [] : targetDiagnosticDetails(row.diagnostic ?? "", width);
+		return { rendered, details };
+	});
 	return {
 		header: truncate(line(TABLE_COLUMNS.map((key, index) => column(HEADER[index] ?? key, widths[key]))), width),
-		rows: rows.map((row) => {
-			const cells = TABLE_COLUMNS.map((key) => column(row[key], widths[key]));
-			const plain = line(cells);
-			if (plain.length > width) return truncate(plain, width);
-			return line(cells.map((cell, index) => (TABLE_COLUMNS[index] === "health" ? paintHealth(cell, row) : cell)));
-		}),
+		rows: formatted.map(({ rendered }) => rendered),
+		details: formatted.map(({ details }) => details),
 	};
 }
 
+/** Indented diagnostic text that retains every word when the table row cannot. */
+function targetDiagnosticDetails(diagnostic: string, width: number): string[] {
+	const indent = 2;
+	return wrapPlain(`reason: ${diagnostic}`, Math.max(8, width - indent), indent).map((line, index) =>
+		index === 0 ? `${" ".repeat(indent)}${line}` : line,
+	);
+}
+
 function renderTable(providers: ProvidersContract, entries: ReadonlyArray<TargetStatus>): void {
 	const sorted = [...entries].sort(compareStatusByTier);
 	const table = formatTargetTable(
@@ -950,10 +968,12 @@ function renderTable(providers: ProvidersContract, entries: ReadonlyArray<Target
 			process.stdout.write(`${chalk.bold(table.header)}\n`);
 		}
 		process.stdout.write(`${table.rows[index] ?? ""}\n`);
+		for (const detail of table.details[index] ?? []) process.stdout.write(`${detail}\n`);
 	}
 }
 
 export function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
+	const diagnostic = degradedHealthDiagnostic(status);
 	return {
 		id: status.target.id,
 		tier: statusTier(status),
@@ -964,6 +984,7 @@ export function targetTableRow(providers: ProvidersContract, status: TargetStatu
 		health: status.health.status,
 		caps: capabilityBadges(status.capabilities),
 		notes: formatNotes(status),
+		...(diagnostic ? { diagnostic } : {}),
 	};
 }
 
@@ -1044,22 +1065,29 @@ export function formatContextWindow(
 		: `ctx ${window}`;
 }
 
-function formatNotes(status: TargetStatus): string {
+export function formatNotes(status: TargetStatus): string {
 	const parts: string[] = [];
+	const diagnostic = degradedHealthDiagnostic(status);
+	// The health diagnosis leads because gateway, context, and residency facts
+	// are supplementary once the target says it cannot serve its default model.
+	if (diagnostic) parts.push(diagnostic);
+	const endpoint = endpointCapacityForStatus(status);
+	if (endpoint) parts.push(`slots ${endpoint.limit}`);
 	if (status.target.gateway) parts.push("gateway");
 	if (status.runtime?.auth === "oauth") parts.push("oauth");
 	if (status.runtime?.auth === "claude-cli") parts.push("claude-cli");
 	if (status.capabilities.contextWindow > 0) parts.push(formatContextWindow(status));
 	if (!status.available && status.reason) parts.push(status.reason);
-	// A reachable target that cannot serve its own default is degraded, and the
-	// row has to say why or the model column reads as a model that works.
-	if (status.health.status === "degraded" && status.health.lastError) parts.push(status.health.lastError);
 	const residency = residentModelsSummary(status.discoveredModelStates);
 	if (residency) parts.push(residency);
 	if (status.probeNotes && status.probeNotes.length > 0) parts.push(`note: ${status.probeNotes.join("; ")}`);
 	return parts.join(" ");
 }
 
+function degradedHealthDiagnostic(status: TargetStatus): string | null {
+	return status.health.status === "degraded" && status.health.lastError ? status.health.lastError : null;
+}
+
 function statusTier(status: TargetStatus): ProviderOutputTier {
 	return status.runtime?.tier ?? "unknown";
 }
@@ -1120,6 +1148,7 @@ interface SerializedStatus {
 	tier: ProviderOutputTier;
 	detectedReasoning: boolean | null;
 	reasoningCandidateModelId: string | null;
+	endpointCapacity?: ReturnType<typeof endpointCapacityForStatus>;
 }
 
 function serializeStatus(
@@ -1141,6 +1170,8 @@ function serializeStatus(
 		detectedReasoning: extras.detectedReasoning,
 		reasoningCandidateModelId: extras.candidateModelId,
 	};
+	const endpointCapacity = endpointCapacityForStatus(status);
+	if (endpointCapacity !== null) out.endpointCapacity = endpointCapacity;
 	if (status.contextWindowProvenance !== undefined) {
 		out.contextWindowProvenance = status.contextWindowProvenance;
 	}