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

package/extensions/wechat/timer.ts

@@ -3,20 +3,18 @@
  *
  * The bridge and the channel need a cancellable one-shot timer that a test can
  * drive without waiting (the delayed acknowledgement, the typing keep-alive, the
- * prompt timeout); login needs an abortable sleep between polls. The defaults use
- * a real `setTimeout`, `unref`'d for the one-shot so a pending timer never holds
- * the process open.
+ * prompt timeout), and login needs an abortable sleep between polls; both seams
+ * and their production defaults are in [`lib/timer.ts`](../../lib/timer.ts),
+ * because job, watch, file-browse, plan, and web-access arm the same two. This
+ * module adds the per-key map those timers are held in.
  */
 
-/** Arm a one-shot timer; the returned function cancels it. */
-export type ArmTimer = (ms: number, fn: () => void) => () => void;
+import { abortableSleep, type ArmTimer } from "../../lib/timer.ts";
 
-/** The production timer: `setTimeout`, detached from the event loop. */
-export const defaultTimer: ArmTimer = (ms, fn) => {
-	const timer = setTimeout(fn, ms);
-	(timer as { unref?: () => void }).unref?.();
-	return () => clearTimeout(timer);
-};
+export { type ArmTimer, defaultTimer } from "../../lib/timer.ts";
+
+/** The shared abortable sleep, under the name the bridge and login already use. */
+export const defaultSleep = abortableSleep;
 
 /**
  * A set of one-shot timers keyed by a caller's id (a peer, a watcher).
@@ -74,22 +72,3 @@ export function createTimerMap(arm: ArmTimer): TimerMap {
 	};
 	return map;
 }
-
-/** An abortable sleep: resolves after `ms`, rejects when `signal` aborts. */
-export function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
-	return new Promise((resolve, reject) => {
-		if (signal?.aborted) {
-			reject(new Error("aborted"));
-			return;
-		}
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new Error("aborted"));
-		};
-		signal?.addEventListener("abort", onAbort, { once: true });
-	});
-}

package/extensions/wechat/tools.ts

@@ -10,9 +10,8 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
-import { sanitizeLine } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
+import { callLine, errorLine, rejectionLine } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import type { Bridge } from "./bridge.ts";
 
@@ -82,11 +81,9 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 		},
 
 		renderCall(args, theme, context) {
-			const text = reuseCallText(context.lastComponent);
 			const body = (args as { text?: unknown }).text;
-			const label = context.argsComplete && typeof body === "string" ? sanitizeLine(body) : "…";
-			text.setText(toolCallTitle(theme, `${TOOL_NAME} `) + paint(theme, "meta", label));
-			return text;
+			const label = context.argsComplete && typeof body === "string" ? body : "…";
+			return callLine(theme, context.lastComponent, TOOL_NAME, label);
 		},
 
 		renderResult(result, options, theme, context) {
@@ -97,7 +94,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 				return text;
 			}
 			if (details?.error) {
-				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
+				text.setText(errorLine(theme, details.error));
 				return text;
 			}
 			// Pi's rejection result carries `{}`; show its sanitized message.

package/lib/README.md

