pi-umbra-subagents 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grkn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# pi-umbra-subagents
+
+Parallel, read-only pi branches you can watch while they work. A branch is a separate `pi -p`
+process with an empty context; a live list above the input box shows what each one is doing,
+and their answers come back to the session when the last one ends. Also `/umb-loop`, which
+sends a prompt again after every reply, on a count or a timer.
+
+![Three branches running under the input box](https://raw.githubusercontent.com/grknbyk/pi-umbra/main/assets/subagents.webp)
+
+```sh
+pi install npm:pi-umbra-subagents
+node ~/.pi/agent/npm/node_modules/pi-umbra-subagents/patch.mjs
+```
+
+Restart pi after the patch. Only `/umb-loop` needs it; the branches work without it.
+
+Nothing is added to the model's prompt and no tool is registered. The model starts a run by
+ending its answer with a fenced `fan` block, which the bundled `fan` skill teaches it:
+
+````
+```fan
+name: weather-map
+desc: Map the weather API
+# Map
+routes: List every route in src/server.ts with file:line.
+upstream: List what src/forecast.ts fetches, with file:line.
+# Plan
+design: Given the Map results, propose the change.
+```
+````
+
+`# Title` starts a phase. Phases run in order; the branches inside one run at the same time.
+`label@provider/model: task` picks a model for one branch, otherwise it runs on the session's
+model. The results arrive as a follow-up message at the start of the next turn.
+
+## Commands and keys
+
+| Command or key | Effect |
+|---|---|
+| `/umb-fan [spec]` | start a run yourself; with no argument an editor opens with a template |
+| `/umb-agents`, `alt+a`, `↓` from the last input line | open the agent panel |
+| `↑` `↓` in the panel | select a branch |
+| `x` in the panel | stop the selected branch |
+| `esc` in the panel | back to the input box, unsent text kept |
+| `/umb-loop [count\|duration] [prompt]` | send the prompt again after each reply; run it again to stop |
+
+`/umb-loop 5 fix the next failing test` runs five times, `/umb-loop 10m continue` for ten
+minutes, `/umb-loop 0 …` until stopped. Without a prompt it sends `Continue.`. Escape cancels
+one round and keeps the loop.
+
+## Skills
+
+| Skill | Use |
+|---|---|
+| `fan` | the fenced block above; the extension owns the branches |
+| `delegate` | the same branches started from a bash call (`dstart`, `branch`, `dwait`), for runs the model wants to read back itself, or continue with `dresume` after a branch asks a question |
+
+Both write every branch's answer to `.pi-out/<run>/<phase>-<name>.md` and its errors to the
+matching `.err`. Add `.pi-out/` to `.gitignore`. Quitting pi stops the branches; what they
+wrote stays on disk.
+
+## Settings
+
+| Variable | Default | Effect |
+|---|---|---|
+| `FAN_MODEL` | the session's model | model for `fan` branches that do not name one |
+| `FAN_TOOLS` | `read,grep,find,ls` | tools a branch may use |
+| `FAN_LOAD` | empty | extra `-e <path>` flags; branches start with `--no-extensions`, so a provider that comes from an extension has to be listed here |
+| `FAN_TIMEOUT_MS` | `300000` | a branch still running after this long is cut off |
+
+The `delegate` skill reads the same knobs as `FAST`, `LOAD` and `DELEGATE_TIMEOUT` from its
+`delegate.env`, then from `~/.pi/agent/delegate.env`.
+
+## The patch
+
+`/umb-loop` sends its prompt the way the input box does, and the extension API has no way to
+do that. `patch.mjs` makes one small additive edit to pi's installed bundle that exposes it. A
+pi update removes the patch without any error, so run the script again after every update.
+
+| Command | Effect |
+|---|---|
+| `node .../patch.mjs` | apply the patch; a part already applied is skipped |
+| `node .../patch.mjs --check` | change nothing, exit 1 if the patch is missing |
+
+The script patches the `pi` on your PATH. Set `PI_UMBRA_PI` to the `pi-coding-agent`
+directory to patch another one.
+
+MIT.

package/extensions/umbra-loop.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// The editor's submit path is not on the extension API, so repatch.mjs publishes it.
+const submit = (text: string) => (globalThis as any).__piSubmit?.(text);
+
+const DEFAULT_PROMPT = "Continue.";
+const UNIT_MS: Record<string, number> = { h: 3_600_000, m: 60_000, s: 1000 };
+// "90s", "10 min", "1h30m" — a run of number+unit pairs at the very start of the args. A unit
+// ends at any non-letter, not at \b, which never falls between "h" and "30".
+const DURATION = /^(?:\d+\s*(?:hours?|hrs?|h|minutes?|mins?|m|seconds?|secs?|s)(?![a-z])\s*)+/i;
+const COUNT = /^(\d+)\s*/;
+const RESUBMIT_DELAY_MS = 50;
+
+type Loop = { prompt: string; iterations?: number; deadline?: number; done: number };
+
+const durationMs = (text: string) =>
+	[...text.matchAll(/(\d+)\s*([a-z]+)/gi)].reduce(
+		(sum, [, amount, unit]) => sum + Number(amount) * UNIT_MS[unit[0].toLowerCase()],
+		0,
+	);
+
+const parse = (args: string): Loop => {
+	const trimmed = args.trim();
+	const rest = (from: string) => trimmed.slice(from.length).trim() || DEFAULT_PROMPT;
+
+	const duration = trimmed.match(DURATION);
+	if (duration) return { prompt: rest(duration[0]), deadline: Date.now() + durationMs(duration[0]), done: 0 };
+
+	const count = trimmed.match(COUNT);
+	if (count) {
+		// 0 means "no limit". Either branch strips the number from the prompt, so
+		// "/umb-loop 0 fix the tests" submits "fix the tests", not "0 fix the tests".
+		const iterations = Number(count[1]);
+		return iterations > 0
+			? { prompt: rest(count[0]), iterations, done: 0 }
+			: { prompt: rest(count[0]), done: 0 };
+	}
+
+	return { prompt: trimmed || DEFAULT_PROMPT, done: 0 };
+};
+
+export default function (pi: ExtensionAPI) {
+	let loop: Loop | undefined;
+	let cancelled = false;
+
+	const describe = () => {
+		if (!loop) return undefined;
+		if (loop.iterations) return `loop ${loop.done}/${loop.iterations}`;
+		if (loop.deadline) return `loop ${Math.max(0, Math.round((loop.deadline - Date.now()) / 1000))}s`;
+		return `loop ${loop.done}`;
+	};
+
+	const stop = (ctx: ExtensionContext, reason: string) => {
+		loop = undefined;
+		ctx.ui.setStatus("loop", undefined);
+		ctx.ui.notify(reason);
+	};
+
+	pi.registerCommand("umb-loop", {
+		description: "Toggle automatic resubmission after each yield: /umb-loop [count|duration] [prompt]",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			if (loop) return stop(ctx, "loop off");
+			// Without the patch nothing would ever be sent, while the status claimed a running loop.
+			if (!(globalThis as any).__piSubmit) {
+				return ctx.ui.notify("umb-loop needs its patch: run pi-umbra-subagents/patch.mjs, then restart pi", "warning");
+			}
+
+			loop = parse(args);
+			cancelled = false;
+			ctx.ui.setStatus("loop", describe());
+			ctx.ui.notify(`loop on — "${loop.prompt}"`);
+			if (ctx.isIdle()) {
+				loop.done++;
+				submit(loop.prompt);
+			}
+		},
+	});
+
+	// An aborted run (Escape) keeps the loop armed but skips this yield, so the turn comes back to
+	// the user. Read from how the run ended, not from the Escape key: an Escape that only closed a
+	// panel or an autocomplete list aborts nothing and must not stall the loop.
+	pi.on("agent_end", (event) => {
+		const last = [...event.messages].reverse().find((message) => message.role === "assistant");
+		if (loop && last && "stopReason" in last && last.stopReason === "aborted") cancelled = true;
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (!loop) return;
+		if (cancelled) {
+			cancelled = false;
+			ctx.ui.notify("loop: iteration cancelled");
+			return;
+		}
+		if (loop.deadline && Date.now() >= loop.deadline) return stop(ctx, "loop done (time up)");
+		if (loop.iterations && loop.done >= loop.iterations) return stop(ctx, "loop done");
+
+		loop.done++;
+		ctx.ui.setStatus("loop", describe());
+		const prompt = loop.prompt;
+		setTimeout(() => loop && submit(prompt), RESUBMIT_DELAY_MS);
+	});
+}

