pi-umbra-subagents 0.1.0

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

@@ -0,0 +1,229 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { MAX_ROWS, layoutBar, layoutList, renderKey, renderLines } from "./bar/bar-line.ts";
+import type { BranchView, RunState } from "./skills/delegate/state.ts";
+
+// The widget sits directly above the input box, so two things can hurt and both are checked
+// here rather than argued in a comment:
+//
+//   1. a composed line one column too wide wraps in the terminal and pushes the box down
+//   2. the collapsed shape rendering anything other than exactly one line does the same
+//
+// Everything under test is pure, so this needs no terminal, no theme and no pi.
+// Run with: bun run bar.check.ts
+
+// A function declaration, not a const arrow: TypeScript only narrows past a never-returning
+// call when it is declared this way, and every assertion below relies on that narrowing.
+function fail(message: string): never {
+	throw new Error(message);
+}
+
+// SAFETY: only the fields the layouts read are populated; every one of them is here.
+const branch = (over: Partial<BranchView> = {}): BranchView =>
+	({
+		phase: "map",
+		name: "general-purpose",
+		parent: null,
+		index: 1,
+		model: "Opus 5",
+		pid: 4242,
+		status: "running",
+		activity: "Grepping localStorage keys in office-persist.ts",
+		tokens: 56_500,
+		startedAt: 0,
+		updatedAt: 232_000,
+		report: null,
+		error: null,
+		stem: "map-general-purpose",
+		label: "map:general-purpose",
+		depth: 0,
+		elapsedMs: 232_000, // 3m 52s
+		idleMs: 0,
+		exitCode: null,
+		timedOut: false,
+		alive: true,
+		settled: false,
+		...over,
+	}) as BranchView;
+
+const run = (over: Partial<RunState> = {}): RunState =>
+	({
+		dir: ".pi-out/20260905-030000",
+		name: "pi-toolcall-render",
+		description: "Map how pi renders tool calls and whether an extension can override it",
+		startedAt: 0,
+		phases: ["map", "design"],
+		activePhase: 0,
+		branches: [],
+		done: 2,
+		total: 4,
+		tokens: 397_800,
+		live: true,
+		...over,
+	}) as RunState;
+
+const now = 278_000; // 4m 38s
+
+// ---------- reference 2, the collapsed bar ----------
+
+// One branch producing, so the leading glyph has something to be filled about. An empty
+// branches[] would read as "the whole run is quiet", which is a different assertion below.
+const phased = run({ branches: [branch()] });
+
+for (let width = 8; width <= 200; width++) {
+	const parts = layoutBar(width, phased, now);
+	if (!parts) {
+		if (width - 2 >= 8) fail(`no layout at width ${width}`);
+		continue;
+	}
+	const used =
+		visibleWidth(parts.left) + visibleWidth(parts.description) + parts.fill.length + visibleWidth(parts.right);
+	if (used !== width - 2) fail(`bar width ${width}: composed ${used}, expected ${width - 2}`);
+	if (!parts.right.startsWith("2/4")) fail(`bar width ${width}: counters mangled: ${parts.right}`);
+}
+
+const wide = layoutBar(100, phased, now);
+if (!wide) fail("no layout at width 100");
+if (wide.right !== "2/4 agents done · 4m 38s · ↓ 397.8k tokens") fail(`wide tier: ${wide.right}`);
+if (!wide.description.includes("...")) fail(`description not truncated at 100: ${wide.description}`);
+if (!wide.left.startsWith("●")) fail(`live glyph: ${wide.left}`);
+
+// Reference 2's pasted frame reads `○ pi-toolcall-render ... 2/4 agents done` — a run that is
+// live but waiting. One rule covers both screens: filled means a branch is producing right
+// now, not merely that the run has not finished.
+const waiting = layoutBar(100, run({ branches: [branch({ idleMs: 20_000 })] }), now);
+if (!waiting?.left.startsWith("○")) fail(`live-but-quiet glyph: ${waiting?.left}`);
+if (layoutBar(30, phased, now)?.description !== "") fail("description survived 30 columns");
+
+// A finished run stops counting: the clock freezes at the last write, not at Date.now().
+const settled = run({ live: false, done: 4, branches: [branch({ updatedAt: now, settled: true, alive: false })] });
+const frozen = layoutBar(100, settled, now + 5_000);
+if (!frozen) fail("no layout for a settled run inside its linger window");
+if (!frozen.right.includes("4m 38s")) fail(`clock kept running after the run ended: ${frozen.right}`);
+if (!frozen.left.startsWith("○")) fail(`finished glyph: ${frozen.left}`);
+if (layoutBar(100, settled, now + 31_000)) fail("finished run outstayed LINGER_MS");
+
+// Zero is a lie while a provider reports usage only at completion, so it renders as a dash.
+if (!layoutBar(100, run({ tokens: 0 }), now)?.right.includes("↓ – tokens")) fail("zero tokens rendered as a number");
+if (layoutBar(100, run({ total: 0 }), now)) fail("empty run rendered");
+if (layoutBar(100, undefined, now)) fail("missing run rendered");
+
+// ---------- reference 3, the flat list ----------
+
+const flat = run({
+	phases: ["map"], // one phase: no workflow to collapse, so this is the list case
+	done: 0,
+	total: 2,
+	branches: [
+		branch(),
+		branch({
+			name: "Explore",
+			stem: "map-explore",
+			label: "map:Explore",
+			depth: 1,
+			parent: "map-general-purpose",
+			index: 2,
+			activity: "Confirming store.ts is unused",
+			tokens: 86_300,
+			elapsedMs: 172_000, // 2m 52s
+			// Hollow in the reference while its sibling is filled, and a branch that has not
+			// emitted for a quarter of a minute is the one state that can honestly produce that.
+			// The screen cannot tell us which of the two it was; the rule has to mean something,
+			// so it means the thing the panel already tracks.
+			idleMs: 20_000,
+		}),
+	],
+});
+
+for (let width = 8; width <= 200; width++) {
+	for (const state of [flat, undefined, settled]) {
+		const rows = layoutList(width, state, now, MAX_ROWS);
+		if (rows.length === 0) fail(`list width ${width}: zero rows un-mounts the widget`);
+		for (const row of rows) {
+			const used =
+				visibleWidth(row.head) + visibleWidth(row.activity) + row.fill.length + visibleWidth(row.right);
+			if (used !== width - 2) fail(`list width ${width}: row composed ${used}, expected ${width - 2}`);
+		}
+		// The activity column has to start in the same place on every row, or the sentences
+		// stagger and the list stops being readable at a glance.
+		const heads = new Set(rows.map((row) => visibleWidth(row.head)));
+		if (heads.size !== 1) fail(`list width ${width}: ragged head column ${[...heads].join()}`);
+	}
+}
+
+const list = layoutList(100, flat, now, MAX_ROWS);
+if (list.length !== 3) fail(`expected main + two agents, got ${list.length}`);
+// SAFETY: length checked immediately above.
+const [main, first, nested] = list as [(typeof list)[0], (typeof list)[0], (typeof list)[0]];
+if (main.head.trimEnd() !== "○ main") fail(`main row: ${JSON.stringify(main.head)}`);
+if (main.branch !== undefined) fail("the main row is not a branch");
+if (main.activity !== "" || main.right.trim() !== "") fail("the main row carries counters the reference does not show");
+if (first.head.trimEnd() !== "● general-purpose") fail(`agent row: ${JSON.stringify(first.head)}`);
+if (first.dotAt !== 0) fail(`dot column on a top-level row: ${first.dotAt}`);
+if (!first.activity.endsWith("Grepping localStorage keys in office-persist.ts")) fail(`activity: ${first.activity}`);
+if (first.right !== "3m 52s · ↓ 56.5k tokens") fail(`right column: ${JSON.stringify(first.right)}`);
+if (nested.head.trimEnd() !== "└ ○ Explore") fail(`nested row: ${JSON.stringify(nested.head)}`);
+if (nested.dotAt !== 2) fail(`dot column on a nested row: ${nested.dotAt}`);
+if (nested.right !== "2m 52s · ↓ 86.3k tokens") fail(`nested right column: ${JSON.stringify(nested.right)}`);
+
+// An idle session is one bare row, which is also the height a phased run collapses to — so the
+// widget never changes height just by changing its mind about which screen it is drawing.
+const idle = layoutList(100, undefined, now, MAX_ROWS);
+if (idle.length !== 1 || idle[0]?.head.trimEnd() !== "○ main") fail("idle is not exactly one `○ main` row");
+if (layoutList(100, settled, now + 31_000, MAX_ROWS).length !== 1) fail("finished run outstayed LINGER_MS in the list");
+
+// A quiet branch goes hollow, a working one is filled, and the row budget is a ceiling rather
+// than a suggestion.
+const quiet = layoutList(100, run({ phases: ["map"], branches: [branch({ idleMs: 60_000 })] }), now, MAX_ROWS);
+if (!quiet[1]?.head.startsWith("○")) fail(`an idle branch kept its filled dot: ${quiet[1]?.head}`);
+
+const many = run({ phases: ["map"], branches: Array.from({ length: 40 }, (_, i) => branch({ stem: `map-b${i}` })) });
+const capped = layoutList(100, many, now, MAX_ROWS);
+if (capped.length !== MAX_ROWS) fail(`row budget ignored: ${capped.length}`);
+if (!capped[MAX_ROWS - 1]?.head.startsWith("+33 more")) fail(`no overflow row: ${capped[MAX_ROWS - 1]?.head}`);
+if (capped[MAX_ROWS - 1]?.dotAt !== -1) fail("the overflow row was given a status dot");
+// A budget of one is `○ main` and nothing else, not `○ main` plus an apology.
+if (layoutList(100, many, now, 1).length !== 1) fail("a one-row budget grew a second row");
+if (layoutList(100, many, now, 2).length !== 2) fail("a two-row budget is main plus the overflow");
+
+// ---------- the fixed-height rule ----------
+
+const paint = (_color: unknown, text: string) => text; // identity: measure the plain frame
+for (let width = 0; width <= 200; width++) {
+	const collapsed = renderLines(width, phased, now, MAX_ROWS, paint);
+	if (collapsed.length !== 1) fail(`collapsed rendered ${collapsed.length} lines at width ${width}`);
+	if (visibleWidth(collapsed[0] ?? "") !== Math.max(0, width)) fail(`collapsed overflowed at width ${width}`);
+
+	// Every other path through renderLines, at the same widths.
+	for (const [label, lines] of [
+		["panel open", renderLines(width, phased, now, MAX_ROWS, paint, true)],
+		["idle", renderLines(width, undefined, now, MAX_ROWS, paint)],
+		["list", renderLines(width, flat, now, MAX_ROWS, paint)],
+		["faded", renderLines(width, settled, now + 31_000, MAX_ROWS, paint)],
+	] as [string, string[]][]) {
+		// idle and faded now draw NOTHING, at every width, and that is the assertion - not a
+		// blank line. The slot is belowEditor, where pi passes spacerWhenEmpty and leadingSpacer
+		// both false, so zero lines is zero rows and the footer above never moves. The check
+		// runs width 0..200 because the faded test sits ahead of the narrow-terminal guard;
+		// putting it after would have made a 5-column terminal the one place a bare row survived.
+		if (label === "idle" || label === "faded") {
+			if (lines.length !== 0) fail(`${label} drew ${lines.length} lines at width ${width}, expected none`);
+		} else if (lines.length < 1) {
+			fail(`${label} rendered nothing at width ${width}`);
+		}
+		for (const line of lines) {
+			if (visibleWidth(line) !== Math.max(0, width)) fail(`${label} overflowed at width ${width}: ${line.length}`);
+		}
+	}
+}
+if (renderLines(80, phased, now, MAX_ROWS, paint, true)[0]?.trim() !== "") fail("the open panel did not blank the widget");
+
+// ---------- the no-op frame ----------
+
+if (renderKey(flat, now) !== renderKey(flat, now)) fail("render key is not stable");
+if (renderKey(undefined, now) !== "-") fail("an empty screen is not one key");
+if (renderKey(settled, now + 31_000) !== "-") fail("a faded run is not the empty screen");
+if (renderKey(flat, now) === renderKey(flat, now + 1_000)) fail("the clock moved and the key did not");
+const rewritten = run({ ...flat, branches: [branch({ activity: "Reading hooks.server.ts and app.d.ts" }), ...flat.branches.slice(1)] });
+if (renderKey(flat, now) === renderKey(rewritten, now)) fail("the activity sentence changed and the key did not");
+
+console.log("ok");

