@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/cli/skills.ts

@@ -1,495 +1,48 @@
 import { resolve } from "node:path";
-import {
-	discoverMarketplaceSkills,
-	installSkill,
-	loadSkills,
-	type MarketplaceSkill,
-	modelVisibleSkills,
-	type ResourceDiagnostic,
-	resolveMarketplaceShaping,
-	type Skill,
-	type SkillUpdateReport,
-	skillCatalogValidity,
-	updateSkills,
-} from "../domains/resources/index.js";
-import { formatColumns, printError, printOk } from "./shared.js";
-
-const HELP = `clio-coder skills <command>
-
-Manage local Clio and Agent Skills-compatible skills.
-
-Commands:
-  clio-coder skills list [--json] [--all]
-  clio-coder skills inventory --json
-  clio-coder skills search <query> [--json]
-  clio-coder skills inspect <name> [--json]
-  clio-coder skills validate [path] [--json]
-  clio-coder skills install <name|path|github-url>... [--user|--project] [--name <name>] [--force]
-  clio-coder skills install --category <category> [--user|--project] [--force]
-  clio-coder skills update <name> | --all [--force]
-  clio-coder skills sync [--force]
-  clio-coder skills eval <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]
-
-inventory is the fixed machine-readable read a GUI host may run. Unlike a bare
-list it reports every installed skill, not only the ones the model may load, and
-says which are which; it carries no body, path, hash, or install URL.
-
-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
-marketplace entry. Several sources install in one command, and --category
-installs every marketplace skill in one catalog group (git, research, ...).
-
-eval (experimental) executes the skill's evals.md RED-GREEN scenarios: per
-scenario a baseline headless run without the skill, a treatment run with it,
-and a judge run scoring each Expected bullet from the transcripts. Exit is 1
-when a treatment bullet fails and 3 when a scenario was never measured (a
-truncated or unparseable judge response scores no bullet, which is not a skill
-failure). Every arm runs hermetic: the network tool plane is stripped from the
-child runs unless you pass --allow-network. The baseline and treatment arms run
-at autonomy full-auto in per-run disposable workspaces, because a headless run
-has no operator to approve anything and a gated arm measures the harness rather
-than the skill. --scenario takes a full id as written
-in evals.md, whose prefix is per-skill (S1, but also D2 in clio-dev, T3 in
-clio-test, F1 in find-skills, H2 in context-handoff), or a bare number that
-selects that scenario whatever its prefix. --json emits one JSONL row per
-(scenario, bullet) with schema: "experimental". --workspace copies an existing
-checkout into a throwaway seed; the source checkout is not mutated. Fixture
-commands declared in evals.md are real shell run in that seed; they only execute
-with --trust-fixtures, after you have reviewed the evals.md.
-`;
-
-type SkillInstallScope = "user" | "project";
-
-interface Parsed {
-	command?: string;
-	positional: string[];
-	json: boolean;
-	all: boolean;
-	help: boolean;
-	force: boolean;
-	name?: string;
-	category?: string;
-	scope?: SkillInstallScope;
-	scenario?: string;
-	target?: string;
-	workspace?: string;
-	timeoutSeconds?: number;
-	trustFixtures: boolean;
-	allowNetwork: boolean;
-}
-
-function parse(argv: ReadonlyArray<string>): Parsed {
-	const out: Parsed = {
-		positional: [],
-		json: false,
-		all: false,
-		help: false,
-		force: false,
-		trustFixtures: false,
-		allowNetwork: false,
-	};
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i];
-		if (arg === undefined) continue;
-		if (!out.command && !arg.startsWith("-")) {
-			out.command = arg;
-			continue;
-		}
-		switch (arg) {
-			case "--json":
-				out.json = true;
-				break;
-			case "--all":
-				out.all = true;
-				break;
-			case "--force":
-				out.force = true;
-				break;
-			case "--trust-fixtures":
-				out.trustFixtures = true;
-				break;
-			case "--allow-network":
-				out.allowNetwork = true;
-				break;
-			case "--name": {
-				const value = argv[i + 1];
-				if (!value || value.startsWith("-")) throw new Error("--name requires a value");
-				out.name = value;
-				i++;
-				break;
-			}
-			case "--category": {
-				const value = argv[i + 1];
-				if (!value || value.startsWith("-")) throw new Error("--category requires a value");
-				out.category = value;
-				i++;
-				break;
-			}
-			case "--scenario": {
-				const value = argv[i + 1];
-				if (!value || value.startsWith("-")) throw new Error("--scenario requires a value");
-				out.scenario = value;
-				i++;
-				break;
-			}
-			case "--target": {
-				const value = argv[i + 1];
-				if (!value || value.startsWith("-")) throw new Error("--target requires a value");
-				out.target = value;
-				i++;
-				break;
-			}
-			case "--workspace": {
-				const value = argv[i + 1];
-				if (!value || value.startsWith("-")) throw new Error("--workspace requires a value");
-				out.workspace = value;
-				i++;
-				break;
-			}
-			case "--timeout": {
-				const value = argv[i + 1];
-				const seconds = value === undefined ? Number.NaN : Number.parseInt(value, 10);
-				if (!Number.isInteger(seconds) || seconds <= 0) throw new Error("--timeout requires a positive integer");
-				out.timeoutSeconds = seconds;
-				i++;
-				break;
-			}
-			case "--user":
-				if (out.scope && out.scope !== "user") throw new Error("--user and --project are mutually exclusive");
-				out.scope = "user";
-				break;
-			case "--project":
-				if (out.scope && out.scope !== "project") throw new Error("--user and --project are mutually exclusive");
-				out.scope = "project";
-				break;
-			case "--help":
-			case "-h":
-				out.help = true;
-				break;
-			default:
-				if (arg.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
-				out.positional.push(arg);
-		}
-	}
-	return out;
-}
-
-function printUpdateReports(reports: ReadonlyArray<SkillUpdateReport>): number {
-	if (reports.length === 0) {
-		process.stdout.write("skills: nothing to update (no installed skills with source-url provenance)\n");
-		return 0;
-	}
-	for (const report of reports) {
-		const detail = report.detail ? ` (${report.detail})` : "";
-		process.stdout.write(`${report.name}: ${report.status}${detail}\n`);
-	}
-	return reports.some((report) => report.status === "error") ? 1 : 0;
-}
-
-function printDiagnostics(diagnostics: ReadonlyArray<ResourceDiagnostic>): void {
-	for (const diag of diagnostics) {
-		const detail = diag.path ? `${diag.message}: ${diag.path}` : diag.message;
-		if (diag.type === "error") printError(detail);
-		else process.stderr.write(`warning: ${detail}\n`);
-	}
-}
-
-function skillRows(skills: ReadonlyArray<Skill>): string[][] {
-	return skills.map((skill) => [
-		skill.name,
-		skill.scope,
-		skill.source,
-		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,
-	]);
-}
-
-function printList(skills: ReadonlyArray<Skill>): void {
-	if (skills.length === 0) {
-		process.stdout.write("skills: none\n");
-		return;
-	}
-	process.stdout.write(
-		formatColumns([["name", "scope", "source", "trust", "invoke", "hash", "by", "description"], ...skillRows(skills)]),
-	);
-}
-
-function printInspect(skill: Skill): void {
-	process.stdout.write(`name: ${skill.name}\n`);
-	process.stdout.write(`description: ${skill.description}\n`);
-	process.stdout.write(`path: ${skill.filePath}\n`);
-	process.stdout.write(`baseDir: ${skill.baseDir}\n`);
-	process.stdout.write(`scope: ${skill.scope}\n`);
-	process.stdout.write(`source: ${skill.source}\n`);
-	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`);
-	}
-}
-
-function formatMarketplaceOrigin(skill: MarketplaceSkill): string {
-	const parts = [skill.origin === "catalog" ? "catalog" : "index"];
-	if (skill.version) parts.push(`v${skill.version}`);
-	if (skill.audit) parts.push(`audit: ${skill.audit}`);
-	return parts.join(", ");
-}
-
-function validationLoad(pathArg: string | undefined): ReturnType<typeof loadSkills> {
-	if (!pathArg) return loadSkills({ cwd: process.cwd() });
-	return loadSkills({ disableDiscovery: true, explicitSkillPaths: [resolve(pathArg)] });
-}
-
-export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<number> {
-	// Routed before the shared parser so the fixed read stays exactly fixed: no
-	// skills flag can reach it, and no flag it does not name can be spent on it.
-	if (argv[0] === "inventory") {
-		const { runSkillsInventory } = await import("./skills-inventory.js");
-		return runSkillsInventory(argv.slice(1));
-	}
-	let parsed: Parsed;
-	try {
-		parsed = parse(argv);
-	} catch (error) {
-		printError(error instanceof Error ? error.message : String(error));
-		process.stderr.write(HELP);
+import { readSettings } from "../core/config.js";
+import { loadSkills, modelVisibleSkills, skillCatalogValidity } from "../domains/resources/index.js";
+import { formatColumns } from "./shared.js";
+
+/** Runtime discovery is a read surface of the library; package mutations live in library.ts. */
+export function runSkillsRead(args: ReadonlyArray<string>): number {
+	const command = args[0];
+	const positional = args.slice(1).filter((arg) => !arg.startsWith("-"));
+	const json = args.includes("--json");
+	if (
+		(command !== "list" && command !== "validate") ||
+		args.slice(1).some((arg) => arg.startsWith("-") && arg !== "--json" && arg !== "--all") ||
+		positional.length > (command === "list" ? 0 : 1)
+	) {
+		process.stderr.write("usage: clio-coder library skills [--all] [--json], or library validate <SKILL.md> [--json]\n");
 		return 2;
 	}
-	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() });
-			const skills = parsed.all ? list.items : modelVisibleSkills(list.items);
-			if (parsed.json) process.stdout.write(`${JSON.stringify({ skills, diagnostics: list.diagnostics }, null, 2)}\n`);
-			else {
-				printList(skills);
-				printDiagnostics(list.diagnostics);
-			}
-			return list.diagnostics.some((diag) => diag.type === "error") ? 1 : 0;
-		}
-		case "search": {
-			const query = parsed.positional.join(" ").trim().toLowerCase();
-			if (query.length === 0) {
-				process.stderr.write("usage: clio-coder skills search <query> [--json]\n");
-				return 2;
-			}
-			const list = loadSkills({ cwd: process.cwd() });
-			const discovery = discoverMarketplaceSkills({ cwd: process.cwd() });
-			const installedNames = new Set(list.items.map((skill) => skill.name));
-			const matchesQuery = (name: string, description: string): boolean =>
-				name.toLowerCase().includes(query) || description.toLowerCase().includes(query);
-			const installed = list.items.filter((skill) => matchesQuery(skill.name, skill.description));
-			// A catalog group name is the other thing an operator types here, and
-			// `install --category git` treats it as a real field: without this,
-			// `search git` answered with the skills whose prose mentions git and
-			// omitted every member of skills/git/.
-			const marketplace = discovery.skills.filter(
-				(skill) =>
-					!installedNames.has(skill.name) &&
-					(matchesQuery(skill.name, skill.description) || skill.category?.toLowerCase() === query),
-			);
-			// Search must report anything that made the result incomplete: loader
-			// diagnostics (like list) plus marketplace discovery diagnostics, so a
-			// broken index looks different from a skill that does not exist.
-			const exitCode = list.diagnostics.some((diag) => diag.type === "error") ? 1 : 0;
-			if (parsed.json) {
-				process.stdout.write(
-					`${JSON.stringify(
-						{ query, installed, marketplace, diagnostics: list.diagnostics, marketplaceDiagnostics: discovery.diagnostics },
-						null,
-						2,
-					)}\n`,
-				);
-				return exitCode;
-			}
-			if (installed.length > 0) {
-				process.stdout.write("installed:\n");
-				for (const skill of installed) {
-					process.stdout.write(`  ${skill.name.padEnd(24)} ${skill.description}  (${skill.scope}/${skill.source})\n`);
-				}
-			}
-			if (marketplace.length > 0) {
-				process.stdout.write("marketplace (clio-coder skills install <name>):\n");
-				for (const skill of marketplace) {
-					process.stdout.write(`  ${skill.name.padEnd(24)} ${skill.description}  (${formatMarketplaceOrigin(skill)})\n`);
-				}
-			}
-			if (installed.length === 0 && marketplace.length === 0) {
-				process.stdout.write(`skills: no matches for "${query}"\n`);
-			}
-			printDiagnostics(list.diagnostics);
-			for (const message of discovery.diagnostics) process.stderr.write(`warning: ${message}\n`);
-			return exitCode;
-		}
-		case "inspect": {
-			const name = parsed.positional[0];
-			if (!name || parsed.positional.length !== 1) {
-				process.stderr.write("usage: clio-coder skills inspect <name> [--json]\n");
-				return 2;
-			}
-			const list = loadSkills({ cwd: process.cwd() });
-			const skill = list.items.find((entry) => entry.name === name);
-			if (!skill) {
-				// inspect reads an installed skill's loaded record, which a marketplace
-				// entry does not have yet. Saying "unknown skill" about a name `search`
-				// just listed denies the skill exists; name the state and the one
-				// command that changes it.
-				const available = discoverMarketplaceSkills({ cwd: process.cwd() }).skills.some((entry) => entry.name === name);
-				printError(
-					available
-						? `skill not installed: ${name} (available in the marketplace; install it with: clio-coder skills install ${name})`
-						: `unknown skill: ${name}`,
-				);
-				return 1;
-			}
-			if (parsed.json) process.stdout.write(`${JSON.stringify({ skill }, null, 2)}\n`);
-			else printInspect(skill);
-			return 0;
-		}
-		case "validate": {
-			const pathArg = parsed.positional[0];
-			if (parsed.positional.length > 1) {
-				process.stderr.write("usage: clio-coder skills validate [path] [--json]\n");
-				return 2;
-			}
-			const list = validationLoad(pathArg);
-			// The rule itself lives in the loader, because `skills inspect --json`
-			// reports the same verdict to a GUI host and a verdict that drifts
-			// between the terminal and the browser is worse than no verdict.
-			const { ok } = skillCatalogValidity(list);
-			if (parsed.json) {
-				process.stdout.write(`${JSON.stringify({ ok, skills: list.items, diagnostics: list.diagnostics }, null, 2)}\n`);
-			} else {
-				printDiagnostics(list.diagnostics);
-				process.stdout.write(`${ok ? "valid" : "invalid"}: ${list.items.length} skill(s)\n`);
-			}
-			return ok ? 0 : 1;
-		}
-		case "install": {
-			let sources = parsed.positional;
-			if (parsed.category !== undefined) {
-				if (sources.length > 0) {
-					process.stderr.write("--category installs a whole catalog group; do not also name skills\n");
-					return 2;
-				}
-				const grouped = discoverMarketplaceSkills().skills.filter((skill) => skill.category === parsed.category);
-				if (grouped.length === 0) {
-					printError(`no marketplace skills in category "${parsed.category}"`);
-					return 1;
-				}
-				sources = grouped.map((skill) => skill.name);
-			}
-			if (sources.length === 0) {
-				process.stderr.write(
-					"usage: clio-coder skills install <name|path|github-url>... [--user|--project] [--name <name>] [--force]\n" +
-						"       clio-coder skills install --category <category> [--user|--project] [--force]\n",
-				);
-				return 2;
-			}
-			// --name renames the destination directory, which can only mean one
-			// thing for one source; silently applying it to a list would install
-			// every skill over the same directory.
-			if (parsed.name !== undefined && sources.length !== 1) {
-				process.stderr.write("--name applies to a single skill; install them one at a time to rename\n");
-				return 2;
-			}
-			let failed = 0;
-			for (const source of sources) {
-				try {
-					const result = installSkill({
-						source,
-						scope: parsed.scope ?? "project",
-						force: parsed.force,
-						...(parsed.name ? { name: parsed.name } : {}),
-					});
-					printOk(`installed ${result.scope} skill ${result.name} at ${result.path}`);
-					for (const warning of result.warnings) process.stderr.write(`warning: ${warning}\n`);
-				} catch (err) {
-					failed += 1;
-					printError(err instanceof Error ? err.message : String(err));
-				}
-			}
-			if (failed === sources.length) return 1;
-			process.stdout.write("audit is set to unknown; review the skill and set audit: pass yourself\n");
-			return failed > 0 ? 1 : 0;
-		}
-		case "update": {
-			const name = parsed.positional[0];
-			if ((!name && !parsed.all) || parsed.positional.length > 1) {
-				process.stderr.write("usage: clio-coder skills update <name> | --all [--force]\n");
-				return 2;
-			}
-			try {
-				const reports = updateSkills({
-					...(name ? { name } : { all: true }),
-					force: parsed.force,
-					resolveShaping: resolveMarketplaceShaping(),
-				});
-				return printUpdateReports(reports);
-			} catch (err) {
-				printError(err instanceof Error ? err.message : String(err));
-				return 1;
-			}
-		}
-		case "sync": {
-			try {
-				return printUpdateReports(
-					updateSkills({ all: true, force: parsed.force, resolveShaping: resolveMarketplaceShaping() }),
-				);
-			} catch (err) {
-				printError(err instanceof Error ? err.message : String(err));
-				return 1;
-			}
-		}
-		case "eval": {
-			const name = parsed.positional[0];
-			if (!name || parsed.positional.length !== 1) {
-				process.stderr.write(
-					"usage: clio-coder skills eval <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]\n",
-				);
-				return 2;
-			}
-			// Dynamic import keeps the eval lane (evidence + eval domains) out of
-			// the chunk that clio-coder skills list/search load.
-			const { runSkillsEvalCommand } = await import("./skills-eval.js");
-			return runSkillsEvalCommand(name, {
-				json: parsed.json,
-				trustFixtures: parsed.trustFixtures,
-				allowNetwork: parsed.allowNetwork,
-				...(parsed.scenario !== undefined ? { scenario: parsed.scenario } : {}),
-				...(parsed.target !== undefined ? { target: parsed.target } : {}),
-				...(parsed.workspace !== undefined ? { workspace: parsed.workspace } : {}),
-				...(parsed.timeoutSeconds !== undefined ? { timeoutSeconds: parsed.timeoutSeconds } : {}),
-			});
-		}
-		default:
-			printError(`unknown skills command: ${parsed.command}`);
-			process.stderr.write(HELP);
-			return 2;
-	}
+	const list = loadSkills(
+		command === "validate" && positional[0]
+			? { disableDiscovery: true, explicitSkillPaths: [resolve(positional[0])] }
+			: { cwd: process.cwd(), trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports },
+	);
+	const skills = command === "validate" || args.includes("--all") ? list.items : modelVisibleSkills(list.items);
+	const valid =
+		command === "validate" ? skillCatalogValidity(list).ok : !list.diagnostics.some((diag) => diag.type === "error");
+	if (json)
+		process.stdout.write(
+			`${JSON.stringify({ ...(command === "validate" ? { ok: valid } : {}), skills, diagnostics: list.diagnostics }, null, 2)}\n`,
+		);
+	else {
+		process.stdout.write(
+			formatColumns([
+				["name", "scope", "source", "trust", "invoke", "description"],
+				...skills.map((skill) => [
+					skill.name,
+					skill.scope,
+					skill.source,
+					skill.trusted ? "trusted" : "untrusted",
+					skill.disableModelInvocation ? "manual" : "model",
+					skill.description,
+				]),
+			]),
+		);
+		for (const diagnostic of list.diagnostics) process.stderr.write(`${diagnostic.type}: ${diagnostic.message}\n`);
+	}
+	return valid ? 0 : 1;
 }

package/src/cli/trace.ts

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