@iowarp/clio-coder 0.3.8 → 0.4.0

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 = "…";
 
 /**
@@ -129,6 +137,14 @@ interface QuestionState {
 	customAnswer: string;
 	inputValue: string;
 	answer: string;
+	/**
+	 * The operator's typed text exactly as submitted, empty when they typed
+	 * nothing. `answer` is the one-line rendering of the whole decision and gets
+	 * trimmed and joined; this is the record of what they actually typed, and
+	 * losing it is what made an interview re-ask for the same figures three times
+	 * (issue #228).
+	 */
+	rawValue: string;
 	focusedValue?: string;
 }
 
@@ -154,6 +170,7 @@ function createQuestionState(question: AskUserQuestion): QuestionState {
 		customAnswer: "",
 		inputValue: "",
 		answer: "",
+		rawValue: "",
 	};
 }
 
@@ -205,12 +222,18 @@ function optionIndexFromValue(value: string): number | null {
 	return Number.isInteger(index) && index >= 0 ? index : null;
 }
 
-function answerText(question: AskUserQuestion, selected: ReadonlySet<number>, customAnswer: string): string {
-	const parts: string[] = [];
+/** The labels the operator chose, in list order. */
+function selectedOptionLabels(question: AskUserQuestion, selected: ReadonlySet<number>): string[] {
+	const labels: string[] = [];
 	for (const index of [...selected].sort((a, b) => a - b)) {
 		const label = question.options?.[index]?.label;
-		if (label) parts.push(label);
+		if (label) labels.push(label);
 	}
+	return labels;
+}
+
+function answerText(question: AskUserQuestion, selected: ReadonlySet<number>, customAnswer: string): string {
+	const parts = selectedOptionLabels(question, selected);
 	const custom = customAnswer.trim();
 	if (custom.length > 0) parts.push(custom);
 	return parts.join("; ");
@@ -348,6 +371,10 @@ class AskUserOverlayView implements Component {
 			this.commitMultiSelectOrOpenOther(state);
 			return;
 		}
+		if (this.isAddTextKey(data)) {
+			this.chooseFocusedAndOpenText(question, state);
+			return;
+		}
 		this.list?.handleInput(data);
 	}
 
@@ -492,34 +519,40 @@ 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" };
 		if (question.multi_select === true) {
 			return this.questions.length > 1
 				? this.withScrollHint([
 						{ key: "Left/Right", verb: "question" },
 						{ key: "Space", verb: "toggle" },
+						addText,
 						{ key: "Enter", verb: recordAnswer },
 					])
-				: this.withScrollHint([
-						{ key: "Space", verb: "toggle" },
-						{ key: "Enter", verb: recordAnswer },
-					]);
+				: this.withScrollHint([{ key: "Space", verb: "toggle" }, addText, { key: "Enter", verb: recordAnswer }]);
 		}
 		return this.questions.length > 1
-			? this.withScrollHint([
-					{ key: "Left/Right", verb: "question" },
-					{ key: "Enter", verb: recordAnswer },
-				])
-			: this.withScrollHint([{ key: "Enter", verb: recordAnswer }]);
+			? this.withScrollHint([{ key: "Left/Right", verb: "question" }, addText, { key: "Enter", verb: recordAnswer }])
+			: this.withScrollHint([addText, { key: "Enter", verb: recordAnswer }]);
 	}
 
 	private renderDecisionContext(width: number): string[] {
@@ -541,9 +574,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 {
@@ -644,6 +677,34 @@ class AskUserOverlayView implements Component {
 		return this.questions.length > 1 && (matchesKey(data, "alt+right") || matchesKey(data, "ctrl+right"));
 	}
 
+	/**
+	 * The key that adds typed text to the option under the cursor.
+	 *
+	 * Choosing an option used to be the whole answer, so a model that offered
+	 * "Exact number - I'll type it" gave the operator a label and nowhere to put
+	 * the number; the interview then spent two of its four rounds asking for the
+	 * figures again (issue #228). The list itself only reads the arrows, Enter,
+	 * and Esc, so a letter is free here.
+	 */
+	private isAddTextKey(data: string): boolean {
+		return matchesKey(data, "t");
+	}
+
+	/**
+	 * Take the focused option and open the text field for it, without committing.
+	 * Submitting the text records the label and the text together.
+	 */
+	private chooseFocusedAndOpenText(question: AskUserQuestion, state: QuestionState): void {
+		const current = this.list?.getSelectedItem();
+		const optionIndex = current && current.value !== "other" ? optionIndexFromValue(current.value) : null;
+		if (optionIndex !== null) {
+			if (question.multi_select === true) state.selected.add(optionIndex);
+			else state.selected = new Set<number>([optionIndex]);
+			state.focusedValue = `option:${optionIndex}`;
+		}
+		this.openTextInput(state.selected.size > 0 ? "Add your answer to the chosen option" : "Other answer");
+	}
+
 	/**
 	 * The row above the question, or nothing.
 	 *
@@ -739,17 +800,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) {
@@ -764,13 +837,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
@@ -780,22 +862,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 {
@@ -829,16 +929,22 @@ class AskUserOverlayView implements Component {
 				return;
 			}
 			state.inputValue = answer;
+			// Verbatim, before any joining or trimming the display line does. The
+			// typed text is the answer; the one-line `answer` is a rendering of it.
+			state.rawValue = value;
 			if (questionHasOptions(question) && question.multi_select === true) {
 				state.customAnswer = answer;
 				this.commitCurrentAnswer();
-			} else {
-				state.customAnswer = questionHasOptions(question) ? answer : "";
-				state.answer = answer;
-				this.finishIfCompleteOrAdvance();
+				return;
 			}
+			state.customAnswer = questionHasOptions(question) ? answer : "";
+			// The chosen labels and the typed text compose, so a question answered
+			// with an option that says "I will type it" keeps both. With nothing
+			// selected, which is the implicit Other path, this is the text alone.
+			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;
 	}
@@ -866,7 +972,14 @@ class AskUserOverlayView implements Component {
 				return;
 			}
 			state.selected = new Set<number>([optionIndex]);
-			state.answer = question.options?.[optionIndex]?.label ?? item.label;
+			// Choosing a plain option is a label-only answer, so the typed text
+			// clears with the choice: it was given for a label the operator has
+			// just moved off, and the composed answer runs through the same
+			// `answerText` every other path uses.
+			state.customAnswer = "";
+			state.rawValue = "";
+			state.inputValue = "";
+			state.answer = answerText(question, state.selected, state.customAnswer) || item.label;
 			state.focusedValue = item.value;
 			this.status = "";
 			this.finishIfCompleteOrAdvance();
@@ -902,6 +1015,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();
@@ -992,12 +1152,26 @@ class AskUserOverlayView implements Component {
 		return this.states.length > 0 && this.states.every((state) => state.answer.trim().length > 0);
 	}
 
+	/**
+	 * What the round captured, as three separable facts per question: the one-line
+	 * answer, the labels chosen, and the text typed. A reader tells a label-only
+	 * answer from a label-plus-value one by whether `value` is there, which the
+	 * joined string alone could never say.
+	 */
 	private answers(): AskUserResult["answers"] {
 		const answers: AskUserResult["answers"] = [];
 		for (let index = 0; index < this.questions.length; index += 1) {
 			const question = this.questions[index];
-			const answer = this.states[index]?.answer.trim();
-			if (question && answer && answer.length > 0) answers.push({ question: question.question, answer });
+			const state = this.states[index];
+			const answer = state?.answer.trim();
+			if (!question || !state || !answer || answer.length === 0) continue;
+			const options = selectedOptionLabels(question, state.selected);
+			answers.push({
+				question: question.question,
+				answer,
+				...(options.length > 0 ? { options } : {}),
+				...(state.rawValue.length > 0 ? { value: state.rawValue } : {}),
+			});
 		}
 		return answers;
 	}
@@ -1005,6 +1179,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();
@@ -1056,6 +1231,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

@@ -102,6 +102,7 @@ export function openContextResetOverlay(tui: TUI, deps: OpenContextResetOverlayD
 	return showClioOverlayFrame(tui, new FocusBox(list), {
 		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

@@ -135,6 +135,7 @@ export function openCwdFallbackOverlay(tui: TUI, deps: OpenCwdFallbackOverlayDep
 	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,22 +94,21 @@ 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;
 }
@@ -296,6 +295,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

@@ -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

@@ -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.",
@@ -129,6 +130,10 @@ export function openHelpOverlay(
 					"auto-edit parks unrecognized commands, and full-auto runs them.",
 				"**Approvals**: a parked call waits for a one-shot operator decision; approving resumes only that call. " +
 					"Workers resolve asks per `workers.onPermission` (Approvals Routing); headless runs auto-deny.",
+				"**Inspecting a mutation**: a parked `write` or `edit` card carries the target, the byte count, and a `sha256` digest of the exact call arguments. " +
+					"Press `v` to read the complete proposed content, or the complete effective diff against the file on disk, and `v` again to put it away; ↑/↓ and PageUp/PageDown scroll it. " +
+					"Enter still allows, `s` still stops, and Esc still denies while it is open. The mutation text is shown locally and never enters the transcript, a notice, a desktop notification, or the render trace. " +
+					"A worker escalation has no preview because the call's arguments never leave the worker, and its card says so.",
 			],
 		},
 	];
@@ -136,6 +141,7 @@ export function openHelpOverlay(
 	const items = [...commands, ...keys, ...topics];
 
 	return openListOverlay(tui, {
+		markerId: "help",
 		title: "Help Center",
 		items,
 		filterable: true,

package/src/interactive/overlays/interop.ts

@@ -120,6 +120,7 @@ export function openInteropOverlay(tui: TUI, ctx: SlashCommandContext, onClose:
 	};
 
 	const handle: ListOverlayHandle = openListOverlay(tui, {
+		markerId: "interop",
 		title: "Interop",
 		items: buildItems(deps),
 		filterable: true,

package/src/interactive/overlays/library-install-confirm.ts

@@ -137,6 +137,7 @@ export function openLibraryInstallConfirmOverlay(
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: confirmOverlayWidth(options.columns),
+		markerId: "library-install",
 		title: LIBRARY_INSTALL_CONFIRM_TITLE,
 		footerHint: buildResponsiveHint([{ key: "Enter", verb: "install" }], { key: "Esc", verb: "cancel" }),
 	});

package/src/interactive/overlays/library-tabs.ts

@@ -0,0 +1,28 @@
+/**
+ * The Skills Hub's tab table.
+ *
+ * It sits in its own module rather than inside `skills-hub.ts` because the slash
+ * registry parses `/library <kind>` against it, and the registry has to stay off
+ * the render module graph. Pulling the whole hub overlay in for four ids made
+ * `src/cli/run.ts` a second, disjoint reacher of the interactive theme and
+ * `src/engine/tui.ts`, which splits the merged chunk the Stage 0 instant shell
+ * depends on. See `tests/contracts/instant-shell-import-graph.test.ts`.
+ *
+ * Pure data plus its membership test: no rendering, no overlay state.
+ * `skills-hub.ts` re-exports both symbols, so every existing importer keeps the
+ * path it had.
+ */
+
+import type { LibraryEntryKind } from "../../domains/resources/index.js";
+
+/** The hub's tabs, in the order ←/→ walks them. `skill` is the original view. */
+export const LIBRARY_TABS: ReadonlyArray<{ id: LibraryEntryKind; label: string }> = [
+	{ id: "skill", label: "Skills" },
+	{ id: "agent", label: "Agents" },
+	{ id: "prompt", label: "Prompts" },
+	{ id: "fleet", label: "Fleets" },
+];
+
+export function isLibraryTab(value: string): value is LibraryEntryKind {
+	return LIBRARY_TABS.some((tab) => tab.id === value);
+}

package/src/interactive/overlays/list-overlay.ts

@@ -742,11 +742,20 @@ export interface ListOverlayHandle extends OverlayHandle {
 	activeTabId(): string;
 }
 
-export function openListOverlay(tui: TUI, options: ListOverlayOptions): ListOverlayHandle {
+/**
+ * The marker id rides on the opener rather than on `ListOverlayOptions` because
+ * it belongs to the mounted modal, not to the view: the view renders the same
+ * rows whether it is a modal or a body inside something else. It is named by
+ * the surface rather than derived from `title`, because a tabbed overlay's
+ * rendered title names the active tab while the modal holding the keyboard has
+ * not changed hands.
+ */
+export function openListOverlay(tui: TUI, options: ListOverlayOptions & { markerId: string }): ListOverlayHandle {
 	const view = new ListOverlayView(options, () => tui.requestRender());
 	const handle = showClioOverlayFrame(tui, view, {
 		anchor: "center",
 		width: 100,
+		markerId: options.markerId,
 		// A function, not the string: on a tabbed overlay the title names the tab
 		// and must be re-read after every switch.
 		title: () => view.title(),

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

@@ -149,6 +149,7 @@ export function openMessagePickerOverlay(tui: TUI, deps: OpenMessagePickerOverla
 	return showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: MESSAGE_PICKER_OVERLAY_WIDTH,
+		markerId: "message-picker",
 		title: "Fork",
 		footerHint: rows.length > 0 ? buildHint([{ key: "Enter", verb: "select" }]) : buildHint([]),
 	});