@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/interactive/overlay-general-openers.ts

@@ -1,7 +1,10 @@
+import { randomBytes } from "node:crypto";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import type { AgentsContract } from "../domains/agents/contract.js";
 import { foldWorkingSet } from "../domains/context/working-set/fold.js";
-import type { DispatchContract } from "../domains/dispatch/index.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/index.js";
+import { agentRoleFactsResolver, executeFleetRun, requestExecutionRole } from "../domains/dispatch/index.js";
 import {
 	canonicalMemoryRepositoryIdentity,
 	loadMemoryRecordsSync,
@@ -23,6 +26,7 @@ import {
 	isDispatchBoardRowCancellable,
 	isDispatchBoardRowSteerable,
 } from "./dispatch-board.js";
+import { compileFleetRunPreview, type FleetRunPreview, type FleetRunPreviewInput } from "./fleet-run-preview.js";
 import { openMemoryOverlay } from "./memory-overlay.js";
 import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
 import type { OverlayTransitions } from "./overlay-transitions.js";
@@ -32,6 +36,8 @@ import {
 	openContextResetOverlay,
 } from "./overlays/context-reset.js";
 import { formatDecisionCorrectionTurn, openDecisionsOverlay } from "./overlays/decisions.js";
+import { openFleetRunApprovalOverlay } from "./overlays/fleet-run-approval.js";
+import { openSideQuestionOverlay } from "./overlays/side-question.js";
 import { type ContextClearCommandOptions, formatUserTaskHandoff } from "./slash-commands.js";
 import { openTasksOverlay } from "./tasks-overlay.js";
 import { type ArtifactProviderDeps, createDefaultArtifactProviders } from "./view/artifacts.js";
@@ -77,6 +83,37 @@ export interface OverlayGeneralOpenersDeps {
 	openDecisionsOverlay?: typeof openDecisionsOverlay;
 	openMemoryOverlay?: typeof openMemoryOverlay;
 	openViewOverlay?: typeof openViewOverlay;
+	openSideQuestionOverlay?: typeof openSideQuestionOverlay;
+	openFleetRunApprovalOverlay?: typeof openFleetRunApprovalOverlay;
+	/** Recipe registry `/fleet run` resolves every step's agent against. */
+	agents?: AgentsContract;
+	/** Session budget state the run would be admitted under; absent leaves it unknown. */
+	getBudgetPreflight?: () => { ceilingUsd: number; currentUsd: number; verdict: "under" | "at" | "over" };
+	/**
+	 * True while a turn is streaming. `/fleet run` is refused then, never
+	 * queued: an approved plan describes the workspace as it stands, and a turn
+	 * still in flight is about to change it.
+	 */
+	isTurnInFlight?: () => boolean;
+	/** Record which wave and step a dispatched run belongs to, for the board's phase column. */
+	setFleetRunPhase?: (runId: string, phase: { wave: number; stepId: string }) => void;
+	/** The shared fleet-run path; overridable so a test can observe one call. */
+	runFleet?: typeof executeFleetRun;
+	/** Contract and command-registry loader; overridable so a test projects a fixture. */
+	loadFleetSources?: FleetRunPreviewInput["load"];
+	/**
+	 * Run one `/btw` round. Absent on a host with no chat loop, in which case
+	 * `/btw` reports that instead of opening an empty overlay.
+	 */
+	askSideQuestion?: (
+		question: string,
+		options: { signal: AbortSignal; onDelta: (partialText: string) => void },
+	) => Promise<
+		| { status: "answered"; text: string }
+		| { status: "aborted"; text: string }
+		| { status: "refused"; reason: string }
+		| { status: "failed"; reason: string }
+	>;
 }
 
 export interface OverlayGeneralOpeners {
@@ -89,6 +126,9 @@ export interface OverlayGeneralOpeners {
 	openMemory(): void;
 	openView(initialFilter?: string): void;
 	toggleDispatchBoard(): void;
+	openSideQuestion(question: string): void;
+	/** `/fleet run <name> [--var k=v ...]`: preview the plan, then dispatch on approval. */
+	startFleetRun(name: string, vars: Readonly<Record<string, string>>): void;
 }
 
 export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): OverlayGeneralOpeners {
@@ -100,6 +140,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 	const openMemoryOverlayFactory = deps.openMemoryOverlay ?? openMemoryOverlay;
 	const openViewOverlayFactory = deps.openViewOverlay ?? openViewOverlay;
 	const showOverlayFrameFactory = deps.showOverlayFrame ?? showClioOverlayFrame;
+	const openSideQuestionOverlayFactory = deps.openSideQuestionOverlay ?? openSideQuestionOverlay;
 
 	const openCost = (): void => {
 		if (deps.transitions.state !== "closed") return;
@@ -305,6 +346,152 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		return buildHint(entries);
 	};
 
+	/**
+	 * `/btw <question>`: one model round beside the session, rendered in an
+	 * overlay and nowhere else. Esc aborts a round that is still streaming and
+	 * closes one that has settled; both paths run through the same abort
+	 * controller, so a cancelled round never keeps a stream alive behind a closed
+	 * overlay.
+	 */
+	const openSideQuestion = (question: string): void => {
+		if (deps.transitions.state !== "closed") return;
+		const ask = deps.askSideQuestion;
+		if (!ask) {
+			deps.notify("error", "/btw is not wired in this session", "btw:unavailable");
+			return;
+		}
+		const controller = new AbortController();
+		deps.transitions.state = "side-question";
+		const session = openSideQuestionOverlayFactory(deps.tui, {
+			question,
+			columns: deps.terminal.columns,
+			onClose: () => controller.abort(),
+		});
+		deps.transitions.handle = session;
+		deps.requestRender();
+		void ask(question, { signal: controller.signal, onDelta: (partialText) => session.setAnswer(partialText) })
+			.then((outcome) => {
+				if (outcome.status === "answered") {
+					session.settle({ kind: "answered", text: outcome.text });
+					return;
+				}
+				if (outcome.status === "aborted") {
+					session.settle({ kind: "aborted", text: outcome.text });
+					return;
+				}
+				session.settle({ kind: "error", reason: outcome.reason });
+			})
+			.catch((error: unknown) => {
+				session.settle({ kind: "error", reason: error instanceof Error ? error.message : String(error) });
+			});
+	};
+
+	/**
+	 * `/fleet run <name>`: compile the plan, show it, and dispatch only what the
+	 * operator accepted.
+	 *
+	 * Nothing is dispatched and nothing is written before the accept key. A
+	 * contract that fails preflight opens the same overlay with its diagnostics
+	 * and no accept action, so the only exit from a broken plan is to leave it.
+	 */
+	const startFleetRun = (name: string, vars: Readonly<Record<string, string>>): void => {
+		if (deps.transitions.state !== "closed") return;
+		// Refused, never queued: an approved plan describes the workspace as it
+		// stands, and a turn still in flight is about to change it.
+		if (deps.isTurnInFlight?.() === true) {
+			deps.notify("warning", "a turn is in flight; /fleet run is refused rather than queued", "fleet-run:in-flight");
+			return;
+		}
+		const agents = deps.agents;
+		if (!agents) {
+			deps.notify("error", "/fleet run needs the agents domain, which is not wired in this session", "fleet-run:agents");
+			return;
+		}
+		const workspaceRoot = deps.getSessionMeta()?.cwd ?? process.cwd();
+		const roleFacts = agentRoleFactsResolver((id) => agents.getSpec(id));
+		const budget = deps.getBudgetPreflight?.();
+		const result = compileFleetRunPreview({
+			workspaceRoot,
+			name,
+			vars,
+			getAgentSpec: (agentId) => agents.getSpec(agentId),
+			roleFacts,
+			...(budget ? { budget } : {}),
+			...(deps.loadFleetSources ? { load: deps.loadFleetSources } : {}),
+			resolveRoute: (step) => {
+				const request: DispatchRequest = {
+					agentId: step.agentId,
+					executionRole: requestExecutionRole({ agentId: step.agentId, resolveFacts: roleFacts }),
+					task: step.task,
+					...(step.scope === "readonly" ? { autonomy: "read-only" as const } : {}),
+					...(step.target !== undefined ? { target: step.target } : {}),
+					...(step.profile !== undefined ? { workerProfile: step.profile } : {}),
+				};
+				const resolution = deps.dispatch.preview?.(request);
+				if (!resolution) return null;
+				return {
+					targetId: resolution.targetId,
+					wireModelId: resolution.wireModelId,
+					nodeId: resolution.node.id,
+				};
+			},
+		});
+
+		deps.transitions.state = "fleet-run-approval";
+		deps.transitions.handle = (deps.openFleetRunApprovalOverlay ?? openFleetRunApprovalOverlay)(deps.tui, {
+			subject: result.ok ? { ok: true, preview: result.preview } : { ok: false, name, diagnostics: result.diagnostics },
+			columns: deps.terminal.columns,
+			onAccept: () => {
+				deps.closeOverlay();
+				if (result.ok) dispatchFleetRun(result.preview, agents);
+			},
+			onCancel: () => {
+				deps.closeOverlay();
+				deps.notify("info", `fleet ${name}: cancelled; nothing was dispatched`, "fleet-run:cancelled");
+			},
+		});
+		deps.requestRender();
+	};
+
+	const dispatchFleetRun = (preview: FleetRunPreview, agents: AgentsContract): void => {
+		const fleetRootId = `fleet-${randomBytes(6).toString("hex")}`;
+		const run = deps.runFleet ?? executeFleetRun;
+		deps.notify(
+			"info",
+			`fleet ${preview.name}: root=${fleetRootId} plan=${preview.planHash.slice(0, 12)} steps=${preview.plan.steps.length}`,
+			"fleet-run:started",
+		);
+		void run({
+			plan: preview.plan,
+			contractName: preview.name,
+			commands: preview.commands,
+			workspaceRoot: deps.getSessionMeta()?.cwd ?? process.cwd(),
+			fleetRootId,
+			dispatch: deps.dispatch,
+			agents: { getSpec: (agentId) => agents.getSpec(agentId) },
+			attributionEnabled: deps.getSettings?.().attribution.gitCommits ?? true,
+			vars: preview.vars,
+			onStepDispatched: (event) => {
+				deps.setFleetRunPhase?.(event.assignmentId, { wave: event.waveIndex, stepId: event.stepId });
+			},
+			onNotice: (text) => deps.stderr(`[fleet ${preview.name}] ${text}\n`),
+		})
+			.then((outcome) => {
+				deps.notify(
+					outcome.cleanRun ? "success" : "warning",
+					`fleet ${preview.name}: ${outcome.succeededStepCount}/${outcome.requiredStepCount} steps succeeded, cost $${outcome.totalCostUsd.toFixed(4)}`,
+					"fleet-run:settled",
+				);
+			})
+			.catch((error: unknown) => {
+				deps.notify(
+					"error",
+					`fleet ${preview.name}: ${error instanceof Error ? error.message : String(error)}`,
+					"fleet-run:failed",
+				);
+			});
+	};
+
 	return {
 		openCost,
 		openContextView,
@@ -315,5 +502,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		openMemory,
 		openView,
 		toggleDispatchBoard,
+		openSideQuestion,
+		startFleetRun,
 	};
 }

package/src/interactive/overlay-key-routing.ts

@@ -25,7 +25,10 @@ export type OverlayState =
 	| "prompts"
 	| "extensions"
 	| "interop"
-	| "skills-hub";
+	| "skills-hub"
+	| "side-question"
+	| "handoff-review"
+	| "fleet-run-approval";
 
 export interface PermissionOverlayKeyDeps {
 	cancelPermission: () => void;
@@ -220,6 +223,19 @@ export function routeOverlayKey(
 		routeCostOverlayKey(data, deps);
 		return true;
 	}
+	// Esc is the only key the side-question overlay answers: it aborts a round
+	// that is still streaming and closes one that has settled. Everything else is
+	// swallowed so a keystroke cannot reach the composer behind it.
+	if (overlayState === "side-question") {
+		routeCostOverlayKey(data, deps);
+		return true;
+	}
+	// The handoff review overlay owns Enter, `e`, the arrows, and Esc itself, so
+	// every key goes to its own focus box rather than through the router.
+	if (overlayState === "handoff-review") return false;
+	// The fleet-run approval overlay owns Enter, the arrows, and Esc itself, so
+	// every key goes to its own focus box rather than through the router.
+	if (overlayState === "fleet-run-approval") return false;
 	if (overlayState === "context-reset") return false;
 	if (overlayState === "tasks") return false;
 	if (overlayState === "decisions") return false;

package/src/interactive/overlay-lifecycle.ts

@@ -1,3 +1,4 @@
+import type { LibraryEntryKind } from "../domains/resources/index.js";
 import { appendNotice } from "./command-output.js";
 import { createOverlayAskUserLifecycle, type OverlayAskUserLifecycle } from "./overlay-ask-user-lifecycle.js";
 import { createOverlayAuthLifecycle } from "./overlay-auth-lifecycle.js";
@@ -26,6 +27,7 @@ import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings
 // application composition root no longer owns the mutable overlay state.
 export type OverlayLifecycleApplicationDeps = Pick<
 	import("./interactive-application.js").InteractiveDeps,
+	| "agents"
 	| "bus"
 	| "chat"
 	| "commitSetting"
@@ -42,12 +44,14 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "observability"
 	| "onContextClear"
 	| "onForkSession"
+	| "onNewSession"
 	| "onResumeSession"
 	| "onSelectModel"
 	| "providers"
 	| "readSessionEntries"
 	| "registerAskUserHandler"
 	| "resources"
+	| "scheduling"
 	| "session"
 	| "stateDir"
 	| "supersedeDecision"
@@ -75,9 +79,17 @@ export interface OverlayLifecycleRuntimeDeps {
 	notify: (level: import("./interactive-subscriptions.js").InteractiveNoticeLevel, text: string, key?: string) => void;
 	terminal: Pick<import("../engine/tui.js").ProcessTerminal, "columns">;
 	dispatchBoard: ReturnType<typeof import("./dispatch-board.js").createDispatchBoardView>;
+	/** Record a dispatched fleet step's plan position for the board's phase column. */
+	setFleetRunPhase?: (runId: string, phase: { wave: number; stepId: string }) => void;
 	chatPanel: import("./chat-panel.js").ChatPanel;
 	/** Clears the transcript and every view folded alongside it; the session overlays call it before a replay. */
 	resetTranscript: () => void;
+	/**
+	 * Stop and restart the terminal around a child process that owns the screen.
+	 * `/handoff` uses it for the external editor, the same way the composer's
+	 * own `$EDITOR` opener does.
+	 */
+	suspendTerminal: <T>(run: () => T) => T;
 	io: import("./slash-commands.js").RunIo;
 	readStructuredEntries: (sessionId: string) => import("../domains/session/index.js").SessionEntry[];
 	announceTaskMemorySeedOffer: () => void;
@@ -86,6 +98,11 @@ export interface OverlayLifecycleRuntimeDeps {
 	keybindings: ReturnType<typeof import("./keybinding-manager.js").createKeybindingManager>;
 	editor: Pick<import("./clio-editor.js").ClioEditor, "getText" | "render" | "setText">;
 	getSlashContext: () => import("./slash-commands.js").SlashCommandContext;
+	/**
+	 * A worker permission or ask_user request parked waiting for the operator.
+	 * Wired to the desktop notification; absent hosts simply do not notify.
+	 */
+	onOperatorParked?: () => void;
 	showOverlayFrame?: typeof showClioOverlayFrame;
 	openAuthDialog?: typeof import("./overlays/auth-dialog.js").openAuthDialog;
 	openAskUserOverlay?: typeof import("./overlays/ask-user.js").openAskUserOverlay;
@@ -127,6 +144,11 @@ export interface OverlayLifecycleController {
 	openDecisionsOverlayState(): void;
 	openMemoryOverlayState(): void;
 	openViewOverlayState(initialFilter?: string): void;
+	/** `/btw <question>`: one side-question round rendered in its own overlay. */
+	openSideQuestionOverlayState(question: string): void;
+	/** `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoffState(goal: string): void;
+	startFleetRunState(name: string, vars: Readonly<Record<string, string>>): void;
 	openModelOverlayState(): void;
 	openSettingsOverlayState(section?: SettingsSectionId, rowId?: SettingsCenterRowId): void;
 	openResumeOverlayState(): void;
@@ -134,7 +156,7 @@ export interface OverlayLifecycleController {
 	openMessagePickerOverlayState(): void;
 	openHelpOverlayState(query?: string): void;
 	openAgentsOverlayState(): void;
-	openSkillsHubState(): void;
+	openSkillsHubState(tab?: LibraryEntryKind): void;
 	openPromptsOverlayState(): void;
 	openExtensionsOverlayState(): void;
 	openInteropOverlayState(): void;
@@ -253,6 +275,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 				source: "stream_cancel",
 				auditReason: "operator stopped the turn at a permission prompt",
 			}),
+		...(deps.onOperatorParked ? { onOperatorParked: deps.onOperatorParked } : {}),
 	});
 
 	overlayAskUser = createOverlayAskUserLifecycle({
@@ -270,6 +293,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		requestRender: () => tui.requestRender(),
 		...(deps.app.registerAskUserHandler ? { registerHandler: deps.app.registerAskUserHandler } : {}),
 		...(openAskUserOverlayFactory ? { openAskUserOverlay: openAskUserOverlayFactory } : {}),
+		...(deps.onOperatorParked ? { onOperatorParked: deps.onOperatorParked } : {}),
 	});
 
 	const overlayModelSelectors = createOverlayModelSelectors({
@@ -318,6 +342,10 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		getSlashNotice: () => deps.getSlashContext().notice,
 		...(deps.app.onResumeSession ? { onResumeSession: deps.app.onResumeSession } : {}),
 		...(deps.app.onForkSession ? { onForkSession: deps.app.onForkSession } : {}),
+		...(deps.app.onNewSession ? { onNewSession: deps.app.onNewSession } : {}),
+		...(deps.app.getDecisionBoard ? { getDecisionBoard: deps.app.getDecisionBoard } : {}),
+		terminal: deps.terminal,
+		suspendTerminal: deps.suspendTerminal,
 		announceTaskMemorySeedOffer,
 		sessionUsage: deps.app.observability,
 		...(setLastTurnSummary ? { setLastTurnSummary } : {}),
@@ -331,6 +359,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(openCwdFallbackOverlayFactory ? { openCwdFallbackOverlay: openCwdFallbackOverlayFactory } : {}),
 	});
 
+	const scheduling = deps.app.scheduling;
 	const overlayGeneralOpeners = createOverlayGeneralOpeners({
 		tui,
 		transitions: overlayTransitions,
@@ -370,6 +399,11 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(openDecisionsOverlayFactory ? { openDecisionsOverlay: openDecisionsOverlayFactory } : {}),
 		...(openMemoryOverlayFactory ? { openMemoryOverlay: openMemoryOverlayFactory } : {}),
 		...(openViewOverlayFactory ? { openViewOverlay: openViewOverlayFactory } : {}),
+		askSideQuestion: (question, options) => deps.app.chat.askSideQuestion(question, options),
+		...(deps.app.agents ? { agents: deps.app.agents } : {}),
+		...(scheduling ? { getBudgetPreflight: () => scheduling.preflight() } : {}),
+		isTurnInFlight: () => deps.app.chat.isStreaming(),
+		...(deps.setFleetRunPhase ? { setFleetRunPhase: deps.setFleetRunPhase } : {}),
 	});
 
 	const openResumeOverlayState = overlaySessions.openResume;
@@ -383,6 +417,9 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 	const openDecisionsOverlayState = overlayGeneralOpeners.openDecisions;
 	const openMemoryOverlayState = overlayGeneralOpeners.openMemory;
 	const openViewOverlayState = overlayGeneralOpeners.openView;
+	const openSideQuestionOverlayState = overlayGeneralOpeners.openSideQuestion;
+	const startFleetRunState = overlayGeneralOpeners.startFleetRun;
+	const startHandoffState = overlaySessions.startHandoff;
 	const toggleDispatchBoardOverlay = overlayGeneralOpeners.toggleDispatchBoard;
 
 	return {
@@ -402,6 +439,9 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		openDecisionsOverlayState,
 		openMemoryOverlayState,
 		openViewOverlayState,
+		openSideQuestionOverlayState,
+		startFleetRunState,
+		startHandoffState,
 		openModelOverlayState: overlayModelSelectors.openModelOverlayState,
 		openSettingsOverlayState: overlayModelSelectors.openSettingsOverlayState,
 		openResumeOverlayState,

package/src/interactive/overlay-permission-lifecycle.ts

@@ -50,6 +50,12 @@ export interface OverlayPermissionLifecycleDeps {
 	requestRender(): void;
 	/** End the in-flight run, carrying the text the operator will see. */
 	stopActiveTurn(reason: string): void;
+	/**
+	 * A worker permission request parked waiting for the operator. Fired once per
+	 * request, on the same dedup the operator-facing surfaces use, so a
+	 * re-presented dialog does not notify twice.
+	 */
+	onOperatorParked?(): void;
 }
 
 export interface OverlayPermissionLifecycle {
@@ -184,6 +190,8 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 	let pendingWorker: Pick<WorkerEscalationEntry, "agentId" | "requestId" | "runId"> | null = null;
 	const workerQueue: WorkerEscalationEntry[] = [];
 	const announcedRequestIds = new Set<string>();
+	/** Worker escalations already surfaced, so one request parks the operator once. */
+	const announcedWorkerRequestIds = new Set<string>();
 	let confirmed = false;
 	let stopping = false;
 
@@ -245,8 +253,10 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 	const unsubscribeWorker = deps.bus.on(BusChannels.PermissionRequested, (payload) => {
 		const entry = workerEscalationEntry(payload, deps.getAutonomy());
 		if (!entry) return;
+		if (!markPermissionRequestSurfaced(announcedWorkerRequestIds, entry.requestId)) return;
 		const notice = workerEscalationNotice(payload);
 		if (notice !== null) deps.appendNotice(notice.level, notice.text);
+		deps.onOperatorParked?.();
 		workerQueue.push(entry);
 		maybeOpenWorker();
 	});

package/src/interactive/overlay-resource-openers.ts

@@ -1,4 +1,4 @@
-import type { ResourcesContract } from "../domains/resources/index.js";
+import type { LibraryEntryKind, ResourcesContract } from "../domains/resources/index.js";
 import { installSkill as installMarketplaceSkill } from "../domains/resources/skills/marketplace.js";
 import type { TUI } from "../engine/tui.js";
 import type { ClioEditor } from "./clio-editor.js";
@@ -32,7 +32,7 @@ export interface OverlayResourceOpenersDeps {
 export interface OverlayResourceOpeners {
 	openHelpOverlayState(query?: string): void;
 	openAgentsOverlayState(): void;
-	openSkillsHubState(): void;
+	openSkillsHubState(tab?: LibraryEntryKind): void;
 	openPromptsOverlayState(): void;
 	openExtensionsOverlayState(): void;
 	openInteropOverlayState(): void;
@@ -61,10 +61,18 @@ export function createOverlayResourceOpeners(deps: OverlayResourceOpenersDeps):
 		deps.tui.requestRender();
 	};
 
-	const openSkillsHubState = (): void => {
+	const openSkillsHubState = (tab?: LibraryEntryKind): void => {
 		if (deps.transitions.state !== "closed") return;
 		deps.transitions.state = "skills-hub";
 		deps.transitions.handle = openSkills(deps.tui, {
+			...(tab ? { initialTab: tab } : {}),
+			// A fleet's `use` is its approval preview, which is a surface of its own.
+			// The hub closes first so the preview owns the overlay slot, exactly as
+			// `/fleet run <name>` typed into the composer would.
+			openFleetRun: (name) => {
+				deps.closeOverlay();
+				deps.getSlashContext().startFleetRun?.(name, {});
+			},
 			listSkills: () => deps.resources?.skills(process.cwd()) ?? { items: [], diagnostics: [] },
 			setEditorText: (text) => {
 				deps.editor.setText(text);