package/extensions/umbra-subagents/bar.ts

@@ -0,0 +1,173 @@
+import { CustomEditor, type ExtensionAPI, type ExtensionContext, type KeybindingsManager, type Theme } from "@earendil-works/pi-coding-agent";
+import { Editor, type Component, type EditorTheme, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { faded, MAX_ROWS, renderKey, renderLines } from "./bar/bar-line.ts";
+import type { RunState } from "./skills/delegate/state.ts";
+
+// Part 3: everything the widget slot below the input box draws, and the ways it opens into the
+// full panel of reference 1.
+//
+// Two shapes, one widget. Reference 3 — the flat live list, `○ main` on top, one row per agent,
+// `└` for a nested one — is the default, and is what an idle session shows as a single bare
+// `○ main`. Reference 2 — one line: run name, truncated description, right-aligned counters —
+// replaces it while a phased run is going, because that run has a panel worth zooming into and
+// a per-agent list would only be that panel drawn badly.
+//
+// The widget is mounted once at session_start and never removed. It asks for belowEditor, and
+// repatch.mjs moves that slot below pi's status line. The slot grows a Spacer(1) the moment it holds anything, so registering and
+// unregistering it moves the input box by a row;
+// and setWidget disposes and rebuilds its component on every call, so calling it per tick would
+// be a per-tick rebuild. Register the factory once, then requestRender().
+//
+// The string[] form of setWidget is unusable here twice over: it is wrapped in a Text that
+// word-wraps a long line into two rows and yields nothing at all for a blank one, and it is
+// capped at 10 lines. Only the factory form is handed `width`, which is what makes every
+// truncation in bar/bar-line.ts possible.
+//
+// Every column of the frame itself is in bar/bar-line.ts, down to and including the string
+// concatenation, because bar.check.ts cannot import this file: `CustomEditor` is a value from
+// pi's own package, and loading that package pulls in an experimental server module that is not
+// installed. What is left here is the part a check could not have run anyway — a component, an
+// editor subclass, and four registrations.
+
+const BAR_KEY = "agent-bar";
+// Rows the list leaves to the editor, the status line and pi's own footer on a short terminal.
+const RESERVE = 6;
+
+class BarComponent implements Component {
+	constructor(
+		private tui: TUI,
+		private theme: Theme,
+		private onOpen: () => void,
+	) {}
+
+	render(width: number): string[] {
+		// terminal.rows only changes on a resize, which repaints everything anyway, so reading
+		// it per frame costs nothing and keeps the list inside a shrunk window.
+		const budget = Math.max(1, Math.min(MAX_ROWS, this.tui.terminal.rows - RESERVE));
+		return renderLines(width, current, Date.now(), budget, (color, text) => this.theme.fg(color, text), panelOpen);
+	}
+
+	// Mouse reporting is only on in the alternate-screen TUI (tuiMode "fullscreen"). Clicks are
+	// routed by position, not focus, so a click while another dialog holds the editor slot
+	// (ask_user_question, a select) would swap that dialog out and leave its promise hanging:
+	// the bar only opens the panel while an editor has focus.
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (event.type !== "click" || panelOpen || !current) return undefined;
+		if (!(this.tui.getFocusedComponent() instanceof Editor)) return undefined;
+		this.onOpen();
+		return { handled: true };
+	}
+
+	invalidate(): void {
+		// Nothing is cached between frames: render() reads the snapshot fresh every time.
+	}
+
+	refresh(): void {
+		// Never requestRender(true). That calls resetRenderState(), which forces a repaint of
+		// the whole screen instead of the changed band — which is the flicker.
+		this.tui.requestRender();
+	}
+}
+
+// Down is not ours to steal outright: it moves the cursor, walks prompt history and drives the
+// autocomplete list. It belongs to the bar only when the editor would do nothing with it —
+// cursor already parked at the end of the last visual line — so the editor is asked rather than
+// second-guessed. Its wrap map is private and re-deriving it would drift the first time pi
+// changes its wrapping; a no-op cannot drift. registerShortcut("down") is not an option: the
+// dispatcher consumes a matched key session-wide, history and autocomplete included.
+class BarEditor extends CustomEditor {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		private keys: KeybindingsManager,
+		private onDownAtEnd: () => void,
+	) {
+		super(tui, theme, keys);
+	}
+
+	handleInput(data: string): void {
+		// With the autocomplete list open, down moves the highlight and changes neither the text
+		// nor the cursor, so the probe below would misread it as a no-op.
+		if (!this.keys.matches(data, "tui.editor.cursorDown") || this.isShowingAutocomplete()) {
+			super.handleInput(data);
+			return;
+		}
+		const text = this.getText();
+		const before = this.getCursor();
+		super.handleInput(data);
+		const after = this.getCursor();
+		if (this.getText() === text && after.line === before.line && after.col === before.col) this.onDownAtEnd();
+	}
+}
+
+let current: RunState | undefined;
+let panelOpen = false;
+let bar: BarComponent | undefined;
+let lastKey = "";
+
+/** The bar holds no state and owns no timer: the reader that already polls `<cwd>/.pi-out` for
+ *  the panel calls this every tick, so the two views can never disagree about the same run and
+ *  only one thing is ever walking the disk. */
+export const setRun = (run: RunState | undefined) => {
+	current = run;
+	const key = renderKey(run, Date.now());
+	if (key === lastKey) return;
+	lastKey = key;
+	bar?.refresh();
+};
+
+export const installBar = (pi: ExtensionAPI, openPanel: (ctx: ExtensionContext) => Promise<void> | void) => {
+	// `quiet` is the down arrow and the click: both fire whether or not a run exists, and a
+	// notification on every press of a key the user meant as "move the cursor" is noise. The
+	// command and the shortcut were typed on purpose, so those get told why nothing happened.
+	const open = (ctx: ExtensionContext, quiet = false) => {
+		if (panelOpen) return quiet ? undefined : ctx.ui.notify("agent panel is already open");
+		// Opening on nothing would draw an empty box the user cannot fill. The quiet doors also
+		// skip a run the bar has already let go of: a key meant as "move the cursor" should not
+		// bring back a run that finished minutes ago. The command and alt+a still open it.
+		if (!current || (quiet && faded(current, Date.now()))) {
+			return quiet ? undefined : ctx.ui.notify("no agent run in this directory");
+		}
+		panelOpen = true;
+		bar?.refresh();
+		void Promise.resolve(openPanel(ctx)).finally(() => {
+			panelOpen = false;
+			bar?.refresh();
+		});
+	};
+
+	// umbra-inputbar's editor announces a down at the end on pi's event bus. pi keeps one editor
+	// per session and does not sort extensions before loading them (under bun the order is the
+	// filesystem's), so a second editor class of our own would win or lose at random. The event
+	// works whichever loads first; the subscription is dropped by pi on /reload.
+	let lastCtx: ExtensionContext | undefined;
+	pi.events.on("editor:down-at-end", () => {
+		if (lastCtx) open(lastCtx, true);
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		lastCtx = ctx;
+		// Re-registered on every session_start, including the "reload" one that follows
+		// resetExtensionUI() clearing every widget and the custom editor. Once per session is
+		// not once per tick: each call disposes the old component and builds a new one.
+		ctx.ui.setWidget(
+			BAR_KEY,
+			(tui, theme) => {
+				bar = new BarComponent(tui, theme, () => open(ctx, true));
+				return bar;
+			},
+			{ placement: "belowEditor" },
+		);
+		// Fallback for a setup without umbra-inputbar: then this editor does the same probe
+		// itself. With umbra-inputbar present its editor is kept, and the event above is the way
+		// in. Only one editor is ever live, so the panel cannot be asked to open twice.
+		if (ctx.ui.getEditorComponent()) return;
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => new BarEditor(tui, theme, keybindings, () => open(ctx, true)));
+	});
+
+	// Not ctrl+<letter>: every one is already bound by pi, and extension shortcuts are matched
+	// before app keybindings, so one would silently shadow a built-in.
+	pi.registerShortcut("alt+a", { description: "Open the agent panel", handler: (ctx) => open(ctx) });
+	pi.registerCommand("umb-agents", { description: "Open the agent panel", handler: async (_args, ctx) => open(ctx) });
+};

