pi-umbra-subagents 0.1.0

package/extensions/umbra-subagents/panel.check.ts

@@ -0,0 +1,193 @@
+import { strict as assert } from "node:assert";
+import { visibleWidth, type TUI } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { BranchView, RunState } from "./skills/delegate/state.ts";
+import { createPanel, type PanelSource } from "./panel.ts";
+
+// The one runnable check for the panel. Run it with:
+//   node --experimental-strip-types build/panel.check.ts
+// (node resolves "@earendil-works/*" through build/node_modules, a junction to the copy pi
+// already has: mklink /J build\node_modules %USERPROFILE%\.bun\install\global\node_modules)
+//
+// It renders the component against a stub theme, a stub TUI and a stub source, so it never
+// starts pi, never reads a run directory and never kills anything. What it protects is the
+// arithmetic: the height and the two box widths must be identical on every frame whatever
+// the data does, because a line that wraps or a box that disagrees costs a row and moves
+// everything under it. The keys are checked for what they promise in the footer and
+// nothing more.
+
+// SAFETY: the panel only ever calls fg, bold and terminal.rows. Uncoloured output also
+// makes every assertion below a plain string comparison.
+const theme = { fg: (_color: string, text: string) => text, bold: (text: string) => text } as unknown as Theme;
+let renders = 0;
+// SAFETY: same, for requestRender and terminal.rows.
+const tui = { terminal: { rows: 40 }, requestRender: () => renders++ } as unknown as TUI;
+
+const now = Date.now();
+const branch = (phase: string, name: string, index: number, over: Partial<BranchView> = {}): BranchView => ({
+	phase,
+	name,
+	index,
+	parent: null,
+	model: "Opus 5",
+	pid: 1000 + index,
+	status: "running",
+	activity: "Reading vite.config.ts",
+	tokens: 72_700,
+	startedAt: now - 195_000,
+	updatedAt: now,
+	report: null,
+	error: null,
+	stem: `${phase}-${name}`,
+	label: `${phase}:${name}`,
+	depth: 0,
+	elapsedMs: 195_000,
+	idleMs: 0,
+	exitCode: null,
+	timedOut: false,
+	alive: true,
+	settled: false,
+	...over,
+});
+
+const run: RunState = {
+	dir: "/tmp/.pi-out/20260905-030000-pi-toolcall-render",
+	name: "pi-toolcall-render",
+	description: "Map how pi renders tool calls and whether an extension can override it",
+	startedAt: now - 196_000,
+	phases: ["map", "design"],
+	activePhase: 0,
+	branches: [
+		branch("map", "core-render", 1, { idleMs: 53_000 }),
+		branch("map", "omp-intercept", 2, { tokens: 89_600 }),
+		branch("map", "api-surface", 3, { tokens: 108_600 }),
+		branch("map", "flicker", 4, { tokens: 106_900 }),
+	],
+	done: 0,
+	total: 4,
+	tokens: 397_800,
+	live: true,
+};
+
+const stopped: string[] = [];
+const source: PanelSource = {
+	run: () => run,
+	stop: (dead) => stopped.push(dead.stem),
+	subscribe: () => () => {},
+};
+
+let closed = 0;
+const panel = createPanel(tui, theme, source, () => closed++);
+// handleInput is optional on Component, so bind it once here rather than asserting non-null at
+// each of the fourteen call sites. A panel that did not implement it is a failure worth naming.
+if (!panel.handleInput) throw new Error("the panel implements no handleInput; ↑↓, x and esc cannot work");
+const press = panel.handleInput.bind(panel);
+const KEY = { up: "\x1b[A", down: "\x1b[B", escape: "\x1b", stop: "x" };
+const WIDTH = 88;
+const height = panel.render(WIDTH).length;
+
+const boxLines = (lines: string[]) => lines.filter((line) => /[┌│└]/.test(line));
+// Height and width are one assertion, not two: a line one column too wide wraps in the
+// terminal, which costs a row the array cannot show. So the header, the footer and every
+// other piece of chrome is measured, not just the box.
+const fits = (lines: string[], width: number, label: string) => {
+	for (const line of lines) {
+		assert.ok(visibleWidth(line) <= width, `${label}: a line is ${visibleWidth(line)} wide, over ${width}`);
+	}
+	const widths = new Set(boxLines(lines).map(visibleWidth));
+	assert.equal(widths.size, 1, `${label}: box lines disagree on width: ${[...widths]}`);
+	return [...widths][0];
+};
+
+const frame = (label: string) => {
+	const lines = panel.render(WIDTH);
+	assert.equal(lines.length, height, `${label}: height changed`);
+	fits(lines, WIDTH, label);
+	return lines.join("\n");
+};
+
+// The reference-1 frame: header, sidebar, four rows, footer.
+const first = frame("initial");
+assert.match(first, /pi-toolcall-render\s+0\/4 agents · 3m16s/);
+assert.match(first, /> 1 Map 0\/4/);
+assert.match(first, /2 Design/);
+assert.match(first, /Map · 4 agents/);
+assert.match(first, /● map:core-render\s+Opus 5 · 72\.7k tok · idle 53s\s+3m15s/);
+assert.match(first, /↑↓ select · x stop · esc back/);
+assert.ok(!first.includes("pause") && !first.includes("save"), "the dropped keys are back in the footer");
+
+// Selection wraps through the whole run, so it crosses into the next phase, and the
+// sidebar marker and the box title follow it there rather than needing a second focus.
+run.branches.push(branch("design", "api", 5));
+run.total = 5;
+for (let n = 0; n < 4; n++) press(KEY.down);
+const crossed = frame("after crossing into Design");
+assert.match(crossed, /> 2 Design 0\/1/);
+assert.match(crossed, /Design · 1 agents/);
+assert.equal(renders, 4, "every handled key asks for exactly one render");
+
+// x stops the selected unsettled branch, and only an unsettled one: a finished branch's
+// pid belongs to whatever the OS handed it to next.
+press(KEY.stop);
+assert.deepEqual(stopped, ["design-api"]);
+run.branches[4] = branch("design", "api", 5, { status: "done", settled: true, alive: false, exitCode: 0, report: "OK" });
+press(KEY.stop);
+assert.deepEqual(stopped, ["design-api"], "a settled branch must not be killed twice");
+
+// A branch arriving mid-run must not slide the cursor onto another row, and the panel must
+// not grow a line for it either: the box scrolls instead.
+run.branches.unshift(branch("design", "late", 6));
+run.total = 6;
+const arrived = frame("after a branch arrives");
+assert.match(arrived, /Design · 2 agents/, "the new branch joined the shown phase");
+assert.match(arrived, /design:api/, "the selection is still on its own row");
+
+// A nested branch gets reference 3's marker here too, and the marker is part of the label
+// column, so the model column stays aligned with its parent's.
+run.branches[0] = branch("design", "late", 6, { parent: "design-api", depth: 1 });
+assert.match(frame("nested branch"), /└ design:late\s+Opus 5/);
+
+// The honest dash, not a fake 0, and the three states that are not "running".
+run.branches[0] = branch("design", "late", 6, { tokens: null });
+assert.match(frame("no usage reported yet"), /design:late\s+Opus 5 · –/);
+run.branches[0] = branch("design", "late", 6, { timedOut: true, exitCode: 124, settled: true, status: "running" });
+assert.match(frame("timed out"), /design:late\s+Opus 5 · 72\.7k tok · timeout/);
+run.branches[0] = branch("design", "late", 6, { status: "error", error: "no credentials", settled: true });
+assert.match(frame("errored"), /design:late\s+Opus 5 · 72\.7k tok · error/);
+
+// A phase that run.json never declared still gets its own box: the title is read off the
+// selected branch, not off a phase index, so no row can vanish into another phase's box.
+// The sidebar simply carries no marker while that row is selected.
+run.branches[0] = branch("verify", "late", 6);
+press(KEY.down);
+const undeclared = frame("undeclared phase");
+assert.match(undeclared, /Verify · 1 agents/);
+assert.match(undeclared, /● verify:late/);
+
+// Every width the boxes claim to support draws to exactly that width. One column too wide
+// wraps, and a wrapped line costs a row that everything below it then moves by.
+for (let width = 13; width <= 200; width++) {
+	const lines = panel.render(width);
+	assert.equal(lines.length, height, `width ${width}: height changed`);
+	assert.equal(fits(lines, width, `width ${width}`), width, `width ${width}: the boxes are not ${width} wide`);
+}
+
+// Nothing to draw is not a crash, and neither is a run that ends under the panel: an empty
+// list must not reach Math.max() with no seed, which is the -Infinity the seed extension
+// still carries.
+run.branches.length = 0;
+run.done = 0;
+frame("empty run");
+run.live = false;
+frame("ended run");
+press(KEY.stop);
+press(KEY.down);
+
+// esc closes, and closing is the only thing that closes.
+press("q");
+assert.equal(closed, 0);
+press(KEY.escape);
+assert.equal(closed, 1);
+panel.dispose();
+
+console.log(`ok - panel: ${height} lines, ${WIDTH} columns, ${renders} renders`);

