@iowarp/clio-coder 0.3.1 → 0.3.3

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

@@ -4,6 +4,10 @@ import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/inde
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import type { ContextLedger } from "../domains/session/context-ledger.js";
 import type { SessionMeta } from "../domains/session/index.js";
+import { foldSessionArtifacts } from "../domains/session/session-artifacts.js";
+import { foldSessionTaskHistory } from "../domains/session/task-board.js";
+import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
+import type { UserTasksStore } from "../domains/user-tasks/store.js";
 import type { TUI } from "../engine/tui.js";
 import { type OpenContextOverlayOptions, openContextOverlay } from "./context-overlay.js";
 import { openCostOverlay } from "./cost-overlay.js";
@@ -20,7 +24,8 @@ import {
 	contextResetOptions,
 	openContextResetOverlay,
 } from "./overlays/context-reset.js";
-import type { ContextClearCommandOptions } from "./slash-commands.js";
+import { formatDecisionCorrectionTurn, openDecisionsOverlay } from "./overlays/decisions.js";
+import { type ContextClearCommandOptions, formatUserTaskHandoff } from "./slash-commands.js";
 import { openTasksOverlay } from "./tasks-overlay.js";
 import { type ArtifactProviderDeps, createDefaultArtifactProviders } from "./view/artifacts.js";
 import { openViewOverlay } from "./view/view-overlay.js";