package/extensions/umbra-subagents/fan/index.ts

@@ -0,0 +1,110 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { installBar, setRun } from "../bar.ts";
+import { openPanel, type PanelSource } from "../panel.ts";
+import { findBlock, parseSpec, TEMPLATE } from "./spec.ts";
+import { reportOf, store } from "./store.ts";
+import type { RunState } from "../skills/delegate/state.ts";
+
+// Wiring only. store.ts owns the branches, bar.ts and panel.ts render them.
+//
+// Three ways in, all free: `/umb-fan` for the user, a fenced ```fan block in the model's own
+// answer, and a bash call that turns out to be the delegate skill — the same run directory
+// either way, so the panel does not care which one started it. No pi.registerTool anywhere,
+// so the prompt is byte-for-byte unchanged.
+
+const RUN_SH = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", "delegate", "run.sh");
+
+// A branch that stopped on a question goes to the model first: most questions are answered by
+// the conversation the branch never saw, and only the rest reach the user.
+const askingNote = (run: RunState): string => {
+	const asking = run.branches.filter((branch) => branch.report === "ASKING");
+	if (!asking.length) return "";
+	return (
+		`\n\n${asking.map((branch) => branch.stem).join(", ")} stopped on a question. Answer it from this ` +
+		"conversation if you can; if only the user can decide, ask them with ask_user_question first. " +
+		"Then continue each one in a single bash call and read its new report:\n\n" +
+		`. '${RUN_SH}'; ${asking.map((branch) => `dresume '${run.dir}' ${branch.stem} '<answer>'`).join("; ")}; wait; ` +
+		asking.map((branch) => `cat '${run.dir}/${branch.stem}.md'`).join("; ")
+	);
+};
+
+const modelOf = (ctx: ExtensionContext) =>
+	process.env.FAN_MODEL || (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "");
+
+// The one adapter between the producer and the two renderers. store keys a branch by its
+// stem because that is its filename; the panel hands back the whole BranchView it drew,
+// because a row it did not draw must not be stoppable. Converting here keeps both sides
+// honest instead of widening either signature to meet the other.
+const source: PanelSource = {
+	run: () => store.run(),
+	stop: (branch) => void store.stop(branch.stem),
+	subscribe: (fn) => store.subscribe(fn),
+};
+
+export default function (pi: ExtensionAPI) {
+	// The widget above the editor, the alt+a shortcut, the /umb-agents command and the down arrow
+	// out of the last editor line. All four open the same panel over the same source.
+	installBar(pi, (ctx) => openPanel(ctx, source));
+	// The bar is pushed to rather than polling a second time: store already ticks once a
+	// second while branches are live, and a second reader could only disagree with it.
+	store.subscribe(() => setRun(store.run()));
+
+	// The run directory this session started, and has therefore promised to report back on.
+	// A run the delegate skill started in bash is left alone: that caller reads $run/*.md
+	// itself, and a follow-up would hand the model the same text twice.
+	let awaiting: string | undefined;
+
+	// Branches must not outlive the pi that started them: nothing would be watching, and a
+	// branch left running keeps spending. Their reports are already on disk.
+	pi.on("session_shutdown", () => store.stopAll());
+
+	// A bash call may be the delegate skill mid-run. Arming the tick when one starts is what
+	// makes a skill-started run appear on the bar from its first frame rather than at the end;
+	// the turn's end disarms it, because no bash call outlives its turn.
+	pi.on("tool_execution_start", (event, ctx) => {
+		if (event.toolName === "bash") store.arm(ctx.cwd);
+	});
+	pi.on("agent_end", () => store.disarm());
+	pi.on("session_start", (_event, ctx) => store.watch(ctx.cwd));
+
+	pi.on("message_end", (event, ctx) => {
+		if (ctx.mode !== "tui" || event.message.role !== "assistant") return;
+		const text = event.message.content
+			.filter((part) => part.type === "text")
+			.map((part) => part.text)
+			.join("\n");
+		const block = findBlock(text);
+		if (!block) return;
+		const spec = parseSpec(block);
+		// The whole assistant message, not just the fenced block: the reasoning around the
+		// block is the half a branch cannot reconstruct from its own task line.
+		if (spec) awaiting = store.start(spec, modelOf(ctx), ctx.cwd, text) ?? awaiting;
+	});
+
+	// The branches' answers come back as a follow-up rather than as a tool result: the turn
+	// that asked for them already ended, so the model reads them at the top of the next one.
+	store.subscribe(() => {
+		const run = store.run();
+		if (!run || run.dir !== awaiting || run.live) return;
+		awaiting = undefined;
+		pi.sendUserMessage(`Branch results for ${run.name}:\n\n${reportOf(run)}${askingNote(run)}`, { deliverAs: "followUp" });
+	});
+
+	pi.registerCommand("umb-fan", {
+		description: "Run parallel pi branches and watch them in the agent panel",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const text = args.trim() || (await ctx.ui.editor("fan", TEMPLATE));
+			if (!text) return;
+			const spec = parseSpec(text);
+			if (!spec) return ctx.ui.notify("fan: no branches in that spec", "warning");
+			// Started by the user, so the results are theirs to read on the panel; the model is
+			// only told about a run it asked for itself. One run at a time, and swallowing the
+			// refusal made /umb-fan look like it had worked.
+			if (!store.start(spec, modelOf(ctx), ctx.cwd, text)) {
+				ctx.ui.notify("fan: a run is already in flight — stop it from the panel first", "warning");
+			}
+		},
+	});
+}