@@ -20,26 +20,28 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
 | [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` / `writeConfigValuesAt` / `unsetConfigValueAt` (the leaf writers preserve siblings and metadata, `writeConfigValuesAt` applies several leaves in one document pass, and the last removes one and prunes what it emptied). Includes `clampInteger` / `clampNumber` / `cleanString` / `optionalString` / `asBoolean` / `stringList` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
-| [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
+| [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters, plus `decodeCodePoint`, the other half of the same boundary — one numeric character reference as text, with a surrogate or out-of-range value decoded to U+FFFD. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |
 | [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job` and `watch`, rendered by bytefly. |
 | [`report.ts`](./report.ts) | The pending-report coordinator: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `source` / `onWoke`, returning the lifecycle handlers that report at the next turn, raise at most one triggered turn per wake window, and prune only their own notices. Shared by `job` and `watch`. |
 | [`errors.ts`](./errors.ts) | `messageOf`: the one boundary that turns an unknown thrown value into a user-facing line (an `Error` yields its message, anything else is stringified). |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `boundedTail` (the end of a joined tail with a `truncated` flag), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — `lineOf` (a value read as one sanitized line), `sanitizeUntrustedLine` / `sanitizeUntrustedText` with `MAX_OUTPUT_LINE` for **program output** (OSC/CSI escapes removed whole, `\r` progress resolved, clipped), and `shortenPath`. |
+| [`timer.ts`](./timer.ts) | The three timer seams and their production defaults, each cancellable and each built so a pending timer never holds the process open: `ArmTimer` / `defaultTimer` (one shot), `RepeatTimer` / `defaultInterval` (repeating), and `abortableSleep` (resolve after a delay, reject `Error("aborted")` when a signal wins). Shared by `wechat`'s bridge and prompt channel, plan's review page, `job`'s and `watch`'s repaint clocks, `bytefly`'s working tick, the browse live channel, and the search throttle — so a test drives a deadline instead of waiting on one. |
 | [`lines.ts`](./lines.ts) | `LineSplitter`, the byte-safe splitter for a stream of program output: buffers bytes and decodes only at a newline, so a UTF-8 character split across two reads survives, and caps an over-long line instead of dropping it. Shared by `job`, `watch`, `check`, and `subagent`. |
 | [`pool.ts`](./pool.ts) | `mapConcurrent`: one async read per entry with at most `limit` calls in flight and results in input order, so a directory listing or a status sweep fans out without an unbounded burst or a per-entry round trip. Shared by `file-browse` and `worktree`. |
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote transport marks on the UI context it owns (`INTERACTION_TURN_KEY`), the `InteractionChannel` interface (`request` / `post` / `postFile`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, and digest preface) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `gitCommonDir`, `revParse`, `revParseMany` for several revisions in one call, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
 | [`http/`](./http/) | The loopback HTTP layer shared by `file-browse` and `plan`: [`http/headers.ts`](./http/headers.ts) (the page policy `PAGE_CSP` and the `pageHeaders` / `scriptHeaders` / `jsonHeaders` sets, plus `eventHeaders` for the one long-lived stream), [`http/response.ts`](./http/response.ts) (`ServeResponse` — a buffered body, a `filePath` stream, or an SSE `stream` — plus `htmlResponse` / `jsonResponse` / `jsonError` / `textResponse`), [`http/router.ts`](./http/router.ts) (`parseRequestUrl`, and `isLocalHostHeader` with the `required` mode each server chooses), [`http/server.ts`](./http/server.ts) (`bindLoopback` on `127.0.0.1` with the accept-error listener, `respond` for HEAD / streamed file / body, `openEventStream` for the head and reconnect hint of an SSE response, and the idempotent `createCloser`), and the [`http/index.ts`](./http/index.ts) barrel. |
-| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame) with `detailBlockRows` (the rows its detail block costs), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `statusRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`, `byRunningFirst` for a live list's order), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`, `labelLine` / `clipLabel` with `LABEL_WIDTH`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job`, `watch`, and `subagent` share, with the attached-context `notify` and a `detach` that clears its keys), [`tui/dock-screen.ts`](./tui/dock-screen.ts) (`DockListScreen`, the two-mode docked list + detail-pane screen with navigation, wheel, range, and confirm), [`tui/confirm.ts`](./tui/confirm.ts) (`ConfirmState`, the y/N layer behind every destructive screen action), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint` / `overflowHint` / `earlierHint`, the `TailResult` transcript block, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
+| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame) with `detailBlockRows` (the rows its detail block costs), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow` with its `align` option for a value held beside its label, `statusRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`, `byRunningFirst` for a live list's order), [`tui/columns.ts`](./tui/columns.ts) (`splitRow` for two cells at the two edges, `inlineRow` for two cells held together, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`, `labelLine` / `clipLabel` with `LABEL_WIDTH`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job`, `watch`, and `subagent` share, with the attached-context `notify` and a `detach` that clears its keys), [`tui/dock-screen.ts`](./tui/dock-screen.ts) (`DockListScreen`, the two-mode docked list + detail-pane screen with navigation, wheel, range, and confirm), [`tui/confirm.ts`](./tui/confirm.ts) (`ConfirmState`, the y/N layer behind every destructive screen action), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, `callLine` — the one headline every renderer draws — `detailsOrLine` (a result's details, or the one `errorLine` / `rejectionLine` a failure shows), sanitized `errorLine` / `rejectionLine`, `moreHint` / `overflowHint` / `earlierHint`, the `TailResult` transcript block, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, doc, and plan guards share, and the canonical-path helper the worktree registry keys records by. |
-| [`pdf.ts`](./pdf.ts) | The optional `unpdf` seam shared by `web-access` and `document`: `pdfGuidance`, `PdfUnavailableError`, `pdfTextFromResult`, and the lazy `loadPdfExtractor` / `extractPdfText` (an injected extractor wins), so a missing package and a merged-pages result read the same way through either surface. |
+| [`pdf.ts`](./pdf.ts) | The optional `unpdf` seam shared by `web-access` and `file-read`: `pdfGuidance`, `PdfUnavailableError`, `pdfTextFromResult`, and the lazy `loadPdfExtractor` / `extractPdfText` (an injected extractor wins), so a missing package and a merged-pages result read the same way through either surface. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
 | [`plan-state.ts`](./plan-state.ts) | The plan-mode flag replayed from the session branch: `PLAN_MODE_ENTRY_TYPE` and `isPlanModeEnabled(entries)`, so `rewind` can refuse a write while planning without importing the plan extension. |
 | [`plan-entry.ts`](./plan-entry.ts) | Plan-mode entry shared by the extension that owns the mode and the one that offers it: `READ_ONLY_SUMMARY` and `PLAN_CONSENT` (one wording for the read-only guarantee), the `PLAN_ENTER_REQUEST` channel with its `PlanEnterRequest` payload, and `requestPlanMode(pi, ctx)` — a request/response over `pi.events` that resolves `false` instead of hanging when `plan` is not loaded, so a command context (which has no `executeTool`) can still enter the mode after asking the user once. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
+| [`screen-session.ts`](./screen-session.ts) | `withPolledScreen`: mount one `ctx.ui.custom` dock screen — rails suppressed for its lifetime, an optional repaint tick through an injected `RepeatTimer`, and one teardown — handing the mount the host's `tui`, `theme`, `requestRender`, `close`, and `viewportRows`. Shared by `/jobs`, `/watch`, and `/memory`, whose rails window and timer window were the same one. |
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports, the published search provider, env, and a refresh-only reachability probe): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. A check kind is either a prerequisite (`binary`, `module`, `state`, `invocation`, `notify`, `provider`) or a `safety` switch whose off value trades a protection away, read from `bytefly.json` global-then-project. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
 | [`spawn.ts`](./spawn.ts) | The process seam for extensions that run a shell command: `SpawnedProcess`, `SpawnFn`, `KillTreeFn`, the pure `spawnOptions` / `killPlan`, `applyKillPlan` over injected seams, `isPidAlive`, and the `defaultSpawn` / `defaultKillTree` that execute them (process group on POSIX, `taskkill /T` on Windows). Shared by `job`, `watch`, `check`, `worktree`, and `wechat`. |
@@ -62,9 +64,10 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
   one extension probes on another — live in `tool-names.ts`.
 - **A helper that exists here must be imported, not redefined.**
   `test/shared-helpers.test.ts` fails a top-level extension declaration whose
-  name is also exported by `lib/`, and a body copied from `lib/` or from another
-  extension. A deliberate wrapper goes on that test's reasoned exception list; a
-  copy belongs here with one co-located test.
+  name is also exported by `lib/`, and a body copied from `lib/` or from any
+  other file — a second extension, a sibling module, or `lib/` itself. A
+  deliberate wrapper goes on that test's reasoned exception list; a copy belongs
+  here with its declared capability suite.
 - **A color is a role, not a token.** The rules and the primitives are in
   [`tui/README.md`](./tui/README.md#color-is-a-role): draw through
   [`tui/tokens.ts`](./tui/tokens.ts) (`paint(theme, role, text)`) so a theme swap

package/lib/escape.ts

@@ -1,11 +1,14 @@
 /**
- * HTML text escaping for the browse pages.
+ * HTML text escaping, and the inverse for one character reference.
  *
  * The single escape used by every page renderer and by the Markdown renderer:
  * model- and file-authored text becomes safe text nodes and double-quoted
  * attributes. Keeping it here (rather than in `html.ts`) lets `markdown.ts`
  * escape without importing the page renderer, so the module graph stays
- * acyclic.
+ * acyclic. `decodeCodePoint` is the other half of the same boundary and lives
+ * beside it for the same reason: the Markdown inline scan and the raw-HTML
+ * attribute decoder both resolve `&#N;` and `&#xN;` references, and one copy
+ * cannot drift from the other.
  */
 
 /** Escape text for an HTML text node or double-quoted attribute. */
