@iowarp/clio-coder 0.4.7 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.7",
+	"version": "0.4.8",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
@@ -57,7 +57,6 @@
 		".claude-plugin/marketplace.json",
 		"evals/**",
 		"docs/**/*.md",
-		"!docs/html/**",
 		"README.md",
 		"CHANGELOG.md",
 		"CONTRIBUTING.md",
@@ -72,8 +71,8 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "tsup && node --import tsx scripts/build-codewiki-asset.ts",
-		"dev": "tsup --watch",
+		"build": "node --import tsx scripts/build.ts && node --import tsx scripts/build-codewiki-asset.ts",
+		"dev": "node --import tsx scripts/build.ts --watch",
 		"clean": "rm -rf dist",
 		"typecheck": "tsc -p tsconfig.tests.json",
 		"format": "biome format --write .",
@@ -82,18 +81,21 @@
 		"pi:surface-snapshot": "node --import tsx scripts/pi-surface-diff.ts --write",
 		"test:file": "node --import tsx --import ./tests/harness/tmp-root.ts --test",
 		"pretest": "test -f dist/cli/index.js || pnpm run build",
-		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/smoke/*.test.ts",
-		"test:trace-viewer": "pnpm --filter @iowarp/clio-trace-viewer test",
-		"trace:ui": "node apps/trace-viewer/server.mjs",
-		"ci": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test && pnpm run test:trace-viewer",
-		"ci:release": "pnpm run ci && node scripts/check-release.mjs",
+		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test --test-concurrency=2 tests/contracts/*.test.ts tests/smoke/acp-boundary.test.ts tests/smoke/real-binary-boot.test.ts tests/smoke/process-lifecycle.test.ts",
+		"test:web": "pnpm --filter @iowarp/clio-coder-web test",
+		"ci": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test && pnpm run test:web",
+		"ci:release": "node scripts/release-candidate.mjs qualify",
 		"install:local": "bash scripts/install-local.sh",
 		"smoke:real-home": "bash scripts/smoke-real-home.sh",
-		"prepublishOnly": "CLIO_CODER_RELEASE_CONTEXT=publish pnpm run ci:release",
+		"prepublishOnly": "node scripts/release-candidate.mjs preflight",
 		"skills:pin": "node --import tsx scripts/pin-skills.ts",
 		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
 		"library:pin": "node --import tsx scripts/pin-library.ts",
-		"library:check": "node --import tsx scripts/pin-library.ts --check"
+		"library:check": "node --import tsx scripts/pin-library.ts --check",
+		"test:full": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/extended/*.test.ts tests/smoke/*.test.ts tests/extended-smoke/*.test.ts",
+		"test:package": "node --import tsx --import ./tests/harness/tmp-root.ts --test --test-concurrency=2 tests/smoke/installed-package.test.ts tests/smoke/native-call-timing.test.ts",
+		"release:preflight": "node scripts/release-candidate.mjs preflight",
+		"test:web:full": "pnpm --filter @iowarp/clio-coder-web test:full"
 	},
 	"optionalDependencies": {
 		"@anthropic-ai/claude-agent-sdk": "0.3.186"

package/src/cli/docs.ts

@@ -1,354 +1,91 @@
-import { spawn } from "node:child_process";
-import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
-import type { AddressInfo } from "node:net";
-import { relative, resolve } from "node:path";
-import chalk from "chalk";
+import { readdirSync } from "node:fs";
+import { basename, join } from "node:path";
 import { resolvePackageRoot } from "../core/package-root.js";
-import { printError, printHeader } from "./argv.js";
-
-// Human-facing viewer over the source-checkout HTML blueprints. It binds an ephemeral
-// static file server to 127.0.0.1 only, serves docs/html/index.html as the
-// menu plus the blueprint pages, prints the URL, and runs until SIGINT. It
-// uses only Node's built-in http and fs: zero new dependencies, no daemon, no
-// persisted state, no telemetry, and no external network. The static-path
-// resolution and the menu synthesis are pure functions so they unit-test
-// without binding a port.
-
-const HOST = "127.0.0.1";
+import { printError } from "./argv.js";
+import { runWebCommand } from "./web.js";
 
 const HELP = `clio-coder docs [topic] [--no-open]
 
-Serve Clio Coder's interactive HTML documentation locally and open it in a
-browser. The blueprints live in docs/html of a source checkout; the npm package
-ships the categorized Markdown reference tree under docs/ and excludes HTML.
-The server binds an ephemeral port on
-127.0.0.1, keeps no state, runs no daemon, and reaches no external network.
-Press Ctrl+C to stop it.
+Open the documentation in the Clio Coder web app. Pages, navigation and outlines
+are rendered from the same Markdown reference shipped with Clio.
 
 Arguments:
-  [topic]      deep-link a specific blueprint (for example: safety, configuration,
-               tools). Omit to open the documentation menu.
+  [topic]      a topic such as safety, configuration, or fleet_dispatch, or a
+               document path such as architecture/safety-model.md.
+               Omit to open the documentation map.
 
 Flags:
-  --no-open    do not launch a browser; just print the URL.
+  --no-open    print the private launch link without opening a browser.
   --help, -h   this message.
-`;
-
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-	".html": "text/html; charset=utf-8",
-	".htm": "text/html; charset=utf-8",
-	".css": "text/css; charset=utf-8",
-	".js": "text/javascript; charset=utf-8",
-	".mjs": "text/javascript; charset=utf-8",
-	".json": "application/json; charset=utf-8",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".webp": "image/webp",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".ico": "image/x-icon",
-	".woff": "font/woff",
-	".woff2": "font/woff2",
-	".ttf": "font/ttf",
-	".map": "application/json; charset=utf-8",
-	".txt": "text/plain; charset=utf-8",
-};
-
-export interface DocsMenuEntry {
-	/** Short deep-link key, for example `safety`. */
-	topic: string;
-	/** Real on-disk file name, for example `safety_blueprint.html`. */
-	file: string;
-	/** Human label, for example `Safety`. */
-	label: string;
-}
-
-/** Resolve the source-checkout HTML root. The npm package deliberately excludes it. */
-function resolveDocsHtmlDir(): string {
-	return resolve(resolvePackageRoot(), "docs", "html");
-}
 
