@iowarp/clio-coder 0.3.7 → 0.3.8

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.7).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.8).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.7",
+	"version": "0.3.8",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -107,7 +107,6 @@
 	},
 	"overrides": {
 		"@anthropic-ai/sdk": "0.105.0",
-		"ip-address": "10.2.0",
 		"esbuild": "0.28.1"
 	},
 	"devDependencies": {

package/src/cli/argv.ts

@@ -15,6 +15,11 @@ export function printError(message: string, detail?: string): void {
 	if (detail) process.stderr.write(`  ${detail}\n`);
 }
 
+/** An expected condition worth a line on stderr that is neither an error nor a success. */
+export function printNote(message: string): void {
+	process.stderr.write(`${chalk.yellow("note:")} ${message}\n`);
+}
+
 export function printOk(message: string): void {
 	process.stdout.write(`${chalk.green("ok:")} ${message}\n`);
 }

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-preflight.ts

@@ -1,7 +1,4 @@
-import { join } from "node:path";
 import { readSettings } from "../core/config.js";
-import { resolvePackageRoot } from "../core/package-root.js";
-import { clioConfigDir } from "../core/xdg.js";
 import {
 	type FleetCommandRegistry,
 	type FleetContract,
@@ -9,7 +6,7 @@ import {
 	loadFleetContract,
 	renderFleetPrompt,
 } from "../domains/agents/index.js";
-import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "../domains/agents/registry.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";
@@ -23,14 +20,7 @@ export interface FleetPreflightResult {
 }
 
 function discoverSpecs(cwd: string): AgentSpec[] {
-	const diagnostics: AgentRecipeDiagnostic[] = [];
-	const builtin = loadRecipesFromDir(
-		{ dir: join(resolvePackageRoot(), "src", "domains", "agents", "builtins"), source: "builtin" },
-		diagnostics,
-	);
-	const user = loadRecipesFromDir({ dir: join(clioConfigDir(), "agents"), source: "user" }, diagnostics);
-	const project = loadRecipesFromDir({ dir: join(cwd, ".clio-coder", "agents"), source: "project" }, diagnostics);
-	return mergeRecipes(builtin, user, project).map(normalizeAgentSpec);
+	return discoverAgentRecipes(cwd).map(normalizeAgentSpec);
 }
 
 export function inspectFleet(name: string, vars?: Readonly<Record<string, string>>): FleetPreflightResult {

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/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";
@@ -737,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: 19;
+	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-v19/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 !== 19 ||
+		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-v19/sha256:${receipt.digest}`;
+	return `Clio-Evidence: receipt-v20/sha256:${receipt.digest}`;
 }
 
 /**