@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/cli/configure.ts

@@ -27,7 +27,12 @@ import { fingerprintNativeRuntime } from "../domains/providers/probe/fingerprint
 import { getRuntimeRegistry } from "../domains/providers/registry.js";
 import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.js";
 import { greetLmStudio } from "../domains/providers/runtimes/common/lmstudio-http.js";
-import type { ProbeContext, ProbeResult, RuntimeDescriptor } from "../domains/providers/types/runtime-descriptor.js";
+import type {
+	ProbeContext,
+	ProbeModelStatus,
+	ProbeResult,
+	RuntimeDescriptor,
+} from "../domains/providers/types/runtime-descriptor.js";
 import type { TargetDescriptor } from "../domains/providers/types/target-descriptor.js";
 import { registerClioOAuthProviders } from "../engine/oauth.js";
 import { ask, askYesNo } from "./ask.js";
@@ -44,7 +49,7 @@ import { createDelayedManualCodeInput } from "./oauth-manual-input.js";
 import { promptOAuthSelection } from "./oauth-select.js";
 import { credentialWriteFailed, printError, printOk, printPlaintextCredentialWarning } from "./shared.js";
 import { terminalColumns, wrapPlain } from "./text-layout.js";
-import { validateModelChoice } from "./validate-model.js";
+import { type LiveModelInventory, validateModelChoice } from "./validate-model.js";
 
 const HELP = `clio-coder configure
 
@@ -70,7 +75,8 @@ Non-interactive flags:
   --agent-profile-model <id>       model to use for --agent-profile
   --api-key-env <VAR>              read API key from this env var at call time
   --api-key <literal>              store API key in credentials.yaml
-  --force                          allow a model outside the runtime catalog
+  --force                          save a model outside the runtime catalog, or one the
+                                   target does not advertise, without refusing
   --gateway                        mark the target as a gateway
   --lifecycle <user-managed|clio-managed>
                                   resident model lifecycle policy
@@ -378,19 +384,35 @@ function catalogContextWindowFor(runtime: RuntimeDescriptor, modelId: string): n
 	return null;
 }
 
-function validateResolvedModel(runtimeId: string, modelId: string | undefined, force: boolean): boolean {
+/**
+ * Check the resolved model against the catalog where there is one and against
+ * the target's own list where there is not. A runtime with no catalog used to
+ * pass any string here while the same command wrote the live list that ruled
+ * it out into `wireModels`, so the target saved as `ok` and failed on its first
+ * turn. Without a catalog or a live list there is nothing to check against, and
+ * the note says so rather than implying the id was verified.
+ */
+function validateResolvedModel(
+	runtime: RuntimeDescriptor,
+	target: Pick<TargetDescriptor, "id" | "url">,
+	modelId: string | undefined,
+	force: boolean,
+	inventory: WireModelInventory,
+): boolean {
 	if (!modelId) return true;
-	const validation = validateModelChoice({
-		runtimeId,
-		modelId,
-		knownModels: runtimeKnownModelsFor(runtimeId),
-		force,
-	});
+	const knownModels = runtimeKnownModelsFor(runtime.id);
+	const live = inventory.source === "probe" ? liveInventoryFor(target, inventory) : undefined;
+	const validation = validateModelChoice({ runtimeId: runtime.id, modelId, knownModels, live, force });
 	if (!validation.ok) {
 		process.stderr.write(`error: ${validation.reason}\n`);
 		return false;
 	}
 	if (validation.warning) process.stderr.write(`warning: ${validation.warning}\n`);
+	if (knownModels.length === 0 && live === undefined && runtime.kind === "http") {
+		process.stderr.write(
+			`warning: could not verify model '${modelId}': ${target.url ?? `target '${target.id}'`} returned no model list; it is saved as written\n`,
+		);
+	}
 	return true;
 }
 
@@ -412,10 +434,15 @@ function validateContextWindowOverride(
 	return true;
 }
 
-async function runtimeProbe(runtime: RuntimeDescriptor, target: TargetDescriptor): Promise<ProbeResult | null> {
+async function runtimeProbe(
+	runtime: RuntimeDescriptor,
+	target: TargetDescriptor,
+	authToken?: string,
+): Promise<ProbeResult | null> {
 	if (typeof runtime.probe !== "function") return null;
 	try {
-		return await runtime.probe(target, await buildProbeContext(runtime, target));
+		const context = await buildProbeContext(runtime, target);
+		return await runtime.probe(target, authToken === undefined ? context : { ...context, authToken });
 	} catch (err) {
 		return { ok: false, error: err instanceof Error ? err.message : String(err) };
 	}
@@ -679,17 +706,69 @@ async function loginOAuthRuntime(rl: ReturnType<typeof createInterface>, runtime
 	}
 }
 
+/**
+ * The model ids a target can be configured with, and where they came from.
+ * `probe` is the only source that says anything about the server in front of
+ * us right now; `catalog` is static provider knowledge, and `existing` is the
+ * list a previous configure recorded, which the server may no longer match.
+ */
+interface WireModelInventory {
+	models: string[];
+	source: "catalog" | "probe" | "existing" | "none";
+	/** Per-model load state when the probe reported it. */
+	modelStates?: Readonly<Record<string, ProbeModelStatus>> | undefined;
+}
+
+/**
+ * Every id the runtime would resolve. LM Studio lists a loaded model under its
+ * instance id and keeps the model key only in the state map, and the request
+ * path accepts either, so both count as advertised.
+ */
+function advertisedModelIds(inventory: Pick<WireModelInventory, "models" | "modelStates">): string[] {
+	const ids = [...inventory.models];
+	for (const id of Object.keys(inventory.modelStates ?? {})) if (!ids.includes(id)) ids.push(id);
+	return ids;
+}
+
+function residentModelIds(modelStates: WireModelInventory["modelStates"]): string[] {
+	return Object.entries(modelStates ?? {})
+		.filter(([, status]) => status.state === "loaded" || status.state === "loading")
+		.map(([id]) => id);
+}
+
+function liveInventoryFor(
+	target: Pick<TargetDescriptor, "id" | "url">,
+	inventory: WireModelInventory,
+): LiveModelInventory {
+	return {
+		targetId: target.id,
+		url: target.url,
+		models: advertisedModelIds(inventory),
+		resident: residentModelIds(inventory.modelStates),
+	};
+}
+
 async function resolveSupportedWireModels(
 	runtime: RuntimeDescriptor,
 	target: TargetDescriptor,
 	existing?: TargetDescriptor,
 	authToken?: string,
-): Promise<string[]> {
+): Promise<WireModelInventory> {
 	const known = listKnownModelsForRuntime(runtime.id);
-	if (known.length > 0) return known;
-	const discovered = runtime.kind === "http" ? await runtimeProbeModels(runtime, target, authToken) : [];
-	if (discovered.length > 0) return discovered;
-	return existing?.wireModels ? [...existing.wireModels] : [];
+	if (known.length > 0) return { models: known, source: "catalog" };
+	if (runtime.kind === "http") {
+		// The full probe carries load state alongside the ids; a runtime that
+		// lists models only through probeModels still gets its ids checked.
+		const probe = await runtimeProbe(runtime, target, authToken);
+		if (probe?.ok && probe.models && probe.models.length > 0) {
+			return { models: [...probe.models], source: "probe", modelStates: probe.modelStates };
+		}
+		const discovered = await runtimeProbeModels(runtime, target, authToken);
+		if (discovered.length > 0) return { models: discovered, source: "probe" };
+	}
+	if (existing?.wireModels && existing.wireModels.length > 0)
+		return { models: [...existing.wireModels], source: "existing" };
+	return { models: [], source: "none" };
 }
 
 function resolveModelChoice(
@@ -810,7 +889,8 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 		...(args.reasoning !== undefined ? { reasoning: args.reasoning } : {}),
 		...(existing?.lmstudio ? { lmstudio: existing.lmstudio } : {}),
 	});
-	const wireModels = await resolveSupportedWireModels(runtime, seed, existing, args.apiKey);
+	const inventory = await resolveSupportedWireModels(runtime, seed, existing, args.apiKey);
+	const wireModels = inventory.models;
 	const model =
 		args.model ??
 		existing?.defaultModel ??
@@ -820,7 +900,7 @@ async function runNonInteractive(runtime: RuntimeDescriptor, args: ParsedArgs):
 		refuseCatalogSeededModel(runtime, support);
 		return 2;
 	}
-	if (!validateResolvedModel(runtime.id, model, args.force)) return 2;
+	if (!validateResolvedModel(runtime, seed, model, args.force, inventory)) return 2;
 	if (!validateContextWindowOverride(runtime, model, args.contextWindow, args.force)) return 2;
 	const descriptor = buildDescriptor(runtime, args.id, {
 		...(url !== undefined ? { url } : {}),
@@ -1192,7 +1272,10 @@ async function runInteractive(
 	}
 
 	let model: string | undefined = defaults.model;
-	let wireModels: string[] = existing?.wireModels ? [...existing.wireModels] : [];
+	let inventory: WireModelInventory =
+		existing?.wireModels && existing.wireModels.length > 0
+			? { models: [...existing.wireModels], source: "existing" }
+			: { models: [], source: "none" };
 	const tentative = buildDescriptor(runtime, targetId, {
 		...(url !== undefined ? { url } : {}),
 		...(apiKeyEnv !== undefined ? { apiKeyEnv } : {}),
@@ -1211,8 +1294,9 @@ async function runInteractive(
 	});
 
 	if (runtime.kind === "http") {
-		wireModels = await resolveSupportedWireModels(runtime, tentative, existing ?? undefined);
+		inventory = await resolveSupportedWireModels(runtime, tentative, existing ?? undefined);
 	}
+	const wireModels = inventory.models;
 	// The wizard shows the whole list, so a catalog-ordered runtime does not need
 	// --model here the way the non-interactive path does. It does need to stop
 	// offering the alphabetically first id as though it were the recommended one.
@@ -1234,11 +1318,11 @@ async function runInteractive(
 				process.stdout.write("  a model is required: enter a number from the list or a model id.\n");
 				continue;
 			}
-			if (validateResolvedModel(runtime.id, model, defaults.force)) break;
+			if (validateResolvedModel(runtime, tentative, model, defaults.force, inventory)) break;
 		}
 	} else {
 		for (;;) {
-			if (model && validateResolvedModel(runtime.id, model, defaults.force)) break;
+			if (model && validateResolvedModel(runtime, tentative, model, defaults.force, inventory)) break;
 			const manual = await ask(rl, "Default model id (blank to leave empty)", model ?? "");
 			if (manual === null) return 0;
 			model = manual.length > 0 ? manual : undefined;

package/src/cli/doctor.ts

@@ -4,6 +4,7 @@ import {
 	runDoctor,
 	runDoctorFleetChecks,
 	runDoctorInteropChecks,
+	runDoctorModelChecks,
 	runDoctorRuntimeChecks,
 } from "../domains/lifecycle/doctor.js";
 import { printError } from "./shared.js";
@@ -35,6 +36,9 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	const untouched = !fix && isUninitializedHome();
 	const findings = runDoctor({ fix });
 	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.
+	const modelChecks = await runDoctorModelChecks();
 	// The interop and fleet sweeps read the state and config roots through the
 	// ensuring accessors, which create them, and there is no fleet or interop
 	// state to inspect before Clio has ever written anything. On a home Clio has
@@ -43,7 +47,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, ...interopChecks, ...fleetChecks];
+	const all = [...findings, ...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/evidence.ts

@@ -1,16 +1,18 @@
 import { InvalidIdError } from "../core/safe-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
-import type { CanonicalTrustStatus, EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
+import type { EvidenceOverview, EvidenceRunProvenance } from "../domains/evidence/index.js";
 import {
 	buildEvalEvidence,
 	buildEvidence,
 	EvidenceNotFoundError,
+	formatTrustAxes,
+	formatTrustSummary,
 	inspectEvidence,
 	listEvidenceOverviews,
 	loadEvidenceRunProvenance,
 	provenanceTranscriptLines,
 } from "../domains/evidence/index.js";
-import { printError, printOk } from "./shared.js";
+import { printError, printNote, printOk } from "./shared.js";
 
 const HELP = `clio-coder evidence build --run <runId>
 clio-coder evidence build --session <sessionId>