package/extensions/umbra-subagents/panel.ts

@@ -0,0 +1,333 @@
+import { Editor, truncateToWidth, visibleWidth, type Component, type TUI, matchesKey } from "@earendil-works/pi-tui";
+import type { ExtensionContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { BranchView, RunState } from "./skills/delegate/state.ts";
+
+// Reference 1, the full-screen panel: the zoomed-in view of the run the collapsed bar
+// summarises. Phases on the left, the selected phase's branches on the right, one header
+// line and one footer line.
+//
+// Opened with ctx.ui.custom() and NO `overlay` option, so it takes editorContainer's slot
+// instead of floating over it. pi snapshots the editor's unsent text before the swap and
+// calls setText with it on close, so "esc returns to the input box with unsent text
+// intact" costs zero lines here — the overlay path is the one that would not.
+//
+// The panel reads a snapshot and nothing else: no file, no process, no kill. The bar
+// already polls readRun() once a second for both views, so a second reader could only
+// disagree with it by a frame, and a component with no I/O cannot be hung by a branch that
+// dies. Its one timer asks for a frame and reads nothing, because elapsed and "idle Ns"
+// move with the clock even on a run whose files have stopped changing.
+
+/** What the panel needs from whoever owns the poll. `stop` is the producer's kill. */
+export type PanelSource = {
+	/** undefined when no run has been seen yet. */
+	run(): RunState | undefined;
+	/** Called only for a branch the panel drew as unsettled. */
+	stop(branch: BranchView): void;
+	/** Fires on every change; returns the unsubscribe. */
+	subscribe(fn: () => void): () => void;
+};
+
+// A finished run closes the panel on its own after this long, so a panel left open does not sit
+// over the editor. Only a run the panel watched finish: one opened already finished stays.
+const AUTO_CLOSE_MS = 8_000;
+
+// The user dropped `p pause` and `s save`: they said they never used them.
+const FOOTER = "↑↓ select · x stop · esc back";
+
+// Rule, header, description, box top, box bottom, footer — the lines that are not body.
+const CHROME = 6;
+// Rows left to the transcript, the status line, the collapsed bar and pi's own footer.
+const RESERVE = 4;
+const MIN_BODY = 3;
+// Reference 1 ends every agent row `3m15s   │`, three columns clear of the border.
+const RIGHT_GUTTER = 3;
+// Reference 1 shows "idle 53s", so the marker has to appear well before a minute.
+const IDLE_MS = 15_000;
+
+// "45s", "3m15s". No space before the seconds: this string sits at the right edge of every
+// row, and the panel's columns are tighter than the flat list's.
+const clock = (ms: number) => {
+	const total = Math.max(0, Math.round(ms / 1000));
+	const minutes = Math.floor(total / 60);
+	return minutes ? `${minutes}m${String(total % 60).padStart(2, "0")}s` : `${total}s`;
+};
+
+// A timed-out branch answered nothing but is not a crash, and a soft report is not a
+// success. Colour carries the difference; note() repeats it in text, because a monochrome
+// theme would otherwise make the two identical.
+const dotColor = (branch: BranchView): ThemeColor => {
+	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.status === "running" ? "accent" : "dim";
+};
+
+const note = (branch: BranchView): string => {
+	if (branch.timedOut) return " · timeout";
+	if (branch.status === "error") return " · error";
+	// A settled branch stopped emitting because it finished, not because it is stuck.
+	if (!branch.settled && branch.idleMs >= IDLE_MS) return ` · idle ${clock(branch.idleMs)}`;
+	return "";
+};
+
+// The producer leaves tokens at 0 or null until the provider reports, and some report only
+// at completion. "0 tok" would be a fake number for minutes; the dash is an honest one.
+const tokenText = (count: number | null) =>
+	!count ? "–" : count < 1000 ? `${count} tok` : `${(count / 1000).toFixed(1)}k tok`;
+
+// Run.phases holds the branch's own identifier ("map"), because the stem is
+// `${phase}-${name}` and has to be a legal NTFS filename and a legal --session-id.
+// Reference 1's sidebar reads "Map" while its rows read "map:core-render", so the capital
+// is put back at render time rather than stored a second time in the producer.
+const phaseTitle = (name: string) => name.charAt(0).toUpperCase() + name.slice(1);
+
+// Reference 3's nesting marker, kept here too: a branch that was spawned by another is
+// otherwise indistinguishable from its siblings, and readRun() already orders parents
+// before children, so the prefix needs no tree walk.
+const nest = (depth: number) => (depth > 0 ? `${"  ".repeat(depth - 1)}└ ` : "");
+
+/**
+ * The panel component. `close` is the `done` callback ctx.ui.custom hands the factory:
+ * calling it restores the editor, resolves the promise, then calls dispose().
+ */
+export const createPanel = (
+	tui: TUI,
+	theme: Theme,
+	source: PanelSource,
+	close: () => void,
+	orphaned: () => void = () => {},
+): Component & { dispose(): void } => {
+	let shown = source.run();
+	let sawLive = shown?.live === true;
+	let finishedAt: number | undefined;
+	// Selection is keyed on the stem, never on a row index: a branch arriving mid-run would
+	// otherwise slide the cursor onto a different row under the user's hands.
+	let selectedStem =
+		shown?.branches.find((branch) => branch.phase === shown?.phases[shown.activePhase])?.stem ??
+		shown?.branches[0]?.stem;
+	let top = 0;
+
+	// Fixed for the life of the panel. Growing the box as branches arrive would move every
+	// line below it, and a height change is one of the things that forces a full repaint.
+	const bodyAtOpen = Math.max(MIN_BODY, shown?.phases.length ?? 0, shown?.branches.length ?? 0);
+
+	// Never requestRender(true): that resets the render state and repaints the whole screen.
+	const unsubscribe = source.subscribe(() => tui.requestRender());
+	// Elapsed and "idle Ns" move with the clock rather than with the files, so the panel keeps
+	// a second hand of its own instead of inheriting whatever cadence the reader polls at. It
+	// only asks for a frame — nothing is re-read here — and pi coalesces the request at 16 ms.
+	const tick = setInterval(() => {
+		// Another dialog (ask_user_question, a select) that takes the editor slot while the panel
+		// is up swaps it out without calling done(), and pi later restores the editor, not the
+		// panel. Focus back on an editor while this panel still thinks it is open is that case:
+		// let go, or every door stays shut until /reload. Not done(): pi's restore would put back
+		// text saved before the dialog over whatever was typed since.
+		const focused = tui.getFocusedComponent();
+		if (focused !== self && focused instanceof Editor) {
+			self.dispose();
+			orphaned();
+			return;
+		}
+		const run = source.run();
+		if (run?.live) {
+			sawLive = true;
+			finishedAt = undefined;
+		} else if (sawLive) {
+			finishedAt ??= Date.now();
+			if (Date.now() - finishedAt >= AUTO_CLOSE_MS) return close();
+		}
+		tui.requestRender();
+	}, 1000);
+	// A panel timer must never be the reason node refuses to exit.
+	tick.unref();
+
+	const box = {
+		top(title: string, inner: number): string {
+			const text = truncateToWidth(title, Math.max(0, inner - 4), "…");
+			// "┌ " + text + " " + dashes + "┐" has to come to inner + 2 columns.
+			const dashes = Math.max(0, inner - visibleWidth(text) - 2);
+			return theme.fg("border", "┌ ") + theme.fg("text", text) + theme.fg("border", ` ${"─".repeat(dashes)}┐`);
+		},
+		row(content: string, inner: number): string {
+			// truncateToWidth pads as well as cuts, so a row is exactly `inner` wide however
+			// much colour is inside it and the two boxes can never drift apart.
+			return theme.fg("border", "│") + truncateToWidth(content, inner, "…", true) + theme.fg("border", "│");
+		},
+		bottom(inner: number): string {
+			return theme.fg("border", `└${"─".repeat(inner)}┘`);
+		},
+	};
+
+	const self = {
+		render(width: number): string[] {
+			// A run can be replaced under the panel; keeping the last one means the component
+			// never blanks for a frame while the reader is between ticks.
+			shown = source.run() ?? shown;
+			const run = shown;
+			const now = Date.now();
+			// One leading space, like the reference. The floor keeps the two boxes summing to
+			// exactly `inner`: under 13 columns they do not fit, the line wraps, and a wrapped
+			// line costs a row that everything below it then moves by.
+			const inner = Math.max(12, width - 1);
+			// Every line is cut to `width`, ask.ts style: one column too many wraps in the
+			// terminal, and a wrapped line costs a row that everything below it then moves by.
+			// The box rows are built to exactly `width` already, so only the chrome needs it.
+			const fit = (line: string) => truncateToWidth(line, width, "…");
+			if (!run) return [fit(` ${theme.fg("dim", "no run")}`), fit(`  ${theme.fg("dim", FOOTER)}`)];
+
+			const branches = run.branches;
+			const selected = branches.find((branch) => branch.stem === selectedStem) ?? branches[0];
+			// The sidebar follows the selection instead of being a second focus. One cursor,
+			// no left/right keys, and the footer stays literally true. The phase is looked up
+			// FROM the selected branch rather than the branch found from a phase index, so a
+			// branch whose phase run.json never declared is still drawn under its own name
+			// instead of disappearing into the first phase's box. Then the sidebar simply has
+			// no marker on that frame, which is honest.
+			const title = selected?.phase ?? run.phases[run.activePhase] ?? "";
+			const phase = run.phases.indexOf(title);
+			const list = branches.filter((branch) => branch.phase === title);
+
+			const sidebarRows = run.phases.map((name, index) => {
+				const mine = branches.filter((branch) => branch.phase === name);
+				const done = mine.filter((branch) => branch.settled).length;
+				return `${index === phase ? ">" : " "} ${index + 1} ${phaseTitle(name)}${mine.length ? ` ${done}/${mine.length}` : ""}`;
+			});
+			// 10 is "┌ Phases ─┐" without its borders: the box title has to fit as well as the
+			// rows. A third of the width is the ceiling, so a long phase name cannot squeeze
+			// the agent list down to nothing.
+			const sidebarInner = Math.min(
+				Math.max(10, ...sidebarRows.map((row) => row.length)) + 1,
+				Math.max(3, Math.floor(inner / 3)),
+			);
+			const agentInner = Math.max(3, inner - sidebarInner - 4);
+
+			// terminal.rows only changes on a resize, which repaints everything anyway, so
+			// reading it per frame costs nothing and keeps the panel inside a shrunk window.
+			const body = Math.min(bodyAtOpen, Math.max(MIN_BODY, tui.terminal.rows - CHROME - RESERVE));
+
+			const index = Math.max(0, list.findIndex((branch) => branch.stem === selected?.stem));
+			if (index < top) top = index;
+			if (index >= top + body) top = index - body + 1;
+			top = Math.max(0, Math.min(top, list.length - body));
+
+			// Seeded, because Math.max() over an empty list is -Infinity — the bug the seed
+			// extension carries at agents-panel.ts:75.
+			const labelWidth = Math.max(0, ...list.map((branch) => nest(branch.depth).length + branch.label.length));
+			const agentRows = list.slice(top, top + body).map((branch) => {
+				const right = theme.fg("dim", clock(branch.elapsedMs));
+				const head = (nest(branch.depth) + branch.label).padEnd(labelWidth);
+				const left =
+					`${theme.fg(dotColor(branch), "●")} ` +
+					theme.fg(branch.stem === selected?.stem ? "accent" : "text", head) +
+					` ${theme.fg("dim", `${branch.model} · ${tokenText(branch.tokens)}${note(branch)}`)}`;
+				// One space in from the left border, three out to the right one: reference 1
+				// writes `3m15s   │`, and a clock hard against the border reads as an overflow.
+				// Widths are measured, never assumed: `left` is full of escape codes.
+				// The sidebar's `>` marks the phase the selection is in, not a second focus, so this
+				// row needs a marker of its own. Without one the accent colour was the only sign of
+				// the cursor, the sidebar's arrow was the only `>` on screen, and `x` read as though
+				// it would stop a phase. One column makes the footer's "x stop" true to the eye.
+				const cursor = branch.stem === selected?.stem ? theme.fg("accent", ">") : " ";
+				const room = Math.max(0, agentInner - visibleWidth(right) - RIGHT_GUTTER - 3);
+				return `${cursor} ${truncateToWidth(left, room, "…", true)} ${right}${" ".repeat(RIGHT_GUTTER)}`;
+			});
+			if (!agentRows.length) agentRows.push(`  ${theme.fg("dim", "no branches in this phase")}`);
+
+			// RunState has no endedAt, so a finished run's clock is the last branch to stop
+			// rather than a wall clock that keeps ticking after everything is done.
+			const elapsed = run.live
+				? now - run.startedAt
+				: Math.max(0, ...branches.map((branch) => branch.startedAt + branch.elapsedMs - run.startedAt));
+			const stat = `${run.done}/${run.total} agents · ${clock(elapsed)}`;
+			const name = truncateToWidth(
+				theme.bold(theme.fg("text", run.name)),
+				Math.max(0, inner - visibleWidth(stat) - 3),
+				"…",
+			);
+			const gap = Math.max(1, inner - 2 - visibleWidth(name) - visibleWidth(stat));
+
+			const lines = [
+				` ${theme.fg("borderMuted", "─".repeat(inner))}`,
+				fit(`  ${name}${" ".repeat(gap)}${theme.fg("dim", stat)}`),
+				`  ${theme.fg("muted", truncateToWidth(run.description, Math.max(0, inner - 2), "…"))}`,
+				` ${box.top("Phases", sidebarInner)}${box.top(`${title ? phaseTitle(title) : "Agents"} · ${list.length} agents`, agentInner)}`,
+			];
+			for (let row = 0; row < body; row++) {
+				lines.push(` ${box.row(sidebarRows[row] ?? "", sidebarInner)}${box.row(agentRows[row] ?? "", agentInner)}`);
+			}
+			lines.push(` ${box.bottom(sidebarInner)}${box.bottom(agentInner)}`);
+			lines.push(fit(`  ${theme.fg("dim", FOOTER)}`));
+			return lines;
+		},
+
+		handleInput(data: string): void {
+			// ctrl+c is pi's own select cancel, and alt+a opened the panel, so it closes it too.
+			if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || matchesKey(data, "alt+a")) return close();
+			// Read the source, not the last frame: a key can land between renders, and `x` has
+			// to judge a branch by its status now rather than by the one drawn 16 ms ago.
+			shown = source.run() ?? shown;
+			const branches = shown?.branches ?? [];
+			if (!branches.length) return;
+			// Up and down walk the whole run, not one phase, so falling off the end of Map
+			// lands on the first branch of Design and the sidebar and box title follow.
+			const index = Math.max(0, branches.findIndex((branch) => branch.stem === selectedStem));
+			if (matchesKey(data, "up")) selectedStem = branches[(index - 1 + branches.length) % branches.length]?.stem;
+			else if (matchesKey(data, "down")) selectedStem = branches[(index + 1) % branches.length]?.stem;
+			// matchesKey, not a byte compare: Caps Lock or Shift sends "X", and the kitty protocol
+			// can send x with lock bits set.
+			else if (matchesKey(data, "x") || matchesKey(data, "shift+x")) {
+				const branch = branches[index];
+				// A settled branch's pid belongs to whatever the OS handed it to next, so the
+				// guard is here as well as in the producer. A pid not yet written by the beacon is
+				// no reason to refuse: the producer finds its own child without it. Stopping is
+				// silent and immediate: the footer promises `x stop`, not a confirmation.
+				if (branch && !branch.settled) source.stop(branch);
+			} else return;
+			tui.requestRender();
+		},
+
+		invalidate(): void {
+			// Nothing is cached between frames; render() reads the snapshot fresh every time.
+		},
+
+		dispose(): void {
+			unsubscribe();
+			clearInterval(tick);
+		},
+	};
+	return self;
+};
+
+// One panel at a time. A second ctx.ui.custom() would clear editorContainer again, and the
+// first panel's close would then restore an editor the second one had already replaced.
+let showing = false;
+
+/**
+ * The one door in. The bar owns `/umb-agents`, `alt+a` and the down-arrow probe and calls this
+ * from all three, so the panel registers no command and no shortcut of its own — a second
+ * registration of the same name is a collision, not a third way in.
+ */
+export const openPanel = async (ctx: ExtensionContext, source: PanelSource): Promise<void> => {
+	if (ctx.mode !== "tui" || showing) return;
+	// Opening on nothing draws an empty box the user cannot fill, and the down-arrow door
+	// fires whether or not a run exists.
+	if (!source.run()) return ctx.ui.notify("no agent run to show");
+	showing = true;
+	let orphan = () => {};
+	const orphaned = new Promise<void>((resolve) => (orphan = resolve));
+	try {
+		// No `overlay` option: the panel takes the editor's slot rather than floating over
+		// it, which is the path that saves and restores the user's unsent text. The promise
+		// resolves when the component calls done(), and pi calls dispose() straight after;
+		// `orphaned` resolves when another dialog took the slot and pi never will.
+		await Promise.race([
+			ctx.ui.custom<undefined>((tui, theme, _keybindings, done) =>
+				createPanel(tui, theme, source, () => done(undefined), orphan),
+			),
+			orphaned,
+		]);
+	} finally {
+		showing = false;
+	}
+};

