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

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

@@ -1,14 +1,14 @@
 /**
- * The supported document formats, in one table.
+ * The supported formats, in one table.
  *
  * The tool handler, the config defaults, the `formats` merge, and the
- * unsupported-file error all derive from `FORMATS`, so adding a format is a
- * local change: one extractor module plus one entry here. See the README's
- * "Adding a format" section.
+ * unsupported-file error all derive from `FORMATS`, so a format is a local
+ * change: one extractor module plus one entry here. See the README's "Adding a
+ * format" section.
  */
 
 import { extname } from "node:path";
-import type { DocExtractor } from "./extract/file.ts";
+import type { FormatExtractor } from "./extract/file.ts";
 import { extractDocText } from "./extract/doc.ts";
 import { extractDocxText } from "./extract/docx.ts";
 import { extractOdtText } from "./extract/odt.ts";
@@ -16,17 +16,17 @@ import { extractPdfDocument } from "./extract/pdf.ts";
 import { extractRtfText } from "./extract/rtf.ts";
 import { extractXlsxText } from "./extract/xlsx.ts";
 
-export interface DocumentFormat {
-	/** Stable id, also the `document.formats` key in `bytefly.json` and the output `format`. */
+export interface ReadFormat {
+	/** Stable id, also the `file-read.formats` key in `bytefly.json` and the output `format`. */
 	id: "pdf" | "docx" | "doc" | "odt" | "rtf" | "xlsx";
 	/** Human label for messages. */
 	label: string;
 	/** Lower-case extensions, with the dot, that select this format. */
 	extensions: readonly string[];
-	/** Enabled unless `document.formats[id]` in `bytefly.json` says otherwise. */
+	/** Enabled unless `file-read.formats[id]` in `bytefly.json` says otherwise. */
 	defaultEnabled: boolean;
 	/** Extractor; runs the format's parser and throws a readable error when it fails. */
-	extract: DocExtractor;
+	extract: FormatExtractor;
 }
 
 export const FORMATS = [
@@ -36,7 +36,7 @@ export const FORMATS = [
 	{ id: "odt", label: "ODT", extensions: [".odt"], defaultEnabled: true, extract: extractOdtText },
 	{ id: "rtf", label: "RTF", extensions: [".rtf"], defaultEnabled: true, extract: extractRtfText },
 	{ id: "xlsx", label: "XLSX", extensions: [".xlsx"], defaultEnabled: true, extract: extractXlsxText },
-] as const satisfies readonly DocumentFormat[];
+] as const satisfies readonly ReadFormat[];
 
 export type FormatId = (typeof FORMATS)[number]["id"];
 
@@ -46,7 +46,7 @@ export function supportedExtensions(): string[] {
 }
 
 /** The format selected by a path's extension, or undefined when unsupported. */
-export function detectFormat(path: string): DocumentFormat | undefined {
+export function detectFormat(path: string): ReadFormat | undefined {
 	const ext = extname(path).toLowerCase();
 	return FORMATS.find((format) => (format.extensions as readonly string[]).includes(ext));
 }

package/extensions/file-read/index.ts

@@ -0,0 +1,17 @@
+/**
+ * The `file-read` extension entrypoint.
+ *
+ * Registers `read_doc`, which extracts text from a local document or workbook
+ * under the effective working root using in-process parsers. The factory only
+ * registers; a parser library loads lazily on the first read of its format, so
+ * the extension costs nothing at startup.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerReadTool } from "./tool.ts";
+
+export default function fileRead(pi: ExtensionAPI): void {
+	if (!isExtensionEnabled("file-read")) return;
+	registerReadTool(pi);
+}

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

@@ -1,7 +1,7 @@
 /**
  * Model-facing text formatting and slicing for `read_doc`.
  *
- * `formatDoc` slices extracted text by code point from `startIndex`, so CJK and
+ * `formatPage` slices extracted text by code point from `startIndex`, so CJK and
  * emoji stay well-formed, and names the offset of the next chunk. The body is
  * the clean slice; the text adds a header and any truncation note.
  */
@@ -9,7 +9,9 @@
 import { formatCount } from "../../lib/format.ts";
 import type { FormatId } from "./formats.ts";
 
-export interface DocPageInput {
+export interface PageInput {
+	/** The tool that produced this page; named in the truncation note. */
+	tool: string;
 	path: string;
 	format: FormatId;
 	bytes: number;
@@ -18,8 +20,8 @@ export interface DocPageInput {
 	maxChars: number;
 }
 
-export interface FormattedDoc {
-	/** The requested slice of the document text. */
+export interface FormattedPage {
+	/** The requested slice of the extracted text. */
 	body: string;
 	/** Header, body, and any truncation note. */
 	text: string;
@@ -30,13 +32,13 @@ export interface FormattedDoc {
 	chars: number;
 }
 
-export function formatDoc(input: DocPageInput): FormattedDoc {
+export function formatPage(input: PageInput): FormattedPage {
 	const points = Array.from(input.text);
 	const total = points.length;
 	const header = `Path: ${input.path}\nFormat: ${input.format.toUpperCase()}\nSize: ${input.bytes} bytes`;
 
 	if (total === 0) {
-		const text = `${header}\n\n(no extractable text; the document may be scanned or image-only)`;
+		const text = `${header}\n\n(no extractable text; the file may be empty or contain no readable text)`;
 		return { body: "", text, truncated: false, nextIndex: input.startIndex, chars: 0 };
 	}
 
@@ -52,14 +54,14 @@ export function formatDoc(input: DocPageInput): FormattedDoc {
 
 	let text = `${header}\n\n${body}`;
 	if (truncated) {
-		text += `\n\n… (truncated at ${nextIndex} of ${total} characters; call read_doc again with startIndex=${nextIndex})`;
+		text += `\n\n… (truncated at ${nextIndex} of ${total} characters; call ${input.tool} again with startIndex=${nextIndex})`;
 	}
 
 	return { body, text, truncated, nextIndex, chars: total };
 }
 
-/** Inputs for `summarizeDoc`, the fields the transcript summary reads. */
-export interface DocSummaryInput {
+/** Inputs for `summarizeRead`, the fields the transcript summary reads. */
+export interface SummaryInput {
 	format: FormatId;
 	/** Total characters in the extracted text. */
 	chars: number;
@@ -69,7 +71,7 @@ export interface DocSummaryInput {
 }
 
 /** Theme-free transcript summary: the format, the range detail, and any note. */
-export interface DocSummary {
+export interface PageSummary {
 	/** Uppercase format id, e.g. `PDF`. */
 	format: string;
 	/** Range detail, e.g. `chars 1–40,000 of 42,478`. */
@@ -81,13 +83,13 @@ export interface DocSummary {
 }
 
 /**
- * Describe a `read_doc` result for the transcript, without theme colours.
+ * Describe a file-read result for the transcript, without theme colours.
  *
  * A complete first read shows the total; a paged read shows the returned range
  * and where to continue, so a truncated result is never mistaken for the whole
- * document.
+ * file.
  */
-export function summarizeDoc(input: DocSummaryInput): DocSummary {
+export function summarizeRead(input: SummaryInput): PageSummary {
 	const format = input.format.toUpperCase();
 	if (input.chars === 0) return { format, detail: "no extractable text", truncated: false };
 	if (input.startIndex >= input.chars) {

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 => {