@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/cli/index.ts

@@ -57,7 +57,7 @@ Usage:
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
   clio-coder upgrade              upgrade Clio Coder and run pending migrations
   clio-coder agents               list discovered agent recipes
-  clio-coder fleet list|run|status|drain|resume  fleet contracts, status, and admission control
+  clio-coder fleet new|validate|graph|commands|run|status|drain|resume  fleet authoring, execution, status, and admission control
   clio-coder evidence             build, list, or inspect evidence artifacts
   clio-coder eval                 run, report, or compare local eval task files
   clio-coder memory               list, propose, promote, approve, reject, or prune memory
@@ -65,6 +65,7 @@ Usage:
   clio-coder trace                query or view the durable dispatch trace mirror
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder skills               list, inspect, validate, or install skills
+  clio-coder library              list, search, add, or sync agents, prompts, fleets, and skills from catalogs
   clio-coder verifiers            discover, author, validate, edit, or dry-run project checks
   clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
@@ -246,6 +247,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["ext", extensionsCommand],
 	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
 	["skills", async (subArgs) => (await import("./skills.js")).runSkillsCommand(subArgs)],
+	["library", async (subArgs) => (await import("./library.js")).runLibraryCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],

package/src/cli/library.ts

@@ -0,0 +1,190 @@
+import {
+	classifyLibraryRequirements,
+	confirmLibraryRemote,
+	discoverLibrary,
+	installLibraryPlan,
+	type LibraryEntry,
+	type LibraryEntryKind,
+	libraryEntryRef,
+	libraryInstallPath,
+	planLibraryInstall,
+	syncLibrary,
+} from "../domains/resources/index.js";
+import { printError, printOk } from "./shared.js";
+
+const KINDS = new Set<LibraryEntryKind>(["skill", "agent", "prompt", "fleet"]);
+const HELP = `clio-coder library <command>
+
+Commands:
+  clio-coder library list [--kind <kind>] [--json]
+  clio-coder library search <query> [--kind <kind>] [--json]
+  clio-coder library add <ref> [--from <catalog|path>] [--with-requirements] [--yes] [--json]
+  clio-coder library use <kind> <name>
+  clio-coder library sync
+  clio-coder library push
+  clio-coder library remote confirm <url>
+`;
+
+interface Parsed {
+	command?: string;
+	positional: string[];
+	kind?: LibraryEntryKind;
+	from?: string;
+	json: boolean;
+	yes: boolean;
+	withRequirements: boolean;
+	help: boolean;
+}
+
+function parse(argv: ReadonlyArray<string>): Parsed {
+	const out: Parsed = { positional: [], json: false, yes: false, withRequirements: false, help: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (!arg) continue;
+		if (!out.command && !arg.startsWith("-")) {
+			out.command = arg;
+			continue;
+		}
+		if (arg === "--json") out.json = true;
+		else if (arg === "--yes") out.yes = true;
+		else if (arg === "--with-requirements") out.withRequirements = true;
+		else if (arg === "--help" || arg === "-h") out.help = true;
+		else if (arg === "--kind") {
+			const value = argv[++i];
+			if (!value || !KINDS.has(value as LibraryEntryKind))
+				throw new Error("--kind requires skill, agent, prompt, or fleet");
+			out.kind = value as LibraryEntryKind;
+		} else if (arg === "--from") {
+			const value = argv[++i];
+			if (!value) throw new Error("--from requires a value");
+			out.from = value;
+		} else if (arg.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
+		else out.positional.push(arg);
+	}
+	return out;
+}
+
+function selectEntry(entries: ReadonlyArray<LibraryEntry>, ref: string): LibraryEntry {
+	const matches = ref.includes(":")
+		? entries.filter((entry) => libraryEntryRef(entry) === ref)
+		: entries.filter((entry) => entry.name === ref);
+	if (matches.length === 0) throw new Error(`library entry not found: ${ref}`);
+	if (matches.length > 1)
+		throw new Error(`library entry is ambiguous; use a typed reference: ${matches.map(libraryEntryRef).join(", ")}`);
+	return matches[0] as LibraryEntry;
+}
+
+function filtered(entries: ReadonlyArray<LibraryEntry>, kind?: LibraryEntryKind): LibraryEntry[] {
+	return entries.filter((entry) => kind === undefined || entry.kind === kind);
+}
+
+export async function runLibraryCommand(argv: ReadonlyArray<string>): Promise<number> {
+	let parsed: Parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 2;
+	}
+	if (!parsed.command || parsed.help) {
+		process.stdout.write(HELP);
+		return parsed.help ? 0 : 2;
+	}
+	try {
+		if (parsed.command === "list" || parsed.command === "search") {
+			const discovery = discoverLibrary();
+			const query = parsed.command === "search" ? parsed.positional.join(" ").trim().toLowerCase() : "";
+			if (parsed.command === "search" && !query) throw new Error("library search requires a query");
+			const entries = filtered(discovery.entries, parsed.kind).filter(
+				(entry) => !query || entry.name.toLowerCase().includes(query) || entry.description.toLowerCase().includes(query),
+			);
+			if (parsed.json)
+				process.stdout.write(`${JSON.stringify({ entries, diagnostics: discovery.diagnostics }, null, 2)}\n`);
+			else
+				for (const entry of entries) process.stdout.write(`${libraryEntryRef(entry).padEnd(28)} ${entry.description}\n`);
+			return 0;
+		}
+		if (parsed.command === "add") {
+			const ref = parsed.positional[0];
+			if (!ref || parsed.positional.length !== 1) throw new Error("library add requires one reference");
+			const catalog = parsed.from && parsed.from !== "catalog" ? parsed.from : undefined;
+			const discovery = discoverLibrary(catalog ? { catalog } : {});
+			let entry: LibraryEntry;
+			try {
+				entry = selectEntry(discovery.entries, ref);
+			} catch (error) {
+				const refusal = ref.includes(":")
+					? discovery.refusals[ref]
+					: Object.entries(discovery.refusals).find(([key]) => key.endsWith(`:${ref}`))?.[1];
+				if (refusal) throw new Error(refusal);
+				throw error;
+			}
+			const requirements = classifyLibraryRequirements(entry, discovery.entries);
+			if (requirements.unsatisfied.length > 0 && !parsed.withRequirements) {
+				const refs = requirements.unsatisfied.map(libraryEntryRef);
+				if (parsed.json)
+					process.stdout.write(
+						`${JSON.stringify({ ok: false, entry: libraryEntryRef(entry), satisfiedRequirements: requirements.satisfied.map(libraryEntryRef), unresolvedRequirements: refs }, null, 2)}\n`,
+					);
+				else
+					process.stderr.write(
+						`satisfied requirements: ${requirements.satisfied.length > 0 ? requirements.satisfied.map(libraryEntryRef).join(", ") : "none"}\nunresolved requirements: ${refs.join(", ")}\npass --with-requirements to install them in dependency order\n`,
+					);
+				return 1;
+			}
+			const plans = [...(parsed.withRequirements ? requirements.unsatisfied : []), entry].map(planLibraryInstall);
+			if (parsed.json)
+				process.stdout.write(
+					`${JSON.stringify({ ok: true, confirmed: parsed.yes, satisfiedRequirements: requirements.satisfied.map(libraryEntryRef), writes: plans.map((plan) => ({ ref: libraryEntryRef(plan.entry), path: plan.path, sha256: plan.sha256 })) }, null, 2)}\n`,
+				);
+			else {
+				process.stdout.write("library add plan:\n");
+				process.stdout.write(
+					`  satisfied requirements: ${requirements.satisfied.length > 0 ? requirements.satisfied.map(libraryEntryRef).join(", ") : "none"}\n`,
+				);
+				for (const plan of plans)
+					process.stdout.write(`  ${libraryEntryRef(plan.entry)} -> ${plan.path} sha256 ${plan.sha256}\n`);
+			}
+			if (!parsed.yes) return 0;
+			for (const plan of plans) installLibraryPlan(plan);
+			if (!parsed.json) printOk(`installed ${plans.length} library entry or entries`);
+			return 0;
+		}
+		if (parsed.command === "use") {
+			const kind = parsed.positional[0] as LibraryEntryKind | undefined;
+			const name = parsed.positional[1];
+			if (!kind || !KINDS.has(kind) || !name || parsed.positional.length !== 2)
+				throw new Error("library use requires a kind and name");
+			// A skill is loaded by the operator from the Skills Hub, never by a CLI
+			// verb, so the honest answer names where it lives and how to load it.
+			const output =
+				kind === "fleet"
+					? `clio-coder fleet run ${name}`
+					: kind === "agent"
+						? `/run ${name}`
+						: kind === "skill"
+							? `${libraryInstallPath({ kind, name })}\nload it from /skill in the TUI, or ask the model to call context(scope="skills")`
+							: name;
+			process.stdout.write(`${output}\n`);
+			return 0;
+		}
+		if (parsed.command === "remote") {
+			if (parsed.positional[0] !== "confirm" || !parsed.positional[1] || parsed.positional.length !== 2)
+				throw new Error("library remote confirm requires a URL");
+			confirmLibraryRemote(parsed.positional[1]);
+			printOk("confirmed library remote");
+			return 0;
+		}
+		if (parsed.command === "sync" || parsed.command === "push") {
+			await syncLibrary(parsed.command);
+			printOk(`library ${parsed.command} complete`);
+			return 0;
+		}
+		throw new Error(`unknown library command: ${parsed.command}`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		printError(message);
+		if (parsed.json) process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		return 1;
+	}
+}

package/src/cli/share.ts

@@ -15,7 +15,7 @@ const HELP = `clio-coder share <command>
 Export and import portable Clio project/resource archives.
 
 Commands:
-  clio-coder share export --out <path> [--project|--user|--both] [--context] [--prompts] [--skills] [--settings] [--extensions]
+  clio-coder share export --out <path> [--project|--user|--both] [--context] [--prompts] [--skills] [--agents] [--fleets] [--settings] [--extensions]
   clio-coder share import <path> [--dry-run] [--force] [--project|--user] [--json]
   clio-coder share inspect <path> [--json]
 
@@ -36,6 +36,8 @@ interface Parsed {
 	includeContext?: boolean;
 	includePrompts?: boolean;
 	includeSkills?: boolean;
+	includeAgents?: boolean;
+	includeFleets?: boolean;
 	includeSettings?: boolean;
 	includeExtensions?: boolean;
 }
@@ -93,6 +95,12 @@ function parse(argv: ReadonlyArray<string>): Parsed | null {
 			case "--skills":
 				out.includeSkills = true;
 				break;
+			case "--agents":
+				out.includeAgents = true;
+				break;
+			case "--fleets":
+				out.includeFleets = true;
+				break;
 			case "--settings":
 				out.includeSettings = true;
 				break;
@@ -103,6 +111,8 @@ function parse(argv: ReadonlyArray<string>): Parsed | null {
 				out.includeContext = true;
 				out.includePrompts = true;
 				out.includeSkills = true;
+				out.includeAgents = true;
+				out.includeFleets = true;
 				out.includeSettings = true;
 				out.includeExtensions = true;
 				break;
@@ -152,6 +162,8 @@ function exportOptions(parsed: Parsed): ShareExportOptions {
 		...(parsed.includeContext !== undefined ? { includeContext: parsed.includeContext } : {}),
 		...(parsed.includePrompts !== undefined ? { includePrompts: parsed.includePrompts } : {}),
 		...(parsed.includeSkills !== undefined ? { includeSkills: parsed.includeSkills } : {}),
+		...(parsed.includeAgents !== undefined ? { includeAgents: parsed.includeAgents } : {}),
+		...(parsed.includeFleets !== undefined ? { includeFleets: parsed.includeFleets } : {}),
 		...(parsed.includeSettings !== undefined ? { includeSettings: parsed.includeSettings } : {}),
 		...(parsed.includeExtensions !== undefined ? { includeExtensions: parsed.includeExtensions } : {}),
 	};

package/src/cli/shared.ts

@@ -15,6 +15,7 @@ export {
 	parseFlags,
 	printError,
 	printHeader,
+	printNote,
 	printOk,
 } from "./argv.js";
 

package/src/cli/targets.ts

@@ -953,7 +953,7 @@ function renderTable(providers: ProvidersContract, entries: ReadonlyArray<Target
 	}
 }
 
-function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
+export function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
 	return {
 		id: status.target.id,
 		tier: statusTier(status),
@@ -1051,6 +1051,9 @@ function formatNotes(status: TargetStatus): string {
 	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("; ")}`);

