gentle-pi 2.4.0 → 2.5.0

package/tests/agents-view.test.ts

@@ -0,0 +1,274 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentsView, itemLines, taskHeader } from "../lib/agents-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// Gentle Agents overlay: list left, selected thread right, tail-following,
+// and only the selected task subscribed.
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(id: string, overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return { id, agent: "explore", mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.RUNNING, createdAt: 1000, startedAt: 1000, endedAt: null, model: "gpt-5.6-terra", thinking: undefined, sessionPath: "/sessions/x.jsonl", error: null, result: null, lastStep: "grep", lastActivityAt: 1000, turns: 0, toolCalls: 0, tokens: 34_000, cost: 0.27, ...overrides };
+}
+
+function harness(rows = 8, sessionId?: string) {
+	const store = new TaskStore();
+	const events: string[] = [];
+	let renders = 0;
+	const view = new AgentsView({
+		theme: plainTheme,
+		rows,
+		store,
+		sessionId,
+		now: () => 61_000,
+		onCancel: (entry) => events.push(`cancel:${entry.id}`),
+		onOpen: (entry) => events.push(`open:${entry.id}`),
+		onClose: () => events.push("close"),
+		requestRender: () => (renders += 1),
+	});
+	return { store, view, events, renders: () => renders };
+}
+
+test("itemLines renders text, whole thinking blocks, whole tool output, and notes", () => {
+	assert.deepEqual(itemLines({ kind: "text", text: "one two three four" }, plainTheme, 9), ["one two", "three", "four"]);
+	assert.deepEqual(itemLines({ kind: "thinking", text: "deep\nthoughts" }, plainTheme, 20), ["∴ deep", "  thoughts"]);
+	const output = Array.from({ length: 10 }, (_, index) => `line ${index}`).join("\n");
+	const tool = itemLines({ kind: "tool", callId: "c", name: "bash", args: { command: "ls  -la" }, output, running: true, isError: false }, plainTheme, 30);
+	assert.equal(tool[0], "▸ bash ls -la");
+	assert.equal(tool.length, 12, "head, every output line, running marker");
+	assert.equal(tool[1], "  line 0");
+	assert.equal(tool[10], "  line 9");
+	assert.equal(tool[11], "  …");
+	// A long output line wraps instead of being clipped, so nothing is hidden.
+	const wide = itemLines({ kind: "tool", callId: "c", name: "bash", args: {}, output: "alpha beta gamma delta", running: false, isError: false }, plainTheme, 12);
+	assert.deepEqual(wide.slice(1), ["  alpha beta", "  gamma", "  delta"]);
+	assert.deepEqual(itemLines({ kind: "note", text: "error: boom" }, plainTheme, 30), ["· error: boom"]);
+	assert.equal(taskHeader(task("a"), 61_000), "explore · running · gpt-5.6-terra · 34k · $0.27 · 1m00s");
+});
+
+test("AgentsView renders the frame with the task list and the selected thread's tail, at width", () => {
+	const { store, view } = harness(8);
+	store.add(task("a"));
+	store.add(task("b", { agent: "worker", status: TASK_STATUS.COMPLETED, endedAt: 5000, createdAt: 900, lastActivityAt: 900 }));
+	for (let index = 0; index < 6; index += 1) store.apply("a", { type: TASK_EVENT.TEXT, text: `line ${index}\n` }, 2000);
+	const lines = view.render(90);
+	for (const line of lines) assert.equal(visibleWidth(line), 90, `"${stripAnsi(line)}" is not 90 wide`);
+	const plain = lines.map(stripAnsi);
+	assert.equal(plain.length, 8);
+	assert.match(plain[0], /^╭─ ❀ Agents · 1 active · 1 finished ─+╮$/);
+	assert.match(plain[1], /^│ ▸ ◐ explore  1m00s +│ explore · running · gpt-5\.6-terra · 34k · \$0\.27 · 1m00s +│$/);
+	assert.match(plain[2], /^│   ✓ worker  4s +│ line 3 +│$/, "the thread window follows the tail");
+	assert.match(plain[4], /line 5/);
+	assert.match(plain[6], /j\/k task .* esc close/);
+	assert.match(plain[7], /^╰─+╯$/);
+});
+
+test("AgentsView keys move the selection, scroll, follow, cancel, open, and close", () => {
+	const { store, view, events } = harness(8);
+	store.add(task("a"));
+	store.add(task("b", { createdAt: 900, lastActivityAt: 900, status: TASK_STATUS.COMPLETED, endedAt: 5000 }));
+	assert.equal(view.selectedTask()?.id, "a");
+	view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "b");
+	view.handleInput("c");
+	assert.deepEqual(events, [], "finished tasks cannot be cancelled");
+	view.handleInput("k");
+	view.handleInput("c");
+	view.handleInput("o");
+	view.handleInput("\x1b");
+	assert.deepEqual(events, ["cancel:a", "open:a", "close"]);
+	for (let index = 0; index < 12; index += 1) store.apply("a", { type: TASK_EVENT.TEXT, text: `l${index}\n` }, 2000);
+	view.handleInput("\x1b[5~");
+	assert.match(stripAnsi(view.render(80)[2]), /│ l0 +│$/, "page up leaves follow mode and shows the top");
+	view.handleInput("\x0a");
+	assert.match(stripAnsi(view.render(80)[2]), /│ l4 +│$/, "ctrl+j scrolls one page down");
+	view.handleInput("\x0b");
+	assert.match(stripAnsi(view.render(80)[2]), /│ l0 +│$/, "ctrl+k scrolls one page up");
+	view.handleInput("f");
+	assert.match(stripAnsi(view.render(80)[2]), /│ l9 +│$/, "f follows the tail again");
+});
+
+test("AgentsView subscribes only to the selected task and survives an empty store", () => {
+	const { store, view, renders } = harness(6);
+	assert.match(stripAnsi(view.render(60)[1]), /no tasks yet/);
+	store.add(task("a"));
+	store.add(task("b", { createdAt: 900, lastActivityAt: 900 }));
+	const before = renders();
+	store.apply("b", { type: TASK_EVENT.TEXT, text: "quiet" }, 2000);
+	assert.equal(renders(), before, "an event on the unselected task renders nothing");
+	store.apply("a", { type: TASK_EVENT.TEXT, text: "loud" }, 2000);
+	assert.equal(renders(), before + 1);
+	view.dispose();
+	store.apply("a", { type: TASK_EVENT.TEXT, text: "after" }, 2000);
+	assert.equal(renders(), before + 1, "disposed views stay quiet");
+});
+
+function mouse(x: number, y: number, width: number, height: number, type: TuiMouseEvent["type"] = "move", wheelDelta?: number): TuiMouseEvent {
+	return { type, button: type === "move" || type === "wheel" ? "none" : "left", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false, wheelDelta };
+}
+
+test("AgentsView pointer regions hover and select task rows without activating, and keep list and thread wheels independent", () => {
+	const { store, view, events } = harness(6);
+	for (const id of ["a", "b", "c", "d", "e"]) store.add(task(id, { agent: id }));
+	for (let index = 0; index < 8; index += 1) store.apply("b", { type: TASK_EVENT.TEXT, text: `thread ${index}\n` }, 2000);
+	const lines = view.render(80);
+
+	assert.equal(view.handleMouse(mouse(4, 2, 80, lines.length))?.handled, true, "hover consumes only the task row");
+	assert.equal(view.selectedTask()?.id, "a", "hover never changes keyboard selection or the displayed thread");
+	assert.equal(view.handleMouse(mouse(4, 2, 80, lines.length, "click"))?.handled, true);
+	assert.equal(view.selectedTask()?.id, "b", "click selects the task and displays its thread");
+	assert.deepEqual(events, [], "click selects the task only; it never opens or cancels");
+	view.render(80);
+	assert.equal(view.handleMouse(mouse(50, 2, 80, lines.length, "wheel", -1))?.handled, true, "thread wheel is handled by its viewport");
+	assert.match(stripAnsi(view.render(80)[2]), /thread 6/, "thread wheel moves only the selected thread");
+	assert.equal(view.handleMouse(mouse(4, 2, 80, lines.length, "wheel", 1))?.handled, true, "list wheel is handled by its viewport");
+	assert.match(stripAnsi(view.render(80)[1]), / b /, "list wheel changes only the task-list viewport");
+	assert.equal(view.handleMouse(mouse(50, 2, 80, lines.length, "click")), undefined, "thread clicks are inert");
+	view.dispose();
+	assert.equal(view.handleMouse(mouse(4, 2, 80, lines.length)), undefined, "late pointer events are inert after disposal");
+});
+
+test("AgentsView clears hover on leave, list scrolling, resize, updates, empty lists, and disposal", () => {
+	const { store, view } = harness(6);
+	store.add(task("a"));
+	store.add(task("b", { agent: "b" }));
+	store.add(task("c", { agent: "c" }));
+	store.add(task("d", { agent: "d" }));
+	const lines = view.render(80);
+	const observer = view.mouseObserver();
+	const dispatch = (event: TuiMouseEvent) => {
+		observer.beforeMouse(event);
+		try {
+			return view.handleMouse(event);
+		} finally {
+			observer.afterMouse(event);
+		}
+	};
+	dispatch(mouse(4, 2, 80, lines.length));
+	assert.match(stripAnsi(view.render(80)[2]), /▹/, "the hovered row is styled without changing selection");
+	dispatch(mouse(4, 2, 80, lines.length, "wheel", -1));
+	assert.match(stripAnsi(view.render(80)[2]), /▹/, "a list wheel event at its boundary preserves hover");
+	dispatch(mouse(4, 2, 80, lines.length, "wheel", 1));
+	assert.doesNotMatch(stripAnsi(view.render(80).join("\n")), /▹/, "list scrolling clears hover so it cannot remain on the task formerly under the pointer");
+	dispatch(mouse(4, 2, 80, lines.length));
+	dispatch(mouse(50, 2, 80, lines.length));
+	assert.doesNotMatch(stripAnsi(view.render(80)[2]), /▹/, "the root observer clears hover outside a child region");
+	dispatch(mouse(4, 2, 80, lines.length));
+	view.render(81);
+	assert.doesNotMatch(stripAnsi(view.render(81)[2]), /▹/, "resize clears hover before the next frame");
+	dispatch(mouse(4, 2, 81, lines.length));
+	store.apply("a", { type: TASK_EVENT.TEXT, text: "update" }, 2000);
+	assert.doesNotMatch(stripAnsi(view.render(81)[2]), /▹/, "task updates clear hover");
+	view.dispose();
+	const { view: empty } = harness(6);
+	empty.render(80);
+	assert.equal(empty.handleMouse(mouse(4, 1, 80, 6)), undefined, "empty task rows are inert");
+	empty.dispose();
+});
+
+test("AgentsView advertises s to stop an active selection, retains c as an alias, and hides stopping for finished tasks", () => {
+	const { store, view, events } = harness(8);
+	store.add(task("active"));
+	assert.match(stripAnsi(view.render(80).at(-2) ?? ""), /s Stop selected/);
+	view.handleInput("s");
+	view.handleInput("c");
+	assert.deepEqual(events, ["cancel:active", "cancel:active"]);
+	store.update("active", { status: TASK_STATUS.CANCELLED, endedAt: 2000 });
+	assert.doesNotMatch(stripAnsi(view.render(80).at(-2) ?? ""), /Stop selected/);
+	view.handleInput("s");
+	assert.deepEqual(events, ["cancel:active", "cancel:active"], "finished tasks never stop");
+});
+
+test("AgentsView Escape and q close an active selection without cancelling it", () => {
+	const { store, view, events } = harness(8);
+	store.add(task("active"));
+	view.handleInput("\x1b");
+	view.handleInput("q");
+	assert.deepEqual(events, ["close", "close"], "close keys never invoke selected-task cancellation");
+});
+
+test("AgentsView scrolls the task list so the selection stays visible when there are more tasks than rows", () => {
+	const { store, view } = harness(6);
+	for (let index = 0; index < 6; index += 1) store.add(task(`t${index}`, { agent: `agent${index}`, createdAt: 1000 - index, lastActivityAt: 1000 - index }));
+	const listed = () => view.render(80).slice(1, 4).map((line) => stripAnsi(line).slice(0, 24));
+	assert.match(listed()[0], /▸ ◐ agent0/);
+	assert.match(listed()[2], /agent2/);
+	for (let index = 0; index < 4; index += 1) view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "t4");
+	assert.match(listed()[2], /▸ ◐ agent4/, "the list scrolls down until the selection is the last visible row");
+	assert.match(listed()[0], /agent2/);
+	view.handleInput("j");
+	view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "t5", "the selection stops at the last task");
+	assert.match(listed()[2], /▸ ◐ agent5/);
+	for (let index = 0; index < 4; index += 1) view.handleInput("k");
+	assert.match(listed()[0], /▸ ◐ agent1/, "moving up scrolls the list back");
+	assert.match(listed()[2], /agent3/);
+});
+
+test("AgentsView lists the active session's recent tasks by default and a toggles every session", () => {
+	const { store, view } = harness(8, "s");
+	store.add(task("mine", { agent: "mine" }));
+	store.add(task("theirs", { agent: "theirs", parentSessionId: "other", createdAt: 900, lastActivityAt: 900 }));
+	store.add(task("fresh", { agent: "fresh", status: TASK_STATUS.COMPLETED, endedAt: 61_000 - 60_000, createdAt: 850, lastActivityAt: 850 }));
+	store.add(task("stale", { agent: "stale", status: TASK_STATUS.COMPLETED, endedAt: 61_000 - 16 * 60_000, createdAt: 800, lastActivityAt: 800 }));
+	const names = () => view.render(80).map(stripAnsi).filter((line) => /[◐✓] /.test(line)).map((line) => line.match(/[◐✓] (\w+)/)?.[1]);
+	let plain = view.render(80).map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · this session · 1 active · 1 finished ─+╮$/);
+	assert.deepEqual(names(), ["mine", "fresh"], "another session's task and one finished over fifteen minutes ago stay out");
+	assert.match(plain.at(-2) ?? "", /a all sessions/);
+	view.handleInput("a");
+	plain = view.render(80).map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · all sessions · 2 active · 2 finished ─+╮$/);
+	assert.deepEqual(names(), ["mine", "theirs", "fresh", "stale"]);
+	assert.match(plain.at(-2) ?? "", /a this session/);
+	view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "theirs");
+	view.handleInput("a");
+	assert.equal(view.selectedTask()?.id, "mine", "a new scope reads from the top");
+	assert.deepEqual(names(), ["mine", "fresh"]);
+});
+
+test("AgentsView footer buttons follow, open only a session-backed selection, and clear stale geometry", () => {
+	const { store, view, events } = harness(8, "s");
+	store.add(task("a", { sessionPath: "/sessions/a.jsonl" }));
+	for (let index = 0; index < 12; index += 1) store.apply("a", { type: TASK_EVENT.TEXT, text: `line ${index}\n` }, 2000);
+	const width = 160;
+	const lines = view.render(width);
+	const footerY = lines.length - 2;
+	const followX = 131;
+	const openX = 142;
+	assert.match(stripAnsi(lines.at(-2) ?? ""), /\[ Follow \].*\[ Open session \]/, "buttons render only after the full key-hint row fits");
+
+	view.handleInput("\x1b[5~");
+	assert.match(stripAnsi(view.render(width)[2]), /line 5/, "page up leaves follow mode before the button restores it");
+	assert.equal(view.handleMouse(mouse(followX, footerY, width, lines.length))?.render, true, "button hover requests a distinct frame");
+	assert.equal(view.handleMouse(mouse(followX, footerY, width, lines.length, "press")), undefined, "press is inert");
+	assert.equal(view.handleMouse({ ...mouse(followX, footerY, width, lines.length, "click"), button: "right" }), undefined, "right click is inert");
+	assert.equal(view.handleMouse({ ...mouse(followX, footerY, width, lines.length, "click"), button: "middle" }), undefined, "middle click is inert");
+	assert.equal(view.handleMouse(mouse(followX, footerY, width, lines.length, "click"))?.handled, true);
+	assert.match(stripAnsi(view.render(width)[2]), /line 9/, "Follow returns the selected thread to its tail");
+	assert.equal(view.handleMouse(mouse(openX, footerY, width, lines.length, "click"))?.handled, true);
+	assert.deepEqual(events, ["open:a"], "Open delegates the selected task to the existing callback");
+	assert.equal(view.handleMouse(mouse(followX, footerY, width + 1, lines.length, "click")), undefined, "a pre-render resize makes the prior footer geometry inert");
+
+	store.update("a", { sessionPath: null });
+	view.render(width);
+	assert.equal(view.handleMouse(mouse(openX, footerY, width, lines.length, "click")), undefined, "Open is disabled when the selected task loses its session path");
+	assert.deepEqual(events, ["open:a"]);
+	view.render(200);
+	assert.equal(view.handleMouse(mouse(followX, footerY, 200, lines.length, "click")), undefined, "resize discards the old footer geometry before routing clicks");
+	assert.doesNotMatch(stripAnsi(view.render(44).at(-2) ?? ""), /\[ Follow \]|\[ Open session \]/, "buttons hide instead of truncating when the rendered key hints do not fit");
+	view.handleInput("a");
+	assert.equal(view.handleMouse(mouse(followX, footerY, width, lines.length, "click")), undefined, "a scope change clears old footer geometry until the next frame");
+	view.dispose();
+	assert.equal(view.handleMouse(mouse(followX, footerY, width, lines.length, "click")), undefined, "disposed footer controls stay inert");
+	const { view: empty } = harness(8, "s");
+	const emptyLines = empty.render(width);
+	assert.equal(empty.handleMouse(mouse(followX, footerY, width, emptyLines.length, "click")), undefined, "Follow is disabled with no selected task");
+	assert.equal(empty.handleMouse(mouse(openX, footerY, width, emptyLines.length, "click")), undefined, "Open is disabled with no selected session");
+	empty.dispose();
+});

