@iowarp/clio-coder 0.4.7 → 0.4.9

package/src/cli/index.ts

@@ -20,6 +20,7 @@ process.env.AI_AGENT = AI_AGENT_NAME;
 // its own chunk.
 import { traceBoot } from "../core/boot-trace.js";
 import { incompleteInstallationAdvice } from "../core/incomplete-installation.js";
+import type { AutonomyLevel } from "../domains/safety/autonomy.js";
 import { extractGlobalFlags, parseFlags, printError } from "./argv.js";
 
 const HELP = `Clio Coder command line
@@ -29,6 +30,7 @@ science. CLIO stands for Context Layer for Input/Output, named for the Greek mus
 
 Usage:
   clio-coder                      start interactive repository chat
+  clio-coder web [--open]         start the browser application
   clio-coder acp                  serve Clio as an ACP v1 agent over stdio
   clio-coder --acp                alias for clio-coder acp
   clio-coder run [flags] <task>   run one headless main-agent turn
@@ -37,6 +39,7 @@ Usage:
   clio-coder --no-context-files, -nc  skip CLIO-CODER.md project-context injection
   clio-coder --with-panes         activate the panes extension (terminal panes for workers and tools)
   clio-coder --no-panes           keep panes off even when settings turn them on
+  clio-coder --autonomy <level>   start this interactive session at read-only|suggest|auto-edit|full-auto
   clio-coder configure            interactive first-run/configuration wizard
   clio-coder targets              list configured targets, health, auth, and capabilities
   clio-coder targets add          add a target interactively or via flags
@@ -70,12 +73,13 @@ Usage:
   clio-coder trace                query or view the durable dispatch trace mirror
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder library              register, install, update, import, inspect, and manage packages of every kind
+  clio-coder mcp list|trust|untrust  list MCP servers and manage trust for project-declared servers
   clio-coder tasks                list, add, hand, finish, or drop project operator tasks
   clio-coder verifiers            discover, inspect, author, validate, edit, or dry-run project checks
   clio-coder tools list|status|install|remove <id>  pinned external programs Clio can drive
   clio-coder interop inspect --json  detected external coding agents and how far each one is wired
   clio-coder panes install|theme  install the pane multiplexer (alias for 'tools install herdr'), or print Clio's theme as a herdr block
-  clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
+  clio-coder docs [topic]         open documentation in the web app (--no-open to print the launch link)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
   clio-coder --help, -h           this message
   clio-coder --help --all         this message plus every command under 'clio-coder dev'
@@ -121,6 +125,7 @@ interface CliBootOptions {
 	noSkills?: boolean;
 	skillPaths?: string[];
 	panes?: "with" | "without";
+	autonomy?: AutonomyLevel;
 }
 
 type CommandHandler = (subArgs: string[], bootOptions: CliBootOptions) => Promise<number>;
@@ -153,6 +158,7 @@ async function main(argv: string[]): Promise<number> {
 		noSkills,
 		skillPaths,
 		panes,
+		autonomy,
 		rest,
 		error: globalFlagError,
 	} = extractGlobalFlags(argv, isCommandToken);
@@ -181,10 +187,17 @@ async function main(argv: string[]): Promise<number> {
 		...(skillPaths.length > 0 ? { skillPaths } : {}),
 		...(panes === undefined ? {} : { panes }),
 	};
+	if (autonomy !== undefined && subcommand) {
+		// Silently dropping a safety level would be worse than refusing it.
+		printError(
+			`--autonomy before a subcommand applies to the interactive session only. For a headless turn use: clio-coder run --autonomy ${autonomy} "<task>"`,
+		);
+		return 2;
+	}
 	if (!subcommand) {
 		await enableBootCompileCache();
 		const { runClioCommand } = await import("./clio.js");
-		return runClioCommand(bootOptions);
+		return runClioCommand({ ...bootOptions, ...(autonomy === undefined ? {} : { autonomy }) });
 	}
 
 	return dispatch(subcommand, subArgs, bootOptions);
@@ -259,7 +272,9 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
 	["library", async (subArgs) => (await import("./library.js")).runLibraryCommand(subArgs)],
 	["tasks", async (subArgs) => (await import("./tasks.js")).runTasksCommand(subArgs)],
+	["mcp", async (subArgs) => (await import("./mcp.js")).runMcpCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
+	["web", async (subArgs) => (await import("./web.js")).runWebCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],
 	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],

package/src/cli/mcp.ts

@@ -0,0 +1,106 @@
+import {
+	MCP_TRUST_ACTION_CLASSES,
+	type McpTrustActionClass,
+	type McpTrustOptions,
+	resolveMcpServers,
+	trustMcpServer,
+	untrustMcpServer,
+} from "../domains/gateway/mcp/index.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder mcp <command>
+
+Commands:
+  clio-coder mcp list [--json]
+  clio-coder mcp trust <id> [--action-class <class>] [--json]
+  clio-coder mcp untrust <id> [--json]
+
+Action classes: ${MCP_TRUST_ACTION_CLASSES.join(", ")}
+
+JSON responses (--json):
+  list: {servers: [...], diagnostics: [...], trustDiagnostics: [...]}
+    Each server includes its declaration and trust {status, actionClass, reason?}.
+  trust: {ok: true, record: {projectRoot, id, digest, actionClass, trustedAt}}
+  untrust: {ok: true, removed: boolean}
+  errors: {ok: false, message: string}
+Exit codes: 0 success; 1 operational failure; 2 invalid usage.
+List retains its response shape on failure and exits 1 when config or trust
+ diagnostics are present. Mutation errors return the error shape with a
+ one-line reason. --help prints this text even when --json is supplied.
+`;
+
+export interface McpCommandOutput {
+	code: number;
+	text: string;
+	data: unknown;
+}
+
+/** Shared operator outcomes for the CLI and slash command. */
+export function mcpCommandOutput(
+	argv: ReadonlyArray<string>,
+	options: McpTrustOptions = { cwd: process.cwd() },
+): McpCommandOutput {
+	const fail = (code: number, message: string): McpCommandOutput => {
+		const text = message.replace(/[\r\n]+/gu, " ");
+		return { code, text, data: { ok: false, message: text } };
+	};
+	try {
+		const [command, id, ...rest] = argv;
+		if (command === "list" && id === undefined) {
+			const result = resolveMcpServers(options);
+			const lines = result.servers.map(
+				(server) =>
+					`${server.id} scope=${server.scope} command=${JSON.stringify([server.command, ...server.args])} cwd=${JSON.stringify(server.cwd)} trust=${server.trust.status}${"reason" in server.trust ? ` (${server.trust.reason})` : ""} actionClass=${server.trust.actionClass}`,
+			);
+			lines.push(...result.diagnostics.map((entry) => `${entry.path}: ${entry.message}`), ...result.trustDiagnostics);
+			return {
+				code: result.diagnostics.length || result.trustDiagnostics.length ? 1 : 0,
+				text: lines.join("\n") || "mcp: none",
+				data: result,
+			};
+		}
+		if ((command !== "trust" && command !== "untrust") || !id)
+			return fail(2, "usage: clio-coder mcp list | trust <id> [--action-class <class>] | untrust <id>");
+		let actionClass: McpTrustActionClass | undefined;
+		if (rest.length) {
+			if (
+				command !== "trust" ||
+				rest.length !== 2 ||
+				rest[0] !== "--action-class" ||
+				!MCP_TRUST_ACTION_CLASSES.includes(rest[1] as McpTrustActionClass)
+			)
+				return fail(2, `--action-class must be one of ${MCP_TRUST_ACTION_CLASSES.join(", ")} and applies only to trust`);
+			actionClass = rest[1] as McpTrustActionClass;
+		}
+		if (command === "trust") {
+			const result = trustMcpServer({ ...options, id, ...(actionClass ? { actionClass } : {}) });
+			return result.ok
+				? { code: 0, text: `mcp: trusted ${id} ${JSON.stringify(result.record)}`, data: result }
+				: fail(1, result.message);
+		}
+		const resolved = resolveMcpServers(options);
+		const server = resolved.servers.find((entry) => entry.id === id);
+		if (!server) return fail(1, `no declared MCP server with id '${id}'`);
+		if (server.scope === "user")
+			return fail(1, `server '${id}' is a user-scope declaration; it is trusted by authorship`);
+		const result = untrustMcpServer({ ...options, id });
+		return result.ok
+			? { code: 0, text: `mcp: untrusted ${id} (record ${result.removed ? "removed" : "already absent"})`, data: result }
+			: fail(1, result.message);
+	} catch (error) {
+		return fail(1, error instanceof Error ? error.message : String(error));
+	}
+}
+
+export function runMcpCommand(argv: ReadonlyArray<string>): number {
+	if (argv.includes("--help") || argv.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const json = argv.includes("--json");
+	const result = mcpCommandOutput(argv.filter((arg) => arg !== "--json"));
+	if (json) process.stdout.write(`${JSON.stringify(result.data, null, 2)}\n`);
+	else if (result.code && argv[0] !== "list") printError(result.text);
+	else process.stdout.write(`${result.text}\n`);
+	return result.code;
+}

package/src/cli/skills-eval.ts

@@ -26,6 +26,7 @@ import {
 	type SkillEvalScenario,
 } from "../domains/resources/index.js";
 import { NO_NETWORK_TOOLS_ENV } from "../tools/network-policy.js";
+import { effectiveToolCall } from "../tools/surface.js";
 import { formatColumns, printError } from "./shared.js";
 
 /**
@@ -845,9 +846,14 @@ function parseRunStdout(stdout: string): { sessionId: string | null; transcript:
 			continue;
 		}
 		if (event.type === "tool_execution_start") {
-			const tool = readString(event.toolName) ?? readString(event.tool) ?? "tool";
-			const args = event.args ?? event.arguments ?? event.input;
+			const recordedTool = readString(event.toolName) ?? readString(event.tool) ?? "tool";
+			const recordedArgs = event.args ?? event.arguments ?? event.input;
 			const callId = readString(event.toolCallId);
+			// A gateway call is judged as the capability it reached: an artifact
+			// written through the gateway is still the terminal answer.
+			const effective = effectiveToolCall(recordedTool, recordedArgs);
+			const tool = effective.toolName;
+			const args = effective.viaGateway ? effective.args : recordedArgs;
 			if (callId !== null && loadsSkillBody(tool, args)) skillBodyCallIds.add(callId);
 			lines.push(`TOOL ${tool} args=${preview(args)}`);
 			// Terminating tools end the turn with no assistant text; their content

package/src/cli/trace.ts

@@ -1,7 +1,5 @@
 import { existsSync } from "node:fs";
-import { access } from "node:fs/promises";
 import { resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import { clioStatePath } from "../core/xdg.js";
 import type { CodeStepRecord } from "../domains/dispatch/code-step.js";
 import { codeStepDir, readCodeStepRecords } from "../domains/dispatch/code-step-store.js";
@@ -29,10 +27,8 @@ const HELP = `Usage:
   clio-coder trace code-steps <rootId> [--json]   deterministic code steps of one fleet root
   clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
   clio-coder trace sql <SELECT query> [--db PATH]
-  clio-coder trace ui [--db PATH] [--port N]        source checkout only
 
-The viewer ships with the repository, not the npm package, so from an installed
-Clio the subcommands above are the way in. They read the same database, except
+The subcommands above read the same database, except
 code-steps, which reads the per-root record files under the state directory's
 code-steps/ tree (a code step is a subprocess, not a model run, so it never
 enters the SQLite mirror).
@@ -51,7 +47,6 @@ interface ParsedTraceArgs {
 	dbExplicit: boolean;
 	follow: boolean;
 	limit: number;
-	port: number;
 	json: boolean;
 	maxAgeDays: number | undefined;
 	maxBytes: number | undefined;
@@ -63,7 +58,6 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let dbExplicit = false;
 	let follow = false;
 	let limit = DEFAULT_TRACE_LIMIT;
-	let port = 0;
 	let json = false;
 	let maxAgeDays: number | undefined;
 	let maxBytes: number | undefined;
@@ -71,13 +65,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 		const arg = args[index];
 		if (arg === "--follow") follow = true;
 		else if (arg === "--json") json = true;
-		else if (
-			arg === "--db" ||
-			arg === "--limit" ||
-			arg === "--port" ||
-			arg === "--max-age-days" ||
-			arg === "--max-bytes"
-		) {
+		else if (arg === "--db" || arg === "--limit" || arg === "--max-age-days" || arg === "--max-bytes") {
 			const value = args[index + 1];
 			if (value === undefined) throw new Error(`${arg} requires a value`);
 			index += 1;
@@ -85,25 +73,23 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 				db = resolve(value);
 				dbExplicit = true;
 			} else if (arg === "--limit") limit = parseInteger(value, "--limit", 1, 500);
-			else if (arg === "--port") port = parseInteger(value, "--port", 0, 65_535);
 			else if (arg === "--max-age-days") maxAgeDays = parseInteger(value, arg, 1, 36_500);
 			else maxBytes = parseInteger(value, arg, 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		} else if (arg?.startsWith("--db=")) {
 			db = resolve(arg.slice(5));
 			dbExplicit = true;
 		} else if (arg?.startsWith("--limit=")) limit = parseInteger(arg.slice(8), "--limit", 1, 500);
-		else if (arg?.startsWith("--port=")) port = parseInteger(arg.slice(7), "--port", 0, 65_535);
 		else if (arg?.startsWith("--max-age-days=")) maxAgeDays = parseInteger(arg.slice(15), "--max-age-days", 1, 36_500);
 		else if (arg?.startsWith("--max-bytes="))
 			maxBytes = parseInteger(arg.slice(12), "--max-bytes", 1024 * 1024, Number.MAX_SAFE_INTEGER);
 		else if (arg?.startsWith("-")) throw new Error(`unknown trace flag: ${arg}`);
 		else if (arg !== undefined) positional.push(arg);
 	}
-	return { positional, db, dbExplicit, follow, limit, port, json, maxAgeDays, maxBytes };
+	return { positional, db, dbExplicit, follow, limit, json, maxAgeDays, maxBytes };
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "code-steps", "prune", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "code-steps", "prune", "sql"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -169,8 +155,6 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 		}
 	}
 
-	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
-
 	// Code-step records live in flat per-root JSON files beside the ledger, not
 	// in the SQLite mirror, so this answers before the database is consulted and
 	// ignores --db. An absent root directory is the empty state: the root either
@@ -187,7 +171,6 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 				!parsed.dbExplicit &&
 				!parsed.follow &&
 				parsed.limit === DEFAULT_TRACE_LIMIT &&
-				parsed.port === 0 &&
 				parsed.maxAgeDays === undefined &&
 				parsed.maxBytes === undefined,
 		);
@@ -379,50 +362,6 @@ function printProcesses(rows: TraceProcessRow[]): void {
 	}
 }
 
-async function runTraceUi(db: string, port: number): Promise<number> {
-	const candidates = [
-		fileURLToPath(new URL("../apps/trace-viewer/server.mjs", import.meta.url)),
-		fileURLToPath(new URL("../../apps/trace-viewer/server.mjs", import.meta.url)),
-	];
-	const entry = await firstExisting(candidates);
-	if (entry === null) {
-		process.stderr.write(
-			"trace viewer is available only from a source checkout; apps/trace-viewer/server.mjs was not found\n" +
-				"  the npm package does not carry the viewer, so an installed clio cannot start it\n" +
-				`  the same run is readable here: clio-coder trace runs --db ${db}\n` +
-				"  from a checkout of the repository: npm run trace:ui\n",
-		);
-		return 1;
-	}
-	const module = (await import(pathToFileURL(entry).href)) as {
-		startTraceViewer(options: { db: string; port: number }): Promise<{ url: string; close(): Promise<void> }>;
-	};
-	const server = await module.startTraceViewer({ db, port });
-	process.stdout.write(`Trace viewer: ${server.url}\n`);
-	await new Promise<void>((resolveStop) => {
-		const stop = (): void => {
-			process.off("SIGINT", stop);
-			process.off("SIGTERM", stop);
-			void server.close().finally(resolveStop);
-		};
-		process.on("SIGINT", stop);
-		process.on("SIGTERM", stop);
-	});
-	return 0;
-}
-
-async function firstExisting(paths: string[]): Promise<string | null> {
-	for (const path of paths) {
-		try {
-			await access(path);
-			return path;
-		} catch {
-			// Try the next source-checkout location.
-		}
-	}
-	return null;
-}
-
 function parseInteger(value: string, flag: string, min: number, max: number): number {
 	const parsed = Number(value);
 	if (!Number.isInteger(parsed) || parsed < min || parsed > max)

package/src/cli/uninstall.ts

@@ -9,6 +9,7 @@ import { detectInstallMethod } from "../domains/lifecycle/install-method.js";
 import { createLifecyclePresenter, type LifecycleItem, measurePath, shortenPath } from "./lifecycle-presenter.js";
 import { type RemovalFailure, removePath, reportRemovalFailures } from "./removal.js";
 import { printError } from "./shared.js";
+import { prepareWebUninstall } from "./web.js";
 
 const HELP = `clio-coder uninstall [--remove-binary] [--keep-config] [--keep-data] [--dry-run] [--force] [--json]
 
@@ -18,6 +19,8 @@ Per-project \`.clio-coder/\` directories sit outside those roots and are never
 removed here. Every project Clio has run in is recorded in the session metadata,
 so the real run and --dry-run both list them and name the command that clears one.
 Shell startup files are reported, never edited.
+Owned web background services are stopped and disabled before their state is
+removed; their desktop launchers are removed using the app's ownership manifests.
 
 Flags:
   --keep-config    preserve the configuration root (settings.yaml, credentials)
@@ -331,6 +334,18 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	const linkSize = measurePath(linkPath);
 	const launcher = classifyLauncher(linkPath);
 	const shellEdits = detectShellRcEdits();
+	let web: Awaited<ReturnType<typeof prepareWebUninstall>>;
+	try {
+		const desktopPrefix =
+			process.env.XDG_DATA_HOME && isAbsolute(process.env.XDG_DATA_HOME)
+				? process.env.XDG_DATA_HOME
+				: join(homedir(), ".local/share");
+		web = await prepareWebUninstall({ stateDir: dirs.state, desktopPrefix });
+	} catch (error) {
+		presenter.fail(error instanceof Error ? error.message : "Web installation ownership could not be checked.");
+		presenter.finish();
+		return 1;
+	}
 
 	// The state root's own children (audit, sessions) are inside the State row
 	// and go with it; listing them again as separate removals double-counted the
@@ -372,6 +387,7 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 			detail: launcherItemDetail(launcher, args.removeBinary),
 		},
 	];
+	for (const item of web.items) items.push({ ...item, status: "remove", detail: "verified app ownership" });
 
 	// A login file is reported, never edited; see detectShellRcEdits.
 	for (const file of shellEdits) {
@@ -413,6 +429,16 @@ export async function runUninstallCommand(argv: ReadonlyArray<string>): Promise<
 	}
 
 	const failures: RemovalFailure[] = [];
+	try {
+		await web.remove();
+		for (const item of web.items) presenter.completedStep(`Removed ${item.label}`);
+	} catch (error) {
+		presenter.fail(
+			error instanceof Error ? error.message : "Could not stop the web installation; Clio state was preserved.",
+		);
+		presenter.finish();
+		return 1;
+	}
 
 	if (cacheSize.exists) {
 		const failure = removePath("cache", dirs.cache, false);

package/src/cli/upgrade.ts

@@ -86,24 +86,10 @@ function parseUpgradeArgs(argv: ReadonlyArray<string>): UpgradeOptions {
  * the installed version is the newest one.
  */
 type RegistryLookup =
-	| { asked: false; reason: "source checkout" | "network checks are disabled" | "post-install checks" }
+	| { asked: false; reason: "source checkout" | "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 = 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 };
-	if (noNetwork) return { asked: false, reason: "network checks are disabled" };
+async function lookUpAvailableVersion(channel: Channel, method: "source" | "npm"): Promise<RegistryLookup> {
 	if (method === "source") return { asked: false, reason: "source checkout" };
 	try {
 		const res = await fetch(`https://registry.npmjs.org/@iowarp/clio-coder/${channel}`, {
@@ -149,16 +135,10 @@ async function runChild(command: string, args: ReadonlyArray<string>, label: str
 }
 
 async function runNpmInstall(channel: Channel): Promise<void> {
-	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 (testSeam("CLIO_CODER_TEST_UPGRADE_FAIL") === "doctor") {
-		throw new Error("mock doctor fix failure");
-	}
 	await runChild("clio-coder", ["doctor", "--fix"], "clio-coder doctor --fix");
 }
 
@@ -168,7 +148,29 @@ async function runPostInstallUpgrade(opts: UpgradeOptions): Promise<void> {
 	await runChild("clio-coder", args, "clio-coder upgrade --post-install");
 }
 
-export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<number> {
+export interface UpgradeDependencies {
+	detectInstallMethod: typeof detectInstallMethod;
+	lookUpAvailableVersion: typeof lookUpAvailableVersion;
+	runNpmInstall: typeof runNpmInstall;
+	runDoctorFixAfterInstall: typeof runDoctorFixAfterInstall;
+	runPostInstallUpgrade: typeof runPostInstallUpgrade;
+	runPending: typeof runPending;
+}
+
+const DEFAULT_DEPENDENCIES: UpgradeDependencies = {
+	detectInstallMethod,
+	lookUpAvailableVersion,
+	runNpmInstall,
+	runDoctorFixAfterInstall,
+	runPostInstallUpgrade,
+	runPending,
+};
+
+export async function runUpgradeCommand(
+	argv: ReadonlyArray<string>,
+	dependencies: Partial<UpgradeDependencies> = {},
+): Promise<number> {
+	const deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
 	let opts: UpgradeOptions;
 	try {
 		opts = parseUpgradeArgs(argv);
@@ -186,14 +188,13 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 
 	const before = getVersionInfo().clio;
 	const stateDir = resolveClioDirs().state;
-	const method = detectInstallMethod();
+	const method = deps.detectInstallMethod();
 	const methodLabel = method === "source" ? "source checkout" : opts.postInstall ? "package install" : "npm global";
 	presenter.setMethod(methodLabel);
 
-	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);
+		: await deps.lookUpAvailableVersion(opts.channel, method);
 	const availableVersion = lookup.asked ? lookup.version : null;
 
 	presenter.step(`Installation method: ${methodLabel}`);
@@ -223,8 +224,8 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	// "Already current" is a claim about a version that was compared. A lookup
 	// that was made and came back empty has compared nothing, so it does not get
 	// to make it: the run falls through and attempts the install, which is what
-	// the operator asked for. A lookup that was never owed (a checkout, or the
-	// network seam) leaves the recorded state version to decide.
+	// the operator asked for. A lookup that was never owed for a checkout or
+	// post-install checks leaves the recorded state version to decide.
 	const versionIsCurrent =
 		(lookup.asked ? lookup.version === before : true) && (recorded === null || recorded === before);
 	const hasPendingMigrations = pendingMigrationIds.length > 0;
@@ -260,11 +261,9 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 		presenter.note("Running post-install checks with the active clio-coder binary.");
 	} else if (method === "source") {
 		presenter.note("Source checkout: no npm install to run.");
-	} else if (noNetwork) {
-		presenter.note("CLIO_CODER_TEST_UPGRADE_NO_NETWORK is set; skipping npm install.");
 	} else {
 		try {
-			await runNpmInstall(opts.channel);
+			await deps.runNpmInstall(opts.channel);
 			presenter.completedStep(`Installed @iowarp/clio-coder@${opts.channel}`);
 		} catch (err) {
 			presenter.fail("npm install failed", err instanceof Error ? err.message : String(err));
@@ -276,7 +275,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 			return 1;
 		}
 		try {
-			await runPostInstallUpgrade(opts);
+			await deps.runPostInstallUpgrade(opts);
 			presenter.done("Done");
 			return 0;
 		} catch (err) {
@@ -293,10 +292,7 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	} else {
 		let result: Awaited<ReturnType<typeof runPending>>;
 		try {
-			if (testSeam("CLIO_CODER_TEST_UPGRADE_FAIL") === "migration") {
-				throw new Error("mock migration failure in 2026-09-01-settings-v2");
-			}
-			result = await runPending(stateDir);
+			result = await deps.runPending(stateDir);
 		} catch (err) {
 			presenter.fail("migration failed", err instanceof Error ? err.message : String(err));
 			presenter.commandAdvice(
@@ -312,13 +308,13 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 		else for (const id of applied) presenter.completedStep(`Applied migration ${id}`);
 	}
 
-	if (method === "source" || noNetwork) {
+	if (method === "source") {
 		const refresh = describeRefresh();
 		initializeClioHome();
 		presenter.completedStep(`Refreshed ${refresh}`);
 	} else {
 		try {
-			await runDoctorFixAfterInstall();
+			await deps.runDoctorFixAfterInstall();
 			presenter.completedStep("Checked the install with clio-coder doctor --fix");
 		} catch (err) {
 			presenter.fail("doctor fix failed", err instanceof Error ? err.message : String(err));

package/src/cli/usage.ts

@@ -85,6 +85,7 @@ interface UsageTotals {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	cacheWrite1h?: number;
 	reasoningTokens: number;
 	totalTokens: number;
 	costUsd: number;
@@ -169,6 +170,7 @@ function outOfTurnUsageCall(row: OutOfTurnUsageRow): LedgerUsageCall {
 		output: row.usage.output ?? 0,
 		cacheRead: row.usage.cacheRead ?? 0,
 		cacheWrite: row.usage.cacheWrite ?? 0,
+		...(typeof row.usage.cacheWrite1h === "number" ? { cacheWrite1h: row.usage.cacheWrite1h } : {}),
 		reasoningTokens: row.usage.reasoning ?? 0,
 		totalTokens: row.usage.totalTokens ?? 0,
 		costUsd: row.usage.costUsd ?? 0,
@@ -197,6 +199,7 @@ function addUsageCall(totals: UsageTotals, call: LedgerUsageCall): void {
 	totals.output += call.output;
 	totals.cacheRead += call.cacheRead;
 	totals.cacheWrite += call.cacheWrite;
+	if (call.cacheWrite1h !== undefined) totals.cacheWrite1h = (totals.cacheWrite1h ?? 0) + call.cacheWrite1h;
 	totals.reasoningTokens += call.reasoningTokens;
 	totals.totalTokens += call.totalTokens;
 	totals.costUsd += call.costUsd;

package/src/cli/verifiers.ts

@@ -38,7 +38,7 @@ Fields:
   --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;
+  --tolerance <json>      numeric-compare: {"relative"?,"absolute"?,"ulp"?,"combine"?:all|any,"nonFinite"?:fail|match}, at least one numeric bound;
                           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