package/src/cli/usage.ts

@@ -9,6 +9,7 @@ import {
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
 import { readEvidenceIndex } from "../domains/observability/evidence-index.js";
+import { type OutOfTurnUsageRow, readOutOfTurnUsageRows } from "../domains/observability/out-of-turn-usage.js";
 import { loadSkills } from "../domains/resources/index.js";
 import {
 	type LedgerUsageCall,
@@ -23,9 +24,10 @@ import { formatColumns, printError } from "./shared.js";
 const HELP = `clio-coder usage report [--repo <path>] [--days <n>] [--json]
 
 Cross-session usage analyzer (experimental, read-only). Reads the local usage
-archive (receipts, session ledgers, audit rows, evidence index, memory store)
-and reports facts plus improvement opportunities, every line citing ids and
-counts. Nothing is written or stored; suggestions are printed only.
+archive (receipts, session ledgers, the out-of-turn usage store, audit rows,
+evidence index, memory store) and reports facts plus improvement opportunities,
+every line citing ids and counts. Nothing is written or stored; suggestions are
+printed only.
 
 Flags:
   --repo <path>   restrict sessions (and runs via the run ledger) to one repo
@@ -98,6 +100,54 @@ function addResponseModelIdObservation(counts: ResponseModelIdObservationCounts,
 	addResponseModelIdObservationCount(counts, call.responseModelIdObservation, call.apiCalls ?? 1);
 }
 
+/**
+ * How the folded calls split between the session's own turns and the rounds
+ * that were billed beside it. A `/btw` side question and a `/handoff` round are
+ * real spend and belong in the token and cost totals, but neither is a turn:
+ * they never entered the session. `turns` therefore subtracts them from the
+ * folded row count, which is exactly what the `/cost` overlay does.
+ */
+interface CallOrigins {
+	rows: number;
+	sideQuestions: number;
+	handoffs: number;
+}
+
+function emptyCallOrigins(): CallOrigins {
+	return { rows: 0, sideQuestions: 0, handoffs: 0 };
+}
+
+function turnsOf(origins: CallOrigins): number {
+	return origins.rows - origins.sideQuestions - origins.handoffs;
+}
+
+function hasLabelledCall(origins: CallOrigins): boolean {
+	return origins.sideQuestions > 0 || origins.handoffs > 0;
+}
+
+function addOutOfTurnRow(origins: CallOrigins, row: OutOfTurnUsageRow): void {
+	origins.rows += 1;
+	if (row.label === "side-question") origins.sideQuestions += 1;
+	else origins.handoffs += 1;
+}
+
+/** The out-of-turn store keeps its own usage shape; fold it as one completed call. */
+function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
+	return {
+		providerId: row.target,
+		attributedModelId: row.attributedModelId,
+		requestedModelId: row.attributedModelId,
+		responseModelIdObservation: { state: "not-observed" },
+		input: row.usage.input,
+		output: row.usage.output,
+		cacheRead: row.usage.cacheRead,
+		cacheWrite: row.usage.cacheWrite,
+		reasoningTokens: row.usage.reasoning,
+		totalTokens: row.usage.totalTokens,
+		costUsd: row.usage.costUsd,
+	};
+}
+
 function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.apiCalls += call.apiCalls ?? 1;
 	totals.input += call.input;
@@ -250,6 +300,13 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		(receipt) => repoRunIds === null || repoRunIds.has(receipt.runId),
 	);
 	const sessions = await readSessions(stateDir, windowStart, now, repoHash, diagnostics);
+	// Side questions and handoff rounds append nothing to the session ledger by
+	// design, so their spend lives in its own store and is folded in here.
+	const outOfTurn = readOutOfTurnUsageRows(stateDir);
+	for (const error of outOfTurn.errors) diagnostics.notes.push(error);
+	const outOfTurnRows = outOfTurn.rows.filter(
+		(row) => inWindow(row.timestamp, windowStart, now) && (repoHash === undefined || row.repoIdentity === repoHash),
+	);
 	const auditRows = await readAuditRows(stateDir);
 	diagnostics.malformedAuditRows = auditRows.errors.length;
 	const auditInWindow = auditRows.rows.filter((row) => row.ts !== null && inWindow(row.ts, windowStart, now));
@@ -345,23 +402,36 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		}
 	>();
 	const usageTotals = emptyUsageTotals();
+	const callOrigins = emptyCallOrigins();
+	const foldCall = (call: LedgerUsageCall): void => {
+		addUsageCall(usageTotals, call);
+		const key = `${call.providerId}::${call.attributedModelId}`;
+		const entry = usageByModel.get(key) ?? {
+			providerId: call.providerId,
+			attributedModelId: call.attributedModelId,
+			requestedModelIds: new Set<string>(),
+			responseModelIdObservationCounts: emptyResponseModelIdObservationCounts(),
+			totals: emptyUsageTotals(),
+		};
+		entry.requestedModelIds.add(call.requestedModelId);
+		addResponseModelIdObservation(entry.responseModelIdObservationCounts, call);
+		addUsageCall(entry.totals, call);
+		usageByModel.set(key, entry);
+	};
 	for (const session of sessions) {
 		for (const call of session.usageCalls) {
-			addUsageCall(usageTotals, call);
-			const key = `${call.providerId}::${call.attributedModelId}`;
-			const entry = usageByModel.get(key) ?? {
-				providerId: call.providerId,
-				attributedModelId: call.attributedModelId,
-				requestedModelIds: new Set<string>(),
-				responseModelIdObservationCounts: emptyResponseModelIdObservationCounts(),
-				totals: emptyUsageTotals(),
-			};
-			entry.requestedModelIds.add(call.requestedModelId);
-			addResponseModelIdObservation(entry.responseModelIdObservationCounts, call);
-			addUsageCall(entry.totals, call);
-			usageByModel.set(key, entry);
+			foldCall(call);
+			callOrigins.rows += 1;
 		}
 	}
+	for (const row of outOfTurnRows) {
+		foldCall(outOfTurnUsageCall(row));
+		addOutOfTurnRow(callOrigins, row);
+	}
+	// Token and cost facts need one of their two inputs on disk. A machine whose
+	// session store is gone can still have recorded out-of-turn spend, and
+	// dropping those rows would report money that was spent as nothing at all.
+	const usageMeasurable = presence.sessionsPresent || outOfTurnRows.length > 0;
 	const usageRows = [...usageByModel.values()].sort(
 		(a, b) => b.totals.totalTokens - a.totals.totalTokens || a.providerId.localeCompare(b.providerId),
 	);
@@ -443,8 +513,22 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		if (presence.receiptsPresent) emit({ kind: "fact", fact: "dispatch-runs", value: receipts.length });
 		else emit({ kind: "fact", fact: "receipt-store-missing", path: presence.receiptsPath });
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
-		if (presence.sessionsPresent) {
-			emit({ kind: "fact", fact: "tokens", ...usageTotals });
+		if (usageMeasurable) {
+			// The origin split is emitted only when something out of turn was
+			// recorded, so a report over an archive with no `/btw` or `/handoff`
+			// round in it stays byte-identical to what it printed before.
+			emit({
+				kind: "fact",
+				fact: "tokens",
+				...usageTotals,
+				...(hasLabelledCall(callOrigins)
+					? {
+							turns: turnsOf(callOrigins),
+							sideQuestions: callOrigins.sideQuestions,
+							handoffs: callOrigins.handoffs,
+						}
+					: {}),
+			});
 			for (const row of usageRows) {
 				emit({
 					kind: "fact",
@@ -505,10 +589,18 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		out(`  receipt store missing at ${presence.receiptsPath}`);
 	}
 	out(`  audited tool calls in window: ${auditToolCalls.length} (${auditBlocked.length} blocked/denied)`);
-	if (presence.sessionsPresent) {
+	if (usageMeasurable) {
 		out(
 			`  tokens in window: ${usageTotals.totalTokens} over ${usageTotals.apiCalls} model calls (input ${usageTotals.input}, output ${usageTotals.output}, cache read ${usageTotals.cacheRead}, cache write ${usageTotals.cacheWrite}, reasoning ${usageTotals.reasoningTokens})`,
 		);
+		if (hasLabelledCall(callOrigins)) {
+			// Only printed when a labelled call is in the window. Over an archive
+			// with none, these three lines would say nothing the line above does
+			// not already say, and their absence keeps the older output intact.
+			out(`  turns in window: ${turnsOf(callOrigins)}`);
+			if (callOrigins.sideQuestions > 0) out(`  side questions in window: ${callOrigins.sideQuestions}`);
+			if (callOrigins.handoffs > 0) out(`  handoffs in window: ${callOrigins.handoffs}`);
+		}
 		out(`  provider-reported cost in window: $${usageTotals.costUsd.toFixed(4)}`);
 	}
 	if (usageRows.length > 0) {

package/src/cli/validate-model.ts

@@ -1,7 +1,25 @@
+/**
+ * What a target advertised when it was asked, for runtimes with no static
+ * catalog. `models` is the id list the probe returned and `resident` the
+ * subset the server reports as loaded, when it reports load state at all.
+ */
+export interface LiveModelInventory {
+	targetId: string;
+	url?: string | undefined;
+	models: ReadonlyArray<string>;
+	resident: ReadonlyArray<string>;
+}
+
 export interface ValidateModelInput {
 	runtimeId: string;
 	modelId: string;
 	knownModels: ReadonlyArray<string>;
+	/**
+	 * The live list, when one was fetched. It is consulted only when the static
+	 * catalog is empty, so the catalog stays the authority for cloud runtimes
+	 * and the probe becomes the authority where there is nothing else.
+	 */
+	live?: LiveModelInventory | undefined;
 	force: boolean;
 }
 
@@ -9,9 +27,30 @@ export type ValidateModelResult =
 	| { ok: true; warning?: string }
 	| { ok: false; reason: string; knownModels: ReadonlyArray<string> };
 
+const SAMPLE_SIZE = 10;
+
+function sample(models: ReadonlyArray<string>): string {
+	const shown = models.slice(0, SAMPLE_SIZE).join(", ");
+	return models.length > SAMPLE_SIZE ? `${shown}, …` : shown;
+}
+
+function describeLiveTarget(live: LiveModelInventory): string {
+	return live.url ? `target '${live.targetId}' at ${live.url}` : `target '${live.targetId}'`;
+}
+
+/** The refusal `configure` prints for a model the live target does not advertise. */
+export function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
+	const resident = live.resident.length > 0 ? live.resident.join(", ") : "none";
+	return (
+		`${describeLiveTarget(live)} does not advertise model '${modelId}'. ` +
+		`Advertised (${live.models.length}): ${sample(live.models)}. Resident instances: ${resident}. ` +
+		"Pass one of the advertised ids with --model, or --force to save a model the target cannot serve."
+	);
+}
+
 export function validateModelChoice(input: ValidateModelInput): ValidateModelResult {
-	const { runtimeId, modelId, knownModels, force } = input;
-	if (knownModels.length === 0) return { ok: true };
+	const { runtimeId, modelId, knownModels, live, force } = input;
+	if (knownModels.length === 0) return validateAgainstLive(modelId, live, force);
 	if (knownModels.includes(modelId)) return { ok: true };
 	if (force) {
 		return {
@@ -19,10 +58,26 @@ export function validateModelChoice(input: ValidateModelInput): ValidateModelRes
 			warning: `model '${modelId}' not in ${runtimeId} catalog (use without --force to reject)`,
 		};
 	}
-	const sample = knownModels.slice(0, 10).join(", ");
 	return {
 		ok: false,
-		reason: `model '${modelId}' not in ${runtimeId} catalog. Known: ${sample}. Use --force to skip validation.`,
-		knownModels: knownModels.slice(0, 10),
+		reason: `model '${modelId}' not in ${runtimeId} catalog. Known: ${sample(knownModels)}. Use --force to skip validation.`,
+		knownModels: knownModels.slice(0, SAMPLE_SIZE),
 	};
 }
+
+/**
+ * With no catalog, the live list is the only evidence there is. An empty
+ * catalog used to be an early `ok` on its own, which is how a placeholder id
+ * was written next to the very list that ruled it out.
+ */
+function validateAgainstLive(
+	modelId: string,
+	live: LiveModelInventory | undefined,
+	force: boolean,
+): ValidateModelResult {
+	if (!live || live.models.length === 0) return { ok: true };
+	if (live.models.includes(modelId)) return { ok: true };
+	const reason = formatUnadvertisedModelReason(modelId, live);
+	if (force) return { ok: true, warning: `${reason.replace(/ Pass one of.*$/u, "")} Saved anyway because of --force.` };
+	return { ok: false, reason, knownModels: live.models.slice(0, SAMPLE_SIZE) };
+}

package/src/core/bus-events.ts

@@ -51,6 +51,7 @@ export const BusChannels = {
 	ToolBudgetExceeded: "safety.toolBudgetExceeded",
 	ProviderHealth: "provider.health",
 	RuntimeNotice: "runtime.notice",
+	DispatchScopeNotice: "dispatch.scopeNotice",
 	DispatchEnqueued: "dispatch.enqueued",
 	DispatchStarted: "dispatch.started",
 	DispatchProgress: "dispatch.progress",
@@ -108,6 +109,29 @@ export interface ContextWarningPayload {
 	warning: string | null;
 }
 
+/** A dispatch path-scope decision that must remain visible in the operator transcript. */
+export type DispatchScopeNoticePayload =
+	| {
+			code: "typed_scope_replaced_inferred_paths";
+			level: "warning";
+			agentId: string;
+			omittedPaths: ReadonlyArray<string>;
+			message: string;
+	  }
+	| {
+			code: "legacy_scope_inferred" | "legacy_scope_empty";
+			level: "warning";
+			agentId: string;
+			paths: ReadonlyArray<{
+				path: string;
+				policy: "working-context" | "write-boundary";
+				provenance: "declared" | "derived" | "inferred";
+				source: "intent.read_roots" | "intent.write_roots" | "intent.relevant_paths" | "writeRoots" | "task" | "briefing";
+				confidence: "certain" | "high" | "medium" | "low";
+			}>;
+			message: string;
+	  };
+
 export type ContextActivityKind = "context-init" | "context-clear" | "context-refresh" | "context-wiki" | "compaction";
 export type ContextActivityPhase = "scan" | "codewiki" | "generate" | "clio-md" | "state" | "done";
 export type ContextActivityStatus = "started" | "running" | "completed" | "failed";
@@ -487,6 +511,8 @@ export interface DispatchRunIdentity {
 	node?: string | undefined;
 	/** Review/compete gate role and cycle, for fleet board badges. */
 	gate?: { role: string; cycle: number } | undefined;
+	/** Council group presentation data for the Fleet Runs board. */
+	council?: { group: string; label: string; color?: string; round: number } | undefined;
 	/** Dead-node failover hops recorded on this run's chain so far. */
 	rerouteCount?: number | undefined;
 	/** Model context window in tokens, for the per-worker context meter. */
@@ -572,6 +598,8 @@ export interface DispatchTerminalStats {
 	exitCode: number;
 	/** Honest activity record aggregated from the run's tool telemetry; null when the receipt predates it. */
 	toolActivity: ToolActivitySummary | null;
+	/** Host-run declared verification status when the request included checks. */
+	hostVerification?: "verified" | "rejected" | "skipped";
 }
 
 /** Published on {@link BusChannels.DispatchCompleted} when a run finalizes as succeeded. */
@@ -733,6 +761,7 @@ export type BusPayloadMap = {
 	[BusChannels.ToolBudgetExceeded]: ToolBudgetExceededPayload;
 	[BusChannels.ProviderHealth]: ProviderHealthPayload;
 	[BusChannels.RuntimeNotice]: RuntimeNoticePayload;
+	[BusChannels.DispatchScopeNotice]: DispatchScopeNoticePayload;
 	[BusChannels.DispatchEnqueued]: DispatchEnqueuedPayload;
 	[BusChannels.DispatchStarted]: DispatchStartedPayload;
 	[BusChannels.DispatchProgress]: DispatchProgressPayload;

package/src/core/commit-attribution.ts

@@ -16,7 +16,7 @@ export const CLIO_COMMIT_TRAILERS = {
 } as const;
 
 export interface CommitReceiptEvidence {
-	version: 15;
+	version: 20;
 	algorithm: "sha256";
 	digest: string;
 	/** The receipt was checked against its run-ledger envelope. */
@@ -58,7 +58,7 @@ const KNOWN_CLIO_TRAILERS = new Set(
 );
 
 function isClioTrailer(key: string): boolean {
-	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v15/sha256:");
+	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v20/sha256:");
 }
 
 /**
@@ -87,7 +87,7 @@ function trailerBlockStart(lines: ReadonlyArray<string>): number | null {
 
 function receiptTrailer(receipt: CommitReceiptEvidence | undefined): string | null {
 	if (
-		receipt?.version !== 15 ||
+		receipt?.version !== 20 ||
 		receipt.algorithm !== "sha256" ||
 		receipt.integrityValid !== true ||
 		receipt.directlyRelevant !== true ||
@@ -95,7 +95,7 @@ function receiptTrailer(receipt: CommitReceiptEvidence | undefined): string | nu
 	) {
 		return null;
 	}
-	return `Clio-Evidence: receipt-v15/sha256:${receipt.digest}`;
+	return `Clio-Evidence: receipt-v20/sha256:${receipt.digest}`;
 }
 
 /**