@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/overlays/side-question.ts

@@ -0,0 +1,139 @@
+/**
+ * `/btw` overlay: the question, then the answer as it streams.
+ *
+ * The overlay is the whole surface for a side question. Nothing it shows is
+ * appended to the transcript, so closing it is the end of the exchange: the
+ * answer was for the operator, in the moment, and the session never saw it.
+ */
+
+import { type Component, type OverlayHandle, type TUI, wrapTextWithAnsi } from "../../engine/tui.js";
+import { buildResponsiveHint, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, GLYPH, rule } from "../theme/index.js";
+
+export const SIDE_QUESTION_OVERLAY_TITLE = "Side question";
+
+/** What the overlay is showing right now. */
+export type SideQuestionOverlayPhase =
+	| { kind: "streaming"; text: string }
+	| { kind: "answered"; text: string }
+	| { kind: "aborted"; text: string }
+	| { kind: "error"; reason: string };
+
+export interface SideQuestionOverlaySession extends OverlayHandle {
+	/** Replace the streamed answer text. */
+	setAnswer(text: string): void;
+	/** Settle the overlay on a final phase. */
+	settle(phase: SideQuestionOverlayPhase): void;
+}
+
+export interface OpenSideQuestionOverlayOptions {
+	question: string;
+	/** Live terminal width, so the box tracks the window it opened in. */
+	columns: number;
+	/** Esc: abort a streaming round, then close. */
+	onClose: () => void;
+}
+
+const SIDE_QUESTION_OVERLAY_MIN_WIDTH = 44;
+const SIDE_QUESTION_OVERLAY_MAX_WIDTH = 100;
+
+export function sideQuestionOverlayWidth(columns: number): number {
+	return Math.max(SIDE_QUESTION_OVERLAY_MIN_WIDTH, Math.min(SIDE_QUESTION_OVERLAY_MAX_WIDTH, columns - 4));
+}
+
+/**
+ * Render the overlay body. Pure so the layout is unit-testable without a TUI:
+ * the question in dim above a rule, then the answer, then one status line that
+ * says whether the round is still running, cancelled, or failed.
+ */
+export function formatSideQuestionBody(
+	question: string,
+	phase: SideQuestionOverlayPhase,
+	width: number,
+	spinner: string,
+): string[] {
+	const theme = clioTheme();
+	const contentWidth = Math.max(1, Math.floor(width));
+	const lines: string[] = [];
+	for (const line of wrapTextWithAnsi(theme.fg("dim", `${GLYPH.user} ${question}`), contentWidth)) lines.push(line);
+	lines.push(rule(theme, contentWidth));
+	if (phase.kind === "error") {
+		for (const line of wrapTextWithAnsi(theme.fg("error", phase.reason), contentWidth)) lines.push(line);
+		return lines;
+	}
+	const body = phase.text.trim();
+	if (body.length > 0) {
+		for (const paragraph of body.split("\n")) {
+			if (paragraph.length === 0) {
+				lines.push("");
+				continue;
+			}
+			for (const line of wrapTextWithAnsi(theme.fg("muted", paragraph), contentWidth)) lines.push(line);
+		}
+	}
+	if (phase.kind === "streaming") {
+		lines.push(theme.fg("dim", body.length > 0 ? spinner : `${spinner} asking…`));
+	} else if (phase.kind === "aborted") {
+		lines.push(theme.fg("warning", "cancelled"));
+	} else if (body.length === 0) {
+		lines.push(theme.fg("dim", "the model returned no text"));
+	}
+	return lines;
+}
+
+const SPINNER_FRAMES = ["·", "•", "●", "•"] as const;
+
+class SideQuestionOverlayBody implements Component {
+	private phase: SideQuestionOverlayPhase = { kind: "streaming", text: "" };
+	private frame = 0;
+
+	constructor(private readonly question: string) {}
+
+	set(phase: SideQuestionOverlayPhase): void {
+		this.phase = phase;
+	}
+
+	render(width: number): string[] {
+		if (this.phase.kind === "streaming") this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+		return formatSideQuestionBody(this.question, this.phase, width, SPINNER_FRAMES[this.frame] ?? "·");
+	}
+
+	invalidate(): void {}
+}
+
+/**
+ * Mount the overlay. `setAnswer` is called from the stream; `settle` closes the
+ * round's live state without closing the overlay, so the operator reads the
+ * answer and leaves with Esc.
+ */
+export function openSideQuestionOverlay(tui: TUI, options: OpenSideQuestionOverlayOptions): SideQuestionOverlaySession {
+	const body = new SideQuestionOverlayBody(options.question);
+	let settled = false;
+	const handle = showClioOverlayFrame(tui, body, {
+		anchor: "center",
+		width: sideQuestionOverlayWidth(options.columns),
+		title: SIDE_QUESTION_OVERLAY_TITLE,
+		// Esc means two things here and the footer names the live one: it aborts a
+		// round that is still streaming, and it closes one that has settled.
+		footerHint: (innerWidth) => buildResponsiveHint([], { key: "Esc", verb: settled ? "close" : "cancel" })(innerWidth),
+	});
+	return {
+		...handle,
+		setAnswer(text: string): void {
+			if (settled) return;
+			body.set({ kind: "streaming", text });
+			body.invalidate();
+			tui.requestRender();
+		},
+		settle(phase: SideQuestionOverlayPhase): void {
+			settled = true;
+			body.set(phase);
+			body.invalidate();
+			tui.requestRender();
+		},
+		hide(): void {
+			options.onClose();
+			handle.hide();
+		},
+	};
+}

