@iowarp/clio-coder 0.3.9 → 0.4.0

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

@@ -36,6 +36,7 @@ interface WorkerEscalationEntry {
 	axis: ApprovalRequestView["axis"];
 	reason: string;
 	target?: string;
+	fallback: "deny" | "fail";
 }
 
 export interface OverlayPermissionLifecycleDeps {
@@ -190,6 +191,7 @@ function workerEscalationEntry(payload: PermissionRequestedPayload, autonomy: st
 		...(typeof payload.target === "string" && payload.target.length > 0
 			? { target: sanitizeCallTargetText(payload.target).slice(0, 200) }
 			: {}),
+		fallback: payload.fallback === "fail" ? "fail" : "deny",
 	};
 }
 
@@ -207,42 +209,87 @@ function workerApprovalRequestView(entry: WorkerEscalationEntry): ApprovalReques
 
 export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycleDeps): OverlayPermissionLifecycle {
 	let pendingPermission: { call: ClassifierCall; decision: SafetyDecision; meta?: PermissionRequiredMeta } | null = null;
-	let pendingWorker: Pick<WorkerEscalationEntry, "agentId" | "requestId" | "runId"> | null = null;
+	let pendingWorker: WorkerEscalationEntry | null = null;
 	const workerQueue: WorkerEscalationEntry[] = [];
 	const announcedRequestIds = new Set<string>();
 	/** Worker escalations already surfaced, so one request parks the operator once. */
 	const announcedWorkerRequestIds = new Set<string>();
+	/** Expiry notices already printed, including a decision that lost the terminal-state race. */
+	const expiredWorkerRequestIds = new Set<string>();
 	let confirmed = false;
 	let stopping = false;
+	let withdrawingWorker = false;
 
-	const openWorker = (entry: WorkerEscalationEntry): void => {
-		if (deps.getOverlayState() !== "closed") return;
-		if (!deps.openPermissionOverlay(workerApprovalRequestView(entry))) return;
-		pendingWorker = { runId: entry.runId, requestId: entry.requestId, agentId: entry.agentId };
+	const openWorker = (entry: WorkerEscalationEntry): boolean => {
+		if (!deps.openPermissionOverlay(workerApprovalRequestView(entry))) return false;
+		pendingWorker = entry;
 		pendingPermission = null;
 		confirmed = false;
+		return true;
 	};
 	const maybeOpenWorker = (): void => {
-		if (deps.getOverlayState() !== "closed") return;
-		const next = workerQueue.shift();
-		if (next) openWorker(next);
+		const next = workerQueue[0];
+		if (next && openWorker(next)) workerQueue.shift();
 	};
 	const retryPending = (): void => {
 		maybeOpenWorker();
-		if (deps.getOverlayState() === "closed" && deps.toolRegistry?.hasParkedCalls()) {
+		if (deps.getOverlayState() !== "permission-confirm" && deps.toolRegistry?.hasParkedCalls()) {
 			deps.toolRegistry.renotifyHead();
 		}
 	};
+	const announceWorkerExpiry = (
+		entry: WorkerEscalationEntry,
+		fallback: "deny" | "fail",
+		cause: "timeout" | "terminal" | "late-answer",
+	): void => {
+		if (!markPermissionRequestSurfaced(expiredWorkerRequestIds, entry.requestId)) return;
+		const why =
+			cause === "timeout"
+				? "expired after its escalation timeout"
+				: cause === "terminal"
+					? "expired when its run ended"
+					: "expired before the operator decision arrived";
+		deps.appendNotice(
+			"warn",
+			`Worker approval request ${entry.requestId} for ${entry.agentId} (${entry.runId}) ${why}; fallback ${fallback} applied.`,
+		);
+	};
+	const removeQueuedWorkers = (matches: (entry: WorkerEscalationEntry) => boolean): WorkerEscalationEntry[] => {
+		const removed: WorkerEscalationEntry[] = [];
+		for (let index = workerQueue.length - 1; index >= 0; index -= 1) {
+			const entry = workerQueue[index];
+			if (entry === undefined || !matches(entry)) continue;
+			removed.unshift(entry);
+			workerQueue.splice(index, 1);
+		}
+		return removed;
+	};
+	const withdrawWorkers = (
+		matches: (entry: WorkerEscalationEntry) => boolean,
+		cause: "timeout" | "terminal",
+		fallback?: "deny" | "fail",
+	): void => {
+		const active = pendingWorker !== null && matches(pendingWorker) ? pendingWorker : null;
+		const expired = [...(active === null ? [] : [active]), ...removeQueuedWorkers(matches)];
+		if (expired.length === 0) return;
+		if (active !== null) {
+			pendingWorker = null;
+			confirmed = false;
+			withdrawingWorker = true;
+			deps.closeOverlay();
+		}
+		for (const entry of expired) announceWorkerExpiry(entry, fallback ?? entry.fallback, cause);
+		deps.requestRender();
+	};
 
 	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
-			// emitted only when no dialog could open (another overlay holds the
-			// screen), which is the case where it is the operator's only signal.
+			// The dialog states the tool, target, action class, asking axis, and
+			// decision keys. Another modal is interrupted so this prompt can take
+			// focus. The notice remains for a second queued approval or a frame that
+			// could not mount, when it is the operator's only additional signal.
 			const announceParked = (): void => {
 				if (!markPermissionRequestSurfaced(announcedRequestIds, meta.requestId)) return;
 				const notice = approvalParkedNotice(call.tool, decision, autonomy);
@@ -256,10 +303,6 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 					view,
 				});
 			}
-			if (deps.getOverlayState() !== "closed") {
-				announceParked();
-				return;
-			}
 			if (!deps.openPermissionOverlay(view, mainMutationInspector(call, view))) {
 				announceParked();
 				return;
@@ -280,6 +323,18 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		workerQueue.push(entry);
 		maybeOpenWorker();
 	});
