@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/interactive/interactive-tickers.ts

@@ -1,5 +1,5 @@
 import { type TaskBoardSnapshot, type TaskBoardStore, taskBoardCounts } from "../domains/session/task-board.js";
-import { Text, type TUI, visibleWidth } from "../engine/tui.js";
+import { Text, type TUI, visibleWidth, wrapTextWithAnsi } from "../engine/tui.js";
 import {
 	CONTEXT_ISLAND_WIDTH,
 	type ContextActivitySnapshot,
@@ -7,6 +7,7 @@ import {
 } from "./context-activity.js";
 import { type DispatchBoardRow, formatTaskIslandLines, TASK_ISLAND_WIDTH } from "./dispatch-board.js";
 import { clioTheme, frame, GLYPH } from "./theme/index.js";
+import { isHelperRun } from "./worker-stream.js";
 
 export interface InteractiveTickerHandle {
 	unref?(): void;
@@ -49,7 +50,15 @@ function formatTaskBoardIslandLines(board: TaskBoardSnapshot): string[] {
 		const glyph = active ? theme.fg("accent", GLYPH.running) : theme.fg("dim", GLYPH.queued);
 		body.push(`${glyph} ${theme.fg("dim", next.id)} ${theme.fg("muted", next.title)}`);
 	}
-	return frame(theme, "Tasks", body, TASK_ISLAND_WIDTH + 4);
+	return frame(
+		theme,
+		"Tasks",
+		[
+			...body.flatMap((line) => wrapTextWithAnsi(line, TASK_ISLAND_WIDTH)).slice(0, 7),
+			theme.fg("dim", "/tasks · full task board"),
+		],
+		TASK_ISLAND_WIDTH + 4,
+	);
 }
 
 export interface InteractiveTickers {
@@ -69,13 +78,17 @@ export function createInteractiveTickers(deps: InteractiveTickersDeps): Interact
 		((handle: InteractiveTickerHandle) => clearInterval(handle as ReturnType<typeof setInterval>));
 	const taskIsland = new Text("", 0, 0);
 	const contextIsland = new Text("", 0, 0);
+	let taskIslandHeight = 24;
 	const taskIslandWidth = formatTaskIslandLines([]).reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
 	const taskIslandHandle = deps.tui.showOverlay(taskIsland, {
 		anchor: "top-right",
 		width: taskIslandWidth,
 		margin: { top: 1, right: 1 },
 		nonCapturing: true,
-		visible: (width, height) => width >= 80 && height >= 18,
+		visible: (width, height) => {
+			taskIslandHeight = height;
+			return width >= 80 && height >= 18;
+		},
 	});
 	taskIslandHandle.setHidden(true);
 	const contextIslandHandle = deps.tui.showOverlay(contextIsland, {
@@ -94,7 +107,7 @@ export function createInteractiveTickers(deps: InteractiveTickersDeps): Interact
 	let taskIslandHidden = true;
 
 	const renderTaskIsland = (): boolean => {
-		const rows = deps.dispatchBoardStore.activeRows();
+		const rows = deps.dispatchBoardStore.activeRows().filter((row) => !isHelperRun(row));
 		const board = rows.length === 0 ? (deps.getTaskBoard?.() ?? null) : null;
 		const boardHasOpenTasks = board !== null && taskBoardCounts(board).open > 0;
 		const contextActive = deps.contextActivityStore.active();
@@ -111,7 +124,10 @@ export function createInteractiveTickers(deps: InteractiveTickersDeps): Interact
 		// leaves the last text in place, which is unreachable while hidden.
 		if (hidden && taskIslandHidden && rows.length === 0 && !boardHasOpenTasks) return visibilityChanged;
 		taskIslandHidden = hidden;
-		if (rows.length > 0) taskIsland.setText(formatTaskIslandLines(rows).join("\n"));
+		if (rows.length > 0)
+			taskIsland.setText(
+				formatTaskIslandLines(rows, Math.max(1, Math.min(4, Math.floor((taskIslandHeight - 8) / 9)))).join("\n"),
+			);
 		else if (board) taskIsland.setText(formatTaskBoardIslandLines(board).join("\n"));
 		taskIsland.invalidate();
 		return visibilityChanged || !hidden;

package/src/interactive/keybinding-manager.ts

@@ -571,3 +571,12 @@ export function createKeybindingManagerForTesting(
 ): ClioKeybindingManager {
 	return buildManager(overrides, env, false);
 }
+
+/** Title-case a KeyId for compact chrome hints, preserving each caller's fallback. */
+export function formatKeyLabel(keyId: string | undefined, fallback = "unbound"): string {
+	if (!keyId || keyId.length === 0) return fallback;
+	return keyId
+		.split("+")
+		.map((segment) => (segment.length === 0 ? segment : segment.charAt(0).toUpperCase() + segment.slice(1)))
+		.join("+");
+}

package/src/interactive/overlay-frame.ts

@@ -386,6 +386,7 @@ export class ClioOverlayFrame implements Component {
 		 * decision treatment only while it is actually holding a decision.
 		 */
 		private readonly tone?: OverlayTone,
+		private readonly fullscreen = false,
 	) {}
 
 	setRowBudget(rows: number): void {
@@ -418,11 +419,21 @@ export class ClioOverlayFrame implements Component {
 		}
 		const label = titleText.length > 0 ? `─ ${titleText} ` : "─ ";
 		const side = clioFrame("│", tone ?? "frame");
-		const boxLines = [
-			brandedTopBorder(label, contentWidth + 2, tone),
-			...fitBody(childLines, this.rowBudget, contentWidth).map((line) => `${side} ${padAnsi(line, contentWidth)} ${side}`),
-			brandedBottomBorder(contentWidth + 2, hint, tone),
-		];
+		const body = [...fitBody(childLines, this.rowBudget, contentWidth)];
+		if (this.fullscreen) {
+			while (body.length < Math.max(0, this.rowBudget - 2)) body.push("");
+		}
+		const boxLines = this.fullscreen
+			? [
+					padAnsi(`  ${clioTitle(titleText, tone)}`, boxWidth),
+					...body.map((line) => `  ${padAnsi(line, contentWidth)}  `),
+					padAnsi(`  ${clioTheme().fg("muted", hint ?? "")}`, boxWidth),
+				]
+			: [
+					brandedTopBorder(label, contentWidth + 2, tone),
+					...body.map((line) => `${side} ${padAnsi(line, contentWidth)} ${side}`),
+					brandedBottomBorder(contentWidth + 2, hint, tone),
+				];
 		const slack = Math.max(0, width - boxWidth);
 		const lines = ((): string[] => {
 			if (slack === 0) return boxLines;
@@ -500,11 +511,22 @@ export function showClioOverlayFrame(
 		 * really is fixed and surface-specific.
 		 */
 		markerId: string;
+		/** Cover the viewport, including unused rows, while background content updates. */
+		fullscreen?: boolean;
 	},
 ): OverlayHandle {
-	const { title, footerHint, tone, width, visible, maxHeight, margin, markerId, ...overlayOptions } = options;
+	const { title, footerHint, tone, width, visible, maxHeight, margin, markerId, fullscreen, ...overlayOptions } =
+		options;
 	const boxWidth = typeof width === "number" ? width : 0;
-	const frame = new ClioOverlayFrame(child, title, footerHint, boxWidth, frameAlignForAnchor(options.anchor), tone);
+	const frame = new ClioOverlayFrame(
+		child,
+		title,
+		footerHint,
+		boxWidth,
+		frameAlignForAnchor(options.anchor),
+		tone,
+		fullscreen,
+	);
 	const handle = tui.showOverlay(frame, {
 		...overlayOptions,
 		...(margin !== undefined ? { margin } : {}),

package/src/interactive/overlay-lifecycle.ts

@@ -36,6 +36,7 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "dataDir"
 	| "dispatch"
 	| "getFleetNodes"
+	| "getRouteBreakers"
 	| "getSessionId"
 	| "getSettings"
 	| "getTaskBoard"
@@ -271,9 +272,9 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		dispatch: deps.app.dispatch,
 		getAutonomy: () => deps.app.getSettings?.().safety.autonomy ?? "auto-edit",
 		getOverlayState: () => overlayTransitions.state,
-		openPermissionOverlay: (view, inspect) => {
+		openPermissionOverlay: (view, inspect, invocation) => {
 			if (overlayTransitions.state === "permission-confirm") return false;
-			const body = createPermissionOverlayBody(view, inspect);
+			const body = createPermissionOverlayBody(view, inspect, invocation);
 			permissionBody = body;
 			const handle = showOverlayFrame(tui, body, {
 				...permissionOverlayPlacement(tui, editor, footer.view),
@@ -360,6 +361,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(deps.app.onSelectModel ? { onSelectModel: deps.app.onSelectModel } : {}),
 		...(deps.app.onSetThinkingLevel ? { onSetThinkingLevel: deps.app.onSetThinkingLevel } : {}),
 		...(deps.app.getFleetNodes ? { getFleetNodes: deps.app.getFleetNodes } : {}),
+		...(deps.app.getRouteBreakers ? { getRouteBreakers: deps.app.getRouteBreakers } : {}),
 		connectTarget: (targetId) => overlayAuth.openConnectFlow(targetId),
 		...(deps.app.interop ? { getInteropProposals: interopProposalsFor(deps.app.interop) } : {}),
 		...(openModelOverlayFactory ? { openModelOverlay: openModelOverlayFactory } : {}),
@@ -419,7 +421,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		getContextLedger: () => deps.app.chat.contextLedger(),
 		contextChat: deps.app.chat,
 		bus: deps.app.bus,
-		...(deps.app.onContextClear ? { onContextClear: deps.app.onContextClear } : {}),
+		...(deps.app.onContextClear ? { onContextClear: (options) => deps.app.onContextClear?.(options, deps.io) } : {}),
 		stderr: (text) => io.stderr(text),
 		refreshFooter: () => footer.refresh(),
 		toggleFooter: () => footer.toggleExpanded(),

package/src/interactive/overlay-model-selectors.ts

@@ -1,6 +1,7 @@
 import type { ClioSettings } from "../core/config.js";
 import type { ThinkingLevel } from "../core/defaults.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import type { RouteBreakerView } from "../domains/dispatch/contract.js";
 import type { InteropProposal } from "../domains/interop/index.js";
 import type { ProvidersContract } from "../domains/providers/index.js";
 import type { FleetNodeSnapshot } from "../domains/scheduling/cluster.js";
@@ -33,6 +34,8 @@ export interface OverlayModelSelectorsDeps {
 	onSetThinkingLevel?: (level: ThinkingLevel, scope?: ModelScopeChoice) => void;
 	/** Settings → Fleet shows live node placement health when the scheduler exposes it. */
 	getFleetNodes?: () => ReadonlyArray<FleetNodeSnapshot>;
+	/** Settings → Targets shows this process's dispatch breaker state per route. */
+	getRouteBreakers?: () => ReadonlyArray<RouteBreakerView>;
 	/** Settings → Targets "connect" runs the auth flow over the open settings overlay. */
 	connectTarget?: (targetId: string) => Promise<void> | void;
 	/** Settings → Advanced offers detected agents on the delegation.agents row. */
@@ -121,6 +124,7 @@ export function createOverlayModelSelectors(deps: OverlayModelSelectorsDeps): Ov
 			...(section ? { section } : {}),
 			...(rowId ? { rowId } : {}),
 			...(deps.getFleetNodes ? { getFleetNodes: deps.getFleetNodes } : {}),
+			...(deps.getRouteBreakers ? { getRouteBreakers: deps.getRouteBreakers } : {}),
 			...(deps.connectTarget ? { connectTarget: deps.connectTarget } : {}),
 			...(deps.getInteropProposals ? { getInteropProposals: deps.getInteropProposals } : {}),
 			writeSettings: (next) => {

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

@@ -50,7 +50,7 @@ export interface OverlayPermissionLifecycleDeps {
 	 * mutation text and is the only channel that does; it is process-local by
 	 * construction, so it is passed here rather than folded into the view.
 	 */
-	openPermissionOverlay(view: ApprovalRequestView, inspect?: MutationInspector): boolean;
+	openPermissionOverlay(view: ApprovalRequestView, inspect?: MutationInspector, invocation?: () => unknown): boolean;
 	closeOverlay(): void;
 	appendNotice(level: NoticeLevel, text: string): void;
 	applyApprovalState(event: ToolApprovalStateEvent): void;
@@ -58,7 +58,7 @@ export interface OverlayPermissionLifecycleDeps {
 	/** 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
+	 * A 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.
 	 */
@@ -292,6 +292,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			// could not mount, when it is the operator's only additional signal.
 			const announceParked = (): void => {
 				if (!markPermissionRequestSurfaced(announcedRequestIds, meta.requestId)) return;
+				deps.onOperatorParked?.();
 				const notice = approvalParkedNotice(call.tool, decision, autonomy);
 				deps.appendNotice(notice.level, notice.text);
 			};
@@ -303,11 +304,11 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 					view,
 				});
 			}
-			if (!deps.openPermissionOverlay(view, mainMutationInspector(call, view))) {
+			if (!deps.openPermissionOverlay(view, mainMutationInspector(call, view), () => call.args)) {
 				announceParked();
 				return;
 			}
-			markPermissionRequestSurfaced(announcedRequestIds, meta.requestId);
+			if (markPermissionRequestSurfaced(announcedRequestIds, meta.requestId)) deps.onOperatorParked?.();
 			pendingPermission = { call, decision, meta };
 			pendingWorker = null;
 			confirmed = false;
@@ -398,7 +399,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			// here printed the same guidance twice in one payload.
 			const cancellationReason = stopping
 				? "User denied this tool call and stopped the turn from the permission confirmation prompt. The turn is over."
-				: "User cancelled this tool call from the permission confirmation prompt. Wait for new instruction.";
+				: "User denied this invocation from the permission confirmation prompt. This call will not run; no approval is pending.";
 			deps.bus.emit(BusChannels.PermissionResolved, {
 				status: "denied",
 				...(permission?.meta ? { requestId: permission.meta.requestId } : {}),

package/src/interactive/overlays/ask-user.ts

@@ -40,38 +40,17 @@ export const ASK_USER_DECISION_TONE: ClioToken = DEFAULT_ASK_USER_PRESENTATION.s
 export const ASK_USER_DECISION_TITLE = DEFAULT_ASK_USER_PRESENTATION.title;
 export const ASK_USER_WAITING_TITLE = "Ask User";
 
-/**
- * One box for every request shape.
- *
- * Three surfaces used to answer three request shapes: a fixed 68-column bar for
- * a short question, a fixed 88-column panel for a longer option list, and a
- * full-screen workspace for an interview. The bar cut Daisy's four-part research
- * question to two parts at every terminal width, and the workspace put twelve
- * empty rows between the question and its options. The box now sizes itself to
- * what it has to say, sits above the composer where the operator was typing,
- * and takes a readable measure from the terminal rather than a constant.
- */
-export const ASK_USER_MAX_BOX_WIDTH = 100;
-export const ASK_USER_MIN_BOX_WIDTH = 40;
-const ASK_USER_MARGIN = { top: 1, right: 2, bottom: 1, left: 2 };
-/** Two border rows plus the one-row margin above and below. */
+/** An interview owns the viewport for every round, including one-question rounds. */
 const ASK_USER_FRAME_AND_MARGIN_ROWS = 4;
 const MIN_INNER_ROWS = 6;
 /** The question region keeps at least this many rows before the options window shrinks. */
 const MIN_QUESTION_ROWS = 3;
-/** Below this width an option's description goes under its label instead of beside it. */
-const STACKED_OPTION_WIDTH = 56;
 const MAX_LABEL_COLUMN = 30;
 const MIN_LABEL_COLUMN = 12;
 const ELLIPSIS = "…";
 const CONTINUATION_INDENT = "    ";
 const TEXT_ASKING_DESCRIPTION = "opens a text field for your answer";
 
-export function askUserBoxWidth(columns: number): number {
-	if (!Number.isFinite(columns) || columns <= 0) return ASK_USER_MAX_BOX_WIDTH;
-	return Math.max(ASK_USER_MIN_BOX_WIDTH, Math.min(ASK_USER_MAX_BOX_WIDTH, Math.floor(columns) - 4));
-}
-
 export interface OpenAskUserOverlayDeps {
 	onCancel: () => void;
 }
@@ -366,62 +345,25 @@ interface OptionRowLayout {
 	rows: string[][];
 }
 
-/**
- * Every option, with its whole description.
- *
- * A description is what the operator is choosing between: "+Latency,
- * +Simplicity. Good for: Financial, Auth" is the trade-off, and the old table
- * cut it to its first clause on every row the cursor was not on. Every row now
- * wraps its description beside the label, or under it when the box is too
- * narrow for two columns, and the row carries no key: the footer does.
- */
+/** Full-width labels and explanations; selection never hides another option's explanation. */
 function layoutOptionRows(items: ReadonlyArray<SelectItem>, focusedIndex: number, width: number): OptionRowLayout {
 	const theme = clioTheme();
 	const safeWidth = Math.max(8, width);
-	const stacked = safeWidth < STACKED_OPTION_WIDTH;
-	const widestLabel = items.reduce((max, item) => Math.max(max, visibleWidth(item.label)), 0);
-	const labelColumn = Math.max(
-		MIN_LABEL_COLUMN,
-		Math.min(MAX_LABEL_COLUMN, Math.floor(safeWidth * 0.42), widestLabel + 2),
-	);
-	const rows: string[][] = [];
-	for (let index = 0; index < items.length; index += 1) {
-		const item = items[index];
-		if (!item) continue;
-		const focused = index === focusedIndex;
-		const prefix = focused ? theme.fg("accent", `${GLYPH.cursor} `) : "  ";
-		const description = item.description?.replace(/[\r\n]+/g, " ").trim() ?? "";
-		const paint = (text: string): string => (focused ? theme.style("accent", text, { bold: true }) : text);
-		const describe = (text: string): string => (focused ? text : theme.fg("muted", text));
-		if (description.length === 0) {
-			rows.push(
-				wrapTextWithAnsi(paint(item.label), Math.max(4, safeWidth - 2)).map(
-					(line, at) => `${at === 0 ? prefix : "  "}${line}`,
-				),
-			);
-			continue;
-		}
-		if (stacked || visibleWidth(item.label) > labelColumn - 1) {
-			const labelRows = wrapTextWithAnsi(paint(item.label), Math.max(4, safeWidth - 2)).map(
-				(line, at) => `${at === 0 ? prefix : "  "}${line}`,
-			);
-			const descriptionRows = wrapTextWithAnsi(
-				describe(description),
-				Math.max(4, safeWidth - CONTINUATION_INDENT.length),
-			).map((line) => `${CONTINUATION_INDENT}${line}`);
-			rows.push([...labelRows, ...descriptionRows]);
-			continue;
-		}
-		const spacing = " ".repeat(Math.max(1, labelColumn - visibleWidth(item.label)));
-		const descriptionWidth = Math.max(4, safeWidth - 2 - labelColumn);
-		const wrapped = wrapTextWithAnsi(describe(description), descriptionWidth);
-		const indent = " ".repeat(2 + labelColumn);
-		rows.push([
-			`${prefix}${paint(item.label)}${spacing}${wrapped[0] ?? ""}`,
-			...wrapped.slice(1).map((line) => `${indent}${line}`),
-		]);
-	}
-	return { rows };
+	return {
+		rows: items.map((item, index) => {
+			const focused = index === focusedIndex;
+			const label = theme.paint(item.label, { bold: true, ...(focused ? { fg: "accent" as const } : {}) });
+			const prefix = focused ? theme.fg("accent", `${GLYPH.cursor} `) : "  ";
+			const labels = wrapTextWithAnsi(label, safeWidth - 2).map((line, at) => `${at === 0 ? prefix : "  "}${line}`);
+			const description = item.description?.trim();
+			const explanation = description
+				? formatAskUserQuestion(description, Math.max(4, safeWidth - CONTINUATION_INDENT.length)).map(
+						(line) => `${CONTINUATION_INDENT}${line}`,
+					)
+				: [];
+			return [...labels, ...explanation];
+		}),
+	};
 }
 
 /**
@@ -549,7 +491,10 @@ class AskUserOverlayView implements Component {
 		return true;
 	}
 	handleInput(data: string): void {
-		if (this.phase !== "asking") return;
+		if (this.phase !== "asking") {
+			if (matchesKey(data, "escape")) this.deps.onCancel();
+			return;
+		}
 		const question = this.currentQuestion();
 		const state = this.currentState();
 		if (!question || !state) return;
@@ -558,6 +503,20 @@ class AskUserOverlayView implements Component {
 		// options, so the region has keys of its own that neither control claims.
 		if (this.handleScrollInput(data, state.mode)) return;
 
+		// Question navigation must work from both choices and the answer editor.
+		// Bare arrows browse an empty answer; once typing starts they edit text.
+		const canBrowseWithArrows = state.mode !== "text" || !(this.text?.getText() ?? state.inputValue);
+		if (this.questions.length > 1) {
+			if (matchesKey(data, "shift+tab") || (canBrowseWithArrows && matchesKey(data, "left"))) {
+				this.goToRelativeQuestion(-1);
+				return;
+			}
+			if (matchesKey(data, "tab") || (canBrowseWithArrows && matchesKey(data, "right"))) {
+				this.goToRelativeQuestion(1);
+				return;
+			}
+		}
+
 		if (state.mode === "text") {
 			if (matchesKey(data, "escape")) {
 				this.escapeFromTextInput(question, state);
@@ -567,14 +526,6 @@ class AskUserOverlayView implements Component {
 			return;
 		}
 
-		if (this.isPreviousQuestionKey(data)) {
-			this.goToRelativeQuestion(-1);
-			return;
-		}
-		if (this.isNextQuestionKey(data)) {
-			this.goToRelativeQuestion(1);
-			return;
-		}
 		if (question.multi_select === true && data === " ") {
 			this.toggleCurrentSelection(question, state);
 			return;
@@ -608,17 +559,55 @@ class AskUserOverlayView implements Component {
 	 * rows it needs.
 	 */
 	render(width: number): string[] {
+		const wide = width >= 120 && this.maxInnerRows() >= 24 && this.phase === "asking" && this.questions.length > 1;
+		const menuWidth = 28;
+		const bodyWidth = Math.min(104, Math.max(1, width - (wide ? menuWidth + 5 : 0)));
+		const body = this.renderBody(bodyWidth, wide);
+		if (!wide) return body;
+		const theme = clioTheme();
+		const menu = [theme.style("accent", "QUESTIONS", { bold: true }), ""];
+		this.questions.forEach((question, index) => {
+			const active = index === this.index;
+			const answered = Boolean(this.states[index]?.answer.trim());
+			const prefix = active ? "› " : answered ? "✓ " : "○ ";
+			menu.push(
+				...wrapLabeledValue(
+					prefix,
+					theme.paint(`${index + 1}. ${compactTitle(question)}`, { fg: active ? "accent" : "muted", bold: active }),
+					menuWidth,
+				),
+				"",
+			);
+		});
+		menu.push(theme.fg("muted", "Tab / Shift+Tab to browse"));
+		return Array.from({ length: Math.min(this.maxInnerRows(), Math.max(menu.length, body.length)) }, (_, index) => {
+			const left = menu[index] ?? "";
+			return `${left}${" ".repeat(Math.max(0, menuWidth - visibleWidth(left)))}  ${theme.fg("frame", "│")}  ${body[index] ?? ""}`;
+		});
+	}
+
+	private renderBody(width: number, hasMenu: boolean): string[] {
 		const safeWidth = Math.max(1, width);
 		const maxRows = this.maxInnerRows();
 		if (this.phase !== "asking") return this.renderWaiting(safeWidth, maxRows);
 		const question = this.currentQuestion();
 		if (!question) return [clioTheme().fg("muted", "No questions.")];
 
-		const strip = this.renderQuestionStrip(safeWidth);
+		const theme = clioTheme();
+		const strip = [
+			fitLine(
+				theme.style("accent", `Question ${this.index + 1} of ${this.questions.length} · Round ${this.roundsAnswered + 1}`, {
+					bold: true,
+				}),
+				safeWidth,
+			),
+			"",
+			...(hasMenu ? [] : this.renderQuestionStrip(safeWidth)),
+		];
 		const header = this.renderQuestionHeader(question, safeWidth);
 		const details = this.renderDecisionContext(safeWidth);
 		const status = this.status.length > 0 ? wrapTextWithAnsi(clioTheme().fg("dim", this.status), safeWidth) : [];
-		const body = formatAskUserQuestion(question.question, safeWidth);
+		const body = formatAskUserQuestion(question.question, safeWidth).map((line) => theme.paint(line, { bold: true }));
 		const fixedTop = [...strip, ...header, ...details];
 		// The control is sized after the question has claimed its minimum, so a
 		// long option list cannot push a short question off the box.
@@ -701,12 +690,14 @@ class AskUserOverlayView implements Component {
 			// back; a question without one has nothing behind it and the key still
 			// leaves the interview. The footer says which one this is.
 			const escapeVerb: OverlayEscVerb = questionHasOptions(question) ? "back" : "close";
-			const entries: HintEntry[] = [{ key: "Enter", verb: recordAnswer }];
+			const entries: HintEntry[] = [];
+			if (this.questions.length > 1) entries.push({ key: "Tab/Shift+Tab", verb: "question" });
+			entries.push({ key: "Enter", verb: recordAnswer });
 			if (this.deps.tui) entries.push({ key: getKeybindings().getKeys("tui.input.newLine").join("/"), verb: "newline" });
 			return buildHint([...entries, ...scroll], escapeVerb);
 		}
 		const entries: HintEntry[] = [];
-		if (this.questions.length > 1) entries.push({ key: "Left/Right", verb: "question" });
+		if (this.questions.length > 1) entries.push({ key: "←/→ or Tab", verb: "question" });
 		if (question.multi_select === true) entries.push({ key: "Space", verb: "toggle" });
 		// `t` is on every select footer because the operator cannot tell from a
 		// label whether the option needs a figure attached until they read it.
@@ -797,14 +788,6 @@ class AskUserOverlayView implements Component {
 		return this.states[this.index] ?? null;
 	}
 
-	private isPreviousQuestionKey(data: string): boolean {
-		return this.questions.length > 1 && matchesKey(data, "left");
-	}
-
-	private isNextQuestionKey(data: string): boolean {
-		return this.questions.length > 1 && matchesKey(data, "right");
-	}
-
 	/**
 	 * The key that adds typed text to the option under the cursor.
 	 *
@@ -843,7 +826,7 @@ class AskUserOverlayView implements Component {
 	 */
 	private renderQuestionHeader(question: AskUserQuestion, width: number): string[] {
 		const theme = clioTheme();
-		const parts: string[] = [];
+		const parts: string[] = [theme.fg("accent", "Clio-Coder asks you")];
 		if (question.header) parts.push(screenTitle(theme, question.header));
 		if (this.questions.length <= 1 && this.roundsAnswered > 0) {
 			parts.push(theme.fg("dim", `Round ${this.roundsAnswered + 1}`));
@@ -941,6 +924,10 @@ class AskUserOverlayView implements Component {
 			items.findIndex((item) => item.value === selectedItem.value),
 		);
 		const layout = layoutOptionRows(items, focusedIndex, width);
+		const totalRows = layout.rows.reduce((sum, rows) => sum + rows.length, 0);
+		if (totalRows + items.length <= rowBudget) {
+			for (const rows of layout.rows) rows.push("");
+		}
 		if ((layout.rows[focusedIndex]?.length ?? 0) >= rowBudget) {
 			this.optionDetailRows = [
 				"",
@@ -1303,13 +1290,7 @@ export function createAskUserViewForTesting(deps: {
 	};
 }
 
-/**
- * Show the ask_user overlay.
- *
- * One frame for the whole interview: it sits above the composer, takes its
- * width from the terminal, and its height from what the round has to say. A
- * shape change between rounds is just the next render; nothing is remounted.
- */
+/** Keep one full-screen interview mounted across questions and background work. */
 export function openAskUserOverlay(tui: TUI, deps: OpenAskUserOverlayDeps): AskUserOverlaySession {
 	let closed = false;
 
@@ -1321,25 +1302,37 @@ export function openAskUserOverlay(tui: TUI, deps: OpenAskUserOverlayDeps): AskU
 	});
 
 	const handle = showClioOverlayFrame(tui, view, {
-		anchor: "bottom-center",
-		width: askUserBoxWidth(tui.terminal?.columns ?? 0),
-		margin: ASK_USER_MARGIN,
+		anchor: "top-left",
+		width: "100%",
+		margin: 0,
+		fullscreen: true,
 		// Not derived from the title: this modal swaps between a waiting title
 		// and a classified decision title without ever changing hands.
 		markerId: "ask-user",
-		title: () => (view.isDecisionPending() ? view.decisionTitle() : ASK_USER_WAITING_TITLE),
+		title: () => (view.isDecisionPending() ? `Clio-Coder interview · ${view.decisionTitle()}` : "Clio-Coder interview"),
 		tone: () => (view.isDecisionPending() ? view.decisionTone() : undefined),
-		footerHint: () => view.footerHint(),
+		footerHint: () => `${view.footerHint()} · drag to select/copy`,
 	});
+	const selectionTui = tui as TUI & { useTerminalSelection?: () => () => void };
+	let releaseSelection = selectionTui.useTerminalSelection?.();
 
 	const close = (): void => {
 		if (closed) return;
 		closed = true;
 		view.close();
+		releaseSelection?.();
+		releaseSelection = undefined;
 		handle.hide();
 	};
 	return {
-		setHidden: (hidden) => handle.setHidden(hidden),
+		setHidden: (hidden) => {
+			if (closed) return;
+			if (hidden) {
+				releaseSelection?.();
+				releaseSelection = undefined;
+			} else releaseSelection ??= selectionTui.useTerminalSelection?.();
+			handle.setHidden(hidden);
+		},
 		isHidden: () => (closed ? true : handle.isHidden()),
 		focus: () => handle.focus(),
 		unfocus: (options) => (options ? handle.unfocus(options) : handle.unfocus()),

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

@@ -134,6 +134,7 @@ export function openHelpOverlay(
 			group: "Topics",
 			detail: () => [
 				"# Fleet runs & steering",
+				"**Internal helpers**: Scout and other shadow agents appear as Clio → agent cards. Compact shows identity/status, standard adds task/progress, and detailed shows the fuller worker report. `/view` opens the complete report. Helpers remain inspectable and steerable/cancellable through this board using the same supported actions, without floating fleet cards.",
 				`**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.",

package/src/interactive/overlays/message-picker.ts

@@ -1,6 +1,7 @@
 import { collectSessionEntries } from "../../domains/session/compaction/session-entries.js";
 import type { SessionContract } from "../../domains/session/contract.js";
 import type { MessageEntry } from "../../domains/session/entries.js";
+import { buildTurnPreview } from "../../domains/session/tree/preview.js";
 import { openSession, sessionPaths } from "../../engine/session.js";
 import {
 	type Component,
@@ -21,7 +22,7 @@ const PREVIEW_WIDTH = 60;
 
 /**
  * /fork picker. Lists the current session's assistant turns, most-recent first,
- * with the first line of the assistant text as the row label. Selecting a row
+ * with a structured assistant preview as the row label. Selecting a row
  * calls onFork(parentTurnId); the caller wires that through
  * SessionContract.fork(parentTurnId).
  *
@@ -38,33 +39,6 @@ function shortTurnId(id: string): string {
 	return id.length > 8 ? id.slice(0, 8) : id;
 }
 
-/**
- * Coerce a structured message payload into a preview string. Handles raw
- * strings, text properties, and pi-ai content blocks.
- */
-function payloadPreview(payload: unknown): string {
-	if (typeof payload === "string") return payload;
-	if (!payload || typeof payload !== "object") return "";
-	const p = payload as Record<string, unknown>;
-	if (typeof p.text === "string") return p.text;
-	if (Array.isArray(p.content)) {
-		for (const block of p.content) {
-			if (block && typeof block === "object") {
-				const b = block as Record<string, unknown>;
-				if (b.type === "text" && typeof b.text === "string") return b.text;
-			}
-		}
-	}
-	return "";
-}
-
-function firstLineClamped(text: string, max: number): string {
-	const firstLine = text.split("\n", 1)[0] ?? "";
-	const trimmed = firstLine.trim();
-	if (trimmed.length === 0) return "(no text)";
-	return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
-}
-
 export interface MessagePickerRow {
 	turnId: string;
 	shortId: string;
@@ -87,7 +61,7 @@ function buildMessagePickerRows(turns: ReadonlyArray<MessageEntry>): MessagePick
 			turnId: turn.turnId,
 			shortId: shortTurnId(turn.turnId),
 			at: turn.timestamp,
-			preview: firstLineClamped(payloadPreview(turn.payload), PREVIEW_WIDTH),
+			preview: buildTurnPreview({ kind: "assistant", payload: turn.payload }, PREVIEW_WIDTH),
 		});
 	}
 	return rows;