@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/cli/reset.ts

@@ -15,7 +15,7 @@ Each level clears exactly the root (or file) it names and nothing else.
 Levels (combinable except --all):
   --state       state root only (default). Holds every session transcript, so a
                 reset is the end of resume, /view, and the audit behind them.
-  --data        data root only: memory, evidence, evals (durable products)
+  --data        data root only: memory, evidence, evals, vendored tools (durable products)
   --cache       cache root only
   --auth        credentials.yaml only
   --config      settings.yaml only
@@ -42,7 +42,10 @@ Safety:
 const ROOT_NOTES: Readonly<Record<string, string>> = {
 	state:
 		"the state root holds every session transcript and the audit trail beside it; resume and /view lose their history",
-	data: "the data root holds durable products (memory, evidence, evals)",
+	// Vendored tools are named because they are the one durable product a reset
+	// cannot regenerate from anything local: getting them back is a download.
+	data:
+		"the data root holds durable products (memory, evidence, evals, and any vendored external tools, which a reinstall re-downloads)",
 };
 
 interface ParsedResetArgs {

package/src/cli/run.ts

@@ -11,6 +11,7 @@ import { createContextDomainModule } from "../domains/context/runtime.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import { agentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
 import { createDispatchDomainModule } from "../domains/dispatch/index.js";
+import { configureRunEventJournal } from "../domains/dispatch/run-event-journal.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
 import { ensureClioState, LifecycleDomainModule } from "../domains/lifecycle/index.js";
 import {
@@ -158,6 +159,45 @@ export function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): stri
 	return errors;
 }
 