package/src/interactive/overlays/skills-hub.ts

@@ -1,28 +1,74 @@
 import type {
+	LibraryDiscoveryResult,
+	LibraryEntry,
+	LibraryEntryKind,
+	LibraryInstallPlan,
+	LibraryRequirementStatus,
 	MarketplaceDiscoveryResult,
 	MarketplaceSkill,
 	ResourceList,
 	Skill,
 } from "../../domains/resources/index.js";
-import { discoverMarketplaceSkills, MARKETPLACE_UNCONFIGURED } from "../../domains/resources/index.js";
+import {
+	classifyLibraryRequirements,
+	discoverLibrary,
+	discoverMarketplaceSkills,
+	installLibraryPlan,
+	libraryEntryInstalled,
+	libraryEntryPin,
+	libraryEntryRef,
+	libraryInstallPath,
+	MARKETPLACE_UNCONFIGURED,
+	planLibraryInstall,
+} from "../../domains/resources/index.js";
 import type { OverlayHandle, TUI } from "../../engine/tui.js";
 import type { NoticeLevel } from "../command-output.js";
 import { clioTheme, GLYPH } from "../theme/index.js";
-import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+import type { LibraryInstallConfirmSubject } from "./library-install-confirm.js";
+import { openLibraryInstallConfirmOverlay } from "./library-install-confirm.js";
+import { type ListOverlayItem, type ListOverlayTab, openListOverlay } from "./list-overlay.js";
 
 /**
- * The Skills Hub: one multipane surface for every skill Clio can reach.
- * Installed skills group by scope, marketplace rows come from the same local
- * marketplace lookup the installer and `/skill <name>` resolve through, Enter
- * inserts the invocation into the editor, and `i` installs in place. The hub
- * lists nothing the resolver cannot resolve; when the lookup is empty the hub
- * says so and names the remedy instead of drawing an inventory.
+ * The Skills Hub: one multipane surface for every resource Clio can reach.
+ *
+ * The Skills tab is the original view. Installed skills group by scope,
+ * marketplace rows come from the same local marketplace lookup the installer
+ * and `/skill <name>` resolve through, Enter inserts the invocation into the
+ * editor, and `i` installs in place. The hub lists nothing the resolver cannot
+ * resolve; when the lookup is empty the hub says so and names the remedy
+ * instead of drawing an inventory.
+ *
+ * The Agents, Prompts, and Fleets tabs are the interactive half of the resource
+ * library. Their rows come from the same `discoverLibrary()` the CLI's
+ * `library list --kind` reads, their install runs the same plan-then-write pair
+ * `library add` runs behind the same confirmation the `--yes` gate expresses,
+ * and their requirement gate is the same classifier. Nothing here reaches
+ * around the library domain into a private path.
  */
 
 const GROUP_PROJECT = "Project";
 const GROUP_USER = "User";
 const GROUP_MARKETPLACE = "Marketplace";
 const GROUP_DIAGNOSTICS = "Diagnostics";
