@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/cli/index.ts

@@ -5,14 +5,21 @@
 // a crashed boot are both legible to `ps`, `pgrep -f`, and htop.
 process.title = "clio-coder";
 
+import { AI_AGENT_NAME } from "../core/agent-environment.js";
+
+// Pi and other agent-aware developer tools use this generic marker to
+// attribute subprocess activity without knowing Clio-specific variables.
+// Set it unconditionally so every child inherits the actual spawning agent.
+process.env.AI_AGENT = AI_AGENT_NAME;
+
 // Only argument parsing and boot tracing load statically. Every subcommand is
 // imported dynamically through the command registry (see `dispatch`), so a bare `clio`
 // (interactive) or `clio-coder --version` pays for its own module graph and nothing
 // else — this is the highest-value cut of the cold module-load tax. Code
 // splitting (tsup.config.ts) keeps each command's transitive heavy externals in
 // its own chunk.
-import { fileURLToPath } from "node:url";
 import { traceBoot } from "../core/boot-trace.js";
+import { incompleteInstallationAdvice } from "../core/incomplete-installation.js";
 import { extractGlobalFlags, parseFlags, printError } from "./argv.js";
 
 const HELP = `Clio Coder command line
@@ -56,7 +63,7 @@ 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 skills               list, inspect, validate, or install skills
-  clio-coder docs [topic]         serve bundled HTML docs on 127.0.0.1 (--no-open to skip browser)
+  clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   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'
@@ -160,6 +167,7 @@ async function main(argv: string[]): Promise<number> {
 		...(skillPaths.length > 0 ? { skillPaths } : {}),
 	};
 	if (!subcommand) {
+		await enableBootCompileCache();
 		const { runClioCommand } = await import("./clio.js");
 		return runClioCommand(bootOptions);
 	}
@@ -167,6 +175,21 @@ async function main(argv: string[]): Promise<number> {
 	return dispatch(subcommand, subArgs, bootOptions);
 }
 
+/**
+ * Cache the boot-path module graphs' bytecode. Only the three long-lived
+ * entrypoints that already write state enable it (interactive, `run`, `acp`);
+ * read-only and dry-run commands such as `paths` and bare `doctor` document
+ * that they create nothing, and enabling the cache creates its directory, so
+ * a dispatch-wide enable would break that promise on every initialized home.
+ * A help invocation of a boot command is itself zero-side-effect, so the
+ * guard runs before enablement, not after the module's own help check.
+ */
+async function enableBootCompileCache(subArgs: ReadonlyArray<string> = []): Promise<void> {
+	if (subArgs.includes("--help") || subArgs.includes("-h")) return;
+	const { enableClioCompileCache } = await import("../core/compile-cache.js");
+	enableClioCompileCache();
+}
+
 /**
  * The dispatcher is also the command-recognition source used by top-level
  * value flags. Every dynamic import stays a literal so tsup can split command
@@ -177,7 +200,13 @@ const extensionsCommand: CommandHandler = async (subArgs) =>
 	(await import("./extensions.js")).runExtensionsCommand(subArgs);
 
 const COMMAND_HANDLERS = new Map<string, CommandHandler>([
-	["acp", async (subArgs, bootOptions) => (await import("./acp.js")).runAcpCommand(subArgs, bootOptions)],
+	[
+		"acp",
+		async (subArgs, bootOptions) => {
+			await enableBootCompileCache(subArgs);
+			return (await import("./acp.js")).runAcpCommand(subArgs, bootOptions);
+		},
+	],
 	["auth", async (subArgs) => (await import("./auth.js")).runAuthCommand(subArgs)],
 	["config", async (subArgs) => (await import("./config.js")).runConfigCommand(subArgs)],
 	["configure", async (subArgs) => (await import("./configure.js")).runConfigureCommand(subArgs)],
@@ -219,7 +248,13 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],
 	["import", async (subArgs) => (await import("./share.js")).runImportCommand(subArgs)],
 	["context", async (subArgs) => (await import("./context.js")).runContextCommand(subArgs)],
-	["run", async (subArgs, bootOptions) => (await import("./run.js")).runClioRun(subArgs, bootOptions)],
+	[
+		"run",
+		async (subArgs, bootOptions) => {
+			await enableBootCompileCache(subArgs);
+			return (await import("./run.js")).runClioRun(subArgs, bootOptions);
+		},
+	],
 	["doctor", async (subArgs) => (await import("./doctor.js")).runDoctorCommand(subArgs)],
 	["paths", async (subArgs) => (await import("./paths.js")).runPathsCommand(subArgs)],
 	["reset", async (subArgs) => (await import("./reset.js")).runResetCommand(subArgs)],
@@ -232,6 +267,16 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 			// Internal: the native worker stream server (WorkerSpec on stdin,
 			// NDJSON on stdout). The entry module runs main() on import and owns
 			// process exit; this settles only on a pre-run import failure.
+			// This is how SSH placement launches a worker on the remote install,
+			// where no local spawn boundary injected NODE_COMPILE_CACHE, so the
+			// worker graph enables the remote cache itself before it loads. The
+			// enable is in-process only: no environment variable is set, so the
+			// worker's own children inherit nothing. Nothing on this path
+			// injected the provenance pair either, so any marker present is
+			// foreign; strip it (and only it) so the entry's consume can never
+			// match and delete an operator's own NODE_COMPILE_CACHE.
+			Reflect.deleteProperty(process.env, "CLIO_CODER_INJECTED_COMPILE_CACHE");
+			await enableBootCompileCache();
 			await import("../worker/entry.js");
 			return 0;
 		},
@@ -257,27 +302,6 @@ function isCommandToken(token: string): boolean {
  * this repository can act on. The filter on our own output directory keeps a
  * module error raised by a user's extension or hook reporting itself normally.
  */
-function incompleteInstallationAdvice(err: unknown): string | null {
-	if ((err as NodeJS.ErrnoException | undefined)?.code !== "ERR_MODULE_NOT_FOUND") return null;
-	const message = err instanceof Error ? err.message : String(err);
-	let outputDir: string;
-	try {
-		outputDir = fileURLToPath(new URL("../", import.meta.url));
-	} catch {
-		return null;
-	}
-	if (!message.includes(outputDir)) return null;
-	return [
-		`${message}`,
-		"",
-		"This Clio Coder installation is incomplete: the command's own module is missing from",
-		`${outputDir}`,
-		"Reinstall to restore it, using the line that matches how you installed:",
-		"  npm install -g @iowarp/clio-coder    # npm install",
-		"  npm run install:local                # source checkout",
-	].join("\n");
-}
-
 /**
  * Route a subcommand to its registered handler, importing only that command's
  * module. Unknown names fail before loading any command graph.
@@ -295,7 +319,12 @@ async function dispatch(subcommand: string, subArgs: string[], bootOptions: CliB
 		}
 	}
 	printError(`unknown subcommand: ${subcommand}`);
-	process.stdout.write(helpText(false));
+	// The usage that explains a rejection belongs with the rejection on stderr.
+	// Writing it to stdout meant a mistyped command still produced a full page on
+	// the stream the caller was capturing for output, next to an error on the one
+	// it was probably not reading. `clio-coder --help` is the request for this
+	// text, and it still answers on stdout with exit 0.
+	process.stderr.write(helpText(false));
 	return 2;
 }
 

package/src/cli/memory.ts

@@ -92,7 +92,9 @@ export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<num
 		parsed = parseMemoryArgs(args);
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
-		process.stdout.write(HELP);
+		// Usage that accompanies an error goes to stderr with it; see the same
+		// note in evidence.ts.
+		process.stderr.write(HELP);
 		return 2;
 	}
 	if (parsed.help) {

package/src/cli/models.ts

@@ -117,7 +117,7 @@ export async function runModelsCommand(args: ReadonlyArray<string>): Promise<num
 	return 0;
 }
 
-function collectRows(entries: ReadonlyArray<TargetStatus>, providers: ProvidersContract): ModelRow[] {
+export function collectRows(entries: ReadonlyArray<TargetStatus>, providers: ProvidersContract): ModelRow[] {
 	const rows: ModelRow[] = [];
 	for (const status of entries) {
 		const runtimeId = status.runtime?.id ?? status.target.runtime;

package/src/cli/modes/json-stream.ts

@@ -14,6 +14,13 @@
  *     the `message_end` that follows.
  *   - `text_delta` / `thinking_delta` carry the increment, not the growing
  *     partial text.
+ *   - `message_end` keeps the message's accounting (role, model, usage, stop
+ *     reason, tool calls) and replaces the assistant `text` and `thinking`
+ *     blocks the deltas already carried with a marker naming their length.
+ *     Without this the stream carried every assistant token twice: measured on
+ *     one run, 41,094 bytes of deltas alongside 24,600 bytes of `message_end`
+ *     re-stating the same thinking and text. `user` and `toolResult` messages
+ *     pass through whole, because nothing else on the stream carries them.
  *   - `agent_end` carries its segment's usage and message count, not a second
  *     copy of every message already streamed.
  *   - `turn_end` keeps its assistant message (stop reason and usage live
@@ -34,13 +41,42 @@ export function projectHeadlessJsonEvent(event: ChatLoopEvent): unknown | null {
 	if (event.type === "thinking_delta") {
 		return { type: event.type, contentIndex: event.contentIndex, delta: event.delta };
 	}
+	if (event.type === "message_end") {
+		return { ...event, message: withoutStreamedContent(event.message) };
+	}
 	if (event.type === "agent_end") return segmentSummary(event.type, event.messages);
 	if (event.type === "turn_end") {
-		return { type: event.type, message: event.message };
+		return { type: event.type, message: withoutStreamedContent(event.message) };
 	}
 	return event;
 }
 
+/**
+ * Replace the content blocks a reader has already received as deltas.
+ *
+ * Only an assistant message streams: its `text` and `thinking` blocks arrive
+ * incrementally as `text_delta` and `thinking_delta` keyed by the same
+ * `contentIndex` this array is indexed by, so a reader reassembles them itself.
+ * `toolCall` blocks never stream and are kept whole. A `user` or `toolResult`
+ * message is returned untouched, because no delta ever carried it.
+ */
+function withoutStreamedContent<T>(message: T): T {
+	if (!isRecord(message) || message.role !== "assistant" || !Array.isArray(message.content)) return message;
+	const content = message.content.map((block: unknown) => {
+		if (!isRecord(block)) return block;
+		if (block.type === "text" && typeof block.text === "string") {
+			const { text: _text, ...rest } = block;
+			return { ...rest, streamed: true, textLength: block.text.length };
+		}
+		if (block.type === "thinking" && typeof block.thinking === "string") {
+			const { thinking: _thinking, ...rest } = block;
+			return { ...rest, streamed: true, thinkingLength: block.thinking.length };
+		}
+		return block;
+	});
+	return { ...message, content } as T;
+}
+
 /**
  * Projection for the dispatch `--json` stream, whose events come off a worker
  * rather than out of the chat loop.

package/src/cli/modes/print.ts

@@ -211,14 +211,29 @@ function countToolStats(stats: Map<string, ToolCallStat>): number {
 	return count;
 }
 
-const TERMINAL_JSON_EVENT_TYPES = new Set([
-	"agent_start",
-	"agent_end",
-	"message_end",
-	"notice",
-	"tool_execution_start",
-	"tool_execution_end",
-]);
+function prefixHeadlessFailure(chat: ChatLoop, message: string): string {
+	const snapshot = chat.lastRunSnapshot?.();
+	if (!snapshot) return message;
+	const url = snapshot.targetUrl ?? "endpoint unavailable";
+	return `target '${snapshot.targetId}' (${snapshot.runtimeId} ${url}): ${message}`;
+}
+
+/**
+ * The events `--json-events terminal` lets through, alongside the `turn_start`
+ * and `turn_end` frames this mode synthesizes itself.
+ *
+ * The mode's contract is the run receipt and nothing else. It used to admit
+ * `message_end`, which is the largest event on the stream and carries the
+ * injected system reminders, the operator's prompt, and every thinking block:
+ * "Say OK." produced 39.8 KB. `agent_start` and the two `tool_execution_*`
+ * events are per-step progress, which is what `--json-events full` is for.
+ *
+ * `turn_end` is deliberately absent even though the mode emits one. The
+ * synthesized frame carries `startedAt`, `endedAt`, and `exitCode`; the streamed
+ * event of the same name carries the turn's assistant message instead. Letting
+ * both through would put two different shapes behind one `type` on one stream.
+ */
+const TERMINAL_JSON_EVENT_TYPES = new Set(["agent_end", "notice"]);
 
 function isMainAgentRunKind(value: string): value is RunKind {
 	return value === "http" || value === "sdk" || value === "subprocess";
@@ -542,7 +557,7 @@ export async function runHeadlessMainAgent(chat: ChatLoop, options: HeadlessMain
 		stderrMessage = result.abortReason;
 	} else if (result.error) {
 		terminal = { exitCode: 1, outcome: "failed", status: "failed", failureMessage: result.error };
-		stderrMessage = result.error;
+		stderrMessage = prefixHeadlessFailure(chat, result.error);
 	} else if (result.text.length === 0 && !result.sawTerminatingToolResult) {
 		const failureMessage =
 			result.lastNotice !== null

package/src/cli/run.ts

@@ -7,7 +7,7 @@ import type { AgentsContract } from "../domains/agents/contract.js";
 import { AgentsDomainModule } from "../domains/agents/index.js";
 import type { ConfigContract } from "../domains/config/contract.js";
 import { ConfigDomainModule } from "../domains/config/index.js";
-import { createContextDomainModule } from "../domains/context/index.js";
+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";
@@ -28,7 +28,7 @@ import { SafetyDomainModule } from "../domains/safety/index.js";
 import { SchedulingDomainModule } from "../domains/scheduling/index.js";
 import { SessionDomainModule } from "../domains/session/index.js";
 import type { ImageContent } from "../engine/types.js";
-import { assistantTextFromEvent } from "../tools/dispatch.js";
+import { assistantTextFromEvent } from "../tools/dispatch-event-text.js";
 import { isToolProfileName } from "../tools/profiles.js";
 import { parseRunCliArgs, type RunCliArgs } from "./args.js";
 import { runClioCommand } from "./clio.js";

package/src/cli/skills-eval.ts

@@ -33,7 +33,7 @@ import { formatColumns, printError } from "./shared.js";
  * `evals.md` with RED-GREEN scenarios; this lane executes them instead of
  * trusting the prose: per scenario one baseline headless run (no skills), one
  * treatment run (the skill loaded via the explicit --skill path and invoked
- * with /skill:<name>), then one judge run that scores each Expected bullet
+ * with /skill <name>), then one judge run that scores each Expected bullet
  * pass/fail from the two transcripts.
  *
  * Deltas from the task-file eval harness, recorded rather than papered over:
@@ -302,10 +302,12 @@ function describeArmPolicyOutcome(allowNetwork: boolean): string {
 type EvalArm = "baseline" | "treatment" | "judge";
 
 /**
- * The argv for one arm's child `clio-coder run`. Every arm streams terminal JSON
- * events (a turn that ends on a terminating tool carries its content there,
- * not in text mode) and runs with discovery off so only the explicit --skill
- * of the treatment arm loads.
+ * The argv for one arm's child `clio-coder run`. Every arm streams the full JSON
+ * event sequence because the evaluator scores assistant messages and tool
+ * evidence, while terminal mode is intentionally receipt-only. A turn that ends
+ * on a terminating tool carries its content in the full event stream rather
+ * than text mode. Discovery stays off so only the treatment arm's explicit
+ * skill loads.
  *
  * @internal Exported for contract tests.
  */
@@ -314,7 +316,7 @@ export function armRunArgs(
 	prompt: string,
 	options: { target?: string | undefined; skillBaseDir?: string | undefined } = {},
 ): string[] {
-	const args = ["run", "--json", "--json-events", "terminal", "--no-skills"];
+	const args = ["run", "--json", "--json-events", "full", "--no-skills"];
 	if (arm !== "judge") args.push("--autonomy", ARM_AUTONOMY);
 	if (options.skillBaseDir !== undefined) args.push("--skill", options.skillBaseDir);
 	if (options.target !== undefined) args.push("--target", options.target);
@@ -465,7 +467,7 @@ async function runScenario(
 			childEnv,
 		);
 		const treatment = await captureHeadlessRun(
-			armRunArgs("treatment", `/skill:${skillName} ${scenario.setup}`, { target, skillBaseDir }),
+			armRunArgs("treatment", `/skill ${skillName} ${scenario.setup}`, { target, skillBaseDir }),
 			runWorkspaces.treatment,
 			timeoutMs,
 			childEnv,
@@ -817,6 +819,7 @@ export function parseRunStdout(stdout: string): { sessionId: string | null; tran
 	const lines: string[] = [];
 	let finalText = "";
 	let sawJson = false;
+	const streamedText = new Map<number, string>();
 	// Tool calls whose result is the skill's own SKILL.md. Correlated by
 	// toolCallId, which both the start and end events carry.
 	const skillBodyCallIds = new Set<string>();
@@ -834,6 +837,11 @@ export function parseRunStdout(stdout: string): { sessionId: string | null; tran
 			sessionId = event.id;
 			continue;
 		}
+		if (event.type === "text_delta" && typeof event.delta === "string") {
+			const contentIndex = typeof event.contentIndex === "number" ? event.contentIndex : 0;
+			streamedText.set(contentIndex, `${streamedText.get(contentIndex) ?? ""}${event.delta}`);
+			continue;
+		}
 		if (event.type === "tool_execution_start") {
 			const tool = readString(event.toolName) ?? readString(event.tool) ?? "tool";
 			const args = event.args ?? event.arguments ?? event.input;
@@ -865,13 +873,20 @@ export function parseRunStdout(stdout: string): { sessionId: string | null; tran
 		}
 		if (event.type === "message_end" && isRecord(event.message) && event.message.role === "assistant") {
 			const content = Array.isArray(event.message.content) ? event.message.content : [];
-			const text = content
+			const completedText = content
 				.filter((item): item is { type: "text"; text: string } => {
 					return isRecord(item) && item.type === "text" && typeof item.text === "string";
 				})
 				.map((item) => item.text)
 				.join("")
 				.trim();
+			const streamed = [...streamedText.entries()]
+				.sort(([left], [right]) => left - right)
+				.map(([, text]) => text)
+				.join("")
+				.trim();
+			streamedText.clear();
+			const text = completedText.length > 0 ? completedText : streamed;
 			if (text.length > 0) {
 				lines.push(`ASSISTANT: ${text}`);
 				finalText = text;

package/src/cli/skills.ts

@@ -27,8 +27,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]
 
-search covers installed skills plus the local marketplace (a repo skills/
-catalog, CLIO_CODER_SKILL_CATALOG_DIR, or the skill-marketplace.json index).
+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
+local files and needs no network.
 
 install resolves a bare name through that marketplace; a path or GitHub URL
 installs directly, and an existing local path always wins over a same-named
@@ -198,6 +200,9 @@ function skillRows(skills: ReadonlyArray<Skill>): string[][] {
 		skill.trusted ? "trusted" : "untrusted",
 		skill.disableModelInvocation ? "manual" : "model",
 		skill.hash.slice(0, 12),
+		// Blank for the ordinary operator-installed case; a worker install is
+		// the anomaly worth a column, so it is the only value that ever prints.
+		skill.provenance?.installedBy ?? "",
 		skill.description,
 	]);
 }
@@ -208,7 +213,7 @@ function printList(skills: ReadonlyArray<Skill>): void {
 		return;
 	}
 	process.stdout.write(
-		formatColumns([["name", "scope", "source", "trust", "invoke", "hash", "description"], ...skillRows(skills)]),
+		formatColumns([["name", "scope", "source", "trust", "invoke", "hash", "by", "description"], ...skillRows(skills)]),
 	);
 }
 
@@ -222,6 +227,9 @@ function printInspect(skill: Skill): void {
 	process.stdout.write(`trusted: ${skill.trusted}\n`);
 	process.stdout.write(`disableModelInvocation: ${skill.disableModelInvocation}\n`);
 	process.stdout.write(`hash: ${skill.hash}\n`);
+	if (skill.provenance?.installedBy) {
+		process.stdout.write(`installed-by: ${skill.provenance.installedBy}\n`);
+	}
 	if (skill.diagnostics.length > 0) {
 		process.stdout.write("diagnostics:\n");
 		for (const diag of skill.diagnostics) process.stdout.write(`  ${diag.type}: ${diag.message}\n`);
@@ -249,10 +257,17 @@ export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<num
 		process.stderr.write(HELP);
 		return 2;
 	}
-	if (parsed.help || !parsed.command) {
+	if (parsed.help) {
 		process.stdout.write(HELP);
 		return 0;
 	}
+	// A bare `clio-coder skills` is a missing required argument, which the
+	// exit-code contract puts at 2 with the usage on stderr. See the same note in
+	// extensions.ts.
+	if (!parsed.command) {
+		process.stderr.write(HELP);
+		return 2;
+	}
 	switch (parsed.command) {
 		case "list": {
 			const list = loadSkills({ cwd: process.cwd() });

package/src/cli/targets.ts

@@ -1101,6 +1101,7 @@ interface SerializedStatus {
 	probeCapabilities?: TargetStatus["probeCapabilities"];
 	probeModelId?: TargetStatus["probeModelId"];
 	probeNotes?: TargetStatus["probeNotes"];
+	probeSurfaces?: TargetStatus["probeSurfaces"];
 	discoveredModels: TargetStatus["discoveredModels"];
 	discoveredModelsSource?: TargetStatus["discoveredModelsSource"];
 	discoveredModelStates?: TargetStatus["discoveredModelStates"];
@@ -1146,5 +1147,8 @@ function serializeStatus(
 	if (status.probeNotes !== undefined) {
 		out.probeNotes = status.probeNotes;
 	}
+	if (status.probeSurfaces !== undefined) {
+		out.probeSurfaces = status.probeSurfaces;
+	}
 	return out;
 }

package/src/cli/text-layout.ts

@@ -14,12 +14,22 @@
  */
 
 /** Columns to lay out for, with a floor that keeps arithmetic non-negative. */
-export function terminalColumns(stream: { columns?: number | undefined } = process.stdout): number {
+export function terminalColumns(
+	stream: { columns?: number | undefined } = process.stdout,
+	env: { COLUMNS?: string | undefined } = process.env,
+): number {
 	const columns = stream.columns;
-	// A pipe reports no width. 80 is the conventional answer and is also the
-	// width the fixed-width rows were implicitly written for.
-	if (typeof columns !== "number" || !Number.isFinite(columns)) return 80;
-	return Math.max(20, Math.floor(columns));
+	if (typeof columns === "number" && Number.isFinite(columns)) return Math.max(20, Math.floor(columns));
+	// A pipe reports no width, and the fallback used to end there: `clio-coder
+	// targets | less` was pinned to 80 with no way to widen it, which cut the
+	// port off every url and ellipsized the model column, the two the table
+	// exists to tell apart. $COLUMNS is what a shell exports for exactly this,
+	// so an operator or a CI job can say how wide the capture is.
+	const declared = Number(env.COLUMNS);
+	if (Number.isFinite(declared) && declared > 0) return Math.max(20, Math.floor(declared));
+	// 80 is the conventional answer and is also the width the fixed-width rows
+	// were implicitly written for.
+	return 80;
 }
 
 /** Shorten to `width`, marking the cut so a truncated value never reads as complete. */

