@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/oracle.ts

@@ -0,0 +1,179 @@
+/**
+ * `/oracle <question>`: the briefing an advisor is given, and the note its
+ * answer becomes.
+ *
+ * Oracle never receives a forked transcript. A transcript is the session's raw
+ * history, and handing it to an advisor makes the advisor agree with whatever
+ * the session already believes, which is the opposite of what an operator asks
+ * an oracle for. It is briefed on the record instead: the decisions the
+ * operator settled, the work the board still owes, and the last compaction
+ * summary when one exists.
+ *
+ * Pure: no I/O, no bus, no session, no dispatch. The caller owns the run.
+ */
+
+import type { OracleResult } from "../domains/agents/index.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
+import type { TaskBoardTask } from "../domains/session/task-board.js";
+
+/** The recipe `/oracle` dispatches. Shadow, so `/run` can never reach it. */
+export const ORACLE_AGENT_ID = "oracle";
+
+/**
+ * Total bound on the packed briefing, in UTF-8 bytes. Well under the 64 KiB
+ * an internal-origin dispatch briefing may carry, because the point of the
+ * digest is that a small local advisor can hold all of it at once.
+ */
+export const ORACLE_DIGEST_MAX_BYTES = 12 * 1024;
+
+/**
+ * Per-section byte caps. They sum to 11776, which leaves 512 bytes of the
+ * total for the section headers and blank lines the packer writes between
+ * them. Each section is clamped on its own before the whole digest is clamped
+ * again, so one runaway section can never starve the others: a 40 KiB
+ * compaction summary loses its own tail rather than the question's.
+ */
+export const ORACLE_DECISIONS_MAX_BYTES = 5120;
+export const ORACLE_TASKS_MAX_BYTES = 3072;
+export const ORACLE_COMPACTION_MAX_BYTES = 2048;
+export const ORACLE_QUESTION_MAX_BYTES = 1536;
+
+/** Row caps, applied before the byte caps. Newest decisions and lowest task ids first. */
+export const ORACLE_DECISIONS_MAX_ROWS = 24;
+export const ORACLE_TASKS_MAX_ROWS = 24;
+
+/** Appended wherever a cap cut content, so the advisor knows it is reading a tail-less record. */
+export const ORACLE_TRUNCATION_MARKER = "\n[truncated]";
+
+export const ORACLE_NO_DECISIONS = "(no settled decisions on this branch)";
+export const ORACLE_NO_TASKS = "(no open tasks on the board)";
+
+export interface OracleDigestSources {
+	/** Settled interviews, newest first, exactly as the decision board folds them. */
+	decisions: ReadonlyArray<DecisionLedgerEntry>;
+	/** The live task board's tasks; the packer keeps the open ones. */
+	tasks: ReadonlyArray<TaskBoardTask>;
+	/** The most recent compaction summary on the active branch, or null when the session never compacted. */
+	compactionSummary: string | null;
+	question: string;
+}
+
+export interface OracleDigest {
+	text: string;
+	/** True when any cap cut content. The digest says so in its own text as well. */
+	truncated: boolean;
+}
+
+function byteLength(text: string): number {
+	return Buffer.byteLength(text, "utf8");
+}
+
+/**
+ * Clamp to `maxBytes` including the marker, never past a UTF-8 code point. A
+ * marker that pushed the result over its own cap would make the section caps
+ * unable to add up to the total, which is the one property the packer relies
+ * on.
+ */
+function clamp(text: string, maxBytes: number): { text: string; truncated: boolean } {
+	if (byteLength(text) <= maxBytes) return { text, truncated: false };
+	const room = Math.max(0, maxBytes - byteLength(ORACLE_TRUNCATION_MARKER));
+	const buffer = Buffer.from(text, "utf8");
+	let cut = Math.min(room, buffer.byteLength);
+	while (cut > 0) {
+		const next = buffer[cut];
+		if (next === undefined || (next & 0xc0) !== 0x80) break;
+		cut -= 1;
+	}
+	return { text: `${buffer.subarray(0, cut).toString("utf8")}${ORACLE_TRUNCATION_MARKER}`, truncated: true };
+}
+
+/** One decision line. Superseded decisions carry their correction so a reversal is visible. */
+function decisionLine(decision: DecisionLedgerEntry["decisions"][number]): string {
+	const label = decision.label ? ` (${decision.label})` : "";
+	if (decision.status === "superseded") {
+		const correction = decision.correction ? `; corrected to ${decision.correction}` : "";
+		return `- ${decision.key}${label}: ${decision.value} [superseded${correction}]`;
+	}
+	return `- ${decision.key}${label}: ${decision.value}`;
+}
+
+function taskLine(task: TaskBoardTask): string {
+	return `- ${task.id} [${task.status}] ${task.title}`;
+}
+
+function isOpenTask(task: TaskBoardTask): boolean {
+	return task.status === "pending" || task.status === "active";
+}
+
+/**
+ * Pack the briefing. Sections are fixed and always present, so an advisor
+ * reading an empty one learns that the board is empty rather than that the
+ * packer omitted it.
+ */
+export function packOracleDigest(sources: OracleDigestSources): OracleDigest {
+	let truncated = false;
+
+	const decisionRows = sources.decisions
+		.flatMap((entry) => entry.decisions.map(decisionLine))
+		.slice(0, ORACLE_DECISIONS_MAX_ROWS);
+	if (decisionRows.length < sources.decisions.reduce((total, entry) => total + entry.decisions.length, 0)) {
+		truncated = true;
+	}
+	const decisions = clamp(decisionRows.join("\n") || ORACLE_NO_DECISIONS, ORACLE_DECISIONS_MAX_BYTES);
+	truncated = truncated || decisions.truncated;
+
+	const openTasks = sources.tasks.filter(isOpenTask);
+	const taskRows = openTasks.map(taskLine).slice(0, ORACLE_TASKS_MAX_ROWS);
+	if (taskRows.length < openTasks.length) truncated = true;
+	const tasks = clamp(taskRows.join("\n") || ORACLE_NO_TASKS, ORACLE_TASKS_MAX_BYTES);
+	truncated = truncated || tasks.truncated;
+
+	const summaryText = sources.compactionSummary?.trim() ?? "";
+	const summary = clamp(summaryText, ORACLE_COMPACTION_MAX_BYTES);
+	truncated = truncated || summary.truncated;
+
+	const question = clamp(sources.question.trim(), ORACLE_QUESTION_MAX_BYTES);
+	truncated = truncated || question.truncated;
+
+	const sections = [
+		"## Settled decisions",
+		decisions.text,
+		"",
+		"## Open tasks",
+		tasks.text,
+		"",
+		"## Last compaction summary",
+		summary.text.length > 0 ? summary.text : "(this session has not compacted)",
+		"",
+		"## Question",
+		question.text,
+	];
+	const whole = clamp(sections.join("\n"), ORACLE_DIGEST_MAX_BYTES);
+	return { text: whole.text, truncated: truncated || whole.truncated };
+}
+
+/** The bounded task an oracle run is given. The briefing carries the record; this carries the job. */
+export const ORACLE_TASK =
+	"Answer the question in the briefing's Question section. Check it against the settled decisions first, " +
+	"then return the strongest challenge you can support and the evidence that would change your mind.";
+
+/**
+ * The advisor's structured answer as the prose the operator note carries. The
+ * contract keeps the four fields typed so a run cannot half-answer; the note
+ * renders them because the main agent reads prose, not a payload.
+ */
+export function formatOracleAnswer(result: OracleResult): string {
+	const cited =
+		result.citedDecisions.length === 0
+			? "Cited decisions: none bear on this question."
+			: `Cited decisions: ${result.citedDecisions.join(", ")}`;
+	return [
+		`Verdict: ${result.verdict}`,
+		"",
+		`Strongest challenge: ${result.challenge}`,
+		"",
+		`What would change its mind: ${result.changesMyMind}`,
+		"",
+		cited,
+	].join("\n");
+}