+const GROUP_INSTALLED = "Installed";
+const GROUP_AVAILABLE = "Available";
+
+/** The hub's tabs, in the order ←/→ walks them. `skill` is the original view. */
+export const LIBRARY_TABS: ReadonlyArray<{ id: LibraryEntryKind; label: string }> = [
+	{ id: "skill", label: "Skills" },
+	{ id: "agent", label: "Agents" },
+	{ id: "prompt", label: "Prompts" },
+	{ id: "fleet", label: "Fleets" },
+];
+
+export const SKILLS_HUB_TITLE = "Skills Hub";
+
+/** Row id prefix for a library row, which is how an action tells the tabs apart. */
+export const LIBRARY_ROW_PREFIX = "library:";
+
+export function isLibraryTab(value: string): value is LibraryEntryKind {
+	return LIBRARY_TABS.some((tab) => tab.id === value);
+}
 
 /** @internal exported for contract tests */
 export const SKILLS_HUB_EMPTY =
@@ -37,6 +83,50 @@ export interface SkillsHubDeps {
 	onClose: () => void;
 	/** Injectable for tests; defaults to the local marketplace the installer uses. */
 	discoverMarketplace?: () => MarketplaceDiscoveryResult;
+	/** Tab the hub opens on. `/skills` opens on Skills, `/library <kind>` on that kind. */
+	initialTab?: LibraryEntryKind;
+	/** Injectable for tests; defaults to the discovery `library list` reads. */
+	discoverLibrary?: () => LibraryDiscoveryResult;
+	/** Injectable for tests; defaults to the classifier `library add` gates on. */
+	classifyRequirements?: (entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>) => LibraryRequirementStatus;
+	/** Injectable for tests; defaults to the planner `library add` prints from. */
+	planInstall?: (entry: LibraryEntry) => LibraryInstallPlan;
+	/** Injectable for tests; defaults to the writer `library add --yes` runs. */
+	installPlan?: (plan: LibraryInstallPlan) => void;
+	/** Injectable for tests; defaults to the pin-and-destination check the domain owns. */
+	entryInstalled?: (entry: LibraryEntry) => boolean;
+	/** Injectable for tests; defaults to the recorded pin for this entry. */
+	entryPin?: (entry: LibraryEntry) => { sha256: string; sourceUrl: string } | undefined;
+	/**
+	 * The confirmation gate. Resolves true only when the operator accepted, and
+	 * nothing is written before it does. Defaults to the framed confirmation
+	 * overlay, which is the TUI spelling of `library add`'s `--yes`.
+	 */
+	confirmInstall?: (subject: LibraryInstallConfirmSubject) => Promise<boolean>;
+	/** Opens the `/fleet run` approval preview for an installed fleet. */
+	openFleetRun?: (name: string) => void;
+}
+
+/** Row and action context for one library tab, resolved once per rebuild. */
+interface LibraryTabContext {
+	discovery: LibraryDiscoveryResult;
+	installed: (entry: LibraryEntry) => boolean;
+	pin: (entry: LibraryEntry) => { sha256: string; sourceUrl: string } | undefined;
+	unresolved: (entry: LibraryEntry) => LibraryEntry[];
+}
+
+/**
+ * The composer text or the surface a `use` on this entry leads to.
+ *
+ * A fleet has no composer spelling because its `use` opens the `/fleet run`
+ * approval preview instead, so this returns null for one and the caller routes
+ * it there.
+ */
+export function libraryUseInvocation(entry: Pick<LibraryEntry, "kind" | "name">): string | null {
+	if (entry.kind === "fleet") return null;
+	if (entry.kind === "agent") return `/run ${entry.name} `;
+	if (entry.kind === "prompt") return `/${entry.name} `;
+	return `/skill ${entry.name} `;
 }
 
 function groupForScope(scope: string): string {
@@ -170,8 +260,159 @@ export function buildDiagnosticItems(
 	return items;
 }
 
+/** @internal exported for contract tests */
+export function libraryRowId(entry: Pick<LibraryEntry, "kind" | "name">): string {
+	return `${LIBRARY_ROW_PREFIX}${libraryEntryRef(entry)}`;
+}
+
+/**
+ * One kind's rows: the same columns the Skills tab shows where they apply, plus
+ * the requirements this entry still needs.
+ *
+ * The requires column carries the names rather than a count, because the names
+ * are what the refusal will say and what the second confirmation will install.
+ * It renders in the warning token: an entry with an unmet requirement is
+ * listable and readable but not installable on its own.
+ *
+ * @internal exported for contract tests
+ */
+export function buildLibraryItems(kind: LibraryEntryKind, context: LibraryTabContext): ListOverlayItem[] {
+	const theme = clioTheme();
+	return context.discovery.entries
+		.filter((entry) => entry.kind === kind)
+		.map((entry) => {
+			const installed = context.installed(entry);
+			const pin = context.pin(entry);
+			const unresolved = context.unresolved(entry).map(libraryEntryRef);
+			const metaParts: string[] = [entry.origin];
+			if (entry.version) metaParts.push(`v${entry.version}`);
+			metaParts.push(installed ? "installed" : "available");
+			metaParts.push(pin ? `pin ${pin.sha256.slice(0, 8)}` : "unpinned");
+			if (unresolved.length > 0) metaParts.push(theme.fg("warning", `requires ${unresolved.join(", ")}`));
+			return {
+				id: libraryRowId(entry),
+				label: entry.name,
+				meta: metaParts.join(" · "),
+				group: installed ? GROUP_INSTALLED : GROUP_AVAILABLE,
+				detail: () => {
+					const use = libraryUseInvocation(entry);
+					const lines = [
+						`# ${entry.name}`,
+						`**Kind:** ${entry.kind}`,
+						`**Use:** ${use === null ? "`Enter` opens the /fleet run approval preview" : `\`${use.trim()}\``}`,
+						`**State:** ${installed ? "installed" : "available"}${pin ? ` · pinned ${pin.sha256.slice(0, 12)}` : " · unpinned"}`,
+						`**Destination:** \`${libraryInstallPath(entry)}\``,
+						`**Source:** \`${entry.sourceUrl}\``,
+						`**Origin:** ${entry.origin}`,
+					];
+					if ((entry.requires ?? []).length > 0) {
+						lines.push(`**Requires:** ${(entry.requires ?? []).join(", ")}`);
+					}
+					if (unresolved.length > 0) {
+						lines.push(`**Unresolved:** ${unresolved.join(", ")}`, "", "Press `i` twice to install them with it.");
+					} else if (!installed) {
+						lines.push("", "**Install now:** press `i`");
+					}
+					lines.push("", "---", "", entry.description);
+					return lines;
+				},
+			};
+		});
+}
+
+/**
+ * Diagnostic rows for a library tab. `discoverLibrary` drops an entry whose
+ * requirements are missing, malformed, or cyclic and records why; a tab that
+ * silently omitted those would be the inventory this hub refuses to draw.
+ *
+ * @internal exported for contract tests
+ */
+export function buildLibraryDiagnosticItems(discovery: LibraryDiscoveryResult): ListOverlayItem[] {
+	const theme = clioTheme();
+	return discovery.diagnostics
+		.filter((message) => message !== MARKETPLACE_UNCONFIGURED)
+		.map((message, index) => ({
+			id: `library-diagnostic-${index}`,
+			label: `${theme.fg("warning", GLYPH.warnInline)} ${message}`,
+			meta: "library",
+			group: GROUP_DIAGNOSTICS,
+			detail: () => ["# Library diagnostic", `**Message:** ${message}`],
+		}));
+}
+
+/** What one attempted library install did, in the terms the hub reports it. */
+export type LibraryInstallOutcome =
+	| { status: "installed"; refs: string[] }
+	| { status: "cancelled" }
+	| { status: "refused"; unresolved: string[] }
+	| { status: "already-installed" }
+	| { status: "failed"; message: string };
+
+/** The library domain calls one install needs, resolved before it runs. */
+export interface LibraryInstallRunner {
+	discovery: LibraryDiscoveryResult;
+	classify: (entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>) => LibraryRequirementStatus;
+	plan: (entry: LibraryEntry) => LibraryInstallPlan;
+	write: (plan: LibraryInstallPlan) => void;
+	installed: (entry: LibraryEntry) => boolean;
+	confirm: (subject: LibraryInstallConfirmSubject) => Promise<boolean>;
+}
+
+/**
+ * Install one library entry through the same sequence `library add` runs.
+ *
+ * The order is the CLI's order and the refusals are the CLI's refusals: an
+ * entry with an unmet requirement is refused by name and nothing is planned, a
+ * plan is built and shown before anything is written, and the writes happen
+ * only after the confirmation resolves true. A cancelled confirmation is a run
+ * in which no file changed.
+ *
+ * @internal exported for contract tests
+ */
+export async function runLibraryInstall(
+	entry: LibraryEntry,
+	runner: LibraryInstallRunner,
+	options: { withRequirements: boolean },
+): Promise<LibraryInstallOutcome> {
+	if (runner.installed(entry)) return { status: "already-installed" };
+	let requirements: LibraryRequirementStatus;
+	let plans: LibraryInstallPlan[];
+	try {
+		requirements = runner.classify(entry, runner.discovery.entries);
+		if (requirements.unsatisfied.length > 0 && !options.withRequirements) {
+			return { status: "refused", unresolved: requirements.unsatisfied.map(libraryEntryRef) };
+		}
+		plans = [...(options.withRequirements ? requirements.unsatisfied : []), entry].map(runner.plan);
+	} catch (error) {
+		return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+	}
+	const accepted = await runner.confirm({
+		entryRef: libraryEntryRef(entry),
+		writes: plans.map((plan) => ({ ref: libraryEntryRef(plan.entry), path: plan.path, sha256: plan.sha256 })),
+		requirements: options.withRequirements ? requirements.unsatisfied.map(libraryEntryRef) : [],
+		satisfied: requirements.satisfied.map(libraryEntryRef),
+	});
+	if (!accepted) return { status: "cancelled" };
+	const written: string[] = [];
+	try {
+		for (const plan of plans) {
+			runner.write(plan);
+			written.push(libraryEntryRef(plan.entry));
+		}
+	} catch (error) {
+		return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+	}
+	return { status: "installed", refs: written };
+}
+
 export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 	const discoverMarketplace = deps.discoverMarketplace ?? (() => discoverMarketplaceSkills());
