@iowarp/clio-coder 0.3.9 → 0.4.1

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

@@ -18,7 +18,13 @@ import {
 } from "../../engine/tui.js";
 import type { AskUserAnswer, AskUserQuestion, AskUserResult } from "../../tools/ask-user.js";
 import { ASK_USER_OTHER_LABEL, cancelledAskUserResult } from "../../tools/ask-user.js";
-import { buildHint, DEFAULT_SELECT_THEME, type HintEntry, showClioOverlayFrame } from "../overlay-frame.js";
+import {
+	buildHint,
+	DEFAULT_SELECT_THEME,
+	type HintEntry,
+	type OverlayEscVerb,
+	showClioOverlayFrame,
+} from "../overlay-frame.js";
 import { type ClioToken, clioTheme, dotSep, GLYPH, screenTitle } from "../theme/index.js";
 import { nextContentScrollOffset, type ViewScrollAction } from "../view/view-overlay.js";
 
@@ -91,6 +97,8 @@ const MIN_VISIBLE_OPTIONS = 3;
 /** Interview rows spent on chrome before an option row: strip, header, blanks, status, one question row. */
 const INTERVIEW_CHROME_ROWS = 7;
 const MAX_VISIBLE_OPTIONS = 12;
+/** Below this the second column is too narrow to wrap a sentence into. */
+const MIN_DESCRIPTION_COLUMN = 28;
 const ELLIPSIS = "…";
 
 /**
@@ -102,7 +110,7 @@ const ELLIPSIS = "…";
  * should not take the screen. A round that follows an answered one has captured
  * answers to keep on screen, which is the full surface's whole job.
  */
