@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/cli/fleet.ts

@@ -7,6 +7,9 @@
  *   clio-coder fleet commands init             draft a repository command registry
  *   clio-coder fleet run <name> --var k=v ...  preflight + execute a fleet contract
  *   clio-coder fleet status [--json]           runtime snapshot from the durable ledger
+ *   clio-coder fleet inspect --json             bounded recent run and journal projection
+ *   clio-coder fleet decisions --json           bounded sealed review and compete gate verdicts
+ *   clio-coder fleet view <runId|fleetRootId>  one run's transcript, or a root's step index
  *   clio-coder fleet drain|resume [--json]      close or reopen durable dispatch admission
  *
  * Fleet contracts are repo-owned policy (.clio-coder/fleets/<name>.md). Preflight
@@ -47,27 +50,39 @@ import {
 	type RunToolBudgetEnvelope,
 } from "../domains/dispatch/budget-envelope.js";
 import { type CapacityDrain, capacityDrain, setCapacityDraining } from "../domains/dispatch/capacity-lease.js";
-import type { DispatchContract } from "../domains/dispatch/contract.js";
-import type { ExecutionPlan } from "../domains/dispatch/execution-plan.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
+import { bindExecutionPlanEndpoints, type ExecutionPlan } from "../domains/dispatch/execution-plan.js";
 import { agentRoleFactsResolver, requestExecutionRole, withAttemptRole } from "../domains/dispatch/execution-role.js";
 import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
 import {
-	DispatchDomainModule,
+	createDispatchDomainModule,
 	type ExecuteFleetRunInput,
 	executeFleetRun,
 	type FleetRunOutcome,
 	planFleetResume,
 	readFleetRun,
 } from "../domains/dispatch/index.js";
+import { configureRunEventJournal } from "../domains/dispatch/run-event-journal.js";
 import { openLedger } from "../domains/dispatch/state.js";
 import type { RunEnvelope, RunReceipt } from "../domains/dispatch/types.js";
 import { WRITE_BOUNDARY_VIOLATION_REASON } from "../domains/dispatch/write-boundary.js";
 import { preflightWriteBoundaries } from "../domains/dispatch/write-boundary-enforcer.js";
 import { ensureClioState, LifecycleDomainModule } from "../domains/lifecycle/index.js";
 import { MiddlewareDomainModule } from "../domains/middleware/index.js";
-import { ObservabilityDomainModule } from "../domains/observability/index.js";
+import {
+	aggregateCostAmounts,
+	type CostAggregate,
+	ObservabilityDomainModule,
+	renderCostAggregate,
+	renderCostAmount,
+} from "../domains/observability/index.js";
 import { createPromptsDomainModule } from "../domains/prompts/index.js";
-import { ProvidersDomainModule } from "../domains/providers/index.js";
+import {
+	type CostProvenance,
+	foregroundStreamUsage,
+	normalizeCostProvenance,
+	ProvidersDomainModule,
+} from "../domains/providers/index.js";
 import { ResourcesDomainModule } from "../domains/resources/index.js";
 import type { SafetyContract } from "../domains/safety/contract.js";
 import { SafetyDomainModule } from "../domains/safety/index.js";
@@ -89,6 +104,10 @@ Subcommands:
        [--resume <runId>]        replay a completed prefix from a prior run of the same plan
        [--json]                 emit step receipts as JSON
   status [--json]               show running, retrying, and total dispatch state
+  inspect --json                emit a bounded recent-run and event-journal projection
+  decisions --json              emit a bounded window of sealed review and compete gate verdicts
+  view <runId> [--follow]       read one run's ledger entry, event journal, and receipt
+  view <fleetRootId>            list a fleet run's steps and the run id to view for each
   drain [--json]                deny new execution starts for up to one hour
   resume [--json]               reopen dispatch admission immediately
 
@@ -96,6 +115,10 @@ Notes:
   status reads the durable run ledger. Rows started by another process show
   heartbeat liveness from the recorded worker pid; per-token live meters are
   only available inside the process that owns the run.
