@iowarp/clio-coder 0.3.4 → 0.3.7

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

@@ -1,3 +1,8 @@
+import {
+	classifyDecisionPresentation,
+	type DecisionPresentation,
+	decisionFactsForAnswer,
+} from "../../domains/safety/decision-presentation.js";
 import {
 	type Component,
 	Input,
@@ -18,16 +23,14 @@ import { type ClioToken, clioTheme, dotSep, GLYPH, screenTitle } from "../theme/
 import { nextContentScrollOffset, type ViewScrollAction } from "../view/view-overlay.js";
 
 /**
- * The border and title token while a decision is pending.
- *
- * Orange is the token that means Clio is acting, and a prompt holding the
- * keyboard is the moment the operator has to act with it. Everything
- * informational keeps the teal frame, so the one border that is not teal is the
- * one asking for an answer. All three surfaces carry it: what changes between
- * them is the size and the place, never the signal.
+ * The default title and border token for a local conversational answer.
+ * Outward and other consequence tiers replace both values with their typed
+ * presentation. All ask_user surfaces carry the same classified signal.
  */
-export const ASK_USER_DECISION_TONE: ClioToken = "action";
-export const ASK_USER_DECISION_TITLE = "Decision required";
+const DEFAULT_ASK_USER_PRESENTATION = classifyDecisionPresentation(decisionFactsForAnswer("local"));
+
+export const ASK_USER_DECISION_TONE: ClioToken = DEFAULT_ASK_USER_PRESENTATION.semanticToken;
+export const ASK_USER_DECISION_TITLE = DEFAULT_ASK_USER_PRESENTATION.title;
 export const ASK_USER_WAITING_TITLE = "Ask User";
 
 /**
@@ -73,7 +76,7 @@ interface AskUserSurfaceGeometry {
  * `ASK_USER_FRAME_AND_MARGIN_ROWS` counts alongside the two border rows.
  */
 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 } },
