@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/lib/report.ts

@@ -2,23 +2,29 @@
  * The pending-report coordinator: how a live feature tells the model what
  * happened without interrupting it.
  *
- * A watcher match and a finished job follow one rule — report at the next turn,
- * and raise at most one triggered turn when the work opted into `wake`. The two
- * traps are subtle enough to have been re-derived once per extension:
+ * A watcher match, a finished job, and arriving mail follow one rule — report at
+ * the next turn, and raise at most one triggered turn per burst when the work
+ * opted into `wake`, as soon as the agent is idle. The three traps are subtle
+ * enough to have been re-derived once per extension:
  *
  * - a wake is only safe while the agent is idle, so an outcome that arrives
- *   mid-turn must be queued rather than sent;
+ *   mid-turn is queued rather than sent, and `agent_settled` retries it;
+ * - an outcome outlives the run it arrived in, so the retry asks
+ *   `wakeRequested()` rather than trusting the one call that queued it;
  * - between the triggered send and the `agent_start` it causes, the agent still
  *   looks idle, so a second outcome in that window must not trigger a second
  *   turn. `waking` closes that window.
  *
  * Delivery is one shared transcript notice per burst, and a burst is marked
  * reported only after the send succeeded, so a throw leaves it for the next
- * turn. Value-only: every flag lives in the returned closure, never in a module
- * variable, because each extension gets its own module instance.
+ * turn. `registerPendingChannel` is the other half: the seven host hooks that
+ * drive the machine, registered once for `job` and `watch` rather than copied
+ * into each factory. Value-only: every flag lives in the returned closure, never
+ * in a module variable, because each extension gets its own module instance.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { pruneStaleNotices, type NoticeMessage } from "./notice.ts";
 
 export interface PendingReporterOptions<T> {
@@ -30,6 +36,11 @@ export interface PendingReporterOptions<T> {
 	markReported(items: T[]): void;
 	/** Build the notice for one burst: model text plus renderer details. */
 	buildNotice(items: T[]): NoticeMessage;
+	/**
+	 * Whether any pending outcome asks for a triggered turn. Called by the settle
+	 * retry, so a mid-turn outcome still wakes once the agent is idle.
+	 */
+	wakeRequested(): boolean;
 	/** The notice's source, so only its own stale entries are pruned. */
 	source: string;
 	/** Runs after a wake turn was successfully requested, for an extra announcement. */
@@ -44,8 +55,8 @@ export interface PendingReporter {
 	sessionStart(): void;
 	/** A turn began: outcomes queue up, and none of them triggers a turn. */
 	agentStart(): void;
-	/** The turn settled: a later outcome may wake again. */
-	agentSettled(): void;
+	/** The turn settled: retry a wake it suppressed, unless it was aborted. */
+	agentSettled(event?: { aborted?: boolean }): void;
 	/** Report what is queued at the start of a turn, without triggering one. */
 	beforeAgentStart(): { message: NoticeMessage } | undefined;
 	/** Drop this source's older notices from the outgoing context. */
@@ -53,26 +64,29 @@ export interface PendingReporter {
 }
 
 export function createPendingReporter<T>(options: PendingReporterOptions<T>): PendingReporter {
-	const { wake, pending, markReported, buildNotice, source, onWoke } = options;
+	const { wake, pending, markReported, buildNotice, wakeRequested, source, onWoke } = options;
 	let busy = false;
 	let waking = false;
 
+	const report = (): void => {
+		if (busy || waking) return;
+		if (!wakeRequested()) return;
+		const items = pending();
+		if (items.length === 0) return;
+		try {
+			wake(buildNotice(items));
+		} catch {
+			// Reporting is best-effort; the next turn reports the same items.
+			return;
+		}
+		// Mark only after the send succeeded, so a throw changes nothing.
+		markReported(items);
+		waking = true;
+		onWoke?.(items);
+	};
+
 	return {
-		report: () => {
-			if (busy || waking) return;
-			const items = pending();
-			if (items.length === 0) return;
-			try {
-				wake(buildNotice(items));
-			} catch {
-				// Reporting is best-effort; the next turn reports the same items.
-				return;
-			}
-			// Mark only after the send succeeded, so a throw changes nothing.
-			markReported(items);
-			waking = true;
-			onWoke?.(items);
-		},
+		report,
 		sessionStart: () => {
 			busy = false;
 			waking = false;
@@ -80,9 +94,13 @@ export function createPendingReporter<T>(options: PendingReporterOptions<T>): Pe
 		agentStart: () => {
 			busy = true;
 		},
-		agentSettled: () => {
+		agentSettled: (event) => {
 			busy = false;
 			waking = false;
+			// An interrupted run is not a request to interrupt again; its outcomes
+			// stay queued for the next turn.
+			if (event?.aborted === true) return;
+			report();
 		},
 		beforeAgentStart: () => {
 			const items = pending();
@@ -97,3 +115,77 @@ export function createPendingReporter<T>(options: PendingReporterOptions<T>): Pe
 		},
 	};
 }
+
+/** The session-scoped state a channel drives, narrowed to what its hooks need. */
+export interface PendingChannelRuntime {
+	/**
+	 * Load this session's records on every session start. A promise is awaited, so a
+	 * runtime that resolves a repository or opens a store is fully loaded before the
+	 * report trigger is armed.
+	 */
+	load(ctx: ExtensionContext): void | Promise<void>;
+	/** Repaint the status chip; a runtime that publishes none omits it. */
+	setStatus?(ctx: ExtensionContext): void;
+	/** Release the session's resources; idempotent. */
+	shutdown(): Promise<void>;
+}
+
+export interface PendingChannelOptions {
+	/** The reporter that turns pending outcomes into notices. */
+	reporter: PendingReporter;
+	/** The runtime whose pending outcomes the notices describe. */
+	runtime: PendingChannelRuntime;
+	/** Runs on every session start, after the runtime loads: arm the report trigger. */
+	onSessionStart?(ctx: ExtensionContext): void;
+	/** Runs before the runtime releases: clear what `onSessionStart` armed. */
+	onSessionShutdown?(): void;
+}
+
+/**
+ * Wire a reporter to the host's session lifecycle.
+ *
+ * The order inside `session_start` is the contract: the reporter forgets the
+ * previous session's busy window, the runtime loads the records, and only then
+ * is the report trigger armed — a reload or a replaced session reuses the same
+ * runtime. A shutdown clears the trigger before the runtime releases the table it
+ * was calling into.
+ */
+export function registerPendingChannel(
+	pi: Pick<ExtensionAPI, "on">,
+	{ reporter, runtime, onSessionStart, onSessionShutdown }: PendingChannelOptions,
+): void {
+	pi.on("session_start", async (_event, ctx) => {
+		reporter.sessionStart();
+		await runtime.load(ctx);
+		onSessionStart?.(ctx);
+	});
+
+	// Tree navigation does not change the pending records; only repaint.
+	pi.on("session_tree", (_event, ctx) => {
+		runtime.setStatus?.(ctx);
+	});
+
+	pi.on("agent_start", () => {
+		reporter.agentStart();
+	});
+	pi.on("agent_settled", (event) => {
+		reporter.agentSettled(event);
+	});
+
+	// Report what is queued at the start of the next turn, without triggering one.
+	pi.on("before_agent_start", (_event, ctx) => {
+		const reported = reporter.beforeAgentStart();
+		if (!reported) return undefined;
+		runtime.setStatus?.(ctx);
+		return reported;
+	});
+
+	// Keep stale notices out of later turns. Only this source's notices are
+	// pruned; another source's are left for its own handler.
+	pi.on("context", (event) => reporter.filterContext(event.messages));
+
+	pi.on("session_shutdown", async () => {
+		onSessionShutdown?.();
+		await runtime.shutdown();
+	});
+}

package/lib/requirements.ts

@@ -19,7 +19,6 @@ import { configSection, configValueAt, type JsonReadResult, SHARED_CONFIG_FILE }
 import type { WebSearchProviderEvent } from "./events.ts";
 import { pdfGuidance } from "./pdf.ts";
 import { getPiInvocation, type PiInvocation } from "./pi-invocation.ts";
-
 /** How a check came out. Only `missing` is worth interrupting a session for. */
 export type FindingSeverity = "ok" | "missing" | "degraded" | "info";
 
@@ -216,7 +215,6 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		notes: ["Runs the project's detected command through a shell; a stack with no detector needs `check.command`."],
 	},
 	plan: {
-		optional: [gitCheck("project-local `.pi/plans` (otherwise plans land in the agent directory)")],
 		notes: ["Needs an interactive UI to enter plan mode."],
 	},
 	subagent: {
@@ -267,6 +265,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [gitCheck("project-scope memory under the repository root")],
 	},
 	context: {},
+	"session-bus": {},
 	wechat: {
 		optional: [
 			{

package/lib/tool-result.ts

@@ -1,17 +1,67 @@
 /**
- * The shared shape of a rejected tool call.
+ * The shared shape of a tool result.
  *
- * Extension tools return an `isError: true` result carrying their own `details`
- * type. `toolError` builds the content and the flag so the extensions that
- * reject a call (`job` and `watch`, plus any future tool) agree on the shape.
+ * Every extension tool returns the same envelope: one text block the model
+ * reads, the extension's own `details` for the renderer and the session branch,
+ * and — where the tool declares an `outputSchema` — the JSON mirror Pi calls
+ * `structuredContent`. A rejected call is that envelope marked `isError`, still
+ * carrying the previous state so the model can retry.
+ *
+ * `textResult` and `failedResult` build the two, so the flag and the absent
+ * `structuredContent` are decided once. What stays with the extension is the
+ * text and the mirror: `structuredContent` drops `undefined` field by field and
+ * projects nested objects, so it is written per `details` type rather than
+ * derived. `toolError` / `errorResult` keep the shorthand the
+ * action-and-message tools (`job` and `watch`) share.
  */
 
+import type { JsonValue } from "@earendil-works/pi-ai";
+
 /** One text block in a tool result. */
 export interface ToolErrorContent {
 	type: "text";
 	text: string;
 }
 
+/** A tool result: what the model reads, the extension's details, and its JSON mirror. */
+export interface ToolResult<Details> {
+	content: ToolErrorContent[];
+	details: Details;
+	structuredContent?: Record<string, JsonValue>;
+}
+
+/** A rejected call: the result, marked so the host reports it as an error. */
+export interface ToolFailure<Details> extends ToolResult<Details> {
+	isError: true;
+}
+
+/** The content and details both results share. */
+function envelope<Details>(text: string, details: Details): ToolResult<Details> {
+	return { content: [{ type: "text", text }], details };
+}
+
+/** A successful call. */
+export function textResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolResult<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined ? result : { ...result, structuredContent };
+}
+
+/** A rejected call, keeping the state the caller had before it. */
+export function failedResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolFailure<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined
+		? { ...result, isError: true }
+		: { ...result, structuredContent, isError: true };
+}
+
 /** A rejected tool call: the message as content, the extension's details, and the error flag. */
 export function toolError<Details extends { action: string; error: string }>(
 	message: string,

package/lib/tui/README.md

@@ -35,17 +35,24 @@ Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
 `fitCells` for two columns, `LinePane` for a scrollable log, `ListCursor` /
 `IdCursor` for selection, `byRunningFirst` for a live list's order,
 `DockListScreen` for a list that opens a pane, `TailResult` for a tool result
-that lists rows or tails output, and `ConfirmState` before a destructive action.
+that lists rows, heads several row sections, or tails output, `screenFooter` for a
+screen's own last three rows, and `ConfirmState` before a destructive action.
 
 ## Docked list screens
 
 Every list screen is `dockListFrame`: the header rule, an optional summary and
-its blank line, the body, an optional range row, an optional detail block, and
-the blank-padded hint. The frame owns that spacing, so a screen never hand-rolls
-it — including the blank line above the detail block, which keeps a footnote
-from reading as one more row. A screen that sizes its body through `fitRows`
-counts the block with `detailBlockRows`, or the hint row is pushed off the
-bottom of a short terminal.
+its blank line, the body, an optional range row, an optional detail block, the
+key-hint row, and the closing rule. The frame owns that spacing, so a screen
+never hand-rolls it — including the blank line above the detail block, which
+keeps a footnote from reading as one more row. A screen that sizes its body
+through `fitRows` counts the block with `detailBlockRows`, or the hint row is
+pushed off the bottom of a short terminal.
+
+The closing rule is not decoration: Pi's built-in selectors draw one under the
+list and over the footer, and the editor a docked screen replaces draws its own,
+so a screen that ends on a blank removes the dock's bottom edge. A screen that
+lays out its own rows closes its block with `screenFooter(theme, width, hint)`;
+a screen whose row above the hint varies places `plainRule` itself.
 
 A list that **opens a pane over one row** — `/jobs`, `/watch`, `/agents`,
 `/check` — subclasses [`dock-screen.ts`](./dock-screen.ts) instead of
@@ -74,6 +81,20 @@ what a plain list wants — do not hand-roll the frame to get one of them:
   (`c` collect, `x` cancel). Return `true` for the keys it claimed; everything
   else falls through to the pane's scroll keys.
 
+A pane is a log by default: it opens at the tail and its subtitle says
+`following` or `paused`. Two more fields cover the other body:
+
+- `DetailContents.text` — prose instead of `lines`, wrapped to the width the pane
+  renders at and re-wrapped on a resize. One source line is one paragraph; a blank
+  line stays blank. `lines` remains the right shape for output that is already
+  split.
+- `DetailContents.tail: false` — a prose or list pane opens at the top and never
+  claims to follow anything. Leave it out for a log.
+
+A screen whose list is one of several scopes overrides `headerLabel()` (the
+header rule's name) and `emptyLabel()` (the empty-list line), so `Tab` can change
+what is listed without a second renderer; both default to the screen's options.
+
 A destructive action asks through [`confirm.ts`](./confirm.ts):
 `ConfirmState.ask(prompt, accept)` holds the question, `resolve(data)` accepts on
 `y`/`Y`/Enter, dismisses on `n`/`N`/Esc/`q`, and returns `undefined` for any
@@ -92,7 +113,8 @@ Resolve colors through a [`tokens.ts`](./tokens.ts) role
 (`paint(theme, role, text)`), never a literal ANSI sequence, hex value, or Pi
 token named inline; a theme swap must re-skin every surface. Use the shared
 `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
-their literals, and `screenHint` / Pi's `keyHint` for the hint row.
+their literals, `screenHint` / Pi's `keyHint` for the hint row, and
+`screenFooter` for the hint row with its blank and closing rule.
 
 A list accents the focused row's label (`labelRole: selected ? "accent" :
 "label"`); the `❯` marker alone is not enough to tell which row is live. The

package/lib/tui/chrome.ts

@@ -8,9 +8,9 @@
  * the transcript visible.
  *
  * Screens are full-width, terminal-height-aware components. These helpers build
- * the top rule, clamp a screen's body to the terminal, and render the key-hint
- * footer, so each screen keeps its own layout but not its own copy of the
- * arithmetic or hint vocabulary.
+ * the top rule and the closing rule, clamp a screen's body to the terminal, and
+ * render the key-hint footer, so each screen keeps its own layout but not its
+ * own copy of the arithmetic or hint vocabulary.
  *
  * No runtime dependencies beyond `@earendil-works/pi-tui`: the theme is passed
  * in, and the viewport options are explicit.
@@ -20,6 +20,7 @@ import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
 import { SEPARATORS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
+import { plainRule } from "./rules.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -88,12 +89,29 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[], ind
 	return truncateToWidth(`${lead}${kept.map(render).join(separator)}`, target);
 }
 
+/**
+ * The bottom of a screen: a blank row, its key-hint row, and the closing rule.
+ *
+ * {@link dockListFrame} ends a docked list screen with this, and a screen that
+ * lays out its own rows — `/context`, the WeChat login and control screens —
+ * closes its block with it too, so no screen spells the three rows out alone. A
+ * screen whose row above the hint varies (a scroll gauge or a blank) places its
+ * own rule with `plainRule` instead.
+ */
+export function screenFooter(theme: Theme, width: number, hint: string): string[] {
+	return ["", hint, plainRule(theme, width)];
+}
+
 /**
  * The sections of a docked list screen, assembled by {@link dockListFrame}.
  * `body`, `range`, and `detail` lines are built (and truncated) by the caller;
  * the frame only places them.
  */
 export interface DockListFrame {
+	/** The active theme, used for the closing rule. */
+	theme: Theme;
+	/** The screen width in columns, used for the closing rule. */
+	width: number;
 	/** The pre-rendered header line, usually `titleRule(theme, width, title)`. */
 	header: string;
 	/** A summary line under the header; a blank line follows it. */
@@ -132,11 +150,14 @@ export function detailBlockRows(detail: readonly string[] | undefined, blank = t
 /**
  * Assemble a docked list screen: the caller's header rule, an optional summary
  * and its blank line, the body, an optional range row, optional detail rows after
- * their own blank line, and the blank-line-padded key-hint footer.
+ * their own blank line, the key-hint row, and the closing rule.
  *
  * This is the convention every docked list screen shares — the bytefly panel,
  * `/jobs`, `/watch`, `/todos`, `/memory`, and `/rewind`. The header line is built
- * by the caller (usually `titleRule`), so the frame never picks a rule style.
+ * by the caller (usually `titleRule`), so the frame never picks the *opening*
+ * rule style; the closing rule is always the muted fill, matching the closing
+ * rule Pi's built-in selectors draw and the bottom border of the editor slot the
+ * screen replaces.
  */
 export function dockListFrame(frame: DockListFrame): string[] {
 	const lines: string[] = [frame.header];
@@ -147,7 +168,7 @@ export function dockListFrame(frame: DockListFrame): string[] {
 		if (frame.detailBlank !== false) lines.push("");
 		lines.push(...frame.detail);
 	}
-	lines.push("", frame.hint, "");
+	lines.push(...screenFooter(frame.theme, frame.width, frame.hint));
 	return lines;
 }
 

package/lib/tui/dock-screen.ts

@@ -20,11 +20,13 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { detailBlockRows, dockListFrame, screenHint, type ScreenHint, type ViewportRowsSource } from "./chrome.ts";
 import { clip, fitCells } from "./columns.ts";
 import { ConfirmState } from "./confirm.ts";
 import { fitRows, formatRange, IdCursor, isCloseKey, navIntent, wheelDelta } from "./cursor.ts";
 import { SEPARATORS } from "./glyphs.ts";
+import { BODY_INDENT } from "./indent.ts";
 import { LinePane } from "./line-pane.ts";
 import { emptyState } from "./rows.ts";
 import { titleRule } from "./rules.ts";
@@ -33,22 +35,33 @@ import { paint } from "./tokens.ts";
 /** Rows the body shows when the terminal height is unknown. */
 const SCREEN_DEFAULT_ROWS = 14;
 
-/** Fixed rows around the list body: header, summary, blank, blank, hint, blank. */
+/** Fixed rows around the list body: header, summary, blank, blank, hint, closing rule. */
 const LIST_CHROME_ROWS = 6;
 
-/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, blank. */
+/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, closing rule. */
 const DETAIL_CHROME_ROWS = 6;
 
 /** What a detail pane shows: its title, lines, and the one-line subtitle. */
 export interface DetailContents {
 	/** Pane title, e.g. `j1 build`. */
 	title: string;
-	/** The body lines, already sanitized by the caller. */
-	lines: string[];
+	/** The body lines, already sanitized by the caller. Omit for a `text` pane. */
+	lines?: string[];
+	/**
+	 * Prose body, built once at open and wrapped to the render width on every
+	 * frame. Takes precedence over `lines`. A resize re-wraps; a blank line in the
+	 * source stays a blank line in the pane.
+	 */
+	text?: string;
 	/** More lines exist above the ones supplied. */
 	more?: boolean;
 	/** Subtitle under the title, e.g. the log file path. */
 	subtitle?: string;
+	/**
+	 * Whether the pane follows its tail. Default true, which is a log's behavior;
+	 * false opens a prose or list pane at the top and never says `following`.
+	 */
+	tail?: boolean;
 	/**
 	 * Rows above the scrollable body that depend on the width: key/value facts,
 	 * a legend, a divider. Read fresh every frame with the live width and already
@@ -101,6 +114,9 @@ export abstract class DockListScreen<T> implements Component {
 	private readonly confirmState = new ConfirmState();
 	private feedback: string | undefined;
 	private detailFacts: ((width: number) => string[]) | undefined;
+	/** Prose body for the open pane, wrapped to the width it is rendered at. */
+	private detailText: string | undefined;
+	private detailWrap: { width: number; lines: string[] } | undefined;
 
 	constructor(protected readonly options: DockListScreenOptions) {}
 
@@ -163,6 +179,19 @@ export abstract class DockListScreen<T> implements Component {
 		this.options.requestRender();
 	}
 
+	/**
+	 * The header rule's label. A screen whose list is one of several scopes
+	 * overrides it, so the rule names what is on screen.
+	 */
+	protected headerLabel(): string {
+		return this.options.title;
+	}
+
+	/** The empty-list line; a screen whose scopes differ overrides it. */
+	protected emptyLabel(): string {
+		return this.options.emptyList;
+	}
+
 	/** Show one line of feedback in place of the hints. */
 	protected notify(text: string): void {
 		this.feedback = text;
@@ -182,6 +211,12 @@ export abstract class DockListScreen<T> implements Component {
 		// Facts stay with the pane unless this update supplies its own, so a poll that
 		// only refreshes the body cannot drop the facts the row opened with.
 		if (contents.facts) this.detailFacts = contents.facts;
+		// `text` and `tail` belong to the row that opened the pane; an update either
+		// replaces the prose or settles the pane back onto a line buffer.
+		if (contents.text !== undefined || contents.lines !== undefined) {
+			this.detailText = contents.text;
+			this.detailWrap = undefined;
+		}
 		const changed =
 			contents.subtitle === undefined
 				? this.pane.update({ title: contents.title, lines: contents.lines, more: contents.more })
@@ -201,6 +236,7 @@ export abstract class DockListScreen<T> implements Component {
 
 	/** Re-read the open detail pane, so a poll cannot show stale lines. */
 	refreshDetail(id: string): void {
+		if (this.detailText !== undefined) return;
 		const source = this.detailById?.(id);
 		if (source && this.pane.update({ lines: source.lines, more: source.more })) this.options.requestRender();
 	}
@@ -242,10 +278,30 @@ export abstract class DockListScreen<T> implements Component {
 		const contents = this.detailFor(row);
 		this.mode = "detail";
 		this.detailFacts = contents.facts;
-		this.pane.open(this.idOf(row), contents);
+		this.detailText = contents.text;
+		this.detailWrap = undefined;
+		this.pane.open(
+			this.idOf(row),
+			{
+				title: contents.title,
+				lines: contents.text === undefined ? (contents.lines ?? []) : [],
+				more: contents.more,
+				subtitle: contents.subtitle,
+			},
+			contents.tail ?? true,
+		);
 		this.options.requestRender();
 	}
 
+	/** Leave detail mode and drop everything that belonged to the open row. */
+	private closeDetail(): void {
+		this.mode = "list";
+		this.pane.close();
+		this.detailFacts = undefined;
+		this.detailText = undefined;
+		this.detailWrap = undefined;
+	}
+
 	private handleListKey(data: string): void {
 		if (isCloseKey(data) || data === "q") {
 			this.options.onClose();
@@ -294,9 +350,7 @@ export abstract class DockListScreen<T> implements Component {
 
 	private handleDetailKey(data: string): void {
 		if (matchesKey(data, Key.escape) || matchesKey(data, Key.backspace) || data === "q") {
-			this.mode = "list";
-			this.pane.close();
-			this.detailFacts = undefined;
+			this.closeDetail();
 			this.options.requestRender();
 			return;
 		}
@@ -307,11 +361,11 @@ export abstract class DockListScreen<T> implements Component {
 	}
 
 	/** The footer: a pending confirmation, one line of feedback, or the hints. */
-	private hint(width: number, rows: readonly T[]): string {
+	private footer(width: number, hints: ScreenHint[]): string {
 		const pending = this.confirmState.pending;
 		if (pending) return clip(`  ${paint(this.theme, "warn", pending.prompt)}`, width);
 		if (this.feedback) return clip(`  ${paint(this.theme, "meta", this.feedback)}`, width);
-		return screenHint(this.theme, width, this.listHints(rows));
+		return screenHint(this.theme, width, hints);
 	}
 
 	private summary(rows: readonly T[], width: number): string {
@@ -343,7 +397,7 @@ export abstract class DockListScreen<T> implements Component {
 		const body: string[] = [];
 		let range: string | undefined;
 		if (rows.length === 0) {
-			body.push(...emptyState(this.theme, w, { label: this.options.emptyList }));
+			body.push(...emptyState(this.theme, w, { label: this.emptyLabel() }));
 		} else {
 			const end = Math.min(rows.length, this.cursor.scroll + this.cursor.visible);
 			for (let i = this.cursor.scroll; i < end; i++) body.push(this.rowLine(rows[i], w, i === index));
@@ -353,12 +407,14 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
-			header: titleRule(this.theme, w, this.options.title),
+			theme: this.theme,
+			width: w,
+			header: titleRule(this.theme, w, this.headerLabel()),
 			summary: this.summary(rows, w),
 			body,
 			range,
 			detail: block.map((line) => clip(`  ${paint(this.theme, "meta", line)}`, w)),
-			hint: this.hint(w, rows),
+			hint: this.footer(w, this.listHints(rows)),
 		});
 	}
 
@@ -366,6 +422,7 @@ export abstract class DockListScreen<T> implements Component {
 		this.syncDetail();
 		// A live pane whose row is gone has already closed itself: draw the list.
 		if (this.mode !== "detail") return this.renderList(w);
+		this.syncText(w);
 		const facts = this.detailFacts ? this.detailFacts(w) : [];
 		const visible = fitRows(
 			this.options.viewportRowsSource,
@@ -389,18 +446,21 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, this.pane.title(this.options.detailTitle)),
 			summary: clip(`  ${paint(this.theme, "faint", this.pane.subtitleLine())}`, w),
 			body,
 			range,
-			hint: screenHint(this.theme, w, this.detailHints(this.detailRow)),
+			hint: this.footer(w, this.detailHints(this.detailRow)),
 		});
 	}
 
 	/**
 	 * Re-read a live pane in place. This runs inside a render, so it must not ask
 	 * for another frame; a source that disappeared closes the pane instead of
-	 * showing lines the list no longer has a row for.
+	 * showing lines the list no longer has a row for. A prose pane is skipped here:
+	 * `syncText` owns its lines, and this still closes it when the row is gone.
 	 */
 	private syncDetail(): void {
 		if (!this.liveDetail()) return;
@@ -408,11 +468,23 @@ export abstract class DockListScreen<T> implements Component {
 		if (!id) return;
 		const source = this.detailById?.(id);
 		if (!source) {
-			this.mode = "list";
-			this.pane.close();
-			this.detailFacts = undefined;
+			this.closeDetail();
 			return;
 		}
-		this.pane.update({ lines: source.lines, more: source.more });
+		if (this.detailText === undefined) this.pane.update({ lines: source.lines, more: source.more });
+	}
+
+	/**
+	 * Wrap a prose body to the width the pane actually renders at, once per width.
+	 * The pane's body lines are built at open, so this is the one source that can
+	 * follow a resize.
+	 */
+	private syncText(width: number): void {
+		if (this.detailText === undefined) return;
+		const inner = Math.max(1, width - BODY_INDENT);
+		if (this.detailWrap?.width === inner) return;
+		const lines = this.detailText.split("\n").flatMap((line) => (line === "" ? [""] : wrapTextWithAnsi(line, inner)));
+		this.detailWrap = { width: inner, lines };
+		this.pane.update({ lines });
 	}
 }