@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/overlays/decisions.ts

@@ -0,0 +1,300 @@
+import type { DecisionLedgerEntry, DecisionRecord } from "../../domains/session/entries.js";
+import {
+	type Component,
+	Input,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "../../engine/tui.js";
+import { buildHint, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, GLYPH, rule } from "../theme/index.js";
+
+const DEFAULT_CONTENT_WIDTH = 88;
+
+export const DECISIONS_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
+
+export interface DecisionSelection {
+	interviewId: string;
+	key: string;
+	label: string;
+	value: string;
+}
+
+/** The operator-authored turn that makes a durable correction visible to the model. */
+export function formatDecisionCorrectionTurn(selection: DecisionSelection, correction: string): string {
+	return `Decision "${selection.label}" (previously: ${selection.value}) is superseded by the operator. New direction: ${correction}. Acknowledge and adjust the plan.`;
+}
+
+export interface OpenDecisionsOverlayOptions {
+	onSupersede: (selection: DecisionSelection) => void;
+	onCorrection: (selection: DecisionSelection, correction: string) => void;
+	onClose: () => void;
+	requestRender?: () => void;
+	now?: () => number;
+}
+
+interface SelectableDecision {
+	interview: DecisionLedgerEntry;
+	decision: DecisionRecord;
+}
+
+function fitLine(text: string, width: number): string {
+	const safeWidth = Math.max(1, Math.floor(width));
+	return visibleWidth(text) <= safeWidth ? text : truncateToWidth(text, safeWidth, "…", true);
+}
+
+function relativeTime(timestamp: string, now: number): string {
+	const value = Date.parse(timestamp);
+	if (!Number.isFinite(value)) return "unknown time";
+	const seconds = Math.max(0, Math.floor((now - value) / 1000));
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	return `${Math.floor(hours / 24)}d ago`;
+}
+
+function selectionFor(row: SelectableDecision): DecisionSelection {
+	return {
+		interviewId: row.interview.interviewId,
+		key: row.decision.key,
+		label: row.decision.label ?? row.decision.key,
+		value: row.decision.value,
+	};
+}
+
+function selectableRows(interviews: ReadonlyArray<DecisionLedgerEntry>): SelectableDecision[] {
+	return interviews.flatMap((interview) => interview.decisions.map((decision) => ({ interview, decision })));
+}
+
+function interviewHeader(interview: DecisionLedgerEntry, width: number, now: number): string[] {
+	const theme = clioTheme();
+	const rounds = `${interview.roundCount} round${interview.roundCount === 1 ? "" : "s"}`;
+	const status =
+		interview.interviewStatus === "complete" ? theme.fg("success", "complete") : theme.fg("warning", "cancelled");
+	const heading = `${theme.fg("accent", relativeTime(interview.endedAt, now))}${theme.fg("dim", " · ")}${theme.fg("muted", rounds)}${theme.fg("dim", " · ")}${status}`;
+	const lines = [fitLine(heading, width)];
+	if (interview.summary) {
+		lines.push(...wrapTextWithAnsi(theme.fg("dim", interview.summary), width).map((line) => fitLine(line, width)));
+	}
+	return lines;
+}
+
+function decisionLines(decision: DecisionRecord, selected: boolean, expanded: boolean, width: number): string[] {
+	const theme = clioTheme();
+	const cursor = selected ? theme.fg("accent", GLYPH.cursor) : " ";
+	const status = decision.status === "active" ? theme.fg("success", GLYPH.ok) : theme.fg("dim", GLYPH.cancelled);
+	const labelText = decision.label ?? decision.key;
+	const label = decision.status === "superseded" ? theme.fg("dim", labelText) : theme.fg("muted", labelText);
+	const value = decision.status === "superseded" ? theme.fg("dim", decision.value) : decision.value;
+	const lines = [fitLine(`${cursor} ${status} ${label}${theme.fg("dim", ":")} ${value}`, width)];
+	if (decision.status === "superseded" && decision.correction) {
+		lines.push(fitLine(`      ${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`, width));
+	}
+	if (selected && expanded) {
+		if (decision.source_question) {
+			lines.push(
+				...wrapTextWithAnsi(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`, width).map(
+					(line) => fitLine(`      ${line}`, width),
+				),
+			);
+		}
+		lines.push(
+			...wrapTextWithAnsi(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`, width).map((line) =>
+				fitLine(`      ${line}`, width),
+			),
+		);
+	}
+	return lines;
+}
+
+export function formatDecisionsOverlayBodyLines(
+	interviews: ReadonlyArray<DecisionLedgerEntry>,
+	selectedIndex = 0,
+	expandedKey: string | null = null,
+	contentWidth = DEFAULT_CONTENT_WIDTH,
+	now = Date.now(),
+): string[] {
+	const width = Math.max(1, Math.floor(contentWidth));
+	const theme = clioTheme();
+	if (interviews.length === 0) {
+		return [
+			...wrapTextWithAnsi(theme.fg("muted", "No interview decisions have been recorded on this branch."), width),
+			"",
+			...wrapTextWithAnsi(theme.fg("dim", "Completed and cancelled ask_user interviews appear here."), width),
+		].map((line) => fitLine(line, width));
+	}
+	const selected = selectableRows(interviews)[selectedIndex];
+	const lines: string[] = [];
+	for (let interviewIndex = 0; interviewIndex < interviews.length; interviewIndex += 1) {
+		const interview = interviews[interviewIndex];
+		if (!interview) continue;
+		if (interviewIndex > 0) lines.push(rule(theme, width));
+		lines.push(...interviewHeader(interview, width, now));
+		if (interview.decisions.length === 0) {
+			lines.push(fitLine(`  ${theme.fg("dim", "No compact decisions were recorded.")}`, width));
+			continue;
+		}
+		for (const decision of interview.decisions) {
+			const isSelected =
+				selected?.interview.interviewId === interview.interviewId && selected.decision.key === decision.key;
+			const rowKey = `${interview.interviewId}:${decision.key}`;
+			lines.push(...decisionLines(decision, isSelected, isSelected && expandedKey === rowKey, width));
+		}
+	}
+	return lines;
+}
+
+class DecisionsOverlayBody implements Component {
+	private selectedIndex = 0;
+	private expandedKey: string | null = null;
+	private correctionInput: Input | null = null;
+	private status = "";
+
+	constructor(
+		private readonly getInterviews: () => ReadonlyArray<DecisionLedgerEntry>,
+		private readonly options: OpenDecisionsOverlayOptions,
+	) {}
+
+	render(width: number): string[] {
+		const interviews = this.readInterviews();
+		const rows = selectableRows(interviews);
+		this.selectedIndex = Math.max(0, Math.min(this.selectedIndex, Math.max(0, rows.length - 1)));
+		const body = formatDecisionsOverlayBodyLines(
+			interviews,
+			this.selectedIndex,
+			this.expandedKey,
+			width,
+			this.options.now?.() ?? Date.now(),
+		);
+		if (this.correctionInput) {
+			const theme = clioTheme();
+			body.push("", fitLine(theme.fg("accent", "New direction"), width));
+			body.push(
+				...this.correctionInput
+					.render(Math.max(1, width))
+					.map((line) =>
+						fitLine(line.startsWith("> ") ? `${theme.fg("accent", `${GLYPH.cursor} `)}${line.slice(2)}` : line, width),
+					),
+			);
+		}
+		if (this.status) body.push("", fitLine(clioTheme().fg("warning", this.status), width));
+		return body;
+	}
+
+	handleInput(data: string): void {
+		if (this.correctionInput) {
+			this.correctionInput.handleInput(data);
+			return;
+		}
+		const rows = selectableRows(this.readInterviews());
+		if (matchesKey(data, "esc")) {
+			this.options.onClose();
+			return;
+		}
+		if (rows.length === 0) return;
+		if (matchesKey(data, "up")) {
+			this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+			this.expandedKey = null;
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.selectedIndex = Math.min(rows.length - 1, this.selectedIndex + 1);
+			this.expandedKey = null;
+			this.requestRender();
+			return;
+		}
+		const selected = rows[this.selectedIndex];
+		if (!selected) return;
+		if (matchesKey(data, "enter") || data === "\n") {
+			const key = `${selected.interview.interviewId}:${selected.decision.key}`;
+			this.expandedKey = this.expandedKey === key ? null : key;
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "s")) {
+			try {
+				this.options.onSupersede(selectionFor(selected));
+				this.status = "Decision superseded.";
+			} catch (error) {
+				this.status = error instanceof Error ? error.message : String(error);
+			}
+			this.requestRender();
+			return;
+		}
+		if (matchesKey(data, "c")) this.beginCorrection(selected);
+	}
+
+	invalidate(): void {
+		this.correctionInput?.invalidate();
+	}
+
+	footerHint(): string {
+		return this.correctionInput
+			? buildHint([{ key: "Enter", verb: "submit" }])
+			: buildHint([
+					{ key: "↑↓", verb: "select" },
+					{ key: "Enter", verb: "expand" },
+					{ key: "s", verb: "supersede" },
+					{ key: "c", verb: "correct" },
+				]);
+	}
+
+	private readInterviews(): ReadonlyArray<DecisionLedgerEntry> {
+		try {
+			return this.getInterviews();
+		} catch (error) {
+			this.status = error instanceof Error ? error.message : String(error);
+			return [];
+		}
+	}
+
+	private beginCorrection(selected: SelectableDecision): void {
+		const input = new Input();
+		input.onSubmit = (value) => {
+			const correction = value.trim();
+			if (correction.length === 0) {
+				this.status = "Enter the operator's new direction.";
+				this.requestRender();
+				return;
+			}
+			try {
+				this.options.onCorrection(selectionFor(selected), correction);
+			} catch (error) {
+				this.status = error instanceof Error ? error.message : String(error);
+				this.requestRender();
+			}
+		};
+		input.onEscape = () => this.options.onClose();
+		this.correctionInput = input;
+		this.status = "";
+		this.requestRender();
+	}
+
+	private requestRender(): void {
+		this.options.requestRender?.();
+	}
+}
+
+/** Mount the settled interview decision board. */
+export function openDecisionsOverlay(
+	tui: TUI,
+	getInterviews: () => ReadonlyArray<DecisionLedgerEntry>,
+	options: OpenDecisionsOverlayOptions,
+): OverlayHandle {
+	const body = new DecisionsOverlayBody(getInterviews, {
+		...options,
+		requestRender: options.requestRender ?? (() => tui.requestRender()),
+	});
+	return showClioOverlayFrame(tui, body, {
+		anchor: "center",
+		width: DECISIONS_OVERLAY_WIDTH,
+		title: () => "Decisions",
+		footerHint: () => body.footerHint(),
+	});
+}

package/src/interactive/overlays/extensions.ts

@@ -0,0 +1,54 @@
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { SlashCommandContext } from "../slash-commands.js";
+import { clioTheme } from "../theme/index.js";
+import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+/** @internal exported for contract tests */
+export const EXTENSIONS_EMPTY =
+	"no extensions installed. install one with `clio-coder extensions install <path>`, then `clio-coder extensions list` shows what it contributed.";
+
+export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClose: () => void): OverlayHandle {
+	const list = ctx.listExtensions?.() ?? [];
+	const items: ListOverlayItem[] = list.map((ext) => {
+		const state = !ext.enabled ? "disabled" : ext.effective ? "active" : `shadowed:${ext.overriddenBy ?? "higher"}`;
+
+		let meta = state;
+		if (state === "active") {
+			meta = clioTheme().fg("success", "active");
+		} else if (state === "disabled") {
+			meta = clioTheme().fg("dim", "disabled");
+		} else {
+			meta = clioTheme().fg("warning", state);
+		}
+
+		const label = `${ext.id.padEnd(22)} ${ext.scope.padEnd(7)} ${ext.description}`;
+
+		return {
+			id: ext.id,
+			label,
+			meta,
+			group: "Extensions",
+			detail: () => {
+				const lines = [
+					`# Extension: ${ext.id}`,
+					`**Version:** ${ext.version}`,
+					`**Scope:** ${ext.scope}`,
+					`**Description:** ${ext.description}`,
+					`**State:** ${state}`,
+				];
+				if (ext.overriddenBy) {
+					lines.push(`**Overridden By:** ${ext.overriddenBy}`);
+				}
+				return lines;
+			},
+		};
+	});
+
+	return openListOverlay(tui, {
+		title: "Extensions Reference",
+		items,
+		filterable: true,
+		emptyMessage: EXTENSIONS_EMPTY,
+		onClose,
+	});
+}