+	const readLibrary = deps.discoverLibrary ?? (() => discoverLibrary());
+	const classify = deps.classifyRequirements ?? classifyLibraryRequirements;
+	const plan = deps.planInstall ?? planLibraryInstall;
+	const write = deps.installPlan ?? installLibraryPlan;
+	const installed = deps.entryInstalled ?? libraryEntryInstalled;
+	const pin = deps.entryPin ?? libraryEntryPin;
 
 	// Rebuilt rather than mutated in place: the view memoizes its frame on the row
 	// set, so a spliced array leaves an installed skill drawn as installable.
@@ -186,27 +427,170 @@ export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 		];
 	};
 
+	// One discovery pass feeds all three library tabs. The tab bar asks every tab
+	// for its rows on each rebuild, and four independent catalog reads per
+	// keystroke would be four answers to the same question.
+	let libraryCache: LibraryTabContext | null = null;
+	const libraryContext = (): LibraryTabContext => {
+		if (libraryCache) return libraryCache;
+		const discovery = readLibrary();
+		libraryCache = {
+			discovery,
+			installed,
+			pin,
+			unresolved: (entry) => {
+				try {
+					return classify(entry, discovery.entries).unsatisfied;
+				} catch {
+					// A requirement that will not resolve is already a diagnostic row on
+					// this tab; a row that cannot answer the question reports none rather
+					// than taking the whole rebuild down.
+					return [];
+				}
+			},
+		};
+		return libraryCache;
+	};
+	const invalidateLibrary = (): void => {
+		libraryCache = null;
+	};
+
+	const buildLibraryRows = (kind: LibraryEntryKind): ListOverlayItem[] => {
+		const context = libraryContext();
+		return [...buildLibraryItems(kind, context), ...buildLibraryDiagnosticItems(context.discovery)];
+	};
+
+	const entryForRow = (item: ListOverlayItem): LibraryEntry | undefined => {
+		if (!item.id.startsWith(LIBRARY_ROW_PREFIX)) return undefined;
+		const ref = item.id.slice(LIBRARY_ROW_PREFIX.length);
+		return libraryContext().discovery.entries.find((candidate) => libraryEntryRef(candidate) === ref);
+	};
+
+	const tabs: ListOverlayTab[] = LIBRARY_TABS.map((tab) => ({
+		id: tab.id,
+		label: tab.label,
+		items: tab.id === "skill" ? buildRows : () => buildLibraryRows(tab.id),
+	}));
+
 	let closed = false;
 	let installInFlight = false;