package/extensions/umbra-subagents/skills/delegate/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: delegate
+description: Fan out independent read-only work (find usages across many files, summarize several modules, run tests and report, compare options) to separate cheap pi processes and read back their result files. Use whenever a task splits into 2+ lookups that do not need each other, or when the user writes "delegate", "fan out", "subagent", or starts a message with "delegate:".
+---
+
+# Delegate
+
+pi has no subagent tool. A branch is a separate `pi -p` process with an empty
+context and read-only tools; its result is a file this session reads. Nothing
+is added to this session's prompt. Each branch keeps its session under
+`$run/sessions/<stem>`, so a finished branch can be continued with `dresume`.
+
+Each branch also writes a small live state file, so the agent panel can show
+what it is doing while it runs instead of only what it concluded at the end.
+That is handled by `run.sh` — do not hand-roll the `pi -p` command line.
+
+## Run
+
+One bash call. `dstart` records the session cwd and must run **before** any
+`cd`, because the panel watches the directory pi started in. The smart tier is
+this session's own model, `$PI_PROVIDER/$PI_MODEL`; `$FAST` and `$LOAD` come
+from `delegate.env`, then from `~/.pi/agent/delegate.env` when it exists.
+
+```bash
+. <skill dir>/run.sh   # <skill dir>: the directory this SKILL.md is in
+dstart <slug> "<one line describing the whole run>" map
+cd <deepest folder the branches touch>   # optional, and only after dstart
+
+branch map explorer-1 "$FAST" "Find every file that imports X. List file:line."
+branch map explorer-2 "$FAST" "..."
+dwait
+grep -L '^STATUS: OK' "$run"/*.md
+```
+
+`dstart <slug> <description> <phase>...` names every phase up front, in the
+order the panel lists them. `branch <phase> <name> <model> <task>` seeds and
+launches one branch. `dwait` publishes the run and waits for all of them.
+
+`<slug>`, phase names and branch names must all match `^[a-z0-9][a-z0-9._-]*$`:
+they become filenames. A duplicate `<phase>-<name>` is refused rather than
+silently sharing one state file with another branch.
+
+Every branch defaults to `$FAST`. Use `$PI_PROVIDER/$PI_MODEL` when the user
+asks for the smart tier or the same model, or any `provider/id` from `/model`
+when they name one.
+
+## Read
+
+Read `$run/*.md`. The `grep -L` line lists branches that did not report
+`STATUS: OK` (PARTIAL, NEED_STRONGER, ASKING, or a malformed answer). Re-run
+each PARTIAL or NEED_STRONGER one with the same task on
+`$PI_PROVIDER/$PI_MODEL`. A missing STATUS line is NEED_STRONGER, never
+success. Check FILES paths with `ls` before relying on them.
+
+`STATUS: ASKING` means the branch stopped on a decision, with `QUESTION:` and
+`OPTIONS:` lines. Answer it yourself from this conversation when you can;
+only when the user alone can decide, ask them with `ask_user_question` first.
+Then continue the branch in its own session and read the new report:
+
+```bash
+. <skill dir>/run.sh
+dresume "$run" <stem> "<answer>"   # one per asking branch
+wait; cat "$run/<stem>.md"
+```
+
+A second wave is a second batch of `branch` calls on the next phase name
+followed by another `dwait`, in the same bash call.
+
+## Rules
+
+- Branches are read-only (`--tools read,grep,find,ls`). Add `bash` only for
+  a test-and-report branch. Work that must edit files stays in this session.
+- A branch given `bash` may source `run.sh` and fan out again. It joins THIS run
+  directory instead of starting a rival one, keeps this branch's phase, and the
+  panel draws its children indented under it. Two levels is the sensible limit.
+- A branch that needs one more extension gets it explicitly, e.g.
+  `-e $HOME/.pi/agent/npm/node_modules/pi-web-access-lean` for research —
+  append it to `$LOAD` before the first `branch` call, because
+  `--no-extensions` drops provider extensions too.
+- 2 to 6 branches per run. Each task is self-contained: name the files or
+  directory, say exactly what to return.
+- `.pi-out/` is gitignored scratch. Follow-up to a branch: same `branch` call,
+  a new name, new task text.
+- Read `$run/<phase>-<name>.err` when a branch reports nothing; that is where
+  a bad model id or a missing provider extension lands.
+
+## Files
+
+- `run.sh` — `dstart` / `branch` / `dwait` / `dresume`. Check: `bash run.check.sh`.
+- `beacon.ts` — loaded into each branch with `-e`, writes its state file.
+- `state.ts` — the on-disk schema and `readRun()`, which the panel imports.
+  Check: `bun run state.check.ts`.
+- `report.md` — the report contract, appended to every branch's system prompt.
+- `delegate.env` — defaults for `$FAST`, `$LOAD` and `$DELEGATE_TIMEOUT`. The owner's
+  own values go in `~/.pi/agent/delegate.env`, which is read after it.