@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/cli/run.ts

@@ -148,7 +148,7 @@ async function assemblePrompt(parsed: RunCliArgs): Promise<{
  * path, not a skill package, or validation failure such as a missing
  * description). Exported for contracts tests.
  */
-export function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
+function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
 	const errors: string[] = [];
 	for (const skillPath of skillPaths) {
 		const list = loadSkills({ disableDiscovery: true, explicitSkillPaths: [skillPath] });
@@ -187,7 +187,7 @@ export function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): stri
  * closure sits on. Boundaries rule6 in `tests/boundaries/check-boundaries.ts`
  * holds both halves of that.
  */
-export async function unknownSlashCommandRefusal(task: string): Promise<string | null> {
+async function unknownSlashCommandRefusal(task: string): Promise<string | null> {
 	if (!task.trim().startsWith("/")) return null;
 	const { parseSlashCommand } = await import("../interactive/slash-commands.js");
 	const command = parseSlashCommand(task);
@@ -261,7 +261,7 @@ export async function runClioRun(
 				// A mistyped slash command is a usage error, not a task. Refusing it
 				// here keeps it from booting a session and spending a model turn on a
 				// command that was never run, which is what the TUI has always done
-				// and what docs/extensions-and-sharing.md documents for both surfaces.
+				// and what docs/guide/extensions-and-sharing.md documents for both surfaces.
 				const slashRefusal = await unknownSlashCommandRefusal(assembled.prompt);
 				if (slashRefusal !== null) {
 					process.stderr.write(`clio-coder run: ${slashRefusal}\n`);
@@ -372,13 +372,13 @@ async function runDispatch(
 	]);
 	const config = loaded.getContract<ConfigContract>("config");
 	const baseSettings = config?.get() ?? readSettings();
-	// Install `panes.journal` the same way the interactive composition root
+	// Install `fleet.history.journal` the same way the interactive composition root
 	// does. The journal never reads settings.yaml itself: it sits on the
 	// dispatch event path, where a settings read would be both a cost and a
 	// throw site.
-	configureRunEventJournal(baseSettings.panes.journal);
-	effectiveSettings =
-		parsed.autonomy === undefined ? baseSettings : { ...structuredClone(baseSettings), autonomy: parsed.autonomy };
+	configureRunEventJournal(baseSettings.fleet.history.journal);
+	effectiveSettings = structuredClone(baseSettings);
+	if (parsed.autonomy !== undefined) effectiveSettings.safety.autonomy = parsed.autonomy;
 	const dispatch = loaded.getContract<DispatchContract>("dispatch");
 	if (!dispatch) {
 		process.stderr.write("dispatch domain unavailable\n");
@@ -394,19 +394,15 @@ async function runDispatch(
 			return 1;
 		}
 		const settings = effectiveSettings;
-		const profileTargetId = parsed.agentProfile ? settings.workers?.profiles?.[parsed.agentProfile]?.target : undefined;
+		const profileTargetId = parsed.agentProfile ? settings.fleet?.profiles?.[parsed.agentProfile]?.target : undefined;
 		const runtimeByTarget = new Map(settings.targets.map((target) => [target.id, target.runtime] as const));
 		const runtimeTargetId = parsed.agentRuntime
-			? [settings.workers?.default, ...Object.values(settings.workers?.profiles ?? {})].find(
+			? [settings.fleet?.default, ...Object.values(settings.fleet?.profiles ?? {})].find(
 					(profile) => profile?.target && runtimeByTarget.get(profile.target) === parsed.agentRuntime,
 				)?.target
 			: undefined;
 		const targetId =
-			parsed.target ??
-			profileTargetId ??
-			runtimeTargetId ??
-			settings.workers?.default?.target ??
-			settings.orchestrator?.target;
+			parsed.target ?? profileTargetId ?? runtimeTargetId ?? settings.fleet?.default?.target ?? settings.chat?.target;
 		const target = targetId ? providers.getTarget(targetId) : null;
 		const runtime = target ? providers.getRuntime(target.runtime) : null;
 		if (!target || !runtime) {
@@ -441,7 +437,7 @@ async function runDispatch(
 	if (skillPaths.length > 0) dispatchReq.skillPaths = skillPaths;
 	try {
 		const settings = effectiveSettings;
-		if (settings.skills?.trustProjectCompatRoots) {
+		if (settings.integrations.projectResources?.trustProjectImports) {
 			dispatchReq.trustProjectCompatRoots = true;
 		}
 	} catch {
@@ -451,8 +447,8 @@ async function runDispatch(
 	let memorySection = "";
 	try {
 		const records = loadMemoryRecordsSync(clioDataDir());
-		const boundProfileName = parsed.agentProfile ?? effectiveSettings.workers.agentBindings[parsed.agentId];
-		const boundProfile = boundProfileName ? effectiveSettings.workers.profiles[boundProfileName] : undefined;
+		const boundProfileName = parsed.agentProfile ?? effectiveSettings.fleet.agentProfiles[parsed.agentId];
+		const boundProfile = boundProfileName ? effectiveSettings.fleet.profiles[boundProfileName] : undefined;
 		const configuredRuntime = (targetId: string | null | undefined): string | undefined =>
 			effectiveSettings.targets.find((target) => target.id === targetId)?.runtime;
 		const profileRuntimeId = configuredRuntime(boundProfile?.target);

package/src/cli/share.ts

@@ -142,7 +142,11 @@ function printDiagnostics(diagnostics: ReadonlyArray<ShareDiagnostic>): void {
 
 function printRecovery(plan: ShareImportPlan): void {
 	if (!plan.recovery) return;
-	process.stderr.write("recovery: import stopped after a write failure\n");
+	process.stderr.write(
+		plan.recovery.failed
+			? "recovery: import stopped after a write failure\n"
+			: "recovery: import completed with preserved backups\n",
+	);
 	process.stderr.write("written files:\n");
 	if (plan.recovery.written.length === 0) process.stderr.write("  none\n");
 	else {
@@ -233,7 +237,7 @@ export function runShareCommand(argv: ReadonlyArray<string>): number {
 				const archive = plan.archive;
 				if (archive) {
 					process.stdout.write(
-						`archive: ${archive.manifest.format} clio=${archive.manifest.clioVersion} files=${archive.files.length} created=${archive.manifest.createdAt}\n`,
+						`archive: ${archive.manifest.format} clio-coder=${archive.manifest.clioCoderVersion} files=${archive.files.length} created=${archive.manifest.createdAt}\n`,
 					);
 				}
 			}

package/src/cli/skills-eval.ts

@@ -51,9 +51,9 @@ const DEFAULT_RUN_TIMEOUT_MS = 600_000;
  *
  * A headless `clio-coder run` has no operator to answer a permission ask, so below
  * full-auto every exec-class call in an arm dies with the harness's own denial
- * and the judge scores a skill that was never allowed to act. Operator decision
- * of 2026-08-13 (docs/findings/HARNESS-NOTES.md item 4): eval arms run
- * full-auto, because their workspaces are per-run copies created under a
+ * and the judge scores a skill that was never allowed to act. The 2026-08-13
+ * harness decision is that eval arms run full-auto because their workspaces
+ * are per-run copies created under a
  * private temp root and removed when the scenario ends. The judge arm is
  * excluded: it scores text and is instructed to call no tools, so granting it
  * unattended write and exec buys nothing.
@@ -311,7 +311,7 @@ type EvalArm = "baseline" | "treatment" | "judge";
  *
  * @internal Exported for contract tests.
  */
-export function armRunArgs(
+function armRunArgs(
 	arm: EvalArm,
 	prompt: string,
 	options: { target?: string | undefined; skillBaseDir?: string | undefined } = {},
@@ -335,7 +335,7 @@ export function armRunArgs(
  *
  * @internal Exported for contract tests.
  */
-export function permissionWallReason(arm: EvalArm, run: CapturedRun): string | null {
+function permissionWallReason(arm: EvalArm, run: CapturedRun): string | null {
 	const haystack = `${run.transcript}\n${run.finalText}`;
 	let blocked = 0;
 	let at = haystack.indexOf(HEADLESS_PERMISSION_DENIED_MARKER);
@@ -360,7 +360,7 @@ function unmeasuredBullets(scenario: SkillEvalScenario, reason: string): ScoredB
  *
  * @internal Exported for contract tests.
  */
-export function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
 	const childEnv: NodeJS.ProcessEnv = { ...env };
 	if (allowNetwork) Reflect.deleteProperty(childEnv, NO_NETWORK_TOOLS_ENV);
 	else childEnv[NO_NETWORK_TOOLS_ENV] = "1";
@@ -378,7 +378,7 @@ export function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = pro
  * the catalog answers only for a name no root installed, which is the skill
  * author's case in this repository.
  */
-export function resolveSkillBaseDir(
+function resolveSkillBaseDir(
 	nameOrPath: string,
 	cwd: string,
 ): { baseDir: string | null; origin?: string; error?: string } {
@@ -442,7 +442,7 @@ async function runScenario(
 	// Published per-scenario figure: monotonic so a clock correction during a
 	// long sweep cannot land in one row's wall time.
 	const scenarioStart = performance.now();
-	const workspace = await mkdtemp(join(tmpdir(), "clio-skill-eval-seed-"));
+	const workspace = await mkdtemp(join(tmpdir(), "clio-coder-skill-eval-seed-"));
 	let runWorkspaces: MaterializedSkillEvalWorkspaces | null = null;
 	try {
 		if (workspaceOverride !== null) await copyWorkspace(workspaceOverride, workspace);
@@ -570,7 +570,7 @@ export interface MaterializedSkillEvalWorkspaces {
  * cooperative model, not as an isolation guarantee.
  */
 async function armWorkspace(created: string[]): Promise<string> {
-	const root = await mkdtemp(join(tmpdir(), "clio-skill-eval-"));
+	const root = await mkdtemp(join(tmpdir(), "clio-coder-skill-eval-"));
 	created.push(root);
 	const workspace = join(root, "workspace");
 	await mkdir(workspace, { recursive: true });
@@ -578,7 +578,7 @@ async function armWorkspace(created: string[]): Promise<string> {
 }
 
 /** @internal Exported for contract tests. */
-export async function materializeSkillEvalWorkspaces(seedWorkspace: string): Promise<MaterializedSkillEvalWorkspaces> {
+async function materializeSkillEvalWorkspaces(seedWorkspace: string): Promise<MaterializedSkillEvalWorkspaces> {
 	const created: string[] = [];
 	try {
 		const baseline = await armWorkspace(created);
@@ -814,7 +814,7 @@ function loadsSkillBody(tool: string, args: unknown): boolean {
 }
 
 /** @internal Exported for contract tests. */
-export function parseRunStdout(stdout: string): { sessionId: string | null; transcript: string; finalText: string } {
+function parseRunStdout(stdout: string): { sessionId: string | null; transcript: string; finalText: string } {
 	let sessionId: string | null = null;
 	const lines: string[] = [];
 	let finalText = "";
@@ -938,7 +938,7 @@ function judgeVerdictAbsenceReason(judge: CapturedRun): string {
 }
 
 /** Exported for contracts tests. */
-export function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedRun): ScoredBullet[] {
+function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedRun): ScoredBullet[] {
 	const parsed = extractBulletsObject(judge.finalText) ?? extractBulletsObject(judge.transcript);
 	// No verdict object anywhere in the judge run. The scenario was not scored,
 	// which is a fact about the judge, so every bullet stays unmeasured rather
@@ -982,7 +982,7 @@ export function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedR
  * content, so this walks candidate `{` openers around the first "bullets" key
  * and balance-scans to the matching close brace.
  */
-export function extractBulletsObject(text: string): Record<string, unknown> | null {
+function extractBulletsObject(text: string): Record<string, unknown> | null {
 	const stripped = text.replace(/```(?:json)?/g, "");
 	const bulletsAt = stripped.indexOf('"bullets"');
 	if (bulletsAt < 0) return null;
@@ -1085,7 +1085,7 @@ function synthesizeArtifact(
 		evalId,
 		taskFile: evalsPath,
 		taskFileHash: contentHash,
-		clio: evalClioProvenance(),
+		clioCoder: evalClioProvenance(),
 		environment: evalEnvironmentProvenance(),
 		target: target ?? null,
 		model: null,

package/src/cli/targets.ts

@@ -51,10 +51,6 @@ Usage:
   clio-coder targets convert <id> --runtime <runtimeId>
   clio-coder targets remove <id>
   clio-coder targets rename <old> <new>
-
-Aliases:
-  --worker-target and --worker-model are accepted for --fleet-target and
-  --fleet-model, carried over from before the worker/fleet rename.
 `;
 
 const USE_USAGE =
@@ -205,8 +201,7 @@ export async function runTargetsCommand(args: ReadonlyArray<string>): Promise<nu
 	if (parsed.json) {
 		const settings = readSettings();
 		const candidateFor = (status: TargetStatus): string | null => {
-			const orchestratorModel =
-				settings.orchestrator?.target === status.target.id ? (settings.orchestrator?.model ?? null) : null;
+			const orchestratorModel = settings.chat?.target === status.target.id ? (settings.chat?.model ?? null) : null;
 			return orchestratorModel ?? status.target.defaultModel ?? null;
 		};
 		const rows = filtered.map((status) => {
@@ -250,11 +245,11 @@ function parseUseArgs(args: ReadonlyArray<string>): UseArgs | null {
 			parsed.backgroundModel = need();
 			continue;
 		}
-		if (arg === "--fleet-model" || arg === "--worker-model") {
+		if (arg === "--fleet-model") {
 			parsed.workerModel = need();
 			continue;
 		}
-		if (arg === "--fleet-target" || arg === "--worker-target") {
+		if (arg === "--fleet-target") {
 			parsed.workerTarget = need();
 			continue;
 		}
@@ -467,11 +462,11 @@ function runProfileRemove(args: ReadonlyArray<string>): number {
 	}
 	ensureClioState();
 	const settings = readSettings();
-	if (!settings.workers.profiles[parsed.name]) {
+	if (!settings.fleet.profiles[parsed.name]) {
 		printError(`no fleet profile named ${parsed.name}`);
 		return 1;
 	}
-	const boundAgents = Object.entries(settings.workers.agentBindings)
+	const boundAgents = Object.entries(settings.fleet.agentProfiles)
 		.filter(([, profileName]) => profileName === parsed.name)
 		.map(([agentId]) => agentId);
 	if (boundAgents.length > 0 && !parsed.force) {
@@ -510,23 +505,23 @@ function runProfileRename(args: ReadonlyArray<string>): number {
 	}
 	ensureClioState();
 	const settings = readSettings();
-	if (!settings.workers.profiles[parsed.oldName]) {
+	if (!settings.fleet.profiles[parsed.oldName]) {
 		printError(`no fleet profile named ${parsed.oldName}`);
 		return 1;
 	}
-	if (settings.workers.profiles[parsed.newName]) {
+	if (settings.fleet.profiles[parsed.newName]) {
 		printError(`fleet profile already exists: ${parsed.newName}`);
 		return 2;
 	}
 	let updatedBindings = 0;
 	updateSettings((fresh) => {
-		const profile = fresh.workers.profiles[parsed.oldName];
+		const profile = fresh.fleet.profiles[parsed.oldName];
 		if (!profile) return;
-		fresh.workers.profiles[parsed.newName] = profile;
-		delete fresh.workers.profiles[parsed.oldName];
-		for (const [agentId, profileName] of Object.entries(fresh.workers.agentBindings)) {
+		fresh.fleet.profiles[parsed.newName] = profile;
+		delete fresh.fleet.profiles[parsed.oldName];
+		for (const [agentId, profileName] of Object.entries(fresh.fleet.agentProfiles)) {
 			if (profileName !== parsed.oldName) continue;
-			fresh.workers.agentBindings[agentId] = parsed.newName;
+			fresh.fleet.agentProfiles[agentId] = parsed.newName;
 			updatedBindings += 1;
 		}
 	});
@@ -551,13 +546,13 @@ function runProfileBind(args: ReadonlyArray<string>): number {
 	}
 	ensureClioState();
 	const settings = readSettings();
-	if (settings.delegation.agents.some((agent) => agent.id === parsed.agentId)) {
+	if (settings.integrations.externalAgents.entries.some((agent) => agent.id === parsed.agentId)) {
 		printError(
 			`cannot bind ACP delegation agent '${parsed.agentId}' to a fleet profile; ACP agents use their own runner and ignore native target routing`,
 		);
 		return 1;
 	}
-	if (!settings.workers.profiles[parsed.profileName]) {
+	if (!settings.fleet.profiles[parsed.profileName]) {
 		process.stderr.write(
 			`${chalk.yellow("warning:")} fleet profile '${parsed.profileName}' is not configured; binding will resolve after the profile exists\n`,
 		);
@@ -581,12 +576,12 @@ function runProfileUnbind(args: ReadonlyArray<string>): number {
 	}
 	ensureClioState();
 	const settings = readSettings();
-	if (!settings.workers.agentBindings[parsed]) {
+	if (!settings.fleet.agentProfiles[parsed]) {
 		printError(`agent ${parsed} is not bound to a fleet profile`);
 		return 1;
 	}
 	updateSettings((fresh) => {
-		delete fresh.workers.agentBindings[parsed];
+		delete fresh.fleet.agentProfiles[parsed];
 	});
 	printOk(`unbound agent ${parsed}`);
 	return 0;
@@ -608,10 +603,10 @@ function runProfileBindings(args: ReadonlyArray<string>): number {
 	}
 	ensureClioState();
 	const settings = readSettings();
-	const rows = Object.entries(settings.workers.agentBindings)
+	const rows = Object.entries(settings.fleet.agentProfiles)
 		.sort(([a], [b]) => a.localeCompare(b))
 		.map(([agentId, profileName]) => {
-			const profile = settings.workers.profiles[profileName];
+			const profile = settings.fleet.profiles[profileName];
 			return {
 				agentId,
 				profile: profileName,
@@ -686,7 +681,7 @@ function runFleet(args: ReadonlyArray<string>, usage = "clio-coder targets fleet
 	ensureClioState();
 	const settings = readSettings();
 	const byId = new Map(settings.targets.map((target) => [target.id, target] as const));
-	const rows = Object.entries(settings.workers.profiles).map(([name, profile]) => {
+	const rows = Object.entries(settings.fleet.profiles).map(([name, profile]) => {
 		const target = profile.target ? byId.get(profile.target) : undefined;
 		return {
 			name,
@@ -782,7 +777,7 @@ function runConvert(args: ReadonlyArray<string>): number {
 		printOk(`target ${id} already uses runtime ${runtimeId}`);
 		return 0;
 	}
-	if (settings.orchestrator.target === id && !isOrchestratorEligibleRuntime(runtime)) {
+	if (settings.chat.target === id && !isOrchestratorEligibleRuntime(runtime)) {
 		printError(`cannot convert orchestrator target '${id}' to non-HTTP/native runtime '${runtime.id}'`);
 		return 1;
 	}
@@ -917,7 +912,7 @@ function tableWidths(rows: ReadonlyArray<TargetTableRow>, width: number): Target
  * cut to its width, marked the same way. Colour is dropped on those rows because
  * the ansi bytes would sit inside the cut; a wrapped row costs more than colour.
  */
-export function formatTargetTable(
+function formatTargetTable(
 	rows: ReadonlyArray<TargetTableRow>,
 	width: number,
 	paintHealth: (cell: string, row: TargetTableRow) => string = (cell) => cell,
@@ -972,7 +967,7 @@ function renderTable(providers: ProvidersContract, entries: ReadonlyArray<Target
 	}
 }
 
-export function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
+function targetTableRow(providers: ProvidersContract, status: TargetStatus): TargetTableRow {
 	const diagnostic = degradedHealthDiagnostic(status);
 	return {
 		id: status.target.id,
@@ -1034,7 +1029,7 @@ function capabilityBadges(caps: CapabilityFlags): string {
  * no states (cloud targets); "resident: none" when states are known and
  * nothing is loaded, so a cold box is distinguishable from an unknown one.
  */
-export function residentModelsSummary(states: TargetStatus["discoveredModelStates"]): string | null {
+function residentModelsSummary(states: TargetStatus["discoveredModelStates"]): string | null {
 	if (!states) return null;
 	const entries = Object.entries(states);
 	if (entries.length === 0) return null;
@@ -1049,7 +1044,7 @@ export function residentModelsSummary(states: TargetStatus["discoveredModelState
  * capability the target reported. Saying so is the difference between a number
  * a user can plan against and one they cannot.
  */
-export function formatContextWindow(
+function formatContextWindow(
 	status: Pick<TargetStatus, "capabilities" | "contextWindowProvenance"> &
 		Partial<Pick<TargetStatus, "target" | "discoveredModelStates">>,
 ): string {
@@ -1065,7 +1060,7 @@ export function formatContextWindow(
 		: `ctx ${window}`;
 }
 
-export function formatNotes(status: TargetStatus): string {
+function formatNotes(status: TargetStatus): string {
 	const parts: string[] = [];
 	const diagnostic = degradedHealthDiagnostic(status);
 	// The health diagnosis leads because gateway, context, and residency facts

package/src/cli/trace-inspect.ts

@@ -166,7 +166,7 @@ function processSummary(reader: TraceReader, runId: string): TraceInspectProcess
 }
 
 /** Pure payload builder, exported so the fixed contract is testable without subprocess capture. */
-export function traceInspectSnapshot(
+function traceInspectSnapshot(
 	now: () => number = Date.now,
 	databasePath: string = traceDatabasePath(clioStatePath()),
 ): TraceInspectSnapshot {

package/src/cli/trace.ts

@@ -3,7 +3,10 @@ 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";
 import {
+	assertTraceSelectOnly,
 	DEFAULT_TRACE_RETENTION_POLICY,
 	resolveTraceRetentionPolicy,
 	TRACE_EVENT_POLL_LIMIT,
@@ -23,12 +26,16 @@ const HELP = `Usage:
   clio-coder trace phases <runId> [--db PATH]
   clio-coder trace tail <runId> [--follow] [--db PATH]
   clio-coder trace procs <runId> [--db PATH]
+  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.
+Clio the subcommands above are the way in. They 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).
 Pruning keeps ${DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays} days and at most ${DEFAULT_TRACE_RETENTION_POLICY.maxBytes} bytes by default. Set
 CLIO_CODER_TRACE_RETENTION_DAYS or CLIO_CODER_TRACE_MAX_BYTES to change the automatic
 policy; prune flags override those values for one command.
@@ -96,7 +103,7 @@ function parseTraceArgs(args: string[]): ParsedTraceArgs {
 }
 
 /** Every subcommand `trace` answers to. Anything else is a usage error. */
-const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "prune", "sql", "ui"]);
+const TRACE_COMMANDS = new Set(["runs", "inspect", "phases", "tail", "procs", "code-steps", "prune", "sql", "ui"]);
 
 /** The subcommands whose first positional is a run id. */
 const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
@@ -118,6 +125,10 @@ function invocationError(command: string, runId: string | undefined): number | n
 		return 2;
 	}
 	if (TRACE_COMMANDS_NEEDING_RUN_ID.has(command) && !runId) return missingRunId(command);
+	if (command === "code-steps" && !runId) {
+		process.stderr.write("trace code-steps requires a fleet root id\n");
+		return 2;
+	}
 	return null;
 }
 
@@ -149,9 +160,23 @@ 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);
 
+	// 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
+	// never ran a code step or its records were pruned with the state tree.
+	if (command === "code-steps") return runTraceCodeSteps(runId ?? "", parsed.json);
+
 	// `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.
@@ -233,6 +258,41 @@ export async function runTraceCommand(args: string[]): Promise<number> {
 	}
 }
 
+/**
+ * Print every `CodeStepRecord` one fleet root wrote, oldest first. The record
+ * is the code step's stand-in for a receipt (argv, cwd, env names, exit code,
+ * duration, output digest, artifact paths), and until this command nothing
+ * read it back. JSON is the record verbatim; the table keeps the fields an
+ * operator scans for and leaves argv last because it is the widest.
+ */
+function runTraceCodeSteps(rootId: string, json: boolean): number {
+	let records: CodeStepRecord[];
+	try {
+		records = readCodeStepRecords(rootId);
+	} catch (error) {
+		process.stderr.write(`code-step records: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	if (json) {
+		process.stdout.write(`${JSON.stringify(records, null, 2)}\n`);
+		return 0;
+	}
+	if (records.length === 0) {
+		process.stdout.write(
+			`no code-step records for fleet root ${rootId} under ${codeStepDir(rootId)}. a record is written when a fleet plan runs a deterministic code step.\n`,
+		);
+		return 0;
+	}
+	process.stdout.write("EXIT  DURATION STARTED                  STEP                 COMMAND              ARGV\n");
+	for (const record of records) {
+		const exit = record.timedOut ? "timeout" : record.signal !== null ? `sig:${record.signal}` : String(record.exitCode);
+		process.stdout.write(
+			`${exit.padEnd(5)} ${`${record.durationMs}ms`.padStart(8)} ${record.startedAt.padEnd(24)} ${record.stepId.slice(0, 20).padEnd(20)} ${record.commandId.slice(0, 20).padEnd(20)} ${record.argv.join(" ")}\n`,
+		);
+	}
+	return 0;
+}
+
 function runTracePrune(parsed: ParsedTraceArgs): number {
 	let policy: ReturnType<typeof resolveTraceRetentionPolicy>;
 	try {
@@ -293,10 +353,10 @@ function formatEvent(row: TraceEventRow): string {
 }
 
 function printRuns(rows: TraceRunRow[]): void {
-	process.stdout.write("STATUS   STARTED                      TOKENS       COST RUN\n");
+	process.stdout.write("STATUS   SOURCE   STARTED                      TOKENS       COST RUN\n");
 	for (const row of rows) {
 		process.stdout.write(
-			`${row.status.padEnd(8)} ${row.started_at.padEnd(28)} ${formatNumber(row.total_tokens).padStart(8)} ${formatCost(row.total_cost_usd).padStart(10)} ${row.run_id}\n`,
+			`${row.status.padEnd(8)} ${row.source.padEnd(8)} ${row.started_at.padEnd(28)} ${formatNumber(row.total_tokens).padStart(8)} ${formatCost(row.total_cost_usd).padStart(10)} ${row.run_id}\n`,
 		);
 	}
 }
@@ -378,6 +438,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 => {