@iowarp/clio-coder 0.4.8 → 0.4.9

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/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/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

package/src/core/bash-exec.ts

@@ -21,7 +21,14 @@ export const BASH_HARD_CAP_BYTES = 16 * 1024 * 1024;
 
 const CLIO_CONTROL_ENV_KEYS = ["CLIO_CODER_INTERACTIVE", "BASH_ENV", "ENV"] as const;
 
-export interface BashCommandResult {
+export interface BashStreamByteCounts {
+	observedStdoutBytes: number;
+	observedStderrBytes: number;
+	retainedStdoutBytes: number;
+	retainedStderrBytes: number;
+}
+
+export interface BashCommandResult extends Partial<BashStreamByteCounts> {
 	error: NodeJS.ErrnoException | null;
 	stdout: string;
 	stderr: string;
@@ -60,6 +67,8 @@ export interface BashProgressScheduler {
 }
 
 export interface BashOutputProgressController {
+	/** Raw stream byte counts, independent of UTF-8 decoding and capture clipping. */
+	byteCounts(): BashStreamByteCounts;
 	/** Emit the initial empty cumulative snapshot, when a callback is configured. */
 	start(): void;
 	/** Accept one stream chunk. Returns true only when this chunk reaches the hard cap. */
@@ -90,6 +99,12 @@ export function createBashOutputProgressController(
 	const stdoutDecoder = new StringDecoder("utf8");
 	const stderrDecoder = new StringDecoder("utf8");
 	let decodersFinished = false;
+	const counts: BashStreamByteCounts = {
+		observedStdoutBytes: 0,
+		observedStderrBytes: 0,
+		retainedStdoutBytes: 0,
+		retainedStderrBytes: 0,
+	};
 	let outputBytes = 0;
 	let outputCapped = false;
 	let updateTimer: unknown = null;
@@ -144,16 +159,22 @@ export function createBashOutputProgressController(
 	};
 
 	return {
+		byteCounts: () => ({ ...counts }),
 		start(): void {
 			if (phase !== "active" || onUpdate === undefined) return;
 			updateDirty = true;
 			emitUpdate();
 		},
 		append(target, chunk): boolean {
-			if (phase !== "active" || outputCapped) return false;
+			if (phase !== "active") return false;
+			if (target === "stdout") counts.observedStdoutBytes += chunk.byteLength;
+			else counts.observedStderrBytes += chunk.byteLength;
+			if (outputCapped) return false;
 			const remaining = BASH_HARD_CAP_BYTES - outputBytes;
 			const accepted = chunk.byteLength <= remaining ? chunk : chunk.subarray(0, Math.max(0, remaining));
 			outputBytes += accepted.byteLength;
+			if (target === "stdout") counts.retainedStdoutBytes += accepted.byteLength;
+			else counts.retainedStderrBytes += accepted.byteLength;
 			if (accepted.byteLength > 0) {
 				const decoded = target === "stdout" ? stdoutDecoder.write(accepted) : stderrDecoder.write(accepted);
 				if (target === "stdout") stdout += decoded;
@@ -213,7 +234,7 @@ function parseNullDelimitedEnv(raw: string): NodeJS.ProcessEnv | null {
 }
 
 function captureLoginEnv(): Promise<NodeJS.ProcessEnv | null> {
-	return new Promise((resolve) => {
+	return new Promise<NodeJS.ProcessEnv | null>((resolve) => {
 		let stdout = "";
 		let settled = false;
 		const finish = (value: NodeJS.ProcessEnv | null): void => {
@@ -266,7 +287,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 		enabled: gitCommitAttributionEnabled(process.env),
 	});
 	reportCommitAttributionDiagnostic(attribution.diagnostic);
-	return new Promise((resolve) => {
+	return new Promise<BashCommandResult>((resolve) => {
 		const timeout = clampTimerDelayMs(options.timeoutMs ?? 300_000);
 		let aborted = false;
 		let timedOut = false;
@@ -377,6 +398,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			resolveAfterCancellation({
 				error: error as NodeJS.ErrnoException,
 				...finalOutput,
+				...output.byteCounts(),
 				exitCode: null,
 				signal: null,
 				aborted,
@@ -401,6 +423,7 @@ export async function runBashCommand(command: string, options: RunBashCommandOpt
 			resolveAfterCancellation({
 				error,
 				...finalOutput,
+				...output.byteCounts(),
 				exitCode: code,
 				signal: signalName,
 				aborted,

package/src/core/config.ts

@@ -1309,12 +1309,13 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 						"baseDelayMs",
 						"maxDelayMs",
 						"streamStallMs",
+						"firstTokenStallMs",
 					]);
 					if ("enabled" in chat.retry) {
 						const parsed = expectBoolean(issues, "chat.retry.enabled", chat.retry.enabled);
 						if (parsed !== undefined) settings.chat.retry.enabled = parsed;
 					}
-					for (const key of ["maxRetries", "baseDelayMs", "maxDelayMs", "streamStallMs"] as const) {
+					for (const key of ["maxRetries", "baseDelayMs", "maxDelayMs", "streamStallMs", "firstTokenStallMs"] as const) {
 						if (!(key in chat.retry)) continue;
 						const parsed = expectInteger(issues, `chat.retry.${key}`, chat.retry[key], { min: 0 });
 						if (parsed !== undefined) settings.chat.retry[key] = parsed;

package/src/core/defaults.ts

@@ -217,6 +217,13 @@ export interface RetrySettings {
 	maxDelayMs: number;
 	/** Silence on an in-flight stream past this many ms is treated as a wedged backend: abort and retry. */
 	streamStallMs: number;
+	/**
+	 * Silence allowed before a call's first token. A local server that slept
+	 * reloads the model and prefills cold before it can emit anything, so this
+	 * window is longer than the mid-stream one. 0 never aborts a call that has
+	 * not started streaming.
+	 */
+	firstTokenStallMs: number;
 }
 
 export const OUTPUT_STYLES = ["compact", "standard", "detailed"] as const;
@@ -391,7 +398,7 @@ export interface FleetSettings extends FleetRouteSettings {
 	history: FleetHistorySettings;
 }
 
-/** Roles whose authority is narrow enough for Slice 9 active joint routing. */
+/** Roles whose authority is narrow enough for active joint routing. */
 export const ACTIVE_ROUTING_ROLES = ["researcher", "verifier", "reviewer", "judge"] as const;
 export type ActiveRoutingRole = (typeof ACTIVE_ROUTING_ROLES)[number];
 
@@ -485,6 +492,7 @@ export const DEFAULT_SETTINGS = {
 			baseDelayMs: 2000,
 			maxDelayMs: 60000,
 			streamStallMs: 180000,
+			firstTokenStallMs: 600000,
 		} as RetrySettings,
 	} as ChatSettings,
 	fleet: {
@@ -620,6 +628,7 @@ chat:
     baseDelayMs: 2000
     maxDelayMs: 60000
     streamStallMs: 180000
+    firstTokenStallMs: 600000
 
 fleet:
   default:

package/src/core/event-bus.ts

@@ -14,7 +14,7 @@ import type { BusChannel, BusPayloadMap } from "./bus-events.js";
  * settling, so side effects that must happen before the next emit() must be
  * completed synchronously.
  *
- * Phase 2+ registers domain listeners here; violate the invariant and
+ * Domain listeners register here; violate the invariant and
  * shutdown.* ordering or banner timing will drift.
  */
 export type SafeEventListener<C extends BusChannel = BusChannel> = (payload: BusPayloadMap[C]) => void | Promise<void>;