package/tests/agents-widget.test.ts

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { TASK_STATUS, type TaskRecord } from "../lib/agents-protocol.ts";
+import { formatElapsed, renderAgentsCard, widgetExpiryMs, widgetRows, widgetTasks } from "../lib/agents-widget.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// Gentle Agents widget: the card above the editor that shows what the
+// subagents are doing, drawn from task records only (never from threads).
+// Layout: glyph, agent, task summary (wrapped), then model · tokens · cost · time.
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(overrides: Partial<TaskRecord>): TaskRecord {
+	return { id: "t", agent: "sdd-explore", mode: "task", prompt: "map footer data sources", label: "map footer data sources", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.RUNNING, createdAt: 1000, startedAt: 1000, endedAt: null, model: "anthropic/claude-sonnet-5", thinking: undefined, sessionPath: null, error: null, result: null, lastStep: "grep", lastActivityAt: 1000, turns: 0, toolCalls: 0, tokens: 34_000, cost: 0.27, ...overrides };
+}
+
+test("formatElapsed renders seconds, minutes, and hours compactly", () => {
+	assert.equal(formatElapsed(4_000), "4s");
+	assert.equal(formatElapsed(65_000), "1m05s");
+	assert.equal(formatElapsed(3_720_000), "1h02m");
+	assert.equal(formatElapsed(-5), "0s");
+});
+
+test("widgetTasks keeps active tasks in start order and only recently finished ones", () => {
+	const tasks = [
+		task({ id: "old-done", status: TASK_STATUS.COMPLETED, endedAt: 10_000 }),
+		task({ id: "new-done", status: TASK_STATUS.FAILED, endedAt: 95_000 }),
+		task({ id: "queued", status: TASK_STATUS.QUEUED, createdAt: 3000, startedAt: null }),
+		task({ id: "running", createdAt: 2000, startedAt: 2000 }),
+	];
+	assert.deepEqual(widgetTasks(tasks, 100_000).map((entry) => entry.id), ["new-done", "running", "queued"]);
+	assert.deepEqual(widgetTasks([], 100_000), []);
+});
+
+test("widgetExpiryMs says how long until the next finished row leaves the card", () => {
+	const running = task({ id: "running", createdAt: 2000, startedAt: 2000 });
+	const done = task({ id: "done", status: TASK_STATUS.COMPLETED, endedAt: 95_000 });
+	const later = task({ id: "later", status: TASK_STATUS.COMPLETED, endedAt: 99_000 });
+	assert.equal(widgetExpiryMs([running, done, later], 100_000), 55_000, "the oldest shown row expires first");
+	assert.equal(widgetExpiryMs([done], 155_000), undefined, "a row past its minute is already gone");
+	assert.equal(widgetExpiryMs([running], 100_000), undefined, "active rows never expire");
+	assert.equal(widgetExpiryMs([], 100_000), undefined);
+});
+
+test("renderAgentsCard draws columns for agent, task, and model · tokens · cost · time, with the batch time in the rule", () => {
+	const tasks = [
+		task({ id: "a", status: TASK_STATUS.COMPLETED, startedAt: 1000, endedAt: 26_000 }),
+		task({ id: "b", agent: "sdd-apply", label: "write gentle-shell footer", startedAt: 44_000, tokens: 12_000, cost: 0.09 }),
+	];
+	const lines = renderAgentsCard(tasks, plainTheme, 84, 85_000, { collapsed: false });
+	for (const line of lines) assert.equal(visibleWidth(line), 84, `"${stripAnsi(line)}" is not 84 wide`);
+	const plain = lines.map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · 1 active · 1 done ─+ 1m24s ╮$/);
+	assert.match(plain[1], /^│ ✓  sdd-explore  map footer data sources +claude-sonnet-5 · 34k · \$0\.27 · 25s │$/);
+	assert.match(plain[2], /^│ ◐  sdd-apply    write gentle-shell footer +claude-sonnet-5 · 12k · \$0\.09 · 41s │$/);
+	assert.match(plain[3], /^╰─+╯$/);
+	assert.deepEqual(renderAgentsCard([], plainTheme, 60, 0, { collapsed: false }), []);
+});
+
+test("renderAgentsCard keeps every task on one line, clipping long labels, and drops the task column when the card is narrow", () => {
+	const tasks = [task({ id: "a", label: "write the gentle shell footer and all of its tests before lunch" })];
+	const wide = renderAgentsCard(tasks, plainTheme, 84, 5_000, { collapsed: false }).map(stripAnsi);
+	assert.equal(wide.length, 3);
+	assert.match(wide[1], /^│ ◐  sdd-explore  write the gentle shell foot… +claude-sonnet-5 · 34k · \$0\.27 · 4s │$/);
+	const narrow = renderAgentsCard(tasks, plainTheme, 44, 5_000, { collapsed: false }).map(stripAnsi);
+	assert.equal(narrow.length, 3);
+	assert.match(narrow[1], /^│ ◐  sdd-explore +34k · \$0\.27 · 4s │$/);
+});
+
+test("renderAgentsCard shows questions and failures in place of the task, and collapses to the first row", () => {
+	const tasks = [
+		task({ id: "a", status: TASK_STATUS.WAITING, lastStep: "asked: Delete?", tokens: 0, cost: 0 }),
+		task({ id: "b", status: TASK_STATUS.FAILED, endedAt: 2000, error: "pi exited with code 1", lastStep: "pi exited with code 1" }),
+		task({ id: "c", status: TASK_STATUS.QUEUED, createdAt: 1500, startedAt: null, tokens: 0, cost: 0 }),
+	];
+	const plain = renderAgentsCard(tasks, plainTheme, 80, 3000, { collapsed: false }).map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · 1 waiting · 1 queued · 1 failed ─+ 2s ╮$/);
+	assert.match(plain[1], /^│ \?  sdd-explore  asked: Delete\? +claude-sonnet-5 · 2s │$/);
+	assert.match(plain[2], /^│ ✗  sdd-explore  pi exited with code 1 +claude-sonnet-5 · 34k · \$0\.27 · 1s │$/);
+	assert.match(plain[3], /^│ ○  sdd-explore  map footer data sources +queued │$/);
+	const collapsed = renderAgentsCard(tasks, plainTheme, 80, 3000, { collapsed: true, collapseKey: "ctrl+shift+a" }).map(stripAnsi);
+	assert.equal(collapsed.length, 3);
+	assert.match(collapsed[0], /ctrl\+shift\+a expand ╮$/);
+	assert.match(collapsed[1], /^│ \?  sdd-explore  asked: Delete\?/);
+});
+
+test("widgetRows caps the card at a quarter of the terminal, between three and eight rows", () => {
+	assert.equal(widgetRows(40), 8, "tall terminals still stop at eight rows");
+	assert.equal(widgetRows(24), 6);
+	assert.equal(widgetRows(10), 3, "short terminals keep three rows");
+	assert.equal(widgetRows(undefined), 8, "without a terminal the widest default applies");
+});
+
+test("renderAgentsCard caps the rows at maxRows, keeps active tasks ahead of finished ones, and says how many are hidden", () => {
+	const tasks = [
+		task({ id: "done", status: TASK_STATUS.COMPLETED, startedAt: 500, endedAt: 2000 }),
+		...Array.from({ length: 6 }, (_, index) => task({ id: `run${index}`, label: `job ${index}`, createdAt: 1000 + index, startedAt: 1000 + index })),
+	];
+	const plain = renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 4, viewKey: "alt+a" }).map(stripAnsi);
+	assert.equal(plain.length, 6, "frame plus four rows");
+	assert.match(plain[0], /6 active · 1 done/, "the title still counts every shown task");
+	assert.match(plain[1], /◐  sdd-explore  job 0/);
+	assert.match(plain[3], /◐  sdd-explore  job 2/);
+	assert.match(plain[4], /^│ … 4 more · alt\+a to view +│$/, "the finished row gives way to running ones");
+	assert.equal(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false }).length, 9, "without a cap every row shows");
+	assert.equal(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 7 }).length, 9, "at the cap no row is hidden");
+	assert.match(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 4 }).map(stripAnsi)[4], /^│ … 4 more +│$/, "no view key, no hint");
+	const waiting = [...tasks, task({ id: "ask", status: TASK_STATUS.WAITING, lastStep: "asked: Delete?", createdAt: 4000, startedAt: 4000 })];
+	assert.match(renderAgentsCard(waiting, plainTheme, 80, 5000, { collapsed: false, maxRows: 2 }).map(stripAnsi)[1], /^│ \?  sdd-explore  asked: Delete\?/, "a question is never hidden");
+});

