@iowarp/clio-coder 0.3.2 → 0.3.4

package/src/interactive/footer-panel.ts

@@ -1,6 +1,7 @@
 import type { TokenThroughputSnapshot, UsageBreakdown } from "../domains/observability/index.js";
 import { type Text, truncateToWidth, visibleWidth } from "../engine/tui.js";
 import type { DispatchBoardRow, DispatchBoardStatus } from "./dispatch-board.js";
+import { formatReasoningChip } from "./status/reasoning.js";
 import { type ClioTheme, formatCompactMs, formatContextPercent, GLYPH } from "./theme/index.js";
 
 /**
@@ -37,7 +38,11 @@ export function tokensSegment(usage: UsageBreakdown | null | undefined): string
 	const reasoning = Math.max(0, usage.reasoningTokens ?? 0);
 	const total = Math.max(0, usage.totalTokens ?? input + output);
 	if (input + output + reasoning + total === 0) return null;
-	const reasoningPart = reasoning > 0 ? ` r${formatFooterTokens(reasoning)}` : "";
+	// Session totals are summed from provider usage payloads, so the chip carries
+	// no `≈`. It is built by the same formatter every other reasoning surface
+	// uses rather than by a fourth copy of the marker rule.
+	const reasoningChip = formatReasoningChip({ tokens: reasoning, provenance: "provider" }, formatFooterTokens);
+	const reasoningPart = reasoningChip === null ? "" : ` ${reasoningChip}`;
 	const totalPart = total > 0 ? ` Σ${formatFooterTokens(total)}` : "";
 	return `${GLYPH.up}${formatFooterTokens(input)} ${GLYPH.down}${formatFooterTokens(output)}${reasoningPart}${totalPart}`;
 }

package/src/interactive/interactive-application.ts

@@ -560,6 +560,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		recordToolEnd: (_toolName, toolCallId, isError, truncated) =>
 			presentation.recordToolEnd({ toolCallId, isError, truncated }),
 		setStatusLine: (line) => chatPanel.setStatusLine(line),
+		setLiveReasoning: (view) => chatPanel.setLiveReasoning(view),
 		setLastTurnSummary: (summary) => presentation.setLastTurnSummary(summary),
 		startTerminalProgress: () => agentProgress.start(),
 		stopTerminalProgress: () => agentProgress.stop(),
@@ -591,6 +592,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		chatPanel: {
 			appendReplayBlock: (...args) => chatRenderer.mutate(() => chatPanel.appendReplayBlock(...args), "slash-output"),
 			appendUser: (text) => chatRenderer.mutate(() => chatPanel.appendUser(text), "user-submit"),
+			clearFoldOverrides: () => chatRenderer.mutate(() => chatPanel.clearFoldOverrides(), "output-detail"),
 		},
 		beforeSemanticSubmit: () => chatRenderer.flush(),
 		settleVisibleFrame: (reason) => chatRenderer.flushAndCommit(reason),

package/src/interactive/interactive-event-projection.ts

@@ -28,6 +28,8 @@ import {
 import {
 	type AgentStatus,
 	INLINE_STATUS_INDENT_COLS,
+	type ReasoningUsageView,
+	reasoningFromTally,
 	resolveInlineVerb,
 	type StatusPhase,
 	spinnerFrame,
@@ -67,6 +69,11 @@ export interface InteractiveEventProjectionDeps {
 	recordToolStart: (toolName: string, toolCallId: string) => void;
 	recordToolEnd: (toolName: string, toolCallId: string, isError: boolean, truncated: boolean) => void;
 	setStatusLine: (line: InteractiveStatusLine | null) => void;
+	/**
+	 * Publish the live turn's reasoning projection to the transcript. Optional so
+	 * a host without a chat panel still gets every other projection.
+	 */
+	setLiveReasoning?: (view: ReasoningUsageView | null) => void;
 	setLastTurnSummary: (summary: TurnSummary) => void;
 	startTerminalProgress: () => void;
 	stopTerminalProgress: () => void;