package/src/interactive/overlays/help-reference.ts

@@ -0,0 +1,145 @@
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { ClioKeybindingManager } from "../keybinding-manager.js";
+import { commandReference, SLASH_COMMAND_GROUPS } from "../slash-commands.js";
+import { formatKeybindingDetailBodyLines } from "./keybinding-detail.js";
+import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+function formatKey(raw: string): string {
+	if (raw === "(unbound)") return raw;
+	return raw
+		.split(" / ")
+		.map((single) =>
+			single
+				.split("+")
+				.map((segment) => {
+					const head = segment.charAt(0);
+					return head.length === 0 ? segment : head.toUpperCase() + segment.slice(1);
+				})
+				.join("+"),
+		)
+		.join(" / ");
+}
+
+export function openHelpOverlay(
+	tui: TUI,
+	manager: ClioKeybindingManager,
+	onClose: () => void,
+	initialFilter?: string,
+): OverlayHandle {
+	// Commands are grouped by the verb they perform, in SLASH_COMMAND_GROUPS
+	// order, and keep registry order inside each group.
+	const groupRank = new Map(SLASH_COMMAND_GROUPS.map((group, index) => [group, index] as const));
+	const commands: ListOverlayItem[] = [...commandReference()]
+		.sort((a, b) => (groupRank.get(a.group) ?? 0) - (groupRank.get(b.group) ?? 0))
+		.map((ref) => {
+			const usagePart = ref.usage.length >= 30 ? `${ref.usage} ` : ref.usage.padEnd(30);
+			const label = `${usagePart}${ref.description}`;
+			const item: ListOverlayItem = {
+				id: ref.name,
+				label,
+				group: ref.group,
+				// Overlay key actions are deliberately not duplicated here: each
+				// overlay's footer hint is the live source of its keys, and a static
+				// copy would rot exactly like the old SLASH_HOTKEYS table did.
+				detail: () => [`# Command: /${ref.name}`, `**Usage:** \`${ref.usage}\``, `**Description:** ${ref.description}`],
+			};
+			return item;
+		});
+
+	const conflicts = manager.getConflicts();
+	const keys: ListOverlayItem[] = manager.hotkeyEntries().map((row) => {
+		const formattedKeys = formatKey(row.keys);
+		const keysPart = formattedKeys.length >= 24 ? `${formattedKeys} ` : formattedKeys.padEnd(24);
+		const label = `${keysPart}${row.description}`;
+
+		const item: ListOverlayItem = {
+			id: row.id,
+			label,
+			group: "Keys",
+			detail: (width) => {
+				const warnings = manager
+					.platformWarnings()
+					.filter((w) => w.id === row.id)
+					.map((w) => `${w.keys.map(formatKey).join(" / ")} may not fire: ${w.reason}`);
+				const detailEntry = {
+					id: row.id,
+					keys: formattedKeys,
+					action: row.description,
+					source: row.source,
+					warnings,
+				};
+				return formatKeybindingDetailBodyLines(detailEntry, width);
+			},
+		};
+
+		const metaParts: string[] = [];
+		if (row.source === "user") metaParts.push("user");
+		const hasConflict = conflicts.some((c) => c.keybindings.includes(row.id));
+		if (hasConflict) metaParts.push("conflict");
+		if (metaParts.length > 0) {
+			item.meta = metaParts.join(", ");
+		}
+
+		return item;
+	});
+
+	// Static concept topics. Unlike commands and keys these are not generated
+	// from a registry; keep each detail consistent with the enforced behavior
+	// and with the live footer hints on the surface it documents.
+	const topics: ListOverlayItem[] = [
+		{
+			id: "topic-fleet-runs",
+			label: `${"fleet runs & steering".padEnd(30)}Inspect, guide, and cancel delegated workers`,
+			group: "Topics",
+			detail: () => [
+				"# Fleet runs & steering",
+				"**Fleet Runs board**: open it with the configured Dispatch Board key (Alt+W by default). Use Up/Down or `j`/`k` to select a live or recent run.",
+				"**Steer**: press `s` on a live native run to close the board and prefill `@<runId> `. Add guidance and submit it normally. The first notice means queued; a received notice confirms worker delivery.",
+				"**Cancel**: press `x` on a running, stale, queued, or retry-waiting run. The row changes to cancelling while the worker or retry is being stopped.",
+				"**Capabilities**: ACP delegation runs cannot accept live steering. The board footer only advertises actions supported by the selected row.",
+				"**Tasks versus runs**: `/tasks` shows the agent's plan steps. Fleet runs are concrete delegated worker executions and remain in this board as recent terminal history.",
+			],
+		},
+		{
+			id: "topic-steering-modes",
+			label: `${"steering modes".padEnd(30)}Interrupt, next slot, or end of turn: when a message lands mid-run`,
+			group: "Topics",
+			detail: () => [
+				"# Steering modes",
+				"While Clio is running, the key that submits a message chooses when it lands. The default is next slot.",
+				"**Next slot** (Enter): the message is delivered between tool batches, mid-run. The agent keeps going and reads it before its next model call.",
+				"**End of turn** (Alt+Enter by default): the message waits until the whole run settles and Clio would hand control back, then starts the next round.",
+				"**Interrupt** (Alt+I by default, or Ctrl+G then i): cancels the in-flight work the way Esc does, including a running bash child, then delivers the message as a fresh prompt. Anything already queued returns to the editor.",
+				"**Interrupt is refused** while an attached dispatch is running (the abort would kill the worker's run with no receipt; steer it with `@<agent>` or cancel it with Esc) and while a permission ask is parked (it is already waiting on you). In both cases the message is queued for the next slot and a notice says why.",
+				"**Alt+Up** restores queued messages to the editor. Workers accept next-slot steering only, through `@<agent>`.",
+			],
+		},
+		{
+			id: "topic-autonomy",
+			label: `${"autonomy & safety net".padEnd(30)}How the autonomy level and the always-on guardrails interact`,
+			group: "Topics",
+			detail: () => [
+				"# Autonomy & safety net",
+				"**Tool surface**: which tools exist at all through registration, tool profiles, skill narrowing, and dispatch admission. " +
+					"Violations are terminal denials, never approvable.",
+				"**Safety net** (always on, level-independent): damage-control rules, path policy for secrets and system paths, " +
+					"command-substitution confirmation, and `git_destructive` blocks. Blocks are final at every level; confirm rails ask at every level.",
+				"**Autonomy level** (`/settings`, persisted as `autonomy`): the operator's standing grant per action class for actions the net passed, " +
+					"enforced by the harness at tool admission. read-only denies non-read, suggest parks every non-read call, " +
+					"auto-edit parks unrecognized commands, and full-auto runs them.",
+				"**Approvals**: a parked call waits for a one-shot operator decision; approving resumes only that call. " +
+					"Workers resolve asks per `workers.onPermission` (Approvals Routing); headless runs auto-deny.",
+			],
+		},
+	];
+
+	const items = [...commands, ...keys, ...topics];
+
+	return openListOverlay(tui, {
+		title: "Help Center",
+		items,
+		filterable: true,
+		...(initialFilter ? { initialFilter } : {}),
+		onClose,
+	});
+}