-/** Content-type for a file path by extension. Pure. Defaults to octet-stream. */
-function contentTypeFor(filePath: string): string {
-	const dot = filePath.lastIndexOf(".");
-	if (dot === -1) return "application/octet-stream";
-	return CONTENT_TYPES[filePath.slice(dot).toLowerCase()] ?? "application/octet-stream";
-}
-
-/**
- * Map a request URL to a safe relative path under the html root. Pure: no disk
- * access. Strips the query and fragment, decodes percent-escapes, defaults `/`
- * to `index.html`, and rejects any traversal segment so a request can never
- * escape the served directory.
- */
-function resolveRequestPath(rawUrl: string): { ok: true; relative: string } | { ok: false; reason: string } {
-	const pathPart = (rawUrl.split(/[?#]/, 1)[0] ?? "").trim();
-	let decoded: string;
-	try {
-		decoded = decodeURIComponent(pathPart);
-	} catch {
-		return { ok: false, reason: "bad-request" };
-	}
-	if (decoded.includes("\0")) return { ok: false, reason: "forbidden" };
-	const segments = decoded.split(/[/\\]/).filter((segment) => segment.length > 0 && segment !== ".");
-	if (segments.length === 0) return { ok: true, relative: "index.html" };
-	for (const segment of segments) {
-		if (segment === "..") return { ok: false, reason: "forbidden" };
-	}
-	return { ok: true, relative: segments.join("/") };
-}
-
-function titleize(topic: string): string {
-	return topic
-		.split(/[-_]+/)
-		.filter((word) => word.length > 0)
-		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-		.join(" ");
-}
-
-/**
- * Synthesize the deep-linkable topic menu from a directory listing. Pure: takes
- * the file-name list, not the directory. `index.html` is the menu itself and is
- * excluded; a trailing `_blueprint` is stripped from the topic key.
- */
-function synthesizeMenu(fileNames: ReadonlyArray<string>): DocsMenuEntry[] {
-	const entries: DocsMenuEntry[] = [];
-	for (const name of fileNames) {
-		if (!name.toLowerCase().endsWith(".html")) continue;
-		if (name.toLowerCase() === "index.html") continue;
-		const topic = name.replace(/\.html$/i, "").replace(/_blueprint$/i, "");
-		entries.push({ topic, file: name, label: titleize(topic) });
-	}
-	entries.sort((a, b) => a.topic.localeCompare(b.topic));
-	return entries;
-}
-
-/**
- * Resolve a user-supplied `[topic]` to a real file name. Pure. Accepts the bare
- * topic (`safety`), the blueprint file stem (`safety_blueprint`), or a full
- * `.html` name, case-insensitively. Returns null when nothing matches.
- */
-function topicToFile(topic: string, fileNames: ReadonlyArray<string>): string | null {
-	const wanted = topic
-		.trim()
-		.toLowerCase()
-		.replace(/\.html$/i, "");
-	if (wanted.length === 0) return null;
-	for (const candidate of [`${wanted}.html`, `${wanted}_blueprint.html`]) {
-		const match = fileNames.find((name) => name.toLowerCase() === candidate);
-		if (match) return match;
-	}
-	const hit = synthesizeMenu(fileNames).find((entry) => entry.topic.toLowerCase() === wanted);
-	return hit ? hit.file : null;
-}
-
-function isWithin(child: string, parent: string): boolean {
-	const rel = relative(parent, child);
-	return rel === "" || (!rel.startsWith("..") && !rel.startsWith(`..${"/"}`) && !/^([A-Za-z]:)?[/\\]/.test(rel));
-}
-
-function listHtmlFiles(htmlDir: string): string[] {
-	try {
-		return readdirSync(htmlDir)
-			.filter((name) => name.toLowerCase().endsWith(".html"))
-			.sort((a, b) => a.localeCompare(b));
-	} catch {
-		return [];
-	}
-}
+Reuses your installed background app when available. Otherwise starts a local
+foreground web server on 127.0.0.1; press Ctrl+C to stop it. No background service
+is installed by this command. Your current directory does not affect the docs.
+`;
 
-/** Build the static request handler for one html root. */
-export function createDocsRequestHandler(htmlDir: string): (req: IncomingMessage, res: ServerResponse) => void {
-	const root = realpathSync(resolve(htmlDir));
-	return (req, res) => {
-		if (req.method !== "GET" && req.method !== "HEAD") {
-			res.writeHead(405, { "content-type": "text/plain; charset=utf-8", allow: "GET, HEAD" });
-			res.end("method not allowed");
-			return;
-		}
-		const resolved = resolveRequestPath(req.url ?? "/");
-		if (!resolved.ok) {
-			const status = resolved.reason === "forbidden" ? 403 : 400;
-			res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
-			res.end(resolved.reason);
-			return;
-		}
-		const requestedTarget = resolve(root, resolved.relative);
-		if (!isWithin(requestedTarget, root)) {
-			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-			res.end("forbidden");
-			return;
-		}
-		let size: number | null = null;
-		let target: string | null = null;
-		try {
-			target = realpathSync(requestedTarget);
-			if (!isWithin(target, root)) {
-				res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
-				res.end("forbidden");
-				return;
-			}
-			const stat = statSync(target);
-			if (stat.isFile()) size = stat.size;
-		} catch {
-			size = null;
-		}
-		if (size === null || target === null) {
-			res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-			res.end("not found");
-			return;
-		}
-		const headers = {
-			"content-type": contentTypeFor(target),
-			"content-length": String(size),
-			"cache-control": "no-store",
-		};
-		if (req.method === "HEAD") {
-			res.writeHead(200, headers);
-			res.end();
-			return;
-		}
-		res.writeHead(200, headers);
-		const stream = createReadStream(target);
-		stream.on("error", () => {
-			if (!res.writableEnded) res.end();
-		});
-		stream.pipe(res);
+const key = (value: string) => value.toLowerCase().replace(/_/g, "-");
+const route = (path: string) => `/docs/${path.split("/").map(encodeURIComponent).join("/")}`;
+
+/** Resolve only catalogued destinations; ambiguous basenames require a full path. */
+export function docsTopicRoute(topic: string | undefined, pages: readonly string[]): string | undefined {
+	if (topic === undefined) return "/docs";
+	if (!topic || /[\\\0?#]/.test(topic) || topic.startsWith("/") || topic.split("/").includes("..")) return;
+	const wanted = key(topic.replace(/^docs\//, ""));
+	const topics: Record<string, string> = {
+		safety: "architecture/safety-model.md",
+		configuration: "guide/configuration-and-targets.md",
+		trace: "architecture/trace-store.md",
 	};
-}
-
-export interface DocsServerHandle {
-	server: Server;
-	url: string;
-	port: number;
-	close(): Promise<void>;
-}
-
-export interface StartDocsServerOptions {
-	htmlDir: string;
-	/** Bind host. Defaults to 127.0.0.1 and is never widened. */
-	host?: string;
-	/** Bind port. Defaults to 0 (ephemeral). */
-	port?: number;
-}
-
-/** Start the viewer bound to 127.0.0.1 on an ephemeral port. */
-async function startDocsServer(options: StartDocsServerOptions): Promise<DocsServerHandle> {
-	const host = options.host ?? HOST;
-	const server = createServer(createDocsRequestHandler(options.htmlDir));
-	await new Promise<void>((resolveListen, rejectListen) => {
-		const onError = (err: Error): void => rejectListen(err);
-		server.once("error", onError);
-		server.listen(options.port ?? 0, host, () => {
-			server.removeListener("error", onError);
-			resolveListen();
-		});
-	});
-	const address = server.address() as AddressInfo;
-	const port = address.port;
-	return {
-		server,
-		port,
-		url: `http://${host}:${port}/`,
-		close: () => new Promise<void>((resolveClose) => server.close(() => resolveClose())),
+	const preferred = topics[wanted];
+	if (preferred && pages.includes(preferred)) return route(preferred);
+	const exact = pages.find((path) => key(path) === wanted || key(path.replace(/\.md$/i, "")) === wanted);
+	if (exact) return route(exact);
+	const name = wanted.replace(/\.md$/, "");
+	const exactNames = pages.filter((path) => key(basename(path).replace(/\.md$/i, "")) === name);
+	const matches = exactNames.length
+		? exactNames
+		: pages.filter((path) => key(basename(path).replace(/\.md$/i, "")).startsWith(`${name}-`));
+	const match = matches[0];
+	return matches.length === 1 && match ? route(match) : undefined;
+}
+
+function catalog(root: string) {
+	const pages: string[] = [];
+	const scan = (path: string) => {
+		for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+			const name = path ? `${path}/${entry.name}` : entry.name;
+			if (name === "html") continue;
+			if (entry.isDirectory()) scan(name);
+			else if (entry.isFile() && /\.md$/i.test(name)) pages.push(name);
+		}
 	};
+	scan("");
+	return pages;
 }
 
-function openBrowser(url: string): void {
-	const platform = process.platform;
-	const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-	const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-	try {
-		const child = spawn(command, args, { stdio: "ignore", detached: true });
-		child.on("error", () => {
-			// Best-effort: the printed URL is the fallback when no opener exists.
-		});
-		child.unref();
-	} catch {
-		// Best-effort: never fail the command because a browser could not launch.
-	}
-}
-
-export function waitForShutdown(): Promise<void> {
-	return new Promise((resolveShutdown) => {
-		const onSignal = (): void => {
-			process.removeListener("SIGINT", onSignal);
-			process.removeListener("SIGTERM", onSignal);
-			resolveShutdown();
-		};
-		process.once("SIGINT", onSignal);
-		process.once("SIGTERM", onSignal);
-	});
-}
-
-export async function runDocsCommand(args: ReadonlyArray<string> = []): Promise<number> {
+export async function runDocsCommand(args: readonly string[] = []): Promise<number> {
 	if (args.includes("--help") || args.includes("-h")) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	let noOpen = false;
-	const positionals: string[] = [];
-	for (const arg of args) {
-		if (arg === "--no-open") {
-			noOpen = true;
-			continue;
-		}
-		if (arg.startsWith("-")) {
-			printError(`unknown flag: ${arg}`);
-			process.stdout.write(HELP);
-			return 2;
-		}
-		positionals.push(arg);
-	}
-	if (positionals.length > 1) {
-		printError("docs accepts at most one [topic]");
-		process.stdout.write(HELP);
+	const positionals = args.filter((arg) => arg !== "--no-open");
+	const unknownFlag = positionals.find((arg) => arg.startsWith("-"));
+	if (unknownFlag || positionals.length > 1) {
+		printError(unknownFlag ? `unknown flag: ${unknownFlag}` : "docs accepts at most one [topic]");
 		return 2;
 	}
-
-	let htmlDir: string;
 	try {
-		htmlDir = resolveDocsHtmlDir();
-	} catch (err) {
-		printError(`could not resolve the docs HTML root: ${err instanceof Error ? err.message : String(err)}`);
-		return 1;
-	}
-	const files = listHtmlFiles(htmlDir);
-	if (files.length === 0) {
-		printError(`no HTML docs at ${htmlDir}`);
-		process.stdout.write(
-			`  the npm package ships only the categorized Markdown reference tree: ${resolve(resolvePackageRoot(), "docs")}\n` +
-				"  the interactive blueprints are in a source checkout and at https://github.com/iowarp/clio-coder/tree/main/docs/html\n",
-		);
-		return 1;
-	}
-
-	let landing = "index.html";
-	const topic = positionals[0];
-	if (topic !== undefined) {
-		const file = topicToFile(topic, files);
-		if (!file) {
-			printError(`unknown docs topic: ${topic}`);
-			const topics = synthesizeMenu(files).map((entry) => entry.topic);
-			if (topics.length > 0) process.stdout.write(`  available topics: ${topics.join(", ")}\n`);
+		const pages = catalog(join(resolvePackageRoot(), "docs"));
+		const path = docsTopicRoute(positionals[0], pages);
+		if (!path) {
+			printError(
+				`Unknown or ambiguous docs topic: ${positionals[0]}. Run clio-coder docs to browse the documentation map.`,
+			);
 			return 2;
 		}
-		landing = file;
+		return runWebCommand(["--path", path, "--reuse-background", args.includes("--no-open") ? "--no-open" : "--open"]);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : "Could not open the documentation.");
+		return 1;
 	}
-
-	const handle = await startDocsServer({ htmlDir });
-	const landingUrl = landing === "index.html" ? handle.url : `${handle.url}${landing}`;
-	printHeader("Clio docs viewer");
-	process.stdout.write(`  serving HTML root ${htmlDir}\n`);
-	process.stdout.write(`  open ${chalk.cyan(landingUrl)}\n`);
-	process.stdout.write("  bound to 127.0.0.1 only: no external network, no daemon, no state.\n");
-	process.stdout.write("  press Ctrl+C to stop.\n");
-	if (!noOpen) openBrowser(landingUrl);
-
-	await waitForShutdown();
-	await handle.close();
-	process.stdout.write("docs viewer stopped.\n");
-	return 0;
 }

package/src/cli/index.ts

@@ -29,6 +29,7 @@ science. CLIO stands for Context Layer for Input/Output, named for the Greek mus
 
 Usage:
   clio-coder                      start interactive repository chat
+  clio-coder web [--open]         start the browser application
   clio-coder acp                  serve Clio as an ACP v1 agent over stdio
   clio-coder --acp                alias for clio-coder acp
   clio-coder run [flags] <task>   run one headless main-agent turn
@@ -75,7 +76,7 @@ Usage:
   clio-coder tools list|status|install|remove <id>  pinned external programs Clio can drive
   clio-coder interop inspect --json  detected external coding agents and how far each one is wired
   clio-coder panes install|theme  install the pane multiplexer (alias for 'tools install herdr'), or print Clio's theme as a herdr block
-  clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
+  clio-coder docs [topic]         open documentation in the web app (--no-open to print the launch link)
   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'
@@ -260,6 +261,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["library", async (subArgs) => (await import("./library.js")).runLibraryCommand(subArgs)],
 	["tasks", async (subArgs) => (await import("./tasks.js")).runTasksCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
+	["web", async (subArgs) => (await import("./web.js")).runWebCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],
 	["export", async (subArgs) => (await import("./share.js")).runExportCommand(subArgs)],

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)