@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/interactive/overlays/extension-panel.ts

@@ -0,0 +1,70 @@
+import type { ExtensionPanel } from "../../domains/extensions/public-api.js";
+import { extensionPanelText } from "../../domains/extensions/runtime-schema.js";
+import {
+	type Component,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "../../engine/tui.js";
+import { buildHint, showClioOverlayFrame } from "../overlay-frame.js";
+
+/** Host-owned plain-text rendering. Extension code supplies no components or input handlers. */
+export class ExtensionPanelView implements Component {
+	private offset = 0;
+	private text: string;
+	constructor(
+		panel: ExtensionPanel,
+		private valid: () => boolean,
+		private refresh: () => void,
+		private close: () => void = () => {},
+	) {
+		this.text = extensionPanelText(panel);
+	}
+	render(width: number): string[] {
+		if (!this.valid()) return [truncateToWidth("Extension panel expired. Close it and invoke the command again.", width)];
+		const lines = this.text.split("\n").flatMap((line) => wrapTextWithAnsi(line, Math.max(1, width)));
+		this.offset = Math.min(this.offset, Math.max(0, lines.length - 12));
+		return lines.slice(this.offset, this.offset + 12).map((line) => truncateToWidth(line, width));
+	}
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.close();
+			return;
+		}
+		if (matchesKey(data, "down") || matchesKey(data, "pageDown")) this.offset += 5;
+		if (matchesKey(data, "up") || matchesKey(data, "pageUp")) this.offset = Math.max(0, this.offset - 5);
+		this.refresh();
+	}
+	invalidate(): void {}
+}
+export function openExtensionPanel(
+	tui: TUI,
+	owner: string,
+	panel: ExtensionPanel,
+	valid: () => boolean,
+	onClose?: () => void,
+): OverlayHandle {
+	let handle: OverlayHandle;
+	handle = showClioOverlayFrame(
+		tui,
+		new ExtensionPanelView(
+			panel,
+			valid,
+			() => tui.requestRender(),
+			() => {
+				if (onClose) onClose();
+				else handle.hide();
+			},
+		),
+		{
+			anchor: "center",
+			width: 88,
+			markerId: "extension-panel",
+			title: `Extension: ${owner}`,
+			footerHint: buildHint([{ key: "Up/Down", verb: "scroll" }]),
+		},
+	);
+	return handle;
+}

package/src/interactive/overlays/extensions.ts

@@ -17,12 +17,13 @@ export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClos
 				: !ext.enabled
 					? "disabled"
 					: ext.loadable
-						? "active"
+						? "eligible"
 						: `shadowed:${ext.overriddenBy ?? "higher"}`;
 
