gentle-pi 3.7.0 → 4.0.0

package/tests/agents-view-thread-identity.test.ts

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { TaskStore, type TaskThread } from "../lib/agents-protocol.ts";
+import { AgentsView } from "../lib/agents-view.ts";
+
+// Regression suite for #1011: every presence poll re-reads remote activity from
+// disk, so thread items arrive as fresh objects even when nothing changed.
+// refreshPresence must reuse the prior ThreadItem object when the sanitized new
+// item is deeply equal at the same position (WeakMap render cache hit), while
+// changed items keep a new identity so cached renderings cannot go stale.
+
+interface FixtureSummary {
+	id: string;
+	agent: string;
+	label: string;
+	status: string;
+	model: string;
+	createdAt: number;
+	startedAt: number | null;
+	endedAt: number | null;
+	lastActivityAt: number;
+}
+
+type FixtureItem = Record<string, unknown>;
+type FixtureTask = { summary: FixtureSummary; thread: { version: number; dropped: number; items: FixtureItem[] } };
+type FixtureSession = { sessionId: string; incarnation: string };
+
+function summary(id: string): FixtureSummary {
+	return { id, agent: "worker", label: `task ${id}`, status: "running", model: "test-model", createdAt: 1000, startedAt: 1000, endedAt: null, lastActivityAt: 1000 };
+}
+
+function sampleItems(): FixtureItem[] {
+	return [
+		{ kind: "text", text: "alpha" },
+		{ kind: "tool", callId: "c1", name: "grep", output: "matches", running: false, isError: false },
+		{ kind: "note", text: "note" },
+	];
+}
+
+// Writes the presence pair directly (same shape projectActivity publishes) so
+// tests control content and timing without the publisher's coalescing debounce.
+function publish(profile: string, session: FixtureSession, tasks: FixtureTask[]): void {
+	const root = join(profile, "gentle-agents", "presence");
+	mkdirSync(root, { recursive: true, mode: 0o700 });
+	const sessionHash = createHash("sha256").update(session.sessionId).digest("hex");
+	const bytes = Buffer.from(JSON.stringify({ schema: 1, sessionHash, incarnation: session.incarnation, generation: 1, activity: { tasks } }), "utf8");
+	const header = { schema: 1, sessionHash, incarnation: session.incarnation, label: "peer", heartbeat: Date.now(), generation: 1, counts: { running: tasks.length, queued: 0, waiting: 0, finished: 0 }, digest: createHash("sha256").update(bytes).digest("hex"), unavailable: null };
+	// Header last: readers validate activity bytes against the header digest.
+	writeFileSync(join(root, `${sessionHash}.${session.incarnation}.activity.json`), bytes);
+	writeFileSync(join(root, `${sessionHash}.${session.incarnation}.header.json`), JSON.stringify(header));
+}
+
+function taskKey(session: FixtureSession, summaryId: string): string {
+	const sessionHash = createHash("sha256").update(session.sessionId).digest("hex");
+	return `peer:${sessionHash}:${session.incarnation}:${summaryId}`;
+}
+
+function harness(profile: string): { view: AgentsView; remoteThreads(): Map<string, TaskThread> } {
+	const view = new AgentsView({
+		theme: { fg: (_color, text) => text },
+		rows: 10,
+		store: new TaskStore(),
+		sessionId: "local",
+		now: () => 61_000,
+		onCancel: () => {},
+		onOpen: () => {},
+		onClose: () => {},
+		requestRender: () => {},
+		presence: { profile },
+	});
+	return { view, remoteThreads: () => (view as unknown as { remoteThreads: Map<string, TaskThread> }).remoteThreads };
+}
+
+async function withPresenceFixture(run: (profile: string) => Promise<void>): Promise<void> {
+	// Presence rejects symlinked profile ancestors, and macOS tmpdir() lives under
+	// the /var -> /private/var symlink, so the fixture must use the canonical path.
+	const profile = mkdtempSync(join(realpathSync(tmpdir()), "agents-view-identity-"));
+	try {
+		await run(profile);
+	} finally {
+		rmSync(profile, { recursive: true, force: true });
+	}
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+async function until<T>(probe: () => T | undefined, description: string, timeoutMs = 5_000): Promise<T> {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const found = probe();
+		if (found !== undefined) return found;
+		if (Date.now() > deadline) throw new Error(`timed out waiting for ${description}`);
+		await sleep(5);
+	}
+}
+
+// The view replaces its remoteThreads map on every applied poll, so map
+// identity is a reliable witness that a subsequent poll has been applied.
+function nextApplication(h: ReturnType<typeof harness>, appliedOnce: Map<string, TaskThread>, key: string): Promise<TaskThread> {
+	return until(() => {
+		const map = h.remoteThreads();
+		return map === appliedOnce ? undefined : map.get(key);
+	}, "a subsequent presence poll");
+}
+
+test("unchanged remote thread items keep object identity across presence polls", async () => {
+	await withPresenceFixture(async (profile) => {
+		const session = { sessionId: "peer session", incarnation: randomUUID() };
+		publish(profile, session, [{ summary: summary("t1"), thread: { version: 1, dropped: 0, items: sampleItems() } }]);
+		const h = harness(profile);
+		try {
+			const first = await until(() => h.remoteThreads().get(taskKey(session, "t1")), "the first presence poll");
+			const firstItems = [...first.items];
+			const appliedOnce = h.remoteThreads();
+			// Same files on disk: the second poll still re-parses them, which is
+			// exactly the unchanged-content case that must reuse prior identities.
+			const second = await nextApplication(h, appliedOnce, taskKey(session, "t1"));
+			assert.notEqual(second, first, "the thread container is still rebuilt per poll");
+			assert.equal(second.items.length, firstItems.length);
+			second.items.forEach((item, index) => assert.equal(item, firstItems[index],
+				`unchanged item ${index} (kind ${String((firstItems[index] as { kind?: string }).kind)}) must reuse the prior object identity`));
+		} finally {
+			h.view.dispose();
+		}
+	});
+});
+
+test("a changed remote item takes a new identity while unchanged siblings keep theirs", async () => {
+	await withPresenceFixture(async (profile) => {
+		const session = { sessionId: "peer session", incarnation: randomUUID() };
+		publish(profile, session, [{ summary: summary("t1"), thread: { version: 1, dropped: 0, items: sampleItems() } }]);
+		const h = harness(profile);
+		try {
+			const first = await until(() => h.remoteThreads().get(taskKey(session, "t1")), "the first presence poll");
+			const firstItems = [...first.items];
+			const appliedOnce = h.remoteThreads();
+			const [, tool, note] = sampleItems();
+			publish(profile, session, [{ summary: summary("t1"), thread: { version: 1, dropped: 0, items: [{ kind: "text", text: "alpha changed" }, tool, note] } }]);
+			const second = await nextApplication(h, appliedOnce, taskKey(session, "t1"));
+			assert.notEqual(second.items[0], firstItems[0], "a changed item must yield a new object identity");
+			assert.equal(second.items[1], firstItems[1], "the unchanged tool sibling must reuse the prior identity");
+			assert.equal(second.items[2], firstItems[2], "the unchanged note sibling must reuse the prior identity");
+		} finally {
+			h.view.dispose();
+		}
+	});
+});
+
+test("tool items compare after args sanitization, so unchanged tools are reused with an empty args record", async () => {
+	await withPresenceFixture(async (profile) => {
+		const session = { sessionId: "peer session", incarnation: randomUUID() };
+		publish(profile, session, [{ summary: summary("t1"), thread: { version: 1, dropped: 0, items: [sampleItems()[1]] } }]);
+		const h = harness(profile);
+		try {
+			const first = await until(() => h.remoteThreads().get(taskKey(session, "t1")), "the first presence poll");
+			const appliedOnce = h.remoteThreads();
+			publish(profile, session, [{ summary: summary("t1"), thread: { version: 1, dropped: 0, items: [sampleItems()[1]] } }]);
+			const second = await nextApplication(h, appliedOnce, taskKey(session, "t1"));
+			assert.equal(second.items[0], first.items[0], "an unchanged tool item must reuse the prior sanitized object");
+			assert.deepEqual((second.items[0] as { args?: unknown }).args, {}, "the stored tool item keeps the sanitized args record");
+		} finally {
+			h.view.dispose();
+		}
+	});
+});