package/src/interactive/overlays/interop.ts

@@ -0,0 +1,139 @@
+import type { InteropAgentId, InteropContract, InteropProposal, InteropReport } from "../../domains/interop/index.js";
+import { INHERITED_PROJECT_CONTEXT, renderProposalEntry } from "../../domains/interop/index.js";
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { SlashCommandContext } from "../slash-commands.js";
+import { clioTheme } from "../theme/index.js";
+import { type ListOverlayHandle, type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+/** @internal exported for contract tests */
+export const INTEROP_EMPTY =
+	"no other coding agents detected on this machine. install one, then `/interop` proposes it as a delegation peer.";
+
+const GROUP_DETECTED = "Detected";
+const GROUP_CONFIGURED = "Configured";
+const GROUP_DECLINED = "Declined";
+
+export interface InteropOverlayDeps {
+	report: () => InteropReport | null;
+	proposals: () => ReadonlyArray<InteropProposal>;
+	configured: () => ReadonlyArray<{ id: string; command: string; args: ReadonlyArray<string> }>;
+	accept: (kind: InteropAgentId) => void;
+	decline: (kind: InteropAgentId) => void;
+	onClose: () => void;
+}
+
+/**
+ * The overlay's view of the interop domain, built from the contract alone.
+ *
+ * Detected and Configured partition the same agents, and the frame that follows
+ * a keystroke draws both. Reading the wired peers from the TUI's hot settings
+ * snapshot put them a config-watcher tick behind the proposals, which read the
+ * file: an accepted agent left Detected immediately and reached Configured only
+ * on the next time the overlay was opened. Taking one source is what keeps the
+ * two lists describing one moment.
+ */
+export function interopOverlaySurface(
+	interop: InteropContract,
+	notify: (level: "success" | "warning", text: string) => void,
+): Omit<InteropOverlayDeps, "onClose"> {
+	return {
+		report: () => interop.lastReport(),
+		proposals: () => {
+			const report = interop.lastReport();
+			return report === null ? [] : interop.proposals(report);
+		},
+		configured: () => interop.configured(),
+		accept: (kind) => {
+			const result = interop.accept([kind]);
+			for (const id of result.wired) notify("success", `delegation agent ${id} added`);
+			for (const diagnostic of result.diagnostics) notify("warning", diagnostic);
+		},
+		decline: (kind) => {
+			interop.decline([kind]);
+		},
+	};
+}
+
+function planLines(proposal: InteropProposal): string[] {
+	const lines = [
+		`# Connect ${proposal.label}`,
+		"This appends one entry to `delegation.agents`:",
+		"```yaml",
+		...renderProposalEntry(proposal).split("\n"),
+		"```",
+		`**projectContext:** ${INHERITED_PROJECT_CONTEXT} (inherited; the peer receives your task text, never the project projection)`,
+		"**toolGovernance:** clio-policy (its tool calls are gated by Clio safety)",
+	];
+	if (proposal.needsNetworkInstall) {
+		lines.push("**Adapter:** not installed locally; npx fetches it the first time you delegate");
+	}
+	lines.push("Press `a` to connect it, `d` to decline.");
+	return lines;
+}
+
+function buildItems(deps: InteropOverlayDeps): ListOverlayItem[] {
+	const theme = clioTheme();
+	const report = deps.report();
+	const items: ListOverlayItem[] = deps.proposals().map((proposal) => ({
+		id: proposal.kind,
+		label: `${proposal.entry.id.padEnd(16)}${[proposal.entry.command, ...proposal.entry.args].join(" ")}`,
+		meta: theme.fg("warning", "not configured"),
+		group: GROUP_DETECTED,
+		detail: () => planLines(proposal),
+	}));
+	for (const agent of deps.configured()) {
+		const command = [agent.command, ...agent.args].join(" ");
+		items.push({
+			id: `configured:${agent.id}`,
+			label: `${agent.id.padEnd(16)}${command}`,
+			meta: theme.fg("success", "connected"),
+			group: GROUP_CONFIGURED,
+			detail: () => [`# ${agent.id}`, `**Command:** \`${command}\``, `Delegate with \`/delegate ${agent.id} <task>\`.`],
+		});
+	}
+	for (const agent of report?.agents ?? []) {
+		if (agent.decision !== "declined" || agent.decidedFingerprint !== agent.fingerprint) continue;
+		items.push({
+			id: `declined:${agent.kind}`,
+			label: `${agent.kind.padEnd(16)}${agent.binary ?? agent.installDir ?? ""}`,
+			meta: theme.fg("dim", `declined ${agent.decidedAt ?? ""}`.trim()),
+			group: GROUP_DECLINED,
+			detail: () => [`# ${agent.kind}`, "Declined. Clio proposes it again when its binary version or path changes."],
+		});
+	}
+	return items;
+}
+
+export function openInteropOverlay(tui: TUI, ctx: SlashCommandContext, onClose: () => void): OverlayHandle {
+	const surface = ctx.interop;
+	const deps: InteropOverlayDeps = surface
+		? { ...surface, onClose }
+		: { report: () => null, proposals: () => [], configured: () => [], accept: () => {}, decline: () => {}, onClose };
+	const decide = (item: ListOverlayItem, action: (kind: InteropAgentId) => void): void => {
+		if (item.group !== GROUP_DETECTED) return;
+		action(item.id as InteropAgentId);
+		// The decision is already on disk; the rows are its projection. They are
+		// replaced rather than mutated in place, because the view memoizes the
+		// frame on the row set and a mutated array left the accepted or declined
+		// agent sitting under Detected until the next keystroke repainted it.
+		handle.setItems(buildItems(deps));
+	};
+
+	const handle: ListOverlayHandle = openListOverlay(tui, {
+		title: "Interop",
+		items: buildItems(deps),
+		filterable: true,
+		layout: "split",
+		emptyMessage: INTEROP_EMPTY,
+		hints: [
+			{ key: "a", verb: "connect" },
+			{ key: "d", verb: "decline" },
+		],
+		actions: {
+			a: (item) => decide(item, deps.accept),
+			d: (item) => decide(item, deps.decline),
+		},
+		onClose,
+	});
+	return handle;
+}