-		let meta = state;
-		if (state === "active") {
-			meta = clioTheme().fg("success", "active");
+		const runtime = ctx.operatorExtensions?.entries().find((entry) => entry.id === ext.id && entry.scope === ext.scope);
+		let meta = ext.runtime ? `${state}; runtime ${runtime?.state ?? "not started"}` : state;
+		if (state === "eligible") {
+			meta = clioTheme().fg("success", meta);
 		} else if (state === "disabled") {
 			meta = clioTheme().fg("dim", "disabled");
 		} else {
@@ -35,7 +36,7 @@ export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClos
 			id: ext.id,
 			label,
 			meta,
-			group: "Extensions",
+			group: "Harness extensions",
 			detail: () => {
 				const lines = [
 					`# Extension: ${ext.id}`,
@@ -44,6 +45,28 @@ export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClos
 					`**Description:** ${ext.description}`,
 					`**State:** ${state}`,
 				];
+				if (ext.runtime) {
+					lines.push(
+						`**Operator runtime:** ${runtime?.state ?? "not started"}; generation ${runtime?.generation ?? 0}`,
+						"Runtime code executes on interactive startup/reload after installation. It has your user account's authority; it is not an OS sandbox.",
+					);
+					if (runtime?.reason) lines.push(runtime.reason);
+					if (runtime?.status) lines.push(`**Status:** ${runtime.status.text}`);
+					for (const command of ctx.operatorExtensions
+						?.commands(ctx.listPrompts().items.map((prompt) => prompt.name))
+						.filter((row) => row.extensionId === ext.id) ?? [])
+						lines.push(`/${command.invocation}: ${command.description} (${command.available ? "ready" : command.reason})`);
+				}
+				if (ext.capabilities?.tools.length)
+					lines.push(`**Tool evidence:** ${runtime?.toolEvidence ?? "registry binding unknown in this view"}`);
+				for (const reason of runtime?.newSessionReasons ?? []) lines.push(reason);
+				lines.push(`Manage this copy: clio-coder extensions enable|disable|remove ${ext.id} --${ext.scope}`);
+				if (ext.capabilities?.tools.length)
+					lines.push(
+						`**Command tools:** ${ext.capabilities.tools.map((tool) => tool.name).join(", ")}`,
+						"Restart the session after changes to refresh tool schemas.",
+					);
+				for (const diagnostic of ext.diagnostics) lines.push(`**${diagnostic.type}:** ${diagnostic.message}`);
 				if (ext.overriddenBy) {
 					lines.push(`**Overridden By:** ${ext.overriddenBy}`);
 				}

package/src/interactive/overlays/fleet-run-approval.ts

@@ -17,7 +17,6 @@ import {
 	matchesKey,
 	type OverlayHandle,
 	type TUI,
-	truncateToWidth,
 	wrapTextWithAnsi,
 } from "../../engine/tui.js";
 import type { FleetRunPreview, FleetRunPreviewStep } from "../fleet-run-preview.js";
@@ -96,7 +95,7 @@ export function formatBudgetLine(preview: FleetRunPreview): string {
  * Render the body. Waves in order, each step with its facts, then the argv a
  * code step will actually run, and last the budget the run is admitted under.
  */
-function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: number, scroll: number): string[] {
+export function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: number, scroll: number): string[] {
 	const theme = clioTheme();
 	const contentWidth = Math.max(1, Math.floor(width));
 	const rows: string[] = [];
@@ -120,7 +119,12 @@ function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: num
 					rows.push(line);
 				}
 				if (step.argv !== undefined) {
-					rows.push(theme.fg("dim", truncateToWidth(`    argv ${step.argv.join(" ")}`, contentWidth, "…", false)));
+					rows.push(
+						...wrapTextWithAnsi(
+							theme.fg("dim", `    argv ${step.argv.map((arg) => JSON.stringify(arg)).join(" ")}`),
+							contentWidth,
+						),
+					);
 				}
 			}
 		}

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

@@ -1,4 +1,6 @@
+import type { ExtensionCommandRow } from "../../domains/extensions/operator-commands.js";
 import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import { CLOSED_ACTION_ORDER, GLOBAL_ACTION_ORDER } from "../application-controller.js";
 import type { ClioKeybindingManager } from "../keybinding-manager.js";
 import { commandReference, SLASH_COMMAND_GROUPS } from "../slash-commands.js";
 import { formatKeybindingDetailBodyLines } from "./keybinding-detail.js";
@@ -25,6 +27,7 @@ export function openHelpOverlay(
 	manager: ClioKeybindingManager,
 	onClose: () => void,
 	initialFilter?: string,
+	extensionCommands: readonly ExtensionCommandRow[] = [],
 ): OverlayHandle {
 	// Commands are grouped by the verb they perform, in SLASH_COMMAND_GROUPS
 	// order, and keep registry order inside each group.
@@ -46,54 +49,92 @@ export function openHelpOverlay(
 			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}`;
+	commands.push(
+		...extensionCommands.map((row) => ({
+			id: `extension:${row.invocation}`,
+			label: `/${row.invocation}  ${row.description}`,
+			group: "Operator extensions",
+			meta: row.available ? "ready" : "unavailable",
+			detail: () => [
+				`# /${row.invocation}`,
+				`Owner: ${row.extensionId} (${row.scope}); operator generation ${row.generation}`,
+				row.available ? "Runs installed operator code; results stay local to you." : (row.reason ?? "Runtime unavailable"),
+			],
+		})),
+	);
 