+/**
+ * The TUI's verdict for a command-shaped token the registry does not own,
+ * applied to a headless task. Returns the refusal message, or null when the
+ * task is not an unknown command.
+ *
+ * `parseSlashCommand` is the canonical shape test and the canonical registry
+ * walk, so a token that is one word of letters, digits, hyphens, or colons and
+ * names no command lands here exactly as it does in the editor. Prose keeps
+ * reaching the model: an absolute path such as `/home/user/notes` carries a
+ * separator and is not one word, and `\/tmp is full` is the same escape the
+ * editor honors.
+ *
+ * A prompt template claims the token before the refusal does. Only membership
+ * is checked, not expansion: a template that exists but refuses (an untrusted
+ * project root, an unreadable body) has its own message, which the headless
+ * boot path already prints from the expansion itself. Deciding that here would
+ * duplicate the trust rules and put two refusals on one token.
+ *
+ * Both modules are imported lazily, so a task that does not start with a slash
+ * pays for neither. The laziness is a startup-cost choice and nothing more: for
+ * bundle partitioning a dynamic import is worse than a static one, because a
+ * dynamically imported module becomes a chunk split point by itself. What keeps
+ * this edge safe is the other end. `slash-commands.ts` is a declared CLI seam
+ * whose own imports stay off the interactive render graph, so reaching it does
+ * not make this file a second reacher of the chunk the instant shell's Stage 0
+ * closure sits on. Boundaries rule6 in `tests/boundaries/check-boundaries.ts`
+ * holds both halves of that.
+ */
+export async function unknownSlashCommandRefusal(task: string): Promise<string | null> {
+	if (!task.trim().startsWith("/")) return null;
+	const { parseSlashCommand } = await import("../interactive/slash-commands.js");
+	const command = parseSlashCommand(task);
+	if (command.kind !== "unknown-command") return null;
+	const { loadPromptTemplates } = await import("../domains/resources/index.js");
+	const templates = loadPromptTemplates({ cwd: process.cwd() });
+	if (templates.items.some((template) => template.name === command.token)) return null;
+	return `/${command.token} is not a command. Type /help for the list.`;
+}
+
 export async function runClioRun(
 	args: ReadonlyArray<string>,
 	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
@@ -218,6 +258,15 @@ export async function runClioRun(
 			if (!assembled) return 2;
 
 			if (parsed.agentId === undefined) {
+				// A mistyped slash command is a usage error, not a task. Refusing it
+				// here keeps it from booting a session and spending a model turn on a
+				// command that was never run, which is what the TUI has always done
+				// and what docs/extensions-and-sharing.md documents for both surfaces.
+				const slashRefusal = await unknownSlashCommandRefusal(assembled.prompt);
+				if (slashRefusal !== null) {
+					process.stderr.write(`clio-coder run: ${slashRefusal}\n`);
+					return 2;
+				}
 				// An explicit --target override is a one-run target; a missing id is an
 				// operator config error, not an assistant response. Reject it before the
 				// headless turn so the resolver diagnostic never streams to stdout as a
@@ -314,11 +363,20 @@ async function runDispatch(
 		createDispatchDomainModule({
 			getSettings: () => effectiveSettings,
 			autonomyOverride: parsed.autonomy !== undefined,
+			// This path iterates `handle.events` itself and builds no dispatch
+			// event registry, so the domain is the only thing that can write the
+			// run's durable transcript.
+			journalRunEvents: true,
 		}),
 		LifecycleDomainModule,
 	]);
 	const config = loaded.getContract<ConfigContract>("config");
 	const baseSettings = config?.get() ?? readSettings();
+	// Install `panes.journal` the same way the interactive composition root
+	// does. The journal never reads settings.yaml itself: it sits on the
+	// dispatch event path, where a settings read would be both a cost and a
+	// throw site.
+	configureRunEventJournal(baseSettings.panes.journal);
 	effectiveSettings =
 		parsed.autonomy === undefined ? baseSettings : { ...structuredClone(baseSettings), autonomy: parsed.autonomy };
 	const dispatch = loaded.getContract<DispatchContract>("dispatch");

package/src/cli/skills-inventory.ts

@@ -0,0 +1,185 @@
+/**
+ * Fixed machine-readable projection of this installation's installed skills.
+ *
+ * `skills list --json` already emits a machine-readable listing, and a GUI host
+ * reading it gets two things wrong. Without `--all` it sees only the skills the
+ * model may load, which is `trusted && !disableModelInvocation`, so a surface
+ * rendering trust and invocability off that payload prints "trusted" and
+ * "allowed" on every row and structurally cannot print anything else. And the
+ * rows it does get are the full loaded records, carrying the SKILL.md body, the
+ * file path, the base directory, and two content hashes, so every consumer has
+ * to re-derive the same redaction.
+ *
+ * This command answers both. It loads once, reports every installed skill
+ * whether or not the model can reach it, says which ones it can, and carries
+ * only fields that are safe by construction. It is a separate subcommand rather
+ * than a flag on `skills inspect`, because that one names a skill and a fixed
+ * read a host may run must take no identifier at all.
+ *
+ * Held back deliberately: the skill body, its file path, its base directory,
+ * both hashes, the install and registry URLs, and the free-text loader
+ * diagnostics. Whether a skill has an upstream to update from crosses; where
+ * that upstream is does not.
+ *
+ * Marketplace discovery is deliberately not here. `library list --json` already
+ * folds `discoverMarketplaceSkills` into its catalog, so every installable
+ * skill already crosses through that read, and a second one would report the
+ * same rows under a different name.
+ */
+
+import {
+	loadSkills,
+	type ResourceDiagnostic,
+	type Skill,
+	type SkillCatalogInvalidReason,
+	skillCatalogValidity,
+} from "../domains/resources/index.js";
+
+/** Wire bound on the emitted skill list. */
+const MAX_SKILLS_INVENTORY_SKILLS = 64;
+/** Wire bound on each skill's declared tool policy. */
+const MAX_SKILLS_INVENTORY_TOOLS = 32;
+
+const TOOL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+type SkillAuditState = "pass" | "warn" | "fail" | "unknown" | "not-reported";
+
+interface SkillsInventoryDiagnosticCounts {
+	readonly errors: number;
+	readonly warnings: number;
+	readonly collisions: number;
+}
+
+interface SkillsInventorySkill {
+	readonly name: string;
+	readonly description: string;
+	readonly scope: string;
+	readonly source: string;
+	/** Whether the skill's root is trusted enough for the model to see it at all. */
+	readonly trusted: boolean;
+	/** Whether the skill's own frontmatter permits model invocation. */
+	readonly modelInvocable: boolean;
+	/**
+	 * The effective answer, which is both of the above.
+	 *
+	 * Reported rather than left to be inferred because it is the fact an
+	 * operator is actually asking about, and because a listing filtered to it
+	 * cannot state it.
+	 */
+	readonly modelVisible: boolean;
+	readonly precedence: number;
+	readonly diagnostics: SkillsInventoryDiagnosticCounts;
+	/** Tools the skill narrows itself to. The harness intersects these with host policy. */
+	readonly allowedTools: readonly string[];
+	readonly disallowedTools: readonly string[];
+	/** True when a dispatched worker installed this, rather than the operator. */
+	readonly installedByWorker: boolean;
+	/** True when provenance records an upstream, so `skills update` has something to fetch. */
+	readonly updatable: boolean;
+	readonly audit: SkillAuditState;
+	readonly installedAt: string | null;
+	readonly updatedAt: string | null;
+}
+
+interface SkillsInventorySnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/** The verdict `skills validate` reaches, from the rule both callers share. */
+	readonly valid: boolean;
+	readonly invalidReason: SkillCatalogInvalidReason | null;
+	/** Every installed skill the loader resolved, before the wire bound. */
+	readonly total: number;
+	/** How many of those the model may actually load by name. */
+	readonly modelVisible: number;
+	readonly diagnostics: SkillsInventoryDiagnosticCounts;
+	readonly skills: readonly SkillsInventorySkill[];
+	readonly skillsTruncated: boolean;
+}
+
+const AUDIT_STATES: ReadonlySet<string> = new Set(["pass", "warn", "fail", "unknown"]);
+
+function countDiagnostics(diagnostics: ReadonlyArray<ResourceDiagnostic>): SkillsInventoryDiagnosticCounts {
+	let errors = 0;
+	let warnings = 0;
+	let collisions = 0;
+	for (const diag of diagnostics) {
+		if (diag.type === "error") errors += 1;
+		else if (diag.type === "collision") collisions += 1;
+		else warnings += 1;
+	}
+	return { errors, warnings, collisions };
+}
+
+/**
+ * Tool names are already-crossing identifiers: the agent catalog carries the
+ * same class. They are re-enforced structurally here anyway, because a skill's
+ * frontmatter is operator-authored and the loader does not hold it to a shape.
+ */
+function toolPolicy(value: ReadonlyArray<string> | undefined): string[] {
+	if (value === undefined) return [];
+	const tools: string[] = [];
+	for (const tool of value) {
+		if (tools.length >= MAX_SKILLS_INVENTORY_TOOLS) break;
+		if (typeof tool !== "string" || tool.length > 64 || !TOOL_PATTERN.test(tool)) continue;
+		if (!tools.includes(tool)) tools.push(tool);
+	}
+	return tools;
+}
+
+function timestamp(value: string | undefined): string | null {
+	if (value === undefined) return null;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+function projectSkill(skill: Skill): SkillsInventorySkill {
+	const provenance = skill.provenance;
+	const audit = provenance?.audit;
+	return {
+		name: skill.name,
+		description: skill.description,
+		scope: skill.scope,
+		source: skill.source,
+		trusted: skill.trusted,
+		modelInvocable: !skill.disableModelInvocation,
+		modelVisible: skill.trusted && !skill.disableModelInvocation,
+		precedence: skill.precedence,
+		diagnostics: countDiagnostics(skill.diagnostics),
+		allowedTools: toolPolicy(skill.allowedTools),
+		disallowedTools: toolPolicy(skill.disallowedTools),
+		installedByWorker: provenance?.installedBy === "worker",
+		// The URL itself is a host-side fact; that one exists is what tells the
+		// operator whether an update has anywhere to come from.
+		updatable: provenance?.installUrl !== undefined || provenance?.registryUrl !== undefined,
+		audit: audit !== undefined && AUDIT_STATES.has(audit) ? (audit as SkillAuditState) : "not-reported",
+		installedAt: timestamp(provenance?.installedAt),
+		updatedAt: timestamp(provenance?.updatedAt),
+	};
+}
+
+function skillsInventorySnapshot(now: () => number = Date.now, cwd: string = process.cwd()): SkillsInventorySnapshot {
+	const list = loadSkills({ cwd });
+	const validity = skillCatalogValidity(list);
+	const projected = list.items.map(projectSkill);
+	const skills = projected.slice(0, MAX_SKILLS_INVENTORY_SKILLS);
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		valid: validity.ok,
+		invalidReason: validity.reason,
+		total: projected.length,
+		modelVisible: projected.filter((skill) => skill.modelVisible).length,
+		diagnostics: countDiagnostics(list.diagnostics),
+		skills,
+		skillsTruncated: skills.length < projected.length,
+	};
+}
+
+export function runSkillsInventory(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder skills inventory: usage: clio-coder skills inventory --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(skillsInventorySnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/skills.ts

@@ -8,6 +8,7 @@ import {
 	type ResourceDiagnostic,
 	type Skill,
 	type SkillUpdateReport,
+	skillCatalogValidity,
 	updateSkills,
 } from "../domains/resources/index.js";
 import { formatColumns, printError, printOk } from "./shared.js";
@@ -18,6 +19,7 @@ Manage local Clio and Agent Skills-compatible skills.
 
 Commands:
   clio-coder skills list [--json] [--all]
+  clio-coder skills inventory --json
   clio-coder skills search <query> [--json]
   clio-coder skills inspect <name> [--json]
   clio-coder skills validate [path] [--json]
@@ -27,6 +29,10 @@ Commands:
   clio-coder skills sync [--force]
   clio-coder skills eval <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]
 
+inventory is the fixed machine-readable read a GUI host may run. Unlike a bare
+list it reports every installed skill, not only the ones the model may load, and
+says which are which; it carries no body, path, hash, or install URL.
+
 search covers installed skills plus the local marketplace: CLIO_CODER_SKILL_CATALOG_DIR,
 a repo skills/ catalog, or the catalog and skill-marketplace.json index the
 installed clio-coder package carries. Installing from the shipped catalog copies
@@ -249,6 +255,12 @@ function validationLoad(pathArg: string | undefined): ReturnType<typeof loadSkil
 }
 
 export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<number> {
+	// Routed before the shared parser so the fixed read stays exactly fixed: no
+	// skills flag can reach it, and no flag it does not name can be spent on it.
+	if (argv[0] === "inventory") {
+		const { runSkillsInventory } = await import("./skills-inventory.js");
+		return runSkillsInventory(argv.slice(1));
+	}
 	let parsed: Parsed;
 	try {
 		parsed = parse(argv);
@@ -365,19 +377,10 @@ export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<num
 				return 2;
 			}
 			const list = validationLoad(pathArg);
-			// A scanned file that produced no loaded skill is malformed, and a
-			// collision drops a skill: both make the catalog invalid, as does any
-			// hard error. Benign warnings (name/path mismatch, name format,
-			// description length) attach to a file that still loaded, so their path
-			// is among the loaded skills and they do not fail validation.
-			const loadedPaths = new Set(list.items.map((skill) => skill.filePath));
-			const hasInvalidDiagnostic = list.diagnostics.some(
-				(diag) =>
-					diag.type === "error" ||
-					diag.type === "collision" ||
-					(diag.type === "warning" && diag.path !== undefined && !loadedPaths.has(diag.path)),
-			);
-			const ok = list.items.length > 0 && !hasInvalidDiagnostic;
+			// The rule itself lives in the loader, because `skills inspect --json`
+			// reports the same verdict to a GUI host and a verdict that drifts
+			// between the terminal and the browser is worse than no verdict.
+			const { ok } = skillCatalogValidity(list);
 			if (parsed.json) {
 				process.stdout.write(`${JSON.stringify({ ok, skills: list.items, diagnostics: list.diagnostics }, null, 2)}\n`);
 			} else {

package/src/cli/tools.ts

@@ -0,0 +1,321 @@
+import { describeYaziProfile, inspectCurrentYaziProfile, resetYaziProfile } from "../domains/mux/index.js";
+import {
+	describeFloorRejection,
+	describeResolution,
+	findPinnedTool,
+	installedToolVersions,
+	installRemedy,
+	installTool,
+	PINNED_TOOLS,
+	removeTool,
+	type ToolStatus,
+	toolStatus,
+	toolStatuses,
+} from "../domains/toolchain/index.js";
+import { formatColumns, printError, printOk } from "./shared.js";
+
+const HELP = `clio-coder tools <command>
+
+Manage the external terminal programs Clio can drive. Every one of them is
+optional: Clio works without them and only uses one when it is present. Each is
+pinned to an exact upstream version and checksum, and a copy already on PATH
+wins over Clio's own as long as it clears the pinned minimum.
+
+Commands:
+  clio-coder tools list [--json]           the pinned table and where each resolves
+  clio-coder tools status <id> [--json] [--reset-profile]  one tool in detail
+  clio-coder tools install <id> [--force] [--json]  download, verify, and vendor a tool
+  clio-coder tools remove <id>|--all [--json]  delete every vendored version of a tool
+
+Downloads happen only here. Nothing on a startup path fetches anything.
+
+An install keeps one version directory per tool: once the pinned version is in
+place, versions it superseded are pruned, along with any staging directory left
+by an install that was killed. Removal touches nothing outside <data>/tools/<id>
+and needs no confirmation, since every byte under it is re-downloadable from the
+checksum-pinned registry. "remove --all" sweeps every tool in the table.
+`;
+
+interface Parsed {
+	command?: string;
+	positional: string[];
+	json: boolean;
+	force: boolean;
+	all: boolean;
+	resetProfile: boolean;
+	help: boolean;
+}
+
+export async function runToolsCommand(argv: ReadonlyArray<string> = []): Promise<number> {
+	let parsed: Parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		process.stderr.write(HELP);
+		return 2;
+	}
+	if (parsed.help || parsed.command === undefined) {
+		process.stdout.write(HELP);
+		return parsed.help ? 0 : 2;
+	}
+
+	// `--all` belongs to `remove` alone. Silently ignoring it elsewhere would let
+	// `tools install --all` read as a request that was honored.
+	if (parsed.all && parsed.command !== "remove") {
+		printError("--all is only valid with `tools remove`");
+		return 2;
+	}
+
+	switch (parsed.command) {
+		case "list":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return listTools(parsed.json);
+		case "status":
+			return statusTool(parsed.positional[0], parsed.json, parsed.resetProfile);
+		case "install":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return installOne(parsed.positional[0], parsed.force, parsed.json);
+		case "remove":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return parsed.all ? removeAll(parsed.positional[0], parsed.json) : removeOne(parsed.positional[0], parsed.json);
+		default:
+			printError(`unknown tools command: ${parsed.command}`);
+			process.stderr.write(HELP);
+			return 2;
+	}
+}
+
+function parse(argv: ReadonlyArray<string>): Parsed {
+	const out: Parsed = { positional: [], json: false, force: false, all: false, resetProfile: false, help: false };
+	for (const arg of argv) {
+		if (!out.command && !arg.startsWith("-")) {
+			out.command = arg;
+			continue;
+		}
+		switch (arg) {
+			case "--json":
+				out.json = true;
+				break;
+			case "--force":
+			case "-f":
+				out.force = true;
+				break;
+			case "--all":
+				out.all = true;
+				break;
+			case "--reset-profile":
+				out.resetProfile = true;
+				break;
+			case "--help":
+			case "-h":
+				out.help = true;
+				break;
+			default:
+				if (arg.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
+				out.positional.push(arg);
+		}
+	}
+	return out;
+}
+
+function listTools(json: boolean): number {
+	const statuses = toolStatuses();
+	if (json) {
+		process.stdout.write(`${JSON.stringify(statuses.map(jsonShape), null, 2)}\n`);
+		return 0;
+	}
+	const rows = statuses.map((status) => [
+		status.id,
+		status.version,
+		status.license,
+		status.resolution.source,
+		describeResolution(status),
+	]);
+	process.stdout.write(formatColumns([["TOOL", "PIN", "LICENSE", "SOURCE", "RESOLVED"], ...rows]));
+	return 0;
+}
+
+function invalidResetProfile(): number {
+	printError("--reset-profile is only valid with `tools status yazi`");
+	return 2;
+}
+
+/**
+ * The one refusal an unknown id gets, from every verb.
+ *
+ * It names the tools that do exist, because the whole error an operator makes
+ * here is a name: `tools remove herd` and `tools remove tmux` want different
+ * answers, and the registry list gives both of them one.
+ */
+function unknownTool(id: string): number {
+	printError(`unknown tool: ${id} (known: ${PINNED_TOOLS.map((row) => row.id).join(", ")})`);
+	return 2;
+}
+
+function statusTool(id: string | undefined, json: boolean, resetProfile: boolean): number {
+	if (id === undefined) {
+		printError("usage: clio-coder tools status <id>");
+		return 2;
+	}
+	const entry = findPinnedTool(id);
+	if (entry === null) {
+		return unknownTool(id);
+	}
+	if (resetProfile && id !== "yazi") return invalidResetProfile();
+	if (resetProfile) resetYaziProfile();
+	const status = toolStatus(entry);
+	const profile = id === "yazi" ? inspectCurrentYaziProfile() : null;
+	if (json) {
+		process.stdout.write(
+			`${JSON.stringify({ ...jsonShape(status), ...(profile ? { profile, profileReset: resetProfile } : {}) }, null, 2)}\n`,
+		);
+		return 0;
+	}
+	const rejection = describeFloorRejection(status);
+	const installedVersions = installedToolVersions(entry.id);
+	const lines = [
+		`${entry.id} ${entry.version} (${entry.license})`,
+		`  ${entry.summary}`,
+		`  homepage    ${entry.homepage}`,
+		`  binaries    ${entry.binaries.join(", ")}`,
+		`  PATH floor  ${entry.minimumVersion}`,
+		`  platform    ${status.platform ?? `${process.platform}-${process.arch}`}${status.supported ? "" : " (no pinned asset)"}`,
+		`  vendor dir  ${status.installDir}${status.installed ? "" : " (not installed)"}`,
+		`  vendored    ${installedVersions.length === 0 ? "nothing" : installedVersions.join(", ")}`,
+		`  resolves to ${describeResolution(status)}`,
+		// Spelled out on its own line as well as inside the resolution sentence,
+		// because a rejected PATH copy is the one thing an operator reads this
+		// command to understand and the sentence above may be about something else.
+		...(rejection === null
+			? []
+			: [
+					`  floor       rejected: ${rejection}`,
+					...(status.resolution.source === "none" && status.supported ? [`  remedy      ${installRemedy(entry.id)}`] : []),
+				]),
+		...(profile
+			? [
+					`  profile     ${describeYaziProfile(profile)}`,
+					...(resetProfile ? ["  profile reset; next open regenerates it"] : []),
+				]
+			: []),
+	];
+	process.stdout.write(`${lines.join("\n")}\n`);
+	return 0;
+}
+
+async function installOne(id: string | undefined, force: boolean, json: boolean): Promise<number> {
+	if (id === undefined) {
+		printError("usage: clio-coder tools install <id>");
+		return 2;
+	}
+	if (findPinnedTool(id) === null) {
+		return unknownTool(id);
+	}
+	const result = await installTool(id, {
+		force,
+		...(json ? {} : { onProgress: (message: string) => process.stderr.write(`  ${message}\n`) }),
+	});
+	if (json) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return result.ok ? 0 : 1;
+	}
+	if (!result.ok) {
+		printError(result.message);
+		return 1;
+	}
+	printOk(result.message);
+	for (const path of result.documents) process.stdout.write(`  license  ${path}\n`);
+	for (const version of result.pruned) process.stdout.write(`  pruned   ${id} ${version}\n`);
+	return 0;
+}
+
+/**
+ * Delete a tool's vendored install.
+ *
+ * The two answers an operator can act on are "there was nothing there" and
+ * "these versions are gone", and both are exit 0: the state they asked for
+ * holds either way. Only an id the registry does not know is a usage error,
+ * because that is the one case where nothing was inspected at all.
+ */
+function removeOne(id: string | undefined, json: boolean): number {
+	if (id === undefined) {
+		printError("usage: clio-coder tools remove <id>");
+		return 2;
+	}
+	if (findPinnedTool(id) === null) return unknownTool(id);
+	const result = removeTool(id);
+	if (json) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return result.ok ? 0 : 1;
+	}
+	if (!result.ok) {
+		printError(result.message);
+		return 1;
+	}
+	printOk(result.message);
+	if (result.removed.length > 0) {
+		process.stdout.write(`  reinstall with \`${installRemedy(id)}\`\n`);
+	}
+	return 0;
+}
+
+/**
+ * Delete every pinned tool's vendored install.
+ *
+ * Each tool is swept independently and the exit code is the worst of them, so
+ * one directory that resists deletion does not hide the two that came off
+ * cleanly. Tools that had nothing installed are counted rather than listed:
+ * on the machine this verb is for, most of the registry is usually absent, and
+ * three lines of "nothing to remove" would bury the one line that matters.
+ */
+function removeAll(id: string | undefined, json: boolean): number {
+	if (id !== undefined) {
+		printError("`tools remove --all` takes no tool id; drop the id or drop --all");
+		return 2;
+	}
+	const results = PINNED_TOOLS.map((entry) => removeTool(entry.id));
+	if (json) {
+		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+		return results.every((result) => result.ok) ? 0 : 1;
+	}
+	for (const result of results) {
+		if (!result.ok) printError(result.message);
+		else if (result.removed.length > 0 || result.staleStaging.length > 0) printOk(result.message);
+	}
+	const touched = results.filter((result) => result.ok && result.removed.length > 0);
+	const untouched = results.filter((result) => result.ok && result.removed.length === 0);
+	if (touched.length > 0) {
+		process.stdout.write(`  reinstall with \`clio-coder tools install <id>\`\n`);
+	}
+	if (untouched.length > 0) {
+		process.stdout.write(`  ${untouched.length} of ${results.length} had nothing vendored\n`);
+	}
+	return results.every((result) => result.ok) ? 0 : 1;
+}
+
+/** The JSON surface, flattened so a script does not have to walk the resolution. */
+function jsonShape(status: ToolStatus): Record<string, unknown> {
+	return {
+		id: status.id,
+		version: status.version,
+		license: status.license,
+		platform: status.platform,
+		supported: status.supported,
+		installed: status.installed,
+		installDir: status.installDir,
+		source: status.resolution.source,
+		binaryPath: status.resolution.binaryPath,
+		foundVersion: status.resolution.version,
+		minimumVersion: status.resolution.entry?.minimumVersion ?? null,
+		pathCandidate: status.resolution.pathCandidate,
+		// A script deciding whether to warn about a floor rejection should not have
+		// to parse `detail` for it, so the rejection and the command that answers
+		// it are their own fields. `remedy` is null exactly where installing would
+		// change nothing: already vendored, or no asset for this platform.
+		floorRejection: describeFloorRejection(status),
+		remedy: status.resolution.source === "none" && status.supported ? installRemedy(status.id) : null,
+		installedVersions: installedToolVersions(status.id),
+		detail: describeResolution(status),
+	};
+}