@iowarp/clio-coder 0.3.6 → 0.3.8

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

@@ -1,14 +1,29 @@
 import { resolveSessionCwd } from "../domains/session/cwd-fallback.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
+import {
+	buildHandoffReadLedger,
+	HANDOFF_NOTE_CUSTOM_TYPE,
+	HANDOFF_SEED_CUSTOM_TYPE,
+	type HandoffNoteData,
+	type HandoffSeedData,
+	mergeHandoffDecisions,
+	parseHandoffExtraction,
+	renderHandoffDocument,
+	validateHandoffFiles,
+	validateHandoffGoal,
+} from "../domains/session/handoff.js";
 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 { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
+import { editTextExternally, resolveExternalEditor } from "./external-editor.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 { openHandoffReviewOverlay } from "./overlays/handoff-review.js";
 import { openMessagePickerOverlay } from "./overlays/message-picker.js";
 import { openSessionOverlay } from "./overlays/session-selector.js";
 import { openTreeOverlay } from "./overlays/tree-selector.js";
@@ -22,7 +37,7 @@ export interface OverlaySessionLifecycleDeps {
 	tui: TUI;
 	transitions: OverlayTransitions;
 	session?: SessionContract;
-	chat: Pick<ChatLoop, "cancel" | "isStreaming" | "resetForSession" | "whenSettled">;
+	chat: Pick<ChatLoop, "cancel" | "isStreaming" | "resetForSession" | "whenSettled" | "extractHandoff">;
 	chatPanel: ChatPanel;
 	/** The one transcript reset: the panel plus every view folded alongside it. */
 	resetTranscript(): void;
@@ -30,6 +45,18 @@ export interface OverlaySessionLifecycleDeps {
 	getSlashNotice(): SlashCommandContext["notice"];
 	onResumeSession?(sessionId: string): void;
 	onForkSession?(parentTurnId: string): void;
+	/**
+	 * Mint a fresh session, the same hook `/new` uses. `/handoff` needs the one
+	 * session-creation path the orchestrator owns rather than a second one.
+	 */
+	onNewSession?(): void;
+	/** The session's settled decision board, which wins over extracted decisions. */
+	getDecisionBoard?(): ReadonlyArray<DecisionLedgerEntry>;
+	/** Stop and restart the terminal around an external editor child process. */
+	suspendTerminal?<T>(run: () => T): T;
+	resolveEditor?: typeof resolveExternalEditor;
+	editExternally?: typeof editTextExternally;
+	openHandoffReviewOverlay?: typeof openHandoffReviewOverlay;
 	announceTaskMemorySeedOffer(): void;
 	/**
 	 * Running usage totals, reseeded whenever the session under them changes.
@@ -45,6 +72,8 @@ export interface OverlaySessionLifecycleDeps {
 	setLastTurnSummary?(summary: TurnSummary | null): void;
 	refreshFooter(): void;
 	requestRender(): void;
+	/** Live terminal width, so the handoff review box tracks the window. */
+	terminal?: { columns: number };
 	stderr(text: string): void;
 	notify(level: InteractiveNoticeLevel, text: string, key?: string): void;
 	openSessionOverlay?: typeof openSessionOverlay;
@@ -57,6 +86,8 @@ export interface OverlaySessionLifecycle {
 	openResume(): void;
 	openTree(): void;
 	openMessagePicker(): void;
+	/** `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoff(goal: string): void;
 }
 
 /**
@@ -327,5 +358,206 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		deps.requestRender();
 	}
 
-	return { openResume, openTree, openMessagePicker: openMessagePickerState };
+	/**
+	 * `/handoff <goal>`: carry this session's working state into a fresh one.
+	 *
+	 * A handoff is a session operation. It writes no memory promotion candidate,
+	 * touches no memory record, and never calls the task-memory bank; the only
+	 * things it writes are one seed entry plus replayed skill activations in the
+	 * new session and one terminal note in the old one, and it writes none of
+	 * them until the operator has accepted the document.
+	 */
+	function startHandoff(goal: string): void {
+		if (deps.transitions.state !== "closed") return;
+		const notice = deps.getSlashNotice();
+		const verdict = validateHandoffGoal(goal);
+		if (!verdict.ok) {
+			emitCommandNotice(notice, "warn", "handoff", verdict.reason);
+			return;
+		}
+		if (!deps.session) {
+			emitCommandNotice(notice, "error", "handoff", "session contract unavailable");
+			return;
+		}
+		if (!deps.onNewSession) {
+			emitCommandNotice(notice, "error", "handoff", "no session-creation path is wired in this session");
+			return;
+		}
+		// Refused, never queued. The document describes a session that has
+		// stopped; a turn still in flight is about to change what it would say.
+		if (deps.chat.isStreaming()) {
+			emitCommandNotice(
+				notice,
+				"warn",
+				"handoff",
+				"a turn is in flight; /handoff cannot summarize a session that is still moving",
+			);
+			return;
+		}
+		const session = deps.session;
+		const fromSessionId = session.current()?.id ?? null;
+		if (fromSessionId === null) {
+			emitCommandNotice(notice, "warn", "handoff", "no current session to hand off; start one with /new or /resume");
+			return;
+		}
+		void runHandoffExtraction(session, fromSessionId, verdict.goal);
+	}
+
+	async function runHandoffExtraction(session: SessionContract, fromSessionId: string, goal: string): Promise<void> {
+		const notice = deps.getSlashNotice();
+		const outcome = await deps.chat.extractHandoff(goal);
+		if (outcome.status !== "answered") {
+			const reason = outcome.status === "aborted" ? "the extraction round was cancelled" : outcome.reason;
+			emitCommandNotice(notice, outcome.status === "failed" ? "error" : "warn", "handoff", reason);
+			return;
+		}
+		const parsed = parseHandoffExtraction(outcome.text);
+		if (!parsed.ok) {
+			emitCommandNotice(notice, "error", "handoff", parsed.reason);
+			return;
+		}
+		const meta = session.current();
+		const cwd = typeof meta?.cwd === "string" && meta.cwd.length > 0 ? meta.cwd : null;
+		const entries = deps.readStructuredEntries(fromSessionId);
+		// The ledger is what this session's own tool calls touched, folded through
+		// the active path so an abandoned `/tree` branch is not evidence.
+		const ledger = buildHandoffReadLedger(entries, { cwd, leafTurnId: meta?.pinnedLeafTurnId ?? null });
+		const files = validateHandoffFiles(parsed.result.extraction.files, ledger, cwd);
+		const decisions = mergeHandoffDecisions(parsed.result.extraction.decisions, deps.getDecisionBoard?.() ?? []);
+		const document = renderHandoffDocument({
+			goal,
+			fromSessionId,
+			decisions,
+			facts: parsed.result.extraction.facts,
+			files: files.kept,
+			droppedFiles: files.dropped,
+			commands: parsed.result.extraction.commands,
+			openQuestions: parsed.result.extraction.openQuestions,
+			truncations: parsed.result.truncations,
+		});
+		openHandoffReview(session, fromSessionId, goal, document);
+	}
+
+	/** Hand the document to `$EDITOR`, or say why it could not go. */
+	function editHandoffDocument(current: string): string | null {
+		const resolve = deps.resolveEditor ?? resolveExternalEditor;
+		const edit = deps.editExternally ?? editTextExternally;
+		const command = resolve();
+		if (!command) {
+			deps.notify("warning", "handoff: no external editor configured; set VISUAL or EDITOR", "handoff:no-editor");
+			return null;
+		}
+		const suspend = deps.suspendTerminal ?? (<T>(run: () => T): T => run());
+		const result = suspend(() => edit(current, command));
+		if (result.ok) return result.text ?? current;
+		if (result.error) deps.notify("warning", `handoff: ${result.error}`, "handoff:editor-failed");
+		return null;
+	}
+
+	function openHandoffReview(session: SessionContract, fromSessionId: string, goal: string, document: string): void {
+		if (deps.transitions.state !== "closed") return;
+		const openReview = deps.openHandoffReviewOverlay ?? openHandoffReviewOverlay;
+		deps.transitions.state = "handoff-review";
+		deps.transitions.handle = openReview(deps.tui, {
+			document,
+			goal,
+			columns: deps.terminal?.columns ?? 80,
+			onEdit: editHandoffDocument,
+			onAccept: (reviewed) => {
+				deps.transitions.close();
+				const text = reviewed.trim();
+				if (text.length === 0) {
+					deps.notify("warning", "handoff: the reviewed document was empty; nothing was written", "handoff:empty");
+					return;
+				}
+				seedHandoffSession(session, fromSessionId, goal, text);
+			},
+			// Esc. Nothing has been written yet, so cancel really is free. The
+			// overlay settles itself on cancel and answers no further key, so the
+			// transition has to close here or the review stays on screen inert.
+			onCancel: () => {
+				deps.transitions.close();
+				deps.notify("info", "handoff cancelled; nothing was written", "handoff:cancelled");
+			},
+		});
+		deps.requestRender();
+	}
+
+	/**
+	 * Mint the successor session and open it on the reviewed document.
+	 *
+	 * Order matters. The old session's terminal note is appended while it is
+	 * still current, because an append always lands in the current session. Then
+	 * the new session is minted through the one creation path the orchestrator
+	 * owns, the document goes in as bounded data labelled by its origin, and the
+	 * old session's skill activations are replayed so loaded skills carry
+	 * forward. The old session is otherwise untouched.
+	 */
+	function seedHandoffSession(session: SessionContract, fromSessionId: string, goal: string, document: string): void {
+		const notice = deps.getSlashNotice();
+		const activations = session.current()?.skillActivations ?? [];
+		let toSessionId: string;
+		try {
+			deps.onNewSession?.();
+			const minted = session.current()?.id ?? null;
+			if (minted === null || minted === fromSessionId) throw new Error("the new session was not created");
+			toSessionId = minted;
+			session.appendEntry({
+				kind: "custom",
+				parentTurnId: null,
+				customType: HANDOFF_SEED_CUSTOM_TYPE,
+				display: true,
+				data: { fromSessionId, goal, document } satisfies HandoffSeedData,
+			});
+			for (const activation of activations) session.recordSkillActivation(activation);
+		} catch (error) {
+			emitCommandNotice(
+				notice,
+				"error",
+				"handoff",
+				`could not seed the new session: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			return;
+		}
+		// The note names the target, so it can only be written once the target
+		// exists. Appends land in the current session, so the old session is made
+		// current for exactly one append and then handed back. A failure here
+		// costs the note and nothing else: the successor session is already
+		// seeded and is where the operator continues.
+		try {
+			session.switchBranch(fromSessionId);
+			session.appendEntry({
+				kind: "custom",
+				parentTurnId: null,
+				customType: HANDOFF_NOTE_CUSTOM_TYPE,
+				display: true,
+				data: { toSessionId, goal } satisfies HandoffNoteData,
+			});
+		} catch (error) {
+			deps.stderr(`[/handoff] handoff note failed: ${error instanceof Error ? error.message : String(error)}\n`);
+		} finally {
+			try {
+				session.switchBranch(toSessionId);
+			} catch (error) {
+				deps.stderr(
+					`[/handoff] could not return to the new session: ${error instanceof Error ? error.message : String(error)}\n`,
+				);
+			}
+		}
+		try {
+			const turns = deps.readStructuredEntries(toSessionId);
+			deps.resetTranscript();
+			rehydrateChatPanelFromTurns(deps.chatPanel, turns);
+			deps.chat.resetForSession(null, buildModelReplayAgentMessagesFromTurns(turns));
+			rescopeToBranch(session, turns, null);
+		} catch (error) {
+			deps.stderr(`[/handoff] seeding replay failed: ${error instanceof Error ? error.message : String(error)}\n`);
+			deps.chat.resetForSession(null);
+		}
+		emitCommandNotice(notice, "info", "handoff", `handed off to session ${toSessionId}`);
+		deps.refreshFooter();
+		deps.requestRender();
+	}
+
+	return { openResume, openTree, openMessagePicker: openMessagePickerState, startHandoff };
 }

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();
+		},
+	};
+}