-		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 keyItems = (): ListOverlayItem[] => {
+		const conflicts = manager.getConflicts();
+		const keys: ListOverlayItem[] = manager.hotkeyEntries().map((row) => {
+			const formattedKeys = formatKey(manager.actionLabel(row.id));
+			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}`);
+					for (const conflict of conflicts.filter((entry) => entry.keybindings.includes(row.id))) {
+						const appOrder = ["clio-coder.leader", ...CLOSED_ACTION_ORDER, ...GLOBAL_ACTION_ORDER].filter((id) =>
+							conflict.keybindings.includes(id),
+						);
+						warnings.push(
+							`${conflict.key}: ${conflict.keybindings.join(", ")}. Cancellation and the menu trigger take priority; outside the menu, the focused dialog owns input. Composer history precedes other application actions, then editing.${appOrder.length > 1 ? ` Composer app precedence: ${appOrder.join(" before ")}.` : ""}`,
+						);
+					}
+					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(", ");
-		}
+			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;
-	});
+			return item;
+		});
+
+		return keys;
+	};
 
 	// 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-keyboard-migration",
+			label: "keyboard migration             Defaults, action menu, editing and explicit overrides",
+			group: "Topics",
+			detail: () => [
+				"# Keyboard migration",
+				"Default keys: Alt+L Library, Alt+M model, Shift+Tab effort, Ctrl+Q follow-up, Alt+Q recovery. Alt+B/D and Home/End now edit the composer.",
+				`The persistent action menu is ${manager.actionLabel("clio-coder.leader")}. Fixed suffixes work independently of direct key overrides; arrows and Enter reach every available entry.`,
+				"Existing configured action IDs are preserved. Explicit [] disables an action's direct and menu routes. This help lists your effective keys; settings are never rewritten.",
+				"Pasted slash and bang text remains literal until a deliberate submit. Ctrl+R searches the fullscreen transcript; Ctrl+C closes focused search or a dialog before cancelling other work.",
+			],
+		},
 		{
 			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.",
+				`**Fleet Runs board**: ${manager.actionLabel("clio-coder.dispatchBoard.toggle")}. Use Up/Down or j/k to select a live or recent run.`,
 				"**Enter**: on a live run in a `--with-panes` session, Enter opens (or retargets) the watch pane beside Clio, rendering that run's stream; the arrow keys then move it between runs. On a finished run, or without panes, Enter toggles the inline worker-progress detail instead.",
 				"**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.",
@@ -108,7 +149,7 @@ export function openHelpOverlay(
 			detail: () => [
 				"# Panes & files",
 				"**Where it works**: a session started inside a herdr pane with `clio-coder --with-panes` (or `interface.panes.enabled: auto`). Outside herdr `/files` still works as a full-screen pick that returns to the composer; `/panes open logs|shell` do not.",
-				"**Files pane**: `/files` or the Files toggle key (Alt+E by default) opens the file view below the session and moves the keyboard into it; the same key or command closes it. `/files pick` borrows it for one selection. It is off until `interface.panes.files.enabled` is `true`.",
+				`**Files pane**: /files or ${manager.actionLabel("clio-coder.files.toggle")} opens Yazi from Clio focus. Yazi and the host own keys until Ctrl+Y returns selected paths and focus. Close the pane from Clio with the same action. /files pick borrows it for one selection.`,
 				"**Picking**: navigate, select with Space for several, then Ctrl+Y (or Enter in pick mode). The paths land in the composer as `@file` mentions and the keyboard returns to the composer.",
 				"**Logs and shell**: `/panes open logs` follows the newest dispatched run's journal; `/panes open shell` opens a shell in the workspace. A second open focuses the pane that is already there. `/panes close <name|all>` closes them; `/quit` closes the docks it manages (files, workers), leaves a shell or logs pane you opened, and prints which panes it left and how to close them.",
 				"**Engine**: the files pane runs a vendored file manager installed with `clio-coder tools install yazi`; `clio-coder doctor` and `/panes` say whether it resolved.",
@@ -122,10 +163,10 @@ export function openHelpOverlay(
 				"# 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.",
+				`**End of turn** (${manager.actionLabel("clio-coder.message.followUp")}): wait until the whole run settles, then start the next round.`,
+				`**Interrupt** (${manager.actionLabel("clio-coder.message.interrupt")} or /interrupt <text>): settle active work and deliver a fresh prompt. Queued messages return ahead of any newer draft.`,
 				"**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>`.",
+				`**Recover queues**: ${manager.actionLabel("clio-coder.message.dequeue")}. Workers accept next-slot steering through @<agent>.`,
 			],
 		},
 		{
@@ -151,9 +192,9 @@ export function openHelpOverlay(
 		},
 	];
 
