@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/cli/trace-inspect.ts

@@ -0,0 +1,252 @@
+/**
+ * Fixed machine-readable projection of recent durable trace runs and phases.
+ *
+ * `trace runs --json` is an operator-directed terminal surface: it takes a
+ * database path and a limit, and it emits `SELECT *`, which includes the
+ * request text the operator typed. The GUI cannot reuse that transport. This
+ * command accepts no identifier, path, or limit, opens only the default trace
+ * database, selects a bounded newest-first window itself, and emits accounting
+ * facts with no prompt text, no free-form description or error, and no path.
+ *
+ * It is deliberately a separate read from `fleet inspect --json` even though
+ * both are keyed by run id. The ledger and the trace database are different
+ * durable stores with different failure modes: an installation that never
+ * enabled tracing has no trace database at all, and that must be an empty
+ * answer here rather than a failure of the run journal.
+ */
+
+import { existsSync } from "node:fs";
+import { clioStatePath } from "../core/xdg.js";
+import { TraceReader, traceDatabasePath } from "../domains/observability/trace-store.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+import { truncateToWidth } from "../engine/tui-primitives.js";
+
+export const TRACE_INSPECT_MAX_RUNS = 8;
+export const TRACE_INSPECT_MAX_PHASES = 16;
+export const TRACE_INSPECT_MAX_EVENT_KINDS = 12;
+export const TRACE_INSPECT_MAX_PROCESS_KINDS = 8;
+
+const IDENTITY_WIDTH = 128;
+const STATUS_WIDTH = 64;
+
+export interface TraceInspectPhase {
+	readonly name: string;
+	readonly kind: string;
+	readonly owner: string;
+	readonly status: string;
+	readonly attempt: number;
+	readonly retries: number;
+	/** Whether the phase recorded an error, without the error text itself. */
+	readonly failed: boolean;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+}
+
+/**
+ * What a run's events were, in aggregate.
+ *
+ * Deliberately shapes and not rows. A trace event carries `payload_json` and a
+ * free-form name, which are the class of value this boundary keeps host-side,
+ * so the tail itself stays in the terminal and what crosses is how many events
+ * of each kind there were and the span they cover. The counts come out of SQL,
+ * so the payloads are not read on the way to counting them.
+ */
+export interface TraceInspectEvents {
+	readonly total: number;
+	readonly firstAt: string | null;
+	readonly lastAt: string | null;
+	readonly kinds: readonly { readonly kind: string; readonly count: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+/**
+ * What a run's child processes were, in aggregate.
+ *
+ * Same rule, applied harder: a process row carries the command line, the pid,
+ * and the host. None of that is needed to say a run spawned four workers and
+ * one is still alive, and none of it crosses.
+ */
+export interface TraceInspectProcesses {
+	readonly total: number;
+	readonly running: number;
+	readonly kinds: readonly { readonly kind: string; readonly total: number; readonly running: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+export interface TraceInspectRun {
+	readonly runId: string;
+	readonly agent: string;
+	readonly target: string;
+	readonly model: string;
+	readonly runtime: string;
+	readonly node: string | null;
+	readonly status: string;
+	readonly startedAt: string;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+	readonly phases: readonly TraceInspectPhase[];
+	readonly phasesTruncated: boolean;
+	readonly events: TraceInspectEvents;
+	readonly processes: TraceInspectProcesses;
+}
+
+export interface TraceInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/**
+	 * False when this installation has no trace database. That is the ordinary
+	 * state of an installation that never enabled tracing, and it has to stay
+	 * distinguishable from a database that exists and holds no runs.
+	 */
+	readonly available: boolean;
+	readonly runs: readonly TraceInspectRun[];
+	readonly truncated: boolean;
+}
+
+function bounded(value: string, width: number): string {
+	const sanitized = sanitizeCallTargetText(value);
+	if (sanitized.length === 0) return "unavailable";
+	return sanitizeCallTargetText(truncateToWidth(sanitized, width, "…", false));
+}
+
+function nullableBounded(value: string | null, width: number): string | null {
+	return value === null ? null : bounded(value, width);
+}
+
+/** A finite non-negative count, or null when the store recorded none. */
+function tally(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
+}
+
+/** A finite non-negative cost, or null. Kept as a number so the GUI formats it. */
+function cost(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Wall time between two stamps. Null rather than zero when either is missing or
+ * unparseable, because "still running" and "took no time" are different facts.
+ */
+function elapsed(startedAt: string | null, endedAt: string | null): number | null {
+	if (startedAt === null || endedAt === null) return null;
+	const start = Date.parse(startedAt);
+	const end = Date.parse(endedAt);
+	if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+	return Math.max(0, end - start);
+}
+
+function eventSummary(reader: TraceReader, runId: string): TraceInspectEvents {
+	const span = reader.eventSpan(runId);
+	const all = reader.eventKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_EVENT_KINDS);
+	return {
+		total: tally(span.total) ?? 0,
+		firstAt: span.firstAt,
+		lastAt: span.lastAt,
+		kinds: visible.map((entry) => ({ kind: bounded(entry.type, STATUS_WIDTH), count: tally(entry.count) ?? 0 })),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+function processSummary(reader: TraceReader, runId: string): TraceInspectProcesses {
+	const all = reader.processKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_PROCESS_KINDS);
+	return {
+		total: all.reduce((sum, entry) => sum + (tally(entry.total) ?? 0), 0),
+		running: all.reduce((sum, entry) => sum + (tally(entry.running) ?? 0), 0),
+		kinds: visible.map((entry) => ({
+			kind: bounded(entry.kind, STATUS_WIDTH),
+			total: tally(entry.total) ?? 0,
+			running: tally(entry.running) ?? 0,
+		})),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+/** Pure payload builder, exported so the fixed contract is testable without subprocess capture. */
+function traceInspectSnapshot(
+	now: () => number = Date.now,
+	databasePath: string = traceDatabasePath(clioStatePath()),
+): TraceInspectSnapshot {
+	const generatedAt = new Date(now()).toISOString();
+	if (!existsSync(databasePath)) {
+		return { version: 1, generatedAt, available: false, runs: [], truncated: false };
+	}
+	let reader: TraceReader;
+	try {
+		reader = new TraceReader(databasePath);
+	} catch {
+		// A database that exists but will not open is not an empty installation,
+		// and it is not this command's job to diagnose it. Report it as present
+		// with nothing readable rather than inventing either extreme.
+		return { version: 1, generatedAt, available: true, runs: [], truncated: false };
+	}
+	try {
+		const selected = reader.runs(TRACE_INSPECT_MAX_RUNS + 1);
+		const window = selected.slice(0, TRACE_INSPECT_MAX_RUNS);
+		const runs = window.map((row): TraceInspectRun => {
+			const allPhases = reader.phases(row.run_id);
+			const visible = allPhases.slice(0, TRACE_INSPECT_MAX_PHASES);
+			return {
+				runId: bounded(row.run_id, IDENTITY_WIDTH),
+				agent: bounded(row.agent, IDENTITY_WIDTH),
+				target: bounded(row.target, IDENTITY_WIDTH),
+				model: bounded(row.model, IDENTITY_WIDTH),
+				runtime: bounded(row.runtime, IDENTITY_WIDTH),
+				node: nullableBounded(row.node, IDENTITY_WIDTH),
+				status: bounded(row.status, STATUS_WIDTH),
+				startedAt: row.started_at,
+				elapsedMs: elapsed(row.started_at, row.ended_at),
+				totalTokens: tally(row.total_tokens),
+				totalCostUsd: cost(row.total_cost_usd),
+				phases: visible.map(
+					(phase): TraceInspectPhase => ({
+						name: bounded(phase.name, IDENTITY_WIDTH),
+						kind: bounded(phase.kind, STATUS_WIDTH),
+						owner: bounded(phase.owner, IDENTITY_WIDTH),
+						status: bounded(phase.status, STATUS_WIDTH),
+						attempt: tally(phase.attempt) ?? 0,
+						retries: tally(phase.retries) ?? 0,
+						// The error text can quote a path, a URL, or a model reply, so only
+						// the fact that one was recorded crosses.
+						failed: phase.error !== null && phase.error !== "",
+						elapsedMs: elapsed(phase.started_at, phase.ended_at),
+						totalTokens: tally(phase.total_tokens),
+						totalCostUsd: cost(phase.total_cost_usd),
+					}),
+				),
+				phasesTruncated: allPhases.length > visible.length,
+				events: eventSummary(reader, row.run_id),
+				processes: processSummary(reader, row.run_id),
+			};
+		});
+		return {
+			version: 1,
+			generatedAt,
+			available: true,
+			runs,
+			truncated: selected.length > window.length,
+		};
+	} finally {
+		reader.close();
+	}
+}
+
+/**
+ * `clio-coder trace inspect --json`, and nothing else.
+ *
+ * `fixed` is false as soon as the caller supplied a database, a limit, a follow,
+ * or any other positional. The whole point of this command is that its argv is
+ * not a surface: a GUI host can invoke it and be certain the process it started
+ * cannot be steered into reading a different file or a wider window.
+ */
+export function runTraceInspect(fixed: boolean): number {
+	if (!fixed) {
+		process.stderr.write("clio-coder trace inspect: usage: clio-coder trace inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(traceInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/trace.ts

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { clioStatePath } from "../core/xdg.js";
 import {
+	assertTraceSelectOnly,
 	DEFAULT_TRACE_RETENTION_POLICY,
 	resolveTraceRetentionPolicy,
 	TRACE_EVENT_POLL_LIMIT,
@@ -15,9 +16,11 @@ import {
 	TraceStore,
 	traceDatabasePath,
 } from "../domains/observability/trace-store.js";
+import { runTraceInspect } from "./trace-inspect.js";
 
 const HELP = `Usage:
   clio-coder trace runs [--db PATH] [--limit N] [--json]
+  clio-coder trace inspect --json         a fixed bounded window with no request text
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
@@ -32,6 +35,9 @@ CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the auto
 policy; prune flags override those values for one command.
 `;
 
+/** Rows `trace runs` shows when the operator names no limit. */
+const DEFAULT_TRACE_LIMIT = 50;
+
 interface ParsedTraceArgs {
 	positional: string[];
 	db: string;
@@ -50,7 +56,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 	let db = traceDatabasePath(clioStatePath());
 	let dbExplicit = false;
 	let follow = false;
-	let limit = 50;
+	let limit = DEFAULT_TRACE_LIMIT;
 	let port = 0;
 	let json = false;
 	let maxAgeDays: number | undefined;
@@ -91,7 +97,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "prune", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "prune", "sql", "ui"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -144,9 +150,33 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 		process.stderr.write("trace sql requires a SELECT query\n");
 		return 2;
 	}
+	if (command === "sql") {
+		try {
+			assertTraceSelectOnly(sqlQuery);
+		} catch (error) {
+			process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			return 2;
+		}
+	}
 
 	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
 
+	// `inspect` answers ahead of the no-database courtesy below, because its
+	// answer to a state tree nothing has written to is a JSON snapshot saying
+	// the trace database is unavailable, not a sentence on stdout.
+	if (command === "inspect") {
+		return runTraceInspect(
+			parsed.positional.length === 1 &&
+				parsed.json &&
+				!parsed.dbExplicit &&
+				!parsed.follow &&
+				parsed.limit === DEFAULT_TRACE_LIMIT &&
+				parsed.port === 0 &&
+				parsed.maxAgeDays === undefined &&
+				parsed.maxBytes === undefined,
+		);
+	}
+
 	// A database that was never written is the empty state, not a failure. Handing
 	// the absent path to node:sqlite produced "unable to open database file",
 	// which named neither the file nor a next step, and loading the module leaked
@@ -357,6 +387,38 @@ function missingDatabase(parsed: ParsedTraceArgs): number {
 		);
 		return 1;
 	}
+	if (parsed.json && parsed.positional[0] === "runs") {
+		process.stdout.write("[]\n");
+		return 0;
+	}
+	if (parsed.json && parsed.positional[0] === "prune") {
+		let policy: ReturnType<typeof resolveTraceRetentionPolicy>;
+		try {
+			policy = resolveTraceRetentionPolicy({
+				...(parsed.maxAgeDays === undefined ? {} : { maxAgeDays: parsed.maxAgeDays }),
+				...(parsed.maxBytes === undefined ? {} : { maxBytes: parsed.maxBytes }),
+			});
+		} catch (error) {
+			process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+			return 1;
+		}
+		process.stdout.write(
+			`${JSON.stringify(
+				{
+					available: false,
+					policy,
+					runsRemoved: 0,
+					rowsRemoved: 0,
+					bytesRemoved: 0,
+					vacuumed: false,
+					protectedRuns: 0,
+				},
+				null,
+				2,
+			)}\n`,
+		);
+		return 0;
+	}
 	process.stdout.write(
 		`no trace database yet at ${parsed.db}. rows are recorded when a dispatch executes or an interactive turn runs; run \`clio-coder run "<task>"\` or start a session to create one.\n`,
 	);

package/src/cli/uninstall.ts

@@ -90,7 +90,7 @@ export interface ProjectContextInventory {
  * rather than one per session. Directories whose `.clio-coder/` is already gone are
  * dropped, because an inventory of nothing to do is noise.
  */
-export function projectContextInventory(stateDir: string): ProjectContextInventory {
+function projectContextInventory(stateDir: string): ProjectContextInventory {
 	const root = join(stateDir, "sessions");
 	let hashes: string[];
 	try {
@@ -298,7 +298,7 @@ function readNpmPrefix(): string | null {
  * that cannot be resolved is dangling, which is still something the operator
  * will hit and still not this installation.
  */
-export function otherClioOnPath(pathClio: string | null, localLink: string): string | null {
+function otherClioOnPath(pathClio: string | null, localLink: string): string | null {
 	if (pathClio === null) return null;
 	if (pathClio === localLink) return null;
 	const resolve = (path: string): string | null => {

package/src/cli/upgrade.ts

@@ -1,12 +1,8 @@
 import { spawn } from "node:child_process";
-import { loadDomains } from "../core/domain-loader.js";
 import { initializeClioHome } from "../core/init.js";
 import { clioStateDir } from "../core/xdg.js";
-import { ConfigDomainModule } from "../domains/config/index.js";
-import type { LifecycleContract } from "../domains/lifecycle/contract.js";
-import { LifecycleDomainModule } from "../domains/lifecycle/index.js";
 import { detectInstallMethod } from "../domains/lifecycle/install-method.js";
-import { listMigrations } from "../domains/lifecycle/migrations/index.js";
+import { listMigrations, runPending } from "../domains/lifecycle/migrations/index.js";
 import { readStateInfo } from "../domains/lifecycle/state.js";
 import { getVersionInfo } from "../domains/lifecycle/version.js";
 import { printError, printHeader, printOk } from "./shared.js";
@@ -229,36 +225,35 @@ export async function runUpgradeCommand(argv: ReadonlyArray<string>): Promise<nu
 	if (opts.skipMigrations) {
 		process.stdout.write("[upgrade] skipping migrations (--skip-migrations)\n");
 	} else {
-		const loaded = await loadDomains([ConfigDomainModule, LifecycleDomainModule]);
+		// Migrations run on the state tree directly rather than through the
+		// lifecycle domain. Loading that domain pulls in `config`, whose start
+		// runs the strict settings reader, and a settings-repairing migration is
+		// precisely the one that cannot get past it: `clio-coder upgrade` on a
+		// home whose settings.yaml names a retired key failed the domain load and
+		// never reached the migration that removes the key. A runner that needs
+		// valid config in order to repair invalid config can never run. The
+		// domain's `runMigrations` is a passthrough to this same function, so
+		// nothing is lost by calling it where the circularity does not exist.
+		let result: Awaited<ReturnType<typeof runPending>>;
 		try {
-			const lifecycle = loaded.getContract<LifecycleContract>("lifecycle");
-			if (!lifecycle) {
-				printError("lifecycle domain unavailable");
-				return 1;
-			}
-			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) {
-				process.stdout.write("[upgrade] no pending migrations\n");
-			} else {
-				for (const id of appliedIds) process.stdout.write(`[upgrade] applied migration ${id}\n`);
-			}
-		} finally {
-			await loaded.stop();
+			result = await runPending(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) {
+			process.stdout.write("[upgrade] no pending migrations\n");
+		} else {
+			for (const id of appliedIds) process.stdout.write(`[upgrade] applied migration ${id}\n`);
 		}
 	}
 

package/src/cli/usage.ts

@@ -788,7 +788,7 @@ function indent(text: string): string {
 		.join("\n");
 }
 
-export function inWindow(iso: string, start: number, end: number): boolean {
+function inWindow(iso: string, start: number, end: number): boolean {
 	const value = Date.parse(iso);
 	return Number.isFinite(value) && value >= start && value <= end + USAGE_WINDOW_FUTURE_SKEW_MS;
 }
@@ -968,7 +968,7 @@ function bashCommandFromToolCallPayload(payload: unknown): string | null {
  * assignments dropped, verb plus subcommand kept, flags kept with values
  * stripped, remaining arguments dropped.
  */
-export function bashShape(command: string): string {
+function bashShape(command: string): string {
 	const firstLine = command.split("\n").find((line) => {
 		const trimmed = line.trim();
 		return trimmed.length > 0 && !trimmed.startsWith("#");

package/src/cli/validate-model.ts

@@ -39,7 +39,7 @@ function describeLiveTarget(live: LiveModelInventory): string {
 }
 
 /** The refusal `configure` prints for a model the live target does not advertise. */
-export function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
+function formatUnadvertisedModelReason(modelId: string, live: LiveModelInventory): string {
 	const resident = live.resident.length > 0 ? live.resident.join(", ") : "none";
 	return (
 		`${describeLiveTarget(live)} does not advertise model '${modelId}'. ` +