@@ -25,3 +28,13 @@ export function escapeHtml(value: string): string {
 		}
 	});
 }
+
+/**
+ * One numeric character reference as text: U+FFFD when it is a surrogate, zero,
+ * or out of range, so an entity cannot inject an unpaired half of a pair.
+ */
+export function decodeCodePoint(value: number): string {
+	if (!Number.isFinite(value) || value <= 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff))
+		return "\uFFFD";
+	return String.fromCodePoint(value);
+}

package/lib/pdf.ts

@@ -1,11 +1,11 @@
 /**
  * The optional `unpdf` seam: lazy load, module-shape handling, and text
- * extraction, shared by `web-access` and `document`.
+ * extraction, shared by `web-access` and `file-read`.
  *
  * `unpdf` bundles a server-friendly build of PDF.js, so it is imported lazily:
  * an extension registers on every session, and a parser should load only when a
  * read actually needs it. `web-access` treats the package as optional and
- * reports {@link pdfGuidance} when it is absent; `document` ships it as a
+ * reports {@link pdfGuidance} when it is absent; `file-read` ships it as a
  * dependency. Both get the same loader, the same merged-pages call, and the same
  * result unwrapping, so a PDF reads the same way through either surface.
  *

package/lib/requirements.ts

@@ -255,7 +255,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [gitCheck("the branch chip and the diff view")],
 		notes: ["The default-browser opener (`open` / `xdg-open` / `cmd`) is best-effort; the URL is printed either way."],
 	},
-	document: {},
+	"file-read": {},
 	"file-open": {
 		notes: [
 			"The `/open` command and its notification need an interactive UI; the `open_path` tool works without one.",
@@ -266,6 +266,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	memory: {
 		optional: [gitCheck("project-scope memory under the repository root")],
 	},
+	context: {},
 	wechat: {
 		optional: [
 			{
@@ -301,7 +302,6 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		],
 	},
 };
-
 // --- Probing ----------------------------------------------------------------
 
 /** Run a command and report its exit code; production backs this with `pi.exec`. */