-export function askUserSurface(questions: ReadonlyArray<AskUserQuestion>, priorRounds = 0): AskUserSurface {
+function askUserSurface(questions: ReadonlyArray<AskUserQuestion>, priorRounds = 0): AskUserSurface {
 	if (priorRounds > 0 || questions.length !== 1) return "interview";
 	const question = questions[0];
 	if (!question) return "interview";
@@ -237,6 +245,16 @@ function fitLine(text: string, width: number): string {
 	return truncateToWidth(text, safeWidth, ELLIPSIS, true);
 }
 
+/** Wrap a prose value inside the columns left by its one-time row label. */
+function wrapLabeledValue(prefix: string, value: string, width: number): string[] {
+	const safeWidth = Math.max(1, width);
+	const prefixWidth = visibleWidth(prefix);
+	const valueWidth = Math.max(1, safeWidth - prefixWidth);
+	return wrapTextWithAnsi(value, valueWidth).map((line, index) =>
+		fitLine(`${index === 0 ? prefix : " ".repeat(prefixWidth)}${line}`, safeWidth),
+	);
+}
+
 function compactTitle(question: AskUserQuestion): string {
 	return (question.header ?? question.question).replace(/\s+/g, " ").trim();
 }
@@ -390,7 +408,8 @@ class AskUserOverlayView implements Component {
 
 		this.contentOverflows = false;
 		const controlLines = this.renderControlLines(safeWidth);
-		const statusLines = this.status.length > 0 ? ["", fitLine(clioTheme().fg("dim", this.status), safeWidth)] : [];
+		const statusLines =
+			this.status.length > 0 ? ["", ...wrapTextWithAnsi(clioTheme().fg("dim", this.status), safeWidth)] : [];
 		const headerLine = this.renderQuestionHeader(question, safeWidth);
 		const headerLines = headerLine.length > 0 ? [headerLine] : [];
 		const bottom = [...statusLines, "", ...controlLines];
@@ -418,7 +437,7 @@ class AskUserOverlayView implements Component {
 	private renderInterview(question: AskUserQuestion, width: number, maxRows: number): string[] {
 		const theme = clioTheme();
 		const controlLines = this.renderControlLines(width);
-		const statusLines = this.status.length > 0 ? ["", fitLine(theme.fg("dim", this.status), width)] : [];
+		const statusLines = this.status.length > 0 ? ["", ...wrapTextWithAnsi(theme.fg("dim", this.status), width)] : [];
 		const headerLine = this.renderQuestionHeader(question, width);
 		const headerLines = headerLine.length > 0 ? [headerLine] : [];
 		const stripLines = [this.renderQuestionStrip(width), ""];
@@ -511,16 +530,24 @@ class AskUserOverlayView implements Component {
 			this.presentation.requiredActions.find((action) => action.id === "record-answer")?.label.toLowerCase() ??
 			"record answer";
 		if (state.mode === "text") {
+			// Esc means two different things depending on what is behind the field.
+			// A question with options has a list to fall back to, so the key goes
+			// 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";
 			return this.questions.length > 1
-				? this.withScrollHint([
-						{ key: "Enter", verb: recordAnswer },
-						{ key: "Alt+Left/Right", verb: "question" },
-					])
-				: this.withScrollHint([{ key: "Enter", verb: recordAnswer }]);
+				? this.withScrollHint(
+						[
+							{ key: "Enter", verb: recordAnswer },
+							{ key: "Alt+Left/Right", verb: "question" },
+						],
+						escapeVerb,
+					)
+				: this.withScrollHint([{ key: "Enter", verb: recordAnswer }], escapeVerb);
 		}
 		// The classified action label distinguishes recording an answer from
-		// granting authority. Esc keeps the product's one word for the way out,
-		// since it closes the prompt and the interview together.
+		// granting authority. Esc on the option list is the way out of the whole
+		// interview, which is the one place the product spells `close`.
 		// `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.
 		const addText: HintEntry = { key: "t", verb: "add text", short: "text" };
@@ -558,9 +585,9 @@ class AskUserOverlayView implements Component {
 	 * scroll. A footer that always advertised PgUp would be advertising a key that
 	 * does nothing on most rounds.
 	 */
-	private withScrollHint(entries: ReadonlyArray<HintEntry>): string {
-		if (this.surface !== "interview" || !this.contentOverflows) return buildHint(entries);
-		return buildHint([...entries, { key: "PgUp/PgDn", verb: "scroll" }]);
+	private withScrollHint(entries: ReadonlyArray<HintEntry>, esc: OverlayEscVerb = "close"): string {
+		if (this.surface !== "interview" || !this.contentOverflows) return buildHint(entries, esc);
+		return buildHint([...entries, { key: "PgUp/PgDn", verb: "scroll" }], esc);
 	}
 
 	private setSurface(next: AskUserSurface): void {
@@ -590,11 +617,14 @@ class AskUserOverlayView implements Component {
 		const lines = [
 			screenTitle(theme, "Interview"),
 			"",
-			theme.fg(
-				"muted",
-				this.history.length > 0
-					? "Answer sent. Waiting for Clio to prepare the next interview question."
-					: "Waiting for Clio to prepare the interview.",
+			...wrapTextWithAnsi(
+				theme.fg(
+					"muted",
+					this.history.length > 0
+						? "Answer sent. Waiting for Clio to prepare the next interview question."
+						: "Waiting for Clio to prepare the interview.",
+				),
+				width,
 			),
 		];
 		if (this.history.length > 0) {
@@ -602,7 +632,7 @@ class AskUserOverlayView implements Component {
 			for (let index = 0; index < this.history.length; index += 1) {
 				const answer = this.history[index];
 				if (!answer) continue;
-				lines.push(fitLine(`${theme.fg("dim", `${index + 1}.`)} ${theme.fg("muted", answer.answer)}`, width));
+				lines.push(...wrapLabeledValue(`${theme.fg("dim", `${index + 1}.`)} `, theme.fg("muted", answer.answer), width));
 			}
 		}
 		return lines.map((line) => fitLine(line, width)).slice(0, maxRows);
@@ -751,7 +781,7 @@ class AskUserOverlayView implements Component {
 		for (let index = 0; index < this.history.length; index += 1) {
 			const answer = this.history[index];
 			if (!answer) continue;
-			rows.push(fitLine(`${theme.fg("dim", `${index + 1}.`)} ${theme.fg("muted", answer.answer)}`, width));
+			rows.push(...wrapLabeledValue(`${theme.fg("dim", `${index + 1}.`)} `, theme.fg("muted", answer.answer), width));
 		}
 		// A round of one question needs no per-question roll: the strip already
 		// names the round and the question is on screen above this.
@@ -759,7 +789,7 @@ class AskUserOverlayView implements Component {
 			for (let index = 0; index < this.questions.length; index += 1) {
 				const answer = this.states[index]?.answer.trim();
 				const value = answer && answer.length > 0 ? theme.fg("muted", answer) : theme.fg("dim", "pending");
-				rows.push(fitLine(`${theme.fg("dim", `Q${index + 1}`)} ${value}`, width));
+				rows.push(...wrapLabeledValue(`${theme.fg("dim", `Q${index + 1}`)} `, value, width));
 			}
 		}
 		if (rows.length === 0) return [];
@@ -784,17 +814,29 @@ class AskUserOverlayView implements Component {
 			0,
 			items.findIndex((item) => item.value === selectedItem.value),
 		);
-		const visibleCount = Math.min(this.maxVisibleOptions(), Math.max(1, items.length));
+		const primaryColumnWidth = this.primaryColumnWidth(items, width);
+		const acceptKey = question.multi_select === true ? "Space" : "Enter";
+		// The focused option's description wraps in full, so the rows it needs come
+		// out of the list rather than out of the sentence. Options the operator
+		// cannot currently read are what a windowed list is for, and one arrow key
+		// brings any of them back; a cut explanation has no such recovery.
+		const focusedRows = this.renderOptionRow(
+			items[selectedIndex] as SelectItem,
+			true,
+			width,
+			primaryColumnWidth,
+			acceptKey,
+		).length;
+		const budget = Math.max(1, this.maxVisibleOptions() - (focusedRows - 1));
+		const visibleCount = Math.min(budget, Math.max(1, items.length));
 		const start = Math.max(0, Math.min(selectedIndex - Math.floor(visibleCount / 2), items.length - visibleCount));
 		const end = Math.min(items.length, start + visibleCount);
-		const primaryColumnWidth = this.primaryColumnWidth(items, width);
 		const lines: string[] = [];
 
-		const acceptKey = question.multi_select === true ? "Space" : "Enter";
 		for (let index = start; index < end; index += 1) {
 			const item = items[index];
 			if (!item) continue;
-			lines.push(this.renderOptionRow(item, index === selectedIndex, width, primaryColumnWidth, acceptKey));
+			lines.push(...this.renderOptionRow(item, index === selectedIndex, width, primaryColumnWidth, acceptKey));
 		}
 
 		if (start > 0 || end < items.length) {
@@ -809,13 +851,22 @@ class AskUserOverlayView implements Component {
 		return Math.max(1, Math.min(bounded, Math.max(1, width - 4)));
 	}
 
+	/**
+	 * One option, as the rows it needs.
+	 *
+	 * The focused option's description wraps under its own column and is never
+	 * cut: a description is what the operator is choosing between, and half of
+	 * one reads as the whole thing. An unfocused row stays a one-line table cell
+	 * whose ellipsis says there is more, which the operator reads by moving to
+	 * it.
+	 */
 	private renderOptionRow(
 		item: SelectItem,
 		selected: boolean,
 		width: number,
 		primaryColumnWidth: number,
 		acceptKey: string,
-	): string {
+	): string[] {
 		const theme = clioTheme();
 		const prefix = selected ? theme.fg("accent", `${GLYPH.cursor} `) : "  ";
 		// The key that answers rides on the focused row. An operator whose eyes are
@@ -825,22 +876,40 @@ class AskUserOverlayView implements Component {
 		const available = Math.max(1, width - 2 - visibleWidth(affordance));
 		const description = item.description?.replace(/[\r\n]+/g, " ").trim();
 
-		let body: string;
-		if (description && width > 40) {
-			const labelWidth = Math.max(1, Math.min(primaryColumnWidth - 2, available - 4));
-			const label = truncateToWidth(item.label, labelWidth, ELLIPSIS, false);
-			const spacing = " ".repeat(Math.max(1, primaryColumnWidth - visibleWidth(label)));
-			const descriptionWidth = Math.max(1, available - visibleWidth(label) - visibleWidth(spacing));
-			const desc = truncateToWidth(description, descriptionWidth, ELLIPSIS, false);
-			body = selected
-				? theme.style("accent", `${label}${spacing}${desc}`, { bold: true })
-				: `${label}${theme.fg("muted", `${spacing}${desc}`)}`;
-		} else {
+		if (!description || width <= 40) {
 			const label = truncateToWidth(item.label, available, ELLIPSIS, false);
-			body = selected ? theme.style("accent", label, { bold: true }) : label;
+			const body = selected ? theme.style("accent", label, { bold: true }) : label;
+			return [fitLine(`${prefix}${body}${affordance}`, width)];
 		}
 
-		return fitLine(`${prefix}${body}${affordance}`, width);
+		const labelWidth = Math.max(1, Math.min(primaryColumnWidth - 2, available - 4));
+		const label = truncateToWidth(item.label, labelWidth, ELLIPSIS, false);
+		const spacing = " ".repeat(Math.max(1, primaryColumnWidth - visibleWidth(label)));
+		const descriptionWidth = Math.max(1, available - visibleWidth(label) - visibleWidth(spacing));
+		if (!selected) {
+			const desc = truncateToWidth(description, descriptionWidth, ELLIPSIS, false);
+			return [fitLine(`${prefix}${label}${theme.fg("muted", `${spacing}${desc}`)}`, width)];
+		}
+		// A gutter this narrow wraps a sentence into slivers and breaks words, so
+		// below the floor the description drops to its own full-width lines under
+		// the label instead of squeezing into the second column.
+		if (descriptionWidth < MIN_DESCRIPTION_COLUMN) {
+			const indent = "    ";
+			const body = theme.style("accent", label, { bold: true });
+			return [
+				fitLine(`${prefix}${body}${affordance}`, width),
+				...wrapTextWithAnsi(description, Math.max(1, width - indent.length)).map((line) =>
+					fitLine(`${indent}${theme.style("accent", line, { bold: true })}`, width),
+				),
+			];
+		}
+		const wrapped = wrapTextWithAnsi(description, descriptionWidth);
+		const head = wrapped[0] ?? "";
+		const indent = " ".repeat(visibleWidth(prefix) + visibleWidth(label) + visibleWidth(spacing));
+		return [
+			fitLine(`${prefix}${theme.style("accent", `${label}${spacing}${head}`, { bold: true })}${affordance}`, width),
+			...wrapped.slice(1).map((line) => fitLine(`${indent}${theme.style("accent", line, { bold: true })}`, width)),
+		];
 	}
 
 	private ensureControl(): void {
@@ -889,7 +958,7 @@ class AskUserOverlayView implements Component {
 			state.answer = questionHasOptions(question) ? answerText(question, state.selected, state.customAnswer) : answer;
 			this.finishIfCompleteOrAdvance();
 		};
-		activeInput.onEscape = () => this.cancel();
+		activeInput.onEscape = () => this.escapeFromTextInput(question, state);
 		this.input = activeInput;
 		this.list = null;
 	}
@@ -960,6 +1029,53 @@ class AskUserOverlayView implements Component {
 		return 0;
 	}
 
+	/**
+	 * Esc in the text field.
+	 *
+	 * The field used to resolve the whole round as cancelled, which made a typed
+	 * draft unrecoverable: a single-question round had no other question to answer
+	 * first, so the only way off `t` was to abandon the interview (issue #260). A
+	 * question with options has a surface behind the field, so Esc goes back to it
+	 * and drops the draft. A question with no options has nothing behind it, so Esc
+	 * keeps its old meaning and leaves the interview; the footer says which.
+	 *
+	 * The draft is dropped rather than parked because Esc is the discard gesture.
+	 * It never reached `answer`, `options`, or `value` in the first place, since
+	 * only a submit writes those, so #228's clearing rule holds either way.
+	 */
+	private escapeFromTextInput(question: AskUserQuestion, state: QuestionState): void {
+		if (!questionHasOptions(question)) {
+			this.cancel();
+			return;
+		}
+		state.inputValue = "";
+		state.mode = "select";
+		this.status = "";
+		this.rebuildSelectList(question, state);
+		this.deps.requestRender();
+	}
+
+	/**
+	 * Leave a question the operator is walking away from on its option list.
+	 *
+	 * The mode used to belong to the question for the rest of the round, so a
+	 * question opened with `t` came back as a prefilled field however the operator
+	 * returned to it, and the option list was gone for good. Navigating away is not
+	 * the discard gesture, so the draft stays in `inputValue` and `t` finds it
+	 * again; what does not survive is the field being the thing that greets them.
+	 *
+	 * A question whose value was actually submitted keeps its field, because
+	 * coming back to a recorded figure is how it gets revised (issue #228).
+	 */
+	private parkTextMode(): void {
+		const question = this.currentQuestion();
+		const state = this.currentState();
+		if (!question || !state) return;
+		if (state.mode !== "text" || !questionHasOptions(question)) return;
+		if (state.rawValue.length > 0) return;
+		state.mode = "select";
+	}
+
 	private openTextInput(nextStatus: string): void {
 		const state = this.currentState();
 		const question = this.currentQuestion();
@@ -1077,6 +1193,7 @@ class AskUserOverlayView implements Component {
 	private goToRelativeQuestion(delta: -1 | 1): void {
 		if (this.questions.length <= 1) return;
 		this.syncActiveControl();
+		this.parkTextMode();
 		this.index = (this.index + delta + this.questions.length) % this.questions.length;
 		this.status = "";
 		this.resetContentScroll();
@@ -1128,6 +1245,9 @@ export function openAskUserOverlay(tui: TUI, deps: OpenAskUserOverlayDeps): AskU
 			// the terminal has left after the margins.
 			...(geometry.maxInnerRows > 0 ? { maxHeight: geometry.maxInnerRows + ASK_USER_FRAME_ROWS } : {}),
 			margin: geometry.margin,
+			// 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),
 			tone: () => (view.isDecisionPending() ? view.decisionTone() : undefined),
 			footerHint: () => view.footerHint(),

package/src/interactive/overlays/auth-dialog.ts

@@ -211,6 +211,7 @@ export function openAuthDialog(tui: TUI, title: string, onCancel: () => void): A
 	const handle = showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: AUTH_DIALOG_WIDTH,
+		markerId: "auth",
 		title: "Authentication",
 		footerHint: getHint,
 	});

package/src/interactive/overlays/context-reset.ts

@@ -1,4 +1,5 @@
 import {
+	type Component,
 	type OverlayHandle,
 	type SelectItem,
 	SelectList,
@@ -6,6 +7,7 @@ import {
 	type TUI,
 	truncateToWidth,
 	visibleWidth,
+	wrapTextWithAnsi,
 } from "../../engine/tui.js";
 import { buildHint, DEFAULT_SELECT_THEME, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
 import type { ContextClearCommandOptions } from "../slash-commands.js";
@@ -29,7 +31,7 @@ export function contextResetOptions(choice: ContextResetMutationChoice): Context
 }
 
 /** Three intentional outcomes, ordered with the least destructive action first. */
-export function buildContextResetItems(): SelectItem[] {
+function buildContextResetItems(): SelectItem[] {
 	return [
 		{
 			value: "preserve-clio-md",
@@ -67,6 +69,10 @@ function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
 			truncatePrimary: ({ text, maxWidth, item, isSelected }) => {
 				const label = singleLine(text);
 				const description = descriptions.get(item.value) ?? "";
+				// The focused description is rendered in full below the list. Keeping
+				// only its label here prevents the same explanation appearing once cut
+				// and once wrapped on the same decision surface.
+				if (isSelected) return truncateToWidth(label, maxWidth, ELLIPSIS, true);
 				if (description.length === 0 || maxWidth < 44) {
 					return truncateToWidth(label, maxWidth, ELLIPSIS, true);
 				}
@@ -76,13 +82,31 @@ function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
 				const spacing = " ".repeat(Math.max(1, labelWidth + 2 - visibleWidth(fittedLabel)));
 				const descriptionWidth = Math.max(1, maxWidth - visibleWidth(fittedLabel) - visibleWidth(spacing));
 				const fittedDescription = truncateToWidth(description, descriptionWidth, ELLIPSIS, true);
-				const body = `${fittedLabel}${spacing}${fittedDescription}`;
-				return isSelected ? body : `${fittedLabel}${clioTheme().fg("muted", `${spacing}${fittedDescription}`)}`;
+				return `${fittedLabel}${clioTheme().fg("muted", `${spacing}${fittedDescription}`)}`;
 			},
 		},
 	};
 }
 
+function describedSelect(list: SelectList, choices: ReadonlyArray<SelectItem>): Component {
+	return {
+		render(width: number): string[] {
+			const rows = list.render(width);
+			const selected = list.getSelectedItem();
+			const description = choices.find((choice) => choice.value === selected?.value)?.description;
+			if (!description) return rows;
+			const indent = "  ";
+			const wrapped = wrapTextWithAnsi(
+				clioTheme().fg("muted", singleLine(description)),
+				Math.max(1, width - visibleWidth(indent)),
+			).map((line) => `${indent}${line}`);
+			return [...rows, ...wrapped];
+		},
+		handleInput: (data: string) => list.handleInput(data),
+		invalidate: () => list.invalidate(),
+	};
+}
+
 /** Open the `/context reset` choice dialog. Cancel paths never reach onReset. */
 export function openContextResetOverlay(tui: TUI, deps: OpenContextResetOverlayDeps): OverlayHandle {
 	const choices = buildContextResetItems();
@@ -99,9 +123,10 @@ export function openContextResetOverlay(tui: TUI, deps: OpenContextResetOverlayD
 		deps.onCancel();
 	};
 
-	return showClioOverlayFrame(tui, new FocusBox(list), {
+	return showClioOverlayFrame(tui, new FocusBox(describedSelect(list, choices)), {
 		anchor: "center",
 		width: CONTEXT_RESET_OVERLAY_WIDTH,
+		markerId: "context-reset",
 		title: "Reset Project Context",
 		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
 	});

package/src/interactive/overlays/cwd-fallback.ts

@@ -11,6 +11,7 @@
  */
 
 import {
+	type Component,
 	type OverlayHandle,
 	type SelectItem,
 	SelectList,
@@ -18,6 +19,7 @@ import {
 	type TUI,
 	truncateToWidth,
 	visibleWidth,
+	wrapTextWithAnsi,
 } from "../../engine/tui.js";
 import { buildHint, DEFAULT_SELECT_THEME, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
 import { clioTheme } from "../theme/index.js";
@@ -69,6 +71,10 @@ function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
 			truncatePrimary: ({ text, maxWidth, item, isSelected }) => {
 				const label = singleLine(text);
 				const description = descriptions.get(item.value) ?? "";
+				// The selected explanation is the recovery decision the operator is
+				// reading, so it renders in full beneath the list instead of appearing
+				// here as an ellipsized fragment.
+				if (isSelected) return truncateToWidth(label, maxWidth, ELLIPSIS, true);
 				if (description.length === 0 || maxWidth < 32) {
 					return truncateToWidth(label, maxWidth, ELLIPSIS, true);
 				}
@@ -80,18 +86,36 @@ function buildSelectPresentation(items: ReadonlyArray<SelectItem>): {
 				const spacing = " ".repeat(Math.max(1, labelWidth + 2 - visibleWidth(fittedLabel)));
 				const descWidth = Math.max(1, maxWidth - visibleWidth(fittedLabel) - visibleWidth(spacing));
 				const fittedDescription = truncateToWidth(description, descWidth, ELLIPSIS, true);
-				const body = `${fittedLabel}${spacing}${fittedDescription}`;
-				return isSelected ? body : `${fittedLabel}${theme.fg("muted", `${spacing}${fittedDescription}`)}`;
+				return `${fittedLabel}${theme.fg("muted", `${spacing}${fittedDescription}`)}`;
 			},
 		},
 	};
 }
 
+function describedSelect(list: SelectList, choices: ReadonlyArray<SelectItem>): Component {
+	return {
+		render(width: number): string[] {
+			const rows = list.render(width);
+			const selected = list.getSelectedItem();
+			const description = choices.find((choice) => choice.value === selected?.value)?.description;
+			if (!description) return rows;
+			const indent = "  ";
+			const wrapped = wrapTextWithAnsi(
+				clioTheme().fg("muted", singleLine(description)),
+				Math.max(1, width - visibleWidth(indent)),
+			).map((line) => `${indent}${line}`);
+			return [...rows, ...wrapped];
+		},
+		handleInput: (data: string) => list.handleInput(data),
+		invalidate: () => list.invalidate(),
+	};
+}
+
 /**
  * Pure builder. Exposed so tests can assert row shape without booting the TUI.
  * Two rows: Continue (uses process cwd) and Cancel (returns to picker).
  */
-export function buildCwdFallbackItems(args: {
+function buildCwdFallbackItems(args: {
 	currentCwd: string;
 	sessionCwd: string;
 	reason: CwdFallbackReason;
@@ -131,10 +155,11 @@ export function openCwdFallbackOverlay(tui: TUI, deps: OpenCwdFallbackOverlayDep
 		deps.onCancel();
 		deps.onClose();
 	};
-	const box = new FocusBox(list);
+	const box = new FocusBox(describedSelect(list, items));
 	return showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: CWD_FALLBACK_OVERLAY_WIDTH,
+		markerId: "cwd-fallback",
 		title: "Session Working Directory",
 		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
 	});

package/src/interactive/overlays/decisions.ts

@@ -94,27 +94,26 @@ function decisionLines(decision: DecisionRecord, selected: boolean, expanded: bo
 	const label = decision.status === "superseded" ? theme.fg("dim", labelText) : theme.fg("muted", labelText);
 	const value = decision.status === "superseded" ? theme.fg("dim", decision.value) : decision.value;
 	const lines = [fitLine(`${cursor} ${status} ${label}${theme.fg("dim", ":")} ${value}`, width)];
+	// The indent belongs to the container, so this text wraps inside what is left
+	// of the row. Wrapping to the full width and then indenting cost every line
+	// its last six columns to a cut that landed mid-sentence.
+	const indent = "      ";
+	const indented = Math.max(1, width - indent.length);
+	const wrapIndented = (text: string): string[] =>
+		wrapTextWithAnsi(text, indented).map((line) => fitLine(`${indent}${line}`, width));
 	if (decision.status === "superseded" && decision.correction) {
-		lines.push(fitLine(`      ${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`, width));
+		lines.push(...wrapIndented(`${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`));
 	}
 	if (selected && expanded) {
 		if (decision.source_question) {
-			lines.push(
-				...wrapTextWithAnsi(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`, width).map(
-					(line) => fitLine(`      ${line}`, width),
-				),
-			);
+			lines.push(...wrapIndented(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`));
 		}
-		lines.push(
-			...wrapTextWithAnsi(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`, width).map((line) =>
-				fitLine(`      ${line}`, width),
-			),
-		);
+		lines.push(...wrapIndented(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`));
 	}
 	return lines;
 }
 
-export function formatDecisionsOverlayBodyLines(
+function formatDecisionsOverlayBodyLines(
 	interviews: ReadonlyArray<DecisionLedgerEntry>,
 	selectedIndex = 0,
 	expandedKey: string | null = null,
@@ -184,7 +183,9 @@ class DecisionsOverlayBody implements Component {
 					),
 			);
 		}
-		if (this.status) body.push("", fitLine(clioTheme().fg("warning", this.status), width));
+		if (this.status) {
+			body.push("", ...wrapTextWithAnsi(clioTheme().fg("warning", this.status), Math.max(1, width)));
+		}
 		return body;
 	}
 
@@ -296,6 +297,7 @@ export function openDecisionsOverlay(
 	return showClioOverlayFrame(tui, body, {
 		anchor: "center",
 		width: DECISIONS_OVERLAY_WIDTH,
+		markerId: "decisions",
 		title: () => "Decisions",
 		footerHint: () => body.footerHint(),
 	});

package/src/interactive/overlays/extensions.ts

@@ -45,6 +45,7 @@ export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClos
 	});
 
 	return openListOverlay(tui, {
+		markerId: "extensions",
 		title: "Extensions Reference",
 		items,
 		filterable: true,

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

@@ -51,14 +51,14 @@ export interface OpenFleetRunApprovalOverlayOptions {
 }
 
 /** The declared boundary as one phrase: an empty allowlist is a claim, not an absence. */
-export function formatWriteBoundary(writes: ReadonlyArray<string> | undefined): string {
+function formatWriteBoundary(writes: ReadonlyArray<string> | undefined): string {
 	if (writes === undefined) return "writes unenforced";
 	if (writes.length === 0) return "writes nothing";
 	return `writes ${writes.join(", ")}`;
 }
 
 /** One step as its facts: kind, who runs it, where, its scope, and its boundary. */
-export function formatFleetRunPreviewStep(step: FleetRunPreviewStep): string {
+function formatFleetRunPreviewStep(step: FleetRunPreviewStep): string {
 	const loop = step.loop === undefined ? "" : ` (${step.loop.loopId} ${step.loop.role} ${step.loop.attempt})`;
 	if (step.kind === "code") {
 		const gate = step.gate === undefined ? "" : ` · gate path ${step.gate.path}`;
@@ -95,7 +95,7 @@ function formatBudgetLine(preview: FleetRunPreview): string {
  * Render the body. Waves in order, each step with its facts, then the argv a
  * code step will actually run, and last the budget the run is admitted under.
  */
-export function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: number, scroll: number): string[] {
+function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: number, scroll: number): string[] {
 	const theme = clioTheme();
 	const contentWidth = Math.max(1, Math.floor(width));
 	const rows: string[] = [];
@@ -191,6 +191,7 @@ export function openFleetRunApprovalOverlay(tui: TUI, options: OpenFleetRunAppro
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: fleetRunApprovalOverlayWidth(options.columns),
+		markerId: "fleet-run-approval",
 		title: FLEET_RUN_APPROVAL_OVERLAY_TITLE,
 		footerHint: buildResponsiveHint(
 			[...(acceptable ? [{ key: "Enter", verb: "dispatch" }] : []), { key: "↑↓", verb: "scroll" }],

package/src/interactive/overlays/handoff-review.ts

@@ -27,7 +27,7 @@ const HANDOFF_REVIEW_MAX_WIDTH = 100;
 /** Rows of document shown at once. Anything longer scrolls. */
 export const HANDOFF_REVIEW_VISIBLE_ROWS = 20;
 
-export function handoffReviewOverlayWidth(columns: number): number {
+function handoffReviewOverlayWidth(columns: number): number {
 	return Math.max(HANDOFF_REVIEW_MIN_WIDTH, Math.min(HANDOFF_REVIEW_MAX_WIDTH, columns - 4));
 }
 
@@ -57,7 +57,7 @@ export interface HandoffReviewOverlaySession extends OverlayHandle {
  * Render the body. Pure so the layout is testable without a TUI: the goal, a
  * rule, then the scrolled document window.
  */
-export function formatHandoffReviewBody(goal: string, document: string, width: number, scroll: number): string[] {
+function formatHandoffReviewBody(goal: string, document: string, width: number, scroll: number): string[] {
 	const theme = clioTheme();
 	const contentWidth = Math.max(1, Math.floor(width));
 	const lines: string[] = [];
@@ -163,6 +163,7 @@ export function openHandoffReviewOverlay(
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: handoffReviewOverlayWidth(options.columns),
+		markerId: "handoff-review",
 		title: HANDOFF_REVIEW_OVERLAY_TITLE,
 		footerHint: buildResponsiveHint(
 			[

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

@@ -94,6 +94,7 @@ export function openHelpOverlay(
 			detail: () => [
 				"# Fleet runs & steering",
 				"**Fleet Runs board**: open it with the configured Dispatch Board key (Alt+W by default). Use Up/Down or `j`/`k` to select a live or recent run.",
+				"**Enter**: on a live run in a `--with-panes` session, Enter opens (or retargets) the watch pane beside Clio, rendering that run's stream; the arrow keys then move it between runs. On a finished run, or without panes, Enter toggles the inline worker-progress detail instead.",
 				"**Steer**: press `s` on a live native run to close the board and prefill `@<runId> `. Add guidance and submit it normally. The first notice means queued; a received notice confirms worker delivery.",
 				"**Cancel**: press `x` on a running, stale, queued, or retry-waiting run. The row changes to cancelling while the worker or retry is being stopped.",
 				"**Capabilities**: ACP delegation runs cannot accept live steering. The board footer only advertises actions supported by the selected row.",
@@ -140,6 +141,7 @@ export function openHelpOverlay(
 	const items = [...commands, ...keys, ...topics];
 
 	return openListOverlay(tui, {
+		markerId: "help",
 		title: "Help Center",
 		items,
 		filterable: true,