+  view is read-only and shares no memory with the orchestrator, so it follows a
+  run from a second terminal or over SSH. Its transcript comes from the run
+  event journal, written when panes.journal is on (the default). Handed the
+  fleet-<hex> root id that run prints, it lists that run's steps instead.
   drain preserves running work. Repeat it to renew the one-hour expiry; resume
   clears it early. The expiry prevents an abandoned drain from wedging Clio.
 `;
@@ -127,7 +150,9 @@ function parseVars(args: ReadonlyArray<string>): { vars: Record<string, string>;
 		const eq = pair.indexOf("=");
 		const key = pair.slice(0, eq).trim();
 		const value = pair.slice(eq + 1);
-		if (key.length === 0) return { vars, rest, error: "--var requires a non-empty key" };
+		if (key.length === 0) {
+			return { vars, rest, error: "--var requires a non-empty key" };
+		}
 		vars[key] = value;
 	}
 	return { vars, rest };
@@ -145,7 +170,9 @@ function renderStep(step: FleetContractStep): string {
 	if (step.kind === "code") return `code:${step.command}[${step.scope}]`;
 	if (step.kind === "agent") return `${step.agent}[${step.scope}]`;
 	if (step.kind === "gate") return `gate:${step.path}[${step.run}]`;
-	if (step.kind === "plan") return `plan:${step.agent}[${step.roster.join(",")}; max ${step.maxTasks}]`;
+	if (step.kind === "plan") {
+		return `plan:${step.agent}[${step.roster.join(",")}; max ${step.maxTasks}]`;
+	}
 	const check =
 		step.check.kind === "code"
 			? `code:${step.check.command}`
@@ -212,16 +239,28 @@ function contractAgents(
 ): Array<{ id: string; agent: string; scope: "readonly" | "workspace" }> {
 	const agents: Array<{ id: string; agent: string; scope: "readonly" | "workspace" }> = [];
 	for (const step of contract.steps) {
-		if (step.kind === "agent") agents.push({ id: step.id, agent: step.agent, scope: step.scope });
-		else if (step.kind === "gate") agents.push({ id: step.id, agent: step.agent, scope: "workspace" });
-		else if (step.kind === "plan") {
+		if (step.kind === "agent") {
+			agents.push({ id: step.id, agent: step.agent, scope: step.scope });
+		} else if (step.kind === "gate") {
+			agents.push({ id: step.id, agent: step.agent, scope: "workspace" });
+		} else if (step.kind === "plan") {
 			agents.push({ id: step.id, agent: step.agent, scope: step.scope });
-			for (const agent of step.roster) agents.push({ id: `${step.id}.roster`, agent, scope: "readonly" });
+			for (const agent of step.roster) {
+				agents.push({ id: `${step.id}.roster`, agent, scope: "readonly" });
+			}
 		} else if (step.kind === "loop") {
 			if (step.check.kind === "agent") {
-				agents.push({ id: `${step.id}.check`, agent: step.check.agent, scope: step.check.scope });
+				agents.push({
+					id: `${step.id}.check`,
+					agent: step.check.agent,
+					scope: step.check.scope,
+				});
 			}
-			agents.push({ id: `${step.id}.repair`, agent: step.repair.agent, scope: step.repair.scope });
+			agents.push({
+				id: `${step.id}.repair`,
+				agent: step.repair.agent,
+				scope: step.repair.scope,
+			});
 		}
 	}
 	return agents;
@@ -231,10 +270,12 @@ function preflightFleet(contract: FleetContract, deps: FleetPreflightDeps): stri
 	const targets = new Set(deps.settings.targets.map((target) => target.id));
 	const profiles = new Set(Object.keys(deps.settings.workers?.profiles ?? {}));
 	const checkRoute = (id: string, route: { target?: string; profile?: string }): string | null => {
-		if (route.target !== undefined && !targets.has(route.target))
+		if (route.target !== undefined && !targets.has(route.target)) {
 			return `unknown target '${route.target}' at step '${id}'`;
-		if (route.profile !== undefined && !profiles.has(route.profile))
+		}
+		if (route.profile !== undefined && !profiles.has(route.profile)) {
 			return `unknown profile '${route.profile}' at step '${id}'`;
+		}
 		return null;
 	};
 	for (const step of contract.steps) {
@@ -280,10 +321,13 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 	const json = rest.includes("--json");
 	const resumeIndex = rest.indexOf("--resume");
 	const resumeId = resumeIndex === -1 ? undefined : rest[resumeIndex + 1];
-	if (resumeIndex !== -1 && (resumeId === undefined || resumeId.startsWith("-")))
+	if (resumeIndex !== -1 && (resumeId === undefined || resumeId.startsWith("-"))) {
 		return fail("--resume requires a run id");
+	}
 	const name = rest.find((arg) => !arg.startsWith("-"));
-	if (!name) return fail("usage: clio-coder fleet run <name> [--var key=value ...] [--resume <runId>] [--json]");
+	if (!name) {
+		return fail("usage: clio-coder fleet run <name> [--var key=value ...] [--resume <runId>] [--json]");
+	}
 
 	let contract: FleetContract;
 	let prompt: string;
@@ -312,7 +356,10 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		MiddlewareDomainModule,
 		ObservabilityDomainModule,
 		SchedulingDomainModule,
-		DispatchDomainModule,
+		// A fleet step is dispatched by executeFleetRun, which drains the handle
+		// itself and never builds a dispatch event registry, so the domain is the
+		// only thing that can write each step's durable transcript.
+		createDispatchDomainModule({ journalRunEvents: true }),
 		SessionDomainModule,
 		LifecycleDomainModule,
 	]);
@@ -325,12 +372,17 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		await loaded.stop();
 		return fail("required domains unavailable (dispatch/agents/safety)");
 	}
+	const fleetSettings = config?.get() ?? readSettings();
+	// Install `panes.journal` the same way the interactive composition root
+	// does, so a fleet run honours the setting without the journal ever reading
+	// settings.yaml from the dispatch event path.
+	configureRunEventJournal(fleetSettings.panes.journal);
 	const roleFacts = agentRoleFactsResolver((id) => agents.getSpec(id));
 	const preflightError = preflightFleet(contract, {
 		agents,
 		safety,
 		scheduling,
-		settings: config?.get() ?? readSettings(),
+		settings: fleetSettings,
 	});
 	if (preflightError !== null) {
 		await loaded.stop();
@@ -372,6 +424,35 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		await loaded.stop();
 		return fail(err instanceof Error ? err.message : String(err));
 	}
+	if (dispatch.preview !== undefined) {
+		try {
+			const foreground = foregroundStreamUsage();
+			const bindings: Record<string, { key: string; limit: number; foregroundHeld?: number } | undefined> = {};
+			for (const step of plan.steps) {
+				if (step.kind === "code") continue;
+				const request: DispatchRequest = {
+					agentId: step.agentId,
+					executionRole: step.executionRole,
+					task: step.task,
+					...(step.scope === "readonly" ? { autonomy: "read-only" as const } : {}),
+					...(step.target !== undefined ? { target: step.target } : {}),
+					...(step.profile !== undefined ? { workerProfile: step.profile } : {}),
+				};
+				const endpoint = dispatch.preview(request).endpoint;
+				if (endpoint === undefined) continue;
+				const foregroundHeld = foreground[endpoint.key] ?? 0;
+				bindings[step.id] = {
+					key: endpoint.key,
+					limit: endpoint.limit,
+					...(foregroundHeld > 0 ? { foregroundHeld } : {}),
+				};
+			}
+			plan = bindExecutionPlanEndpoints(plan, bindings);
+		} catch (err) {
+			await loaded.stop();
+			return fail(`route preflight failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
 	try {
 		preflightWriteBoundaries(plan, process.cwd());
 	} catch (err) {
@@ -428,30 +509,43 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 			...(resume !== undefined ? { resume } : {}),
 			onStepSettled(step) {
 				if (step.replayed === true && step.result !== undefined) {
-					if (json)
+					if (json) {
 						process.stdout.write(
-							`${JSON.stringify({ stepId: step.stepId, status: "replayed", receipt: { runId: step.result.terminalRunId, digest: step.result.receiptDigest } })}\n`,
+							`${JSON.stringify({
+								stepId: step.stepId,
+								status: "replayed",
+								receipt: {
+									runId: step.result.terminalRunId,
+									digest: step.result.receiptDigest,
+								},
+							})}\n`,
 						);
-					else
+					} else {
 						process.stdout.write(
 							`step ${step.stepId}: replayed terminal-run=${step.result.terminalRunId} receipt=${step.result.receiptDigest}\n`,
 						);
+					}
 					return;
 				}
 				if (step.receipt !== undefined) {
 					if (json) process.stdout.write(`${JSON.stringify(step.receipt)}\n`);
-					else
+					else {
 						process.stdout.write(
-							`step ${step.stepId} ${step.agentId}: ${step.succeeded ? "succeeded" : "failed"}${step.failureReason !== undefined ? ` reason=${step.failureReason}` : ""} assignment=${step.assignmentId} terminal-run=${step.terminalRunId} cost=$${step.costUsd.toFixed(4)}\n`,
+							`step ${step.stepId} ${step.agentId}: ${step.succeeded ? "succeeded" : "failed"}${step.failureReason !== undefined ? ` reason=${step.failureReason}` : ""} assignment=${step.assignmentId} terminal-run=${step.terminalRunId} cost=${renderCostAmount(step.costUsd, step.costProvenance)}\n`,
 						);
+					}
 					return;
 				}
 				if (step.codeStep !== undefined) {
-					if (json) process.stdout.write(`${JSON.stringify({ codeStep: step.codeStep })}\n`);
-					else
+					if (json) {
+						process.stdout.write(`${JSON.stringify({ codeStep: step.codeStep })}\n`);
+					} else {
 						process.stdout.write(
-							`step ${step.stepId} code:${step.commandId}: ${step.succeeded ? "passed" : "failed"} exit=${step.codeStep.exitCode} ${step.codeStep.durationMs}ms record=${step.recordPath}\n`,
+							`step ${step.stepId} code:${step.commandId}: ${
+								step.succeeded ? "passed" : "failed"
+							} exit=${step.codeStep.exitCode} ${step.codeStep.durationMs}ms record=${step.recordPath}\n`,
 						);
+					}
 				}
 			},
 			onNotice(text, kind) {
@@ -483,21 +577,31 @@ async function runFleet(args: ReadonlyArray<string>): Promise<number> {
 		);
 	} else {
 		process.stdout.write(
-			`fleet ${contract.name}: ${outcome.succeededStepCount}/${outcome.requiredStepCount} steps succeeded, ${outcome.resolvedLoopCount}/${outcome.result.loops.length} loops resolved, total cost $${outcome.totalCostUsd.toFixed(4)}\n`,
+			`fleet ${contract.name}: ${outcome.succeededStepCount}/${outcome.requiredStepCount} steps succeeded, ${outcome.resolvedLoopCount}/${outcome.result.loops.length} loops resolved, total cost ${renderCostAggregate(outcome.totalCost)}\n`,
 		);
-		for (const loop of outcome.result.loops)
+		for (const loop of outcome.result.loops) {
 			process.stdout.write(
 				`  loop ${loop.loopId}: ${loop.reason} after ${loop.attempts} verification(s) and ${loop.repairs} repair(s)\n`,
 			);
-		if (outcome.result.revalidated.length > 0)
+		}
+		if (outcome.result.revalidated.length > 0) {
 			process.stdout.write(
-				`  staleness: re-ran ${outcome.result.revalidated.join(", ")} because a workspace step landed after the last green\n`,
+				`  staleness: re-ran ${outcome.result.revalidated.join(
+					", ",
+				)} because a workspace step landed after the last green\n`,
 			);
-		for (const message of outcome.result.needsDecision) process.stdout.write(`  needs operator decision: ${message}\n`);
+		}
+		for (const message of outcome.result.needsDecision) {
+			process.stdout.write(`  needs operator decision: ${message}\n`);
+		}
 		for (const boundary of outcome.result.writeBoundaries) {
 			if (!boundary.violated) continue;
 			process.stdout.write(`  write boundary ${boundary.window}: ${boundary.detail ?? WRITE_BOUNDARY_VIOLATION_REASON}\n`);
 		}
+		// The root id printed at the top is the only identifier this command
+		// advertises, so say what it is good for rather than leaving an operator
+		// to guess that the viewer wants a per-step run id.
+		process.stdout.write(`  clio-coder fleet view ${fleetRootId}   step index with each step's run id\n`);
 	}
 	return outcome.cleanRun ? 0 : 1;
 }