package/src/cli/trace.ts

@@ -14,7 +14,7 @@ import {
 } from "../domains/observability/trace-store.js";
 
 const HELP = `Usage:
-  clio-coder trace runs [--db PATH] [--limit N]
+  clio-coder trace runs [--db PATH] [--limit N] [--json]
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
@@ -33,6 +33,7 @@ interface ParsedTraceArgs {
 	follow: boolean;
 	limit: number;
 	port: number;
+	json: boolean;
 }
 
 function parseTraceArgs(args: string[]): ParsedTraceArgs {
@@ -42,9 +43,11 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let follow = false;
 	let limit = 50;
 	let port = 0;
+	let json = false;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--follow") follow = true;
+		else if (arg === "--json") json = true;
 		else if (arg === "--db" || arg === "--limit" || arg === "--port") {
 			const value = args[index + 1];
 			if (value === undefined) throw new Error(`${arg} requires a value`);
@@ -62,7 +65,33 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 		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 };
+	return { positional, db, dbExplicit, follow, limit, port, json };
+}
+
+/** Every subcommand `trace` answers to. Anything else is a usage error. */
+const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "sql", "ui"]);
+
+/** The subcommands whose first positional is a run id. */
+const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
+
+/**
+ * Reject a malformed invocation before the database is consulted.
+ *
+ * The no-database path below is a courtesy that exits 0, because a state tree
+ * nothing has written to is the empty state rather than a failure. Running it
+ * ahead of this check meant that on a fresh install every typed subcommand
+ * succeeded: `trace bogus`, `trace phases` with no run id, and `trace sql` with
+ * no query all exited 0 with the same "no trace database yet" line, so a CI step
+ * gated on one of them went on to the next line. The same invocations against a
+ * home that had a database exited 2, which is the documented behavior.
+ */
+function invocationError(command: string, runId: string | undefined): number | null {
+	if (!TRACE_COMMANDS.has(command)) {
+		process.stderr.write(`unknown trace command: ${command}\n${HELP}`);
+		return 2;
+	}
+	if (TRACE_COMMANDS_NEEDING_RUN_ID.has(command) && !runId) return missingRunId(command);
+	return null;
 }
 
 export async function runTraceCommand(args: string[]): Promise<number> {
@@ -86,6 +115,14 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 		process.stdout.write(HELP);
 		return command === "help" ? 0 : 2;
 	}
+	const sqlQuery = parsed.positional.slice(1).join(" ");
+	const usageError = invocationError(command, runId);
+	if (usageError !== null) return usageError;
+	if (command === "sql" && !sqlQuery) {
+		process.stderr.write("trace sql requires a SELECT query\n");
+		return 2;
+	}
+
 	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
 
 	// A database that was never written is the empty state, not a failure. Handing
@@ -104,29 +141,40 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 		return 1;
 	}
 	try {
+		// Every case below is reachable only after `invocationError` accepted the
+		// command and its required positional, so the run id is present wherever
+		// this reads one.
 		switch (command) {
-			case "runs":
-				printRuns(reader.runs(parsed.limit));
+			case "runs": {
+				const rows = reader.runs(parsed.limit);
+				if (parsed.json) process.stdout.write(`${JSON.stringify(rows, jsonBigInt, 2)}\n`);
+				else printRuns(rows);
 				return 0;
+			}
 			case "phases":
-				if (!runId) return missingRunId(command);
-				printPhases(reader.phases(runId));
+				printPhases(reader.phases(runId ?? ""));
 				return 0;
 			case "tail":
-				if (!runId) return missingRunId(command);
-				await tail(reader, runId, parsed.follow);
+				await tail(reader, runId ?? "", parsed.follow);
 				return 0;
 			case "procs":
-				if (!runId) return missingRunId(command);
-				printProcesses(reader.processes(runId));
+				printProcesses(reader.processes(runId ?? ""));
 				return 0;
 			case "sql": {
-				const query = parsed.positional.slice(1).join(" ");
-				if (!query) {
-					process.stderr.write("trace sql requires a SELECT query\n");
+				// The database opened cleanly above, so anything the store objects to
+				// here is the query the operator typed: a mutating statement, more
+				// than one statement, or SQL that will not parse. All three are usage
+				// errors. Refusing `DELETE FROM runs` with exit 1 said "the command
+				// failed" when the truth is "that is not a query this accepts", and
+				// the exit-code contract puts a mutation keyword at 2.
+				let rows: unknown;
+				try {
+					rows = reader.select(sqlQuery);
+				} catch (error) {
+					process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
 					return 2;
 				}
-				process.stdout.write(`${JSON.stringify(reader.select(query), jsonBigInt, 2)}\n`);
+				process.stdout.write(`${JSON.stringify(rows, jsonBigInt, 2)}\n`);
 				return 0;
 			}
 			default:

package/src/cli/upgrade.ts

@@ -172,9 +172,12 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	// After `npm install -g` the two differ until the refresh below, and that
 	// difference is the upgrade this command reports.
 	const recorded = readStateInfo()?.version ?? null;
+	// Both the dry run and the real run print this, so it stays in the mood the
+	// call site sets with "would refresh" or "refreshed". The null branch used to
+	// bake in "would write it", which a real upgrade printed after writing it.
 	const describeRefresh = (): string =>
 		recorded === null
-			? "state metadata (none recorded; would write it)"
+			? "state metadata (none recorded)"
 			: recorded === before
 				? `state metadata (already ${before})`
 				: `state metadata ${recorded} -> ${before}`;
@@ -233,7 +236,20 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 				printError("lifecycle domain unavailable");
 				return 1;
 			}
-			const result = await lifecycle.runMigrations(stateDir);
+			let result: Awaited<ReturnType<LifecycleContract["runMigrations"]>>;
+			try {
+				result = await lifecycle.runMigrations(stateDir);
+			} catch (err) {
+				// A migration reports why it could not run, but on its own that reads
+				// as the whole upgrade being impossible. It is not: the rest of the
+				// upgrade is independent of it, and naming the flag that runs the rest
+				// is the difference between a stuck operator and a moved one.
+				printError(
+					`migration failed: ${err instanceof Error ? err.message : String(err)}`,
+					"the rest of the upgrade does not depend on it; run `clio-coder upgrade --skip-migrations` to continue, then fix the cause and re-run `clio-coder upgrade`.",
+				);
+				return 1;
+			}
 			appliedIds = [...result.applied];
 			appliedCount = appliedIds.length;
 			if (appliedCount === 0) {