package/src/interactive/overlay-ask-user-lifecycle.ts

@@ -14,6 +14,11 @@ export interface OverlayAskUserLifecycleDeps {
 	requestRender(): void;
 	registerHandler?(handler: AskUserHandler): () => void;
 	openAskUserOverlay?: typeof openAskUserOverlay;
+	/**
+	 * An ask_user request parked waiting for the operator. Fired when the
+	 * overlay session opens, not per question, so one interview notifies once.
+	 */
+	onOperatorParked?(): void;
 }
 
 export interface OverlayAskUserLifecycle {
@@ -61,6 +66,7 @@ export function createOverlayAskUserLifecycle(deps: OverlayAskUserLifecycleDeps)
 		deps.setOverlayState("ask-user");
 		session = openSession(deps.tui, { onCancel: () => pendingCancel?.() });
 		deps.setOverlayHandle(session);
+		deps.onOperatorParked?.();
 		deps.requestRender();
 		return session;
 	};
@@ -77,7 +83,7 @@ export function createOverlayAskUserLifecycle(deps: OverlayAskUserLifecycleDeps)
 		const activeSession = ensureSession();
 		if (!activeSession) return cancelledAskUserResult();
 		pendingCancel = cancel;
-		const result = await activeSession.ask(questions);
+		const result = await activeSession.ask(questions, invokeOptions?.decisionPresentation);
 		if (result.cancelled === true || !toolBacked) {
 			if (result.cancelled === true) cancelledForTurn = true;
 			close();

package/src/interactive/overlay-frame.ts

@@ -478,16 +478,19 @@ export function showClioOverlayFrame(
 	const { title, footerHint, tone, width, visible, maxHeight, margin, ...overlayOptions } = options;
 	const boxWidth = typeof width === "number" ? width : 0;
 	const frame = new ClioOverlayFrame(child, title, footerHint, boxWidth, frameAlignForAnchor(options.anchor), tone);
-	const marginRows = typeof margin === "number" ? margin * 2 : (margin?.top ?? 0) + (margin?.bottom ?? 0);
 	return tui.showOverlay(frame, {
 		...overlayOptions,
 		...(margin !== undefined ? { margin } : {}),
 		width: "100%",
 		visible: (termWidth, termHeight) => {
+			const shown = visible ? visible(termWidth, termHeight) : true;
+			// A caller may update an object margin in its visibility callback to
+			// follow live content geometry. Read it after that callback, every frame.
+			const marginRows = typeof margin === "number" ? margin * 2 : (margin?.top ?? 0) + (margin?.bottom ?? 0);
 			const available = Math.max(1, termHeight - marginRows);
 			const requested = resolveRowSize(maxHeight, termHeight);
 			frame.setRowBudget(requested === null ? available : Math.min(requested, available));
-			return visible ? visible(termWidth, termHeight) : true;
+			return shown;
 		},
 	});
 }

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

@@ -1,7 +1,16 @@
+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 { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/index.js";
+import { agentRoleFactsResolver, executeFleetRun, requestExecutionRole } from "../domains/dispatch/index.js";
+import {
+	canonicalMemoryRepositoryIdentity,
+	loadMemoryRecordsSync,
+	type MemoryRecord,
+	proposeMemoryPromotion,
+} from "../domains/memory/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import type { ContextLedger } from "../domains/session/context-ledger.js";
 import type { SessionMeta } from "../domains/session/index.js";
@@ -17,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";
@@ -26,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";
@@ -57,6 +69,8 @@ export interface OverlayGeneralOpenersDeps {
 	stateDir: string;
 	getSessionMeta: () => SessionMeta | null;
 	readSessionEntries?: ArtifactProviderDeps["readSessionEntries"];
+	/** Live settings, so `/context` can state the configured working-set policy. */
+	getSettings?: () => Readonly<ClioSettings>;
 	terminal: { columns: number };
 	dispatchBoard: ReturnType<typeof createDispatchBoardView>;
 	startDispatchBoardTicker: () => void;
@@ -69,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 {
@@ -81,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 {
@@ -92,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;
@@ -113,6 +162,10 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 				if (!readSessionEntries) return null;
 				return foldWorkingSet(readSessionEntries(), deps.getSessionMeta()?.pinnedLeafTurnId ?? undefined);
 			},
+			getWorkingSetConfig: () => {
+				const workingSet = deps.getSettings?.().context.workingSet;
+				return workingSet ? { enabled: workingSet.enabled, policy: workingSet.policy } : null;
+			},
 		});
 		deps.requestRender();
 	};
@@ -218,6 +271,32 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.state = "memory";
 		deps.transitions.handle = openMemoryOverlayFactory(deps.tui, deps.getTaskMemoryStatus, () => records, {
 			onClose: deps.closeOverlay,
+			onPromote: async (entry, scope) => {
+				const meta = deps.getSessionMeta();
+				if (!meta) throw new Error("memory promotion requires an active session");
+				const selection =
+					scope === "global"
+						? ({ scope: "global", acknowledgeGlobal: true } as const)
+						: (() => {
+								const repository = canonicalMemoryRepositoryIdentity(meta.cwd);
+								if (repository === null) {
+									throw new Error("repo promotion requires a canonical active repository identity");
+								}
+								return { scope: "repo", repository } as const;
+							})();
+				const result = await proposeMemoryPromotion(
+					deps.dataDir,
+					{
+						kind: "task-bank-entry",
+						sessionId: meta.id,
+						evidenceRefs: [`session-${meta.id}`],
+						entry,
+					},
+					selection,
+				);
+				records = loadMemoryRecordsSync(deps.dataDir);
+				return result;
+			},
 		});
 		deps.requestRender();
 	};