-	const items = [...commands, ...keys, ...topics];
+	const items = [...commands, ...keyItems(), ...topics];
 
-	return openListOverlay(tui, {
+	const handle = openListOverlay(tui, {
 		markerId: "help",
 		title: "Help Center",
 		items,
@@ -161,4 +202,12 @@ export function openHelpOverlay(
 		...(initialFilter ? { initialFilter } : {}),
 		onClose,
 	});
+	const unsubscribe = manager.onReload(() => handle.setItems([...commands, ...keyItems(), ...topics]));
+	return {
+		...handle,
+		hide() {
+			unsubscribe();
+			handle.hide();
+		},
+	};
 }

package/src/interactive/overlays/interop.ts

@@ -1,5 +1,13 @@
 import type { InteropAgentId, InteropContract, InteropProposal, InteropReport } from "../../domains/interop/index.js";
-import { INHERITED_PROJECT_CONTEXT, renderProposalEntry } from "../../domains/interop/index.js";
+import {
+	type AdoptionKind,
+	applyInteropAdoption,
+	detectInteropAgents,
+	INHERITED_PROJECT_CONTEXT,
+	type InteropAdoptionPlan,
+	planInteropAdoption,
+	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";
@@ -9,6 +17,7 @@ import { type ListOverlayHandle, type ListOverlayItem, openListOverlay } from ".
 export const INTEROP_EMPTY =
 	"no other coding agents detected on this machine. install one, then `/interop` proposes it as a delegation peer.";
 
+const GROUP_INVENTORY = "Inventory";
 const GROUP_DETECTED = "Detected";
 const GROUP_CONFIGURED = "Configured";
 const GROUP_DECLINED = "Declined";
@@ -101,14 +110,83 @@ function buildItems(deps: InteropOverlayDeps): ListOverlayItem[] {
 			detail: () => [`# ${agent.kind}`, "Declined. Clio proposes it again when its binary version or path changes."],
 		});
 	}
+	for (const agent of report?.agents ?? []) {
+		if (!agent.inventory) continue;
+		const counts = agent.inventory.items.reduce<Record<string, number>>((out, item) => {
+			out[item.kind] = (out[item.kind] ?? 0) + 1;
+			return out;
+		}, {});
+		items.push({
+			id: `inventory:${agent.kind}`,
+			label: agent.kind,
+			group: GROUP_INVENTORY,
+			meta: `${agent.inventory.items.length} resources`,
+			detail: () => [
+				`# What would you like to adopt from ${agent.kind}?`,
+				`Presence: ${agent.presence}. Version: ${agent.version ?? "unknown"}. Inventory: ${agent.inventory?.status}.`,
+				...Object.entries(counts).map(([kind, count]) => `${count} ${kind}`),
+				"Press i to review an adoption plan. Press p for project destination, u for user, c to change the kind filter.",
+				...(agent.inventory?.items.map((item) => `${item.scope} ${item.kind}: ${item.name}`) ?? []),
+				...(agent.inventory?.diagnostics ?? []),
+			],
+		});
+	}
 	return items;
 }
 
 export function openInteropOverlay(tui: TUI, ctx: SlashCommandContext, onClose: () => void): OverlayHandle {
+	let closed = false;
+	let fresh: InteropReport | undefined;
+	let pending: InteropAdoptionPlan | undefined;
+	let scope: "user" | "project" = "user";
+	let filter: AdoptionKind | undefined;
 	const surface = ctx.interop;
 	const deps: InteropOverlayDeps = surface
 		? { ...surface, onClose }
 		: { report: () => null, proposals: () => [], configured: () => [], accept: () => {}, decline: () => {}, onClose };
+	const originalReport = deps.report;
+	deps.report = () => fresh ?? originalReport();
+	const close = (): void => {
+		closed = true;
+		pending = undefined;
+		onClose();
+	};
+	const reset = (): void => {
+		pending = undefined;
+		handle.setItems(buildItems(deps));
+	};
+	const preview = (item: ListOverlayItem): void => {
+		const host = item.id.replace(/^inventory:/, "") as InteropAgentId;
+		const inventory = deps.report()?.agents.find((agent) => agent.kind === host)?.inventory;
+		if (!inventory) return;
+		pending = planInteropAdoption({ host, inventory, scope, ...(filter ? { kind: filter } : {}) });
+		handle.setItems([
+			{
+				id: "approval",
+				label: `Adopt ${pending.entries.filter((entry) => entry.action === "install").length} resources?`,
+				meta: scope,
+				detail: () => [
+					"# Install this reviewed plan?",
+					"Press y to approve. Press b to return without installing.",
+					"Host files are unchanged. Foreign resources keep the project-import trust gate.",
+				],
+			},
+			...pending.entries.map((entry, index) => ({
+				id: `plan:${index}`,
+				label: `${entry.action}: ${entry.item.name}`,
+				meta: entry.item.kind,
+				detail: () => [
+					`# ${entry.action} ${entry.item.name}`,
+					`Source: ${entry.item.path}`,
+					`Source scope: ${entry.item.scope}`,
+					...(entry.destination ? [`Destination: ${entry.destination}`, `SHA-256: ${entry.digest}`] : []),
+					entry.reason,
+					...(entry.requirements?.length ? [`Requires installed packages: ${entry.requirements.join(", ")}`] : []),
+					...(entry.omitted ?? []).map((file) => `Skip ${file}: executable, host-specific, or non-text data.`),
+				],
+			})),
+		]);
+	};
 	const decide = (item: ListOverlayItem, action: (kind: InteropAgentId) => void): void => {
 		if (item.group !== GROUP_DETECTED) return;
 		action(item.id as InteropAgentId);
@@ -121,20 +199,61 @@ export function openInteropOverlay(tui: TUI, ctx: SlashCommandContext, onClose:
 
 	const handle: ListOverlayHandle = openListOverlay(tui, {
 		markerId: "interop",
-		title: "Interop",
+		title: "What would you like to adopt or connect?",
 		items: buildItems(deps),
 		filterable: true,
+		explicitSearch: true,
 		layout: "split",
 		emptyMessage: INTEROP_EMPTY,
 		hints: [
+			{ key: "c", verb: "kind filter" },
+			{ key: "i", verb: "plan adoption" },
+			{ key: "y", verb: "approve plan" },
+			{ key: "b", verb: "back" },
 			{ key: "a", verb: "connect" },
 			{ key: "d", verb: "decline" },
 		],
 		actions: {
+			i: preview,
+			p: () => {
+				scope = "project";
+				reset();
+				ctx.notice("info", "Adoption destination: project.");
+			},
+			u: () => {
+				scope = "user";
+				reset();
+				ctx.notice("info", "Adoption destination: user.");
+			},
+			c: () => {
+				const kinds: Array<AdoptionKind | undefined> = [undefined, "skill", "agent", "prompt", "plugin"];
+				filter = kinds[(kinds.indexOf(filter) + 1) % kinds.length];
+				reset();
+				ctx.notice("info", `Adoption kind: ${filter ?? "all"}.`);
+			},
+			b: reset,
+			y: () => {
+				if (!pending) return;
+				const plan = pending;
+				pending = undefined;
+				const result = applyInteropAdoption(plan, true);
+				for (const id of result.installed) ctx.notice("info", `Installed ${id}.`);
+				for (const diagnostic of result.diagnostics) ctx.notice("warn", diagnostic);
+				reset();
+			},
 			a: (item) => decide(item, deps.accept),
 			d: (item) => decide(item, deps.decline),
 		},
-		onClose,
+		onClose: close,
 	});
+	void detectInteropAgents({ inventory: true, probeVersion: true })
+		.then((report) => {
+			if (closed) return;
+			fresh = report;
+			if (!pending) handle.setItems(buildItems(deps));
+		})
+		.catch((error) => {
+			if (!closed) ctx.notice("warn", `Inventory unavailable: ${String(error)}`);
+		});
 	return handle;
 }

package/src/interactive/overlays/keybinding-detail.ts

@@ -72,12 +72,12 @@ export function formatKeybindingDetailBodyLines(entry: KeybindingDetailEntry, co
 	lines.push("");
 	for (const detail of row(
 		"Change",
-		"Edit settings.yaml under keybindings, then restart Clio or reopen the TUI.",
+		"Edit settings.yaml under interface.keybindings; changes reload live. [] disables direct and leader access; commands remain. Fixed leader suffixes do not follow direct remaps.",
 		contentWidth,
 	)) {
 		lines.push(detail);
 	}
-	if (entry.id.startsWith("clio.")) {
+	if (entry.id.startsWith("clio-coder.")) {
 		const example = `${entry.id}: "alt+<key>"`;
 		lines.push(...row("Example", example, contentWidth));
 	}

package/src/interactive/overlays/library-lifecycle.ts

@@ -0,0 +1,90 @@
+/**
+ * The browser's binding to the package lifecycle.
+ *
+ * The overlay never calls a writer directly. It builds a plan, renders it, and
+ * either applies or releases it, which is what keeps "cancel wrote nothing" a
+ * property of the code rather than a promise in a docstring.
+ *
+ * Types and functions come from `src/domains/resources` unchanged. The UI adds
+ * no lifecycle semantics of its own: no second planner, no fallback writer, and
+ * no shape it maintains in parallel with the domain.
+ */
+
+import type {
+	LibraryApplyResult,
+	LibraryLifecyclePlan,
+	LibraryLifecycleRequest,
+	LibraryRefreshHost,
+	LibraryRefreshResult,
+} from "../../domains/resources/index.js";
+import {
+	applyLibraryLifecycle,
+	planLibraryLifecycle,
+	releaseLibraryLifecycle,
+	retryLibraryRefresh,
+} from "../../domains/resources/index.js";
+
+export type {
+	LibraryApplyResult,
+	LibraryLifecyclePlan,
+	LibraryLifecycleRequest,
+	LibraryOperation,
+	LibraryPackageIdentity,
+	LibraryPlanStep,
+	LibraryRefreshHost,
+	LibraryRefreshResult,
+	LibraryStepOutcome,
+} from "../../domains/resources/index.js";
+
+/** What the browser needs from the lifecycle domain, and nothing more. */
+export interface LibraryLifecyclePort {
+	plan(request: LibraryLifecycleRequest): LibraryLifecyclePlan;
+	apply(plan: LibraryLifecyclePlan): LibraryApplyResult;
+	/** Cancel: release staged sources, write nothing. */
+	release(plan: LibraryLifecyclePlan): void;
+	/** Refresh only. Never repeats a committed install or removal. */
+	retryRefresh(cwd: string): LibraryRefreshResult;
+}
+
+/**
+ * Bind the port for an interactive session.
+ *
+ * `refresh` is the active host's resource reload. It runs once after the last
+ * committed step and its result is reported separately, so a failed refresh
+ * never restates a successful write as a failure, and retrying it never
+ * re-applies the plan.
+ */
+export function createLibraryLifecycle(refresh: LibraryRefreshHost): LibraryLifecyclePort {
+	return {
+		plan: (request) => planLibraryLifecycle(request),
+		apply: (plan) => applyLibraryLifecycle(plan, { refresh }),
+		release: (plan) => releaseLibraryLifecycle(plan),
+		retryRefresh: (cwd) => retryLibraryRefresh(cwd, refresh),
+	};
+}
+
+/**
+ * The active session's resource refresh, as a lifecycle refresh host.
+ *
+ * A session without a reload seam says so rather than reporting a refresh that
+ * never happened, and a reload that throws is a failed refresh beside committed
+ * writes that still stand.
+ */
+export function libraryRefreshHost(reload?: () => { generation: number }): LibraryRefreshHost {
+	if (!reload)
+		return () => ({
+			status: "not-applicable",
+			reason: "this session has no resource reload; restart to pick up installed changes",
+		});
+	let previous = 0;
+	return () => {
+		try {
+			const next = reload().generation;
+			const changed = previous === 0 || next !== previous;
+			previous = next;
+			return { status: "refreshed", generation: next, changed };
+		} catch (error) {
+			return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+		}
+	};
+}