package/lib/screen-session.ts

@@ -0,0 +1,85 @@
+/**
+ * Mounting a dock screen: rails suppressed, an optional repaint tick, and one
+ * teardown.
+ *
+ * Pi mounts a `ctx.ui.custom` screen in the editor slot the above-editor rails
+ * share, so every screen wraps itself in `withRailsSuppressed`. Three of them —
+ * `/jobs`, `/watch`, and `/memory` — also poll while they are open (a log pane,
+ * a line pane, a store another process can edit), and each re-derived the same
+ * `let timer` / `stopTimer` / `setInterval(...).unref?.()` / `finally` skeleton
+ * around its own component. The rails lifetime and the timer lifetime are the
+ * same window, so they are one helper rather than two wrappers each caller
+ * stacks and unwinds by hand.
+ *
+ * The timer is a seam (`RepeatTimer`), so a test drives the tick instead of
+ * waiting for one, and it is armed after the mount returns: a component whose
+ * constructor throws leaves no timer behind.
+ *
+ * Value-only: the timer handle lives in the caller's closure.
+ */
+
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { withRailsSuppressed } from "./rails.ts";
+import { defaultInterval, type RepeatTimer } from "./timer.ts";
+
+/** What the host accepts back from a screen's mount. */
+export type ScreenComponent = Component & { dispose?(): void };
+
+/** What a mounted screen is given: the host's mount parameters, narrowed. */
+export interface PolledScreen {
+	/** The host's component handle; a screen that needs an `Editor` builds it from this. */
+	readonly tui: TUI;
+	/** The theme the host handed the mount. */
+	readonly theme: Theme;
+	/** Ask the host to repaint. */
+	requestRender(): void;
+	/** Close the screen, as its own close key would. */
+	close(): void;
+	/** The terminal's height in rows, or `undefined` when the host cannot say. */
+	viewportRows(): number | undefined;
+}
+
+export interface PolledScreenOptions<Screen> {
+	/** How often `poll` runs while the screen is open, in ms. */
+	pollMs: number;
+	/** Run once per tick; `screen` is what `mount` returned. */
+	poll(screen: Screen, handles: PolledScreen): void;
+	/** Timer seam; defaults to an unref'd interval. */
+	timer?: RepeatTimer;
+}
+
+/**
+ * Show one polled dock screen and resolve when it closes.
+ *
+ * The caller still owns the `ctx.mode !== "tui"` branch, because the text
+ * fallback differs per command; everything from the mount to the teardown is
+ * here.
+ */
+export async function withPolledScreen<Screen extends ScreenComponent>(
+	pi: Pick<ExtensionAPI, "events">,
+	ctx: Pick<ExtensionContext, "ui">,
+	mount: (handles: PolledScreen) => Screen,
+	options: PolledScreenOptions<Screen>,
+): Promise<void> {
+	const { pollMs, poll, timer = defaultInterval } = options;
+	let stop: (() => void) | undefined;
+	try {
+		await withRailsSuppressed(pi, () =>
+			ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+				const handles: PolledScreen = {
+					tui,
+					theme,
+					requestRender: () => tui.requestRender(),
+					close: () => done(),
+					viewportRows: () => tui.terminal?.rows,
+				};
+				const screen = mount(handles);
+				stop = timer(pollMs, () => poll(screen, handles));
+				return screen;
+			}),
+		);
+	} finally {
+		stop?.();
+	}
+}