package/extensions/umbra-subagents/bar/bar-line.ts

@@ -0,0 +1,344 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { LINGER_MS, type BranchView, type RunState } from "../skills/delegate/state.ts";
+
+// Every column the widget above the input box occupies, as pure functions over one run
+// snapshot. Two shapes: the flat live list of reference 3, which is the default, and the
+// one-line collapsed bar of reference 2, which replaces it while a phased run is going.
+//
+// All of it lives here rather than in the component because the arithmetic is the part that can
+// be wrong in a way that hurts: a composed line one column too wide wraps in the terminal, and
+// a wrapped line above the editor pushes the input box down by a row. Pure functions can be
+// walked across every width by bar.check.ts with no terminal, no theme and no pi — and pi
+// cannot even be imported by a check, because loading it drags in the experimental server.
+// The one thing this file borrows from pi is `ThemeColor`, as a type-only import, which is
+// erased before anything runs.
+//
+// Widths are measured before colour goes on. Every piece returned by the two layout functions
+// is plain text whose width is exactly what it will occupy, and renderLines() below only ever
+// concatenates them in order — which is also why a row hands back `dotAt`, the one cell that
+// takes the status colour, instead of a pre-coloured glyph.
+
+export const PAD = 1; // one column of gutter each side, matching the rows pi draws itself
+const GAP = 2; // collapsed bar: name -> description, and description -> counters
+const COL_GAP = 3; // list: agent name -> activity, as in reference 3
+const MIN_DESC = 12; // below this the description is noise, so the columns go to the counters
+const MIN_ACTIVITY = 10; // ditto for the activity sentence, which is the point of the list
+const NAME_CAP = 24; // columns the run name may claim before the counters start shrinking
+const HEAD_CAP = 28; // ditto for the list's marker + dot + name column
+const MIN_INNER = 8; // under this nothing but a stub of the main row fits
+
+/** Reference 1 shows "idle 53s", so a branch counts as quiet well before a minute. */
+export const IDLE_MS = 15_000;
+/** How long a finished run stays on screen before the widget falls back to bare `○ main`. */
+export { LINGER_MS };
+
+/** "45s", "3m 52s" — the reference-2 and reference-3 spelling, with the space. Reference 1
+ *  writes "3m15s" instead; that clock lives in panel.ts, where the columns are tighter. */
+export const clock = (ms: number) => {
+	const seconds = Math.max(0, Math.round(ms / 1000));
+	return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+};
+
+// A dash, not "0": a provider that reports usage only at completion leaves the sum at zero for
+// minutes, and a fake number in the column the user glances at is worse than an honest gap.
+export const compact = (tokens: number) =>
+	tokens <= 0 ? "–" : tokens < 1000 ? `${tokens}` : `${(tokens / 1000).toFixed(1)}k`;
+
+// RunState carries no end time — liveness is per branch — so the last beacon write in the run
+// stands in for one. It is what freezes the elapsed clock, so a finished run stops counting.
+export const endedAt = (run: RunState) => (run.live ? 0 : Math.max(0, ...run.branches.map((branch) => branch.updatedAt)));
+
+/** Past its linger window a finished run is the same thing as no run at all: one bare `○ main`
+ *  row. Both shapes ask that question, so they ask it through one function. */
+export const faded = (run: RunState | undefined, now: number): boolean => {
+	if (!run || run.total === 0) return true;
+	const ended = endedAt(run);
+	return ended > 0 && now - ended > LINGER_MS;
+};
+
+/** Which of the two screens to draw. A run that declares more than one phase is a workflow: it
+ *  has an order, a sidebar, and an "N/M agents done" worth summarising, so it collapses to
+ *  reference 2 and zooms into reference 1. One wave of parallel branches has no structure to
+ *  hide, so it stays the flat list — which is what reference 3 is: the no-workflow case. */
+export const isStructured = (run: RunState | undefined): run is RunState => !!run && run.phases.length > 1;
+
+// ---------- REFERENCE 2: the collapsed bar ----------
+
+// Counters first, widest tier that fits: the numbers are the reason to glance at the bar, so a
+// narrow terminal drops the description and then the run name, never the right-hand block.
+const counterTiers = (run: RunState, until: number) => {
+	const time = clock(until - run.startedAt);
+	const agents = `${run.done}/${run.total}`;
+	return [
+		`${agents} agents done · ${time} · ↓ ${compact(run.tokens)} tokens`,
+		`${agents} · ${time} · ↓ ${compact(run.tokens)}`,
+		`${agents} · ${time}`,
+		agents,
+	];
+};
+
+export type BarParts = { left: string; description: string; fill: string; right: string; live: boolean };
+
+/** Reference 2, whole: `○ pi-toolcall-render  Map how pi renders tool calls...  2/4 agents done
+ *  · 4m 38s · ↓ 397.8k tokens`. Returns undefined when there is nothing to collapse and the
+ *  caller falls back to the list, so the widget is never zero lines. */
+export const layoutBar = (width: number, run: RunState | undefined, now: number): BarParts | undefined => {
+	if (!run || faded(run, now)) return undefined;
+	const inner = width - PAD * 2;
+	if (inner < MIN_INNER) return undefined;
+	const ended = endedAt(run);
+
+	// Same rule as the list rows, asked of the whole run: filled while at least one branch is
+	// producing, hollow while they are all waiting or done. No animation - a spinner costs a
+	// timer of its own, and the counters already tick.
+	const name = `${run.live && run.branches.some(working) ? "●" : "○"} ${run.name}`;
+	// Pick the counters around the name rather than the other way round: a full counter block
+	// that leaves "pi-toolca..." identifies nothing. The cap stops one long name from forcing
+	// the stubbiest counters on a wide terminal.
+	const wanted = Math.min(visibleWidth(name), NAME_CAP);
+	const tiers = counterTiers(run, ended || now);
+	const right = tiers.find((tier) => visibleWidth(tier) <= inner - wanted - GAP) ?? tiers[tiers.length - 1] ?? "";
+	const rightWidth = visibleWidth(right);
+	const leftBudget = inner - rightWidth - GAP;
+	// Under six columns the name is all ellipsis, so the glyph alone says a run is there.
+	const left = leftBudget >= 6 ? truncateToWidth(name, leftBudget) : name.slice(0, 1);
+	const leftWidth = visibleWidth(left);
+	// The description carries its own leading gap: spaces take no colour, so the pieces stay
+	// four plain strings that concatenate in order to exactly `inner` columns.
+	const descBudget = inner - leftWidth - rightWidth - GAP * 2;
+	const description = descBudget >= MIN_DESC ? " ".repeat(GAP) + truncateToWidth(run.description, descBudget) : "";
+	const fill = Math.max(0, inner - leftWidth - visibleWidth(description) - rightWidth);
+	return { left, description, fill: " ".repeat(fill), right, live: run.live };
+};
+
+// ---------- REFERENCE 3: the flat live list ----------
+
+/** One row of reference 3. `head` is the nesting marker, the status dot and the agent name,
+ *  padded so every row's activity starts in the same column; `dotAt` is the one cell inside it
+ *  that takes the status colour, or -1 on a row that has no dot. `branch` is undefined on the
+ *  `○ main` row, and is what tone() below reads to pick that cell's colour. */
+export type ListRow = {
+	head: string;
+	dotAt: number;
+	activity: string;
+	fill: string;
+	right: string;
+	branch?: BranchView;
+};
+
+// Reference 3's nesting marker, two columns per level with `└ ` on the last. Same shape as
+// panel.ts's, because the panel is the zoomed-in view of these same rows.
+const nest = (depth: number) => (depth > 0 ? `${"  ".repeat(depth - 1)}└ ` : "");
+
+// Filled while the branch is working, hollow when it is pending, quiet or finished. `○ main`
+// is hollow for the same reason the reference draws it hollow: the session is not a branch.
+/** Filled while a branch is actually producing; hollow once it goes quiet or finishes. This is
+ *  the ONLY status-glyph rule in the file. The collapsed bar asks it of the whole run instead
+ *  of keeping a second opinion, which is what made reference 2 draw a filled dot on a run whose
+ *  branches were all waiting. */
+export const working = (branch: BranchView) =>
+	branch.alive && branch.status === "running" && branch.idleMs < IDLE_MS;
+
+const dot = (branch: BranchView) => (working(branch) ? "●" : "○");
+
+/** What the row says it is doing. A branch that was killed never got to write "done", so its
+ *  own `activity` is frozen on whatever it was mid-way through — a row reading "Running cd"
+ *  on a process that has been dead for four minutes. The exit file already knows better. */
+export const said = (branch: BranchView): string => {
+	if (branch.timedOut) return "Timed out";
+	if (branch.status === "error") return branch.error ? `Failed: ${branch.error}` : "Failed";
+	// Killed by hand or by a parent going away: a non-zero exit with no error text of its own.
+	if (branch.settled && branch.exitCode !== null && branch.exitCode !== 0 && !branch.report) return "Stopped";
+	return branch.activity ?? "";
+};
+
+// Chosen once for the whole list rather than per row, so the right-hand block is one column
+// instead of four ragged ones. Same order of sacrifice as the bar: the tokens go first, then
+// the arrow, and the clock last.
+const rowRight = (branch: BranchView, tier: number) => {
+	const time = clock(branch.elapsedMs);
+	if (tier === 0) return `${time} · ↓ ${compact(branch.tokens ?? 0)} tokens`;
+	if (tier === 1) return `${time} · ↓ ${compact(branch.tokens ?? 0)}`;
+	if (tier === 2) return time;
+	return "";
+};
+
+const widest = (values: string[]) => Math.max(0, ...values.map(visibleWidth));
+
+/** Reference 3, whole. Always at least one row, because a widget that renders zero lines
+ *  un-mounts itself and the input box drops a line the moment it does.
+ *
+ *  `max` is the row budget the component computes from the terminal height. Anything past it
+ *  collapses into a final "+N more", so the list has a ceiling but never a hidden agent. */
+export const layoutList = (width: number, run: RunState | undefined, now: number, max: number): ListRow[] => {
+	const inner = width - PAD * 2;
+	const main = "○ main";
+	// Sub-8 columns is not a terminal anyone reads a table in, and one stub row still holds the
+	// height the input box is sitting on.
+	if (inner < MIN_INNER) {
+		return [{ head: truncateToWidth(main, Math.max(0, inner), "…", true), dotAt: 0, activity: "", fill: "", right: "" }];
+	}
+
+	// readRun() already orders parents immediately above their children by launch order, so
+	// taking a prefix keeps the tree readable and, more importantly, keeps a row from sliding
+	// under the eye when a sibling settles. Sorting the live ones to the top would do that.
+	const all = !run || faded(run, now) ? [] : run.branches;
+	// The overflow row spends the budget's last slot rather than adding to it, so a run of forty
+	// branches is exactly as tall as a run of `max` and never one row taller.
+	const room = Math.max(0, max - 1); // rows left after `○ main`
+	const shown = all.length <= room ? all : all.slice(0, Math.max(0, room - 1));
+	const hidden = room > 0 ? all.length - shown.length : 0;
+	const overflow = hidden > 0 ? `+${hidden} more` : "";
+
+	const heads = shown.map((branch) => `${nest(branch.depth)}${dot(branch)} ${branch.name}`);
+	const headWidth = Math.min(inner, HEAD_CAP, Math.max(1, widest([main, ...heads, overflow])));
+
+	// One tier for the list, not one per row: the widest that still leaves the activity
+	// sentence a readable column next to the longest head.
+	let tier = 0;
+	let rightWidth = 0;
+	for (; tier < 3; tier++) {
+		rightWidth = widest(shown.map((branch) => rowRight(branch, tier)));
+		if (headWidth + COL_GAP + MIN_ACTIVITY + rightWidth <= inner) break;
+	}
+	if (tier === 3) rightWidth = 0;
+	// Clamped after the choice as well as before it: on a narrow terminal even the bare clock
+	// can be too wide, and an over-wide row is the one failure that moves the input box.
+	rightWidth = Math.min(rightWidth, Math.max(0, inner - headWidth));
+	const activityBudget = inner - headWidth - COL_GAP - rightWidth;
+
+	const row = (headText: string, at: number, text: string, right: string): ListRow => {
+		const head = truncateToWidth(headText, headWidth, "…", true);
+		const activity =
+			text && activityBudget >= MIN_ACTIVITY ? " ".repeat(COL_GAP) + truncateToWidth(text, activityBudget) : "";
+		// Padded on the left, so the clocks sit under each other instead of only the right edge
+		// lining up. Spaces take no colour, so this stays one string the component can dim.
+		const padded = " ".repeat(Math.max(0, rightWidth - visibleWidth(right))) + right;
+		const fill = Math.max(0, inner - headWidth - visibleWidth(activity) - visibleWidth(padded));
+		return { head, dotAt: at, activity, fill: " ".repeat(fill), right: padded };
+	};
+
+	// `○ main` is the session itself and always sits at the top, with no activity and no
+	// counters — exactly as the reference draws it. The widget factory is handed a tui and a
+	// theme and nothing else, so there is no ExtensionContext here to ask for the session's own
+	// usage, and a number the row could not stand behind is worse than the blank the screen
+	// actually shows.
+	const rows: ListRow[] = [row(main, 0, "", "")];
+	shown.forEach((branch, index) => {
+		// SAFETY: heads is built by mapping `shown` in order, so this index is populated.
+		const head = heads[index] as string;
+		rows.push({ ...row(head, visibleWidth(nest(branch.depth)), said(branch), rowRight(branch, tier)), branch });
+	});
+	// No dot on the overflow row: it stands for agents rather than being one.
+	if (overflow) rows.push(row(overflow, -1, "", ""));
+	return rows;
+};
+
+// ---------- THE FRAME ----------
+
+// The list's ceiling: `○ main` plus eight agents. Past that a "+N more" row stands in, so the
+// widget can never eat the screen it is sitting on top of.
+export const MAX_ROWS = 9;
+
+// The same distinctions panel.ts draws, because the panel is the zoomed-in view of these rows:
+// a timed-out branch answered nothing but did not crash, and a soft report is not a success.
+const tone = (branch: BranchView | undefined): ThemeColor => {
+	if (!branch) return "dim";
+	if (branch.timedOut) return "warning";
+	if (branch.status === "error" || (branch.exitCode !== null && branch.exitCode !== 0)) return "error";
+	if (branch.report === "PARTIAL" || branch.report === "NEED_STRONGER" || branch.report === "ASKING") return "warning";
+	if (branch.settled) return "success";
+	return branch.alive && branch.idleMs < IDLE_MS ? "accent" : "dim";
+};
+
+/** Everything on screen, in one string. A frame identical to the last one is never requested:
+ *  pi coalesces renders at 16 ms, but the cheapest frame is the one nobody asks for, and an
+ *  idle session whose reader ticks once a second would otherwise repaint a blank row for as
+ *  long as pi stays open. Width is deliberately absent — a resize repaints everything anyway. */
+export const renderKey = (run: RunState | undefined, now: number): string => {
+	if (!run || faded(run, now)) return "-";
+	const at = endedAt(run) || now;
+	const head = [run.name, run.description, run.done, run.total, run.tokens, Math.round((at - run.startedAt) / 1000)];
+	const rows = run.branches.map((branch) =>
+		[
+			branch.stem,
+			branch.depth,
+			branch.status,
+			said(branch),
+			branch.tokens,
+			Math.round(branch.elapsedMs / 1000),
+			branch.alive ? 1 : 0,
+			branch.idleMs < IDLE_MS ? 1 : 0,
+		].join(","),
+	);
+	return [...head, ...rows].join("|");
+};
+
+/** `theme.fg`, narrowed to the one method used, so the frame can be composed without a TUI. */
+export type Paint = (color: ThemeColor, text: string) => string;
+
+/**
+ * The whole frame. Three returns, and every one of them is provably the right height:
+ *
+ *   1. the panel is open, or the terminal is too narrow to hold anything -> `[blank]`, one element
+ *   2. a phased run is live  -> `[collapsed]`, one element, reference 2
+ *   3. anything else         -> layoutList(), which always yields at least the `○ main` row
+ *
+ * There is no fourth path, no early `return []`, and no branch that appends to a one-line
+ * array. That is the fixed-height rule: a widget above the editor that changes height moves the
+ * input box, and reference 2's line is the one the user is watching while typing.
+ */
+export const renderLines = (
+	width: number,
+	run: RunState | undefined,
+	now: number,
+	budget: number,
+	paint: Paint,
+	panelIsOpen = false,
+): string[] => {
+	const total = Math.max(0, width);
+
+	// Nothing running: draw nothing at all, not a bare `○ main`. pi renders the belowEditor
+	// container with spacerWhenEmpty and leadingSpacer both false, so zero lines really is zero
+	// rows and the footer above it does not move when a run starts or ends. That was not true
+	// while this slot sat above the editor - there, appearing and disappearing would have
+	// shifted the input box under the user's hands, which is why the idle row existed.
+	if (faded(run, now)) return [];
+
+	// The panel already draws all of this, and it took the editor's slot to do it. The width
+	// guard rides along: below two gutters plus a couple of columns there is nothing to say, and
+	// a blank line of the right height beats a two-column line in a one-column terminal.
+	if (panelIsOpen || total < PAD * 2 + 4) return [" ".repeat(total)];
+
+	const parts = isStructured(run) ? layoutBar(total, run, now) : undefined;
+	if (parts) {
+		// Composed in order, nothing padded here: layoutBar() already made the pieces sum to
+		// exactly the inner width, and a second opinion measured in code units rather than in
+		// terminal columns would be wrong the first time a description carried a wide
+		// character. Colour goes on after truncation, so a coloured line is never wider than
+		// the plain one that was measured.
+		return [
+			" ".repeat(PAD) +
+				paint(parts.live ? "accent" : "dim", parts.left.slice(0, 1)) +
+				paint("text", parts.left.slice(1)) +
+				paint("muted", parts.description) +
+				parts.fill +
+				paint("dim", parts.right) +
+				" ".repeat(PAD),
+		];
+	}
+
+	return layoutList(total, run, now, budget).map((row) => {
+		// `head` is plain text, and everything left of the dot is `└`, a space, or a name
+		// matching ^[a-z0-9][a-z0-9._-]*$ — so a visible column and a code-unit index are the
+		// same number here and slicing cannot cut a character in half.
+		const head =
+			row.dotAt >= 0
+				? paint("dim", row.head.slice(0, row.dotAt)) +
+					paint(tone(row.branch), row.head.slice(row.dotAt, row.dotAt + 1)) +
+					paint(row.branch ? "text" : "dim", row.head.slice(row.dotAt + 1))
+				: paint("dim", row.head);
+		return " ".repeat(PAD) + head + paint("muted", row.activity) + row.fill + paint("dim", row.right) + " ".repeat(PAD);
+	});
+};