@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/cli/targets.ts

@@ -5,6 +5,8 @@ import {
 	readSettings,
 	removeFleetProfileFromSettings,
 	setFleetProfileInSettings,
+	type TargetSelectionRole,
+	type UseTargetOptions,
 	updateSettings,
 	useTargetInSettings,
 } from "../core/config.js";
@@ -24,6 +26,7 @@ import { registerBuiltinRuntimes } from "../domains/providers/runtimes/builtins.
 import type { CapabilityFlags } from "../domains/providers/types/capability-flags.js";
 import type { RuntimeTier } from "../domains/providers/types/runtime-descriptor.js";
 import { runConfigureCommand, runTargetRemove, runTargetRename } from "./configure.js";
+import { resolveSupportedWireModels } from "./configure-target.js";
 import { printError, printOk } from "./shared.js";
 import { column, terminalColumns, truncate, wrapPlain } from "./text-layout.js";
 
@@ -259,7 +262,7 @@ function parseUseArgs(args: ReadonlyArray<string>): UseArgs | null {
 	return parsed;
 }
 
-function runUse(args: ReadonlyArray<string>): number {
+async function runUse(args: ReadonlyArray<string>): Promise<number> {
 	if (wantsHelp(args)) return printUsage(USE_USAGE);
 	let parsed: UseArgs | null;
 	try {
@@ -281,42 +284,91 @@ function runUse(args: ReadonlyArray<string>): number {
 	}
 	const registry = getRuntimeRegistry();
 	if (registry.list().length === 0) registerBuiltinRuntimes(registry);
-	const runtime = registry.get(target.runtime);
-	if (!runtime) {
-		printError(
-			`cannot use target '${target.id}' as orchestrator target because runtime '${target.runtime}' is not registered`,
-		);
+	const options: UseTargetOptions = {
+		...(parsed.model !== undefined ? { model: parsed.model } : {}),
+		...(parsed.orchestratorModel !== undefined ? { orchestratorModel: parsed.orchestratorModel } : {}),
+		...(parsed.workerModel !== undefined ? { workerModel: parsed.workerModel } : {}),
+		...(parsed.workerTarget !== undefined ? { workerTargetId: parsed.workerTarget } : {}),
+		...(parsed.backgroundModel !== undefined ? { backgroundModel: parsed.backgroundModel } : {}),
+	};
+	const candidate = structuredClone(settings);
+	const selection = useTargetInSettings(candidate, target.id, options);
+	if (!selection) {
+		printError(`no target with id ${parsed.workerTarget}`);
 		return 1;
 	}
-	if (!isOrchestratorEligibleRuntime(runtime)) {
-		printError(
-			`cannot use target '${target.id}' as orchestrator target because runtime '${runtime.id}' is not an HTTP/native runtime`,
-		);
+	const labels: Record<TargetSelectionRole, string> = {
+		chat: "chat",
+		fleet: "fleet dispatch",
+		memory: "background memory",
+	};
+	const routes = { chat: candidate.chat, fleet: candidate.fleet.default, memory: candidate.context.memory };
+	const inventories = new Map<string, Awaited<ReturnType<typeof resolveSupportedWireModels>>>();
+	const checkedTargets = new Map<string, string>();
+	for (const role of selection.roles) {
+		const route = routes[role];
+		const selectedTarget = candidate.targets.find((entry) => entry.id === route.target);
+		if (!selectedTarget) throw new Error("selected target disappeared");
+		const runtime = registry.get(selectedTarget.runtime);
+		if (!runtime || !(role === "fleet" ? isDispatchEligibleRuntime(runtime) : isOrchestratorEligibleRuntime(runtime))) {
+			printError(
+				`cannot use target '${selectedTarget.id}' for ${labels[role]}: runtime '${selectedTarget.runtime}' is not eligible`,
+			);
+			return 1;
+		}
+		checkedTargets.set(selectedTarget.id, JSON.stringify(selectedTarget));
+		if (route.model === null) continue;
+		let inventory = inventories.get(selectedTarget.id);
+		if (!inventory) {
+			inventory = await resolveSupportedWireModels(runtime, selectedTarget, selectedTarget);
+			inventories.set(selectedTarget.id, inventory);
+		}
+		if (inventory.models.length > 0 && !inventory.models.includes(route.model)) {
+			printError(
+				`target '${selectedTarget.id}' does not list model '${route.model}' for ${labels[role]} (${inventory.source} inventory). Use an exact listed model id: ${inventory.models.slice(0, 10).join(", ")}`,
+			);
+			return 1;
+		}
+		if (inventory.models.length === 0) {
+			// Keep offline selection possible, but never imply that an unknown id was verified.
+			process.stderr.write(
+				`warning: could not verify model '${route.model}' for ${labels[role]}: target '${selectedTarget.id}' returned no model list; saving the id as written\n`,
+			);
+		} else if (inventory.source === "cache" || inventory.source === "legacy") {
+			process.stderr.write(
+				`warning: using ${inventory.source} model inventory for target '${selectedTarget.id}'; live availability was not verified\n`,
+			);
+		}
+	}
+	// Re-read under the settings lock. A changed endpoint/default invalidates the
+	// checked inventory; unrelated concurrent role edits are preserved by the scoped mutation.
+	let changedRoles: TargetSelectionRole[] = [];
+	try {
+		updateSettings((fresh) => {
+			for (const [id, descriptor] of checkedTargets) {
+				if (JSON.stringify(fresh.targets.find((entry) => entry.id === id)) !== descriptor) {
+					throw new Error(`target '${id}' changed while checking models; retry targets use`);
+				}
+			}
+			const applied = useTargetInSettings(fresh, target.id, options);
+			if (!applied) throw new Error("target changed while checking models; retry targets use");
+			changedRoles = applied.changedRoles;
+		});
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
 		return 1;
 	}
-	let workerTarget = target;
-	if (parsed.workerTarget !== undefined && parsed.workerTarget !== target.id) {
-		const resolved = resolveDispatchProfileTarget(settings, parsed.workerTarget, "fleet worker target");
-		if ("exitCode" in resolved) return resolved.exitCode;
-		workerTarget = resolved.target;
+	const changedByTarget = new Map<string, string[]>();
+	for (const role of changedRoles) {
+		const id = routes[role].target as string;
+		const names = changedByTarget.get(id) ?? [];
+		names.push(labels[role]);
+		changedByTarget.set(id, names);
 	}
-	const backgroundModel = parsed.backgroundModel;
-	// Locked read-modify-write so a concurrent session's field-level
-	// write-through (Shift+Tab, Alt+L, …) cannot be lost between our read
-	// above and this save.
-	updateSettings((fresh) => {
-		useTargetInSettings(fresh, target.id, {
-			...(parsed.model !== undefined ? { model: parsed.model } : {}),
-			...(parsed.orchestratorModel !== undefined ? { orchestratorModel: parsed.orchestratorModel } : {}),
-			...(parsed.workerModel !== undefined ? { workerModel: parsed.workerModel } : {}),
-			workerTargetId: workerTarget.id,
-			...(backgroundModel !== undefined ? { backgroundModel } : {}),
-		});
-	});
-	const dispatchWhere = workerTarget === target ? "" : ` and ${workerTarget.id} for fleet dispatch`;
-	const chatWhere = workerTarget === target ? "for chat and fleet dispatch" : "for chat";
 	printOk(
-		`using target ${target.id} ${chatWhere}${dispatchWhere}${backgroundModel === undefined ? "" : ", and background memory"}`,
+		changedRoles.length === 0
+			? "no role settings changed"
+			: `using ${[...changedByTarget].map(([id, names]) => `target ${id} for ${names.join(" and ")}`).join("; ")}`,
 	);
 	return 0;
 }
@@ -1003,7 +1055,7 @@ function formatUrl(status: TargetStatus): string {
 
 function formatAuth(providers: ProvidersContract, status: TargetStatus): string {
 	if (!status.runtime) return "-";
-	if (status.runtime.externalAgentLoop !== undefined) return "operator session";
+	if (status.runtime.externalAgentLoop !== undefined && status.runtime.auth !== "claude-cli") return "operator session";
 	if (status.runtime.auth !== "api-key" && status.runtime.auth !== "oauth") return status.runtime.auth;
 	const auth = providers.auth.statusForTarget(status.target, status.runtime);
 	if (!auth.available) return "disconnected";

package/src/cli/tasks.ts

@@ -0,0 +1,93 @@
+import { normalizeIntentExpectedOutputs, normalizeIntentVerification } from "../domains/dispatch/intent.js";
+import type { UserTaskAcceptance } from "../domains/user-tasks/acceptance.js";
+import { formatUserTaskHandoff } from "../domains/user-tasks/handoff.js";
+import { createUserTasksStore } from "../domains/user-tasks/store.js";
+import { packageDeclaredCheck } from "../tools/verify/catalog.js";
+import { discoverDeclaredChecksAtRoot, discoverDeclaredProjectEntriesAtRoot } from "../tools/verify/scripts.js";
+import { printError } from "./argv.js";
+
+/** Operator flags use the same bounds and normalization as dispatch intent. */
+export function acceptanceFromTaskFlags(
+	cwd: string,
+	expectedOutputs: string[],
+	verify: string[],
+): UserTaskAcceptance | undefined {
+	if (expectedOutputs.length === 0 && verify.length === 0) return undefined;
+	const discovery = discoverDeclaredChecksAtRoot(cwd, undefined);
+	if (!discovery.ok) throw new Error(discovery.reason);
+	const checks = new Map(
+		discovery.sources.flatMap((source) => source.checks.map((check) => [check.id, check] as const)),
+	);
+	for (const entry of discoverDeclaredProjectEntriesAtRoot(cwd)) {
+		if (entry.kind === "package-script" && !checks.has(entry.id))
+			checks.set(entry.id, packageDeclaredCheck(entry.id, entry.path, ".", []));
+	}
+	const verification = verify.map((value) => {
+		const suffix = checks.has(value) ? null : /^(.*):([0-9]+)$/.exec(value);
+		const check = suffix?.[1] ?? value;
+		if (!checks.has(check))
+			throw new Error(
+				`Unknown verification check '${check}'. Known ids: ${[...checks.keys()].sort().join(", ") || "(none)"}`,
+			);
+		return { check, ...(suffix ? { timeout_ms: Number(suffix[2]) } : {}) };
+	});
+	const outputs = normalizeIntentExpectedOutputs(expectedOutputs);
+	if (!Array.isArray(outputs)) throw new Error(outputs.ok ? "invalid expected outputs" : outputs.message);
+	const normalized = normalizeIntentVerification(verification, checks);
+	if (!Array.isArray(normalized)) throw new Error(normalized.ok ? "invalid verification" : normalized.message);
+	return { expectedOutputs: outputs, verification: normalized };
+}
+
+const HELP = `Usage:
+  clio-coder tasks [list]
+  clio-coder tasks add [--expect <path>] [--verify <checkId>[:timeoutMs]] <text>
+  clio-coder tasks hand|done|drop <uN>
+
+--expect and --verify are repeatable. Check ids must be declared in package.json or .clio-coder/verifiers.yaml.`;
+
+export function runTasksCommand(args: string[]): number {
+	try {
+		if (args.includes("--help") || args.includes("-h")) {
+			console.log(HELP);
+			return 0;
+		}
+		const store = createUserTasksStore({ cwd: process.cwd() });
+		const [action = "list", ...rest] = args;
+		if (action === "add") {
+			const expected: string[] = [],
+				verify: string[] = [],
+				title: string[] = [];
+			for (let index = 0; index < rest.length; index++) {
+				const token = rest[index] ?? "";
+				if (token === "--") {
+					title.push(...rest.slice(index + 1));
+					break;
+				}
+				if (token === "--expect" || token === "--verify") {
+					const value = rest[++index];
+					if (!value || value.startsWith("--")) throw new Error(`${token} requires a value`);
+					(token === "--expect" ? expected : verify).push(value);
+				} else if (token.startsWith("--")) throw new Error(`Unknown flag ${token}`);
+				else title.push(token);
+			}
+			const task = store.add(title.join(" "), undefined, acceptanceFromTaskFlags(process.cwd(), expected, verify));
+			console.log(`logged operator task ${task.id}: ${task.title}`);
+		} else if (action === "list" && rest.length === 0) {
+			console.log(JSON.stringify(store.snapshot(), null, 2));
+		} else if ((action === "hand" || action === "done" || action === "drop") && rest.length === 1) {
+			const task = store[action](rest[0] ?? "");
+			console.log(JSON.stringify(task, null, 2));
+			if (action === "hand") {
+				console.error(
+					"CLI hand records the inbox state only; it does not start a session or submit the interactive /tasks hand turn. " +
+						"Pass this pickup prompt to clio-coder run in the same project:\n" +
+						formatUserTaskHandoff(task),
+				);
+			}
+		} else throw new Error(HELP);
+		return 0;
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli/upgrade.ts

@@ -21,11 +21,12 @@ Flags:
   --dry-run             print planned actions without changing anything
   --channel=<chan>      npm dist-tag to install (latest|beta|dev). npm installs only.
   --skip-migrations     skip migrations after the install step
+  --post-install        apply local checks after a package-manager update; skip reinstall
   --json                emit machine-readable JSON output
   --help, -h            show this message
 `;
 
-const SOURCE_UPGRADE_STEPS = ["git pull", "npm run install:local", "hash -r"] as const;
+const SOURCE_UPGRADE_STEPS = ["git pull", "pnpm run install:local", "hash -r"] as const;
 /** One wording for the source-update advice. Three paths print it; they used to disagree. */
 const SOURCE_UPGRADE_LEAD = "To update the checkout itself, run:";
 
@@ -85,15 +86,20 @@ function parseUpgradeArgs(argv: ReadonlyArray<string>): UpgradeOptions {
  * the installed version is the newest one.
  */
 type RegistryLookup =
-	| { asked: false; reason: "source checkout" | "network checks are disabled" }
+	| { asked: false; reason: "source checkout" | "network checks are disabled" | "post-install checks" }
 	| { asked: true; version: string | null };
 
+function testSeam(name: string): string | undefined {
+	if (process.env.NODE_ENV !== "test") return undefined;
+	return process.env[name];
+}
+
 async function lookUpAvailableVersion(
 	channel: Channel,
 	method: "source" | "npm",
 	noNetwork: boolean,
 ): Promise<RegistryLookup> {
-	const seam = process.env.CLIO_CODER_TEST_UPGRADE_AVAILABLE;
+	const seam = testSeam("CLIO_CODER_TEST_UPGRADE_AVAILABLE");
 	// `unreachable` stands in for a registry that answered nothing, which is the
 	// only way to reach that branch without a network in the test.
 	if (seam) return { asked: true, version: seam === "unreachable" ? null : seam };
@@ -143,14 +149,14 @@ async function runChild(command: string, args: ReadonlyArray<string>, label: str
 }
 
 async function runNpmInstall(channel: Channel): Promise<void> {
-	if (process.env.CLIO_CODER_TEST_UPGRADE_FAIL === "npm") {
+	if (testSeam("CLIO_CODER_TEST_UPGRADE_FAIL") === "npm") {
 		throw new Error("npm ERR! 404 Not Found (mock failure)");
 	}
 	await runChild("npm", ["install", "-g", `@iowarp/clio-coder@${channel}`], "npm install");
 }
 
 async function runDoctorFixAfterInstall(): Promise<void> {
-	if (process.env.CLIO_CODER_TEST_UPGRADE_FAIL === "doctor") {
+	if (testSeam("CLIO_CODER_TEST_UPGRADE_FAIL") === "doctor") {
 		throw new Error("mock doctor fix failure");
 	}
 	await runChild("clio-coder", ["doctor", "--fix"], "clio-coder doctor --fix");
@@ -181,11 +187,13 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	const before = getVersionInfo().clio;
 	const stateDir = clioStateDir();
 	const method = detectInstallMethod();
-	const methodLabel = method === "source" ? "source checkout" : "npm global";
+	const methodLabel = method === "source" ? "source checkout" : opts.postInstall ? "package install" : "npm global";
 	presenter.setMethod(methodLabel);
 
-	const noNetwork = Boolean(process.env.CLIO_CODER_TEST_UPGRADE_NO_NETWORK);
-	const lookup = await lookUpAvailableVersion(opts.channel, method, noNetwork);
+	const noNetwork = Boolean(testSeam("CLIO_CODER_TEST_UPGRADE_NO_NETWORK"));
+	const lookup: RegistryLookup = opts.postInstall
+		? { asked: false, reason: "post-install checks" }
+		: await lookUpAvailableVersion(opts.channel, method, noNetwork);
 	const availableVersion = lookup.asked ? lookup.version : null;
 
 	presenter.step(`Installation method: ${methodLabel}`);
@@ -196,7 +204,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	if (availableVersion !== null) presenter.step(`Available version: ${availableVersion}`);
 	else if (!lookup.asked) presenter.step(`Available version: not checked (${lookup.reason})`);
 	else presenter.step("Available version: unknown (the registry could not be reached)");
-	if (method === "npm") presenter.step(`Channel: ${opts.channel}`);
+	if (method === "npm" && !opts.postInstall) presenter.step(`Channel: ${opts.channel}`);
 	presenter.step(`State dir: ${shortenPath(stateDir)}`);
 
 	const migrations = listMigrations();
@@ -231,7 +239,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 
 	if (opts.dryRun) {
 		if (method === "source") presenter.commandAdvice(SOURCE_UPGRADE_LEAD, SOURCE_UPGRADE_STEPS.join("\n"));
-		else presenter.note(`Would run: npm install -g @iowarp/clio-coder@${opts.channel}`);
+		else if (!opts.postInstall) presenter.note(`Would run: npm install -g @iowarp/clio-coder@${opts.channel}`);
 		if (opts.skipMigrations) presenter.note("Would skip migrations (--skip-migrations).");
 		else if (pendingMigrationIds.length === 0) presenter.note("No pending migrations.");
 		else {
@@ -285,7 +293,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	} else {
 		let result: Awaited<ReturnType<typeof runPending>>;
 		try {
-			if (process.env.CLIO_CODER_TEST_UPGRADE_FAIL === "migration") {
+			if (testSeam("CLIO_CODER_TEST_UPGRADE_FAIL") === "migration") {
 				throw new Error("mock migration failure in 2026-09-01-settings-v2");
 			}
 			result = await runPending(stateDir);

package/src/cli/usage.ts

@@ -8,6 +8,7 @@ import {
 } from "../core/response-model-id.js";
 import { clioDataDir, clioStateDir } from "../core/xdg.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
+import { summarizeEvidenceIndex } from "../domains/observability/accountability.js";
 import { summarizeFailedCompactionUsage } from "../domains/observability/compaction-usage.js";
 import { readEvidenceIndex } from "../domains/observability/evidence-index.js";
 import { type OutOfTurnUsageRow, readOutOfTurnUsageRows } from "../domains/observability/out-of-turn-usage.js";
@@ -353,11 +354,15 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	diagnostics.malformedAuditRows = auditRows.errors.length;
 	const auditInWindow = auditRows.rows.filter((row) => row.ts !== null && inWindow(row.ts, windowStart, now));
 	const auditToolCalls = auditInWindow.filter((row) => row.auditKind === "tool_call");
+	const permissions = summarizePermissionDecisions(
+		auditInWindow.filter((row) => row.auditKind === "permission").map((row) => row.row),
+	);
 	const auditBlocked = auditToolCalls.filter((row) => {
 		const decision = typeof row.row.decision === "string" ? row.row.decision : "";
 		return decision === "blocked" || decision === "denied";
 	});
 	const evidenceRows = readEvidenceIndex(stateDir).filter((row) => inWindow(row.generatedAt, windowStart, now));
+	const accountability = summarizeEvidenceIndex(evidenceRows);
 	let memoryRecords: MemoryRecord[] = [];
 	try {
 		memoryRecords = loadMemoryRecordsSync(clioDataDir());
@@ -559,7 +564,10 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 		else emit({ kind: "fact", fact: "session-store-missing", path: presence.sessionsPath });
 		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: "unverified-successes", value: accountability.unverifiedSuccesses });
+		emit({ kind: "fact", fact: "ungrounded-claims", value: accountability.ungroundedClaims });
 		emit({ kind: "fact", fact: "audit-tool-calls", value: auditToolCalls.length, blocked: auditBlocked.length });
+		emit({ kind: "fact", fact: "permission-approval", ...permissions });
 		if (usageMeasurable) {
 			// The origin split is emitted only when something out of turn was
 			// recorded, so a report over an archive with no `/btw`, `/handoff`, or
@@ -652,6 +660,9 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 	} else {
 		out(`  receipt store missing at ${presence.receiptsPath}`);
 	}
+	out(
+		`  permission decisions: ${permissions.requested} requested, ${permissions.granted} granted, ${permissions.denied} denied, ${permissions.expired} expired; approval rate ${permissions.approvalRate === null ? "n/a" : `${(permissions.approvalRate * 100).toFixed(1)}%`}`,
+	);
 	out(`  audited tool calls in window: ${auditToolCalls.length} (${auditBlocked.length} blocked/denied)`);
 	if (usageMeasurable) {
 		out(
@@ -806,6 +817,8 @@ export async function runUsageCommand(argv: ReadonlyArray<string>): Promise<numb
 			),
 		);
 	}
+	out(`  unverified successes: ${accountability.unverifiedSuccesses}`);
+	out(`  ungrounded claims: ${accountability.ungroundedClaims}`);
 	if (tagCounts.size > 0) {
 		out("");
 		out("  failure tags (from evidence index)");
@@ -1122,3 +1135,20 @@ function numberOr0(value: unknown): number {
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+
+/** Event-window approval rate. Resolutions can belong to requests outside the window. */
+export function summarizePermissionDecisions(rows: ReadonlyArray<Record<string, unknown>>): {
+	requested: number;
+	granted: number;
+	denied: number;
+	expired: number;
+	approvalRate: number | null;
+} {
+	const counts = { requested: 0, granted: 0, denied: 0, expired: 0 };
+	for (const row of rows) {
+		const status = row.status;
+		if (status === "requested" || status === "granted" || status === "denied" || status === "expired")
+			counts[status] += 1;
+	}
+	return { ...counts, approvalRate: counts.requested === 0 ? null : counts.granted / counts.requested };
+}

package/src/cli/verifiers.ts

@@ -6,8 +6,15 @@ import {
 	runVerifierAuthoringWorkflow,
 	type VerifierRevision,
 } from "../tools/verify/authoring.js";
-import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+import {
+	DECLARED_CHECK_KINDS,
+	type DeclaredCheckKind,
+	loadProjectVerifierCatalog,
+	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
+} from "../tools/verify/catalog.js";
 import { verifyTool } from "../tools/verify/index.js";
+import { normalizeNumericTolerance } from "../tools/verify/numeric.js";
+import { recordPerfBaseline } from "../tools/verify/scripts.js";
 import { printError, printOk } from "./argv.js";
 import { runVerifiersInspect } from "./verifiers-inspect.js";
 
@@ -23,11 +30,22 @@ Usage:
   clio-coder verifiers edit <id> [--description <text>] [--command <json-argv>] [fields] [--yes]
   clio-coder verifiers rename <old> <new> [--yes]
   clio-coder verifiers remove <id> [--yes]
+  clio-coder verifiers baseline <id>
 
 Fields:
   --cwd <path>            repository-relative working directory (default .)
   --timeout-ms <number>   bounded timeout in milliseconds (default 120000)
   --tags <a,b>            comma-separated catalog tags
+  --kind <kind>           command (default), numeric-compare, or perf-budget
+  --reference <path>      numeric-compare: repository-relative reference JSON of string -> number | number[]
+  --tolerance <json>      numeric-compare: {"relative"?,"absolute"?,"ulp"?}, at least one;
+                          perf-budget with --baseline: {"relative"} headroom over the baseline
+  --budget-ms <number>    perf-budget: wall-time bound in milliseconds
+  --budget-relative <r>   perf-budget with --budget-ms: fractional headroom over the bound
+  --baseline <path>       perf-budget: repository-relative baseline JSON written by 'verifiers baseline <id>'
+
+baseline runs a perf-budget check once and records its wall time at the check's
+baseline path; a failing or timed-out command records nothing.
 
 Discovery and every preview are read-only. Mutating commands write only with
 --yes after printing the exact argv, cwd, timeout, tags, source provenance, and
@@ -48,6 +66,12 @@ const VALUE_OPTIONS = new Set([
 	"--exclude",
 	"--rename",
 	"--dry-run",
+	"--kind",
+	"--reference",
+	"--tolerance",
+	"--budget-ms",
+	"--budget-relative",
+	"--baseline",
 ]);
 
 interface ParsedAuthoringArgs {
@@ -124,6 +148,93 @@ function tags(value: string | undefined): string[] {
 				.filter((tag) => tag.length > 0);
 }
 
+type KindFields = Pick<Extract<VerifierRevision, { kind: "add" }>["check"], "kind" | "numeric" | "perf">;
+
+function parseJsonObject(value: string, option: string): Record<string, unknown> | Error {
+	try {
+		const parsed = JSON.parse(value) as unknown;
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return new Error(`${option} must be a JSON object`);
+		}
+		return parsed as Record<string, unknown>;
+	} catch (error) {
+		return new Error(`${option} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * The kind and its parameters from the option set. Returns `{}` when no kind
+ * option was given so a plain command check keeps the version-1 shape, and an
+ * Error when the options disagree with the kind the way the catalog parser
+ * would refuse them, so the operator reads one message here instead of a
+ * rejected preview.
+ */
+function kindFieldsFromArgs(parsed: ParsedAuthoringArgs): KindFields | Error {
+	const kindValue = oneValue(parsed, "--kind") ?? "command";
+	if (!(DECLARED_CHECK_KINDS as ReadonlyArray<string>).includes(kindValue)) {
+		return new Error(`--kind must be one of ${DECLARED_CHECK_KINDS.join(", ")}`);
+	}
+	const kind = kindValue as DeclaredCheckKind;
+	const reference = oneValue(parsed, "--reference");
+	const toleranceValue = oneValue(parsed, "--tolerance");
+	const budgetMs = oneValue(parsed, "--budget-ms");
+	const budgetRelative = oneValue(parsed, "--budget-relative");
+	const baseline = oneValue(parsed, "--baseline");
+	if (kind === "command") {
+		const stray = [
+			["--reference", reference],
+			["--tolerance", toleranceValue],
+			["--budget-ms", budgetMs],
+			["--budget-relative", budgetRelative],
+			["--baseline", baseline],
+		].filter(([, value]) => value !== undefined);
+		if (stray.length > 0)
+			return new Error(`${stray.map(([name]) => name).join(", ")} require --kind numeric-compare or perf-budget`);
+		return {};
+	}
+	if (kind === "numeric-compare") {
+		if (budgetMs !== undefined || budgetRelative !== undefined || baseline !== undefined) {
+			return new Error("--budget-ms, --budget-relative, and --baseline belong to --kind perf-budget");
+		}
+		if (reference === undefined) return new Error("--reference is required for --kind numeric-compare");
+		if (toleranceValue === undefined) return new Error("--tolerance is required for --kind numeric-compare");
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const tolerance = normalizeNumericTolerance(toleranceJson);
+		if (tolerance instanceof Error) return new Error(`--tolerance ${tolerance.message}`);
+		return { kind, numeric: { reference, tolerance } };
+	}
+	if (reference !== undefined) return new Error("--reference belongs to --kind numeric-compare");
+	if ((budgetMs === undefined) === (baseline === undefined)) {
+		return new Error("--kind perf-budget requires exactly one of --budget-ms or --baseline");
+	}
+	if (budgetMs !== undefined) {
+		if (toleranceValue !== undefined) return new Error("use --budget-relative for headroom over --budget-ms");
+		const wallTimeMs = Number(budgetMs);
+		if (!Number.isFinite(wallTimeMs) || wallTimeMs <= 0) return new Error("--budget-ms must be a positive number");
+		const budget: NonNullable<KindFields["perf"]>["budget"] = { wallTimeMs };
+		if (budgetRelative !== undefined) {
+			const relative = Number(budgetRelative);
+			if (!Number.isFinite(relative) || relative < 0) return new Error("--budget-relative must be a non-negative number");
+			budget.tolerance = { relative };
+		}
+		return { kind, perf: { budget } };
+	}
+	if (budgetRelative !== undefined)
+		return new Error("--budget-relative belongs with --budget-ms; use --tolerance with --baseline");
+	const perf: NonNullable<KindFields["perf"]> = { baseline: baseline as string };
+	if (toleranceValue !== undefined) {
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const relative = toleranceJson.relative;
+		if (typeof relative !== "number" || !Number.isFinite(relative) || relative < 0) {
+			return new Error('--tolerance for a baseline must be {"relative": <non-negative number>}');
+		}
+		perf.tolerance = { relative };
+	}
+	return { kind, perf };
+}
+
 function requiredValue(parsed: ParsedAuthoringArgs, option: string): string | Error {
 	const value = oneValue(parsed, option);
 	return value === undefined || value.length === 0 ? new Error(`${option} is required`) : value;
@@ -151,6 +262,8 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	if (command instanceof Error) return command;
 	const timeoutMs = parseTimeout(oneValue(parsed, "--timeout-ms"));
 	if (timeoutMs instanceof Error) return timeoutMs;
+	const kindFields = kindFieldsFromArgs(parsed);
+	if (kindFields instanceof Error) return kindFields;
 	return {
 		kind: "add",
 		check: {
@@ -160,6 +273,7 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 			cwd: oneValue(parsed, "--cwd") ?? ".",
 			timeoutMs,
 			tags: tags(oneValue(parsed, "--tags")),
+			...kindFields,
 		},
 	};
 }
@@ -186,6 +300,13 @@ function editRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	}
 	const tagValue = oneValue(parsed, "--tags");
 	if (tagValue !== undefined) changes.tags = tags(tagValue);
+	if (oneValue(parsed, "--kind") !== undefined) {
+		const kindFields = kindFieldsFromArgs(parsed);
+		if (kindFields instanceof Error) return kindFields;
+		changes.kind = kindFields.kind ?? "command";
+		if (kindFields.numeric !== undefined) changes.numeric = kindFields.numeric;
+		if (kindFields.perf !== undefined) changes.perf = kindFields.perf;
+	}
 	if (Object.keys(changes).length === 0) return new Error("edit requires at least one changed field");
 	return { kind: "edit", id, changes };
 }
@@ -260,6 +381,30 @@ async function executeWorkflow(
 	return code;
 }
 
+async function baselineCommand(id: string | undefined): Promise<number> {
+	if (id === undefined) {
+		printError("baseline requires a check ID");
+		return 2;
+	}
+	const loaded = loadProjectVerifierCatalog(process.cwd());
+	if (!loaded.ok) {
+		printError(`production catalog parser rejected ${loaded.reason}`);
+		return 1;
+	}
+	const check = loaded.source?.checks.find((candidate) => candidate.id === id);
+	if (check === undefined) {
+		printError(`no catalog check '${id}' in ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}`);
+		return 1;
+	}
+	const recorded = await recordPerfBaseline(check);
+	if (!recorded.ok) {
+		printError(`baseline '${id}' not recorded: ${recorded.message}`);
+		return 1;
+	}
+	printOk(`recorded baseline for '${id}': ${Math.round(recorded.wallTimeMs)}ms at ${recorded.path}`);
+	return 0;
+}
+
 async function discoverCommand(): Promise<number> {
 	const discovery = discoverVerifierAuthoring();
 	if (!discovery.ok) {
@@ -304,6 +449,7 @@ export async function runVerifiersCommand(argv: string[]): Promise<number> {
 	const command = parsed.positional[0];
 	if (command === "discover") return discoverCommand();
 	if (command === "validate") return validateCommand();
+	if (command === "baseline") return baselineCommand(parsed.positional[1]);
 	if (command === "dry-run") {
 		const id = parsed.positional[1];
 		if (id === undefined) {