-	const handle = openListOverlay(tui, {
-		title: "Skills",
-		items: buildRows(),
+	/**
+	 * The row whose requirements were just refused. A second `i` on that row is
+	 * the install-with-requirements offer, so the refusal names what is missing
+	 * before any confirmation lists what would be written.
+	 */
+	let pendingWithRequirements: string | null = null;
+
+	const columns = (): number => (typeof process.stdout.columns === "number" ? process.stdout.columns : 100);
+
+	// eslint-disable-next-line prefer-const -- the confirmation closure needs the handle it is opened from.
+	let handle: ReturnType<typeof openListOverlay>;
+
+	const confirmInstall =
+		deps.confirmInstall ??
+		((subject: LibraryInstallConfirmSubject): Promise<boolean> =>
+			new Promise<boolean>((resolve) => {
+				handle.setHidden(true);
+				const settle = (accepted: boolean): void => {
+					if (!closed) {
+						handle.setHidden(false);
+						handle.focus();
+					}
+					resolve(accepted);
+				};
+				const confirmation = openLibraryInstallConfirmOverlay(tui, {
+					subject,
+					columns: columns(),
+					onAccept: () => {
+						settle(true);
+						confirmation.hide();
+					},
+					onCancel: () => {
+						settle(false);
+						confirmation.hide();
+					},
+				});
+			}));
+
+	const useEntry = (entry: LibraryEntry): void => {
+		if (!installed(entry)) {
+			deps.notice("warn", `${libraryEntryRef(entry)} is not installed; press i to install it`);
+			return;
+		}
+		if (entry.kind === "fleet") {
+			deps.openFleetRun?.(entry.name);
+			return;
+		}
+		const invocation = libraryUseInvocation(entry);
+		if (invocation === null) return;
+		deps.setEditorText(invocation);
+		deps.onClose();
+	};
+
+	const installEntry = (entry: LibraryEntry): void => {
+		const ref = libraryEntryRef(entry);
+		const withRequirements = pendingWithRequirements === ref;
+		installInFlight = true;
+		void (async () => {
+			const outcome = await runLibraryInstall(
+				entry,
+				{ discovery: libraryContext().discovery, classify, plan, write, installed, confirm: confirmInstall },
+				{ withRequirements },
+			);
+			installInFlight = false;
+			if (outcome.status === "refused") {
+				pendingWithRequirements = ref;
+				deps.notice("error", `${ref} needs ${outcome.unresolved.join(", ")}; press i again to install them with it`);
+				return;
+			}
+			pendingWithRequirements = null;
+			if (outcome.status === "already-installed") deps.notice("info", `${ref} is already installed`);
+			else if (outcome.status === "cancelled") deps.notice("info", `${ref}: cancelled; nothing was written`);
+			else if (outcome.status === "failed") deps.notice("error", `library install failed: ${outcome.message}`);
+			else deps.notice("success", `installed ${outcome.refs.join(", ")}`);
+			// An install that lands after the hub closed has nothing to redraw.
+			if (!closed && outcome.status === "installed") {
+				invalidateLibrary();
+				handle.refreshTabs();
+			}
+		})();
+	};
+
+	handle = openListOverlay(tui, {
+		title: SKILLS_HUB_TITLE,
+		items: [],
+		tabs,
+		...(deps.initialTab ? { activeTabId: deps.initialTab } : {}),
+		onTabChange: () => {
+			pendingWithRequirements = null;
+		},
 		filterable: true,
 		layout: "split",
 		emptyMessage: SKILLS_HUB_EMPTY,
 		hints: [
-			{ key: "Enter", verb: "invoke" },
+			{ key: "Enter", verb: "use" },
 			{ key: "i", verb: "install" },
 		],
 		onSelect: (item) => {
 			if (item.group === GROUP_DIAGNOSTICS) return;
+			const entry = entryForRow(item);
+			if (entry) {
+				useEntry(entry);
+				return;
+			}
 			const name = item.id.startsWith("marketplace:") ? item.id.slice("marketplace:".length) : item.id;
 			deps.setEditorText(`/skill ${name} `);
 			deps.onClose();
 		},
 		actions: {
 			i: (item) => {
-				if (!item.id.startsWith("marketplace:") || installInFlight) return;
+				if (installInFlight) return;
+				const entry = entryForRow(item);
+				if (entry) {
+					installEntry(entry);
+					return;
+				}
+				if (!item.id.startsWith("marketplace:")) return;
 				const name = item.id.slice("marketplace:".length);
 				installInFlight = true;
 				void (async () => {
@@ -218,8 +602,10 @@ export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
 						deps.notice("error", `skill install failed: ${err instanceof Error ? err.message : String(err)}`);
 					} finally {
 						installInFlight = false;
-						// An install that lands after the hub closed has nothing to redraw.
-						if (!closed) handle.setItems(buildRows());
+						if (!closed) {
+							invalidateLibrary();
+							handle.refreshTabs();
+						}
 					}
 				})();
 			},

package/src/interactive/permission-hint.ts

@@ -0,0 +1,35 @@
+import type { HintEntry } from "./overlay-frame.js";
+
+/**
+ * The keys that answer a parked call, as data, so the dialog footer and the
+ * composer rail render the same policy at any width.
+ *
+ * This is its own leaf because the composer is part of the Stage 0 boot shell
+ * and the permission overlay is not: importing the overlay from the editor
+ * pulled the safety domain's approval modules into the instant-shell closure.
+ *
+ * At 40 columns the old positional elider removed `[s] stop turn` and left
+ * "allow once" and an ambiguous "close" in front of an operator trying to
+ * refuse. The key kept working, so the layout was hiding a live safety action.
+ * Allow and stop are marked critical, Esc is marked droppable, and
+ * `fitHintEntries` shortens every label before it drops anything.
+ *
+ * Esc says `deny`, not `close`: closing the dialog denies the call, and on the
+ * one surface where a misread is a wrong decision about a tool call the key
+ * names its effect.
+ *
+ * With a draft in the composer, Enter is inert (issue #186): the habitual send
+ * key must not resolve toward "allow" on a safety rail. The entry then says so
+ * and names the key that clears the draft, which the router passes through.
+ */
+export function permissionHintEntries(composerHasDraft = false): HintEntry[] {
+	return [
+		composerHasDraft
+			? { key: "Backspace", verb: "clear the draft to allow", short: "clear draft", critical: true }
+			: { key: "Enter", verb: "allow once", short: "allow", critical: true },
+		{ key: "s", verb: "stop turn", short: "stop", critical: true },
+		// With a draft, deny and stop are the only immediate answers, so Esc
+		// outranks the narrowing that would otherwise drop it first.
+		{ key: "Esc", verb: "deny", critical: composerHasDraft },
+	];
+}