@@ -137,15 +139,19 @@ export async function runEvidenceCommand(args: ReadonlyArray<string>): Promise<n
 			// but the verdict line and exit code must not say ok over a receipt
 			// that failed integrity verification.
 			const integrityFailures = result.findings.filter((entry) => entry.tag === "receipt-integrity");
-			if (integrityFailures.length > 0) {
-				process.stdout.write(`wrote ${result.evidenceId} ${result.directory}\n`);
-				for (const failure of integrityFailures) {
-					printError(`${failure.runId !== null ? `run ${failure.runId}: ` : ""}${failure.message}`);
-				}
-				return 1;
+			// A retired seal is the expected state of every run that predates an
+			// integrity bump: the receipt is set aside unread, as a missing one
+			// is, so it is a note beside the verdict and leaves the exit code alone.
+			const retiredSeals = result.findings.filter((entry) => entry.tag === "receipt-retired");
+			if (integrityFailures.length > 0) process.stdout.write(`wrote ${result.evidenceId} ${result.directory}\n`);
+			else printOk(`wrote ${result.evidenceId} ${result.directory}`);
+			for (const entry of retiredSeals) {
+				printNote(`${entry.runId !== null ? `run ${entry.runId}: ` : ""}${entry.message}`);
 			}
-			printOk(`wrote ${result.evidenceId} ${result.directory}`);
-			return 0;
+			for (const failure of integrityFailures) {
+				printError(`${failure.runId !== null ? `run ${failure.runId}: ` : ""}${failure.message}`);
+			}
+			return integrityFailures.length > 0 ? 1 : 0;
 		}
 		if (parsed.command === "inspect") {
 			const evidenceId = parsed.evidenceId;
@@ -191,30 +197,29 @@ function renderEvidence(
 	if (trustStatus.projection === "historical_format") {
 		process.stdout.write("trust status: unavailable (historical bundle without canonical projection)\n");
 	} else {
+		// The compact projection answers the trust questions; the canonical axis
+		// line beneath it is the drill-down, in the same form the dispatch tool
+		// and monitor print.
 		for (const run of trustStatus.runs) {
-			process.stdout.write(`trust ${run.runId}: ${formatTrustStatus(run.status)}\n`);
+			process.stdout.write(`trust ${run.runId}: ${formatTrustSummary(run.status)}\n`);
+			process.stdout.write(`  ${formatTrustAxes(run.status)}\n`);
 		}
 	}
-	// Provenance is printed only for runs whose receipts carry it, so a legacy
-	// bundle prints nothing new here.
+	// Provenance is the detail behind the projection, never a second reading
+	// of it: each run's block is gated on that run's canonical status, so a
+	// receipt the projection withheld (a broken or retired seal) prints no
+	// autonomy value here, and a run whose block would be empty prints no
+	// header. A historical bundle has no projection and admits no axis detail.
+	const statusByRun = new Map(trustStatus.runs.map((entry) => [entry.runId, entry.status]));
 	for (const { runId, view } of provenance) {
+		const lines = provenanceTranscriptLines(view, statusByRun.get(runId));
+		if (lines.length === 0) continue;
 		process.stdout.write(`provenance ${runId}:\n`);
-		for (const line of provenanceTranscriptLines(view)) process.stdout.write(`  ${line}\n`);
+		for (const line of lines) process.stdout.write(`  ${line}\n`);
 	}
 	process.stdout.write(`files: ${formatList(overview.files)}\n`);
 }
 
-function formatTrustStatus(status: CanonicalTrustStatus): string {
-	return [
-		`artifactIntegrity=${status.artifactIntegrity.state}`,
-		`validationGrounding=${status.validationGrounding.state}`,
-		`independentReview=${status.independentReview.state}`,
-		`contextProvenance=${status.contextProvenance.state}`,
-		`autonomyEnforcement=${status.autonomyEnforcement.state}`,
-		`completionEvidence=${status.completionEvidence.state}`,
-	].join(" ");
-}
-
 function renderEvidenceList(overviews: ReadonlyArray<EvidenceOverview>): void {
 	process.stdout.write(`${overviews.length} evidence artifacts\n`);
 	if (overviews.length === 0) return;

package/src/cli/fleet-commands.ts

@@ -0,0 +1,37 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { discoverDeclaredProjectCommands } from "../tools/verify/authoring.js";
+
+function quoted(value: string): string {
+	return JSON.stringify(value);
+}
+
+export function runFleetCommands(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "init") {
+		process.stderr.write("clio-coder fleet: commands: usage: clio-coder fleet commands init\n");
+		return 2;
+	}
+	const destination = join(process.cwd(), ".clio-coder", "fleets", "commands.yaml");
+	if (existsSync(destination)) {
+		process.stderr.write(`clio-coder fleet: commands init: destination already exists: ${destination}\n`);
+		return 2;
+	}
+	const entries = discoverDeclaredProjectCommands(process.cwd());
+	const lines = [
+		"# Draft fleet command registry.",
+		"# Every entry was discovered from a project declaration. Uncommenting an entry confirms its exact invocation.",
+		"# version: 1",
+		"# commands:",
+	];
+	for (const entry of entries) {
+		lines.push(
+			`#   ${entry.id}:`,
+			`#     argv: [${entry.command.map(quoted).join(", ")}]`,
+			`#     description: ${quoted(`Discovered from ${entry.provenance.path}: ${entry.provenance.detail}`)}`,
+		);
+	}
+	mkdirSync(dirname(destination), { recursive: true });
+	writeFileSync(destination, `${lines.join("\n")}\n`, { flag: "wx" });
+	process.stdout.write(`${destination}\n`);
+	return 0;
+}

package/src/cli/fleet-graph.ts

@@ -0,0 +1,102 @@
+import type { ExecutionPlanStep } from "../domains/dispatch/execution-plan.js";
+import { inspectFleet } from "./fleet-preflight.js";
+
+/**
+ * The contract-level kind of a compiled step. The execution plan knows only
+ * `agent` and `code`; a version 5 `gate` or `plan` step compiles to an agent
+ * step carrying `gate` or `plan` facts, and the graph names it as the author
+ * wrote it.
+ */
+function contractKind(step: ExecutionPlanStep): "agent" | "code" | "gate" | "plan" {
+	if (step.kind === "code") return "code";
+	if (step.gate !== undefined) return "gate";
+	if (step.plan !== undefined) return "plan";
+	return "agent";
+}
+
+function projectedStep(step: ExecutionPlanStep): Record<string, unknown> {
+	return {
+		id: step.id,
+		kind: contractKind(step),
+		...(step.kind === "agent" ? { agent: step.agentId } : { command: step.commandId }),
+		...(step.kind === "agent" && step.gate !== undefined
+			? { gate: { path: step.gate.path, command: step.gate.commandId } }
+			: {}),
+		...(step.kind === "agent" && step.plan !== undefined
+			? { plan: { roster: [...step.plan.roster], maxTasks: step.plan.maxTasks, proposals: step.plan.proposals } }
+			: {}),
+		...(step.kind === "agent" && step.target !== undefined ? { target: step.target } : {}),
+		...(step.kind === "agent" && step.profile !== undefined ? { profile: step.profile } : {}),
+		scope: step.scope,
+		writes: [...(step.writes ?? [])],
+		dependencies: [...step.dependencies],
+	};
+}
+
+export function runFleetGraph(args: ReadonlyArray<string>): number {
+	const json = args.includes("--json");
+	const name = args.find((arg) => !arg.startsWith("-"));
+	const unknown = args.find((arg, index) => (arg.startsWith("-") && arg !== "--json") || index > 1);
+	if (name === undefined || unknown !== undefined) {
+		process.stderr.write("clio-coder fleet: graph: usage: clio-coder fleet graph <name> [--json]\n");
+		return 2;
+	}
+	try {
+		const { plan } = inspectFleet(name);
+		const byId = new Map(plan.steps.map((step) => [step.id, step]));
+		const waves = plan.waves.map((ids, index) => ({
+			wave: index + 1,
+			steps: ids.flatMap((id) => {
+				const step = byId.get(id);
+				return step === undefined ? [] : [projectedStep(step)];
+			}),
+		}));
+		const loops = plan.loops.map((loop) => ({
+			id: loop.id,
+			check: loop.checkStepIds.map((id) => projectedStep(byId.get(id) as ExecutionPlanStep)),
+			repair: loop.repairStepIds.map((id) => projectedStep(byId.get(id) as ExecutionPlanStep)),
+		}));
+		if (json) {
+			process.stdout.write(`${JSON.stringify({ fleet: name, planHash: plan.hash, waves, loops }, null, 2)}\n`);
+			return 0;
+		}
+		for (const wave of waves) {
+			process.stdout.write(`wave ${wave.wave}\n`);
+			for (const step of wave.steps) {
+				const subject = step.kind === "code" ? `command=${step.command}` : `agent=${step.agent}`;
+				const gate = step.gate as { path: string; command: string } | undefined;
+				const plan = step.plan as { roster: string[]; maxTasks: number; proposals: boolean } | undefined;
+				const detail =
+					gate !== undefined
+						? ` gate=${gate.path} run=${gate.command}`
+						: plan !== undefined
+							? ` roster=${JSON.stringify(plan.roster)} maxTasks=${plan.maxTasks}${plan.proposals ? " proposals" : ""}`
+							: "";
+				const route =
+					step.target !== undefined
+						? ` target=${step.target}`
+						: step.profile !== undefined
+							? ` profile=${step.profile}`
+							: "";
+				process.stdout.write(
+					`  ${step.id} kind=${step.kind} ${subject}${route} scope=${step.scope} writes=${JSON.stringify(step.writes)}${detail}\n`,
+				);
+			}
+		}
+		for (const loop of loops) {
+			process.stdout.write(`loop ${loop.id}\n`);
+			for (const step of loop.check)
+				process.stdout.write(
+					`  check ${step.id} kind=${step.kind} scope=${step.scope} writes=${JSON.stringify(step.writes)}\n`,
+				);
+			for (const step of loop.repair)
+				process.stdout.write(
+					`  repair ${step.id} kind=${step.kind} scope=${step.scope} writes=${JSON.stringify(step.writes)}\n`,
+				);
+		}
+		return 0;
+	} catch (error) {
+		process.stderr.write(`clio-coder fleet: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+}

package/src/cli/fleet-new.ts

@@ -0,0 +1,36 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolvePackageRoot } from "../core/package-root.js";
+
+const BUILTINS = ["build-review", "build-test", "sdlc"] as const;
+const SAFE_STEM = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+
+function usage(message: string): number {
+	process.stderr.write(`clio-coder fleet: new: ${message}\n`);
+	return 2;
+}
+
+export function runFleetNew(args: ReadonlyArray<string>): number {
+	const name = args[0];
+	const fromIndex = args.indexOf("--from");
+	const builtin = fromIndex === -1 ? undefined : args[fromIndex + 1];
+	const known = BUILTINS.join(", ");
+	if (name === undefined) return usage("usage: clio-coder fleet new <name> --from <builtin>");
+	if (!SAFE_STEM.test(name)) return usage(`'${name}' is not a safe file stem`);
+	if (fromIndex === -1 || builtin === undefined) return usage("--from <builtin> is required");
+	const expected = new Set([name, "--from", builtin]);
+	const unknown = args.find((arg) => !expected.has(arg));
+	if (unknown !== undefined) return usage(`unknown argument: ${unknown}`);
+	if (!(BUILTINS as ReadonlyArray<string>).includes(builtin)) {
+		return usage(`unknown builtin '${builtin}'. Known builtins: ${known}`);
+	}
+	const destination = join(process.cwd(), ".clio-coder", "fleets", `${name}.md`);
+	if (existsSync(destination)) return usage(`destination already exists: ${destination}`);
+	const source = join(resolvePackageRoot(), "src", "domains", "agents", "fleets", `${builtin}.md`);
+	mkdirSync(dirname(destination), { recursive: true });
+	const sourceText = readFileSync(source, "utf8");
+	const renamed = sourceText.replace(/^name:\s*[^\n]+$/mu, `name: ${name}`);
+	writeFileSync(destination, renamed, { flag: "wx" });
+	process.stdout.write(`${destination}\n`);
+	return 0;
+}

package/src/cli/fleet-preflight.ts

@@ -0,0 +1,111 @@
+import { readSettings } from "../core/config.js";
+import {
+	type FleetCommandRegistry,
+	type FleetContract,
+	loadFleetCommands,
+	loadFleetContract,
+	renderFleetPrompt,
+} from "../domains/agents/index.js";
+import { discoverAgentRecipes } from "../domains/agents/registry.js";
+import { type AgentSpec, normalizeAgentSpec } from "../domains/agents/spec.js";
+import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
+import { requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
+import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
+
+export interface FleetPreflightResult {
+	contract: FleetContract;
+	commands: FleetCommandRegistry | null;
+	plan: ExecutionPlan;
+	checks: ReadonlyArray<{ check: "parse" | "graph" | "commands" | "agents" | "plan"; summary: string }>;
+}
+
+function discoverSpecs(cwd: string): AgentSpec[] {
+	return discoverAgentRecipes(cwd).map(normalizeAgentSpec);
+}
+
+export function inspectFleet(name: string, vars?: Readonly<Record<string, string>>): FleetPreflightResult {
+	const cwd = process.cwd();
+	const contract = loadFleetContract(cwd, name);
+	const commands = loadFleetCommands(cwd);
+	const prompt = vars === undefined ? contract.body : renderFleetPrompt(contract.body, vars);
+	const specs = discoverSpecs(cwd);
+	const byId = new Map(specs.map((spec) => [spec.id, spec]));
+	const resolved = new Set<string>();
+	const settings = readSettings();
+	const targetIds = new Set(settings.targets.map((target) => target.id));
+	const profileIds = new Set(Object.keys(settings.workers?.profiles ?? {}));
+	for (const step of contract.steps) {
+		const positions =
+			step.kind === "loop"
+				? [
+						...(step.check.kind === "agent" ? [{ id: `${step.id}.check`, route: step.check }] : []),
+						{ id: `${step.id}.repair`, route: step.repair },
+					]
+				: step.kind === "agent" || step.kind === "gate" || step.kind === "plan"
+					? [{ id: step.id, route: step }]
+					: [];
+		for (const position of positions) {
+			if (position.route.target !== undefined && !targetIds.has(position.route.target)) {
+				throw new Error(`unknown target '${position.route.target}' at step '${position.id}'`);
+			}
+			if (position.route.profile !== undefined && !profileIds.has(position.route.profile)) {
+				throw new Error(`unknown profile '${position.route.profile}' at step '${position.id}'`);
+			}
+		}
+	}
+	const plan = compileFleetExecutionPlan({
+		contract,
+		task: prompt,
+		resolveAgent(context) {
+			const spec = byId.get(context.agentId);
+			if (spec === undefined) {
+				throw new Error(
+					`unknown agent '${context.agentId}' (step '${context.stepId}' must name a recipe from 'clio-coder agents')`,
+				);
+			}
+			if (spec.capabilityClass === "orchestration" || spec.capabilityClass === "internal") {
+				throw new Error(`fleet step '${context.stepId}' has no automatable agent authority`);
+			}
+			resolved.add(spec.id);
+			const role = requestExecutionRole({
+				agentId: spec.id,
+				resolveFacts: (id) => {
+					const found = byId.get(id);
+					return found === undefined
+						? null
+						: {
+								category: found.category,
+								capabilityClass: found.capabilityClass,
+								resultContractKind: found.resultContract.kind,
+							};
+				},
+				...(context.gateRole === undefined ? {} : { gateRole: context.gateRole }),
+			});
+			return {
+				requestedAuthority: spec.capabilityClass,
+				approvedAuthority: spec.capabilityClass,
+				expectedResultContract:
+					context.planRole === true
+						? "delegation-plan"
+						: context.gateAuthorRole === true
+							? "artifact-report"
+							: context.gateRole === "reviewer"
+								? "verifier-report"
+								: spec.resultContract.kind,
+				executionRole: withAttemptRole(role, context.attempt),
+			};
+		},
+	});
+	return {
+		contract,
+		commands,
+		plan,
+		checks: [
+			{ check: "parse", summary: `parsed contract version ${contract.version}` },
+			{ check: "graph", summary: `validated ${contract.steps.length} declared steps` },
+			{ check: "commands", summary: `validated ${plan.steps.filter((step) => step.kind === "code").length} code steps` },
+			{ check: "agents", summary: `resolved ${resolved.size} agents` },
+			{ check: "plan", summary: `compiled ${plan.steps.length} plan steps with hash ${plan.hash}` },
+		],
+	};
+}

package/src/cli/fleet-validate.ts

@@ -0,0 +1,30 @@
+import { FLEET_COMMANDS_REMEDY, FleetCommandRegistryMissingError } from "../domains/agents/index.js";
+import { preflightWriteBoundaries } from "../domains/dispatch/write-boundary-enforcer.js";
+import { inspectFleet } from "./fleet-preflight.js";
+
+export function runFleetValidate(args: ReadonlyArray<string>): number {
+	const json = args.includes("--json");
+	const unknown = args.find((arg, index) => (arg.startsWith("-") && arg !== "--json") || index > 1);
+	const name = args.find((arg) => !arg.startsWith("-"));
+	if (name === undefined || unknown !== undefined) {
+		process.stderr.write("clio-coder fleet: validate: usage: clio-coder fleet validate <name> [--json]\n");
+		return 2;
+	}
+	try {
+		const result = inspectFleet(name);
+		preflightWriteBoundaries(result.plan, process.cwd());
+		if (json)
+			process.stdout.write(
+				`${JSON.stringify({ valid: true, fleet: name, checks: result.checks, planHash: result.plan.hash }, null, 2)}\n`,
+			);
+		else for (const check of result.checks) process.stdout.write(`${check.check}: ${check.summary}\n`);
+		return 0;
+	} catch (error) {
+		const raw = error instanceof Error ? error.message : String(error);
+		const message = raw.startsWith("unknown agent '") ? `preflight failed: ${raw}` : raw;
+		const diagnostics = [message, ...(error instanceof FleetCommandRegistryMissingError ? [FLEET_COMMANDS_REMEDY] : [])];
+		if (json) process.stdout.write(`${JSON.stringify({ valid: false, fleet: name, diagnostics }, null, 2)}\n`);
+		else process.stderr.write(`clio-coder fleet: ${diagnostics.join("\n  ")}\n`);
+		return 1;
+	}
+}