+	compact: { width: 68, maxInnerRows: 14, anchor: "bottom-center", margin: { top: 1, right: 2, bottom: 1, left: 2 } },
 	panel: { width: 88, maxInnerRows: 18, 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
@@ -111,7 +114,7 @@ export interface OpenAskUserOverlayDeps {
 }
 
 export interface AskUserOverlaySession extends OverlayHandle {
-	ask(questions: ReadonlyArray<AskUserQuestion>): Promise<AskUserResult>;
+	ask(questions: ReadonlyArray<AskUserQuestion>, presentation?: DecisionPresentation): Promise<AskUserResult>;
 	cancel(): void;
 	close(): void;
 	isWaiting(): boolean;
@@ -242,16 +245,21 @@ class AskUserOverlayView implements Component {
 	private contentRegionHeight = 1;
 	/** Rows the scroll region wanted on the last render. */
 	private contentTotalRows = 0;
+	private presentation: DecisionPresentation = DEFAULT_ASK_USER_PRESENTATION;
 
 	constructor(private readonly deps: AskUserOverlayViewDeps) {}
 
-	begin(questions: ReadonlyArray<AskUserQuestion>): Promise<AskUserResult> {
+	begin(
+		questions: ReadonlyArray<AskUserQuestion>,
+		presentation: DecisionPresentation = DEFAULT_ASK_USER_PRESENTATION,
+	): Promise<AskUserResult> {
 		if (this.phase === "closed") return Promise.resolve(cancelledAskUserResult());
 		if (this.resolveCurrent) return Promise.resolve(cancelledAskUserResult());
 		this.phase = "asking";
 		this.index = 0;
 		this.status = "";
 		this.questions = [...questions];
+		this.presentation = presentation;
 		this.states = this.questions.map((question) => createQuestionState(question));
 		this.list = null;
 		this.input = null;
@@ -288,6 +296,14 @@ class AskUserOverlayView implements Component {
 		return this.surface;
 	}
 
+	decisionTitle(): string {
+		return this.presentation.title;
+	}
+
+	decisionTone(): ClioToken {
+		return this.presentation.semanticToken;
+	}
+
 	invalidate(): void {
 		this.list?.invalidate();
 		this.input?.invalidate();
@@ -358,10 +374,17 @@ class AskUserOverlayView implements Component {
 		const statusLines = this.status.length > 0 ? ["", fitLine(clioTheme().fg("dim", this.status), safeWidth)] : [];
 		const headerLine = this.renderQuestionHeader(question, safeWidth);
 		const headerLines = headerLine.length > 0 ? [headerLine] : [];
-		const spent = headerLines.length + statusLines.length + 1 + controlLines.length;
-		const questionLines = wrapTextWithAnsi(question.question, safeWidth).slice(0, Math.max(1, maxRows - spent));
-
-		return [...headerLines, ...questionLines, ...statusLines, "", ...controlLines].slice(0, maxRows);
+		const bottom = [...statusLines, "", ...controlLines];
+		const topBudget = Math.max(1, maxRows - bottom.length);
+		const contextLines = this.renderDecisionContext(safeWidth);
+		const top = [
+			contextLines[0] ?? "",
+			...headerLines,
+			...wrapTextWithAnsi(question.question, safeWidth),
+			...contextLines.slice(1),
+		].slice(0, topBudget);
+
+		return [...top, ...bottom].slice(0, maxRows);
 	}
 
 	/**
@@ -380,7 +403,12 @@ class AskUserOverlayView implements Component {
 		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)];
+		const content = [
+			...wrapTextWithAnsi(question.question, width),
+			"",
+			...this.renderDecisionContext(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
@@ -460,36 +488,52 @@ class AskUserOverlayView implements Component {
 		const question = this.currentQuestion();
 		const state = this.currentState();
 		if (!question || !state) return buildHint([]);
+		const recordAnswer =
+			this.presentation.requiredActions.find((action) => action.id === "record-answer")?.label.toLowerCase() ??
+			"record answer";
 		if (state.mode === "text") {
 			return this.questions.length > 1
 				? this.withScrollHint([
-						{ key: "Enter", verb: "submit" },
+						{ key: "Enter", verb: recordAnswer },
 						{ key: "Alt+Left/Right", verb: "question" },
 					])
-				: this.withScrollHint([{ key: "Enter", verb: "submit" }]);
+				: this.withScrollHint([{ key: "Enter", verb: recordAnswer }]);
 		}
-		// `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
-		// product's one word for the way out, since it closes the prompt and the
-		// interview together.
+		// 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.
 		if (question.multi_select === true) {
 			return this.questions.length > 1
 				? this.withScrollHint([
 						{ key: "Left/Right", verb: "question" },
 						{ key: "Space", verb: "toggle" },
-						{ key: "Enter", verb: "accept" },
+						{ key: "Enter", verb: recordAnswer },
 					])
 				: this.withScrollHint([
 						{ key: "Space", verb: "toggle" },
-						{ key: "Enter", verb: "accept" },
+						{ key: "Enter", verb: recordAnswer },
 					]);
 		}
 		return this.questions.length > 1
 			? this.withScrollHint([
 					{ key: "Left/Right", verb: "question" },
-					{ key: "Enter", verb: "accept" },
+					{ key: "Enter", verb: recordAnswer },
 				])
-			: this.withScrollHint([{ key: "Enter", verb: "accept" }]);
+			: this.withScrollHint([{ key: "Enter", verb: recordAnswer }]);
+	}
+
+	private renderDecisionContext(width: number): string[] {
+		const theme = clioTheme();
+		const tier = theme.style(this.presentation.semanticToken, this.presentation.tierLabel, { bold: true });
+		const requested = theme.fg("dim", `requested by ${this.presentation.requestedByCopy}`);
+		const effect = `${theme.fg("dim", "Effect:")} ${theme.fg("muted", this.presentation.authorizationCopy)}`;
+		return [
+			fitLine(`${tier}${dotSep(theme)}${requested}`, width),
+			...wrapTextWithAnsi(effect, width).map((line) => fitLine(line, width)),
+			...wrapTextWithAnsi(theme.fg("muted", this.presentation.reversibilityCopy), width).map((line) =>
+				fitLine(line, width),
+			),
+		];
 	}
 
 	/**
@@ -1012,8 +1056,8 @@ 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,
-			title: () => (view.isDecisionPending() ? ASK_USER_DECISION_TITLE : ASK_USER_WAITING_TITLE),
-			tone: () => (view.isDecisionPending() ? ASK_USER_DECISION_TONE : undefined),
+			title: () => (view.isDecisionPending() ? view.decisionTitle() : ASK_USER_WAITING_TITLE),
+			tone: () => (view.isDecisionPending() ? view.decisionTone() : undefined),
 			footerHint: () => view.footerHint(),
 		});
 		mounted = surface;
@@ -1034,7 +1078,7 @@ export function openAskUserOverlay(tui: TUI, deps: OpenAskUserOverlayDeps): AskU
 		focus: () => handle?.focus(),
 		unfocus: (options) => (options ? handle?.unfocus(options) : handle?.unfocus()),
 		isFocused: () => handle?.isFocused() ?? false,
-		ask: (questions) => view.begin(questions),
+		ask: (questions, presentation) => view.begin(questions, presentation),
 		cancel: () => view.cancel(),
 		close,
 		hide: close,

package/src/interactive/overlays/decisions.ts

@@ -1,3 +1,4 @@
+import { classifyDecisionPresentation, decisionFactsForAnswer } from "../../domains/safety/decision-presentation.js";
 import type { DecisionLedgerEntry, DecisionRecord } from "../../domains/session/entries.js";
 import {
 	type Component,
@@ -73,10 +74,11 @@ function selectableRows(interviews: ReadonlyArray<DecisionLedgerEntry>): Selecta
 
 function interviewHeader(interview: DecisionLedgerEntry, width: number, now: number): string[] {
 	const theme = clioTheme();
+	const presentation = classifyDecisionPresentation(decisionFactsForAnswer(interview.exposure ?? "local"));
 	const rounds = `${interview.roundCount} round${interview.roundCount === 1 ? "" : "s"}`;
 	const status =
 		interview.interviewStatus === "complete" ? theme.fg("success", "complete") : theme.fg("warning", "cancelled");
-	const heading = `${theme.fg("accent", relativeTime(interview.endedAt, now))}${theme.fg("dim", " · ")}${theme.fg("muted", rounds)}${theme.fg("dim", " · ")}${status}`;
+	const heading = `${theme.style(presentation.semanticToken, presentation.tierLabel, { bold: true })}${theme.fg("dim", " · ")}${theme.fg("accent", relativeTime(interview.endedAt, now))}${theme.fg("dim", " · ")}${theme.fg("muted", rounds)}${theme.fg("dim", " · ")}${status}`;
 	const lines = [fitLine(heading, width)];
 	if (interview.summary) {
 		lines.push(...wrapTextWithAnsi(theme.fg("dim", interview.summary), width).map((line) => fitLine(line, width)));

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

@@ -0,0 +1,208 @@
+/**
+ * `/fleet run <name>` approval: the whole plan, before anything dispatches.
+ *
+ * The operator reads the compiled plan here and decides. Enter accepts and the
+ * run starts; Esc cancels and nothing is dispatched, nothing is written, and no
+ * ledger row exists. A contract that failed preflight opens the same overlay
+ * with its diagnostics and no accept key, so the only way out of a broken plan
+ * is to leave it.
+ *
+ * The body is a pure function of the projection so the layout is testable
+ * without a TUI.
+ */
+
+import {
+	type Component,
+	isKeyRelease,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "../../engine/tui.js";
+import type { FleetRunPreview, FleetRunPreviewStep } from "../fleet-run-preview.js";
+import { buildResponsiveHint, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, rule } from "../theme/index.js";
+
+export const FLEET_RUN_APPROVAL_OVERLAY_TITLE = "Fleet run approval";
+
+const FLEET_RUN_APPROVAL_MIN_WIDTH = 48;
+const FLEET_RUN_APPROVAL_MAX_WIDTH = 110;
+/** Rows of plan shown at once. Anything longer scrolls. */
+export const FLEET_RUN_APPROVAL_VISIBLE_ROWS = 22;
+
+function fleetRunApprovalOverlayWidth(columns: number): number {
+	return Math.max(FLEET_RUN_APPROVAL_MIN_WIDTH, Math.min(FLEET_RUN_APPROVAL_MAX_WIDTH, columns - 4));
+}
+
+/** What the overlay renders: an accepted-shaped plan or the reasons there is none. */
+export type FleetRunApprovalSubject =
+	| { ok: true; preview: FleetRunPreview }
+	| { ok: false; name: string; diagnostics: ReadonlyArray<string> };
+
+export interface OpenFleetRunApprovalOverlayOptions {
+	subject: FleetRunApprovalSubject;
+	/** Live terminal width, so the box tracks the window it opened in. */
+	columns: number;
+	/** Enter: dispatch this exact plan. Never called for a failed preflight. */
+	onAccept: () => void;
+	/** Esc: nothing is dispatched and nothing is written. */
+	onCancel: () => void;
+}
+
+/** The declared boundary as one phrase: an empty allowlist is a claim, not an absence. */
+export function formatWriteBoundary(writes: ReadonlyArray<string> | undefined): string {
+	if (writes === undefined) return "writes unenforced";
+	if (writes.length === 0) return "writes nothing";
+	return `writes ${writes.join(", ")}`;
+}
+
+/** One step as its facts: kind, who runs it, where, its scope, and its boundary. */
+export function formatFleetRunPreviewStep(step: FleetRunPreviewStep): string {
+	const loop = step.loop === undefined ? "" : ` (${step.loop.loopId} ${step.loop.role} ${step.loop.attempt})`;
+	if (step.kind === "code") {
+		const gate = step.gate === undefined ? "" : ` · gate path ${step.gate.path}`;
+		return `code ${step.stepId}${loop} · command ${step.commandId ?? "?"}${gate} · ${step.scope} · ${formatWriteBoundary(step.writes)}`;
+	}
+	const route = step.route === undefined ? "route unresolved" : `${step.route.targetId} ▸ ${step.route.wireModelId}`;
+	const node = step.route === undefined ? "" : ` · node ${step.route.nodeId}`;
+	const declaredRoute =
+		step.target !== undefined
+			? ` · target ${step.target}`
+			: step.profile !== undefined
+				? ` · profile ${step.profile}`
+				: "";
+	const gate =
+		step.gate !== undefined
+			? ` · gate path ${step.gate.path} · run ${"commandId" in step.gate ? step.gate.commandId : "?"} · baseline ${"commandId" in step.gate ? step.gate.commandId : "?"}`
+			: "";
+	const dynamicPlan =
+		step.plan === undefined
+			? ""
+			: ` · roster ${step.plan.roster.join(", ")} · maxTasks ${step.plan.maxTasks}${step.plan.proposals ? " · proposals" : ""}`;
+	return `agent ${step.stepId}${loop} · ${step.agentId ?? "?"} · ${route}${node}${declaredRoute}${gate}${dynamicPlan} · ${step.scope} · ${formatWriteBoundary(step.writes)}`;
+}
+
+function formatBudgetLine(preview: FleetRunPreview): string {
+	const contract =
+		preview.budget.contractUsd === null
+			? "contract declares no ceiling"
+			: `contract ceiling $${preview.budget.contractUsd.toFixed(2)}`;
+	return `budget: admitted under $${preview.budget.ceilingUsd.toFixed(2)} session ceiling, $${preview.budget.currentUsd.toFixed(4)} spent, ${contract}`;
+}
+
+/**
+ * Render the body. Waves in order, each step with its facts, then the argv a
+ * code step will actually run, and last the budget the run is admitted under.
+ */
+export function formatFleetRunApprovalBody(subject: FleetRunApprovalSubject, width: number, scroll: number): string[] {
+	const theme = clioTheme();
+	const contentWidth = Math.max(1, Math.floor(width));
+	const rows: string[] = [];
+
+	if (!subject.ok) {
+		rows.push(theme.fg("error", `${subject.name}: preflight failed; nothing will be dispatched`));
+		rows.push(rule(theme, contentWidth));
+		for (const diagnostic of subject.diagnostics) {
+			for (const line of diagnostic.split("\n")) {
+				for (const wrapped of wrapTextWithAnsi(theme.fg("muted", line), contentWidth)) rows.push(wrapped);
+			}
+		}
+	} else {
+		const { preview } = subject;
+		rows.push(theme.fg("dim", `${preview.name} · plan ${preview.planHash.slice(0, 12)}`));
+		rows.push(rule(theme, contentWidth));
+		for (const wave of preview.waves) {
+			rows.push(theme.fg("accent", `wave ${wave.index}`));
+			for (const step of wave.steps) {
+				for (const line of wrapTextWithAnsi(theme.fg("muted", `  ${formatFleetRunPreviewStep(step)}`), contentWidth)) {
+					rows.push(line);
+				}
+				if (step.argv !== undefined) {
+					rows.push(theme.fg("dim", truncateToWidth(`    argv ${step.argv.join(" ")}`, contentWidth, "…", false)));
+				}
+			}
+		}
+		rows.push(rule(theme, contentWidth));
+		for (const line of wrapTextWithAnsi(theme.fg("info", formatBudgetLine(preview)), contentWidth)) rows.push(line);
+	}
+
+	const maxScroll = Math.max(0, rows.length - FLEET_RUN_APPROVAL_VISIBLE_ROWS);
+	const start = Math.max(0, Math.min(scroll, maxScroll));
+	const shown = rows.slice(start, start + FLEET_RUN_APPROVAL_VISIBLE_ROWS);
+	if (rows.length > FLEET_RUN_APPROVAL_VISIBLE_ROWS) {
+		shown.push(theme.fg("dim", `(${start + 1}-${start + shown.length} of ${rows.length} lines)`));
+	}
+	return shown;
+}
+
+class FleetRunApprovalBody implements Component {
+	scroll = 0;
+
+	constructor(private readonly subject: FleetRunApprovalSubject) {}
+
+	render(width: number): string[] {
+		return formatFleetRunApprovalBody(this.subject, width, this.scroll);
+	}
+
+	invalidate(): void {}
+}
+
+export function openFleetRunApprovalOverlay(tui: TUI, options: OpenFleetRunApprovalOverlayOptions): OverlayHandle {
+	const body = new FleetRunApprovalBody(options.subject);
+	const acceptable = options.subject.ok;
+	let settled = false;
+
+	const accept = (): void => {
+		if (settled || !acceptable) return;
+		settled = true;
+		options.onAccept();
+	};
+	const cancel = (): void => {
+		if (settled) return;
+		settled = true;
+		options.onCancel();
+	};
+
+	const focus = new FocusBox(body, {
+		// Keys are matched by name, never by raw bytes: under the kitty keyboard
+		// protocol Esc arrives as CSI 27 u, and a byte comparison against "\x1b"
+		// left the overlay unanswerable. Everything unmatched is swallowed.
+		onInput: (data: string): void => {
+			if (settled || isKeyRelease(data)) return;
+			if (matchesKey(data, "up")) {
+				body.scroll = Math.max(0, body.scroll - 1);
+				tui.requestRender();
+				return;
+			}
+			if (matchesKey(data, "down")) {
+				body.scroll += 1;
+				tui.requestRender();
+				return;
+			}
+			if (matchesKey(data, "enter")) {
+				accept();
+				return;
+			}
+			if (matchesKey(data, "escape")) cancel();
+		},
+	});
+
+	const handle = showClioOverlayFrame(tui, focus, {
+		anchor: "center",
+		width: fleetRunApprovalOverlayWidth(options.columns),
+		title: FLEET_RUN_APPROVAL_OVERLAY_TITLE,
+		footerHint: buildResponsiveHint(
+			[...(acceptable ? [{ key: "Enter", verb: "dispatch" }] : []), { key: "↑↓", verb: "scroll" }],
+			{ key: "Esc", verb: "cancel" },
+		),
+	});
+
+	return {
+		...handle,
+		hide(): void {
+			cancel();
+			handle.hide();
+		},
+	};
+}

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

@@ -0,0 +1,185 @@
+/**
+ * `/handoff` review: the document, before anything is written anywhere.
+ *
+ * The operator reads the rendered Markdown here and chooses. Enter accepts the
+ * document as it stands, `e` hands it to `$EDITOR` through the same external
+ * editor flow the composer uses and comes back with whatever was saved, and Esc
+ * cancels the whole handoff. Cancel is the important one: nothing has been
+ * written at the point this overlay opens, so leaving it costs the extraction
+ * round and nothing else.
+ */
+
+import {
+	type Component,
+	isKeyRelease,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	wrapTextWithAnsi,
+} from "../../engine/tui.js";
+import { buildResponsiveHint, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, rule } from "../theme/index.js";
+
+export const HANDOFF_REVIEW_OVERLAY_TITLE = "Handoff review";
+
+const HANDOFF_REVIEW_MIN_WIDTH = 44;
+const HANDOFF_REVIEW_MAX_WIDTH = 100;
+/** Rows of document shown at once. Anything longer scrolls. */
+export const HANDOFF_REVIEW_VISIBLE_ROWS = 20;
+
+export function handoffReviewOverlayWidth(columns: number): number {
+	return Math.max(HANDOFF_REVIEW_MIN_WIDTH, Math.min(HANDOFF_REVIEW_MAX_WIDTH, columns - 4));
+}
+
+export interface OpenHandoffReviewOverlayOptions {
+	document: string;
+	goal: string;
+	/** Live terminal width, so the box tracks the window it opened in. */
+	columns: number;
+	/**
+	 * Hand the current document to `$EDITOR` and return what came back, or null
+	 * when the edit was cancelled or no editor is configured. The caller owns
+	 * stopping and restarting the TUI around the child process.
+	 */
+	onEdit: (current: string) => string | null;
+	/** Enter: the operator accepts this exact text. */
+	onAccept: (document: string) => void;
+	/** Esc: the whole handoff is abandoned and nothing is written. */
+	onCancel: () => void;
+}
+
+export interface HandoffReviewOverlaySession extends OverlayHandle {
+	/** The document as it currently stands, including any external edit. */
+	document(): string;
+}
+
+/**
+ * Render the body. Pure so the layout is testable without a TUI: the goal, a
+ * rule, then the scrolled document window.
+ */
+export function formatHandoffReviewBody(goal: string, document: string, width: number, scroll: number): string[] {
+	const theme = clioTheme();
+	const contentWidth = Math.max(1, Math.floor(width));
+	const lines: string[] = [];
+	for (const line of wrapTextWithAnsi(theme.fg("dim", `goal: ${goal}`), contentWidth)) lines.push(line);
+	lines.push(rule(theme, contentWidth));
+
+	const wrapped: string[] = [];
+	for (const raw of document.split("\n")) {
+		if (raw.length === 0) {
+			wrapped.push("");
+			continue;
+		}
+		for (const line of wrapTextWithAnsi(theme.fg("muted", raw), contentWidth)) wrapped.push(line);
+	}
+	const maxScroll = Math.max(0, wrapped.length - HANDOFF_REVIEW_VISIBLE_ROWS);
+	const start = Math.max(0, Math.min(scroll, maxScroll));
+	const window = wrapped.slice(start, start + HANDOFF_REVIEW_VISIBLE_ROWS);
+	for (const line of window) lines.push(line);
+	if (wrapped.length > HANDOFF_REVIEW_VISIBLE_ROWS) {
+		lines.push(theme.fg("dim", `(${start + 1}-${start + window.length} of ${wrapped.length} lines)`));
+	}
+	return lines;
+}
+
+class HandoffReviewBody implements Component {
+	scroll = 0;
+
+	constructor(
+		private readonly goal: string,
+		private text: string,
+	) {}
+
+	setDocument(next: string): void {
+		this.text = next;
+		this.scroll = 0;
+	}
+
+	document(): string {
+		return this.text;
+	}
+
+	lineCount(): number {
+		return this.text.split("\n").length;
+	}
+
+	render(width: number): string[] {
+		return formatHandoffReviewBody(this.goal, this.text, width, this.scroll);
+	}
+
+	invalidate(): void {}
+}
+
+export function openHandoffReviewOverlay(
+	tui: TUI,
+	options: OpenHandoffReviewOverlayOptions,
+): HandoffReviewOverlaySession {
+	const body = new HandoffReviewBody(options.goal, options.document);
+	let settled = false;
+
+	const accept = (): void => {
+		if (settled) return;
+		settled = true;
+		options.onAccept(body.document());
+	};
+	const cancel = (): void => {
+		if (settled) return;
+		settled = true;
+		options.onCancel();
+	};
+
+	const focus = new FocusBox(body, {
+		// Keys are matched by name, never by raw bytes: under the kitty keyboard
+		// protocol Esc arrives as CSI 27 u, and a byte comparison against "\x1b"
+		// left the overlay unanswerable. Everything unmatched is swallowed.
+		onInput: (data: string): void => {
+			if (settled || isKeyRelease(data)) return;
+			if (matchesKey(data, "up")) {
+				body.scroll = Math.max(0, body.scroll - 1);
+				tui.requestRender();
+				return;
+			}
+			if (matchesKey(data, "down")) {
+				body.scroll = Math.min(body.lineCount(), body.scroll + 1);
+				tui.requestRender();
+				return;
+			}
+			if (matchesKey(data, "enter")) {
+				accept();
+				return;
+			}
+			if (matchesKey(data, "escape")) {
+				cancel();
+				return;
+			}
+			if (matchesKey(data, "e") || matchesKey(data, "shift+e")) {
+				const edited = options.onEdit(body.document());
+				if (edited !== null) body.setDocument(edited);
+				tui.requestRender(true);
+			}
+		},
+	});
+
+	const handle = showClioOverlayFrame(tui, focus, {
+		anchor: "center",
+		width: handoffReviewOverlayWidth(options.columns),
+		title: HANDOFF_REVIEW_OVERLAY_TITLE,
+		footerHint: buildResponsiveHint(
+			[
+				{ key: "Enter", verb: "accept" },
+				{ key: "e", verb: "edit" },
+				{ key: "↑↓", verb: "scroll" },
+			],
+			{ key: "Esc", verb: "cancel" },
+		),
+	});
+
+	return {
+		...handle,
+		document: () => body.document(),
+		hide(): void {
+			cancel();
+			handle.hide();
+		},
+	};
+}