@tangle-network/agent-runtime 0.337.2 → 0.339.0

package/dist/tui/bin.js

@@ -1,5 +1,715 @@
 #!/usr/bin/env node
-import { n as runTopApp } from "../top-app-BaMw1W2z.js";
+import { _ as supervisorRunsRoot, n as cancelRun, s as cancelWorker, x as writeWorkerSteer } from "../run-cancellation-C9oL62sW.js";
+import { a as parseTime, i as parseSpend, n as loadTopSnapshot, o as totalSpend, r as numberValue, t as aggregateSnapshot } from "../top-snapshot-CbZE1JsU.js";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+//#region src/tui/top-frame.ts
+const ansiPattern = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const colors = {
+	reset: "\x1B[0m",
+	dim: "\x1B[2m",
+	bold: "\x1B[1m",
+	red: "\x1B[31m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	blue: "\x1B[34m",
+	magenta: "\x1B[35m",
+	cyan: "\x1B[36m",
+	white: "\x1B[37m",
+	inverse: "\x1B[7m"
+};
+/**
+* Render one snapshot, returning the frame together with the row→entity map a mouse click resolves
+* against. The layout is the only thing that knows which row is which run or worker, so emitting it
+* alongside the text is what keeps click handling out of the renderer.
+*/
+function renderTopFrameWithLayout(snapshot, options = {}) {
+	const width = Math.max(88, options.width ?? 128);
+	const height = Math.max(24, options.height ?? 42);
+	const color = options.color ?? false;
+	const focus = options.focus ?? "supervisors";
+	const mode = options.mode ?? "overview";
+	const selectedSupervisor = selectSupervisor(snapshot, options.selectedSupervisorId);
+	const selectedWorker = selectedSupervisor ? selectWorker(selectedSupervisor, options.selectedWorkerId) : void 0;
+	const targets = [];
+	const lines = [];
+	const push = (line = "", target) => {
+		if (lines.length >= height) return;
+		if (target) targets.push({
+			row: lines.length,
+			...target
+		});
+		lines.push(fitAnsi(line, width));
+	};
+	const aggregate = aggregateSnapshot(snapshot);
+	push(`${paint("SUPERVISOR TOP", "bold", color)} ${paint(snapshot.root, "dim", color)}  runs ${aggregate.supervisors}  workers ${aggregate.workers}  live ${aggregate.running}  done ${aggregate.done}  down ${aggregate.down}  ${formatMoney(aggregate.usd)}  tok ${formatTokens(aggregate.tokensInput)}/${formatTokens(aggregate.tokensOutput)}`);
+	push(`${paint("keys", "dim", color)} up/down select  left/right run  tab focus  enter detail  o overview  l log  s steer  c cancel  mouse  q quit`);
+	if (options.notice) push(paint(options.notice, "yellow", color));
+	if (snapshot.completeness === "partial") push(paint(`partial snapshot: ${snapshot.diagnostics.length} source${snapshot.diagnostics.length === 1 ? "" : "s"} skipped or truncated; runs loaded ${snapshot.loaded}/${snapshot.discovered}`, "yellow", color));
+	if (options.steerInput?.active) push(renderSteerInput(options.steerInput, width, color));
+	push(rule(width, color));
+	if (snapshot.supervisors.length === 0) {
+		if (snapshot.discovered > 0) {
+			push(paint("NO READABLE SUPERVISORS", "yellow", color));
+			push(`${snapshot.discovered} run director${snapshot.discovered === 1 ? "y" : "ies"} found under ${supervisorRunsRoot(snapshot.root)}, none readable`);
+		} else {
+			push(paint("NO SUPERVISORS", "yellow", color));
+			push(`No run state under ${supervisorRunsRoot(snapshot.root)}`);
+		}
+		push(`A run appears here once its driver writes state.json; re-point with: agent-runtime-top <root>`);
+		return {
+			frame: `${lines.join("\n")}\n`,
+			targets
+		};
+	}
+	push(sectionTitle("SUPERVISORS", focus === "supervisors", color));
+	push(`  id                    status       workers       spend        tok in/out       latency      task`);
+	for (const supervisor of snapshot.supervisors.slice(0, 9)) {
+		const selected = supervisor.id === selectedSupervisor?.id;
+		const status = statusText(supervisor.status, color);
+		const pointer = selected ? paint(">", "cyan", color) : " ";
+		const rowFocus = selected && focus === "supervisors" ? "inverse" : void 0;
+		const workerSummary = `${supervisor.totals.running}/${supervisor.totals.workers} live`;
+		const task = compact(supervisor.task, 34);
+		const line = `${pointer} ${pad(supervisor.id, 21)} ${pad(status, 12)} ${pad(workerSummary, 13)} ${pad(formatMoney(supervisor.totals.usd), 12)} ${pad(`${formatTokens(supervisor.totals.tokensInput)}/${formatTokens(supervisor.totals.tokensOutput)}`, 16)} ${pad(formatDuration(supervisor.totals.latencyMs), 12)} ${task}`;
+		push(rowFocus ? paint(line, rowFocus, color) : line, {
+			kind: "supervisor",
+			id: supervisor.id
+		});
+	}
+	if (!selectedSupervisor) return {
+		frame: `${lines.join("\n")}\n`,
+		targets
+	};
+	push();
+	push(sectionTitle(`WORKERS ${selectedSupervisor.id}`, focus === "workers", color));
+	push(`  id           state        runtime    latency      cost        tok in/out       score     detail`);
+	for (const worker of selectedSupervisor.workers.slice(0, 12)) {
+		const selected = worker.id === selectedWorker?.id;
+		const pointer = selected ? paint(">", "cyan", color) : " ";
+		const rowFocus = selected && focus === "workers" ? "inverse" : void 0;
+		const score = worker.verdict ?? (worker.status === "done" ? "done" : worker.status);
+		const detail = worker.reason ?? worker.outRef ?? worker.parent ?? "";
+		const spend = totalSpend(worker);
+		const line = `${pointer} ${pad(worker.label, 12)} ${pad(statusText(worker.status, color), 12)} ${pad(worker.runtime ?? "-", 10)} ${pad(formatDuration(worker.latencyMs), 12)} ${pad(formatMoney(spend.usd), 11)} ${pad(`${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`, 16)} ${pad(compact(score, 9), 10)} ${compact(detail, 30)}`;
+		push(rowFocus ? paint(line, rowFocus, color) : line, {
+			kind: "worker",
+			id: worker.id,
+			supervisorId: selectedSupervisor.id
+		});
+	}
+	if (selectedSupervisor.workers.length === 0) push("  no workers spawned yet");
+	push();
+	push(sectionTitle("OBSERVABILITY", false, color));
+	for (const line of renderStatusBars(selectedSupervisor, width, color)) push(line);
+	push();
+	for (const line of renderCostBars(selectedSupervisor, width, color)) push(line);
+	push();
+	for (const line of renderTokenBars(selectedSupervisor, width, color)) push(line);
+	push();
+	for (const line of renderLatencyHistogram(selectedSupervisor, width, color)) push(line);
+	push();
+	if (mode === "log") {
+		push(sectionTitle("JOURNAL TAIL", false, color));
+		for (const line of renderJournalTail(selectedSupervisor, width, color)) push(line);
+	} else {
+		push(sectionTitle(mode === "detail" ? "DETAIL" : "RUN SUMMARY", false, color));
+		for (const line of renderDetail(selectedSupervisor, selectedWorker, mode, width, color)) push(line);
+	}
+	return {
+		frame: `${lines.join("\n")}\n`,
+		targets
+	};
+}
+function renderStatusBars(supervisor, width, color) {
+	const total = Math.max(1, supervisor.totals.workers);
+	const barWidth = Math.max(12, Math.min(28, width - 58));
+	return [`status  ${pad("running", 9)} ${bar(supervisor.totals.running, total, barWidth, "#", color, "yellow")} ${supervisor.totals.running}   ${pad("done", 5)} ${bar(supervisor.totals.done, total, barWidth, "#", color, "green")} ${supervisor.totals.done}   ${pad("down", 5)} ${bar(supervisor.totals.down, total, barWidth, "#", color, "red")} ${supervisor.totals.down}`];
+}
+function renderCostBars(supervisor, width, color) {
+	const workers = supervisor.workers.map((worker) => ({
+		worker,
+		spend: totalSpend(worker)
+	})).sort((a, b) => b.spend.usd - a.spend.usd).slice(0, 6);
+	const maxUsd = Math.max(1e-6, ...workers.map((row) => row.spend.usd), supervisor.driverSpend.usd);
+	const out = [`cost   total ${formatMoney(supervisor.totals.usd)}  driver ${formatMoney(supervisor.driverSpend.usd)}`];
+	const barWidth = Math.max(18, Math.min(46, width - 38));
+	for (const row of workers) out.push(`  ${pad(row.worker.label, 12)} ${bar(row.spend.usd, maxUsd, barWidth, "$", color, "magenta")} ${formatMoney(row.spend.usd)}`);
+	if (workers.length === 0) out.push("  no worker cost yet");
+	return out;
+}
+function renderTokenBars(supervisor, width, color) {
+	const rows = supervisor.workers.map((worker) => ({
+		worker,
+		spend: totalSpend(worker),
+		total: totalSpend(worker).tokensInput + totalSpend(worker).tokensOutput
+	})).sort((a, b) => b.total - a.total).slice(0, 6);
+	const maxTokens = Math.max(1, ...rows.map((row) => row.total), supervisor.driverSpend.tokensInput + supervisor.driverSpend.tokensOutput);
+	const out = [`tokens total in ${formatTokens(supervisor.totals.tokensInput)} / out ${formatTokens(supervisor.totals.tokensOutput)}  driver ${formatTokens(supervisor.driverSpend.tokensInput)}/${formatTokens(supervisor.driverSpend.tokensOutput)}`];
+	const barWidth = Math.max(18, Math.min(46, width - 44));
+	for (const row of rows) out.push(`  ${pad(row.worker.label, 12)} ${stackedTokenBar(row.spend.tokensInput, row.spend.tokensOutput, maxTokens, barWidth, color)} ${formatTokens(row.spend.tokensInput)}/${formatTokens(row.spend.tokensOutput)}`);
+	if (rows.length === 0) out.push("  no worker tokens yet");
+	return out;
+}
+function renderLatencyHistogram(supervisor, width, color) {
+	const values = supervisor.workers.map((worker) => worker.latencyMs).filter((value) => value > 0);
+	const summary = supervisor.totals.workerLatency;
+	const out = [`latency n=${summary.n}  min ${formatDuration(summary.min)}  p50 ${formatDuration(summary.median)}  p90 ${formatDuration(summary.p90)}  max ${formatDuration(summary.max)}`];
+	if (values.length === 0) {
+		out.push("  no latency samples yet");
+		return out;
+	}
+	const bins = histogram(values, 6);
+	const maxCount = Math.max(1, ...bins.map((bin) => bin.count));
+	const barWidth = Math.max(18, Math.min(48, width - 34));
+	for (const bin of bins) out.push(`  ${pad(`${formatDuration(bin.min)}-${formatDuration(bin.max)}`, 15)} ${bar(bin.count, maxCount, barWidth, "#", color, "blue")} ${bin.count}`);
+	return out;
+}
+function renderDetail(supervisor, worker, mode, width, color) {
+	if (mode === "detail" && worker) {
+		const spend = totalSpend(worker);
+		return [
+			`worker ${paint(worker.label, "bold", color)} (${worker.id})  ${statusText(worker.status, color)}  latency ${formatDuration(worker.latencyMs)}`,
+			`tokens in/out ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}  cost ${formatMoney(spend.usd)}  iterations ${spend.iterations}`,
+			`parent ${worker.parent ?? "-"}  runtime ${worker.runtime ?? "-"}  out ${worker.outRef ?? "-"}${worker.infra ? "  infra" : ""}`,
+			`events ${compact(worker.eventFile ?? "-", width - 8)}`,
+			...worker.reason ? [`reason ${compact(worker.reason, width - 7)}`] : [],
+			...renderWorkerTail(worker, width, color)
+		];
+	}
+	const caps = [
+		supervisor.maxSandboxes !== void 0 ? `boxes ${supervisor.maxSandboxes}` : void 0,
+		supervisor.maxUsd !== void 0 ? `max ${formatMoney(supervisor.maxUsd)}` : void 0,
+		supervisor.maxDepth !== void 0 ? `depth ${supervisor.maxDepth}` : void 0,
+		supervisor.maxLifetimeSeconds !== void 0 ? `ttl ${supervisor.maxLifetimeSeconds}s` : void 0
+	].filter((value) => value !== void 0);
+	return [
+		`task ${compact(supervisor.task, width - 7)}`,
+		`workspace ${compact(supervisor.workspaceDir, width - 12)}`,
+		`verify ${compact(supervisor.verifyCmd ?? "-", width - 9)}`,
+		`models worker ${supervisor.workerModel ?? "-"} / driver ${supervisor.driverModel ?? "-"}  caps ${caps.join(" | ") || "-"}`,
+		`progress ${compact(supervisor.progress ?? supervisor.verdict ?? supervisor.status, width - 10)}`
+	];
+}
+function renderJournalTail(supervisor, width, color) {
+	if (supervisor.journalTail.length === 0) return ["  no journal events yet"];
+	return supervisor.journalTail.map((event) => {
+		const at = event.at ? formatClock(event.at) : "--:--:--";
+		if (event.kind === "spawned") return `  ${at} ${paint("spawn", "yellow", color)}  ${pad(event.label ?? event.id, 16)} ${event.id}`;
+		if (event.kind === "settled") {
+			const spend = parseSpend(event.spent);
+			return `  ${at} ${statusText(event.status ?? "settled", color)} ${pad(event.id, 18)} ${formatMoney(spend.usd)} ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`;
+		}
+		if (event.kind === "metered") {
+			const spend = parseSpend(event.spend);
+			return `  ${at} ${paint("meter", "cyan", color)}  ${pad(event.id, 18)} ${formatMoney(spend.usd)} ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`;
+		}
+		if (event.kind === "progress") {
+			const spend = parseSpend(event.spend);
+			return `  ${at} ${paint("live", "blue", color)}   ${pad(event.id, 18)} ${formatMoney(spend.usd)} ${formatTokens(spend.tokensInput)}/${formatTokens(spend.tokensOutput)}`;
+		}
+		return `  ${at} ${paint("cancel", "red", color)} ${pad(event.id, 18)} ${compact(event.reason ?? "", width - 32)}`;
+	});
+}
+function renderWorkerTail(worker, width, color) {
+	if (worker.liveTail.length === 0) return ["live events: none recorded yet"];
+	return ["live events:", ...worker.liveTail.slice(-5).map((line) => `  ${paint(compact(formatWorkerEvent(line), width - 2), "dim", color)}`)];
+}
+function renderSteerInput(input, width, color) {
+	const target = input.workerLabel ?? "-";
+	const value = compact(input.value, Math.max(10, width - target.length - 14));
+	return `${paint("steer", "cyan", color)} ${target} > ${value}${paint("_", "inverse", color)}`;
+}
+function formatWorkerEvent(line) {
+	try {
+		const parsed = JSON.parse(line);
+		const at = typeof parsed.at === "string" ? formatClock(parsed.at) : "--:--:--";
+		const kind = typeof parsed.kind === "string" ? parsed.kind : "event";
+		if (kind === "progress") return `${at} progress iter ${numberValue(parsed.iteration)} ${String(parsed.phase ?? "")}`;
+		if (kind === "message") {
+			const state = parsed.queued === true ? "queued" : "sent";
+			const source = typeof parsed.source === "string" && parsed.source.length > 0 ? `${parsed.source} ` : "";
+			const message = typeof parsed.message === "string" && parsed.message.length > 0 ? ` ${parsed.message}` : "";
+			return `${at} ${source}steer ${state} delivered=${String(parsed.delivered)}${message}`;
+		}
+		if (kind === "verify") return `${at} verify passed=${String(parsed.passed)} exit=${String(parsed.exitCode ?? "-")}${evidenceSnippet(parsed.outputTail, 160)}`;
+		if (kind === "finished") {
+			const branch = typeof parsed.branch === "string" ? ` branch=${parsed.branch}` : "";
+			const files = typeof parsed.filesChanged === "number" ? ` files=${parsed.filesChanged}` : "";
+			const tests = typeof parsed.testPassed === "boolean" ? ` tests=${String(parsed.testPassed)}` : "";
+			return `${at} finished passed=${String(parsed.passed)} patchBytes=${numberValue(parsed.patchBytes)}${files}${tests}${branch}${evidenceSnippet(parsed.evidence, 220)}`;
+		}
+		if (kind === "error") return `${at} error ${String(parsed.error ?? "")}`;
+		return `${at} ${kind}`;
+	} catch {
+		return line;
+	}
+}
+/** One-line the settle evidence / verify tail a worker event carries so the
+*  failure is legible in the tail view (the full block stays in the ndjson). */
+function evidenceSnippet(value, max) {
+	if (typeof value !== "string") return "";
+	const oneLine = value.replace(/\s+/g, " ").trim();
+	return oneLine ? ` :: ${compact(oneLine, max)}` : "";
+}
+function histogram(values, count) {
+	const min = Math.min(...values);
+	const max = Math.max(...values);
+	if (min === max) return [{
+		min,
+		max,
+		count: values.length
+	}];
+	const step = (max - min) / count;
+	return Array.from({ length: count }, (_, index) => {
+		const low = min + step * index;
+		const high = index === count - 1 ? max : min + step * (index + 1);
+		return {
+			min: low,
+			max: high,
+			count: values.filter((value) => value >= low && (index === count - 1 ? value <= high : value < high)).length
+		};
+	}).filter((bin) => bin.count > 0);
+}
+function bar(value, max, width, ch, color, colorName) {
+	const filled = Math.max(0, Math.min(width, Math.round(value / Math.max(max, 1e-6) * width)));
+	return paint(ch.repeat(filled).padEnd(width, "."), colorName, color);
+}
+function stackedTokenBar(input, output, max, width, color) {
+	const inputWidth = Math.round(input / Math.max(max, 1) * width);
+	const outputWidth = Math.round(output / Math.max(max, 1) * width);
+	const clippedInput = Math.min(width, inputWidth);
+	const clippedOutput = Math.min(width - clippedInput, outputWidth);
+	const rest = Math.max(0, width - clippedInput - clippedOutput);
+	return `${paint("#".repeat(clippedInput), "cyan", color)}${paint("+".repeat(clippedOutput), "green", color)}${".".repeat(rest)}`;
+}
+function sectionTitle(title, focused, color) {
+	return paint(focused ? `[${title}]` : title, focused ? "cyan" : "bold", color);
+}
+function statusText(status, color) {
+	if ([
+		"completed",
+		"done",
+		"delivered",
+		"valid"
+	].includes(status)) return paint(status.toUpperCase(), "green", color);
+	if ([
+		"failed",
+		"down",
+		"cancelled",
+		"invalid",
+		"error"
+	].includes(status)) return paint(status.toUpperCase(), "red", color);
+	if ([
+		"running",
+		"spawned",
+		"settled"
+	].includes(status)) return paint(status.toUpperCase(), "yellow", color);
+	return paint(status.toUpperCase(), "white", color);
+}
+function selectSupervisor(snapshot, requested) {
+	if (requested) {
+		const found = snapshot.supervisors.find((supervisor) => supervisor.id === requested);
+		if (found) return found;
+	}
+	return snapshot.supervisors[0];
+}
+function selectWorker(supervisor, requested) {
+	if (requested) {
+		const found = supervisor.workers.find((worker) => worker.id === requested);
+		if (found) return found;
+	}
+	return supervisor.workers[0];
+}
+function formatClock(value) {
+	const parsed = parseTime(value);
+	if (parsed === void 0) return "--:--:--";
+	return new Date(parsed).toISOString().slice(11, 19);
+}
+function formatMoney(value) {
+	if (value === 0) return "$0";
+	if (Math.abs(value) < .01) return `$${value.toFixed(4)}`;
+	return `$${value.toFixed(2)}`;
+}
+function formatTokens(value) {
+	if (value >= 1e6) return `${(value / 1e6).toFixed(1)}m`;
+	if (value >= 1e3) return `${(value / 1e3).toFixed(1)}k`;
+	return `${Math.round(value)}`;
+}
+function formatDuration(ms) {
+	if (!Number.isFinite(ms) || ms <= 0) return "0s";
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1e3;
+	if (seconds < 60) return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+	const minutes = seconds / 60;
+	if (minutes < 60) return `${minutes.toFixed(minutes < 10 ? 1 : 0)}m`;
+	return `${(minutes / 60).toFixed(1)}h`;
+}
+function compact(value, width) {
+	if (width <= 1) return "";
+	if (value.length <= width) return value;
+	return `${value.slice(0, width - 1)}~`;
+}
+function pad(value, width) {
+	const visible = visibleLength(value);
+	if (visible >= width) return fitAnsi(value, width);
+	return `${value}${" ".repeat(width - visible)}`;
+}
+function rule(width, color) {
+	return paint("-".repeat(width), "dim", color);
+}
+function paint(value, colorName, enabled) {
+	if (!enabled || !colorName) return value;
+	return `${colors[colorName]}${value}${colors.reset}`;
+}
+function visibleLength(value) {
+	return stripAnsi(value).length;
+}
+function stripAnsi(value) {
+	return value.replace(ansiPattern, "");
+}
+function fitAnsi(value, width) {
+	if (visibleLength(value) <= width) return value;
+	let out = "";
+	let visible = 0;
+	for (let i = 0; i < value.length; i += 1) {
+		const ch = value[i];
+		if (ch === "\x1B") {
+			const rest = value.slice(i);
+			const match = /^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(rest);
+			if (match) {
+				out += match[0];
+				i += match[0].length - 1;
+				continue;
+			}
+		}
+		if (visible >= width - 1) {
+			out += "~";
+			break;
+		}
+		out += ch;
+		visible += 1;
+	}
+	if (out.includes("\x1B[") && !out.endsWith(colors.reset)) out += colors.reset;
+	return out;
+}
+//#endregion
+//#region src/tui/top-app.ts
+/**
+* The interactive side of the supervisor-run TUI: a keypress/mouse loop over the frames
+* `./top-frame` renders, plus the operator controls that write back to the run — steer a live
+* worker, cancel one worker, and request cancellation of a whole run.
+*
+* The controls go through the owned run layout: steers via `writeWorkerSteer` (the durable inbox
+* append) and worker cancellation via `cancelWorker` (the acknowledged operation the runtime's
+* turn loop applies). Run-level cancellation targets the ROOT, which has no acknowledged runtime
+* path yet for a non-retained tree — it stays a `cancel.request.json` write inside the run
+* directory for a host process to honor. Nothing here joins a path from the workspace root.
+*
+* Extracted from the `loops` repo (`src/top.ts`). The module-level singletons are the origin's
+* shape and are kept: this drives one terminal, and `runTopApp` is its one entry point.
+*
+* @experimental
+*/
+let state = initialState([], process.cwd());
+let snapshot = {
+	root: state.root,
+	generatedAt: 0,
+	supervisors: [],
+	completeness: "complete",
+	diagnostics: [],
+	discovered: 0,
+	loaded: 0
+};
+let targets = [];
+let timer;
+/**
+* Render exactly one frame and return it. This is the non-interactive path — `--once`, a pipe, a
+* test — so it never touches raw mode, the alternate screen, or `process.exit`.
+*/
+function renderTopOnce(options = {}) {
+	state = initialState([...options.argv ?? process.argv.slice(2)], options.cwd ?? process.cwd());
+	snapshot = loadTopSnapshot(state.root);
+	clampSelection();
+	return renderTopFrameWithLayout(snapshot, {
+		color: state.color,
+		width: process.stdout.columns ?? 128,
+		focus: state.focus,
+		mode: state.mode,
+		...state.selectedSupervisorId ? { selectedSupervisorId: state.selectedSupervisorId } : {},
+		...state.selectedWorkerId ? { selectedWorkerId: state.selectedWorkerId } : {},
+		steerInput: renderSteerInputState()
+	}).frame;
+}
+/**
+* Run the TUI. With a TTY on both ends and no `--once` this takes over the terminal until `q`;
+* otherwise it writes a single frame to stdout and returns.
+*/
+function runTopApp(options = {}) {
+	const args = [...options.argv ?? process.argv.slice(2)];
+	if (!process.stdout.isTTY || !process.stdin.isTTY || args.includes("--once")) {
+		process.stdout.write(renderTopOnce(options));
+		return;
+	}
+	state = initialState(args, options.cwd ?? process.cwd());
+	snapshot = loadTopSnapshot(state.root);
+	start();
+}
+function initialState(args, cwd) {
+	return {
+		root: resolve(args.find((arg) => !arg.startsWith("-")) ?? cwd),
+		color: Boolean(process.stdout.isTTY) && !args.includes("--no-color"),
+		focus: args.includes("--detail") ? "workers" : "supervisors",
+		mode: args.includes("--log") ? "log" : args.includes("--detail") ? "detail" : "overview",
+		selectedSupervisorId: void 0,
+		selectedWorkerId: void 0,
+		notice: void 0,
+		steerInput: {
+			active: false,
+			value: ""
+		}
+	};
+}
+function start() {
+	process.stdout.write("\x1B[?1049h\x1B[?25l\x1B[?1000h\x1B[?1006h");
+	emitKeypressEvents(process.stdin);
+	process.stdin.setRawMode(true);
+	process.stdin.resume();
+	process.stdin.on("keypress", onKey);
+	process.stdin.on("data", onData);
+	process.on("SIGINT", stop);
+	draw();
+	timer = setInterval(draw, 1e3);
+}
+function stop() {
+	if (timer) clearInterval(timer);
+	process.stdin.setRawMode(false);
+	process.stdout.write("\x1B[?1000l\x1B[?1006l\x1B[?25h\x1B[?1049l");
+	process.exit(0);
+}
+function draw() {
+	snapshot = loadTopSnapshot(state.root);
+	clampSelection();
+	const rendered = renderTopFrameWithLayout(snapshot, {
+		width: process.stdout.columns ?? 128,
+		height: process.stdout.rows ?? 42,
+		color: state.color,
+		focus: state.focus,
+		mode: state.mode,
+		...state.notice ? { notice: state.notice } : {},
+		...state.selectedSupervisorId ? { selectedSupervisorId: state.selectedSupervisorId } : {},
+		...state.selectedWorkerId ? { selectedWorkerId: state.selectedWorkerId } : {},
+		steerInput: renderSteerInputState()
+	});
+	targets = rendered.targets;
+	process.stdout.write(`\x1b[2J\x1b[H${rendered.frame}`);
+}
+function onKey(str, key) {
+	state.notice = void 0;
+	if (key.ctrl && key.name === "c") stop();
+	if (state.steerInput.active) {
+		handleSteerInput(str, key);
+		draw();
+		return;
+	}
+	if (key.name === "q" || key.name === "escape") stop();
+	if (key.name === "tab") state.focus = state.focus === "supervisors" ? "workers" : "supervisors";
+	else if (key.name === "up") moveSelection(-1);
+	else if (key.name === "down") moveSelection(1);
+	else if (key.name === "left") moveSupervisor(-1);
+	else if (key.name === "right") moveSupervisor(1);
+	else if (key.name === "return") {
+		state.mode = "detail";
+		state.focus = "workers";
+	} else if (key.name === "o") state.mode = "overview";
+	else if (key.name === "l") state.mode = "log";
+	else if (key.name === "s") startSteerInput();
+	else if (key.name === "c") requestCancel();
+	draw();
+}
+function handleSteerInput(str, key) {
+	if (key.name === "escape") {
+		state.steerInput = {
+			active: false,
+			value: ""
+		};
+		return;
+	}
+	if (key.name === "return") {
+		submitSteerInput();
+		return;
+	}
+	if (key.name === "backspace") {
+		state.steerInput.value = state.steerInput.value.slice(0, -1);
+		return;
+	}
+	if (key.ctrl && key.name === "u") {
+		state.steerInput.value = "";
+		return;
+	}
+	if (key.ctrl || key.name === "tab" || key.name === "up" || key.name === "down" || key.name === "left" || key.name === "right") return;
+	if (!str || str === "\r" || str === "\n") return;
+	if ([...str].every((char) => char >= " " && char !== "")) state.steerInput.value += str;
+}
+function onData(data) {
+	const click = parseMouse(data.toString("utf8"));
+	if (!click) return;
+	const target = targets.find((candidate) => candidate.row === click.row);
+	if (!target) return;
+	state.notice = void 0;
+	if (target.kind === "supervisor") {
+		state.focus = "supervisors";
+		state.selectedSupervisorId = target.id;
+		state.selectedWorkerId = void 0;
+	} else {
+		state.focus = "workers";
+		state.mode = "detail";
+		state.selectedSupervisorId = target.supervisorId;
+		state.selectedWorkerId = target.id;
+	}
+	draw();
+}
+function startSteerInput() {
+	state.mode = "detail";
+	state.focus = "workers";
+	if (!selectedSupervisor()) {
+		state.notice = "no supervisor selected";
+		return;
+	}
+	if (!selectedWorker()) {
+		state.notice = "no worker selected";
+		return;
+	}
+	state.steerInput = {
+		active: true,
+		value: ""
+	};
+}
+function submitSteerInput() {
+	const supervisor = selectedSupervisor();
+	const worker = selectedWorker();
+	const message = state.steerInput.value;
+	state.steerInput = {
+		active: false,
+		value: ""
+	};
+	if (!supervisor) {
+		state.notice = "no supervisor selected";
+		return;
+	}
+	if (!worker) {
+		state.notice = "no worker selected";
+		return;
+	}
+	try {
+		const written = writeWorkerSteer(state.root, supervisor.id, worker.id, {
+			operationId: randomUUID(),
+			message,
+			source: "agent-runtime-top"
+		});
+		state.notice = `steer queued for ${supervisor.id}/${worker.label} (op ${written.request.operationId})`;
+	} catch (err) {
+		state.notice = `steer failed: ${err instanceof Error ? err.message : String(err)}`;
+	}
+}
+function parseMouse(raw) {
+	const match = /\x1b\[<(\d+);(\d+);(\d+)([mM])/.exec(raw);
+	if (match?.[4] !== "M") return void 0;
+	const col = Number(match[2]);
+	const row = Number(match[3]);
+	if (!Number.isFinite(col) || !Number.isFinite(row)) return void 0;
+	return {
+		col: col - 1,
+		row: row - 1
+	};
+}
+function moveSelection(delta) {
+	if (state.focus === "supervisors") {
+		moveSupervisor(delta);
+		return;
+	}
+	const supervisor = selectedSupervisor();
+	if (!supervisor || supervisor.workers.length === 0) return;
+	const next = wrap(Math.max(0, supervisor.workers.findIndex((worker) => worker.id === state.selectedWorkerId)) + delta, supervisor.workers.length);
+	const worker = supervisor.workers[next];
+	if (worker) state.selectedWorkerId = worker.id;
+}
+function moveSupervisor(delta) {
+	if (snapshot.supervisors.length === 0) return;
+	const next = wrap(Math.max(0, snapshot.supervisors.findIndex((supervisor) => supervisor.id === state.selectedSupervisorId)) + delta, snapshot.supervisors.length);
+	const supervisor = snapshot.supervisors[next];
+	if (!supervisor) return;
+	state.selectedSupervisorId = supervisor.id;
+	state.selectedWorkerId = supervisor.workers[0]?.id;
+}
+function clampSelection() {
+	if (snapshot.supervisors.length === 0) {
+		state.selectedSupervisorId = void 0;
+		state.selectedWorkerId = void 0;
+		return;
+	}
+	const supervisor = selectedSupervisor() ?? snapshot.supervisors[0];
+	if (!supervisor) return;
+	state.selectedSupervisorId = supervisor.id;
+	const worker = supervisor.workers.find((candidate) => candidate.id === state.selectedWorkerId) ?? supervisor.workers[0];
+	state.selectedWorkerId = worker?.id;
+}
+function selectedSupervisor() {
+	return snapshot.supervisors.find((supervisor) => supervisor.id === state.selectedSupervisorId);
+}
+function selectedWorker() {
+	return selectedSupervisor()?.workers.find((worker) => worker.id === state.selectedWorkerId);
+}
+function renderSteerInputState() {
+	const worker = selectedWorker();
+	return {
+		active: state.steerInput.active,
+		value: state.steerInput.value,
+		...worker?.label ? { workerLabel: worker.label } : {}
+	};
+}
+function requestCancel() {
+	const supervisor = selectedSupervisor();
+	if (!supervisor) {
+		state.notice = "no supervisor selected";
+		return;
+	}
+	if (supervisor.status !== "running") {
+		state.notice = `${supervisor.id} is ${supervisor.status}; no cancel request written`;
+		return;
+	}
+	const worker = state.focus === "workers" ? selectedWorker() : void 0;
+	if (worker) {
+		if (worker.status !== "running") {
+			state.notice = `${worker.label} is ${worker.status}; nothing to cancel`;
+			return;
+		}
+		try {
+			const record = cancelWorker(supervisor.stateDir, worker.id, randomUUID(), {
+				reason: "operator requested cancel from TUI",
+				source: "agent-runtime-top"
+			});
+			state.notice = record.effect === "unknown" ? `cancel queued for ${supervisor.id}/${worker.label} (op ${record.operationId}); awaiting runtime acknowledgement` : `cancel ${record.effect} for ${supervisor.id}/${worker.label} (op ${record.operationId})`;
+		} catch (err) {
+			state.notice = `cancel request failed: ${err instanceof Error ? err.message : String(err)}`;
+		}
+		return;
+	}
+	try {
+		const record = cancelRun(supervisor.stateDir, randomUUID(), {
+			reason: "operator requested cancel from TUI",
+			source: "agent-runtime-top"
+		});
+		state.notice = record.effect === "unknown" ? `run cancel queued for ${supervisor.id} (op ${record.operationId}); awaiting runtime acknowledgement` : `run cancel ${record.effect} for ${supervisor.id} (op ${record.operationId})`;
+	} catch (err) {
+		state.notice = `cancel request failed: ${err instanceof Error ? err.message : String(err)}`;
+	}
+}
+function wrap(value, size) {
+	return (value % size + size) % size;
+}
+//#endregion
 //#region src/tui/bin.ts
 /**
 * `agent-runtime-top` — watch the supervisor runs of one workspace.