@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/extensions/question/tools.ts

@@ -6,8 +6,9 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { askHuman } from "../../lib/interaction.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
-import { reuseText, toolDetails } from "../../lib/tui.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { ASK_USER_QUESTION_TOOL } from "../../lib/tool-names.ts";
 import { UNAVAILABLE_TEXT, formatAnswerText, optionSummary, questionHeaders, unavailableResult } from "./answers.ts";
 import { askViaDialogs, type QuestionUI } from "./dialogs.ts";
@@ -69,16 +70,21 @@ export function registerTools(pi: ExtensionAPI): void {
 		},
 
 		renderCall(args, theme, context) {
-			const raw = (args as Partial<AskUserQuestionArgs>).questions ?? [];
-			const count = raw.length;
+			// The args stream in: `questions` can be absent, and an option can arrive
+			// before its label. Read a partial call as a smaller summary and never
+			// throw — a throwing renderer makes Pi fall back to its own call line.
+			const raw = (args as Partial<AskUserQuestionArgs> | undefined)?.questions;
+			const questions = Array.isArray(raw) ? raw : [];
+			const count = questions.length;
 			const noun = count === 1 ? "question" : "questions";
-			const headers = questionHeaders(raw);
-			let text = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("muted", `${count} ${noun}`);
-			if (headers.length > 0) text += theme.fg("dim", ` (${headers.join(", ")})`);
+			const headers = questionHeaders(questions);
+			let text = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "meta", `${count} ${noun}`);
+			if (headers.length > 0) text += paint(theme, "faint", ` (${headers.join(", ")})`);
 
-			// One indented line per question that offers options, so a long option list
-			// stays mapped to its question instead of wrapping on a single row.
-			for (const line of optionSummary(raw)) text += `\n${theme.fg("dim", `  ${line}`)}`;
+			// One line per question that offers options, so a long option list stays
+			// mapped to its question instead of wrapping on a single row. The line
+			// carries no indent of its own; the tool-block frame supplies it.
+			for (const line of optionSummary(questions)) text += `\n${paint(theme, "meta", line)}`;
 
 			const component = reuseText(context?.lastComponent);
 			component.setText(text);
@@ -94,26 +100,26 @@ export function registerTools(pi: ExtensionAPI): void {
 				return component;
 			}
 			if (details.unavailable) {
-				component.setText(theme.fg("dim", UNAVAILABLE_TEXT));
+				component.setText(paint(theme, "faint", UNAVAILABLE_TEXT));
 				return component;
 			}
 			if (details.answers.length === 0) {
-				component.setText(theme.fg("warning", "Cancelled"));
+				component.setText(paint(theme, "warn", "Cancelled"));
 				return component;
 			}
 
 			const lines = details.answers.map((answer) => {
-				const header = theme.fg("accent", sanitizeLine(answer.header));
+				const header = paint(theme, "accent", sanitizeLine(answer.header));
 				if (answer.wasCustom) {
 					const values = answer.values.map((value) => sanitizeLine(value)).join("; ");
-					return `${theme.fg("success", `${GLYPHS.check} `)}${header}: ${theme.fg("muted", "(wrote) ")}${values}`;
+					return `${paint(theme, "ok", `${GLYPHS.check} `)}${header}: ${paint(theme, "meta", "(wrote) ")}${values}`;
 				}
 				const numbered = answer.labels
 					.map((label, i) => `${answer.indices?.[i] ?? "?"}. ${sanitizeLine(label)}`)
 					.join(", ");
-				return `${theme.fg("success", `${GLYPHS.check} `)}${header}: ${numbered}`;
+				return `${paint(theme, "ok", `${GLYPHS.check} `)}${header}: ${numbered}`;
 			});
-			if (details.cancelled) lines.push(theme.fg("warning", "(cancelled)"));
+			if (details.cancelled) lines.push(paint(theme, "warn", "(cancelled)"));
 			// A blank line separates the call header from a multi-line answer body.
 			component.setText(lines.length > 1 ? `\n${lines.join("\n")}` : lines.join("\n"));
 			return component;