package/tests/agents-view.test.ts

@@ -242,7 +242,13 @@ test("renderThreadItem renders labeled text, thinking, tool-output, and note blo
 	const wide = renderThreadItem({ kind: "tool", callId: "c", name: "bash", args: {}, output: "alpha beta gamma delta", running: false, isError: false }, plainTheme, 12);
 	assert.deepEqual(wide.slice(2), ["    alpha", "    beta", "    gamma", "    delta"]);
 	assert.deepEqual(renderThreadItem({ kind: "note", text: "error: boom" }, plainTheme, 30), ["Note", "  error: boom"]);
-	assert.equal(taskHeader(task("a"), 61_000), "explore · running · gpt-5.6-terra · 34k · $0.27 · 1m00s");
+	assert.equal(taskHeader(task("a"), 61_000), "explore · running · gpt-5.6-terra · 34k · $0.270 · 1m00s");
+});
+
+test("taskHeader formats subagent cost with formatCost (three decimals below $1, two at or above $1)", () => {
+	assert.match(taskHeader(task("small", { cost: 0.09 }), 1000), /\$0\.090/);
+	assert.match(taskHeader(task("large", { cost: 12.5 }), 1000), /\$12\.50/);
+	assert.doesNotMatch(taskHeader(task("zero", { cost: 0 }), 1000), /\$/);
 });
 
 test("AgentsView renders the frame with the task list and the selected thread's tail, at width", () => {
@@ -255,7 +261,7 @@ test("AgentsView renders the frame with the task list and the selected thread's
 	const plain = lines.map(stripAnsi);
 	assert.equal(plain.length, 8);
 	assert.match(plain[0], /^╭─ ❀ Agents · this session · 1 active · 1 finished ─+ \[F Fullscreen\] \[× Close\]╮$/);
-	assert.match(plain[1], /▸ └ ◐ Subagent explore.*explore · running · gpt-5\.6-terra · 34k · \$0\.27 · 1m00s/);
+	assert.match(plain[1], /▸ └ ◐ Subagent explore.*explore · running · gpt-5\.6-terra · 34k · \$0\.270 · 1m00s/);
 	assert.match(plain[2], /line 3/, "the thread window follows the tail");
 	assert.match(plain[3], /line 4/);
 	assert.match(plain.join("\n"), /Subagent worker/, "the session's own finished task now stays listed as history");

package/tests/agents-widget.test.ts

@@ -1,8 +1,9 @@
 import assert from "node:assert/strict";
-import test from "node:test";
+import test, { after, before, type TestContext } 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 { CARD_STYLE, cardStyle, setCardStyle, type CardStyle } from "../lib/shell-card.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 
 // Gentle Agents widget: the card above the editor that shows what the
@@ -11,6 +12,42 @@ import { stripAnsi } from "../lib/terminal-theme.ts";
 
 const plainTheme = { fg: (_color: string, text: string) => text };
 
+// The card style defaults to float; these assertions pin the outlined (neon)
+// panels unless a test switches the style itself.
+const initialCardStyle = cardStyle();
+before(() => setCardStyle(CARD_STYLE.NEON));
+after(() => setCardStyle(initialCardStyle));
+
+function useCardStyle(t: TestContext, style: CardStyle): void {
+	const found = cardStyle();
+	t.after(() => setCardStyle(found));
+	setCardStyle(style);
+}
+
+const BG_OPEN = "\x1b[48;5;22m";
+const BG_CLOSE = "\x1b[49m";
+
+/** The same theme with a background, so the float style applies (without one panels keep the frame). */
+function withBackground<T extends object>(theme: T): T & { bg(color: string, text: string): string } {
+	return { ...theme, bg: (_color: string, text: string) => `${BG_OPEN}${text}${BG_CLOSE}` };
+}
+
+/** Float panel rows: a painted panel inside transparent one-column margins, between padding rows that keep the accent bar. */
+function assertFloatRows(lines: readonly string[], width: number): void {
+	for (const line of lines) {
+		assert.equal(visibleWidth(line), width, `"${stripAnsi(line)}" is not ${width} wide`);
+		assert.ok(line.startsWith(` ${BG_OPEN}`) && line.endsWith(`${BG_CLOSE} `), `painted inside the margins: ${JSON.stringify(line)}`);
+	}
+	const padding = ` ▎${" ".repeat(width - 3)} `;
+	assert.equal(stripAnsi(lines[0]!), padding, "a padding row with the accent bar sits above the header");
+	assert.equal(stripAnsi(lines.at(-1)!), padding, "a padding row with the accent bar replaces the bottom rule");
+}
+
+/** The text of a body row, without the neon side rails or the float accent bar. */
+function bodyText(row: string): string {
+	return stripAnsi(row).replace(/^ ?[│▎] /u, "").replace(/ ?│? ?$/u, "").trimEnd();
+}
+
 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 };
 }
@@ -59,8 +96,8 @@ test("renderAgentsCard draws columns for agent, task, and model · tokens · cos
 	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[1], /^│ ✓  sdd-explore  map footer data sources +claude-sonnet-5 · 34k · \$0\.270 · 25s │$/);
+	assert.match(plain[2], /^│ ◐  sdd-apply    write gentle-shell footer +claude-sonnet-5 · 12k · \$0\.090 · 41s │$/);
 	assert.match(plain[3], /^╰─+╯$/);
 	assert.deepEqual(renderAgentsCard([], plainTheme, 60, 0, { collapsed: false }), []);
 });