package/tests/ask-user-choice.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
 import askUserChoice from "../extensions/ask-user-choice.ts";
 
 interface ChoiceResult {
@@ -35,6 +36,35 @@ interface ChoiceLifecycleEvent {
 	data: { active: boolean };
 }
 
+interface NativeChoiceComponent {
+	render(width: number): string[];
+	handleInput(data: string): void;
+	handleMouse?: (event: Record<string, unknown>) => NativeChoiceMouseResult | undefined;
+}
+
+interface NativeChoiceMouseResult {
+	handled?: boolean;
+	focus?: boolean;
+	render?: boolean;
+}
+
+interface ChoiceTui {
+	requestRender(): void;
+}
+
+interface ChoiceTheme {
+	fg(color: string, text: string): string;
+	bg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+type ChoiceCustomFactory = (
+	tui: ChoiceTui,
+	theme: ChoiceTheme,
+	keybindings: unknown,
+	done: (value: unknown) => void,
+) => NativeChoiceComponent;
+
 type BeforeAgentStart = (event: unknown, ctx: { mode: string }) => void | Promise<void>;
 
 function registerChoiceTool(
@@ -103,11 +133,11 @@ function tuiContext(inputs: readonly string[], rendered: { value: string }) {
 	return {
 		mode: "tui",
 		ui: {
-			custom: async (factory: (tui: { requestRender(): void }, theme: { fg(_color: string, text: string): string; bold(text: string): string }, keybindings: unknown, done: (value: unknown) => void) => { render(width: number): string[]; handleInput(data: string): void }) => {
+			custom: async (factory: ChoiceCustomFactory) => {
 				let result: unknown;
 				const component = factory(
 					{ requestRender() {} },
-					{ fg: (_color, text) => text, bold: (text) => text },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
 					{},
 					(value) => {
 						result = value;
@@ -143,6 +173,128 @@ test("ask_user_choice exposes a strict closed single-select schema", () => {
 	assert.deepEqual(Object.keys(optionSchema?.properties ?? {}).sort(), ["description", "label", "value"]);
 });
 
+test("ask_user_choice hover preserves the keyboard-selected opaque value", async () => {
+	const { tool } = registerChoiceTool();
+	let completionCalls = 0;
+	const result = await tool.execute("call", { question: "Proceed?", options }, new AbortController().signal, undefined, {
+		mode: "tui",
+		ui: { custom: async (factory: ChoiceCustomFactory) => {
+			let completed: unknown;
+			const component = factory({ requestRender() {} }, {
+				fg: (_color, text) => `\u001b[38;5;39m${text}\u001b[39m`,
+				bg: (_color, text) => `\u001b[48;5;236m${text}\u001b[49m`, bold: (text) => text,
+			}, {}, (value) => { completionCalls++; completed = value; });
+			const lines = component.render(80);
+			const first = lines.findIndex((line) => stripTerminalSequences(line).includes(options[0]!.label));
+			const second = lines.findIndex((line) => stripTerminalSequences(line).includes(options[1]!.label));
+			assert.ok(first >= 0 && second >= 0);
+			const hover = {
+				type: "move", button: "none", x: 0, y: second,
+				screenX: 0, screenY: second, width: 80, height: lines.length,
+				shift: false, alt: false, ctrl: false,
+			};
+			assert.equal(component.handleMouse?.(hover)?.render, true);
+			assert.equal(completed, undefined, "hover never submits");
+			const hovered = component.render(80);
+			assert.ok(hovered[second]?.includes("\u001b[48;5;236m"), "only the second option is hovered");
+			assert.ok(
+				hovered[first]?.includes("\u001b[38;5;39m") && !hovered[first]?.includes("\u001b[48;5;236m"),
+				"hover does not change keyboard selection",
+			);
+			component.handleInput("\r");
+			component.handleInput("\r");
+			return completed;
+		} },
+	});
+	assert.deepEqual(result.details.selection, { value: options[0]!.value, label: options[0]!.label, index: 1 });
+	assert.equal(completionCalls, 1);
+});
+
+test("ask_user_choice retains native rendered hit testing for mouse selection", async () => {
+	const longOptions = [
+		{
+			label: "Authorize the observed baseline hash after independent verification",
+			description: "Accept the observed baseline after a long description that verifies layout offsets.",
+			value: "authorize_observed_hash",
+		},
+		{
+			label: "Preserve the originally requested hash without changing the envelope",
+			description: "Keep the original opaque answer token after the user confirms the requested value.",
+			value: "preserve_requested_hash",
+		},
+	];
+	const { tool } = registerChoiceTool();
+	let completionCalls = 0;
+	const result = await tool.execute(
+		"call",
+		{
+			question: "A deliberately long question verifies that the rendered header does not shift native option hit bounds.",
+			options: longOptions,
+		},
+		new AbortController().signal,
+		undefined,
+		{
+			mode: "tui",
+			ui: {
+				custom: async (factory: ChoiceCustomFactory) => {
+					let completed: unknown;
+					const component = factory(
+						{ requestRender() {} },
+						{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+						{},
+						(value) => {
+							completionCalls++;
+							completed = value;
+						},
+					) as NativeChoiceComponent;
+					const narrow = component.render(24);
+					assert.ok(narrow.length > 0, "the real component renders before a narrow-to-wide resize");
+					const wide = component.render(100);
+					const secondRow = wide.findIndex((line) => line.includes(longOptions[1]!.label.slice(0, 24)));
+					assert.ok(secondRow >= 0, "the test locates the actual rendered option row");
+					const event = (type: string, button: string, y: number, wheelDelta?: number) => ({
+						type,
+						button,
+						x: 1,
+						y,
+						screenX: 1,
+						screenY: y,
+						width: 100,
+						height: wide.length,
+						shift: false,
+						alt: false,
+						ctrl: false,
+						wheelDelta,
+					});
+					assert.equal(typeof component.handleMouse, "function", "native mouse dispatch must survive the custom UI adapter");
+					const wheel = component.handleMouse?.(event("wheel", "none", secondRow, 1));
+					assert.equal(wheel?.handled, true);
+					assert.equal(wheel?.render, true);
+					assert.equal(completed, undefined, "wheel changes focus without answering");
+					assert.equal(component.handleMouse?.(event("release", "left", secondRow)), undefined);
+					assert.equal(component.handleMouse?.(event("click", "right", secondRow)), undefined);
+					assert.equal(component.handleMouse?.(event("click", "left", wide.length)), undefined);
+					assert.equal(component.handleMouse?.({ type: "click" }), undefined);
+					const press = component.handleMouse?.(event("press", "left", secondRow));
+					assert.equal(press?.handled, true);
+					assert.equal(press?.focus, true);
+					assert.equal(completed, undefined, "press focuses and selects but never answers");
+					component.handleMouse?.(event("click", "left", secondRow));
+					component.handleMouse?.(event("click", "left", secondRow));
+					component.handleInput("\r");
+					return completed;
+				},
+			},
+		},
+	);
+	assert.deepEqual(result.details.selection, {
+		value: "preserve_requested_hash",
+		label: longOptions[1]!.label,
+		index: 2,
+	});
+	assert.equal(completionCalls, 1, "late keyboard input cannot complete the choice twice");
+});
+
 test("ask_user_choice handles a closed Kilo hash decision with an opaque envelope value", async () => {
 	const { tool } = registerChoiceTool(["read"]);
 	const rendered = { value: "" };
@@ -185,7 +337,9 @@ test("ask_user_choice emits a private balanced lifecycle around selection and ca
 			},
 		},
 	);
-	assert.equal(selected.details.selection?.value, "preserve_requested_hash");
+	const selection = selected.details.selection;
+	assert.ok(selection !== null && typeof selection === "object" && "value" in selection);
+	assert.equal(selection.value, "preserve_requested_hash");
 	assert.deepEqual(sequence, ["active", "custom", "inactive"]);
 	assert.deepEqual(selectedRegistration.emittedEvents(), [
 		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: true } },