+	const unsubscribeWorkerResolution = deps.bus.on(BusChannels.PermissionResolved, (payload) => {
+		if (typeof payload.requestId !== "string") return;
+		if (payload.decidedBy !== "timeout" && payload.status !== "expired") return;
+		const fallback = payload.fallback === "fail" ? "fail" : "deny";
+		withdrawWorkers((entry) => entry.requestId === payload.requestId, "timeout", fallback);
+	});
+	const withdrawTerminalRun = (payload: { runId?: unknown }): void => {
+		if (typeof payload.runId !== "string") return;
+		withdrawWorkers((entry) => entry.runId === payload.runId, "terminal");
+	};
+	const unsubscribeWorkerCompleted = deps.bus.on(BusChannels.DispatchCompleted, withdrawTerminalRun);
+	const unsubscribeWorkerFailed = deps.bus.on(BusChannels.DispatchFailed, withdrawTerminalRun);
 
 	const unsubscribeAutonomy =
 		deps.toolRegistry?.onAutonomyDenied((_call, decision, level) => {
@@ -289,6 +344,12 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		}) ?? (() => {});
 
 	const onPermissionOverlayClosed = (): void => {
+		if (withdrawingWorker) {
+			withdrawingWorker = false;
+			confirmed = false;
+			retryPending();
+			return;
+		}
 		const permission = pendingPermission;
 		const worker = pendingWorker;
 		pendingPermission = null;
@@ -299,10 +360,14 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			try {
 				deps.dispatch.resolveWorkerPermission?.(worker.runId, worker.requestId, wasConfirmed ? "approve" : "deny");
 			} catch (error) {
-				deps.appendNotice(
-					"warn",
-					`Could not deliver permission decision to run ${worker.runId}: ${error instanceof Error ? error.message : String(error)}`,
-				);
+				const message = error instanceof Error ? error.message : String(error);
+				if (
+					/run or assignment '.+' is not active|run '.+' is (?:aborting|terminating)|no longer accepts input/u.test(message)
+				) {
+					announceWorkerExpiry(worker, worker.fallback, "late-answer");
+				} else {
+					deps.appendNotice("warn", `Could not deliver permission decision to run ${worker.runId}: ${message}`);
+				}
 			}
 		} else if (wasConfirmed && permission) {
 			deps.bus.emit(BusChannels.PermissionResolved, {
@@ -384,6 +449,9 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		dispose: () => {
 			unsubscribePermission();
 			unsubscribeWorker();
+			unsubscribeWorkerResolution();
+			unsubscribeWorkerCompleted();
+			unsubscribeWorkerFailed();
 			unsubscribeAutonomy();
 		},
 	};

package/src/interactive/overlay-transitions.ts

@@ -20,12 +20,15 @@ export interface OverlayTransitionsDeps {
 export interface OverlayTransitions {
 	state: OverlayState;
 	handle: OverlayHandle | null;
+	/** Raise a permission prompt while preserving the modal it interrupted. */
+	showPermission(handle: OverlayHandle): boolean;
 	close(): void;
 }
 
 export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayTransitions {
 	let state: OverlayState = "closed";
 	let handle: OverlayHandle | null = null;
+	let interrupted: { state: OverlayState; handle: OverlayHandle | null } | null = null;
 
 	return {
 		get state() {
@@ -44,6 +47,13 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 		set handle(next) {
 			handle = next;
 		},
+		showPermission(nextHandle) {
+			if (state === "permission-confirm") return false;
+			interrupted = state === "closed" ? null : { state, handle };
+			state = "permission-confirm";
+			handle = nextHandle;
+			return true;
+		},
 		close,
 	};
 
@@ -55,12 +65,16 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 			return;
 		}
 		const leaving = state;
-		state = "closed";
-		deps.stopDispatchBoardTicker();
-		handle?.hide();
-		handle = null;
+		const leavingHandle = handle;
+		const restoring = leaving === "permission-confirm" ? interrupted : null;
+		interrupted = null;
+		state = restoring?.state ?? "closed";
+		handle = restoring?.handle ?? null;
+		if (restoring === null) deps.stopDispatchBoardTicker();
+		leavingHandle?.hide();
 		if (leaving === "permission-confirm") deps.onPermissionOverlayClosed();
 		else deps.onOverlayClosed?.();
+		restoring?.handle?.focus();
 		deps.renderContextIsland();
 		deps.renderTaskIsland();
 		deps.requestRender();

package/src/interactive/overlays/agents.ts

@@ -60,6 +60,7 @@ export function openAgentsOverlay(tui: TUI, ctx: SlashCommandContext, onClose: (
 	const items = [...fleetItems, ...delegationItems];
 
 	return openListOverlay(tui, {
+		markerId: "agents",
 		title: "Agents Reference",
 		items,
 		filterable: true,

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

@@ -18,7 +18,13 @@ 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, type HintEntry, showClioOverlayFrame } from "../overlay-frame.js";
+import {
+	buildHint,
+	DEFAULT_SELECT_THEME,
+	type HintEntry,
+	type OverlayEscVerb,
+	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";
 
@@ -91,6 +97,8 @@ 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;
+/** Below this the second column is too narrow to wrap a sentence into. */
+const MIN_DESCRIPTION_COLUMN = 28;
 const ELLIPSIS = "…";
 
 /**
@@ -511,16 +519,24 @@ class AskUserOverlayView implements Component {
 			this.presentation.requiredActions.find((action) => action.id === "record-answer")?.label.toLowerCase() ??
 			"record answer";
 		if (state.mode === "text") {
+			// Esc means two different things depending on what is behind the field.
+			// A question with options has a list to fall back to, so the key goes
+			// back; a question without one has nothing behind it and the key still
+			// leaves the interview. The footer says which one this is.
+			const escapeVerb: OverlayEscVerb = questionHasOptions(question) ? "back" : "close";
 			return this.questions.length > 1
-				? this.withScrollHint([
-						{ key: "Enter", verb: recordAnswer },
-						{ key: "Alt+Left/Right", verb: "question" },
-					])
-				: this.withScrollHint([{ key: "Enter", verb: recordAnswer }]);
+				? this.withScrollHint(
+						[
+							{ key: "Enter", verb: recordAnswer },
+							{ key: "Alt+Left/Right", verb: "question" },
+						],
+						escapeVerb,
+					)
+				: this.withScrollHint([{ key: "Enter", verb: recordAnswer }], escapeVerb);
 		}
 		// 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.
+		// granting authority. Esc on the option list is the way out of the whole
+		// interview, which is the one place the product spells `close`.
 		// `t` is on every select footer because the operator cannot tell from a
 		// label whether the option needs a figure attached until they read it.
 		const addText: HintEntry = { key: "t", verb: "add text", short: "text" };
@@ -558,9 +574,9 @@ class AskUserOverlayView implements Component {
 	 * 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 withScrollHint(entries: ReadonlyArray<HintEntry>, esc: OverlayEscVerb = "close"): string {
+		if (this.surface !== "interview" || !this.contentOverflows) return buildHint(entries, esc);
+		return buildHint([...entries, { key: "PgUp/PgDn", verb: "scroll" }], esc);
 	}
 
 	private setSurface(next: AskUserSurface): void {
@@ -784,17 +800,29 @@ class AskUserOverlayView implements Component {
 			0,
 			items.findIndex((item) => item.value === selectedItem.value),
 		);
-		const visibleCount = Math.min(this.maxVisibleOptions(), Math.max(1, items.length));
+		const primaryColumnWidth = this.primaryColumnWidth(items, width);
+		const acceptKey = question.multi_select === true ? "Space" : "Enter";
+		// The focused option's description wraps in full, so the rows it needs come
+		// out of the list rather than out of the sentence. Options the operator
+		// cannot currently read are what a windowed list is for, and one arrow key
+		// brings any of them back; a cut explanation has no such recovery.
+		const focusedRows = this.renderOptionRow(
+			items[selectedIndex] as SelectItem,
+			true,
+			width,
+			primaryColumnWidth,
+			acceptKey,
+		).length;
+		const budget = Math.max(1, this.maxVisibleOptions() - (focusedRows - 1));
+		const visibleCount = Math.min(budget, Math.max(1, items.length));
 		const start = Math.max(0, Math.min(selectedIndex - Math.floor(visibleCount / 2), items.length - visibleCount));
 		const end = Math.min(items.length, start + visibleCount);
-		const primaryColumnWidth = this.primaryColumnWidth(items, width);
 		const lines: string[] = [];
 
-		const acceptKey = question.multi_select === true ? "Space" : "Enter";
 		for (let index = start; index < end; index += 1) {
 			const item = items[index];
 			if (!item) continue;
-			lines.push(this.renderOptionRow(item, index === selectedIndex, width, primaryColumnWidth, acceptKey));
+			lines.push(...this.renderOptionRow(item, index === selectedIndex, width, primaryColumnWidth, acceptKey));
 		}
 
 		if (start > 0 || end < items.length) {
@@ -809,13 +837,22 @@ class AskUserOverlayView implements Component {
 		return Math.max(1, Math.min(bounded, Math.max(1, width - 4)));
 	}
 
+	/**
+	 * One option, as the rows it needs.
+	 *
+	 * The focused option's description wraps under its own column and is never
+	 * cut: a description is what the operator is choosing between, and half of
+	 * one reads as the whole thing. An unfocused row stays a one-line table cell
+	 * whose ellipsis says there is more, which the operator reads by moving to
+	 * it.
+	 */
 	private renderOptionRow(
 		item: SelectItem,
 		selected: boolean,
 		width: number,
 		primaryColumnWidth: number,
 		acceptKey: string,
-	): string {
+	): string[] {
 		const theme = clioTheme();
 		const prefix = selected ? theme.fg("accent", `${GLYPH.cursor} `) : "  ";
 		// The key that answers rides on the focused row. An operator whose eyes are
@@ -825,22 +862,40 @@ class AskUserOverlayView implements Component {
 		const available = Math.max(1, width - 2 - visibleWidth(affordance));
 		const description = item.description?.replace(/[\r\n]+/g, " ").trim();
 
-		let body: string;
-		if (description && width > 40) {
-			const labelWidth = Math.max(1, Math.min(primaryColumnWidth - 2, available - 4));
-			const label = truncateToWidth(item.label, labelWidth, ELLIPSIS, false);
-			const spacing = " ".repeat(Math.max(1, primaryColumnWidth - visibleWidth(label)));
-			const descriptionWidth = Math.max(1, available - visibleWidth(label) - visibleWidth(spacing));
-			const desc = truncateToWidth(description, descriptionWidth, ELLIPSIS, false);
-			body = selected
-				? theme.style("accent", `${label}${spacing}${desc}`, { bold: true })
-				: `${label}${theme.fg("muted", `${spacing}${desc}`)}`;
-		} else {
+		if (!description || width <= 40) {
 			const label = truncateToWidth(item.label, available, ELLIPSIS, false);
-			body = selected ? theme.style("accent", label, { bold: true }) : label;
+			const body = selected ? theme.style("accent", label, { bold: true }) : label;
+			return [fitLine(`${prefix}${body}${affordance}`, width)];
 		}
 
-		return fitLine(`${prefix}${body}${affordance}`, width);
+		const labelWidth = Math.max(1, Math.min(primaryColumnWidth - 2, available - 4));
+		const label = truncateToWidth(item.label, labelWidth, ELLIPSIS, false);
+		const spacing = " ".repeat(Math.max(1, primaryColumnWidth - visibleWidth(label)));
+		const descriptionWidth = Math.max(1, available - visibleWidth(label) - visibleWidth(spacing));
+		if (!selected) {
+			const desc = truncateToWidth(description, descriptionWidth, ELLIPSIS, false);
+			return [fitLine(`${prefix}${label}${theme.fg("muted", `${spacing}${desc}`)}`, width)];
+		}
+		// A gutter this narrow wraps a sentence into slivers and breaks words, so
+		// below the floor the description drops to its own full-width lines under
+		// the label instead of squeezing into the second column.
+		if (descriptionWidth < MIN_DESCRIPTION_COLUMN) {
+			const indent = "    ";
+			const body = theme.style("accent", label, { bold: true });
+			return [
+				fitLine(`${prefix}${body}${affordance}`, width),
+				...wrapTextWithAnsi(description, Math.max(1, width - indent.length)).map((line) =>
+					fitLine(`${indent}${theme.style("accent", line, { bold: true })}`, width),
+				),
+			];
+		}
+		const wrapped = wrapTextWithAnsi(description, descriptionWidth);
+		const head = wrapped[0] ?? "";
+		const indent = " ".repeat(visibleWidth(prefix) + visibleWidth(label) + visibleWidth(spacing));
+		return [
+			fitLine(`${prefix}${theme.style("accent", `${label}${spacing}${head}`, { bold: true })}${affordance}`, width),
+			...wrapped.slice(1).map((line) => fitLine(`${indent}${theme.style("accent", line, { bold: true })}`, width)),
+		];
 	}
 
 	private ensureControl(): void {
@@ -889,7 +944,7 @@ class AskUserOverlayView implements Component {
 			state.answer = questionHasOptions(question) ? answerText(question, state.selected, state.customAnswer) : answer;
 			this.finishIfCompleteOrAdvance();
 		};
-		activeInput.onEscape = () => this.cancel();
+		activeInput.onEscape = () => this.escapeFromTextInput(question, state);
 		this.input = activeInput;
 		this.list = null;
 	}
@@ -960,6 +1015,53 @@ class AskUserOverlayView implements Component {
 		return 0;
 	}
 
+	/**
+	 * Esc in the text field.
+	 *
+	 * The field used to resolve the whole round as cancelled, which made a typed
+	 * draft unrecoverable: a single-question round had no other question to answer
+	 * first, so the only way off `t` was to abandon the interview (issue #260). A
+	 * question with options has a surface behind the field, so Esc goes back to it
+	 * and drops the draft. A question with no options has nothing behind it, so Esc
+	 * keeps its old meaning and leaves the interview; the footer says which.
+	 *
+	 * The draft is dropped rather than parked because Esc is the discard gesture.
+	 * It never reached `answer`, `options`, or `value` in the first place, since
+	 * only a submit writes those, so #228's clearing rule holds either way.
+	 */
+	private escapeFromTextInput(question: AskUserQuestion, state: QuestionState): void {
+		if (!questionHasOptions(question)) {
+			this.cancel();
+			return;
+		}
+		state.inputValue = "";
+		state.mode = "select";
+		this.status = "";
+		this.rebuildSelectList(question, state);
+		this.deps.requestRender();
+	}
+
+	/**
+	 * Leave a question the operator is walking away from on its option list.
+	 *
+	 * The mode used to belong to the question for the rest of the round, so a
+	 * question opened with `t` came back as a prefilled field however the operator
+	 * returned to it, and the option list was gone for good. Navigating away is not
+	 * the discard gesture, so the draft stays in `inputValue` and `t` finds it
+	 * again; what does not survive is the field being the thing that greets them.
+	 *
+	 * A question whose value was actually submitted keeps its field, because
+	 * coming back to a recorded figure is how it gets revised (issue #228).
+	 */
+	private parkTextMode(): void {
+		const question = this.currentQuestion();
+		const state = this.currentState();
+		if (!question || !state) return;
+		if (state.mode !== "text" || !questionHasOptions(question)) return;
+		if (state.rawValue.length > 0) return;
+		state.mode = "select";
+	}
+
 	private openTextInput(nextStatus: string): void {
 		const state = this.currentState();
 		const question = this.currentQuestion();
@@ -1077,6 +1179,7 @@ class AskUserOverlayView implements Component {
 	private goToRelativeQuestion(delta: -1 | 1): void {
 		if (this.questions.length <= 1) return;
 		this.syncActiveControl();
+		this.parkTextMode();
 		this.index = (this.index + delta + this.questions.length) % this.questions.length;
 		this.status = "";
 		this.resetContentScroll();
@@ -1128,6 +1231,9 @@ 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,
+			// Not derived from the title: this modal swaps between a waiting title
+			// and a classified decision title without ever changing hands.
+			markerId: "ask-user",
 			title: () => (view.isDecisionPending() ? view.decisionTitle() : ASK_USER_WAITING_TITLE),
 			tone: () => (view.isDecisionPending() ? view.decisionTone() : undefined),
 			footerHint: () => view.footerHint(),

package/src/interactive/overlays/auth-dialog.ts

@@ -211,6 +211,7 @@ export function openAuthDialog(tui: TUI, title: string, onCancel: () => void): A
 	const handle = showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: AUTH_DIALOG_WIDTH,
+		markerId: "auth",
 		title: "Authentication",
 		footerHint: getHint,
 	});

package/src/interactive/overlays/context-reset.ts

@@ -102,6 +102,7 @@ export function openContextResetOverlay(tui: TUI, deps: OpenContextResetOverlayD
 	return showClioOverlayFrame(tui, new FocusBox(list), {
 		anchor: "center",
 		width: CONTEXT_RESET_OVERLAY_WIDTH,
+		markerId: "context-reset",
 		title: "Reset Project Context",
 		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
 	});

package/src/interactive/overlays/cwd-fallback.ts

@@ -135,6 +135,7 @@ export function openCwdFallbackOverlay(tui: TUI, deps: OpenCwdFallbackOverlayDep
 	return showClioOverlayFrame(tui, box, {
 		anchor: "center",
 		width: CWD_FALLBACK_OVERLAY_WIDTH,
+		markerId: "cwd-fallback",
 		title: "Session Working Directory",
 		footerHint: buildHint([{ key: "Enter", verb: "select" }]),
 	});

package/src/interactive/overlays/decisions.ts

@@ -94,22 +94,21 @@ function decisionLines(decision: DecisionRecord, selected: boolean, expanded: bo
 	const label = decision.status === "superseded" ? theme.fg("dim", labelText) : theme.fg("muted", labelText);
 	const value = decision.status === "superseded" ? theme.fg("dim", decision.value) : decision.value;
 	const lines = [fitLine(`${cursor} ${status} ${label}${theme.fg("dim", ":")} ${value}`, width)];
+	// The indent belongs to the container, so this text wraps inside what is left
+	// of the row. Wrapping to the full width and then indenting cost every line
+	// its last six columns to a cut that landed mid-sentence.
+	const indent = "      ";
+	const indented = Math.max(1, width - indent.length);
+	const wrapIndented = (text: string): string[] =>
+		wrapTextWithAnsi(text, indented).map((line) => fitLine(`${indent}${line}`, width));
 	if (decision.status === "superseded" && decision.correction) {
-		lines.push(fitLine(`      ${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`, width));
+		lines.push(...wrapIndented(`${theme.fg("dim", "correction")} ${theme.fg("muted", decision.correction)}`));
 	}
 	if (selected && expanded) {
 		if (decision.source_question) {
-			lines.push(
-				...wrapTextWithAnsi(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`, width).map(
-					(line) => fitLine(`      ${line}`, width),
-				),
-			);
+			lines.push(...wrapIndented(`${theme.fg("dim", "question")} ${theme.fg("muted", decision.source_question)}`));
 		}
-		lines.push(
-			...wrapTextWithAnsi(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`, width).map((line) =>
-				fitLine(`      ${line}`, width),
-			),
-		);
+		lines.push(...wrapIndented(`${theme.fg("dim", "answer")} ${theme.fg("muted", decision.value)}`));
 	}
 	return lines;
 }
@@ -296,6 +295,7 @@ export function openDecisionsOverlay(
 	return showClioOverlayFrame(tui, body, {
 		anchor: "center",
 		width: DECISIONS_OVERLAY_WIDTH,
+		markerId: "decisions",
 		title: () => "Decisions",
 		footerHint: () => body.footerHint(),
 	});

package/src/interactive/overlays/extensions.ts

@@ -45,6 +45,7 @@ export function openExtensionsOverlay(tui: TUI, ctx: SlashCommandContext, onClos
 	});
 
 	return openListOverlay(tui, {
+		markerId: "extensions",
 		title: "Extensions Reference",
 		items,
 		filterable: true,

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

@@ -191,6 +191,7 @@ export function openFleetRunApprovalOverlay(tui: TUI, options: OpenFleetRunAppro
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: fleetRunApprovalOverlayWidth(options.columns),
+		markerId: "fleet-run-approval",
 		title: FLEET_RUN_APPROVAL_OVERLAY_TITLE,
 		footerHint: buildResponsiveHint(
 			[...(acceptable ? [{ key: "Enter", verb: "dispatch" }] : []), { key: "↑↓", verb: "scroll" }],

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

@@ -163,6 +163,7 @@ export function openHandoffReviewOverlay(
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: handoffReviewOverlayWidth(options.columns),
+		markerId: "handoff-review",
 		title: HANDOFF_REVIEW_OVERLAY_TITLE,
 		footerHint: buildResponsiveHint(
 			[

package/src/interactive/overlays/help-reference.ts

@@ -94,6 +94,7 @@ export function openHelpOverlay(
 			detail: () => [
 				"# Fleet runs & steering",
 				"**Fleet Runs board**: open it with the configured Dispatch Board key (Alt+W by default). Use Up/Down or `j`/`k` to select a live or recent run.",
+				"**Enter**: on a live run in a `--with-panes` session, Enter opens (or retargets) the watch pane beside Clio, rendering that run's stream; the arrow keys then move it between runs. On a finished run, or without panes, Enter toggles the inline worker-progress detail instead.",
 				"**Steer**: press `s` on a live native run to close the board and prefill `@<runId> `. Add guidance and submit it normally. The first notice means queued; a received notice confirms worker delivery.",
 				"**Cancel**: press `x` on a running, stale, queued, or retry-waiting run. The row changes to cancelling while the worker or retry is being stopped.",
 				"**Capabilities**: ACP delegation runs cannot accept live steering. The board footer only advertises actions supported by the selected row.",
@@ -140,6 +141,7 @@ export function openHelpOverlay(
 	const items = [...commands, ...keys, ...topics];
 
 	return openListOverlay(tui, {
+		markerId: "help",
 		title: "Help Center",
 		items,
 		filterable: true,

package/src/interactive/overlays/interop.ts

@@ -120,6 +120,7 @@ export function openInteropOverlay(tui: TUI, ctx: SlashCommandContext, onClose:
 	};
 
 	const handle: ListOverlayHandle = openListOverlay(tui, {
+		markerId: "interop",
 		title: "Interop",
 		items: buildItems(deps),
 		filterable: true,

package/src/interactive/overlays/library-install-confirm.ts

@@ -137,6 +137,7 @@ export function openLibraryInstallConfirmOverlay(
 	const handle = showClioOverlayFrame(tui, focus, {
 		anchor: "center",
 		width: confirmOverlayWidth(options.columns),
+		markerId: "library-install",
 		title: LIBRARY_INSTALL_CONFIRM_TITLE,
 		footerHint: buildResponsiveHint([{ key: "Enter", verb: "install" }], { key: "Esc", verb: "cancel" }),
 	});