@@ -74,14 +111,14 @@ test("renderAgentsCard right-aligns model·effort, tokens, cost, and elapsed in
 	const [, rowA, rowB] = lines as [string, string, string];
 	assert.match(rowA, /34k/);
 	assert.match(rowB, /1\.2M/);
-	assert.match(rowA, /\$0\.27/);
+	assert.match(rowA, /\$0\.270/);
 	assert.match(rowB, /\$12\.50/);
 	// Each column has a fixed width, so a shorter value in one row (e.g. "34k"
 	// next to "1.2M") still ends at the exact same offset as the wider one.
 	const tokensEndA = rowA.indexOf("34k") + "34k".length;
 	const tokensEndB = rowB.indexOf("1.2M") + "1.2M".length;
 	assert.equal(tokensEndA, tokensEndB, "the tokens column ends at the same offset on every row");
-	const costEndA = rowA.indexOf("$0.27") + "$0.27".length;
+	const costEndA = rowA.indexOf("$0.270") + "$0.270".length;
 	const costEndB = rowB.indexOf("$12.50") + "$12.50".length;
 	assert.equal(costEndA, costEndB, "the cost column ends at the same offset on every row");
 	assert.equal(visibleWidth(rowA), visibleWidth(rowB));
@@ -118,13 +155,13 @@ test("renderAgentsCard keeps every task on one line, clipping long labels, and d
 	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 │$/);
+	assert.match(wide[1], /^│ ◐  sdd-explore  write the gentle shell foo… +claude-sonnet-5 · 34k · \$0\.270 · 4s │$/);
 	// Narrow cards degrade per column: task text first, then the model name,
 	// then tokens and cost. Elapsed is the one value the reader cannot rebuild
 	// from anything else on screen, so it is the last to go.
 	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 │$/, "the model name goes before tokens, cost and elapsed");