package/lib/timer.ts

@@ -0,0 +1,61 @@
+/**
+ * The timer seams: one shot, repeating, and a sleep that can be aborted.
+ *
+ * Extensions need the same three things, and each has the same two properties a
+ * test cares about: it is cancellable, and its production default never holds
+ * the process open. The WeChat bridge arms a one-shot per acknowledgement,
+ * typing keep-alive, and prompt timeout; plan's review page arms one for the
+ * closed-tab grace; `job` and `watch` repaint on a repeating one; the browse
+ * live channel needs both; `job`, `watch`, `check`, `subagent`, and `wechat`
+ * sleep between polls. Keeping the defaults here means one definition of "arm
+ * it, and let it be cancelled", and one place where the `unref` lives.
+ *
+ * Value-only: types and constant functions, no module state.
+ */
+
+/** Arm a one-shot timer; the returned function cancels it. */
+export type ArmTimer = (ms: number, fn: () => void) => () => void;
+
+/** The production timer: `setTimeout`, detached from the event loop. */
+export const defaultTimer: ArmTimer = (ms, fn) => {
+	const timer = setTimeout(fn, ms);
+	(timer as { unref?: () => void }).unref?.();
+	return () => clearTimeout(timer);
+};
+
+/** Arm a repeating timer; the returned function stops it. */
+export type RepeatTimer = (ms: number, tick: () => void) => () => void;
+
+/** The production ticker: `setInterval`, detached from the event loop. */
+export const defaultInterval: RepeatTimer = (ms, tick) => {
+	const timer = setInterval(tick, ms);
+	(timer as { unref?: () => void }).unref?.();
+	return () => clearInterval(timer);
+};
+
+/**
+ * Resolve after `ms`, or reject when `signal` aborts first.
+ *
+ * The one rejection is `Error("aborted")` whatever the signal carries, so a
+ * caller that names its own abort error maps one case rather than inspecting a
+ * reason. The timer is cleared on both paths and never `unref`'d: a sleep exists
+ * to keep the caller waiting, so nothing else is pending to keep the process
+ * alive, and an unref'd one could be dropped mid-wait.
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error("aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = (): void => {
+			clearTimeout(timer);
+			reject(new Error("aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}

package/lib/tui/README.md

@@ -151,6 +151,6 @@ and the first call throws at runtime.
 
 ## Tests
 
-A module here gets a sibling `<module>.test.ts` covering fields, width bounds,
-ordering, and glyphs — never literal column padding. An extension's screen test
-is the `tui.test.ts` beside its `tui.ts`.
+A capability suite groups the modules it covers and asserts fields, width
+bounds, ordering, and glyphs — never literal column padding. An extension's
+screen coverage lives in its declared capability suite (for example `ui.test.ts`).

package/lib/tui/columns.ts

@@ -15,14 +15,17 @@ import { sanitizeLine, sanitizeUntrustedLine } from "../format.ts";
 /** The columns a label gets before it stops reading as a label. */
 export const LABEL_WIDTH = 48;
 