package/extensions/umbra-subagents/fan/spec.ts

@@ -0,0 +1,81 @@
+import type { RunSpec } from "./store.ts";
+
+// The one text format a run is described in. `/umb-fan` opens it in an editor, and the fan
+// skill tells the model to emit the same thing in a ```fan block, so there is one parser
+// and no schema for the model to get wrong.
+//
+//   name: pi-toolcall-render
+//   desc: Map how pi renders tool calls
+//   # Map
+//   core-render: Read the render path and report where a tool call becomes lines.
+//   omp-intercept@openai/gpt-5: Check whether an extension can override it.
+//   # Design
+//   proposal: Given the Map phase, write the design.
+//
+// Phases run in order; every branch inside one phase runs at the same time.
+
+export const TEMPLATE = ["name: ", "desc: ", "# Phase one", "label: task", ""].join("\n");
+
+export const parseSpec = (text: string): RunSpec | undefined => {
+	const spec: RunSpec = { name: "", description: "", phases: [] };
+	for (const raw of text.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("//")) continue;
+		if (line.startsWith("#")) {
+			spec.phases.push({ title: line.replace(/^#+\s*/, "") || `Phase ${spec.phases.length + 1}`, branches: [] });
+			continue;
+		}
+		// Split on the first colon only: a task line is full of colons (file:line, URLs).
+		const colon = line.indexOf(":");
+		if (colon === -1) continue;
+		const key = line.slice(0, colon).trim();
+		const value = line.slice(colon + 1).trim();
+		if (!value) continue;
+		if (key === "name") spec.name = value;
+		else if (key === "desc") spec.description = value;
+		else {
+			// A branch before any "#" gets an implicit first phase, so the common
+			// single-phase run needs no header at all.
+			const phase = spec.phases[spec.phases.length - 1] ?? pushPhase(spec, "Branches");
+			const [label, model] = key.split("@");
+			if (label) phase.branches.push({ label, model, task: value });
+		}
+	}
+	spec.phases = spec.phases.filter((phase) => phase.branches.length > 0);
+	if (!spec.phases.length) return undefined;
+	if (!spec.name) spec.name = spec.phases[0]?.branches[0]?.label ?? "run";
+	return spec;
+};
+
+const pushPhase = (spec: RunSpec, title: string) => {
+	const phase = { title, branches: [] as { label: string; model?: string; task: string }[] };
+	spec.phases.push(phase);
+	return phase;
+};
+
+/** The fenced block the fan skill tells the model to write. */
+export const findBlock = (text: string) => /```fan\s*\n([\s\S]*?)```/.exec(text)?.[1];
+
+// One check for the two things that are easy to get wrong: a colon inside a task, and a
+// branch written before any phase header.
+const demo = () => {
+	const spec = parseSpec(`
+name: toolcall
+desc: Map how pi renders tool calls
+lone: Read tui.d.ts:68 and report.
+# Design
+plan@openai/gpt-5: Write it up.
+`);
+	if (!spec) throw new Error("parseSpec returned undefined for a valid spec");
+	console.assert(spec.name === "toolcall", "name");
+	console.assert(spec.description === "Map how pi renders tool calls", "desc");
+	console.assert(spec.phases.length === 2, `expected 2 phases, got ${spec.phases.length}`);
+	console.assert(spec.phases[0]?.title === "Branches", "implicit first phase");
+	console.assert(spec.phases[0]?.branches[0]?.task === "Read tui.d.ts:68 and report.", "colon in task");
+	console.assert(spec.phases[1]?.branches[0]?.model === "openai/gpt-5", "per-branch model");
+	console.assert(parseSpec("name: empty") === undefined, "a spec with no branches is not a run");
+	console.assert(findBlock("blah\n```fan\nx: y\n```\nblah") === "x: y\n", "block extraction");
+	console.log("spec.ts ok");
+};
+
+if (process.argv[1]?.endsWith("spec.ts")) demo();