@@ -530,7 +634,10 @@ function receiptTokenSplit(row: RunEnvelope): { input: number; output: number }
 	const path = row.receiptPath ?? join(clioStateDir(), "receipts", `${row.id}.json`);
 	try {
 		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<RunReceipt>;
-		return { input: finiteCount(parsed.inputTokenCount), output: finiteCount(parsed.outputTokenCount) };
+		return {
+			input: finiteCount(parsed.inputTokenCount),
+			output: finiteCount(parsed.outputTokenCount),
+		};
 	} catch {
 		return null;
 	}
@@ -543,7 +650,10 @@ function receiptTokenSplit(row: RunEnvelope): { input: number; output: number }
  */
 function rowTokenSplit(row: RunEnvelope): { input: number; output: number } {
 	if (row.inputTokenCount !== undefined || row.outputTokenCount !== undefined) {
-		return { input: finiteCount(row.inputTokenCount), output: finiteCount(row.outputTokenCount) };
+		return {
+			input: finiteCount(row.inputTokenCount),
+			output: finiteCount(row.outputTokenCount),
+		};
 	}
 	if (row.endedAt !== null) {
 		return receiptTokenSplit(row) ?? { input: 0, output: 0 };
@@ -553,7 +663,12 @@ function rowTokenSplit(row: RunEnvelope): { input: number; output: number } {
 
 export type FleetAdmissionStatus =
 	| { state: "open" }
-	| { state: "draining"; requestedByPid: number; requestedAt: string; expiresAt: string };
+	| {
+			state: "draining";
+			requestedByPid: number;
+			requestedAt: string;
+			expiresAt: string;
+	  };
 
 function admissionStatus(drain: CapacityDrain | null): FleetAdmissionStatus {
 	if (drain === null) return { state: "open" };
@@ -565,7 +680,16 @@ export function statusSnapshot(): {
 	admission: FleetAdmissionStatus;
 	running: Array<Record<string, unknown>>;
 	retrying: Array<Record<string, unknown>>;
-	totals: { inputTokens: number; outputTokens: number; totalTokens: number; costUsd: number; runtimeSeconds: number };
+	totals: {
+		inputTokens: number;
+		outputTokens: number;
+		totalTokens: number;
+		/** The bare sum, kept for JSON readers that already parse it. Render `cost`. */
+		costUsd: number;
+		/** Mirrors what `DispatchSnapshot.totals.cost` declares for the in-process surface. */
+		cost: CostAggregate;
+		runtimeSeconds: number;
+	};
 } {
 	const ledger = openLedger();
 	const nowMs = Date.now();
@@ -586,10 +710,18 @@ export function statusSnapshot(): {
 				elapsedMs: Number.isFinite(startedMs) ? Math.max(0, nowMs - startedMs) : 0,
 				tokens: { input: 0, output: 0, total: row.tokenCount },
 				costUsd: row.costUsd,
+				// Absent on pre-provenance ledger rows, which readers must treat as
+				// unknown; `renderCostAmount` normalizes it rather than assuming free.
+				costProvenance: row.costProvenance,
 				node: row.node?.id ?? "local",
 			};
 		});
 	const totals = { inputTokens: 0, outputTokens: 0, totalTokens: 0, costUsd: 0, runtimeSeconds: 0 };
+	// Folded rather than summed: a ledger of runs nobody priced totals to an
+	// absent cost claim, not to zero dollars.
+	const cost = aggregateCostAmounts(
+		rows.map((row) => ({ usd: row.costUsd, provenance: normalizeCostProvenance(row.costProvenance) })),
+	);
 	for (const row of rows) {
 		const split = rowTokenSplit(row);
 		totals.inputTokens += split.input;
@@ -609,7 +741,7 @@ export function statusSnapshot(): {
 		admission: admissionStatus(capacityDrain(nowMs)),
 		running,
 		retrying: [],
-		totals,
+		totals: { ...totals, cost },
 	};
 }
 
@@ -634,7 +766,7 @@ function runStatus(args: ReadonlyArray<string>): number {
 		for (const row of snapshot.running) {
 			const lineage = row.lineage as { attempt: number; depth: number };
 			process.stdout.write(
-				`  ${row.runId}  ${row.agentId}  node=${row.node}  ${row.heartbeat}  attempt=${lineage.attempt} depth=${lineage.depth}  ${Math.round((row.elapsedMs as number) / 1000)}s  $${(row.costUsd as number).toFixed(4)}\n`,
+				`  ${row.runId}  ${row.agentId}  node=${row.node}  ${row.heartbeat}  attempt=${lineage.attempt} depth=${lineage.depth}  ${Math.round((row.elapsedMs as number) / 1000)}s  ${renderCostAmount(row.costUsd as number, row.costProvenance as CostProvenance | undefined)}\n`,
 			);
 			const budget = row.budget as RunToolBudgetEnvelope | null;
 			if (budget !== null) {
@@ -655,7 +787,7 @@ function runStatus(args: ReadonlyArray<string>): number {
 	}
 	const t = snapshot.totals;
 	process.stdout.write(
-		`totals: tokens=${t.totalTokens} (in=${t.inputTokens} out=${t.outputTokens}) cost=$${t.costUsd.toFixed(4)} runtime=${Math.round(t.runtimeSeconds)}s\n`,
+		`totals: tokens=${t.totalTokens} (in=${t.inputTokens} out=${t.outputTokens}) cost=${renderCostAggregate(t.cost)} runtime=${Math.round(t.runtimeSeconds)}s\n`,
 	);
 	return 0;
 }
@@ -709,6 +841,14 @@ export async function runFleetCommand(args: ReadonlyArray<string>): Promise<numb
 			return runFleet(args.slice(1));
 		case "status":
 			return runStatus(args.slice(1));
+		case "inspect":
+			return (await import("./fleet-inspect.js")).runFleetInspect(args.slice(1));
+		case "decisions":
+			return (await import("./fleet-decisions.js")).runFleetDecisions(args.slice(1));
+		case "verify":
+			return (await import("./fleet-verify.js")).runFleetVerify(args.slice(1));
+		case "view":
+			return (await import("./fleet-view.js")).runFleetView(args.slice(1));
 		case "drain":
 			return runAdmissionControl("drain", args.slice(1));
 		case "resume":

package/src/cli/index.ts

@@ -30,10 +30,13 @@ science. CLIO stands for Context Layer for Input/Output, named for the Greek mus
 Usage:
   clio-coder                      start interactive repository chat
   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
   clio-coder --version, -v        print the Clio Coder version
   clio-coder --api-key <key>      override the active target API key for this run
   clio-coder --no-context-files, -nc  skip CLIO-CODER.md project-context injection
+  clio-coder --with-panes         activate the panes extension (terminal panes for workers and tools)
+  clio-coder --no-panes           keep panes off even when settings turn them on
   clio-coder configure            interactive first-run/configuration wizard
   clio-coder targets              list configured targets, health, auth, and capabilities
   clio-coder targets add          add a target interactively or via flags
@@ -57,7 +60,7 @@ Usage:
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
   clio-coder upgrade              upgrade Clio Coder and run pending migrations
   clio-coder agents               list discovered agent recipes
-  clio-coder fleet new|validate|graph|commands|run|status|drain|resume  fleet authoring, execution, status, and admission control
+  clio-coder fleet new|validate|graph|commands|run|status|view|verify|drain|resume  fleet authoring, execution, status, verification, and admission control
   clio-coder evidence             build, list, or inspect evidence artifacts
   clio-coder eval                 run, report, or compare local eval task files
   clio-coder memory               list, propose, promote, approve, reject, or prune memory
@@ -66,7 +69,10 @@ Usage:
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder skills               list, inspect, validate, or install skills
   clio-coder library              list, search, add, or sync agents, prompts, fleets, and skills from catalogs
-  clio-coder verifiers            discover, author, validate, edit, or dry-run project checks
+  clio-coder verifiers            discover, inspect, author, validate, edit, or dry-run project checks
+  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        install the pane multiplexer (alias for 'tools install herdr')
   clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
   clio-coder --help, -h           this message
@@ -112,6 +118,7 @@ interface CliBootOptions {
 	noContextFiles?: boolean;
 	noSkills?: boolean;
 	skillPaths?: string[];
+	panes?: "with" | "without";
 }
 
 type CommandHandler = (subArgs: string[], bootOptions: CliBootOptions) => Promise<number>;
@@ -143,6 +150,7 @@ async function main(argv: string[]): Promise<number> {
 		noContextFiles,
 		noSkills,
 		skillPaths,
+		panes,
 		rest,
 		error: globalFlagError,
 	} = extractGlobalFlags(argv, isCommandToken);
@@ -169,6 +177,7 @@ async function main(argv: string[]): Promise<number> {
 		...(noContextFiles ? { noContextFiles: true } : {}),
 		...(noSkills ? { noSkills: true } : {}),
 		...(skillPaths.length > 0 ? { skillPaths } : {}),
+		...(panes === undefined ? {} : { panes }),
 	};
 	if (!subcommand) {
 		await enableBootCompileCache();
@@ -261,6 +270,9 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 			return (await import("./run.js")).runClioRun(subArgs, bootOptions);
 		},
 	],
+	["tools", async (subArgs) => (await import("./tools.js")).runToolsCommand(subArgs)],
+	["interop", async (subArgs) => (await import("./interop.js")).runInteropCommand(subArgs)],
+	["panes", async (subArgs) => (await import("./panes.js")).runPanesCommand(subArgs)],
 	["doctor", async (subArgs) => (await import("./doctor.js")).runDoctorCommand(subArgs)],
 	["paths", async (subArgs) => (await import("./paths.js")).runPathsCommand(subArgs)],
 	["reset", async (subArgs) => (await import("./reset.js")).runResetCommand(subArgs)],

package/src/cli/interop-inspect.ts

@@ -0,0 +1,128 @@
+/**
+ * Fixed machine-readable projection of detected external coding agents.
+ *
+ * `configure --interop` is an interactive review that writes delegation peers
+ * into settings, so it is not a transport a GUI host can invoke. This command
+ * takes no identifier or flag beyond `--json`, decides nothing, and writes
+ * nothing.
+ *
+ * It also runs no foreign executable. Detection can probe `<bin> --version`,
+ * and this read deliberately does not: a GUI refresh must not become "execute
+ * every coding agent installed on this machine". The version still crosses,
+ * because a non-probing detection keeps the last version the harness observed
+ * for the same binary, so what the operator sees is a recorded fact rather than
+ * a fresh execution.
+ *
+ * Resolved binary paths and the agent's home directory are native filesystem
+ * facts and stay on the host. Whether a directory exists crosses; where it is
+ * does not.
+ */
+
+import { readSettings } from "../core/config.js";
+import {
+	detectInteropAgents,
+	INTEROP_AGENT_KINDS,
+	type InteropAgentId,
+	type InteropPresence,
+	interopAgentKind,
+} from "../domains/interop/index.js";
+
+export type InteropDecisionState = "accepted" | "declined";
+
+export interface InteropInspectAgent {
+	readonly id: InteropAgentId;
+	readonly label: string;
+	readonly presence: InteropPresence;
+	/** The last version the harness observed for this binary, never probed here. */
+	readonly version: string | null;
+	/** Whether the agent owns a directory under the operator's home. The path stays host-side. */
+	readonly hasUserDirectory: boolean;
+	/** Whether this kind speaks ACP at all. */
+	readonly acp: boolean;
+	/** Whether the ACP adapter can start without a network install; null for a kind with no recipe. */
+	readonly adapter: InteropPresence | null;
+	/** Whether a `delegation.agents` entry already names this agent. */
+	readonly configured: boolean;
+	/** The operator's standing answer, or null when they have not been asked. */
+	readonly decision: InteropDecisionState | null;
+	readonly decidedAt: string | null;
+	/**
+	 * True when the facts moved since the decision was taken.
+	 *
+	 * A standing answer suppresses re-proposal only while the facts it was made
+	 * against still hold, so this is what says Clio Coder will ask again.
+	 */
+	readonly decisionStale: boolean;
+	/** True when Clio Coder would offer to wire this agent on the next review. */
+	readonly proposed: boolean;
+	/** True when wiring it would fetch the adapter from the network on first use. */
+	readonly needsNetworkInstall: boolean;
+}
+
+export interface InteropInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	readonly detectedAt: string;
+	/**
+	 * How many agent kinds the registry knows, so an empty list reads as "none
+	 * detected" rather than "nothing to detect". Detection drops a kind with no
+	 * binary, no directory, and no artifacts, so the list is never padded.
+	 */
+	readonly knownKinds: number;
+	readonly agents: readonly InteropInspectAgent[];
+}
+
+/**
+ * Skill and artifact counts are deliberately absent.
+ *
+ * Detection populates them only from sources the resources and context domains
+ * have already loaded, and this command loads neither. Reporting the structural
+ * zero that would result would state a fact this read did not establish.
+ */
+export async function interopInspectSnapshot(now: () => number = Date.now): Promise<InteropInspectSnapshot> {
+	const report = await detectInteropAgents({ cwd: process.cwd(), probeVersion: false });
+	const settings = readSettings();
+	const configured = new Set(settings.delegation.agents.map((agent) => agent.id));
+	const agents: InteropInspectAgent[] = [];
+	for (const record of report.agents) {
+		const kind = interopAgentKind(record.kind);
+		if (kind === undefined) continue;
+		const acp = kind.acp !== undefined;
+		const decision = record.decision === "accepted" || record.decision === "declined" ? record.decision : null;
+		const decisionStale = decision !== null && record.decidedFingerprint !== record.fingerprint;
+		const isConfigured = configured.has(kind.id);
+		agents.push({
+			id: kind.id,
+			label: kind.label,
+			presence: record.presence,
+			version: typeof record.version === "string" && record.version.length > 0 ? record.version : null,
+			hasUserDirectory: record.installDir !== undefined,
+			acp,
+			adapter: acp ? (record.adapter ?? "unknown") : null,
+			configured: isConfigured,
+			decision,
+			decidedAt: decision === null ? null : (record.decidedAt ?? null),
+			decisionStale,
+			// The same rule `interopProposals` applies, restated over the projected
+			// fields so the flag cannot drift from what the review would offer.
+			proposed: acp && record.presence === "present" && !isConfigured && (decision === null || decisionStale),
+			needsNetworkInstall: acp && record.adapter !== "present",
+		});
+	}
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		detectedAt: report.detectedAt,
+		knownKinds: INTEROP_AGENT_KINDS.length,
+		agents,
+	};
+}
+
+export async function runInteropInspect(args: ReadonlyArray<string>): Promise<number> {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder interop inspect: usage: clio-coder interop inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(await interopInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/interop.ts

@@ -0,0 +1,34 @@
+/**
+ * `clio-coder interop`, the read half of external coding agent detection.
+ *
+ * Reviewing and wiring a detected agent as a delegation peer is an interactive
+ * mutation and stays on `configure --interop`. This command family carries the
+ * read only, and its one subcommand is the fixed projection a GUI host may run.
+ */
+
+import { runInteropInspect } from "./interop-inspect.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder interop <subcommand>
+
+Detected external coding agents and how far each one is wired.
+
+Subcommands:
+  inspect --json                emit the detected agent inventory with no native paths
+
+Notes:
+  inspect writes nothing and runs no foreign executable. Wiring a detected agent
+  as a delegation peer is an explicit review: run \`clio-coder configure --interop\`.
+`;
+
+export async function runInteropCommand(args: ReadonlyArray<string>): Promise<number> {
+	const sub = args[0];
+	if (sub === undefined || sub === "--help" || sub === "-h") {
+		process.stdout.write(HELP);
+		return sub === undefined ? 2 : 0;
+	}
+	if (sub === "inspect") return await runInteropInspect(args.slice(1));
+	printError(`unknown interop command: ${sub}`);
+	process.stdout.write(HELP);
+	return 2;
+}