+	assert.match(narrow[1], /^│ ◐  sdd-explore +34k · \$0\.270 · 4s │$/, "the model name goes before tokens, cost and elapsed");
 });
 
 // gentle-shell#1143: one long model id used to flip the whole card to the
@@ -133,9 +170,9 @@ test("renderAgentsCard keeps tokens, cost and elapsed when a long model name no
 	const tasks = [task({ id: "a", model: "anthropic/claude-sonnet-4-5-20250929", tokens: 12_345, cost: 0.42, startedAt: 5_000 - 184_000 })];
 	const lines = renderAgentsCard(tasks, plainTheme, 46, 5_000, { collapsed: false }).map(stripAnsi);
 	assert.equal(lines.length, 3);
-	assert.match(lines[1], /^│ ◐  sdd-explore +12k · \$0\.42 · 3m04s │$/, "tokens, cost and elapsed survive; the model name is what gives way");
+	assert.match(lines[1], /^│ ◐  sdd-explore +12k · \$0\.420 · 3m04s │$/, "tokens, cost and elapsed survive; the model name is what gives way");
 	const tighter = renderAgentsCard(tasks, plainTheme, 34, 5_000, { collapsed: false }).map(stripAnsi);
-	assert.match(tighter[1], /^│ ◐  sdd-explore +\$0\.42 · 3m04s │$/, "then tokens go, then cost, elapsed last");
+	assert.match(tighter[1], /^│ ◐  sdd-explore +\$0\.420 · 3m04s │$/, "then tokens go, then cost, elapsed last");
 	const tightest = renderAgentsCard(tasks, plainTheme, 28, 5_000, { collapsed: false }).map(stripAnsi);
 	assert.match(tightest[1], /^│ ◐  sdd-explore +3m04s │$/, "elapsed is the last column standing");
 });
@@ -146,8 +183,8 @@ test("renderAgentsCard degrades every row of a mixed card together so columns st
 		task({ id: "b", agent: "writer", model: "openai/gpt-5", tokens: 900, cost: 0.01 }),
 	];
 	const lines = renderAgentsCard(tasks, plainTheme, 46, 5_000, { collapsed: false }).map(stripAnsi);
-	assert.match(lines[1], /12k · \$0\.42 · 4s │$/);
-	assert.match(lines[2], /900 · \$0\.01 · 4s │$/);
+	assert.match(lines[1], /12k · \$0\.420 · 4s │$/);
+	assert.match(lines[2], /900 · \$0\.010 · 4s │$/);
 	assert.equal(lines[1].indexOf("· 4s"), lines[2].indexOf("· 4s"), "elapsed stays in one column across rows");
 });
 