@@ -261,11 +340,158 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 	const dispatchBoardHint = (): string => {
 		const row = deps.dispatchBoard.selectedRow();
 		const entries = [{ key: "↑↓", verb: "select" }];
+		if (row) entries.push({ key: "Enter", verb: deps.dispatchBoard.detailExpanded() ? "hide detail" : "detail" });
 		if (row && isDispatchBoardRowSteerable(row)) entries.push({ key: "s", verb: "steer" });
 		if (row && isDispatchBoardRowCancellable(row)) entries.push({ key: "x", verb: "cancel" });
 		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,
@@ -276,5 +502,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		openMemory,
 		openView,
 		toggleDispatchBoard,
+		openSideQuestion,
+		startFleetRun,
 	};
 }

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

@@ -25,12 +25,28 @@ export type OverlayState =
 	| "prompts"
 	| "extensions"
 	| "interop"
-	| "skills-hub";
+	| "skills-hub"
+	| "side-question"
+	| "handoff-review"
+	| "fleet-run-approval";
 
 export interface PermissionOverlayKeyDeps {
 	cancelPermission: () => void;
 	confirmPermission: () => void;
 	stopTurnFromPermission: () => void;
+	/**
+	 * Whether the composer holds text. Enter must not allow a parked call while
+	 * it does (issue #186): an operator who typed a message and pressed the
+	 * habitual send key meant to send, and on a safety rail the ambiguous key
+	 * resolves away from "allow". Absent means an empty composer.
+	 */
+	composerHasDraft?: () => boolean;
+	/**
+	 * Deliver a draft-editing key to the composer while the prompt owns input,
+	 * so the draft that makes Enter inert can be cleared without first denying
+	 * the call. Only the deletion keys in `isDraftEditKey` arrive here.
+	 */
+	editDraft?: (data: string) => void;
 }
 
 export interface DispatchBoardOverlayKeyDeps {
@@ -39,6 +55,8 @@ export interface DispatchBoardOverlayKeyDeps {
 	selectNextDispatch: () => void;
 	steerSelectedDispatch: () => void;
 	cancelSelectedDispatch: () => void;
+	/** Open or close the selected run's worker-progress detail. */
+	toggleSelectedDispatchDetail: () => void;
 }
 
 interface CloseOverlayKeyDeps {
@@ -55,10 +73,29 @@ export function isEscapeKey(data: string): boolean {
 	return matchesKey(data, "escape") && !isKeyRelease(data);
 }
 
+const DRAFT_EDIT_KEYS = ["backspace", "delete", "ctrl+u", "ctrl+w", "alt+backspace", "ctrl+k"] as const;
+
+/**
+ * The keys that only ever remove text from the composer. They are the one
+ * class of input a pending permission prompt lets through, because they
+ * cannot type a command, cannot submit, and are the way out of the inert-Enter
+ * state a draft puts the prompt in.
+ */
+function isDraftEditKey(data: string): boolean {
+	return !isKeyRelease(data) && DRAFT_EDIT_KEYS.some((key) => matchesKey(data, key));
+}
+
 /** Pure permission overlay key router: returns true when the input was consumed. */
 export function routePermissionOverlayKey(data: string, deps: PermissionOverlayKeyDeps): boolean {
 	if (matchesKey(data, "enter") && !isKeyRelease(data)) {
-		deps.confirmPermission();
+		// Consumed either way: with a draft the press changes nothing, and the
+		// composer rail says what clears it. Letting it fall through would hand
+		// Enter to the editor, which is the send path this guard exists to block.
+		if (!(deps.composerHasDraft?.() ?? false)) deps.confirmPermission();
+		return true;
+	}
+	if (deps.editDraft && isDraftEditKey(data)) {
+		deps.editDraft(data);
 		return true;
 	}
 	if (isEscapeKey(data)) {
@@ -98,6 +135,12 @@ export function routeDispatchBoardOverlayKey(data: string, deps: DispatchBoardOv
 		deps.cancelSelectedDispatch();
 		return true;
 	}
+	// Worker progress is expanded detail the operator asks for. The default list
+	// stays compact so a fan-out of scouts costs one card each.
+	if (matchesKey(data, "enter")) {
+		deps.toggleSelectedDispatchDetail();
+		return true;
+	}
 	return false;
 }
 
@@ -180,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;