@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/interactive/overlays/settings.ts

@@ -135,6 +135,7 @@ export const SETTINGS_SECTIONS = [
 	{ id: "compaction", label: "Compaction", group: "RUNTIME" },
 	{ id: "retry", label: "Retry", group: "RUNTIME" },
 	{ id: "terminal", label: "Terminal", group: "EXPERIENCE" },
+	{ id: "watchdog", label: "Watchdog", group: "EXPERIENCE" },
 	{ id: "advanced", label: "Advanced", group: "EXPERIENCE" },
 ] as const;
 
@@ -150,6 +151,7 @@ const SETTINGS_SECTION_DESCRIPTIONS = {
 	compaction: "When and how the context window is summarized under pressure.",
 	retry: "Automatic recovery from transient provider and network errors.",
 	terminal: "Terminal integration and the Clio color palette.",
+	watchdog: "The opt-in turn-end verifier run, where it is routed, and whether it also fires mid-turn.",
 	advanced: "Commit provenance, runtime plugins, delegation timeouts, and links to other surfaces.",
 } as const satisfies Record<SettingsSectionId, string>;
 
@@ -199,6 +201,10 @@ export const SETTINGS_LABELS_BY_ID = {
 	"terminal.tuiMode": "TUI mode",
 	"terminal.fullscreenScrollbar": "Fullscreen scrollbar",
 	"terminal.smoothStreaming": "Smooth streaming",
+	"terminal.notify": "Desktop notifications",
+	"watchdog.enabled": "Turn-end watchdog",
+	"watchdog.target": "Watchdog target",
+	"watchdog.cadenceToolCalls": "Watchdog cadence (tools)",
 	theme: "Theme",
 	runtimePlugins: "Runtime plugins",
 	"compaction.model": "Compaction model",
@@ -269,8 +275,10 @@ export const SETTINGS_SECTION_ROWS = {
 		"terminal.tuiMode",
 		"terminal.fullscreenScrollbar",
 		"terminal.smoothStreaming",
+		"terminal.notify",
 		"theme",
 	],
+	watchdog: ["watchdog.enabled", "watchdog.target", "watchdog.cadenceToolCalls"],
 	advanced: [
 		"runtimePlugins",
 		"attribution.gitCommits",
@@ -329,6 +337,11 @@ const SETTINGS_DESCRIPTIONS_BY_ID = {
 	"terminal.tuiMode": "Use regular terminal scrollback or a fullscreen transcript with a sticky composer and footer.",
 	"terminal.fullscreenScrollbar": "When the draggable transcript scrollbar is visible in fullscreen mode.",
 	"terminal.smoothStreaming": "Presentation-only pacing for streamed assistant text and thinking.",
+	"terminal.notify":
+		"Content-free desktop notification when a turn ends, a detached batch settles, or an approval parks.",
+	"watchdog.enabled": "When enabled, a turn that changed the tree is reviewed by one read-only verifier run.",
+	"watchdog.target": "Set target to route the run at a cheap local model; blank uses the session's active target.",
+	"watchdog.cadenceToolCalls": "Also fire every N tool calls inside a turn; blank fires at turn end only.",
 	theme: "Color palette. Clio ships a single tuned palette.",
 	runtimePlugins: "npm packages exporting clioRuntimes: RuntimeDescriptor[].",
 	"compaction.model": "Dedicated summarization model; blank uses the orchestrator.",
@@ -362,6 +375,14 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 		"clio-policy gates the agent through Clio's safety net; agent-managed trusts the agent; deny-all blocks every tool.",
 	scope: "Choose target-level or exact target/model refs. Alt+J / Alt+K step the chat target through this list.",
 	runtimePlugins: "Comma-separated package names, loaded at startup. Restart Clio after changing.",
+	"terminal.notify":
+		"OSC 777, or OSC 9 on iTerm2, Windows Terminal, and ConEmu. Interactive TTY runs only; the body never carries prompt text, file paths, or model output.",
+	"watchdog.enabled":
+		"The verifier run is briefed with the turn's coalesced diff and the task board's current scope; its blockers become one transcript notice and nothing else. Headless and ACP runs never fire it.",
+	"watchdog.target":
+		"A watchdog run costs a worker run per mutating turn, so routing it at a local target keeps the review cheap. Leave blank to reuse whatever the session is already talking to.",
+	"watchdog.cadenceToolCalls":
+		"Mid-turn firing is how scope drift becomes visible before the turn ends. Leave blank and the watchdog fires at turn end only.",
 	keybindings:
 		"Renderer controls: Alt+O newest tool or worker details, Ctrl+Alt+O or Alt+Shift+O all of them, Alt+P live tool output, Alt+R latest reasoning, Ctrl+Alt+R or Alt+Shift+R all reasoning. Override these in settings.yaml or use /help.",
 };
@@ -422,6 +443,14 @@ const SETTINGS_VALUE_HELP_BY_ID: Partial<Record<EditableSettingId, Record<string
 		auto: "show the scrollbar while scrolling or dragging",
 		always: "reserve the rightmost column for the scrollbar",
 	},
+	"terminal.notify": {
+		true: "post a content-free desktop notification on turn end, batch settlement, and a parked approval",
+		false: "never post a desktop notification",
+	},
+	"watchdog.enabled": {
+		true: "review every mutating turn with one read-only verifier run",
+		false: "no verifier run; a turn ends without a second opinion",
+	},
 	"terminal.smoothStreaming": {
 		off: "preserve the current immediate 16ms-coalesced streaming behavior",
 		auto: "pace only on a capable local TTY without accessibility or backpressure risk",
@@ -478,6 +507,13 @@ export interface SettingsCenterItem extends SettingItem {
 	help?: string;
 	valueHelp?: Record<string, string>;
 	defaultValue?: string;
+	/**
+	 * What a free-text editor opens with when it differs from the rendered
+	 * value. A row that renders its absence as prose such as `(session target)`
+	 * must not hand that prose to the editor, or the operator's typing lands
+	 * behind it and the placeholder is written into settings.yaml.
+	 */
+	editValue?: string;
 }
 
 export interface SettingsCenterSection {
@@ -557,6 +593,13 @@ function delegationAgentsAffordance(
 type SubmenuTitle = string | ((width: number) => string);
 
 export class SubmenuWrapper implements Component {
+	/**
+	 * Why the last submission was refused, or null while nothing is wrong. The
+	 * editor sets it instead of closing, so the operator corrects the value with
+	 * the reason on screen rather than back at the row list with no reason.
+	 */
+	private problem: string | null = null;
+
 	constructor(
 		private readonly title: SubmenuTitle,
 		private readonly child: Component,
@@ -564,6 +607,10 @@ export class SubmenuWrapper implements Component {
 		private readonly note?: string,
 	) {}
 
+	setProblem(problem: string | null): void {
+		this.problem = problem;
+	}
+
 	render(width: number): string[] {
 		const theme = clioTheme();
 		const lines: string[] = [];
@@ -583,6 +630,11 @@ export class SubmenuWrapper implements Component {
 		// two columns off each one and marked the cut, so every entry wore a
 		// trailing … it had not earned.
 		lines.push(...this.child.render(Math.max(1, width - 2)).map((line) => `  ${line}`));
+		if (this.problem !== null) {
+			for (const line of wrapTextWithAnsi(this.problem, Math.max(1, width - 2))) {
+				lines.push(theme.fg("error", `  ${line}`));
+			}
+		}
 		lines.push("");
 		lines.push(theme.fg("dim", `  ${this.hint}`));
 		return lines;
@@ -657,26 +709,108 @@ function editTextSubmenu(title: string, note?: string): SettingSubmenuBuilder {
 	return textInputSubmenu(title, note);
 }
 
-function editNumberSubmenu(title: string): SettingSubmenuBuilder {
+/**
+ * The bound a number row enforces, shared by the editor and the apply path so
+ * the two cannot drift: whatever the editor forwards, the apply path stores.
+ * The bounds mirror the config validator's, so a value the Settings Center
+ * refuses is one settings.yaml would have refused too, in the same words.
+ */
+interface NumberSettingRule {
+	readonly min: number;
+	readonly max?: number;
+	readonly integer: boolean;
+	/** A blank submission clears the key instead of being a parse failure. */
+	readonly allowBlank?: boolean;
+}
+
+const NUMBER_SETTING_RULES = {
+	"budget.sessionCeilingUsd": { min: 0, integer: false },
+	"watchdog.cadenceToolCalls": { min: 1, integer: true, allowBlank: true },
+	"delegation.defaults.connectTimeoutMs": { min: 1, max: MAX_TIMER_DELAY_MS, integer: true },
+	"delegation.defaults.turnTimeoutMs": { min: 1, max: MAX_TIMER_DELAY_MS, integer: true },
+	"delegation.defaults.permissionTimeoutMs": { min: 1, max: MAX_TIMER_DELAY_MS, integer: true },
+} as const satisfies Partial<Record<EditableSettingId, NumberSettingRule>>;
+
+export type NumberSettingId = keyof typeof NUMBER_SETTING_RULES;
+
+export const NUMBER_SETTING_IDS = Object.keys(NUMBER_SETTING_RULES) as readonly NumberSettingId[];
+
+type NumberSettingOutcome = { readonly value: number | null } | { readonly refusal: string };
+
+function describeSubmittedText(value: string): string {
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? "an empty string" : JSON.stringify(trimmed);
+}
+
+/**
+ * Parse one submitted number-row value under its rule. A null value means the
+ * operator cleared an optional key. The refusal is worded like the config
+ * validator's issue for the same key ("expected an integer >= 1, got 0"), with
+ * a "Not applied:" prefix so it reads as the outcome of this submission.
+ */
+function parseNumberSetting(value: string, rule: NumberSettingRule): NumberSettingOutcome {
+	const trimmed = value.trim();
+	const noun = rule.integer ? "an integer" : "a number";
+	if (trimmed.length === 0 && rule.allowBlank === true) return { value: null };
+	const parsed = trimmed.length === 0 ? Number.NaN : Number(trimmed);
+	if (!Number.isFinite(parsed) || (rule.integer && !Number.isInteger(parsed))) {
+		const shown = Number.isFinite(parsed) ? String(parsed) : describeSubmittedText(value);
+		return { refusal: `Not applied: expected ${noun}, got ${shown}.` };
+	}
+	if (parsed < rule.min) return { refusal: `Not applied: expected ${noun} >= ${rule.min}, got ${parsed}.` };
+	if (rule.max !== undefined && parsed > rule.max) {
+		return { refusal: `Not applied: expected ${noun} <= ${rule.max}, got ${parsed}.` };
+	}
+	return { value: parsed };
+}
+
+/**
+ * The reason a number row would refuse `value`, or null when it would apply.
+ * This is the same check the editor and `applySettingChange` run, exposed so a
+ * caller that bypasses the editor can still name the bound it hit.
+ */
+export function describeNumberSettingRefusal(id: NumberSettingId, value: string): string | null {
+	const outcome = parseNumberSetting(value, NUMBER_SETTING_RULES[id]);
+	return "refusal" in outcome ? outcome.refusal : null;
+}
+
+function numberSettingNote(rule: NumberSettingRule): string {
+	const noun = rule.integer ? "a whole number" : "a number";
+	const clears = rule.allowBlank === true ? "; blank clears it" : "";
+	if (rule.min > 0 && rule.max !== undefined) return `Use ${noun} from ${rule.min} to ${rule.max}${clears}.`;
+	if (rule.min > 0) return `Use ${noun} of at least ${rule.min}${clears}.`;
+	return `Use a non-negative ${rule.integer ? "whole number" : "number"}${clears}.`;
+}
+
+/**
+ * A number editor that stays open on a refused submission. Closing with no
+ * value looked like a successful edit that changed nothing, so the reason is
+ * rendered under the input and the operator corrects the text in place; Esc
+ * still leaves without applying.
+ */
+function editNumberSubmenu(title: string, id: NumberSettingId): SettingSubmenuBuilder {
+	const rule = NUMBER_SETTING_RULES[id];
 	return (currentValue: string, done: (val?: string) => void) => {
 		const input = new Input();
 		input.setValue(currentValue);
 		input.focused = true;
-		input.onSubmit = (val) => {
-			const num = Number(val);
-			if (Number.isFinite(num) && num >= 0) {
-				done(val);
-			} else {
-				done();
-			}
-		};
-		input.onEscape = () => done();
-		return new SubmenuWrapper(
+		const wrapper = new SubmenuWrapper(
 			title,
 			input,
 			buildHint([{ key: "Enter", verb: "confirm" }], "back"),
-			"Use a non-negative number.",
+			numberSettingNote(rule),
 		);
+		input.onSubmit = (val) => {
+			const outcome = parseNumberSetting(val, rule);
+			if ("refusal" in outcome) {
+				wrapper.setProblem(outcome.refusal);
+				return;
+			}
+			wrapper.setProblem(null);
+			done(outcome.value === null ? "" : val.trim());
+		};
+		input.onEscape = () => done();
+		return wrapper;
 	};
 }
 
@@ -1122,6 +1256,7 @@ function settingItem(
 		label?: string;
 		description?: string;
 		help?: string;
+		editValue?: string;
 	},
 ): SettingsCenterItem {
 	const item: SettingsCenterItem = {
@@ -1139,6 +1274,7 @@ function settingItem(
 	};
 	const help = options.help ?? SETTINGS_HELP_BY_ID[id];
 	if (help) item.help = help;
+	if (options.editValue !== undefined) item.editValue = options.editValue;
 	const valueHelp = SETTINGS_VALUE_HELP_BY_ID[id];
 	if (valueHelp) item.valueHelp = valueHelp;
 	const def = defaultValueFor(id);
@@ -1211,6 +1347,7 @@ export function buildSettingItems(
 	const compaction = settings.compaction;
 	const retry = settings.retry;
 	const terminal = settings.terminal;
+	const watchdog = settings.watchdog;
 	const orchestratorThinking = thinkingChoices(
 		options?.providers,
 		settings.orchestrator.target,
@@ -1366,7 +1503,7 @@ export function buildSettingItems(
 			readOnly: true,
 		}),
 		settingItem("budget.sessionCeilingUsd", String(settings.budget.sessionCeilingUsd), {
-			submenu: editNumberSubmenu("Edit session cost ceiling USD"),
+			submenu: editNumberSubmenu("Edit session cost ceiling USD", "budget.sessionCeilingUsd"),
 			affordance: "free text",
 		}),
 		settingItem("defaults.maxTokens", String(settings.defaults.maxTokens), {
@@ -1411,10 +1548,36 @@ export function buildSettingItems(
 		settingItem("terminal.smoothStreaming", terminal.smoothStreaming, {
 			values: ["off", "auto", "on"],
 		}),
+		settingItem("terminal.notify", String(terminal.notify), {
+			values: ["false", "true"],
+		}),
 		settingItem("theme", settings.theme, {
 			affordance: "single clio-coder palette",
 			readOnly: true,
 		}),
+		settingItem("watchdog.enabled", String(watchdog.enabled), {
+			values: ["false", "true"],
+		}),
+		// Both optional keys render their absence rather than a fabricated value:
+		// an unset target means the session's own, and an unset cadence means the
+		// watchdog fires at turn end only. Submitting an empty value clears them.
+		settingItem("watchdog.target", watchdog.target ?? "(session target)", {
+			submenu: editTextSubmenu("Edit watchdog target; blank uses the session's active target"),
+			affordance: "free text",
+			editValue: watchdog.target ?? "",
+		}),
+		settingItem(
+			"watchdog.cadenceToolCalls",
+			watchdog.cadenceToolCalls === undefined ? "(turn end only)" : String(watchdog.cadenceToolCalls),
+			{
+				submenu: editNumberSubmenu(
+					"Edit watchdog cadence in tool calls; blank fires at turn end only",
+					"watchdog.cadenceToolCalls",
+				),
+				affordance: "free text",
+				editValue: watchdog.cadenceToolCalls === undefined ? "" : String(watchdog.cadenceToolCalls),
+			},
+		),
 		settingItem("runtimePlugins", settings.runtimePlugins.length > 0 ? settings.runtimePlugins.join(", ") : "(none)", {
 			submenu: editTextSubmenu("Edit runtime plugins comma-separated list", "Restart Clio to load changes."),
 			affordance: "free text",
@@ -1431,15 +1594,15 @@ export function buildSettingItems(
 			affordance: "free text",
 		}),
 		settingItem("delegation.defaults.connectTimeoutMs", String(settings.delegation.defaults.connectTimeoutMs), {
-			submenu: editNumberSubmenu("Edit delegate connect timeout (ms)"),
+			submenu: editNumberSubmenu("Edit delegate connect timeout (ms)", "delegation.defaults.connectTimeoutMs"),
 			affordance: "free text",
 		}),
 		settingItem("delegation.defaults.turnTimeoutMs", String(settings.delegation.defaults.turnTimeoutMs), {
-			submenu: editNumberSubmenu("Edit delegate turn timeout (ms)"),
+			submenu: editNumberSubmenu("Edit delegate turn timeout (ms)", "delegation.defaults.turnTimeoutMs"),
 			affordance: "free text",
 		}),
 		settingItem("delegation.defaults.permissionTimeoutMs", String(settings.delegation.defaults.permissionTimeoutMs), {
-			submenu: editNumberSubmenu("Edit delegate permission timeout (ms)"),
+			submenu: editNumberSubmenu("Edit delegate permission timeout (ms)", "delegation.defaults.permissionTimeoutMs"),
 			affordance: "free text",
 		}),
 		settingItem("keybindings", keybindingCount > 0 ? `${keybindingCount} override(s)` : "(defaults)", {
@@ -1747,9 +1910,15 @@ function applyNonNegativeInteger(value: string, set: (next: number) => void): vo
 	if (Number.isFinite(parsed) && parsed >= 0) set(Math.floor(parsed));
 }
 
-function applyPositiveInteger(value: string, set: (next: number) => void): void {
-	const parsed = Number(value);
-	if (Number.isInteger(parsed) && parsed >= 1 && parsed <= MAX_TIMER_DELAY_MS) set(parsed);
+/**
+ * Store a number-row submission under the row's shared rule. A refused value
+ * leaves the setting alone; the editor has already shown the operator why, and
+ * `describeNumberSettingRefusal` names the reason for any other caller.
+ */
+function applyNumberSetting(id: NumberSettingId, value: string, set: (next: number | null) => void): void {
+	const outcome = parseNumberSetting(value, NUMBER_SETTING_RULES[id]);
+	if ("refusal" in outcome) return;
+	set(outcome.value);
 }
 
 /**
@@ -1898,6 +2067,28 @@ export function applySettingChange(settings: ClioSettings, id: string, value: st
 				settings.terminal.fullscreenScrollbar = value;
 			}
 			return;
+		case "terminal.notify":
+			if (value === "true" || value === "false") settings.terminal.notify = value === "true";
+			return;
+		case "watchdog.enabled":
+			if (value === "true" || value === "false") settings.watchdog.enabled = value === "true";
+			return;
+		// Both watchdog options are absent-by-default, and an empty submission is
+		// how the operator says "go back to the default" from a text row. Deleting
+		// the key rather than storing a blank keeps settings.yaml matching what the
+		// config validator accepts.
+		case "watchdog.target": {
+			const trimmed = value.trim();
+			if (trimmed) settings.watchdog.target = trimmed;
+			else delete settings.watchdog.target;
+			return;
+		}
+		case "watchdog.cadenceToolCalls":
+			applyNumberSetting("watchdog.cadenceToolCalls", value, (next) => {
+				if (next === null) delete settings.watchdog.cadenceToolCalls;
+				else settings.watchdog.cadenceToolCalls = next;
+			});
+			return;
 		case "terminal.smoothStreaming":
 			if (value === "off" || value === "auto" || value === "on") settings.terminal.smoothStreaming = value;
 			return;
@@ -1908,18 +2099,18 @@ export function applySettingChange(settings: ClioSettings, id: string, value: st
 				.filter(Boolean);
 			return;
 		case "delegation.defaults.connectTimeoutMs":
-			applyPositiveInteger(value, (next) => {
-				settings.delegation.defaults.connectTimeoutMs = next;
+			applyNumberSetting("delegation.defaults.connectTimeoutMs", value, (next) => {
+				if (next !== null) settings.delegation.defaults.connectTimeoutMs = next;
 			});
 			return;
 		case "delegation.defaults.turnTimeoutMs":
-			applyPositiveInteger(value, (next) => {
-				settings.delegation.defaults.turnTimeoutMs = next;
+			applyNumberSetting("delegation.defaults.turnTimeoutMs", value, (next) => {
+				if (next !== null) settings.delegation.defaults.turnTimeoutMs = next;
 			});
 			return;
 		case "delegation.defaults.permissionTimeoutMs":
-			applyPositiveInteger(value, (next) => {
-				settings.delegation.defaults.permissionTimeoutMs = next;
+			applyNumberSetting("delegation.defaults.permissionTimeoutMs", value, (next) => {
+				if (next !== null) settings.delegation.defaults.permissionTimeoutMs = next;
 			});
 			return;
 		case "orchestrator.target": {
@@ -1970,11 +2161,11 @@ export function applySettingChange(settings: ClioSettings, id: string, value: st
 					.map((v) => v.trim())
 					.filter(Boolean);
 			return;
-		case "budget.sessionCeilingUsd": {
-			const parsed = Number(value);
-			if (Number.isFinite(parsed) && parsed >= 0) settings.budget.sessionCeilingUsd = parsed;
+		case "budget.sessionCeilingUsd":
+			applyNumberSetting("budget.sessionCeilingUsd", value, (next) => {
+				if (next !== null) settings.budget.sessionCeilingUsd = next;
+			});
 			return;
-		}
 	}
 }
 
@@ -2851,7 +3042,7 @@ export class SettingsCenter implements Component {
 		const item = this.selectedItem();
 		if (!item || item.readOnly) return;
 		if (item.submenu) {
-			this.submenuComponent = item.submenu(item.currentValue, (selectedValue) => {
+			this.submenuComponent = item.submenu(item.editValue ?? item.currentValue, (selectedValue) => {
 				this.submenuComponent = null;
 				if (selectedValue !== undefined) this.prepareScopeConfirm(item, selectedValue);
 				this.options.requestRender?.();

package/src/interactive/overlays/side-question.ts

@@ -0,0 +1,139 @@
+/**
+ * `/btw` overlay: the question, then the answer as it streams.
+ *
+ * The overlay is the whole surface for a side question. Nothing it shows is
+ * appended to the transcript, so closing it is the end of the exchange: the
+ * answer was for the operator, in the moment, and the session never saw it.
+ */
+
+import { type Component, type OverlayHandle, type TUI, wrapTextWithAnsi } from "../../engine/tui.js";
+import { buildResponsiveHint, showClioOverlayFrame } from "../overlay-frame.js";
+import { clioTheme, GLYPH, rule } from "../theme/index.js";
+
+export const SIDE_QUESTION_OVERLAY_TITLE = "Side question";
+
+/** What the overlay is showing right now. */
+export type SideQuestionOverlayPhase =
+	| { kind: "streaming"; text: string }
+	| { kind: "answered"; text: string }
+	| { kind: "aborted"; text: string }
+	| { kind: "error"; reason: string };
+
+export interface SideQuestionOverlaySession extends OverlayHandle {
+	/** Replace the streamed answer text. */
+	setAnswer(text: string): void;
+	/** Settle the overlay on a final phase. */
+	settle(phase: SideQuestionOverlayPhase): void;
+}
+
+export interface OpenSideQuestionOverlayOptions {
+	question: string;
+	/** Live terminal width, so the box tracks the window it opened in. */
+	columns: number;
+	/** Esc: abort a streaming round, then close. */
+	onClose: () => void;
+}
+
+const SIDE_QUESTION_OVERLAY_MIN_WIDTH = 44;
+const SIDE_QUESTION_OVERLAY_MAX_WIDTH = 100;
+
+export function sideQuestionOverlayWidth(columns: number): number {
+	return Math.max(SIDE_QUESTION_OVERLAY_MIN_WIDTH, Math.min(SIDE_QUESTION_OVERLAY_MAX_WIDTH, columns - 4));
+}
+
+/**
+ * Render the overlay body. Pure so the layout is unit-testable without a TUI:
+ * the question in dim above a rule, then the answer, then one status line that
+ * says whether the round is still running, cancelled, or failed.
+ */
+export function formatSideQuestionBody(
+	question: string,
+	phase: SideQuestionOverlayPhase,
+	width: number,
+	spinner: string,
+): string[] {
+	const theme = clioTheme();
+	const contentWidth = Math.max(1, Math.floor(width));
+	const lines: string[] = [];
+	for (const line of wrapTextWithAnsi(theme.fg("dim", `${GLYPH.user} ${question}`), contentWidth)) lines.push(line);
+	lines.push(rule(theme, contentWidth));
+	if (phase.kind === "error") {
+		for (const line of wrapTextWithAnsi(theme.fg("error", phase.reason), contentWidth)) lines.push(line);
+		return lines;
+	}
+	const body = phase.text.trim();
+	if (body.length > 0) {
+		for (const paragraph of body.split("\n")) {
+			if (paragraph.length === 0) {
+				lines.push("");
+				continue;
+			}
+			for (const line of wrapTextWithAnsi(theme.fg("muted", paragraph), contentWidth)) lines.push(line);
+		}
+	}
+	if (phase.kind === "streaming") {
+		lines.push(theme.fg("dim", body.length > 0 ? spinner : `${spinner} asking…`));
+	} else if (phase.kind === "aborted") {
+		lines.push(theme.fg("warning", "cancelled"));
+	} else if (body.length === 0) {
+		lines.push(theme.fg("dim", "the model returned no text"));
+	}
+	return lines;
+}
+
+const SPINNER_FRAMES = ["·", "•", "●", "•"] as const;
+
+class SideQuestionOverlayBody implements Component {
+	private phase: SideQuestionOverlayPhase = { kind: "streaming", text: "" };
+	private frame = 0;
+
+	constructor(private readonly question: string) {}
+
+	set(phase: SideQuestionOverlayPhase): void {
+		this.phase = phase;
+	}
+
+	render(width: number): string[] {
+		if (this.phase.kind === "streaming") this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+		return formatSideQuestionBody(this.question, this.phase, width, SPINNER_FRAMES[this.frame] ?? "·");
+	}
+
+	invalidate(): void {}
+}
+
+/**
+ * Mount the overlay. `setAnswer` is called from the stream; `settle` closes the
+ * round's live state without closing the overlay, so the operator reads the
+ * answer and leaves with Esc.
+ */
+export function openSideQuestionOverlay(tui: TUI, options: OpenSideQuestionOverlayOptions): SideQuestionOverlaySession {
+	const body = new SideQuestionOverlayBody(options.question);
+	let settled = false;
+	const handle = showClioOverlayFrame(tui, body, {
+		anchor: "center",
+		width: sideQuestionOverlayWidth(options.columns),
+		title: SIDE_QUESTION_OVERLAY_TITLE,
+		// Esc means two things here and the footer names the live one: it aborts a
+		// round that is still streaming, and it closes one that has settled.
+		footerHint: (innerWidth) => buildResponsiveHint([], { key: "Esc", verb: settled ? "close" : "cancel" })(innerWidth),
+	});
+	return {
+		...handle,
+		setAnswer(text: string): void {
+			if (settled) return;
+			body.set({ kind: "streaming", text });
+			body.invalidate();
+			tui.requestRender();
+		},
+		settle(phase: SideQuestionOverlayPhase): void {
+			settled = true;
+			body.set(phase);
+			body.invalidate();
+			tui.requestRender();
+		},
+		hide(): void {
+			options.onClose();
+			handle.hide();
+		},
+	};
+}