@@ -162,11 +199,11 @@ test("renderAgentsCard shows questions and failures in place of the task, and co
 	// The waiting row carries no tokens/cost of its own, but the failed row
 	// below it does, so those columns stay reserved (blank) rather than
 	// collapsing — the whole point of fixed columns over the old per-row join.
-	assert.match(plain[1], /^│ \?  sdd-explore  asked: Delete\? +claude-sonnet-5 · {5}· {7}· {5}2s │$/);
-	assert.match(plain[2], /^│ ✗  sdd-explore  pi exited with code… +claude-sonnet-5 · 34k · \$0\.27 · {5}1s │$/);
+	assert.match(plain[1], /^│ \?  sdd-explore  asked: Delete\? +claude-sonnet-5 · {5}· {8}· {5}2s │$/);
+	assert.match(plain[2], /^│ ✗  sdd-explore  pi exited with cod… +claude-sonnet-5 · 34k · \$0\.270 · {5}1s │$/);
 	// Queued fills only the elapsed column with the literal word; model,
 	// tokens, and cost stay blank rather than the row's text spilling past them.
-	assert.match(plain[3], /^│ ○  sdd-explore  map footer data sou… +· {5}· {7}· queued │$/);
+	assert.match(plain[3], /^│ ○  sdd-explore  map footer data so… +· {5}· {8}· 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 ╮$/);
@@ -181,7 +218,7 @@ test("usage outranks the model label at narrow widths without inventing unknown
 		const lines = renderAgentsCard([task({ agent: "worker", model: "openai/gpt-5", thinking: "high" })], plainTheme, width, 5000, { collapsed: false });
 		assert.equal(lines.length, 3);
 		assert.match(lines[1], /worker/);
-		assert.match(lines[1], /gpt-5 · high · 34k · \$0\.27 · 4s/, "wide enough for every column");
+		assert.match(lines[1], /gpt-5 · high · 34k · \$0\.270 · 4s/, "wide enough for every column");
 		for (const line of lines) assert.equal(visibleWidth(line), width);
 	}
 	for (const width of [32, 44]) {
@@ -227,3 +264,105 @@ test("renderAgentsCard caps the rows at maxRows, keeps active tasks ahead of fin
 	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");
 });
+
+test("renderAgentsCard in the float style spends its padding and separator rows from maxRows, so a capped card is exactly as tall as neon", (t) => {
+	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 theme = withBackground(plainTheme);
+	const neon = renderAgentsCard(tasks, theme, 80, 5000, { collapsed: false, maxRows: 4, viewKey: "alt+a" });
+	useCardStyle(t, CARD_STYLE.FLOAT);
+	const float = renderAgentsCard(tasks, theme, 80, 5000, { collapsed: false, maxRows: 4, viewKey: "alt+a" }).map(stripAnsi);
+	assert.equal(neon.length, 6, "neon: frame plus four rows");
+	assert.equal(float.length, neon.length, "float: padding, header, separator, two rows, padding");
+	assert.match(float[1]!, /6 active · 1 done/, "the title still counts every shown task");
+	assert.match(float[2]!, /^ ▎ +$/, "a blank separator row follows the header");
+	assert.match(float[3]!, /◐  sdd-explore  job 0/);
+	assert.match(float[4]!, /^ ▎ … 6 more · alt\+a to view +$/, "two more tasks fold into the overflow row");
+	for (const maxRows of [3, 4, 5, 7, 8, 9]) {
+		const capped = renderAgentsCard(tasks, theme, 80, 5000, { collapsed: false, maxRows });
+		assert.ok(capped.length <= maxRows + 2, `maxRows ${maxRows}: ${capped.length} rows exceed the neon cap`);
+	}
+	assert.match(stripAnsi(renderAgentsCard(tasks, theme, 80, 5000, { collapsed: false, maxRows: 8 }).at(-2)!), /… 2 more/, "seven tasks no longer fit eight rows once the padding and separator rows are spent");
+	assert.equal(renderAgentsCard(tasks, theme, 80, 5000, { collapsed: false, maxRows: 9 }).length, 11, "at the cap no row is hidden");
+});
+
+test("the minimum widget budget fits an overflow-only float body without changing neon", (t) => {
+	const maxRows = widgetRows(12);
+	assert.equal(maxRows, 3, "small terminals reach the three-row task budget");
+	const theme = withBackground(plainTheme);
+	for (const count of [1, 2, 6]) {
+		const tasks = Array.from({ length: count }, (_, index) => task({ id: `run${index}`, label: `job ${index}`, startedAt: 1000 + index }));
+		const options = { collapsed: false, maxRows, viewKey: "alt+a" };
+		setCardStyle(CARD_STYLE.NEON);
+		const neon = renderAgentsCard(tasks, plainTheme, 80, 5000, options);
+		assert.deepEqual(renderAgentsCard(tasks, theme, 80, 5000, options), neon, "neon stays byte-identical with background support");
+		useCardStyle(t, CARD_STYLE.FLOAT);
+		assert.deepEqual(renderAgentsCard(tasks, plainTheme, 80, 5000, options), neon, "missing-background fallback keeps neon rows");
+		setCardStyle(CARD_STYLE.NEON);
+		const neonNarrow = renderAgentsCard(tasks, theme, 9, 5000, options);
+		setCardStyle(CARD_STYLE.FLOAT);
+		assert.deepEqual(renderAgentsCard(tasks, theme, 9, 5000, options), neonNarrow, "narrow fallback keeps neon rows");
+		const rows = renderAgentsCard(tasks, theme, 80, 5000, options);
+		assert.equal(rows.length, maxRows + 2, `${count} tasks must fit five total float rows`);
+		assertFloatRows(rows, 80);
+		assert.match(stripAnsi(rows[2]!), /^ ▎ +$/, "separator stays intact");
+		if (count === 1) assert.match(stripAnsi(rows[3]!), /job 0/, "a single task fits directly");
+		else assert.match(stripAnsi(rows[3]!), new RegExp(`^ ▎ … ${count} more · alt\\+a to view +$`), "the only body row truthfully counts every hidden task");
+		assert.equal(renderAgentsCard(tasks, theme, 80, 5000, { ...options, collapsed: true }).length, maxRows + 2, "collapsed cards keep one task and fit");
+	}
+});
+
+test("float row budgets still prioritize a question when a task and overflow both fit", (t) => {
+	useCardStyle(t, CARD_STYLE.FLOAT);
+	const tasks = [
+		task({ id: "first", label: "running first", startedAt: 1000 }),
+		task({ id: "second", label: "running second", startedAt: 2000 }),
+		task({ id: "question", status: TASK_STATUS.WAITING, lastStep: "asked: Delete?", startedAt: 3000 }),
+	];
+	const rows = renderAgentsCard(tasks, withBackground(plainTheme), 80, 5000, { collapsed: false, maxRows: 4, viewKey: "alt+a" });
+	assert.equal(rows.length, 6);
+	assert.match(stripAnsi(rows[3]!), /^ ▎ \?  sdd-explore  asked: Delete\?/);
+	assert.match(stripAnsi(rows[4]!), /^ ▎ … 2 more · alt\+a to view +$/);
+});
+
+test("renderAgentsCard formats subagent cost with formatCost (three decimals below $1, two at or above $1)", () => {
+	const tasks = [
+		task({ id: "small", agent: "scout", cost: 0.09, tokens: 1000, startedAt: 1000, endedAt: 2000 }),
+		task({ id: "large", agent: "builder", cost: 12.5, tokens: 50000, startedAt: 1000, endedAt: 5000 }),
+	];
+	const card = renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false });
+	assert.ok(card.some((line) => line.includes("$0.090")), "cost below $1 shows 3 decimals");
+	assert.ok(card.some((line) => line.includes("$12.50")), "cost at or above $1 shows 2 decimals");
+});
+
+test("renderAgentsCard in the float style is a float panel two rows taller than neon with unclipped columns", (t) => {
+	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 theme = withBackground(plainTheme);
+	for (const options of [{ collapsed: false }, { collapsed: true, collapseKey: "ctrl+a" }, { collapsed: false, maxRows: 1, viewKey: "ctrl+v" }]) {
+		const neon = renderAgentsCard(tasks, theme, 84, 85_000, options);
+		useCardStyle(t, CARD_STYLE.FLOAT);
+		const float = renderAgentsCard(tasks, theme, 84, 85_000, options);
+		setCardStyle(CARD_STYLE.NEON);
+		assert.equal(float.length, neon.length + 2, "the top padding and separator rows add two rows");
+		assert.match(stripAnsi(float[1]!), /^ ▎ ❀ Agents  1 active · 1 done +\S.*\S {3}$/, "header on row 1, hint right-aligned");
+		assert.match(stripAnsi(float[2]!), /^ ▎ +$/, "a blank separator row follows the header");
+		assertFloatRows(float, 84);
+		for (const [index, row] of float.slice(3, -1).entries()) {
+			assert.match(stripAnsi(row), /^ ▎ \S/u);
+			if (bodyText(row).startsWith("…")) continue;
+			// Task columns fit the float body, so the right-aligned time is never clipped.
+			const tail = bodyText(neon[index + 1]!).split(" ").at(-1)!;
+			assert.ok(bodyText(row).endsWith(tail), `"${stripAnsi(row)}" keeps "${tail}"`);
+			assert.match(stripAnsi(row), /\S {3}$/u, "the time ends where the float body ends");
+		}
+	}
+	useCardStyle(t, CARD_STYLE.FLOAT);
+	const tagged = withBackground({ fg: (color: string, text: string) => `<${color}>${text}</${color}>` });
+	const [, header] = renderAgentsCard([task({ status: TASK_STATUS.WAITING })], tagged, 120, 5000, { collapsed: true, collapseKey: "ctrl+a" });
+	assert.match(stripAnsi(header!), /^ <warning>▎<\/warning> <warning>❀ Agents<\/warning>  <muted>1 waiting<\/muted> +<muted>ctrl\+a expand<\/muted> {3}$/);
+});