package/extensions/question/tui.ts

@@ -6,11 +6,23 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Editor, Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import {
+	Editor,
+	Key,
+	matchesKey,
+	visibleWidth,
+	wrapTextWithAnsi,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+} from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
-import { selectionMarker } from "../../lib/list-cursor.ts";
-import { editorTheme, screenHint } from "../../lib/tui.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { flowCells } from "../../lib/tui/columns.ts";
+import { clampScroll, formatRange, keepVisible, selectionMarker, wheelDelta } from "../../lib/tui/cursor.ts";
+import { editorTheme, screenHint } from "../../lib/tui/chrome.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { checkbox } from "../../lib/tui/rows.ts";
+import { plainRule, titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import { OTHER_LABEL, cancelledResult, collectAnswers, completedResult, describeSelection } from "./answers.ts";
 import {
 	allAnswered,
@@ -29,35 +41,14 @@ type Outcome =
 	| { type: "cancelled"; selections: Map<string, Selection> }
 	| { type: "submitted"; selections: Map<string, Selection> };
 
-/**
- * Lay atomic, ANSI-styled cells onto lines no wider than `width`.
- *
- * Cells are never split: a cell that would not fit moves to the next line, and
- * a cell wider than the whole viewport is truncated. This keeps tab labels and
- * the submit arrow intact instead of letting `wrapTextWithAnsi` break them
- * mid-token.
- */
-function layoutCells(cells: string[], width: number): string[] {
-	const lines: string[] = [];
-	let current = "";
-	let currentWidth = 0;
-	for (const cell of cells) {
-		let text = cell;
-		let cellWidth = visibleWidth(cell);
-		if (cellWidth > width) {
-			text = truncateToWidth(cell, width);
-			cellWidth = visibleWidth(text);
-		}
-		if (currentWidth > 0 && currentWidth + cellWidth > width) {
-			lines.push(current);
-			current = "";
-			currentWidth = 0;
-		}
-		current += text;
-		currentWidth += cellWidth;
+/** Index of the option block containing line `line`, given each block's first line. */
+function blockAt(offsets: number[], line: number): number {
+	let index = 0;
+	for (let i = 0; i < offsets.length; i++) {
+		if (offsets[i] > line) break;
+		index = i;
 	}
-	lines.push(current);
-	return lines;
+	return index;
 }
 
 function mapKey(data: string): KeyAction | undefined {
@@ -82,9 +73,18 @@ export async function askViaTui(
 	const outcome = await ctx.ui.custom<Outcome>((tui, theme, _keybindings, done) => {
 		let state: TuiState = initialState(questions);
 		let cachedWidth: number | undefined;
+		let cachedRows: number | undefined;
 		let cachedLines: string[] | undefined;
+		/** First visible line of the option list, when it is clipped. */
+		let optionsScroll = 0;
 		let settled = false;
 
+		/** Live terminal height, or undefined when the host does not report one. */
+		const terminalRows = (): number | undefined => {
+			const rows = tui.terminal?.rows;
+			return typeof rows === "number" && Number.isFinite(rows) && rows > 0 ? rows : undefined;
+		};
+
 		/** Snapshot the answers recorded so far, for submit or partial cancel. */
 		const selectionMap = (): Map<string, Selection> => new Map(Object.entries(state.selections));
 
@@ -109,6 +109,7 @@ export async function askViaTui(
 
 		const refresh = (): void => {
 			cachedWidth = undefined;
+			cachedRows = undefined;
 			cachedLines = undefined;
 			tui.requestRender();
 		};
@@ -160,7 +161,8 @@ export async function askViaTui(
 
 		function render(width: number): string[] {
 			syncEditorFocus();
-			if (cachedLines && cachedWidth === width) return cachedLines;
+			const rows = terminalRows();
+			if (cachedLines && cachedWidth === width && cachedRows === rows) return cachedLines;
 
 			const lines: string[] = [];
 			const renderWidth = Math.max(1, width);
@@ -168,48 +170,56 @@ export async function askViaTui(
 			const isMulti = questions.length > 1;
 			const submitTab = state.tab >= questions.length;
 
-			const addWrapped = (text: string): void => {
-				lines.push(...wrapTextWithAnsi(text, renderWidth));
-			};
-			const addWithPrefix = (prefix: string, text: string): void => {
+			/** Wrap `text` under `prefix`; only the first line carries the prefix. */
+			const prefixWrapped = (prefix: string, text: string): string[] => {
 				const prefixWidth = visibleWidth(prefix);
-				if (prefixWidth >= renderWidth) {
-					addWrapped(prefix + text);
-					return;
-				}
+				if (prefixWidth >= renderWidth) return wrapTextWithAnsi(prefix + text, renderWidth);
 				const wrapped = wrapTextWithAnsi(text, renderWidth - prefixWidth);
 				const continuation = " ".repeat(prefixWidth);
-				for (let i = 0; i < wrapped.length; i++) {
-					lines.push(`${i === 0 ? prefix : continuation}${wrapped[i]}`);
-				}
+				return wrapped.map((line, index) => `${index === 0 ? prefix : continuation}${line}`);
+			};
+			const addWithPrefix = (prefix: string, text: string): void => {
+				lines.push(...prefixWrapped(prefix, text));
 			};
 
-			function renderOptions(target: Question): void {
+			/** One block of lines per option, so the option list can be windowed. */
+			const renderOptionBlocks = (target: Question): string[][] => {
 				const selection = state.selections[target.id];
 				const chosen = selection?.type === "options" ? selection.indices : [];
 				const count = optionCount(target);
+				const blocks: string[][] = [];
 				for (let i = 0; i < count; i++) {
 					const option = target.options[i];
 					const active = i === state.cursor;
 					const prefix = selectionMarker(theme, active);
 					if (!option) {
 						const otherSelected = selection?.type === "custom";
-						const otherMarker = target.multiSelect ? `[${otherSelected ? "x" : " "}] ` : "";
-						const label = `${i + 1}. ${otherMarker}${OTHER_LABEL}${state.editing ? " ✎" : ""}`;
-						addWithPrefix(prefix, theme.fg(active || state.editing ? "accent" : "text", label));
+						const box = target.multiSelect ? `${checkbox(theme, otherSelected)} ` : "";
+						const tone = active || state.editing ? "accent" : "label";
+						blocks.push(
+							prefixWrapped(
+								prefix,
+								paint(theme, tone, `${i + 1}. `) +
+									box +
+									paint(theme, tone, `${OTHER_LABEL}${state.editing ? " ✎" : ""}`),
+							),
+						);
 						continue;
 					}
-					const marker = target.multiSelect ? `[${chosen.includes(i + 1) ? "x" : " "}] ` : "";
+					const marker = target.multiSelect ? `${checkbox(theme, chosen.includes(i + 1))} ` : "";
 					const label = sanitizeLine(option.label);
-					addWithPrefix(prefix, theme.fg(active ? "accent" : "text", `${i + 1}. ${marker}${label}`));
+					const tone = active ? "accent" : "label";
+					const block = prefixWrapped(prefix, paint(theme, tone, `${i + 1}. `) + marker + paint(theme, tone, label));
 					if (option.description) {
 						const indent = " ".repeat(visibleWidth(prefix) + String(i + 1).length + 2 + visibleWidth(marker));
-						addWithPrefix(indent, theme.fg("muted", sanitizeLine(option.description)));
+						block.push(...prefixWrapped(indent, paint(theme, "meta", sanitizeLine(option.description))));
 					}
+					blocks.push(block);
 				}
-			}
+				return blocks;
+			};
 
-			lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+			lines.push(titleRule(theme, renderWidth, "Question"));
 
 			if (isMulti) {
 				const cells: string[] = [];
@@ -218,60 +228,63 @@ export async function askViaTui(
 					const active = i === state.tab;
 					const text = ` ${answered ? GLYPHS.boxOn : GLYPHS.boxOff} ${sanitizeLine(questions[i].header)} `;
 					const styled = active
-						? theme.bg("selectedBg", theme.fg("text", text))
-						: theme.fg(answered ? "success" : "muted", text);
+						? theme.bg("selectedBg", paint(theme, "label", text))
+						: paint(theme, answered ? "ok" : "meta", text);
 					// Keep the leading hint glued to the first tab so it never wraps alone.
-					cells.push(cells.length === 0 ? `${theme.fg("muted", `${GLYPHS.prev} `)}${styled} ` : `${styled} `);
+					cells.push(cells.length === 0 ? `${paint(theme, "meta", `${GLYPHS.prev} `)}${styled} ` : `${styled} `);
 				}
 				const canSubmit = allAnswered(state);
 				const submitText = ` ${GLYPHS.check} Submit `;
 				const submitStyled = submitTab
-					? theme.bg("selectedBg", theme.fg("text", submitText))
-					: theme.fg(canSubmit ? "success" : "dim", submitText);
+					? theme.bg("selectedBg", paint(theme, "label", submitText))
+					: paint(theme, canSubmit ? "ok" : "faint", submitText);
 				cells.push(`${submitStyled} ${GLYPHS.next}`);
-				for (const tabLine of layoutCells(cells, Math.max(1, renderWidth - 1))) lines.push(` ${tabLine}`);
+				for (const tabLine of flowCells(cells, Math.max(1, renderWidth - 1))) lines.push(` ${tabLine}`);
 				lines.push("");
 			}
 
 			if (state.editing && question) {
-				addWithPrefix(" ", theme.fg("text", sanitizeLine(question.question)));
+				addWithPrefix(" ", paint(theme, "label", sanitizeLine(question.question)));
 				lines.push("");
-				renderOptions(question);
+				lines.push(...renderOptionBlocks(question).flat());
 				lines.push("");
-				addWithPrefix(" ", theme.fg("muted", "Your answer:"));
+				addWithPrefix(" ", paint(theme, "meta", "Your answer:"));
 				const editorPad = renderWidth > 1 ? " " : "";
 				for (const line of editor.render(Math.max(1, renderWidth - 2))) {
 					lines.push(`${editorPad}${line}`);
 				}
 				lines.push("");
-				if (state.message) addWithPrefix(" ", theme.fg("warning", state.message));
+				if (state.message) addWithPrefix(" ", paint(theme, "warn", state.message));
 				lines.push(screenHint(theme, renderWidth, ["Enter to submit", "Esc to go back"]));
 			} else if (submitTab) {
-				addWithPrefix(" ", theme.fg("accent", theme.bold("Ready to submit")));
+				addWithPrefix(" ", paint(theme, "accent", theme.bold("Ready to submit")));
 				lines.push("");
 				for (const target of questions) {
 					addWithPrefix(
 						" ",
-						`${theme.fg("muted", `${sanitizeLine(target.header)}: `)}${theme.fg("text", sanitizeLine(describeSelection(state.selections[target.id])))}`,
+						`${paint(theme, "meta", `${sanitizeLine(target.header)}: `)}${paint(theme, "label", sanitizeLine(describeSelection(state.selections[target.id])))}`,
 					);
 				}
 				lines.push("");
-				if (state.message) addWithPrefix(" ", theme.fg("warning", state.message));
+				if (state.message) addWithPrefix(" ", paint(theme, "warn", state.message));
 				if (allAnswered(state)) {
-					addWithPrefix(" ", theme.fg("success", "Press Enter to submit"));
+					addWithPrefix(" ", paint(theme, "ok", "Press Enter to submit"));
 				} else {
 					const missing = questions
 						.filter((target) => state.selections[target.id] === undefined)
 						.map((target) => sanitizeLine(target.header))
 						.join(", ");
-					addWithPrefix(" ", theme.fg("warning", `Unanswered: ${missing}`));
+					addWithPrefix(" ", paint(theme, "warn", `Unanswered: ${missing}`));
 				}
 			} else if (question) {
-				addWithPrefix(" ", theme.fg("text", sanitizeLine(question.question)));
+				addWithPrefix(" ", paint(theme, "label", sanitizeLine(question.question)));
 				lines.push("");
-				renderOptions(question);
-				lines.push("");
-				if (state.message) addWithPrefix(" ", theme.fg("warning", state.message));
+				const blocks = renderOptionBlocks(question);
+
+				// Everything after the options is fixed chrome; build it first so the
+				// option list can be given exactly the rows that are left.
+				const tail: string[] = [""];
+				if (state.message) tail.push(...prefixWrapped(" ", paint(theme, "warn", state.message)));
 				const hints =
 					optionCount(question) === 0
 						? ["Enter to type an answer", "Esc cancel"]
@@ -279,19 +292,53 @@ export async function askViaTui(
 							? ["↑/↓ move", "Space toggle", "Enter confirm", "Esc cancel"]
 							: ["↑/↓ choose", "Enter select", "Esc cancel"];
 				if (isMulti) hints.unshift(`Tab/${GLYPHS.prev}${GLYPHS.next} navigate`);
-				lines.push(screenHint(theme, renderWidth, hints));
+				tail.push(screenHint(theme, renderWidth, hints));
 				if (question.multiSelect) {
 					const selection = state.selections[question.id];
 					if (selection?.type === "options" && selection.labels.length > 0) {
-						addWithPrefix(" ", theme.fg("success", `Selected: ${selection.labels.map(sanitizeLine).join(", ")}`));
+						tail.push(
+							...prefixWrapped(" ", paint(theme, "ok", `Selected: ${selection.labels.map(sanitizeLine).join(", ")}`)),
+						);
 					} else if (selection?.type === "custom") {
-						addWithPrefix(" ", theme.fg("success", `Selected: ${sanitizeLine(selection.text)}`));
+						tail.push(...prefixWrapped(" ", paint(theme, "ok", `Selected: ${sanitizeLine(selection.text)}`)));
 					}
 				}
+
+				// Window the option list into the rows left after the fixed chrome and the
+				// closing rule. The focused option stays visible; a clipped list says which
+				// options it is showing rather than silently dropping the tail.
+				const flat = blocks.flat();
+				const fixed = lines.length + tail.length + 1;
+				const budget = rows === undefined ? Number.POSITIVE_INFINITY : Math.max(1, rows - fixed);
+				if (flat.length > budget) {
+					const usable = Math.max(1, budget - 1);
+					const offsets: number[] = [];
+					let offset = 0;
+					for (const block of blocks) {
+						offsets.push(offset);
+						offset += block.length;
+					}
+					const focusLine = offsets[Math.min(state.cursor, offsets.length - 1)] ?? 0;
+					optionsScroll = clampScroll(keepVisible(optionsScroll, focusLine, usable), flat.length, usable);
+					const end = Math.min(flat.length, optionsScroll + usable);
+					lines.push(...flat.slice(optionsScroll, end));
+					lines.push(
+						formatRange(theme, renderWidth, {
+							start: blockAt(offsets, optionsScroll),
+							end: blockAt(offsets, end - 1) + 1,
+							total: blocks.length,
+							label: "option",
+						}),
+					);
+				} else {
+					lines.push(...flat);
+				}
+				lines.push(...tail);
 			}
 
-			lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+			lines.push(plainRule(theme, renderWidth));
 			cachedWidth = width;
+			cachedRows = rows;
 			cachedLines = lines;
 			return lines;
 		}
@@ -300,9 +347,18 @@ export async function askViaTui(
 			render,
 			invalidate: () => {
 				cachedWidth = undefined;
+				cachedRows = undefined;
 				cachedLines = undefined;
 			},
 			handleInput,
+			handleMouse: (event: TuiMouseEvent): TuiMouseEventResult | undefined => {
+				const delta = wheelDelta(event);
+				if (delta === undefined) return undefined;
+				// The render clamps the scroll once it knows how many rows are left.
+				optionsScroll = Math.max(0, optionsScroll + delta);
+				refresh();
+				return { handled: true };
+			},
 			dispose: () => {
 				signal?.removeEventListener("abort", onAbort);
 				editor.focused = false;

package/extensions/rewind/README.md

@@ -10,6 +10,8 @@ rewind uses Pi's session tree, so the branch you leave is not erased.
 This is the `rewind` extension entrypoint; it is one of two sibling git
 extensions in this package (`worktree` is the other).
 
+<img src="../../assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%">
+
 ```
 pi --extension ./extensions/rewind   # load this extension alone
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package
@@ -197,6 +199,6 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `runtime.ts` | Root/config caches and the snapshot/list/plan/restore operations. |
 | `timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
 | `rewind.ts` | Scope choice, confirmation, and applying code + conversation rewind. |
-| `rewind-tui.ts` | The selectable, width-safe timeline component. |
+| `rewind-tui.ts` | The selectable, width-safe timeline component, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `commands.ts` | The `/rewind` command. |
 | `format.ts` | Model-facing and transcript text (pure). |

package/extensions/rewind/format.ts

@@ -8,7 +8,7 @@
 
 import { sliceByColumn, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import type { RestoreSummary } from "./types.ts";
 
 /** Longest prompt summary shown before truncation. */
@@ -28,8 +28,13 @@ function truncate(text: string, max = LABEL_WIDTH): string {
 /**
  * A short, single-line summary of a user prompt for storage and display.
  * Takes the first non-empty line, collapses whitespace, and truncates.
+ *
+ * A run started by a custom message (a wake) has no user prompt: `event.prompt`
+ * is typed `string` but is `undefined` there, so a missing prompt is accepted
+ * and yields no summary rather than throwing.
  */
-export function summarizePrompt(text: string): string | undefined {
+export function summarizePrompt(text: string | undefined): string | undefined {
+	if (typeof text !== "string") return undefined;
 	const line = text
 		.split(/\r?\n/)
 		.map((part) => sanitizeLine(part))
@@ -55,6 +60,34 @@ export function formatChangeSummary(changed: number, removed: number): string {
 	return removed > 0 ? `${changedText}, ${removed} created` : changedText;
 }
 
+/** The parts of one timeline row, for the shared list-row grammar. */
+export interface RewindRowParts {
+	/** The `⬥` snapshot marker, or a blank to keep the label column aligned. */
+	glyph: string;
+	/** The sanitized prompt summary. */
+	label: string;
+	/** The right-aligned relative time. */
+	trailing: string;
+}
+
+/**
+ * The timeline row's parts, composed by the screen through `listRow`.
+ * `formatRewindRow` below stays the plain-text form the headless listing uses;
+ * the screen wants the marker, colors, and column math of the shared grammar.
+ */
+export function formatRewindParts(
+	summary: string | undefined,
+	hasSnapshot: boolean,
+	timestamp: number,
+	now = Date.now(),
+): RewindRowParts {
+	return {
+		glyph: hasSnapshot ? GLYPHS.snapshot : " ",
+		label: sanitizeLine(summary || "(no text)"),
+		trailing: formatRelativeTime(timestamp, now),
+	};
+}
+
 /**
  * Id-free row for the rewind timeline: `⬥ "prompt"          2m ago`.
  * The leading glyph marks a point with a code snapshot; the time is

package/extensions/rewind/index.ts

@@ -37,7 +37,9 @@ export function registerRewind(pi: ExtensionAPI): void {
 	});
 
 	// A new prompt begins a task: the run resolves its snapshot decision up
-	// front, so the `tool_call` guard can stay synchronous.
+	// front, so the `tool_call` guard can stay synchronous. A run started by a
+	// custom message (a wake) has no user prompt — `event.prompt` is undefined
+	// there despite its type — so `beginRun` accepts a missing prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		await run.beginRun(event.prompt, ctx);
 	});