-/** A usable origin: terminal arithmetic starts from one column, never zero. */
-function columns(width: number): number {
+/**
+ * A usable drawing width in columns: terminal arithmetic starts from one column,
+ * never zero, so a narrow or unknown width never produces an empty frame.
+ */
+export function usableWidth(width: number): number {
 	return Math.max(1, Math.floor(width));
 }
 
 /** Clip a possibly-themed string to `width` columns, marking a cut with `ellipsis`. */
 export function clip(text: string, width: number, ellipsis = "…"): string {
-	return truncateToWidth(text, columns(width), ellipsis);
+	return truncateToWidth(text, usableWidth(width), ellipsis);
 }
 
 /**
@@ -34,7 +37,7 @@ export function clip(text: string, width: number, ellipsis = "…"): string {
  * A themed string keeps its colours on both the head and the tail.
  */
 export function clipMiddle(text: string, width: number, ellipsis = "…"): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	if (visibleWidth(text) <= w) return text;
 	const ellipsisWidth = visibleWidth(ellipsis);
 	const budget = w - ellipsisWidth;
@@ -69,7 +72,7 @@ export function clipLabel(text: string): string {
 
 /** Pad `text` on the right to exactly `width` columns. Never truncates. */
 export function padTo(text: string, width: number): string {
-	const missing = columns(width) - visibleWidth(text);
+	const missing = usableWidth(width) - visibleWidth(text);
 	return missing > 0 ? text + " ".repeat(missing) : text;
 }
 
@@ -83,7 +86,7 @@ export function padTo(text: string, width: number): string {
  * plain left-aligned line with no trailing spaces.
  */
 export function splitRow(left: string, right: string, width: number, minGap = 1): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	if (!right) return clip(left, w);
 	const gap = Math.max(0, Math.floor(minGap));
 	const rightCell = clip(right, w);
@@ -93,13 +96,35 @@ export function splitRow(left: string, right: string, width: number, minGap = 1)
 	return padTo(clip(left, leftBudget), w - rightWidth) + rightCell;
 }
 
+/**
+ * Left cell, then a gap, then the right cell, with the result ending after the
+ * right cell instead of filling the width.
+ *
+ * The sibling of {@link splitRow}: a label and its value read as one pair on a
+ * wide terminal instead of sitting at opposite edges, while a tight line still
+ * keeps the value — the left cell is clipped to make room, and the gap shrinks
+ * in whole columns before the right cell loses anything.
+ */
+export function inlineRow(left: string, right: string, width: number, gap = 2): string {
+	const w = usableWidth(width);
+	if (!right) return clip(left, w);
+	const space = Math.max(0, Math.floor(gap));
+	const rightCell = clip(right, w);
+	const rightWidth = visibleWidth(rightCell);
+	const leftBudget = w - rightWidth - space;
+	if (leftBudget <= 0) return rightCell;
+	const leftCell = clip(left, leftBudget);
+	const separator = " ".repeat(Math.max(0, Math.min(space, w - visibleWidth(leftCell) - rightWidth)));
+	return `${leftCell}${separator}${rightCell}`;
+}
+
 /**
  * Join as many whole cells as fit, dropping trailing cells rather than
  * clipping one in half. The first cell is always kept, so an over-wide line
  * degrades to a clipped first cell instead of an empty one.
  */
 export function fitCells(cells: readonly string[], width: number, separator = " "): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	const kept: string[] = [];
 	for (const cell of cells) {
 		const candidate = [...kept, cell].join(separator);
@@ -118,7 +143,7 @@ export function fitCells(cells: readonly string[], width: number, separator = "
  * {@link fitCells} it may return several lines, and always returns one.
  */
 export function flowCells(cells: readonly string[], width: number): string[] {
-	const w = columns(width);
+	const w = usableWidth(width);
 	const lines: string[] = [];
 	let current = "";
 	let currentWidth = 0;

package/lib/tui/rows.ts

@@ -13,7 +13,7 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { clip, padTo, splitRow } from "./columns.ts";
+import { clip, inlineRow, padTo, splitRow } from "./columns.ts";
 import { selectionMarker } from "./cursor.ts";
 import { GLYPHS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
@@ -41,21 +41,29 @@ export interface ListRow {
 	/** The row's text. */
 	label: string;
 	labelRole?: TuiRole;
-	/** Right-aligned meta (a count, a time, a state). */
+	/** Meta that closes the row: right-aligned, or beside the label when `align` is `inline`. */
 	trailing?: string;
 	trailingRole?: TuiRole;
+	/**
+	 * Where the trailing cell sits. `end` (the default) pushes it to the right
+	 * edge, which suits a column of counts. `inline` keeps it beside the label
+	 * with a two-column gap, so a label and its value read as one pair on a wide
+	 * terminal instead of sitting at opposite ends of the line.
+	 */
+	align?: "end" | "inline";
 	/** Extra columns before the marker, for a nested row. */
 	indent?: number;
 }
 
 /**
  * One list row: an optional indent, the selection marker, an optional glyph,
- * the label, and right-aligned trailing meta.
+ * the label, and the trailing meta.
  *
  * The marker column is reserved by default, so selected and unselected rows
  * align; `marker: false` drops it for a non-interactive row. The trailing meta
- * is the anchor when the terminal is narrow (see `splitRow`), so a value at the
- * end of the row survives.
+ * is the anchor when the terminal is narrow (see `splitRow` and `inlineRow`),
+ * so a value at the end of the row survives either way; `align` decides whether
+ * it sits at the right edge or right after the label.
  */
 export function listRow(theme: Theme, width: number, row: ListRow): string {
 	const indent = " ".repeat(Math.max(0, Math.floor(row.indent ?? 0)));
@@ -64,7 +72,8 @@ export function listRow(theme: Theme, width: number, row: ListRow): string {
 	const glyph = row.glyph ? `${paint(theme, row.glyphRole ?? "info", row.glyph)} ` : "";
 	const label = paint(theme, row.labelRole ?? "label", row.label);
 	const trailing = row.trailing ? paint(theme, row.trailingRole ?? "meta", row.trailing) : "";
-	return splitRow(`${indent}${marker}${leading}${glyph}${label}`, trailing, width);
+	const head = `${indent}${marker}${leading}${glyph}${label}`;
+	return row.align === "inline" ? inlineRow(head, trailing, width) : splitRow(head, trailing, width);
 }
 
 /** A status row (a job, a watcher): the marker, a status glyph, a label, and right-aligned meta. */

package/lib/tui/rules.ts

@@ -15,6 +15,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
+import { usableWidth } from "./columns.ts";
 import { paint, type TuiRole } from "./tokens.ts";
 
 /** The glyph and colors a rule is drawn with. */
@@ -39,14 +40,9 @@ export interface CenteredRuleStyle extends RuleStyle {
  */
 export const RULE_GLYPH = "─";
 
-/** A usable origin: terminal arithmetic starts from one column, never zero. */
-function widthOf(width: number): number {
-	return Math.max(1, Math.floor(width));
-}
-
 /** A full-width divider in one color. */
 export function plainRule(theme: Theme, width: number, style: RuleStyle = {}): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	return paint(theme, style.fillRole ?? "rule", (style.glyph ?? RULE_GLYPH).repeat(w));
 }
 
@@ -64,7 +60,7 @@ function labelRule(
 	fillRole: TuiRole,
 	style: RuleStyle,
 ): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	const text = label.trim();
 	if (!text) return plainRule(theme, w, style);
 	const labelWidth = visibleWidth(text);
@@ -75,7 +71,7 @@ function labelRule(
 
 /** A centered rule: fill, label, and the rest of the fill. */
 export function centeredRule(theme: Theme, width: number, label: string, style: CenteredRuleStyle = {}): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	const glyph = style.glyph ?? RULE_GLYPH;
 	const fillRole = style.fillRole ?? "ruleStrong";
 	if (!label.trim()) return paint(theme, fillRole, glyph.repeat(w));

package/lib/tui/tool.ts

@@ -1,6 +1,7 @@
 /**
- * The shared tool-transcript kit: a call title, a width-safe call component,
- * sanitized error lines, the expand hint, and the running timer.
+ * The shared tool-transcript kit: a call title, the call line a renderer draws
+ * with it, the failure line a result shows before its body, the expand hint, and
+ * the running timer.
  *
  * Every extension's `renderCall` / `renderResult` used to repeat the same four
  * idioms — a bold `toolTitle`, a raw `result.content[0]`, a hand-built
@@ -34,6 +35,58 @@ export function toolCallTitle(theme: Theme, name: string): string {
 	return theme.fg("toolTitle", theme.bold(name));
 }
 
+/**
+ * One call line: the bold tool name, then the subject in the meta role.
+ *
+ * The subject is flattened to one line here, because a call line is a label: a
+ * stored note, a task, or a path carrying a newline cannot wrap it into the body
+ * column, where it would read as a result. Pass the clip the subject deserves —
+ * `middle` for a path or a URL whose tail is the identity, `end` for prose.
+ *
+ * A subject drawn in another role (an argument value in `label`, a suffix in
+ * `faint`) stays hand-built at its call site; this is the plain headline.
+ */
+export function callLine(
+	theme: Theme,
+	last: unknown,
+	name: string,
+	subject: string,
+	clip: CallClip = "end",
+): ToolCallText {
+	const text = reuseCallText(last, "", clip);
+	text.setText(toolCallTitle(theme, `${name} `) + paint(theme, "meta", sanitizeLine(subject)));
+	return text;
+}
+
+/**
+ * A result resolved to its details, or to the one line a failure shows.
+ */
+export type DetailsOrLine<Details> = { line: string } | { details: Details };
+
+/**
+ * Resolve a result to its details, or to the line to show instead.
+ *
+ * The failure is one branch whether the call carried no details at all (Pi's
+ * `{ details: {}, isError: true }` envelope) or the extension reported its own
+ * `details.error`, and it goes through `errorLine`: a multi-line message keeps
+ * its lines and `Error:` is prefixed exactly once, which a hand-built
+ * `paint(theme, "bad", \`Error: ${sanitizeLine(...)}\`)` does not.
+ */
+export function detailsOrLine<Details extends object>(
+	theme: Theme,
+	result: ToolMessageResult,
+	expanded: boolean,
+	details: Details | undefined,
+): DetailsOrLine<Details> {
+	if (!details) return { line: rejectionLine(theme, result, expanded) };
+	// The one property this reads is the extension's own report field; a details
+	// block without it (a plan summary, a check report) simply has no failure.
+	if ("error" in details && typeof details.error === "string" && details.error !== "") {
+		return { line: errorLine(theme, details.error) };
+	}
+	return { details };
+}
+
 /** How a call line gives up columns when the terminal is narrow. */
 export type CallClip = "end" | "middle";