package/tests/append-system-prompt-route.test.ts

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import test, { after, before } from "node:test";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import gentleTodo from "../extensions/gentle-todo.ts";
+
+// gentle-shell#1485: pi-claude-bridge forwards only the structured
+// systemPromptOptions parts of before_agent_start (contextFiles, skills,
+// customPrompt, appendSystemPrompt) after Claude Code's own preset, so a
+// handler-returned replacement systemPrompt never reaches the model on that
+// provider. These tests exercise both extensions against one shared
+// systemPromptOptions object, the same object every before_agent_start
+// handler observes within a single pi emission (packages/coding-agent
+// extensions/runner.js emitBeforeAgentStart: one `currentOptions` per call).
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+
+let fixtureCwd: string;
+let fixtureRoot: string | undefined;
+const fixtureEnvironment: NodeJS.ProcessEnv = {};
+const previousEnvironment = new Map<string, string | undefined>();
+before(async () => {
+	const root = await mkdtemp(join(tmpdir(), "gentle-pi-append-route-"));
+	fixtureRoot = root;
+	fixtureCwd = join(root, "project");
+	const home = join(root, "home");
+	for (const directory of [fixtureCwd, home]) await mkdir(directory);
+	Object.assign(fixtureEnvironment, {
+		HOME: home, USERPROFILE: home,
+		GENTLE_PI_CONFIG_HOME: join(home, "config"),
+		GENTLE_PI_AGENT_HOME: join(home, "agents"),
+		PI_CODING_AGENT_DIR: join(home, "pi"),
+		XDG_CONFIG_HOME: join(home, "xdg"),
+	});
+	for (const [key, value] of Object.entries(fixtureEnvironment)) {
+		previousEnvironment.set(key, process.env[key]);
+		process.env[key] = value;
+	}
+});
+after(async () => {
+	for (const [key, value] of previousEnvironment) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	if (fixtureRoot !== undefined) await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+function gentleAiHandlers(processEnv: NodeJS.ProcessEnv = {}): Map<string, Handler> {
+	const handlers = new Map<string, Handler>();
+	const pi = {
+		on(name: string, handler: Handler) {
+			handlers.set(name, handler);
+		},
+		events: { emit() {} },
+		registerCommand() {},
+		registerTool() {},
+	} as unknown as ExtensionAPI;
+	createGentleAiExtension({
+		nativeReviewCli: null,
+		processEnv: { ...fixtureEnvironment, GENTLE_PI_AGENTS_CHILD: "0", ...processEnv, GENTLE_AI_TELEMETRY: "0" },
+		resolveTelemetryTriggerBinary: () => join(fixtureCwd, "never-executed"),
+		telemetryTriggerSpawn: () => assert.fail("Route fixtures must not spawn telemetry"),
+	})(pi);
+	return handlers;
+}
+
+function gentleTodoHandlers(): { handlers: Map<string, Handler[]>; tools: Map<string, { execute: (...args: unknown[]) => Promise<unknown> }> } {
+	const handlers = new Map<string, Handler[]>();
+	const tools = new Map<string, { execute: (...args: unknown[]) => Promise<unknown>; name: string }>();
+	const pi = {
+		on(event: string, handler: Handler) {
+			handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+		},
+		registerTool(tool: { execute: (...args: unknown[]) => Promise<unknown>; name: string }) {
+			tools.set(tool.name, tool);
+		},
+		registerShortcut() {},
+	} as unknown as ExtensionAPI;
+	gentleTodo(pi, {});
+	return { handlers, tools };
+}
+
+function ctx(): ExtensionContext {
+	return {
+		cwd: fixtureCwd,
+		hasUI: true,
+		ui: { notify() {}, setWidget() {} },
+		sessionManager: { getSessionId: () => "append-route-session", getBranch: () => [] },
+	} as unknown as ExtensionContext;
+}
+
+test("both extensions land their block in appendSystemPrompt on one shared options object, and neither returns a replacement systemPrompt", async () => {
+	const aiHandlers = gentleAiHandlers();
+	const { handlers: todoHandlers, tools } = gentleTodoHandlers();
+	const session = ctx();
+
+	for (const handler of todoHandlers.get("session_start") ?? []) await handler({}, session);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, session);
+	for (const handler of todoHandlers.get("tool_execution_end") ?? []) await handler({ toolName: "todo" }, session);
+
+	const event = { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
+
+	// Every handler registered for before_agent_start observes the same
+	// systemPromptOptions object within one emission, exactly as pi's runner
+	// does for the real event.
+	const aiResult = await aiHandlers.get("before_agent_start")!(event, session);
+	let todoResult: unknown;
+	for (const handler of todoHandlers.get("before_agent_start") ?? []) todoResult = await handler(event, session);
+
+	assert.equal(aiResult, undefined, "gentle-ai must not return a replacement systemPrompt");
+	assert.equal(todoResult, undefined, "gentle-todo must not return a replacement systemPrompt");
+
+	const appended = event.systemPromptOptions.appendSystemPrompt;
+	assert.match(appended, /el Gentleman Identity and Harness/);
+	assert.match(appended, /## Todo list/);
+	assert.match(appended, /1\. \[pending\] Fix the bug/);
+	assert.ok(
+		appended.indexOf("el Gentleman Identity and Harness") < appended.indexOf("## Todo list"),
+		"gentle-ai's block must precede gentle-todo's, matching handler registration order",
+	);
+});
+
+test("re-running both handlers on the same already-populated options object does not duplicate either block", async () => {
+	const aiHandlers = gentleAiHandlers();
+	const { handlers: todoHandlers, tools } = gentleTodoHandlers();
+	const session = ctx();
+
+	for (const handler of todoHandlers.get("session_start") ?? []) await handler({}, session);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, session);
+	for (const handler of todoHandlers.get("tool_execution_end") ?? []) await handler({ toolName: "todo" }, session);
+
+	const event = { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
+	await aiHandlers.get("before_agent_start")!(event, session);
+	const gentleAiOccurrencesAfterFirstRun = event.systemPromptOptions.appendSystemPrompt.split("el Gentleman Identity and Harness").length - 1;
+	assert.equal(gentleAiOccurrencesAfterFirstRun, 1);
+
+	// A defensive re-run of gentle-ai's own handler against an options object
+	// that already carries its exact block must not append it again.
+	await aiHandlers.get("before_agent_start")!(event, session);
+	const gentleAiOccurrencesAfterSecondRun = event.systemPromptOptions.appendSystemPrompt.split("el Gentleman Identity and Harness").length - 1;
+	assert.equal(gentleAiOccurrencesAfterSecondRun, 1, "a second gentle-ai run on the same options object must not duplicate the harness");
+});
+
+for (const scenario of ["child", "named-agent"] as const) {
+	test(`${scenario} start leaves shared prompt options unchanged and returns no replacement`, async () => {
+		const handlers = gentleAiHandlers(scenario === "child" ? { GENTLE_PI_AGENTS_CHILD: "1" } : {});
+		const event = {
+			systemPrompt: "base",
+			systemPromptOptions: { appendSystemPrompt: "Existing provider section" },
+			...(scenario === "named-agent" ? { agentName: "gentle-ai-worker" } : {}),
+		};
+		const result = await handlers.get("before_agent_start")!(event, ctx());
+		assert.equal(result, undefined, "excluded sessions must not return a replacement system prompt");
+		assert.equal(event.systemPromptOptions.appendSystemPrompt, "Existing provider section");
+		assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /el Gentleman Identity and Harness/);
+	});
+}

package/tests/append-system-prompt.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { appendSystemPromptOnce } from "../lib/append-system-prompt.ts";
+
+// gentle-shell#1485: pi-claude-bridge forwards only the structured
+// systemPromptOptions parts of before_agent_start, so extensions must mutate
+// options.appendSystemPrompt instead of returning a replacement systemPrompt.
+
+test("appends to an empty appendSystemPrompt, stripped of a leading blank line", () => {
+	const options = { appendSystemPrompt: "" };
+	appendSystemPromptOnce(options, "\n\nHarness block");
+	assert.equal(options.appendSystemPrompt, "Harness block");
+});
+
+test("appends after existing content with a blank-line separator", () => {
+	const options = { appendSystemPrompt: "user APPEND_SYSTEM.md content" };
+	appendSystemPromptOnce(options, "\n\nHarness block");
+	assert.equal(options.appendSystemPrompt, "user APPEND_SYSTEM.md content\n\nHarness block");
+});
+
+test("is idempotent: the same text is never appended twice to the same options object", () => {
+	const options = { appendSystemPrompt: "" };
+	appendSystemPromptOnce(options, "\n\nHarness block");
+	appendSystemPromptOnce(options, "\n\nHarness block");
+	assert.equal(options.appendSystemPrompt, "Harness block");
+	assert.equal(options.appendSystemPrompt.split("Harness block").length - 1, 1);
+});
+
+test("two different callers accumulate without erasing each other", () => {
+	const options = { appendSystemPrompt: "" };
+	appendSystemPromptOnce(options, "\n\nGentle AI harness");
+	appendSystemPromptOnce(options, "\n\nTodo list block");
+	assert.equal(options.appendSystemPrompt, "Gentle AI harness\n\nTodo list block");
+});
+
+test("empty or blank text is a no-op", () => {
+	const options = { appendSystemPrompt: "kept" };
+	appendSystemPromptOnce(options, "");
+	appendSystemPromptOnce(options, "\n\n");
+	assert.equal(options.appendSystemPrompt, "kept");
+});
+
+test("a missing options object never throws", () => {
+	assert.doesNotThrow(() => appendSystemPromptOnce(undefined, "\n\nHarness block"));
+	assert.doesNotThrow(() => appendSystemPromptOnce(null, "\n\nHarness block"));
+});