@@ -177,6 +184,11 @@ export function createInteractiveEventProjection(deps: InteractiveEventProjectio
 	let statusInlineFrame = 0;
 	primaryUnsubscribers.push(
 		deps.status.subscribe((status) => {
+			// One projection of the run tally reaches the transcript, so the live
+			// line, the turn receipt, and the footer state the same number.
+			deps.setLiveReasoning?.(
+				status.phase === "idle" || status.phase === "ended" ? null : reasoningFromTally(status.runTally),
+			);
 			if (status.phase === "idle") {
 				deps.setStatusLine(null);
 			} else if (status.phase === "ended") {

package/src/interactive/interactive-slash-runtime.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { BusChannels } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { PendingSkillRequest } from "../core/skill-activation.js";
@@ -28,6 +29,7 @@ import { type ChatPanel, createChatPanel } from "./chat-panel.js";
 import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { runCompactWithNotice } from "./command-fallbacks.js";
 import { appendNotice, appendOperatorCommand } from "./command-output.js";
+import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
@@ -54,7 +56,7 @@ export interface InteractiveSlashSubmitExpansion {
 }
 
 type SlashChat = Pick<ChatLoop, "getSessionId" | "isStreaming" | "submit">;
-type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser">;
+type SlashChatPanel = Pick<ChatPanel, "appendReplayBlock" | "appendUser" | "clearFoldOverrides">;
 type SlashResources = Pick<ResourcesContract, "prompts" | "expandPromptTemplate" | "reload">;
 type SlashExtensions = Pick<ExtensionsContract, "list">;
 type SlashAgents = Pick<AgentsContract, "getSpec" | "listSpecs">;
@@ -100,8 +102,10 @@ export interface InteractiveSlashRuntimeDeps {
 	 * Leaf lookup for `/export`, so the export follows the branch the session
 	 * is actually on. current.jsonl still holds the abandoned turns after a
 	 * `/tree` pin, and an unscoped rehydrate reproduced them (issue #109).
+	 * `/context recall` uses the same leaf for its fold, plus `appendEntry` for
+	 * the `contextRecall` record.
 	 */
-	session?: Pick<SessionContract, "tree">;
+	session?: Pick<SessionContract, "tree" | "current" | "appendEntry">;
 	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
 	openAskUser: AskUserHandler;
 	openSkillsHub: () => void;
@@ -398,6 +402,11 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			// alone. Saving it as the default is what Settings → Terminal is for.
 			if (deps.commitSetting) deps.commitSetting("terminal.outputVerbosity", next, "session");
 			else deps.writeSettings?.(next);
+			// `/output` is also the explicit reset action for transcript folds. Do
+			// this even when the requested level already matches the current one;
+			// the render-time change detector cannot observe a same-value command.
+			deps.chatPanel.clearFoldOverrides();
+			deps.refreshFooter();
 			return { status: "applied", verbosity: match };
 		},
 		openModel: deps.openModel,
@@ -434,11 +443,12 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			try {
 				const turns = deps.readStructuredEntries(sessionId);
 				// Same pure render pipeline as the live panel and /resume replay: a
-				// throwaway panel is rehydrated from the ledger, every tool segment is
-				// expanded, and the transcript is rendered at a stable width. HTML
-				// converts the resulting ANSI presentation to inline styles; Markdown
-				// keeps the prior plain-text fenced transcript.
-				const exportPanel = createChatPanel({ unboundedToolBodies: true });
+				// throwaway panel is rehydrated from the ledger under the verbose
+				// transcript detail policy (every body open, full receipts) with no
+				// operator overrides, and rendered at a stable width. HTML converts
+				// the resulting ANSI presentation to inline styles; Markdown keeps the
+				// prior plain-text fenced transcript.
+				const exportPanel = createChatPanel({ unboundedToolBodies: true, getOutputVerbosity: () => "verbose" });
 				// Scoped to the leaf the session is on, the same way /resume replays
 				// (issue #107): with a /tree pin persisted and not yet extended, the
 				// file still holds the abandoned branch after the pin, and an unscoped
@@ -449,7 +459,6 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 					unboundedToolBodies: true,
 					...(leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
 				});
-				exportPanel.toggleAllToolsExpanded();
 				const ansiLines = exportPanel.render(EXPORT_RENDER_WIDTH);
 				// The operator names this file by the day they ran the export, so the
 				// date in it is their calendar date. The header below keeps the ISO
@@ -507,6 +516,38 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			}
 			deps.openContextReset();
 		},
+		...(deps.session
+			? {
+					runContextRecall: (ref: string) => {
+						const session = deps.session;
+						if (!session) return;
+						const outcome = runOperatorRecall(ref, {
+							hasSession: () => session.current() !== null,
+							readEntries: () => {
+								const sessionId = deps.chat.getSessionId();
+								return sessionId ? deps.readStructuredEntries(sessionId) : [];
+							},
+							activeLeafTurnId: () => {
+								const meta = session.current();
+								return meta ? (session.tree(meta.id).leafId ?? undefined) : undefined;
+							},
+							appendEntry: (entry) => session.appendEntry(entry),
+							onRecalled: (payload) => deps.bus.emit(BusChannels.ContextRecalled, payload),
+							...(deps.now ? { now: () => (deps.now?.() ?? new Date()).getTime() } : {}),
+						});
+						if (!outcome.ok) {
+							appendCommandNotice("error", outcome.message);
+							return;
+						}
+						appendCommandNotice("success", outcome.headline);
+						// The body is transcript output, not a notice: notices collapse
+						// newlines, and a recalled build log is worth nothing on one line.
+						// It is a replay block either way, so it never enters model context.
+						deps.io.stdout(`${outcome.body}\n`);
+						deps.requestRender();
+					},
+				}
+			: {}),
 		runContextRefresh: () => {
 			if (!deps.onContextRefresh) {
 				deps.io.stderr("[/context refresh] context refresh not wired; pass onContextRefresh to startInteractive\n");

package/src/interactive/model-session-replay.ts

@@ -0,0 +1,21 @@
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import { projectWorkingSet } from "../domains/context/working-set/project.js";
+import type { SessionEntry } from "../domains/session/entries.js";
+import type { AgentMessage } from "../engine/types.js";
+import { buildReplayAgentMessagesFromTurns, type RehydrateChatPanelOptions } from "./chat-renderer.js";
+
+/**
+ * Build provider-facing replay messages from the durable session ledger.
+ * Projection always honors existing eviction and recall entries; the enabled
+ * setting gates creation of new evictions, not replay of durable state.
+ * Visible transcript and export callers intentionally keep using the raw
+ * rehydration helpers so eviction remains a model projection, not data loss.
+ */
+export function buildModelReplayAgentMessagesFromTurns(
+	entries: ReadonlyArray<SessionEntry>,
+	options: RehydrateChatPanelOptions = {},
+): AgentMessage[] {
+	const activeLeafTurnId = options.activeLeafTurnId ?? options.uptoTurnId;
+	const projected = projectWorkingSet(entries, foldWorkingSet(entries, activeLeafTurnId));
+	return buildReplayAgentMessagesFromTurns(projected, options);
+}

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

@@ -1,4 +1,5 @@
 import type { SafeEventBus } from "../core/event-bus.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
 import type { DispatchContract } from "../domains/dispatch/index.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
@@ -107,6 +108,11 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.handle = openContextOverlayFactory(deps.tui, deps.getContextLedger, {
 			bus: deps.bus,
 			chat: deps.contextChat,
+			getWorkingSet: () => {
+				const readSessionEntries = deps.readSessionEntries;
+				if (!readSessionEntries) return null;
+				return foldWorkingSet(readSessionEntries(), deps.getSessionMeta()?.pinnedLeafTurnId ?? undefined);
+			},
 		});
 		deps.requestRender();
 	};

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

@@ -3,9 +3,10 @@ import type { SessionContract, SessionEntry } from "../domains/session/index.js"
 import type { TUI } from "../engine/tui.js";
 import type { ChatLoop } from "./chat-loop.js";
 import type { ChatPanel } from "./chat-panel.js";
-import { buildReplayAgentMessagesFromTurns, rehydrateChatPanelFromTurns } from "./chat-renderer.js";
+import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
 import type { InteractiveNoticeLevel } from "./interactive-subscriptions.js";
+import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
 import type { OverlayTransitions } from "./overlay-transitions.js";
 import { openCwdFallbackOverlay } from "./overlays/cwd-fallback.js";
 import { openMessagePickerOverlay } from "./overlays/message-picker.js";
@@ -159,7 +160,7 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 					const replayOptions = leafTurnId ? { activeLeafTurnId: leafTurnId } : {};
 					deps.resetTranscript();
 					rehydrateChatPanelFromTurns(deps.chatPanel, turns, replayOptions);
-					const replayMessages = buildReplayAgentMessagesFromTurns(turns, replayOptions);
+					const replayMessages = buildModelReplayAgentMessagesFromTurns(turns, replayOptions);
 					deps.chat.resetForSession(leafTurnId, replayMessages);
 					rescopeToBranch(session, turns, leafTurnId);
 				} catch (error) {
@@ -209,7 +210,7 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 					const turns = deps.readStructuredEntries(sessionId);
 					deps.resetTranscript();
 					rehydrateChatPanelFromTurns(deps.chatPanel, turns, { uptoTurnId: turnId });
-					const replayMessages = buildReplayAgentMessagesFromTurns(turns, { uptoTurnId: turnId });
+					const replayMessages = buildModelReplayAgentMessagesFromTurns(turns, { uptoTurnId: turnId });
 					deps.chat.resetForSession(turnId, replayMessages);
 					// The same branch the transcript above was just scoped to. Without the
 					// leaf, /cost, the footer Σ, and the last-turn line kept reporting the
@@ -287,8 +288,11 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		try {
 			const turns = deps.readStructuredEntries(forkedSessionId);
 			rehydrateChatPanelFromTurns(deps.chatPanel, turns);
-			const replayMessages = buildReplayAgentMessagesFromTurns(turns);
 			const leafTurnId = session.tree(forkedSessionId).leafId ?? parentTurnId;
+			const replayMessages = buildModelReplayAgentMessagesFromTurns(
+				turns,
+				leafTurnId ? { activeLeafTurnId: leafTurnId } : {},
+			);
 			deps.chat.resetForSession(leafTurnId, replayMessages);
 			rescopeToBranch(session, turns, leafTurnId);
 		} catch (error) {

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

@@ -13,8 +13,9 @@ 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, showClioOverlayFrame } from "../overlay-frame.js";
+import { buildHint, DEFAULT_SELECT_THEME, type HintEntry, 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";
 
 /**
  * The border and title token while a decision is pending.
@@ -54,7 +55,7 @@ export const ASK_USER_DEFAULT_SURFACE: AskUserSurface = "panel";
 interface AskUserSurfaceGeometry {
 	/** Box width in columns; zero fills the row. The frame clamps to the terminal. */
 	width: number;
-	/** Rows the body may use, before the borders. */
+	/** Rows the body may use, before the borders. Zero means every row the frame has. */
 	maxInnerRows: number;
 	anchor: NonNullable<OverlayOptions["anchor"]>;
 	margin: NonNullable<OverlayOptions["margin"]>;
@@ -74,12 +75,18 @@ interface AskUserSurfaceGeometry {
 export const ASK_USER_SURFACE_GEOMETRY: Record<AskUserSurface, AskUserSurfaceGeometry> = {
 	compact: { width: 68, maxInnerRows: 10, anchor: "bottom-center", margin: { top: 1, right: 2, bottom: 1, left: 2 } },
 	panel: { width: 88, maxInnerRows: 18, anchor: "center", margin: 1 },
-	interview: { width: 0, maxInnerRows: 42, anchor: "center", margin: 1 },
+	// The interview is a workspace, not a modal. A cap of 42 turned a 66-row
+	// terminal into a centered box with twenty blank rows around it, so the
+	// interview takes every row the frame has and lays its own chrome out inside
+	// them. The one-row margin keeps the border off the top row and the footer.
+	interview: { width: 0, maxInnerRows: 0, anchor: "center", margin: 1 },
 };
 
 const ASK_USER_FRAME_ROWS = 2;
 const ASK_USER_FRAME_AND_MARGIN_ROWS = 4;
 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;
 const ELLIPSIS = "…";
 
@@ -227,6 +234,14 @@ class AskUserOverlayView implements Component {
 	private list: SelectList | null = null;
 	private input: Input | null = null;
 	private resolveCurrent: ((result: AskUserResult) => void) | null = null;
+	/** Rows of the interview's scrollable middle already scrolled past. */
+	private contentScrollOffset = 0;
+	/** Whether the last interview render had more content than the region held. */
+	private contentOverflows = false;
+	/** Rows the scroll region drew on the last render, for a page-sized jump. */
+	private contentRegionHeight = 1;
+	/** Rows the scroll region wanted on the last render. */
+	private contentTotalRows = 0;
 
 	constructor(private readonly deps: AskUserOverlayViewDeps) {}
 
@@ -240,6 +255,7 @@ class AskUserOverlayView implements Component {
 		this.states = this.questions.map((question) => createQuestionState(question));
 		this.list = null;
 		this.input = null;
+		this.resetContentScroll();
 		// Before the controls, because how many option rows fit is a property of
 		// the box this round is about to be drawn in.
 		this.setSurface(askUserSurface(this.questions, this.history.length));
@@ -283,6 +299,10 @@ class AskUserOverlayView implements Component {
 		const state = this.currentState();
 		if (!question || !state) return;
 
+		// Scrolling the transcript must not cost the operator their place in the
+		// options, so the region has keys of its own that neither control claims.
+		if (this.handleScrollInput(data, state.mode)) return;
+
 		if (state.mode === "text") {
 			if (this.isTextModePreviousKey(data)) {
 				this.goToRelativeQuestion(-1);
@@ -331,21 +351,106 @@ class AskUserOverlayView implements Component {
 		const question = this.currentQuestion();
 		if (!question) return [clioTheme().fg("muted", "No questions.")];
 
-		const interview = this.surface === "interview";
+		if (this.surface === "interview") return this.renderInterview(question, safeWidth, maxRows);
+
+		this.contentOverflows = false;
 		const controlLines = this.renderControlLines(safeWidth);
-		const ledgerLines = interview ? this.renderAnswerLedger(safeWidth) : [];
 		const statusLines = this.status.length > 0 ? ["", fitLine(clioTheme().fg("dim", this.status), safeWidth)] : [];
-		const stripLines = interview ? [this.renderQuestionStrip(safeWidth), ""] : [];
 		const headerLine = this.renderQuestionHeader(question, safeWidth);
 		const headerLines = headerLine.length > 0 ? [headerLine] : [];
-		const spent =
-			stripLines.length + headerLines.length + statusLines.length + 1 + controlLines.length + ledgerLines.length;
+		const spent = headerLines.length + statusLines.length + 1 + controlLines.length;
 		const questionLines = wrapTextWithAnsi(question.question, safeWidth).slice(0, Math.max(1, maxRows - spent));
 
-		return [...stripLines, ...headerLines, ...questionLines, ...statusLines, "", ...controlLines, ...ledgerLines].slice(
-			0,
-			maxRows,
+		return [...headerLines, ...questionLines, ...statusLines, "", ...controlLines].slice(0, maxRows);
+	}
+
+	/**
+	 * The interview, as a workspace with fixed chrome and a scrolling middle.
+	 *
+	 * The round strip and the question header hold the top; the status line and
+	 * the active control hold the bottom, at their full row cost, so the thing the
+	 * operator has to act on is never the thing that gets clipped. The question
+	 * text and the answer ledger share whatever is left and scroll through it.
+	 * Everything is re-derived per render, so a resize is just the next frame.
+	 */
+	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 headerLine = this.renderQuestionHeader(question, width);
+		const headerLines = headerLine.length > 0 ? [headerLine] : [];
+		const stripLines = [this.renderQuestionStrip(width), ""];
+		const content = [...wrapTextWithAnsi(question.question, width), ...this.renderAnswerLedger(width)];
+
+		// Chrome sheds from the outside in when the terminal is too short to carry
+		// all of it: the round strip first, then the header, then the status, and
+		// the control only if a terminal is short enough that nothing else is left.
+		let top = [...stripLines, ...headerLines];
+		let bottom = [...statusLines, "", ...controlLines];
+		const region = (): number => maxRows - top.length - bottom.length;
+		if (region() < 1) top = [...headerLines];
+		if (region() < 1) top = [];
+		if (region() < 1) bottom = ["", ...controlLines];
+		if (region() < 1) bottom = [...controlLines];
+		const regionRows = Math.max(1, region());
+
+		const overflows = content.length > regionRows;
+		this.contentOverflows = overflows;
+		this.contentTotalRows = content.length;
+		// One row of the region pays for the indicator when there is more than the
+		// region holds, so the marker never covers a row it is reporting on.
+		const viewRows = overflows ? Math.max(1, regionRows - 1) : regionRows;
+		this.contentRegionHeight = viewRows;
+		this.contentScrollOffset = Math.max(0, Math.min(this.contentScrollOffset, Math.max(0, content.length - viewRows)));
+
+		const visible = content.slice(this.contentScrollOffset, this.contentScrollOffset + viewRows);
+		const middle = [...visible];
+		if (overflows) middle.push(fitLine(theme.fg("dim", this.scrollIndicator(content.length, viewRows)), width));
+		while (middle.length < regionRows) middle.push("");
+
+		return [...top, ...middle, ...bottom].slice(0, maxRows);
+	}
+
+	private scrollIndicator(total: number, viewRows: number): string {
+		const above = this.contentScrollOffset;
+		const below = Math.max(0, total - viewRows - above);
+		const parts: string[] = [];
+		if (above > 0) parts.push(`↑ ${above} more`);
+		if (below > 0) parts.push(`↓ ${below} more`);
+		parts.push(`(${Math.min(total, above + viewRows)}/${total})`);
+		return parts.join("  ");
+	}
+
+	/** True when the key belonged to the scroll region rather than to a control. */
+	private handleScrollInput(data: string, mode: Mode): boolean {
+		if (this.surface !== "interview") return false;
+		const action = this.scrollAction(data, mode);
+		if (!action) return false;
+		const next = nextContentScrollOffset(
+			this.contentScrollOffset,
+			this.contentTotalRows,
+			this.contentRegionHeight,
+			action,
 		);
+		if (next !== this.contentScrollOffset) {
+			this.contentScrollOffset = next;
+			this.deps.requestRender();
+		}
+		return true;
+	}
+
+	private scrollAction(data: string, mode: Mode): ViewScrollAction | null {
+		if (matchesKey(data, "pageUp")) return "page-up";
+		if (matchesKey(data, "pageDown")) return "page-down";
+		// Ctrl+U and Ctrl+D are line-kill and half-page in a text field, so they
+		// stay with the input while one is focused.
+		if (mode === "select" && matchesKey(data, "ctrl+u")) return "half-up";
+		if (mode === "select" && matchesKey(data, "ctrl+d")) return "half-down";
+		return null;
+	}
+
+	private resetContentScroll(): void {
+		this.contentScrollOffset = 0;
 	}
 
 	footerHint(): string {
@@ -357,11 +462,11 @@ class AskUserOverlayView implements Component {
 		if (!question || !state) return buildHint([]);
 		if (state.mode === "text") {
 			return this.questions.length > 1
-				? buildHint([
+				? this.withScrollHint([
 						{ key: "Enter", verb: "submit" },
 						{ key: "Alt+Left/Right", verb: "question" },
 					])
-				: buildHint([{ key: "Enter", verb: "submit" }]);
+				: this.withScrollHint([{ key: "Enter", verb: "submit" }]);
 		}
 		// `accept` rather than `select` or `commit`: the footer of a decision prompt
 		// has one job, which is to name the key that answers it. Esc keeps the
@@ -369,22 +474,32 @@ class AskUserOverlayView implements Component {
 		// interview together.
 		if (question.multi_select === true) {
 			return this.questions.length > 1
-				? buildHint([
+				? this.withScrollHint([
 						{ key: "Left/Right", verb: "question" },
 						{ key: "Space", verb: "toggle" },
 						{ key: "Enter", verb: "accept" },
 					])
-				: buildHint([
+				: this.withScrollHint([
 						{ key: "Space", verb: "toggle" },
 						{ key: "Enter", verb: "accept" },
 					]);
 		}
 		return this.questions.length > 1
-			? buildHint([
+			? this.withScrollHint([
 					{ key: "Left/Right", verb: "question" },
 					{ key: "Enter", verb: "accept" },
 				])
-			: buildHint([{ key: "Enter", verb: "accept" }]);
+			: this.withScrollHint([{ key: "Enter", verb: "accept" }]);
+	}
+
+	/**
+	 * The keys for this question, plus the scroll keys when there is something to
+	 * 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 setSurface(next: AskUserSurface): void {
@@ -443,17 +558,20 @@ class AskUserOverlayView implements Component {
 	private maxInnerRows(): number {
 		const cap = ASK_USER_SURFACE_GEOMETRY[this.surface].maxInnerRows;
 		const rows = this.deps.getTerminalRows();
-		if (!Number.isFinite(rows) || rows <= 0) return cap;
-		return Math.max(1, Math.min(cap, Math.floor(rows) - ASK_USER_FRAME_AND_MARGIN_ROWS));
+		// A zero cap is the interview's "every row the frame has", which is the
+		// same number the frame budgets itself when the mount passes no maxHeight.
+		if (!Number.isFinite(rows) || rows <= 0) return cap > 0 ? cap : 1;
+		const available = Math.max(1, Math.floor(rows) - ASK_USER_FRAME_AND_MARGIN_ROWS);
+		return cap > 0 ? Math.min(cap, available) : available;
 	}
 
 	private maxVisibleOptions(): number {
 		const inner = this.maxInnerRows();
-		// The interview surface spends rows on the round strip and the ledger
-		// before an option ever renders. The other two spend them on a header, a
-		// question, and a separator, so the options get nearly everything.
+		// The interview's option list is budgeted off the live row count rather
+		// than a fixed heuristic: the strip, header, blank, status, blank and one
+		// row of question are what the control shares the workspace with.
 		if (this.surface === "interview") {
-			return Math.max(MIN_VISIBLE_OPTIONS, Math.min(MAX_VISIBLE_OPTIONS, inner - 12));
+			return Math.max(MIN_VISIBLE_OPTIONS, Math.min(MAX_VISIBLE_OPTIONS, inner - INTERVIEW_CHROME_ROWS));
 		}
 		return Math.max(1, Math.min(MAX_VISIBLE_OPTIONS, inner - 4));
 	}
@@ -809,6 +927,7 @@ class AskUserOverlayView implements Component {
 		const next = this.nextUnansweredIndex();
 		if (next !== null) {
 			this.index = next;
+			this.resetContentScroll();
 			const nextState = this.currentState();
 			const nextQuestion = this.currentQuestion();
 			if (nextState && nextQuestion && !nextState.answer.trim()) nextState.mode = initialMode(nextQuestion);
@@ -844,6 +963,7 @@ class AskUserOverlayView implements Component {
 		this.syncActiveControl();
 		this.index = (this.index + delta + this.questions.length) % this.questions.length;
 		this.status = "";
+		this.resetContentScroll();
 		this.rebuildControl();
 		this.deps.requestRender();
 	}
@@ -888,7 +1008,9 @@ export function openAskUserOverlay(tui: TUI, deps: OpenAskUserOverlayDeps): AskU
 		handle = showClioOverlayFrame(tui, view, {
 			anchor: geometry.anchor,
 			width: geometry.width,
-			maxHeight: geometry.maxInnerRows + ASK_USER_FRAME_ROWS,
+			// A zero cap means the frame keeps its own budget, which is every row
+			// the terminal has left after the margins.
+			...(geometry.maxInnerRows > 0 ? { maxHeight: geometry.maxInnerRows + ASK_USER_FRAME_ROWS } : {}),
 			margin: geometry.margin,
 			title: () => (view.isDecisionPending() ? ASK_USER_DECISION_TITLE : ASK_USER_WAITING_TITLE),
 			tone: () => (view.isDecisionPending() ? ASK_USER_DECISION_TONE : undefined),