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

package/extensions/{document → file-read}/render.ts

@@ -1,7 +1,7 @@
 /**
- * Transcript rendering for `read_doc`.
+ * Transcript rendering for the `read_doc` tool.
  *
- * Theme-aware formatting only: the tool definition in `tool.ts` wires these to
+ * Theme-aware formatting only: the tool definitions in `tool.ts` wire these to
  * `renderCall` / `renderResult`. The call line carries the path (body colour,
  * `~`-shortened, OSC-8 linked when the terminal supports it); the result line
  * leads with the format and the exact character range, so the path is never
@@ -17,14 +17,14 @@ import { formatTokens, sanitizeLine, shortenPath, stripControlChars } from "../.
 import { expandKey, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { rejectionLine, toolCallTitle } from "../../lib/tui/tool.ts";
-import { summarizeDoc } from "./paging.ts";
-import { TOOL_NAME, type DocArgs, type DocResult } from "./schema.ts";
+import { summarizeRead } from "./paging.ts";
+import type { ReadArgs, ReadResult } from "./schema.ts";
 
 /** Lines of extracted text shown in the expanded preview. */
 export const PREVIEW_LINES = 20;
 
 /** Render the argument path: body colour, `~`-shortened, OSC-8 linked when supported. */
-export function renderDocPath(rawPath: string | undefined, theme: Theme, cwd: string, argsComplete = true): string {
+export function renderReadPath(rawPath: string | undefined, theme: Theme, cwd: string, argsComplete = true): string {
 	if (rawPath === undefined && !argsComplete) return theme.fg("toolOutput", "...");
 	if (typeof rawPath !== "string") return paint(theme, "bad", "[invalid arg]");
 	const value = sanitizeLine(rawPath);
@@ -47,14 +47,14 @@ export function previewText(text: string, maxLines: number): { body: string; mor
 }
 
 /** A result shape broad enough for both a test double and the host. */
-export interface DocRenderResult {
+export interface ReadRenderResult {
 	content: ReadonlyArray<{ type: string; text?: string }>;
 	details?: unknown;
 	isError?: boolean;
 }
 
 /** Options the host passes to `renderResult`. */
-export interface DocRenderOptions {
+export interface ReadRenderOptions {
 	expanded: boolean;
 	isPartial: boolean;
 	/** Pre-painted elapsed suffix shown while reading. */
@@ -62,10 +62,14 @@ export interface DocRenderOptions {
 }
 
 /** The call line: `read_doc <path> (from N, max M)`. */
-export function formatDocCall(args: DocArgs, theme: Theme, context: { cwd: string; argsComplete?: boolean }): string {
+export function formatReadCall(
+	tool: string,
+	args: ReadArgs,
+	theme: Theme,
+	context: { cwd: string; argsComplete?: boolean },
+): string {
 	const { path, startIndex, maxChars } = args;
-	let text =
-		toolCallTitle(theme, `${TOOL_NAME} `) + renderDocPath(path, theme, context.cwd, context.argsComplete ?? true);
+	let text = toolCallTitle(theme, `${tool} `) + renderReadPath(path, theme, context.cwd, context.argsComplete ?? true);
 	const options: string[] = [];
 	if (typeof startIndex === "number" && startIndex > 0) options.push(`from ${formatTokens(startIndex)}`);
 	if (typeof maxChars === "number") options.push(`max ${formatTokens(maxChars)}`);
@@ -77,17 +81,17 @@ export function formatDocCall(args: DocArgs, theme: Theme, context: { cwd: strin
  * The result: a format + range summary, an expand hint when collapsed, and, when
  * expanded, a sanitized preview of the extracted text.
  */
-export function formatDocResult(result: DocRenderResult, options: DocRenderOptions, theme: Theme): string {
+export function formatReadResult(result: ReadRenderResult, options: ReadRenderOptions, theme: Theme): string {
 	if (options.isPartial) return paint(theme, "warn", "Reading...") + (options.progress ?? "");
 
 	const isError = result.isError ?? false;
-	const details = result.details as DocResult | undefined;
+	const details = result.details as ReadResult | undefined;
 
 	if (!details || isError) {
 		return rejectionLine(theme, { content: result.content, isError }, options.expanded);
 	}
 
-	const summary = summarizeDoc(details);
+	const summary = summarizeRead(details);
 	const sep = paint(theme, "faint", SEPARATORS.item);
 	let text = paint(theme, "meta", summary.format) + sep + theme.fg("toolOutput", summary.detail);
 	if (summary.note) text += paint(theme, summary.truncated ? "accent" : "faint", SEPARATORS.item + summary.note);

package/extensions/{document → file-read}/schema.ts

@@ -1,5 +1,5 @@
 /**
- * Parameter schema, output schema, and result type for `read_doc`.
+ * Parameter schema, output schema, and result types for the `read_doc` tool.
  */
 
 import { Type, type Static } from "typebox";
@@ -12,16 +12,16 @@ export const MIN_CHARS = 200;
 export const MAX_CHARS = 100_000;
 export const MAX_PATH_LENGTH = 4096;
 
-export const DocParams = Type.Object({
+export const ReadParams = Type.Object({
 	path: Type.String({
 		minLength: 1,
 		maxLength: MAX_PATH_LENGTH,
-		description: "Path to a supported document file, relative to the working directory or absolute inside it.",
+		description: "Path to a supported file, relative to the working directory or absolute inside it.",
 	}),
 	startIndex: Type.Optional(
 		Type.Integer({
 			minimum: 0,
-			description: "Code-point offset to start from. Use this to read a truncated document in chunks.",
+			description: "Code-point offset to start from. Use this to read a truncated file in chunks.",
 		}),
 	),
 	maxChars: Type.Optional(
@@ -33,9 +33,9 @@ export const DocParams = Type.Object({
 	),
 });
 
-export type DocArgs = Static<typeof DocParams>;
+export type ReadArgs = Static<typeof ReadParams>;
 
-export const DocOutput = Type.Object({
+export const ReadOutput = Type.Object({
 	path: Type.String(),
 	format: Type.String(),
 	bytes: Type.Number(),
@@ -47,4 +47,4 @@ export const DocOutput = Type.Object({
 });
 
 /** The runtime result, with `format` narrowed to the registry id. */
-export type DocResult = Omit<Static<typeof DocOutput>, "format"> & { format: FormatId };
+export type ReadResult = Omit<Static<typeof ReadOutput>, "format"> & { format: FormatId };

package/extensions/{document → file-read}/tool.ts

@@ -19,16 +19,14 @@ import { reuseText } from "../../lib/tui/chrome.ts";
 import { elapsedSuffix, reuseCallText, startToolProgress, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { isFormatEnabled, loadConfig } from "./config.ts";
 import { withDeadline } from "./deadline.ts";
-import type { DocExtractor } from "./extract/file.ts";
+import type { FormatExtractor } from "./extract/file.ts";
 import { detectFormat, supportedExtensions, unsupportedHint, type FormatId } from "./formats.ts";
-import { formatDoc } from "./paging.ts";
-import { formatDocCall, formatDocResult } from "./render.ts";
-import { DocOutput, DocParams, MAX_CHARS, MIN_CHARS, TOOL_NAME, type DocArgs, type DocResult } from "./schema.ts";
-
-export { TOOL_NAME } from "./schema.ts";
+import { formatPage } from "./paging.ts";
+import { formatReadCall, formatReadResult } from "./render.ts";
+import { ReadOutput, ReadParams, MAX_CHARS, MIN_CHARS, TOOL_NAME, type ReadArgs, type ReadResult } from "./schema.ts";
 
 /** Resolve a request path under `root`, refusing anything that escapes it. */
-function resolveDocument(root: string, rawPath: string): { display: string; abs: string } {
+function resolveReadPath(root: string, rawPath: string): { display: string; abs: string } {
 	// Resolve on the raw path; sanitize only the displayed/error strings, so a
 	// pathological control character cannot hide a path or forge a transcript line.
 	const trimmed = rawPath.trim();
@@ -44,7 +42,7 @@ function resolveDocument(root: string, rawPath: string): { display: string; abs:
 }
 
 /** Stat the file and raise a model-readable error for a missing/unreadable target. */
-async function statFile(abs: string, display: string, maxFileBytes: number): Promise<number> {
+async function statFile(abs: string, display: string, maxFileBytes: number, tool: string): Promise<number> {
 	let info: Awaited<ReturnType<typeof stat>>;
 	try {
 		info = await stat(abs);
@@ -56,54 +54,57 @@ async function statFile(abs: string, display: string, maxFileBytes: number): Pro
 	}
 	if (!info.isFile()) throw new Error(`Not a file: ${display}`);
 	if (info.size > maxFileBytes) {
-		throw new Error(`File is ${info.size} bytes, larger than the ${maxFileBytes}-byte limit for read_doc.`);
+		throw new Error(`File is ${info.size} bytes, larger than the ${maxFileBytes}-byte limit for ${tool}.`);
 	}
 	return info.size;
 }
 
 /** Per-format extractor overrides, for tests; the format table supplies the rest. */
-export interface DocToolDeps {
-	extractors?: Partial<Record<FormatId, DocExtractor>>;
-	/** Test seam: replace the configured `document.extractTimeoutMs`. */
+export interface ReadToolDeps {
+	extractors?: Partial<Record<FormatId, FormatExtractor>>;
+	/** Test seam: replace the configured `file-read.extractTimeoutMs`. */
 	timeoutMs?: number;
 }
 
-export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void {
+export function registerReadTool(pi: ExtensionAPI, deps: ReadToolDeps = {}): void {
 	pi.registerTool({
 		name: TOOL_NAME,
 		label: "Read document",
 		description:
 			"Read a local PDF, DOCX, DOC, ODT, RTF, or XLSX file and return its extracted text, pageable with " +
 			"startIndex/maxChars. Extraction runs in process, so no external tools are needed; a read that outlasts " +
-			"document.extractTimeoutMs fails with the limit named.",
+			"file-read.extractTimeoutMs fails with the limit named.",
 		promptSnippet: "Read a PDF, DOCX, DOC, ODT, RTF, or XLSX as text, paged with startIndex/maxChars.",
 		promptGuidelines: [
-			"Use read_doc for .pdf/.docx/.doc/.odt/.rtf/.xlsx; the built-in read tool is for text and images.",
-			"Extraction returns plain text only; tables, images, and formatting are dropped.",
+			"Use read_doc for .pdf, .docx, .doc, .odt, .rtf, and .xlsx; the built-in read tool is for text and images.",
+			"Only text survives: tables, images, and formatting are dropped, and an .xlsx read returns one [Sheet] heading per worksheet followed by tab-separated rows of the workbook's displayed values.",
+			"A scanned or image-only PDF has no text layer, so it returns little or nothing; there is no OCR.",
 		],
-		parameters: DocParams,
-		outputSchema: DocOutput,
+		parameters: ReadParams,
+		outputSchema: ReadOutput,
 		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const args = params as DocArgs;
+			const args = params as ReadArgs;
 			const config = loadConfig(ctx.cwd);
 			const root = resolveEffectiveCwd(ctx.cwd);
-			const { display, abs } = resolveDocument(root, args.path);
+			const { display, abs } = resolveReadPath(root, args.path);
 
 			const format = detectFormat(display);
 			if (!format) {
 				const hint = unsupportedHint(display);
 				if (hint) throw new Error(hint);
-				throw new Error(`Unsupported document format. Supported extensions: ${supportedExtensions().join(", ")}.`);
+				throw new Error(
+					`Unsupported file format for ${TOOL_NAME}. Supported extensions: ${supportedExtensions().join(", ")}.`,
+				);
 			}
 			if (!isFormatEnabled(config, format.id)) {
 				throw new Error(
-					`${format.label} extraction is disabled in the bytefly.json document section (document.formats.${format.id} = false).`,
+					`${format.label} extraction is disabled in the bytefly.json file-read section (file-read.formats.${format.id} = false).`,
 				);
 			}
 
-			const size = await statFile(abs, display, config.maxFileBytes);
+			const size = await statFile(abs, display, config.maxFileBytes, TOOL_NAME);
 			const extractor = deps.extractors?.[format.id] ?? format.extract;
 			const timeoutMs = deps.timeoutMs ?? config.extractTimeoutMs;
 			startToolProgress(onUpdate);
@@ -111,7 +112,7 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 				timeoutMs,
 				signal,
 				timeoutMessage:
-					`Extraction of ${display} did not finish within ${timeoutMs} ms (document.extractTimeoutMs). ` +
+					`Extraction of ${display} did not finish within ${timeoutMs} ms (file-read.extractTimeoutMs). ` +
 					`The ${format.label} parser was abandoned; raise the limit or read a smaller file.`,
 			});
 
@@ -119,7 +120,8 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 			const requested = typeof args.maxChars === "number" ? args.maxChars : config.maxChars;
 			const maxChars = Math.min(config.maxChars, MAX_CHARS, Math.max(MIN_CHARS, Math.round(requested)));
 
-			const formatted = formatDoc({
+			const formatted = formatPage({
+				tool: TOOL_NAME,
 				path: display,
 				format: format.id,
 				bytes: size,
@@ -128,7 +130,7 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 				maxChars,
 			});
 
-			const result: DocResult = {
+			const result: ReadResult = {
 				path: display,
 				format: format.id,
 				bytes: size,
@@ -149,7 +151,9 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 		renderCall(args, theme, context) {
 			const cwd = context?.cwd ?? process.cwd();
 			const text = reuseCallText(context?.lastComponent, "", "middle");
-			text.setText(formatDocCall(args as DocArgs, theme, { cwd, argsComplete: context?.argsComplete ?? true }));
+			text.setText(
+				formatReadCall(TOOL_NAME, args as ReadArgs, theme, { cwd, argsComplete: context?.argsComplete ?? true }),
+			);
 			return text;
 		},
 
@@ -159,7 +163,11 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 			const isError = context?.isError ?? result.isError ?? false;
 			const text = reuseText(context?.lastComponent);
 			text.setText(
-				formatDocResult({ content: result.content, details: result.details, isError }, { ...options, progress }, theme),
+				formatReadResult(
+					{ content: result.content, details: result.details, isError },
+					{ ...options, progress },
+					theme,
+				),
 			);
 			return text;
 		},

package/extensions/goal/tools.ts

@@ -9,10 +9,9 @@
 
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { sanitizeLine } from "../../lib/format.ts";
 import { GOAL_TOOL } from "../../lib/tool-names.ts";
+import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { formatCallText, formatGoalText } from "./format.ts";
@@ -118,25 +117,22 @@ export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {
 		},
 
 		renderCall(args, theme, context) {
-			const text = reuseCallText(context.lastComponent);
-			text.setText(
-				toolCallTitle(theme, `${TOOL_NAME} `) +
-					paint(theme, "meta", formatCallText(args.objective, context.argsComplete, args.status)),
+			return callLine(
+				theme,
+				context.lastComponent,
+				TOOL_NAME,
+				formatCallText(args.objective, context.argsComplete, args.status),
 			);
-			return text;
 		},
 
 		renderResult(result, options, theme, context) {
 			const text = reuseText(context.lastComponent);
-			const details = toolDetails<GoalDetails>(result.details);
-			if (!details) {
-				text.setText(rejectionLine(theme, result, options.expanded));
-				return text;
-			}
-			if (details.error) {
-				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
+			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<GoalDetails>(result.details));
+			if ("line" in outcome) {
+				text.setText(outcome.line);
 				return text;
 			}
+			const details = outcome.details;
 			if (!details.goal) {
 				// A neutral marker, deliberately not the achieved check.
 				text.setText(paint(theme, "faint", `${GLYPHS.stopped} `) + paint(theme, "meta", "Cleared the goal"));

package/extensions/job/commands.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { withRailsSuppressed } from "../../lib/rails.ts";
+import { withPolledScreen } from "../../lib/screen-session.ts";
 import { formatJobList } from "./format.ts";
 import type { JobsRuntime } from "./runtime.ts";
 import { JobListComponent } from "./tui.ts";
@@ -23,53 +23,39 @@ export function registerCommands(pi: ExtensionAPI, runtime: JobsRuntime): void {
 				return;
 			}
 
-			let timer: ReturnType<typeof setInterval> | undefined;
-			const stopTimer = (): void => {
-				if (timer) clearInterval(timer);
-				timer = undefined;
-			};
-
-			// The dock screen owns the editor slot; hide the rails for its lifetime.
-			try {
-				await withRailsSuppressed(pi, () =>
-					ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
-						const component = new JobListComponent(
-							() => runtime.list(),
-							theme,
-							{
-								sessionId: () => runtime.sessionId,
-								logs: (id) => runtime.logs(id, 200),
-								kill: (id) => {
-									runtime.kill(id);
-								},
-								clear: () => {
-									const result = runtime.clear(undefined, false);
-									if (result.cleared > 0) {
-										ctx.ui.notify(`Cleared ${result.cleared} job${result.cleared === 1 ? "" : "s"}.`, "info");
-									}
-								},
+			await withPolledScreen(
+				pi,
+				ctx,
+				(screen) =>
+					new JobListComponent(
+						() => runtime.list(),
+						screen.theme,
+						{
+							sessionId: () => runtime.sessionId,
+							logs: (id) => runtime.logs(id, 200),
+							kill: (id) => {
+								runtime.kill(id);
 							},
-							() => {
-								stopTimer();
-								done();
+							clear: () => {
+								const result = runtime.clear(undefined, false);
+								if (result.cleared > 0) {
+									ctx.ui.notify(`Cleared ${result.cleared} job${result.cleared === 1 ? "" : "s"}.`, "info");
+								}
 							},
-							() => tui.requestRender(),
-							() => tui.terminal?.rows,
-						);
-
-						// Poll the open log pane; the runtime's own clock repaints the list.
-						timer = setInterval(() => {
-							const id = component.currentLogId();
-							if (id) component.refreshLogs(id);
-						}, LOG_POLL_MS);
-						timer.unref?.();
-
-						return component;
-					}),
-				);
-			} finally {
-				stopTimer();
-			}
+						},
+						screen.close,
+						screen.requestRender,
+						screen.viewportRows,
+					),
+				{
+					pollMs: LOG_POLL_MS,
+					// Only the open log pane is polled; the runtime's own clock repaints the list.
+					poll: (component) => {
+						const id = component.currentLogId();
+						if (id) component.refreshLogs(id);
+					},
+				},
+			);
 		},
 	});
 }

package/extensions/job/runtime.ts

@@ -34,6 +34,7 @@ import {
 import { loadConfig, type JobsConfig } from "./config.ts";
 import { createLogWriter, type LogHandle } from "./log-writer.ts";
 import { sanitizeUntrustedLine } from "../../lib/format.ts";
+import { defaultInterval } from "../../lib/timer.ts";
 import { clipLabel } from "../../lib/tui/columns.ts";
 import { compareJobs, formatLogs } from "./format.ts";
 import { readLogTail } from "./logs.ts";
@@ -193,7 +194,7 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 	let config: JobsConfig = options.config ?? loadConfig(process.cwd());
 	let sessionId = "session";
 	let disposed = false;
-	let clock: ReturnType<typeof setInterval> | undefined;
+	let clock: (() => void) | undefined;
 
 	/** Jobs this session owns (a dead session's adopted records included). */
 	const ownJobs = (): Job[] => [...jobs.values()].filter((job) => job.sessionId === sessionId);
@@ -247,10 +248,8 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		isSessionAlive(readSessionMarker(store.directory(), owner), now(), config.sessionTtlMs, liveness);
 
 	const stopClock = (): void => {
-		if (clock) {
-			clearInterval(clock);
-			clock = undefined;
-		}
+		clock?.();
+		clock = undefined;
 	};
 
 	const ensureClock = (): void => {
@@ -260,7 +259,7 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			return;
 		}
 		if (clock) return;
-		clock = setInterval(() => {
+		clock = defaultInterval(config.repaintMs, () => {
 			touchMarker();
 			pollExternal();
 			// Re-assert the chip every tick. It is otherwise only set on a job
@@ -268,8 +267,7 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 			// another UI path) would hide a still-running job's chip until the next
 			// transition. The clock is the only periodic hook while jobs run.
 			ui.setStatus();
-		}, config.repaintMs);
-		clock.unref?.();
+		});
 	};
 
 	const paint = (): void => {

package/extensions/job/tools.ts

@@ -9,17 +9,9 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { sanitizeLine } from "../../lib/format.ts";
 import { errorResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import {
-	elapsedSuffix,
-	errorLine,
-	rejectionLine,
-	reuseCallText,
-	syncElapsedTimer,
-	toolCallTitle,
-} from "../../lib/tui/tool.ts";
+import { callLine, detailsOrLine, elapsedSuffix, rejectionLine, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
@@ -229,30 +221,19 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 
 		renderCall(args, theme, context) {
 			const action = typeof args.action === "string" ? args.action : "job";
-			const text = reuseCallText(context.lastComponent, "", "middle");
-			text.setText(
-				toolCallTitle(theme, `${TOOL_NAME} `) +
-					paint(
-						theme,
-						"meta",
-						sanitizeLine(formatCallText(action, args as Record<string, unknown>, context.argsComplete)),
-					),
-			);
-			return text;
+			const subject = formatCallText(action, args as Record<string, unknown>, context.argsComplete);
+			return callLine(theme, context.lastComponent, TOOL_NAME, subject, "middle");
 		},
 
 		renderResult(result, options, theme, context) {
 			const text = reuseText(context.lastComponent);
 			const startedAt = syncElapsedTimer(options.isPartial, context);
-			const details = toolDetails<JobDetails>(result.details);
-			if (!details) {
-				text.setText(rejectionLine(theme, result, options.expanded));
-				return text;
-			}
-			if (details.error) {
-				text.setText(errorLine(theme, details.error));
+			const outcome = detailsOrLine(theme, result, options.expanded, toolDetails<JobDetails>(result.details));
+			if ("line" in outcome) {
+				text.setText(outcome.line);
 				return text;
 			}
+			const details = outcome.details;
 
 			if (options.isPartial) {
 				const id = details.job?.id;

package/extensions/memory/commands.ts

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { withRailsSuppressed } from "../../lib/rails.ts";
+import { withPolledScreen } from "../../lib/screen-session.ts";
 import { messageOf } from "./errors.ts";
 import { formatHealth, memoryHealth } from "./doctor.ts";
 import { formatNotice, scopeLabel } from "./format.ts";
@@ -55,49 +55,35 @@ async function openPicker(pi: ExtensionAPI, runtime: MemoryRuntime, ctx: Extensi
 		return;
 	}
 
-	let timer: ReturnType<typeof setInterval> | undefined;
-	const stopTimer = (): void => {
-		if (timer) clearInterval(timer);
-		timer = undefined;
-	};
-
-	// The dock screen owns the editor slot; hide the rails for its lifetime.
-	try {
-		await withRailsSuppressed(pi, () =>
-			ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
-				const component = new MemoryPickerComponent(
-					tui,
-					theme,
-					{
-						entries: () => runtime.entries(),
-						trusted: () => runtime.trusted(),
-						refresh: () => runtime.refresh().changed.length > 0,
-						add: (scope, text) => runtime.add(scope, text),
-						update: (scope, from, to) => runtime.update(scope, from, to),
-						forget: (scope, entry) => runtime.forget(scope, entry),
-						merge: (scope, first, second, merged) => runtime.merge(scope, first, second, merged),
-						move: (from, to, text) => runtime.move(from, to, text),
-					},
-					() => {
-						stopTimer();
-						done();
-					},
-					() => tui.requestRender(),
-					() => tui.terminal?.rows,
-				);
-
-				// Pick up an external edit while the screen is open, repainting only on a change.
-				timer = setInterval(() => {
-					if (runtime.refresh().changed.length > 0) tui.requestRender();
-				}, PICKER_POLL_MS);
-				timer.unref?.();
-
-				return component;
-			}),
-		);
-	} finally {
-		stopTimer();
-	}
+	await withPolledScreen(
+		pi,
+		ctx,
+		(screen) =>
+			new MemoryPickerComponent(
+				screen.tui,
+				screen.theme,
+				{
+					entries: () => runtime.entries(),
+					trusted: () => runtime.trusted(),
+					refresh: () => runtime.refresh().changed.length > 0,
+					add: (scope, text) => runtime.add(scope, text),
+					update: (scope, from, to) => runtime.update(scope, from, to),
+					forget: (scope, entry) => runtime.forget(scope, entry),
+					merge: (scope, first, second, merged) => runtime.merge(scope, first, second, merged),
+					move: (from, to, text) => runtime.move(from, to, text),
+				},
+				screen.close,
+				screen.requestRender,
+				screen.viewportRows,
+			),
+		{
+			pollMs: PICKER_POLL_MS,
+			// Pick up an external edit while the screen is open, repainting only on a change.
+			poll: (_component, handles) => {
+				if (runtime.refresh().changed.length > 0) handles.requestRender();
+			},
+		},
+	);
 }
 
 export function registerCommands(pi: ExtensionAPI, runtime: MemoryRuntime): void {