@xynogen/pix-commands 0.2.5 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-commands",
-	"version": "0.2.5",
+	"version": "0.3.5",
 	"description": "Pi extension — slash commands for cache clearing and isolated side questions",
 	"type": "module",
 	"main": "src/index.ts",
@@ -45,6 +45,7 @@
 		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
-		"@xynogen/pix-runtime": "^0.4.0"
+		"@xynogen/pix-pretty": "^1.11.2",
+		"@xynogen/pix-runtime": "^0.5.3"
 	}
 }

package/src/btw/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { filterBtwMessages, registerBtw, shortModelName, summarizeLiveText } from "./index.ts";
+import { registerBtw, shortModelName } from "./index.ts";
 
 describe("BTW display helpers", () => {
 	test("prefers model display name and falls back to id", () => {
@@ -7,48 +7,40 @@ describe("BTW display helpers", () => {
 		expect(shortModelName({ id: "id", name: "  " })).toBe("id");
 	});
 
-	test("summarizes streaming output on one bounded line", () => {
-		expect(summarizeLiveText("hello\n\nworld", 20)).toBe("hello world");
-		expect(summarizeLiveText("abcdefghij", 6)).toBe("abcde…");
-		expect(summarizeLiveText("   ")).toBe("thinking…");
-	});
+	test("registers a display-only entry renderer, never a context-bearing message renderer", () => {
+		let entryRenderer: string | undefined;
+		let messageRenderer: string | undefined;
+		const pi = {
+			on() {},
+			registerCommand() {},
+			registerEntryRenderer(name: string) {
+				entryRenderer = name;
+			},
+			registerMessageRenderer(name: string) {
+				messageRenderer = name;
+			},
+		} as any;
+		registerBtw(pi);
 
-	test("filters BTW cards from LLM context without affecting the transcript", () => {
-		const messages = [
-			{ role: "user", content: "main question" },
-			{ role: "custom", customType: "pix-btw-answer", content: "aside" },
-			{ role: "custom", customType: "other", content: "keep" },
-		];
-		expect(filterBtwMessages(messages)).toEqual([
-			{ role: "user", content: "main question" },
-			{ role: "custom", customType: "other", content: "keep" },
-		]);
-		expect(messages).toHaveLength(3);
+		// pix-btw-answer must be a CustomEntry (display-only, never in LLM context),
+		// not a CustomMessageEntry — that is what lets the card land mid-stream.
+		expect(entryRenderer).toBe("pix-btw-answer");
+		expect(messageRenderer).toBeUndefined();
 	});
 
-	test("does not defer an empty card flush after agent_end", async () => {
-		const handlers = new Map<string, (...args: any[]) => unknown>();
+	test("does not register a context handler (BTW cards never enter LLM context)", () => {
+		const events: string[] = [];
 		const pi = {
-			on(event: string, handler: (...args: any[]) => unknown) {
-				handlers.set(event, handler);
+			on(event: string) {
+				events.push(event);
 			},
 			registerCommand() {},
-			registerMessageRenderer() {},
+			registerEntryRenderer() {},
 		} as any;
 		registerBtw(pi);
 
-		let idleChecks = 0;
-		handlers.get("agent_end")?.(
-			{},
-			{
-				isIdle() {
-					idleChecks++;
-					throw new Error("stale extension context");
-				},
-			},
-		);
-		await Bun.sleep(10);
-
-		expect(idleChecks).toBe(0);
+		// A CustomEntry is ignored by buildSessionContext, so there is nothing to
+		// strip — the old pi.on("context", filterBtwMessages) hack is gone.
+		expect(events).not.toContain("context");
 	});
 });

package/src/btw/index.ts

@@ -5,8 +5,10 @@ import type {
 	Theme,
 } from "@earendil-works/pi-coding-agent";
 import { Text, type TUI } from "@earendil-works/pi-tui";
+import { getSessionContextUsage } from "@xynogen/pix-pretty/widget-format";
 import { type BtwMessageDetails, registerBtwRenderer } from "./render.ts";
 import { runBtw, snapshotMainSettings } from "./session.ts";
+import { type BtwWidgetJob, hasVisibleJobs, renderBtwWidget } from "./widget.ts";
 
 const STATUS_KEY = "pix-btw";
 const WIDGET_KEY = "pix-btw-live";
@@ -16,30 +18,39 @@ interface BtwJob {
 	question: string;
 	model: string;
 	startedAt: number;
+	completedAt?: number;
 	status: "running" | "completed" | "error" | "stopped";
 	text: string;
 	activeTools: Set<string>;
 	toolUses: number;
+	turnCount: number;
+	outputTokens: number;
+	/** Final context usage, captured before the session is disposed on publish. */
+	contextUsage: import("@xynogen/pix-pretty/widget-format").ContextUsageLike | null;
 	session?: AgentSession;
 	error?: string;
 }
 
-export function shortModelName(model: { name?: string; id: string }): string {
-	return model.name?.trim() || model.id;
-}
-
-export function summarizeLiveText(text: string, max = 100): string {
-	const first = text.replace(/\s+/g, " ").trim();
-	if (!first) return "thinking…";
-	return first.length > max ? `${first.slice(0, Math.max(1, max - 1))}…` : first;
+/** Project a live job into the widget's render shape. */
+function toWidgetJob(job: BtwJob): BtwWidgetJob {
+	return {
+		id: job.id,
+		model: job.model,
+		status: job.status,
+		startedAt: job.startedAt,
+		completedAt: job.completedAt,
+		activeTools: [...job.activeTools],
+		text: job.text,
+		toolUses: job.toolUses,
+		turnCount: job.turnCount,
+		outputTokens: job.outputTokens,
+		contextUsage: getSessionContextUsage(job.session) ?? job.contextUsage,
+		error: job.error,
+	};
 }
 
-/** Keep rendered BTW cards out of every agent's LLM conversation context. */
-export function filterBtwMessages<T>(messages: T[]): T[] {
-	return messages.filter((message) => {
-		const candidate = message as { role?: string; customType?: string };
-		return !(candidate.role === "custom" && candidate.customType === "pix-btw-answer");
-	});
+export function shortModelName(model: { name?: string; id: string }): string {
+	return model.name?.trim() || model.id;
 }
 
 export function registerBtw(pi: ExtensionAPI): void {
@@ -48,113 +59,68 @@ export function registerBtw(pi: ExtensionAPI): void {
 	const jobs = new Map<number, BtwJob>();
 	let nextId = 1;
 	let latestUi: ExtensionCommandContext["ui"] | undefined;
-	let latestContext: Pick<ExtensionCommandContext, "isIdle"> | undefined;
 	let active = true;
 	let refreshTimer: ReturnType<typeof setInterval> | undefined;
-	let publishTimer: ReturnType<typeof setTimeout> | undefined;
-	const pendingCards: BtwMessageDetails[] = [];
 
-	const renderJobs = (theme: Theme): string[] => {
-		const running = [...jobs.values()].filter((job) => job.status === "running");
-		if (running.length === 0) return [];
-		const lines = [theme.fg("accent", `○ BTW (${running.length})`)];
-		for (const job of running.slice(-4)) {
-			const elapsed = ((Date.now() - job.startedAt) / 1_000).toFixed(1);
-			const activity =
-				job.activeTools.size > 0
-					? [...job.activeTools].map((name) => `using ${name}`).join(", ")
-					: summarizeLiveText(job.text);
-			lines.push(theme.fg("dim", `└─ #${job.id} [${job.model}] · ${elapsed}s · ${activity}`));
-		}
-		return lines;
-	};
+	let frame = 0;
 
 	const updateUi = () => {
 		if (!active || !latestUi) return;
-		const running = [...jobs.values()].filter((job) => job.status === "running");
-		if (running.length === 0) {
+		const now = Date.now();
+		const allJobs = [...jobs.values()];
+		if (!hasVisibleJobs(allJobs.map(toWidgetJob), now)) {
 			latestUi.setStatus(STATUS_KEY, undefined);
 			latestUi.setWidget(WIDGET_KEY, undefined);
 			if (refreshTimer) clearInterval(refreshTimer);
 			refreshTimer = undefined;
 			return;
 		}
-		latestUi.setStatus(STATUS_KEY, `BTW ${running.length}`);
+		const runningCount = allJobs.filter((job) => job.status === "running").length;
+		latestUi.setStatus(STATUS_KEY, runningCount > 0 ? `BTW ${runningCount}` : undefined);
 		latestUi.setWidget(
 			WIDGET_KEY,
 			(tui: TUI, theme: Theme) => {
 				const text = new Text("", 0, 0);
 				return {
 					render: (width: number) => {
-						text.setText(renderJobs(theme).join("\n"));
-						return text.render(width || tui.terminal.columns);
+						const w = width || tui.terminal.columns;
+						const widgetJobs = [...jobs.values()].map(toWidgetJob);
+						text.setText(renderBtwWidget(widgetJobs, theme, frame, Date.now(), w).join("\n"));
+						return text.render(w);
 					},
 					invalidate: () => text.invalidate(),
 				};
 			},
 			{ placement: "aboveEditor" },
 		);
-		refreshTimer ??= setInterval(updateUi, 100);
-	};
-
-	const flushPendingCards = () => {
-		// Child BTW sessions load this extension too, so their agent_end event can
-		// reach here with no cards. Do not touch a context that may be invalidated
-		// immediately afterward when the completed child session is disposed.
-		if (!active || pendingCards.length === 0 || !latestContext?.isIdle()) return;
-		for (const details of pendingCards.splice(0)) {
-			pi.sendMessage<BtwMessageDetails>({
-				customType: "pix-btw-answer",
-				content: details.error
-					? `BTW question failed: ${details.error}`
-					: `BTW answer to “${details.question}”:\n\n${details.answer}`,
-				display: true,
-				details,
-			});
-		}
-	};
-
-	const scheduleCardFlush = () => {
-		if (!active || pendingCards.length === 0 || publishTimer) return;
-		// agent_end handlers run before Pi clears its streaming flag. Flush on the
-		// next macrotask, when sendMessage appends and renders synchronously instead
-		// of entering a queue that only becomes visible on another user turn.
-		publishTimer = setTimeout(() => {
-			publishTimer = undefined;
-			flushPendingCards();
-		}, 0);
+		// 80ms cadence advances the spinner and refreshes elapsed/linger. When only
+		// finished jobs remain, they drop once their linger window closes.
+		refreshTimer ??= setInterval(() => {
+			frame++;
+			updateUi();
+		}, 80);
 	};
 
-	const publish = (job: BtwJob, details: BtwMessageDetails, ctx: ExtensionCommandContext) => {
+	const publish = (job: BtwJob, details: BtwMessageDetails) => {
 		job.session?.dispose();
 		job.session = undefined;
 		// The side session may finish while the main extension runtime is being
-		// replaced. Never touch its captured pi/ctx/UI after shutdown begins.
+		// replaced. Never touch the captured pi/UI after shutdown begins.
 		if (!active) return;
 		updateUi();
-		pendingCards.push(details);
-
-		if (!ctx.isIdle()) {
-			ctx.ui.notify(
-				details.error
-					? `BTW #${job.id} failed: ${details.error}`
-					: `BTW #${job.id} complete\n\n${details.answer}`,
-				details.error ? "error" : "info",
-			);
-			return;
-		}
-
-		flushPendingCards();
+		// A display-only CustomEntry never enters the main agent's LLM context and
+		// never steers the running turn, so the card lands the instant the side
+		// question finishes — even while the main agent is still streaming. This is
+		// the whole point of /btw: an immediate aside, not a deferred bottom-of-log
+		// note that only appears once the main turn goes idle.
+		pi.appendEntry<BtwMessageDetails>("pix-btw-answer", details);
 	};
 
-	pi.on("context", (event) => ({ messages: filterBtwMessages(event.messages) }));
-
 	pi.registerCommand("btw", {
 		description: "Ask an isolated side question without interrupting the main agent",
 		handler: async (rawArgs, ctx) => {
 			const question = rawArgs.trim();
 			latestUi = ctx.ui;
-			latestContext = ctx;
 			if (!question) {
 				ctx.ui.notify("Usage: /btw <question>", "warning");
 				return;
@@ -178,6 +144,9 @@ export function registerBtw(pi: ExtensionAPI): void {
 				text: "",
 				activeTools: new Set(),
 				toolUses: 0,
+				turnCount: 0,
+				outputTokens: 0,
+				contextUsage: null,
 			};
 			jobs.set(id, job);
 			updateUi();
@@ -200,54 +169,51 @@ export function registerBtw(pi: ExtensionAPI): void {
 					job.activeTools.delete(name);
 					job.toolUses++;
 				},
+				onTurnEnd: (turnCount) => {
+					job.turnCount = turnCount;
+				},
+				onOutputTokens: (output) => {
+					job.outputTokens += output;
+					job.contextUsage = getSessionContextUsage(job.session) ?? job.contextUsage;
+				},
 			})
-				.then(({ text, session }) => {
+				.then(({ text, thinking, session }) => {
 					job.status = "completed";
+					job.completedAt = Date.now();
 					job.text = text;
 					job.session = session;
-					publish(
-						job,
-						{
-							question,
-							answer: text || "No answer returned.",
-							model: job.model,
-							thinkingLevel: snapshot.thinkingLevel,
-							durationMs: Date.now() - job.startedAt,
-							toolUses: job.toolUses,
-						},
-						ctx,
-					);
+					job.contextUsage = getSessionContextUsage(session) ?? job.contextUsage;
+					publish(job, {
+						question,
+						answer: text || "No answer returned.",
+						thinking,
+						model: job.model,
+						thinkingLevel: snapshot.thinkingLevel,
+						durationMs: Date.now() - job.startedAt,
+						toolUses: job.toolUses,
+					});
 				})
 				.catch((error) => {
 					job.status = "error";
+					job.completedAt = Date.now();
 					job.error = error instanceof Error ? error.message : String(error);
-					publish(
-						job,
-						{
-							question,
-							answer: "",
-							model: job.model,
-							thinkingLevel: snapshot.thinkingLevel,
-							durationMs: Date.now() - job.startedAt,
-							toolUses: job.toolUses,
-							error: job.error,
-						},
-						ctx,
-					);
+					publish(job, {
+						question,
+						answer: "",
+						thinking: "",
+						model: job.model,
+						thinkingLevel: snapshot.thinkingLevel,
+						durationMs: Date.now() - job.startedAt,
+						toolUses: job.toolUses,
+						error: job.error,
+					});
 				});
 		},
 	});
 
-	pi.on("agent_end", (_event, ctx) => {
-		if (!active) return;
-		latestContext = ctx;
-		scheduleCardFlush();
-	});
-
 	pi.on("session_start", (_event, ctx) => {
 		if (!active) return;
 		latestUi = ctx.ui;
-		latestContext = ctx;
 		updateUi();
 	});
 
@@ -256,10 +222,7 @@ export function registerBtw(pi: ExtensionAPI): void {
 		// completions must become no-ops before Pi invalidates this runtime.
 		active = false;
 		if (refreshTimer) clearInterval(refreshTimer);
-		if (publishTimer) clearTimeout(publishTimer);
 		refreshTimer = undefined;
-		publishTimer = undefined;
-		latestContext = undefined;
 		latestUi?.setStatus(STATUS_KEY, undefined);
 		latestUi?.setWidget(WIDGET_KEY, undefined);
 		for (const job of jobs.values()) {
@@ -270,6 +233,5 @@ export function registerBtw(pi: ExtensionAPI): void {
 			job.session?.dispose();
 		}
 		jobs.clear();
-		pendingCards.length = 0;
 	});
 }

package/src/btw/render.test.ts

@@ -5,9 +5,9 @@ import { type BtwMessageDetails, formatDuration, registerBtwRenderer } from "./r
 const stripAnsi = (text: string) => text.replace(/\x1b\[[0-9;]*m/g, "");
 
 function captureRenderer() {
-	let renderer: ((message: unknown, options: unknown, theme: unknown) => unknown) | undefined;
+	let renderer: ((entry: unknown, options: unknown, theme: unknown) => unknown) | undefined;
 	const pi = {
-		registerMessageRenderer(_name: string, fn: typeof renderer) {
+		registerEntryRenderer(_name: string, fn: typeof renderer) {
 			renderer = fn;
 		},
 	} as unknown as ExtensionAPI;
@@ -26,9 +26,13 @@ const theme = {
 	bold: (text: string) => text,
 };
 
-function render(details: BtwMessageDetails): string {
+function render(details: BtwMessageDetails, expanded = false): string {
 	const renderer = captureRenderer();
-	const component = renderer({ details, content: details.answer }, { expanded: false }, theme) as {
+	const component = renderer(
+		{ type: "custom", customType: "pix-btw-answer", data: details },
+		{ expanded },
+		theme,
+	) as {
 		render(width: number): string[];
 	};
 	return stripAnsi(component.render(80).join("\n"));
@@ -46,6 +50,7 @@ describe("BTW renderer", () => {
 		const output = render({
 			question: "hello",
 			answer: "Hi!",
+			thinking: "",
 			model: "GPT-5.6",
 			thinkingLevel: "high",
 			durationMs: 2_100,
@@ -63,6 +68,7 @@ describe("BTW renderer", () => {
 		const output = render({
 			question: "show markdown",
 			answer: "## Heading\n\n- alpha\n- beta\n\n`code`",
+			thinking: "",
 			model: "Model",
 			thinkingLevel: "medium",
 			durationMs: 1_000,
@@ -73,4 +79,24 @@ describe("BTW renderer", () => {
 		expect(output).toContain("beta");
 		expect(output).toContain("code");
 	});
+
+	test("hides reasoning by default and reveals it when expanded", () => {
+		initTheme();
+		const details: BtwMessageDetails = {
+			question: "why",
+			answer: "Because.",
+			thinking: "first I considered the mutex",
+			model: "Model",
+			thinkingLevel: "high",
+			durationMs: 1_000,
+			toolUses: 0,
+		};
+		const collapsed = render(details, false);
+		expect(collapsed).toContain("reasoning hidden");
+		expect(collapsed).not.toContain("first I considered the mutex");
+
+		const expanded = render(details, true);
+		expect(expanded).toContain("Reasoning");
+		expect(expanded).toContain("first I considered the mutex");
+	});
 });

package/src/btw/render.ts

@@ -1,9 +1,12 @@
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
 
 export interface BtwMessageDetails {
 	question: string;
 	answer: string;
+	/** Captured reasoning/thinking from the child session (empty when none). */
+	thinking: string;
 	model: string;
 	thinkingLevel: string;
 	durationMs: number;
@@ -18,13 +21,18 @@ export function formatDuration(ms: number): string {
 }
 
 export function registerBtwRenderer(
-	pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerMessageRenderer">,
+	pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerEntryRenderer">,
 ): void {
-	pi.registerMessageRenderer<BtwMessageDetails>("pix-btw-answer", (message, _options, theme) => {
-		const details = message.details;
+	// A display-only CustomEntry (not a CustomMessageEntry): it never enters the
+	// main agent's LLM context and never steers the running turn, so the card can
+	// be appended the instant the side question finishes — even mid-stream.
+	pi.registerEntryRenderer<BtwMessageDetails>("pix-btw-answer", (entry, options, theme) => {
+		const details = entry.data;
 		if (!details) return undefined;
 		const failed = Boolean(details.error);
-		const icon = failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
+		const statusGlyph = failed
+			? theme.fg("error", icon("status.error"))
+			: theme.fg("success", icon("status.ok"));
 		const meta = [details.model, details.thinkingLevel, formatDuration(details.durationMs)];
 		if (details.toolUses > 0) meta.push(`${details.toolUses} tools`);
 
@@ -36,7 +44,11 @@ export function registerBtwRenderer(
 		// header text embedded inside Markdown can confuse wrapping and parsing.
 		const card = new Box(1, 1, (text) => theme.bg("selectedBg", text));
 		card.addChild(
-			new Text(`${icon} ${theme.bold("BTW")} ${theme.fg("dim", `· ${meta.join(" · ")}`)}`, 0, 0),
+			new Text(
+				`${statusGlyph} ${theme.bold("BTW")} ${theme.fg("dim", `· ${meta.join(" · ")}`)}`,
+				0,
+				0,
+			),
 		);
 		card.addChild(
 			new Text(`${theme.fg("accent", "▐")} ${theme.fg("muted", details.question)}`, 0, 0),
@@ -48,6 +60,19 @@ export function registerBtwRenderer(
 			return card;
 		}
 
+		// Reasoning is preserved but collapsed by default: shown only when the host
+		// requests the expanded view, never discarded (see AGENTS.md §3).
+		if (details.thinking) {
+			if (options.expanded) {
+				card.addChild(new Text(theme.fg("dim", theme.bold("Reasoning")), 0, 0));
+				card.addChild(new Text(theme.fg("thinkingText", details.thinking), 0, 0));
+				card.addChild(new Spacer(1));
+			} else {
+				card.addChild(new Text(theme.fg("dim", "› reasoning hidden — expand to view"), 0, 0));
+				card.addChild(new Spacer(1));
+			}
+		}
+
 		try {
 			card.addChild(
 				new Markdown(details.answer, 0, 0, getMarkdownTheme(), {

package/src/btw/session.ts

@@ -32,10 +32,16 @@ export interface BtwRunOptions {
 	onTextDelta?: (delta: string, fullText: string) => void;
 	onToolStart?: (toolName: string) => void;
 	onToolEnd?: (toolName: string) => void;
+	/** Called after each completed turn with the running turn count. */
+	onTurnEnd?: (turnCount: number) => void;
+	/** Called once per assistant message_end with that message's output tokens. */
+	onOutputTokens?: (outputTokens: number) => void;
 }
 
 export interface BtwRunResult {
 	text: string;
+	/** Reasoning/thinking captured from the child session (empty when none). */
+	thinking: string;
 	session: AgentSession;
 }
 
@@ -140,19 +146,38 @@ export async function runBtw(options: BtwRunOptions): Promise<BtwRunResult> {
 	options.onSession?.(session);
 
 	let text = "";
+	let thinking = "";
+	let turnCount = 0;
 	const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-		if (event.type === "message_start" && event.message.role === "assistant") text = "";
-		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-			text += event.assistantMessageEvent.delta;
-			options.onTextDelta?.(event.assistantMessageEvent.delta, text);
+		if (event.type === "message_start" && event.message.role === "assistant") {
+			text = "";
+			thinking = "";
+		}
+		if (event.type === "message_update") {
+			const ev = event.assistantMessageEvent;
+			if (ev.type === "text_delta") {
+				text += ev.delta;
+				options.onTextDelta?.(ev.delta, text);
+			} else if (ev.type === "thinking_delta") {
+				thinking += ev.delta;
+			}
 		}
 		if (event.type === "tool_execution_start") options.onToolStart?.(event.toolName);
 		if (event.type === "tool_execution_end") options.onToolEnd?.(event.toolName);
+		if (event.type === "turn_end") options.onTurnEnd?.(++turnCount);
+		if (event.type === "message_end" && event.message.role === "assistant") {
+			const output = event.message.usage?.output;
+			if (typeof output === "number" && output > 0) options.onOutputTokens?.(output);
+		}
 	});
 
 	try {
 		await session.prompt(question, { source: "extension" });
-		return { text: text.trim() || lastAssistantText(session.messages), session };
+		return {
+			text: text.trim() || lastAssistantText(session.messages),
+			thinking: thinking.trim(),
+			session,
+		};
 	} catch (error) {
 		session.dispose();
 		throw error;

package/src/btw/widget.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import {
+	type BtwWidgetJob,
+	hasVisibleJobs,
+	renderBtwWidget,
+	shouldShowFinished,
+	type WidgetTheme,
+} from "./widget.ts";
+
+const theme: WidgetTheme = {
+	fg: (_color, text) => text,
+	bold: (text) => text,
+};
+
+function job(overrides: Partial<BtwWidgetJob>): BtwWidgetJob {
+	return {
+		id: 1,
+		model: "Model",
+		status: "running",
+		startedAt: 0,
+		activeTools: [],
+		text: "",
+		toolUses: 0,
+		turnCount: 0,
+		outputTokens: 0,
+		contextUsage: null,
+		...overrides,
+	};
+}
+
+const render = (jobs: BtwWidgetJob[], now = 1_000) =>
+	renderBtwWidget(jobs, theme, 0, now, 200).join("\n");
+
+describe("BTW widget layout", () => {
+	test("empty when there are no running or lingering jobs", () => {
+		expect(renderBtwWidget([], theme, 0, 1_000, 200)).toEqual([]);
+		const old = job({ status: "completed", completedAt: 0 });
+		expect(renderBtwWidget([old], theme, 0, 999_999, 200)).toEqual([]);
+	});
+
+	test("running heading is hollow and shows the running count", () => {
+		const out = render([job({ id: 7, model: "GPT" })]);
+		expect(out).toContain("\u25cb BTW (1)");
+		expect(out).toContain("#7");
+		expect(out).toContain("[GPT]");
+	});
+
+	test("finished jobs linger with a check, then drop after the window", () => {
+		const done = job({ status: "completed", completedAt: 1_000, toolUses: 2, turnCount: 1 });
+		expect(shouldShowFinished(done, 1_500)).toBe(true);
+		expect(shouldShowFinished(done, 10_000)).toBe(false);
+
+		const out = render([done], 1_500);
+		expect(out).toContain("\u2713");
+		// All jobs finished → filled heading disk.
+		expect(out).toContain("\u25cf BTW (0)");
+	});
+
+	test("errors linger longer and show the message", () => {
+		const failed = job({ status: "error", completedAt: 1_000, error: "boom" });
+		expect(shouldShowFinished(failed, 6_000)).toBe(true); // past the 5s ok-window
+		expect(render([failed], 6_000)).toContain("boom");
+	});
+
+	test("overflow collapses excess rows into a +N more line", () => {
+		const many = Array.from({ length: 20 }, (_, i) => job({ id: i + 1 }));
+		const lines = renderBtwWidget(many, theme, 0, 1_000, 200);
+		expect(lines.length).toBeLessThanOrEqual(12);
+		expect(lines.at(-1)).toContain("more");
+	});
+
+	test("hasVisibleJobs mirrors render visibility", () => {
+		expect(hasVisibleJobs([job({})], 1_000)).toBe(true);
+		expect(hasVisibleJobs([job({ status: "completed", completedAt: 0 })], 999_999)).toBe(false);
+	});
+});

package/src/btw/widget.ts

@@ -0,0 +1,158 @@
+/**
+ * widget.ts — pure render for the live BTW above-editor widget.
+ *
+ * Kept separate from index.ts (which owns job lifecycle + Pi wiring) so the
+ * layout is unit-testable without a Pi host, and so registerBtw stays thin.
+ * Mirrors pix-subagent's AgentWidget shape (spinner, per-job stats, finished
+ * linger, overflow) for a consistent look across pix's concurrent-work UIs.
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
+import {
+	type ContextUsageLike,
+	describeActivity,
+	formatContext,
+	formatMs,
+	formatSpeed,
+	formatToolUses,
+	formatTurns,
+	SPINNER,
+} from "@xynogen/pix-pretty/widget-format";
+
+export type BtwJobStatus = "running" | "completed" | "error" | "stopped";
+
+/** Snapshot of one job the widget needs to render. */
+export interface BtwWidgetJob {
+	id: number;
+	model: string;
+	status: BtwJobStatus;
+	startedAt: number;
+	completedAt?: number;
+	activeTools: string[];
+	text: string;
+	toolUses: number;
+	turnCount: number;
+	outputTokens: number;
+	contextUsage: ContextUsageLike | null;
+	error?: string;
+}
+
+/** Minimal theme surface the widget uses (matches Pi's Theme). */
+export interface WidgetTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+const MAX_WIDGET_LINES = 12;
+const FINISHED_LINGER_MS = 5_000;
+const ERROR_LINGER_MS = 15_000;
+const ERROR_STATUSES = new Set<BtwJobStatus>(["error", "stopped"]);
+
+/** True while a finished job should still linger in the widget. */
+export function shouldShowFinished(job: BtwWidgetJob, now: number): boolean {
+	if (job.status === "running" || job.completedAt == null) return false;
+	const linger = ERROR_STATUSES.has(job.status) ? ERROR_LINGER_MS : FINISHED_LINGER_MS;
+	return now - job.completedAt < linger;
+}
+
+/** Any job worth painting right now (running or lingering finished). */
+export function hasVisibleJobs(jobs: Iterable<BtwWidgetJob>, now: number): boolean {
+	for (const job of jobs) {
+		if (job.status === "running" || shouldShowFinished(job, now)) return true;
+	}
+	return false;
+}
+
+function statsFor(job: BtwWidgetJob, endMs: number): string {
+	const parts: string[] = [];
+	if (job.turnCount > 0) parts.push(formatTurns(job.turnCount));
+	if (job.toolUses > 0) parts.push(formatToolUses(job.toolUses));
+	const ctx = formatContext(job.contextUsage);
+	if (ctx) parts.push(ctx);
+	const speed = formatSpeed(job.outputTokens, endMs - job.startedAt);
+	if (speed) parts.push(speed);
+	parts.push(formatMs(endMs - job.startedAt));
+	return parts.join(" \u00b7 ");
+}
+
+function finishedLine(job: BtwWidgetJob, theme: WidgetTheme): string {
+	const end = job.completedAt ?? Date.now();
+	let mark: string;
+	let suffix = "";
+	if (job.status === "completed") {
+		mark = theme.fg("success", "\u2713");
+	} else if (job.status === "stopped") {
+		mark = theme.fg("dim", "\u25a0");
+		suffix = theme.fg("dim", " stopped");
+	} else {
+		mark = theme.fg("error", "\u2717");
+		suffix = theme.fg("error", job.error ? ` ${job.error.slice(0, 60)}` : " error");
+	}
+	const model = theme.fg("muted", `[${job.model}]`);
+	const stats = theme.fg("dim", statsFor(job, end));
+	return `${mark} ${theme.fg("dim", `#${job.id}`)} ${model} ${theme.fg("dim", "\u00b7")} ${stats}${suffix}`;
+}
+
+function runningLine(job: BtwWidgetJob, theme: WidgetTheme, frame: string, now: number): string {
+	const model = theme.fg("muted", `[${job.model}]`);
+	const stats = theme.fg("dim", statsFor(job, now));
+	const activeMap = new Map<string, string>(job.activeTools.map((name, i) => [String(i), name]));
+	const activity = theme.fg("dim", describeActivity(activeMap, job.text));
+	const dot = theme.fg("dim", "\u00b7");
+	return `${theme.fg("accent", frame)} ${theme.fg("toolTitle", theme.bold(`#${job.id}`))} ${model} ${dot} ${stats} ${dot} ${activity}`;
+}
+
+/**
+ * Render the full widget: heading + one line per running job, then lingering
+ * finished jobs, with a "+N more" overflow line when the budget is exceeded.
+ * Returns [] when nothing is worth showing.
+ */
+export function renderBtwWidget(
+	jobs: BtwWidgetJob[],
+	theme: WidgetTheme,
+	frame: number,
+	now: number,
+	width: number,
+): string[] {
+	const running = jobs.filter((j) => j.status === "running");
+	const finished = jobs.filter((j) => j.status !== "running" && shouldShowFinished(j, now));
+	if (running.length === 0 && finished.length === 0) return [];
+
+	const truncate = (line: string) => truncateToWidth(line, width);
+	const hasActive = running.length > 0;
+	const headingColor = hasActive ? "accent" : "dim";
+	const headingIcon = hasActive ? icon("status.pending") : icon("status.done"); // running · all done
+	const spinner = SPINNER[frame % SPINNER.length] ?? "";
+
+	const runningLines = running.map((j) =>
+		truncate(`${theme.fg("dim", "\u251c\u2500")} ${runningLine(j, theme, spinner, now)}`),
+	);
+	const finishedLines = finished.map((j) =>
+		truncate(`${theme.fg("dim", "\u251c\u2500")} ${finishedLine(j, theme)}`),
+	);
+
+	const lines: string[] = [
+		truncate(
+			`${theme.fg(headingColor, headingIcon)} ${theme.fg(headingColor, `BTW (${running.length})`)}`,
+		),
+	];
+
+	const body = [...runningLines, ...finishedLines];
+	const maxBody = MAX_WIDGET_LINES - 1;
+	if (body.length <= maxBody) {
+		lines.push(...body);
+	} else {
+		const shown = body.slice(0, maxBody - 1);
+		const hidden = body.length - shown.length;
+		lines.push(...shown);
+		lines.push(
+			truncate(`${theme.fg("dim", "\u251c\u2500")} ${theme.fg("dim", `+${hidden} more`)}`),
+		);
+	}
+
+	// Fix the last connector ├─ → └─.
+	const last = lines.length - 1;
+	if (last > 0) lines[last] = (lines[last] ?? "").replace("\u251c\u2500", "\u2514\u2500");
+	return lines;
+}

package/src/extension.test.ts

@@ -14,7 +14,7 @@ describe("pix-commands registration", () => {
 			registerCommand(name: string) {
 				commands.push(name);
 			},
-			registerMessageRenderer(name: string) {
+			registerEntryRenderer(name: string) {
 				renderers.push(name);
 			},
 			on() {},