@@ -40,6 +45,10 @@ export interface OverlayGeneralOpenersDeps {
 	renderTaskIsland: () => void;
 	requestRender: () => void;
 	getTaskBoard?: Parameters<typeof openTasksOverlay>[1];
+	userTasks?: UserTasksStore;
+	getDecisionBoard?: Parameters<typeof openDecisionsOverlay>[1];
+	supersedeDecision?: (interviewId: string, key: string, correction?: string) => unknown;
+	submitChat: (text: string) => void;
 	getTaskMemoryStatus?: Parameters<typeof openMemoryOverlay>[1];
 	dataDir: string;
 	notify: (level: "info" | "success" | "warning" | "error", text: string, key?: string) => void;
@@ -56,6 +65,7 @@ export interface OverlayGeneralOpenersDeps {
 	openContextOverlay?: typeof openContextOverlay;
 	openContextResetOverlay?: typeof openContextResetOverlay;
 	openTasksOverlay?: typeof openTasksOverlay;
+	openDecisionsOverlay?: typeof openDecisionsOverlay;
 	openMemoryOverlay?: typeof openMemoryOverlay;
 	openViewOverlay?: typeof openViewOverlay;
 }
@@ -66,6 +76,7 @@ export interface OverlayGeneralOpeners {
 	openContextReset(): void;
 	toggleFooter(): void;
 	openTasks(): void;
+	openDecisions(): void;
 	openMemory(): void;
 	openView(initialFilter?: string): void;
 	toggleDispatchBoard(): void;
@@ -76,6 +87,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 	const openContextOverlayFactory = deps.openContextOverlay ?? openContextOverlay;
 	const openContextResetOverlayFactory = deps.openContextResetOverlay ?? openContextResetOverlay;
 	const openTasksOverlayFactory = deps.openTasksOverlay ?? openTasksOverlay;
+	const openDecisionsOverlayFactory = deps.openDecisionsOverlay ?? openDecisionsOverlay;
 	const openMemoryOverlayFactory = deps.openMemoryOverlay ?? openMemoryOverlay;
 	const openViewOverlayFactory = deps.openViewOverlay ?? openViewOverlay;
 	const showOverlayFrameFactory = deps.showOverlayFrame ?? showClioOverlayFrame;
@@ -137,6 +149,50 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.state = "tasks";
 		deps.transitions.handle = openTasksOverlayFactory(deps.tui, () => deps.getTaskBoard?.() ?? null, {
 			onClose: deps.closeOverlay,
+			getSessionSnapshot: () => {
+				const meta = deps.getSessionMeta();
+				const entries = filterEntriesToActivePath(deps.readSessionEntries?.() ?? [], meta?.pinnedLeafTurnId ?? undefined);
+				const workspace = meta?.cwd ?? process.cwd();
+				return {
+					history: foldSessionTaskHistory(entries),
+					artifacts: foldSessionArtifacts(entries, { workspace }),
+				};
+			},
+			...(deps.userTasks
+				? {
+						getUserTasks: () => deps.userTasks?.snapshot() ?? [],
+						onAddUserTask: (title: string) => void deps.userTasks?.add(title),
+						onHandUserTask: (id: string) => {
+							const task = deps.userTasks?.hand(id, deps.getSessionId?.() ?? undefined);
+							if (!task) throw new Error("operator task inbox is unavailable");
+							deps.submitChat(formatUserTaskHandoff(task));
+						},
+						onDoneUserTask: (id: string) => void deps.userTasks?.done(id),
+						onDropUserTask: (id: string) => void deps.userTasks?.drop(id),
+					}
+				: {}),
+			onOpenArtifact: (path: string) => openView(`workspace:${path}`),
+			requestRender: deps.requestRender,
+			workspace: deps.getSessionMeta()?.cwd ?? process.cwd(),
+		});
+		deps.requestRender();
+	};
+
+	const openDecisions = (): void => {
+		if (deps.transitions.state !== "closed") return;
+		deps.transitions.state = "decisions";
+		deps.transitions.handle = openDecisionsOverlayFactory(deps.tui, () => deps.getDecisionBoard?.() ?? [], {
+			onSupersede: (selection) => {
+				if (!deps.supersedeDecision) throw new Error("decision board is unavailable in this session");
+				deps.supersedeDecision(selection.interviewId, selection.key);
+			},
+			onCorrection: (selection, correction) => {
+				if (!deps.supersedeDecision) throw new Error("decision board is unavailable in this session");
+				deps.supersedeDecision(selection.interviewId, selection.key, correction);
+				deps.closeOverlay();
+				deps.submitChat(formatDecisionCorrectionTurn(selection, correction));
+			},
+			onClose: deps.closeOverlay,
 		});
 		deps.requestRender();
 	};
@@ -210,6 +266,7 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		openContextReset,
 		toggleFooter,
 		openTasks,
+		openDecisions,
 		openMemory,
 		openView,
 		toggleDispatchBoard,

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

@@ -10,6 +10,7 @@ export type OverlayState =
 	| "context-view"
 	| "context-reset"
 	| "tasks"
+	| "decisions"
 	| "memory"
 	| "view"
 	| "model"
@@ -158,6 +159,7 @@ export function routeOverlayKey(
 	if (overlayState === "closed") return false;
 	if (
 		(overlayState === "dispatch-board" && matches(data, "clio.dispatchBoard.toggle")) ||
+		(overlayState === "tasks" && matches(data, "clio.tasks.open")) ||
 		(overlayState === "tree" && matches(data, "clio.session.tree")) ||
 		(overlayState === "model" && matches(data, "clio.model.select")) ||
 		(overlayState === "help" && matches(data, "clio.leader"))
@@ -180,6 +182,7 @@ export function routeOverlayKey(
 	}
 	if (overlayState === "context-reset") return false;
 	if (overlayState === "tasks") return false;
+	if (overlayState === "decisions") return false;
 	if (overlayState === "memory") return false;
 	if (overlayState === "view") return false;
 	if (overlayState === "model") return routeModelOverlayKey(data, deps);

package/src/interactive/overlay-lifecycle.ts

@@ -33,6 +33,8 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "getSessionId"
 	| "getSettings"
 	| "getTaskBoard"
+	| "userTasks"
+	| "getDecisionBoard"
 	| "getTaskMemoryStatus"
 	| "interop"
 	| "observability"
@@ -46,6 +48,7 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "resources"
 	| "session"
 	| "stateDir"
+	| "supersedeDecision"
 	| "toolRegistry"
 	| "writeSettings"
 >;
@@ -94,6 +97,7 @@ export interface OverlayLifecycleRuntimeDeps {
 	openContextOverlay?: typeof import("./context-overlay.js").openContextOverlay;
 	openContextResetOverlay?: typeof import("./overlays/context-reset.js").openContextResetOverlay;
 	openTasksOverlay?: typeof import("./tasks-overlay.js").openTasksOverlay;
+	openDecisionsOverlay?: typeof import("./overlays/decisions.js").openDecisionsOverlay;
 	openMemoryOverlay?: typeof import("./memory-overlay.js").openMemoryOverlay;
 	openViewOverlay?: typeof import("./view/view-overlay.js").openViewOverlay;
 	openHelpOverlay?: typeof import("./overlays/help-reference.js").openHelpOverlay;
@@ -118,6 +122,7 @@ export interface OverlayLifecycleController {
 	openContextResetOverlayState(): void;
 	toggleFooterDashboardState(): void;
 	openTasksOverlayState(): void;
+	openDecisionsOverlayState(): void;
 	openMemoryOverlayState(): void;
 	openViewOverlayState(initialFilter?: string): void;
 	openModelOverlayState(): void;
@@ -169,6 +174,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		openContextOverlay: openContextOverlayFactory,
 		openContextResetOverlay: openContextResetOverlayFactory,
 		openTasksOverlay: openTasksOverlayFactory,
+		openDecisionsOverlay: openDecisionsOverlayFactory,
 		openMemoryOverlay: openMemoryOverlayFactory,
 		openViewOverlay: openViewOverlayFactory,
 		openHelpOverlay: openHelpOverlayFactory,
@@ -334,6 +340,10 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		renderTaskIsland: () => interactiveTickers.renderTaskIsland(),
 		requestRender: () => tui.requestRender(),
 		...(deps.app.getTaskBoard ? { getTaskBoard: deps.app.getTaskBoard } : {}),
+		...(deps.app.userTasks ? { userTasks: deps.app.userTasks } : {}),
+		...(deps.app.getDecisionBoard ? { getDecisionBoard: deps.app.getDecisionBoard } : {}),
+		...(deps.app.supersedeDecision ? { supersedeDecision: deps.app.supersedeDecision } : {}),
+		submitChat: (text) => deps.getSlashContext().submitChat(text),
 		...(deps.app.getTaskMemoryStatus ? { getTaskMemoryStatus: deps.app.getTaskMemoryStatus } : {}),
 		dataDir: deps.app.dataDir,
 		notify,
@@ -350,6 +360,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(openContextOverlayFactory ? { openContextOverlay: openContextOverlayFactory } : {}),
 		...(openContextResetOverlayFactory ? { openContextResetOverlay: openContextResetOverlayFactory } : {}),
 		...(openTasksOverlayFactory ? { openTasksOverlay: openTasksOverlayFactory } : {}),
+		...(openDecisionsOverlayFactory ? { openDecisionsOverlay: openDecisionsOverlayFactory } : {}),
 		...(openMemoryOverlayFactory ? { openMemoryOverlay: openMemoryOverlayFactory } : {}),
 		...(openViewOverlayFactory ? { openViewOverlay: openViewOverlayFactory } : {}),
 	});
@@ -362,6 +373,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 	const openContextResetOverlayState = overlayGeneralOpeners.openContextReset;
 	const toggleFooterDashboardState = overlayGeneralOpeners.toggleFooter;
 	const openTasksOverlayState = overlayGeneralOpeners.openTasks;
+	const openDecisionsOverlayState = overlayGeneralOpeners.openDecisions;
 	const openMemoryOverlayState = overlayGeneralOpeners.openMemory;
 	const openViewOverlayState = overlayGeneralOpeners.openView;
 	const toggleDispatchBoardOverlay = overlayGeneralOpeners.toggleDispatchBoard;
@@ -380,6 +392,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		openContextResetOverlayState,
 		toggleFooterDashboardState,
 		openTasksOverlayState,
+		openDecisionsOverlayState,
 		openMemoryOverlayState,
 		openViewOverlayState,
 		openModelOverlayState: overlayModelSelectors.openModelOverlayState,

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

@@ -192,6 +192,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 	const unsubscribePermission =
 		deps.toolRegistry?.onPermissionRequired((call, decision, meta) => {
 			const autonomy = deps.getAutonomy();
+			const view = mainApprovalRequestView(call, decision, meta, autonomy, deps.toolRegistry?.parkedCount());
 			// The dialog states the tool, the target, the action class, the axis
 			// that asked, and the keys that answer it. While it is on screen the
 			// notice repeats all of that one line above the transcript, so it is
@@ -207,13 +208,13 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 					type: "tool_approval_state",
 					toolCallId: meta.toolCallId,
 					state: "awaiting-approval",
+					view,
 				});
 			}
 			if (deps.getOverlayState() !== "closed") {
 				announceParked();
 				return;
 			}
-			const view = mainApprovalRequestView(call, decision, meta, autonomy, deps.toolRegistry?.parkedCount());
 			if (!deps.openPermissionOverlay(view)) {
 				announceParked();
 				return;

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

@@ -12,6 +12,7 @@ import { openMessagePickerOverlay } from "./overlays/message-picker.js";
 import { openSessionOverlay } from "./overlays/session-selector.js";
 import { openTreeOverlay } from "./overlays/tree-selector.js";
 import { lastTurnSummaryFromLedger } from "./session-last-turn.js";
+import { settleChatBeforeSessionSwitch } from "./session-switch-settlement.js";
 import { reseedSessionUsageFromLedger, type SessionUsageSink } from "./session-usage-reseed.js";
 import type { SlashCommandContext } from "./slash-commands.js";
 import type { TurnSummary } from "./status/index.js";
@@ -20,7 +21,7 @@ export interface OverlaySessionLifecycleDeps {
 	tui: TUI;
 	transitions: OverlayTransitions;
 	session?: SessionContract;
-	chat: Pick<ChatLoop, "resetForSession">;
+	chat: Pick<ChatLoop, "cancel" | "isStreaming" | "resetForSession" | "whenSettled">;
 	chatPanel: ChatPanel;
 	/** The one transcript reset: the panel plus every view folded alongside it. */
 	resetTranscript(): void;
@@ -113,20 +114,58 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		deps.transitions.state = "resume";
 		deps.transitions.handle = openResumeOverlay(deps.tui, {
 			session,
-			onResume: (sessionId) => {
+			onResume: async (sessionId) => {
+				const settlement = settleChatBeforeSessionSwitch(deps.chat);
+				if (settlement) await settlement;
 				deps.onResumeSession?.(sessionId);
+				// onResumeSession (wired to session.resume) catches and stderr-logs
+				// its own failure rather than throwing here, so this is the only
+				// signal available: a successful switch always leaves session.current()
+				// pointing at the requested id. Without this check, a failed switch
+				// still replayed the target's transcript and moved the chat leaf to
+				// it while session.current() stayed on the session the operator
+				// started on (issue #93), so the next message was appended with a
+				// parent turn from a session that was never actually opened.
+				if (session.current()?.id !== sessionId) {
+					emitCommandNotice(
+						deps.getSlashNotice(),
+						"error",
+						"resume",
+						`could not switch to that session; staying on ${preResumeSessionId ?? "no session"}`,
+					);
+					deps.refreshFooter();
+					deps.requestRender();
+					return;
+				}
 				try {
 					const turns = deps.readStructuredEntries(sessionId);
-					deps.resetTranscript();
-					rehydrateChatPanelFromTurns(deps.chatPanel, turns);
-					const replayMessages = buildReplayAgentMessagesFromTurns(turns);
+					// The leaf is read before the transcript is rebuilt because it is
+					// what the rebuild has to follow. resolveLeafOnOpen prefers a
+					// persisted `/tree` pin over the newest turn, so a session resumed
+					// on a pin extends from the pinned turn while the file still holds
+					// the abandoned branch after it. Replaying the file unfiltered
+					// rendered those abandoned turns as ordinary history above the
+					// prompt, disagreeing with the branch the next message parents onto
+					// and with the tip `/tree` marks (issue #107). The `/tree` switch
+					// path below has always scoped its replay to the selected turn;
+					// this is the same active-path filter, rooted at the leaf resume
+					// actually landed on.
 					const leafTurnId = session.tree(sessionId).leafId;
+					// activeLeafTurnId, not uptoTurnId: this is a live branch about to
+					// be extended, so sidecars anchored to a path turn but written
+					// after it (a compaction summary covering the leaf, above all)
+					// still belong on screen. uptoTurnId is the historical-truncation
+					// variant `/tree` uses.
+					const replayOptions = leafTurnId ? { activeLeafTurnId: leafTurnId } : {};
+					deps.resetTranscript();
+					rehydrateChatPanelFromTurns(deps.chatPanel, turns, replayOptions);
+					const replayMessages = buildReplayAgentMessagesFromTurns(turns, replayOptions);
 					deps.chat.resetForSession(leafTurnId, replayMessages);
 					rescopeToBranch(session, turns, leafTurnId);
 				} catch (error) {
 					deps.stderr(`[/resume] transcript replay failed: ${error instanceof Error ? error.message : String(error)}\n`);
 				}
-				if (session.current()?.id === sessionId && sessionId !== preResumeSessionId) {
+				if (sessionId !== preResumeSessionId) {
 					deps.announceTaskMemorySeedOffer();
 				}
 				deps.refreshFooter();
@@ -160,7 +199,9 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		deps.transitions.state = "tree";
 		deps.transitions.handle = openTreeSelector(deps.tui, {
 			session,
-			onSwitchTurn: (turnId) => {
+			onSwitchTurn: async (turnId) => {
+				const settlement = settleChatBeforeSessionSwitch(deps.chat);
+				if (settlement) await settlement;
 				try {
 					session.switchTurn(turnId);
 					const sessionId = session.current()?.id ?? null;
@@ -195,7 +236,8 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 			return;
 		}
 		const session = deps.session;
-		if (session.current() === null) {
+		const preForkSessionId = session.current()?.id ?? null;
+		if (preForkSessionId === null) {
 			emitCommandNotice(
 				deps.getSlashNotice(),
 				"warn",
@@ -207,14 +249,29 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		deps.transitions.state = "message-picker";
 		deps.transitions.handle = openMessagePicker(deps.tui, {
 			session,
-			onFork: (parentTurnId) => {
+			onFork: async (parentTurnId) => {
+				const settlement = settleChatBeforeSessionSwitch(deps.chat);
+				if (settlement) await settlement;
 				try {
 					if (deps.onForkSession) deps.onForkSession(parentTurnId);
 					else session.fork(parentTurnId);
-					deps.resetTranscript();
 					const forkedSessionId = session.current()?.id ?? null;
-					if (forkedSessionId) replayFork(forkedSessionId, parentTurnId, session);
-					else deps.chat.resetForSession(null);
+					// A successful fork always creates a fresh session id; landing back
+					// on the id fork started from means the fork threw and
+					// onForkSession swallowed it (orchestrator.ts stderr-logs there).
+					// Do not replay: session.current() did not move (issue #93's
+					// extension.ts/fork.ts ordering fix keeps it on the session the
+					// operator started on instead of orphaning it), so there is
+					// nothing new to replay and doing so anyway just re-renders the
+					// same transcript while hiding that the fork failed.
+					if (forkedSessionId === null || forkedSessionId === preForkSessionId) {
+						emitCommandNotice(deps.getSlashNotice(), "error", "fork", `fork failed; staying on ${preForkSessionId}`);
+						deps.refreshFooter();
+						deps.requestRender();
+						return;
+					}
+					deps.resetTranscript();
+					replayFork(forkedSessionId, parentTurnId, session);
 				} catch (error) {
 					deps.stderr(`[/fork] fork failed: ${error instanceof Error ? error.message : String(error)}\n`);
 				}

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),