gentle-pi 4.0.0 → 4.1.0

package/tests/gentle-todo.test.ts

@@ -1,10 +1,12 @@
 import assert from "node:assert/strict";
 import test, { after, before } from "node:test";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
+import { convertToLlm, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
 import gentleTodo, { todoCollapseKey, todoEnabled } from "../extensions/gentle-todo.ts";
 import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
 import { stripAnsi } from "../lib/terminal-theme.ts";
+import { sidebarState } from "../lib/shell-sidebar.ts";
+import { installSidebar } from "../lib/shell-sidebar-layout.ts";
 
 // The card style defaults to float; these assertions pin the outlined (neon)
 // panels unless a test switches the style itself.
@@ -76,6 +78,87 @@ function fakeContext(branch: unknown[] = [], hasUI = true) {
 	return { ctx, widgets, widget, widgetComponent };
 }
 
+test("long Todo widgets stay bounded, scroll, resize and keep their collapse control in mobile and sidebar", async (t) => {
+	for (const style of [CARD_STYLE.NEON, CARD_STYLE.FLOAT]) {
+		setCardStyle(style);
+		const { pi, tools, fire, shortcuts } = fakePi();
+		gentleTodo(pi, {});
+		const { ctx, widgets } = fakeContext();
+		await fire("session_start", ctx);
+		const title = "long active title ".repeat(150);
+		const note = "description ".repeat(150);
+		const result = await tools.get("todo")!.execute("write", { action: "write", tasks: [{ title, note, status: "in_progress" }, { title: "LAST TASK" }] }, undefined, undefined, ctx);
+		await fire("tool_execution_end", ctx, { toolName: "todo" });
+		const tui = { requestRender() {}, terminal: { rows: 30, columns: 40 } };
+		const theme = { ...plainTheme, bg: (_color: string, text: string) => `\x1b[48;5;22m${text}\x1b[49m` };
+		const bottom = widgets.get("gentle-todo")!(tui, theme);
+		const rail = sidebarState(tui as never).parts.get("todo")!;
+		for (const component of [bottom, rail]) {
+			const before = component.render(40).map(stripAnsi);
+			assert.ok(before.length <= 10, "card uses at most one third of terminal height");
+			const header = style === CARD_STYLE.FLOAT ? 1 : 0;
+			assert.match(before[header]!, /Todos ▾/);
+			assert.equal(component.handleMouse?.({ type: "wheel", button: "none", wheelDelta: 10000, x: 5, y: header + 2, screenX: 5, screenY: 5, width: 40, height: before.length, shift: false, alt: false, ctrl: false })?.handled, true);
+			const after = component.render(40).map(stripAnsi);
+			assert.match(after[header]!, /Todos ▾/);
+			assert.match(after.join("\n"), /LAST TASK/, "all details remain reachable by scrolling");
+			assert.notDeepEqual(after, before);
+		}
+		tui.terminal.rows = 24;
+		assert.ok(bottom.render(40).length <= 8, "height responds to resize");
+		await shortcuts.get("ctrl+shift+t")!.handler(ctx);
+		const collapsed = bottom.render(40).map(stripAnsi);
+		assert.ok(collapsed.length <= (style === CARD_STYLE.FLOAT ? 6 : 4));
+		assert.match(collapsed.join("\n"), /long active title/);
+		assert.match(collapsed.join("\n"), /…/);
+		assert.equal((result.details.gentleTodo as { tasks: { title: string; note: string }[] }).tasks[0].title, title.trim());
+		assert.equal((result.details.gentleTodo as { tasks: { title: string; note: string }[] }).tasks[0].note, note.trim());
+		await shortcuts.get("ctrl+shift+t")!.handler(ctx);
+		await shortcuts.get("ctrl+shift+down")!.handler(ctx);
+		assert.notDeepEqual(bottom.render(40), collapsed, "keyboard scrolling is available without mouse");
+	}
+	t.after(() => setCardStyle(CARD_STYLE.NEON));
+});
+
+test("Todo keyboard scrolling targets the visible card after a cached sidebar breakpoint round-trip", async (t) => {
+	const node = Symbol.for("@earendil-works/pi-tui/layout-node");
+	for (const style of [CARD_STYLE.NEON, CARD_STYLE.FLOAT]) {
+		setCardStyle(style);
+		const { pi, tools, fire, shortcuts } = fakePi();
+		gentleTodo(pi, {});
+		const { ctx, widgets } = fakeContext();
+		await fire("session_start", ctx);
+		await tools.get("todo")!.execute("write", { action: "write", tasks: [{ title: Array.from({ length: 100 }, (_, i) => `TITLE${i}`).join(" "), status: "in_progress" }] }, undefined, undefined, ctx);
+		await fire("tool_execution_end", ctx, { toolName: "todo" });
+		const root = { render: () => [], invalidate() {}, [node]: () => ({ type: "vstack", entries: [] }) };
+		const tui = { mode: "fullscreen", terminal: { rows: 30, columns: 160 }, layoutRoot: root, requestRender() {} };
+		const theme = { ...plainTheme, bold: (text: string) => text, bg: (_color: string, text: string) => `\x1b[48;5;22m${text}\x1b[49m` };
+		const bottom = widgets.get("gentle-todo")!(tui, theme);
+		const dispose = installSidebar(tui as unknown as TUI, theme);
+		try {
+			const railLines = () => {
+				const layout = root[node]() as unknown as { entries: { component: Component }[] };
+				return layout.entries[1]!.component.render(50).map(stripAnsi);
+			};
+			railLines();
+			tui.terminal.columns = 40;
+			root[node]();
+			bottom.render(40);
+			tui.terminal.columns = 160;
+			const before = railLines();
+			await shortcuts.get("ctrl+shift+down")!.handler(ctx);
+			const after = railLines();
+			assert.notDeepEqual(after, before, "DOWN changes the visible cached rail, not the hidden bottom widget");
+			assert.match(after.join("\n"), /↑↓ 4–/);
+			await shortcuts.get("ctrl+shift+up")!.handler(ctx);
+			assert.deepEqual(railLines(), before, "UP restores the expanded viewport");
+		} finally {
+			dispose();
+		}
+	}
+	t.after(() => setCardStyle(CARD_STYLE.NEON));
+});
+
 test("todoEnabled and todoCollapseKey read their environment flags", () => {
 	assert.equal(todoEnabled({}), true);
 	assert.equal(todoEnabled({ GENTLE_PI_TODO: "0" }), false);
@@ -199,6 +282,138 @@ test("in the float style the Todos header sits on row 1 below the top padding, a
 	assert.match(stripAnsi(component.render(70)[1]!), /^ ▎ ❀ Todos ▸ Expand  0 of 2 /);
 });
 
+const REMINDER = "The todo plan has not been reviewed during several tool-use turns. Check whether it still matches the work performed and update tasks where needed. Do not mark work done without verification.";
+
+function toolTurn(toolName = "read") {
+	return { message: { role: "assistant", content: [{ type: "toolCall", id: "call", name: toolName, arguments: {} }] }, toolResults: [] };
+}
+
+async function contextReminder(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext) {
+	const messages = [{ role: "user", content: "Keep working", timestamp: 1 }];
+	const result = await fire("context", ctx, { messages }) as { messages: Array<{ role: string; content: unknown }> } | undefined;
+	assert.deepEqual(messages, [{ role: "user", content: "Keep working", timestamp: 1 }], "request-local injection must not mutate the input transcript");
+	return result;
+}
+
+async function workTurns(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext, count: number) {
+	for (let index = 0; index < count; index++) {
+		assert.equal(await fire("turn_end", ctx, toolTurn()), undefined, "a reminder must never request continuation or persist entries");
+	}
+}
+
+test("runtime reminder arrives after four tool-use turns, only once, without changing todo state", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext([], false);
+	await fire("session_start", ctx);
+	const tool = tools.get("todo")!;
+	const written = await tool.execute("write", { action: "write", tasks: [{ title: "Implement" }] }, undefined, undefined, ctx);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	await workTurns(fire, ctx, 3);
+	assert.equal(await contextReminder(fire, ctx), undefined);
+	await workTurns(fire, ctx, 1);
+	const result = await contextReminder(fire, ctx);
+	assert.ok(result, "the next model request must carry a reminder within the same run");
+	assert.equal(result.messages.length, 2);
+	assert.deepEqual(result.messages[0], { role: "user", content: "Keep working", timestamp: 1 });
+	assert.deepEqual(result.messages[1], { role: "custom", customType: "gentle-todo-reminder", content: REMINDER, display: false, timestamp: (result.messages[1] as { timestamp?: number }).timestamp });
+	const converted = convertToLlm(result.messages as Parameters<typeof convertToLlm>[0]);
+	assert.deepEqual(converted[1], { role: "user", content: [{ type: "text", text: REMINDER }], timestamp: (result.messages[1] as { timestamp?: number }).timestamp }, "Pi forwards the reminder as provider-compatible text");
+	await workTurns(fire, ctx, 4);
+	assert.equal(await contextReminder(fire, ctx), undefined, "no repeated nagging without a todo write");
+	const listed = await tool.execute("list", { action: "list" }, undefined, undefined, ctx);
+	assert.deepEqual(listed.details.gentleTodo, written.details.gentleTodo, "a nudge does not update tasks, freshness or IDs");
+});
+
+test("a successful todo update resets and rearms the runtime reminder", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	await fire("session_start", ctx);
+	const tool = tools.get("todo")!;
+	await tool.execute("write", { action: "write", tasks: [{ title: "Implement" }] }, undefined, undefined, ctx);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	await workTurns(fire, ctx, 4);
+	assert.ok(await contextReminder(fire, ctx));
+	await tool.execute("update", { action: "update", id: 1, status: "in_progress" }, undefined, undefined, ctx);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	await workTurns(fire, ctx, 3);
+	assert.equal(await contextReminder(fire, ctx), undefined);
+	await workTurns(fire, ctx, 1);
+	assert.ok(await contextReminder(fire, ctx));
+});
+
+test("list and rejected todo writes do not reset or rearm runtime reminders", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	await fire("session_start", ctx);
+	const tool = tools.get("todo")!;
+	const written = await tool.execute("write", { action: "write", tasks: [{ title: "Implement" }] }, undefined, undefined, ctx);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	await workTurns(fire, ctx, 2);
+	const listed = await tool.execute("list", { action: "list" }, undefined, undefined, ctx);
+	assert.deepEqual(listed.details.gentleTodo, written.details.gentleTodo);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	const rejected = await tool.execute("bad", { action: "update", id: 999, status: "done" }, undefined, undefined, ctx);
+	assert.equal(rejected.content[0].text, "Error: no task #999");
+	assert.equal(rejected.details.error, "no task #999");
+	assert.deepEqual(rejected.details.gentleTodo, written.details.gentleTodo);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	assert.ok(await contextReminder(fire, ctx));
+	await tool.execute("list-again", { action: "list" }, undefined, undefined, ctx);
+	await tool.execute("bad-again", { action: "update", id: 999, status: "done" }, undefined, undefined, ctx);
+	await workTurns(fire, ctx, 4);
+	assert.equal(await contextReminder(fire, ctx), undefined);
+});
+
+test("runtime reminders skip empty, blocked-only and finished plans and non-tool turns", async () => {
+	for (const tasks of [[], [{ title: "Wait", status: "blocked", note: "waiting for approval" }], [{ title: "Done", status: "done" }, { title: "Obsolete", status: "dropped" }]]) {
+		const { pi, tools, fire } = fakePi();
+		gentleTodo(pi, {});
+		const { ctx } = fakeContext();
+		await fire("session_start", ctx);
+		await tools.get("todo")!.execute("write", { action: "write", tasks }, undefined, undefined, ctx);
+		await fire("turn_end", ctx, toolTurn("todo"));
+		await workTurns(fire, ctx, 8);
+		assert.equal(await contextReminder(fire, ctx), undefined);
+	}
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("write", { action: "write", tasks: [{ title: "Implement" }] }, undefined, undefined, ctx);
+	await fire("turn_end", ctx, toolTurn("todo"));
+	for (let index = 0; index < 8; index++) await fire("turn_end", ctx, { message: { role: "assistant", content: [{ type: "text", text: "Thinking" }] }, toolResults: [] });
+	assert.equal(await contextReminder(fire, ctx), undefined);
+	await workTurns(fire, ctx, 4);
+	await tools.get("todo")!.execute("clear", { action: "clear" }, undefined, undefined, ctx);
+	assert.equal(await contextReminder(fire, ctx), undefined, "clearing the plan invalidates a pending reminder");
+});
+
+test("runtime reminder tracking is isolated by session and reset on session load", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const first = fakeContext();
+	const second = fakeContext();
+	second.ctx.sessionManager = { ...second.ctx.sessionManager, getSessionId: () => "s2" } as ExtensionContext["sessionManager"];
+	await fire("session_start", first.ctx);
+	await fire("session_start", second.ctx);
+	const tool = tools.get("todo")!;
+	const written = await tool.execute("write", { action: "write", tasks: [{ title: "Implement" }] }, undefined, undefined, first.ctx);
+	await fire("turn_end", first.ctx, toolTurn("todo"));
+	await workTurns(fire, first.ctx, 4);
+	await workTurns(fire, second.ctx, 4);
+	assert.equal(await contextReminder(fire, second.ctx), undefined, "another session cannot inherit the plan or reminder");
+	assert.ok(await contextReminder(fire, first.ctx));
+	await fire("session_shutdown", first.ctx);
+	const reloaded = fakeContext([{ type: "message", message: { role: "toolResult", toolName: "todo", details: written.details } }]);
+	await fire("session_start", reloaded.ctx);
+	assert.equal(await contextReminder(fire, reloaded.ctx), undefined, "reloaded plans start with a fresh reminder counter");
+	await workTurns(fire, reloaded.ctx, 4);
+	assert.ok(await contextReminder(fire, reloaded.ctx), "reload does not inherit a consumed reminder");
+});
+
 function promptEvent(): { systemPrompt: string; systemPromptOptions: { appendSystemPrompt: string } } {
 	return { systemPrompt: "base", systemPromptOptions: { appendSystemPrompt: "" } };
 }
@@ -309,3 +524,39 @@ test("session_start drops a list that was already finished, so a reload never sh
 	const prompt = (await fire("before_agent_start", ctx, { systemPrompt: "base" })) as { systemPrompt: string } | undefined;
 	assert.equal(prompt, undefined, "and nothing is injected into the prompt");
 });
+
+test("the todo tool offers blocked and dropped in its schema and guidelines", () => {
+	const { pi, tools } = fakePi();
+	gentleTodo(pi, {});
+	const tool = tools.get("todo") as unknown as { parameters: { properties: Record<string, { enum?: string[]; items?: { properties: Record<string, { enum?: string[]; description?: string }> } }> }; promptGuidelines: string[] };
+	const statuses = ["pending", "in_progress", "blocked", "done", "dropped"];
+	assert.deepEqual(tool.parameters.properties.status.enum, statuses);
+	assert.deepEqual(tool.parameters.properties.tasks.items!.properties.status.enum, statuses);
+	assert.match(tool.parameters.properties.tasks.items!.properties.note.description!, /required for blocked/);
+	assert.ok(tool.promptGuidelines.some((line) => /blocked with a note naming what it waits for/.test(line)));
+	assert.ok(tool.promptGuidelines.some((line) => /dropped/.test(line) && /obsolete/.test(line)));
+});
+
+test("a list left with only dropped tasks open finishes and clears; a blocked-only list stays in the prompt without going stale", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widget } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "A", status: "done" }, { title: "Old plan", status: "dropped" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	await fire("agent_end", ctx);
+	assert.match(widget()![0], /Todos ▾ Collapse · 1 of 1/);
+	await fire("before_agent_start", ctx, promptEvent());
+	assert.equal(widget(), undefined, "a done-and-dropped list clears at the next turn");
+
+	await tools.get("todo")!.execute("c2", { action: "write", tasks: [{ title: "A", status: "done" }, { title: "Deploy", status: "blocked", note: "waiting for an admin" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	for (let turn = 0; turn < 4; turn++) {
+		await fire("agent_end", ctx);
+		const event = promptEvent();
+		await fire("before_agent_start", ctx, event);
+		assert.match(event.systemPromptOptions.appendSystemPrompt, /2\. \[blocked\] Deploy — waiting for an admin/);
+		assert.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /stale/);
+	}
+	assert.match(widget()![2], /⊘ Deploy · waiting for an admin/);
+});

package/tests/herdr-activity.test.ts

@@ -0,0 +1,243 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { activitySummary, ActivityPublisher, createActivityColumns, metadataArgs, metadataTransport } from "../lib/herdr-activity.ts";
+
+const tasks = [{ title: "Revisar integración Herdr", status: "in_progress" }];
+const project = (title: string, columns = 30) => activitySummary([{ title, status: "in_progress" }], columns);
+
+test("summary contains only the icon and sanitized active Todo title", () => {
+	assert.equal(activitySummary(tasks, 30), "◐ Revisar integración Herdr");
+	assert.equal(project("\x1b[31munsafe\x1b[0m\n\u202e title"), "◐ unsafe title");
+	assert.equal(project("\x1b]8;;https://private\x07safe\x1b]8;;\x07"), "◐ safe");
+	assert.equal(project("\x1b_private\x1b\\safe"), "◐ safe");
+});
+
+test("absent, completed, malformed or sanitized-empty active titles clear the summary", () => {
+	for (const entries of [null, {}, [], [{ title: "pending", status: "pending" }],
+		[{ title: "done", status: "completed" }], [{ title: 42, status: "in_progress" }],
+		[{ title: "\x1b[31m\x1b[0m\n\u202e", status: "in_progress" }], [null]]) {
+		assert.equal(activitySummary(entries), null);
+	}
+});
+
+test("two rows preserve words and all fitting text; only the last row truncates", () => {
+	assert.equal(project("one two three four", 12), "◐ one two\n  three four");
+	const long = project("one two three four five six", 12)!;
+	assert.equal(long, "◐ one two\n  three…");
+	assert.equal(project("abcdefghijklmnop", 10), "◐ abcdefgh\n  ijklmnop");
+	assert.equal(project("abcdefghijk", 3), "◐ a\n  …");
+	assert.equal(project("abc", 2), "◐…");
+});
+
+test("Unicode uses display cells and keeps accents, CJK and emoji graphemes intact", () => {
+	for (const title of ["café a\u0301 mañana", "漢字漢字漢字漢字", "👩🏽‍💻 👨‍👩‍👧‍👦 😀", "🇪🇸🇯🇵🇫🇷"]) {
+		const text = project(title, 10)!;
+		assert.ok(text.split("\n").length <= 2);
+		for (const row of text.split("\n")) assert.ok(visibleWidth(row) <= 10, row);
+		assert.equal(text.replace(/^◐ /, "").replace("\n  ", "").replace(/ /g, ""), title.replace(/ /g, ""));
+	}
+	assert.equal(project("👩🏽‍💻".repeat(10), 8), "◐ 👩🏽‍💻👩🏽‍💻👩🏽‍💻\n  👩🏽‍💻👩🏽‍💻…");
+});
+
+test("tokens fit 80 Unicode scalars before wrapping, including prefixes and ellipsis", () => {
+	assert.equal(project("x".repeat(100), 105), `◐ ${"x".repeat(78)}\n  ${"x".repeat(22)}`);
+	assert.equal(project("😀".repeat(50), 105), `◐ ${"😀".repeat(50)}`, "count scalars, not UTF-16 units");
+	assert.equal(project("x".repeat(156), 512), `◐ ${"x".repeat(78)}\n  ${"x".repeat(78)}`);
+	assert.equal(project("x".repeat(157), 512), `◐ ${"x".repeat(78)}\n  ${"x".repeat(77)}…`);
+	assert.equal(project("😀".repeat(56) + "x".repeat(26), 200),
+		`◐ ${"😀".repeat(56)}${"x".repeat(22)}\n  xxxx`, "private LF is not part of the 256-byte token budget");
+	const combining = "a\u0301\u0302".repeat(40);
+	assert.equal(project(combining, 105), `◐ ${"a\u0301\u0302".repeat(26)}\n  ${"a\u0301\u0302".repeat(14)}`);
+	for (const title of ["x".repeat(200), combining.repeat(2), "😀".repeat(100),
+		"a" + "\u0301".repeat(80), "👩🏽‍💻".repeat(100)]) {
+		const text = project(title, 105)!;
+		assert.ok(text.endsWith("…"), "actual capacity overflow needs ellipsis");
+		assert.ok(text.split("\n").length <= 2);
+		for (const row of text.split("\n")) {
+			assert.ok(Array.from(row).length <= 80, "each raw token includes its prefix and ellipsis");
+			assert.ok(visibleWidth(row) <= 105);
+		}
+		assert.ok(Buffer.byteLength(text.replace("\n", "")) <= 256);
+	}
+});
+
+test("word preference yields to a hard break only to avoid unnecessary ellipsis", () => {
+	assert.equal(project("a bcdefghijkl", 10), "◐ a bcdefg\n  hijkl");
+	assert.equal(project("a 漢字漢字漢", 10), "◐ a 漢字漢\n  字漢");
+	assert.equal(project("one two three four", 12), "◐ one two\n  three four");
+	assert.equal(project(`a ${"b".repeat(100)}`, 80), `◐ a ${"b".repeat(76)}\n  ${"b".repeat(24)}`);
+	const combined = project(`a ${"😀".repeat(70)}`, 105)!;
+	assert.ok(combined.endsWith("…"), "hard breaks cannot bypass the shared byte budget");
+	assert.ok(Buffer.byteLength(combined.replace("\n", "")) <= 256);
+	for (const row of combined.split("\n")) assert.ok(Array.from(row).length <= 80);
+});
+
+test("sanitization removes Arabic Letter Mark without removing emoji ZWJ", () => {
+	assert.equal(project("abc\u061c123"), "◐ abc 123");
+	assert.equal(project("👩🏽‍💻\u061c ok"), "◐ 👩🏽‍💻 ok");
+});
+
+test("UTF-8 budget covers both tokens including prefixes and ellipsis", () => {
+	for (const title of ["😀".repeat(500), "👩🏽‍💻".repeat(500), "a" + "\u0301".repeat(10000), "x".repeat(10000)]) {
+		const text = project(title, 200)!;
+		assert.ok(Buffer.byteLength(text.replace("\n", "")) <= 256);
+		assert.ok(text.endsWith("…"));
+		assert.doesNotMatch(text, /[\x00-\x09\x0b-\x1f\x7f\u202e]/);
+		assert.ok(text.split("\n").length <= 2);
+	}
+});
+
+test("publisher serializes latest-only updates, clear, refresh and transport failures", async () => {
+	const calls: Array<{ summary: string | null; seq: number }> = [];
+	const queue: Array<() => void> = [];
+	let release: (() => void) | undefined;
+	const publisher = new ActivityPublisher(async (summary, seq) => {
+		calls.push({ summary, seq });
+		if (calls.length === 1) await new Promise<void>((resolve) => { release = resolve; });
+		if (summary === "fail") throw new Error("offline");
+	}, (fn) => { queue.push(fn); return () => {}; });
+	publisher.update("old"); publisher.update("first"); queue.shift()!();
+	publisher.update("second"); publisher.update("latest");
+	release!(); await new Promise(setImmediate);
+	queue.shift()!(); await new Promise(setImmediate);
+	assert.deepEqual(calls.map((call) => call.summary), ["first", "latest"]);
+	publisher.update("latest"); assert.equal(queue.length, 0);
+	publisher.update("latest", true); queue.shift()!(); await new Promise(setImmediate);
+	publisher.update("fail"); queue.shift()!(); await new Promise(setImmediate);
+	publisher.update(null); await new Promise(setImmediate);
+	assert.equal(calls.at(-1)?.summary, null);
+	assert.ok(calls.every((call, index) => index === 0 || call.seq > calls[index - 1]!.seq));
+	publisher.close(); publisher.update("ignored"); assert.equal(queue.length, 0);
+	await new Promise(setImmediate);
+});
+
+test("a non-forced clear supersedes active work in flight after a previous clear", async () => {
+	const calls: Array<string | null> = [];
+	const queue: Array<() => void> = [];
+	let release!: () => void;
+	const publisher = new ActivityPublisher(async (summary) => {
+		calls.push(summary);
+		if (summary === "active") await new Promise<void>((resolve) => { release = resolve; });
+	}, (fn) => { queue.push(fn); return () => {}; });
+	publisher.update(null); await new Promise(setImmediate);
+	publisher.update("active"); queue.shift()!();
+	publisher.update(null); publisher.update(null);
+	release(); await new Promise(setImmediate);
+	assert.equal(queue.length, 1, "one latest clear must be queued, not deduplicated against stale last");
+	queue.shift()!(); await new Promise(setImmediate);
+	assert.deepEqual(calls, [null, "active", null], "clear happens before close or TTL expiry");
+	publisher.close(); await new Promise(setImmediate);
+});
+
+test("shutdown supersedes queued activity even while a send is in flight", async () => {
+	const calls: Array<string | null> = [];
+	const queue: Array<() => void> = [];
+	let release!: () => void;
+	const publisher = new ActivityPublisher(async (summary) => {
+		calls.push(summary);
+		if (calls.length === 1) await new Promise<void>((resolve) => { release = resolve; });
+	}, (fn) => { queue.push(fn); return () => {}; });
+	publisher.update("active"); queue.shift()!(); publisher.update("stale");
+	publisher.close(); publisher.update("ignored"); release();
+	await new Promise(setImmediate); queue.shift()!(); await new Promise(setImmediate);
+	assert.deepEqual(calls, ["active", null]);
+});
+
+test("CLI transport uses only a bounded shell-free stub and tolerates offline failure", async (t) => {
+	const calls: unknown[][] = [];
+	const stub = t.mock.method(childProcess, "execFile", (...args: unknown[]) => {
+		calls.push(args);
+		(args[3] as (error: Error) => void)(new Error("offline"));
+	});
+	syncBuiltinESMExports();
+	try {
+		const env = { HERDR_ENV: "1", HERDR_SOCKET_PATH: "/fake", HERDR_PANE_ID: "fake-pane" };
+		await metadataTransport(env)("◐ long\n  title", 7);
+		assert.equal(calls[0]?.[0], "herdr");
+		assert.deepEqual(calls[0]?.[1], metadataArgs("fake-pane", "◐ long\n  title", 7));
+		assert.deepEqual(calls[0]?.[2], { env, timeout: 1500, maxBuffer: 4096, windowsHide: true });
+	} finally { stub.mock.restore(); syncBuiltinESMExports(); }
+});
+
+test("CLI transport honors an explicit Herdr binary path without shell interpretation", async (t) => {
+	const calls: unknown[][] = [];
+	const stub = t.mock.method(childProcess, "execFile", (...args: unknown[]) => {
+		calls.push(args);
+		(args[3] as (error: Error | null) => void)(null);
+	});
+	syncBuiltinESMExports();
+	try {
+		const env = { HERDR_BIN_PATH: "/fake/custom herdr/bin/herdr", HERDR_PANE_ID: "pane", PATH: "/fake/bin" };
+		await metadataTransport(env)("◐ task", 8);
+		assert.equal(calls[0]?.[0], env.HERDR_BIN_PATH);
+		assert.deepEqual(calls[0]?.[1], metadataArgs("pane", "◐ task", 8));
+		assert.deepEqual(calls[0]?.[2], { env, timeout: 1500, maxBuffer: 4096, windowsHide: true });
+	} finally { stub.mock.restore(); syncBuiltinESMExports(); }
+});
+
+test("one metadata report sets or clears both tokens without changing semantic state", () => {
+	const base = ["pane", "report-metadata", "pane", "--source", "gentle:activity", "--agent", "pi", "--seq", "42", "--ttl-ms", "30000"];
+	assert.deepEqual(metadataArgs("pane", null, 42), [...base, "--clear-token", "summary", "--clear-token", "summary2"]);
+	assert.deepEqual(metadataArgs("pane", "◐ long\n  title", 42), [...base, "--token", "summary=◐ long", "--token", "summary2=  title"]);
+	assert.deepEqual(metadataArgs("pane", "◐ short", 42), [...base, "--token", "summary=◐ short", "--clear-token", "summary2"]);
+});
+
+test("geometry opens nonblocking and closes non-files without reading", (t) => {
+	let flags: unknown;
+	const stubs = [
+		t.mock.method(fs, "openSync", (_path: string, mode: unknown) => { flags = mode; return 9; }),
+		t.mock.method(fs, "fstatSync", () => ({ size: 0, isFile: () => false })),
+		t.mock.method(fs, "readSync", () => { throw new Error("must not read a non-file"); }),
+		t.mock.method(fs, "closeSync", () => {}),
+	];
+	syncBuiltinESMExports();
+	try {
+		assert.equal(createActivityColumns("/fake/herdr.sock")(), 24);
+		assert.equal(stubs[2]!.mock.callCount(), 0);
+		assert.deepEqual(stubs[3]!.mock.calls[0]!.arguments, [9]);
+		assert.equal(stubs[3]!.mock.callCount(), 1);
+		assert.equal(typeof flags, "number", "open must use numeric nonblocking flags");
+		assert.equal(flags, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+	} finally { for (const stub of stubs) stub.mock.restore(); syncBuiltinESMExports(); }
+});
+
+test("geometry is cached, local/named, bounded and fail-safe without reading user data", (t) => {
+	let now = 0;
+	let body = '{"sidebar_width":35}';
+	let grew = false;
+	const paths: string[] = [];
+	const stubs = [
+		t.mock.method(fs, "openSync", (path: string) => { paths.push(path); return 9; }),
+		t.mock.method(fs, "fstatSync", () => ({ size: grew ? 1 : Buffer.byteLength(body), isFile: () => true })),
+		t.mock.method(fs, "readSync", (_fd: number, buffer: Buffer) => {
+			assert.equal(buffer.length, 262145);
+			return grew ? buffer.length : buffer.write(body);
+		}),
+		t.mock.method(fs, "closeSync", () => {}),
+	];
+	syncBuiltinESMExports();
+	try {
+		const columns = createActivityColumns("/fake/named/herdr.sock", () => now);
+		assert.equal(columns(), 30); body = '{"sidebar_width":25}';
+		assert.equal(columns(), 30); assert.equal(paths.length, 1);
+		now = 5000; assert.equal(columns(), 20);
+		assert.deepEqual(paths, ["/fake/named/session.json", "/fake/named/session.json"]);
+		for (const invalid of ["{", "null", '{"sidebar_width":"35"}', '{"sidebar_width":-1}',
+			'{"sidebar_width":35.5}', '{"sidebar_width":9999}', "x".repeat(262145)]) {
+			body = invalid; now += 5000; assert.equal(columns(), 24);
+		}
+		assert.equal(stubs[2]!.mock.callCount(), paths.length - 1, "oversized fstat must skip read");
+		grew = true; // Simulate a snapshot growing after fstat.
+		now += 5000; assert.equal(columns(), 24);
+		assert.equal(stubs[3]!.mock.callCount(), paths.length, "every opened descriptor closes");
+		stubs[0]!.mock.mockImplementation(() => { throw new Error("missing"); });
+		now += 5000; assert.equal(columns(), 24);
+		const before = paths.length;
+		assert.equal(createActivityColumns("relative.sock")(), 24);
+		assert.equal(paths.length, before, "relative paths must not read arbitrary snapshots");
+	} finally { for (const stub of stubs) stub.mock.restore(); syncBuiltinESMExports(); }
+});

package/tests/history-agent-home.test.ts

@@ -0,0 +1,81 @@
+import { after, test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// S9: in a bundled install the store, its legacy files and the transcript
+// scan follow the agent home Pi runs with (PI_CODING_AGENT_DIR). Everywhere
+// else they stay under ~/.pi/agent, where existing histories live.
+
+// The OS home is a temporary folder before the extension is imported, so even
+// a resolver that ignores PI_CODING_AGENT_DIR (or reads the OS home at import)
+// can never write into the real home.
+const osHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-os-home-"));
+const previousHome = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
+process.env.HOME = osHome;
+process.env.USERPROFILE = osHome;
+const { default: promptHistoryExtension } = await import("../extensions/history/index.ts");
+const { setBundledInstallForTesting } = await import("../lib/gentle-shell-bundled.ts");
+after(() => {
+  for (const [name, value] of Object.entries(previousHome)) {
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+  }
+  fs.rmSync(osHome, { recursive: true, force: true });
+});
+
+type Handler = (...args: unknown[]) => unknown;
+
+function load(env: NodeJS.ProcessEnv) {
+  const handlers = new Map<string, Handler[]>();
+  const pi = {
+    on: (name: string, handler: Handler) => {
+      handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+    },
+    registerShortcut: () => {},
+    registerCommand: () => {},
+  };
+  promptHistoryExtension(pi as never, {
+    env: { GENTLE_PI_HISTORY_CAPTURE: "1", ...env },
+    cwd: "/pi-history-test/project-agent-home",
+    instanceId: "inst-agent-home",
+    now: () => 1700000000000,
+    gentlePiConfigHome: fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-agent-home-config-")),
+  });
+  return async (prompt: string) => {
+    await new Promise((resolve) => setImmediate(resolve));
+    for (const handler of handlers.get("before_agent_start") ?? []) await handler({ prompt }, {});
+  };
+}
+
+function holds(store: string, prompt: string): boolean {
+  if (!fs.existsSync(store)) return false;
+  return fs.readdirSync(store, { recursive: true }).map(String)
+    .map((file) => path.join(store, file))
+    .filter((file) => fs.statSync(file).isFile())
+    .some((file) => fs.readFileSync(file, "utf8").includes(prompt));
+}
+
+test("outside a bundled install prompt history stays under ~/.pi/agent, whatever agent home Pi runs with", async (t) => {
+  const agentHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-agent-home-"));
+  t.after(() => fs.rmSync(agentHome, { recursive: true, force: true }));
+  // The isolated launcher's home, and a prefix variable this package is not installed in.
+  await load({ PI_CODING_AGENT_DIR: agentHome, GENTLE_SHELL_PREFIX: agentHome })("isolated home prompt");
+  assert.ok(holds(path.join(osHome, ".pi", "agent", "history"), "isolated home prompt"));
+  assert.equal(fs.existsSync(path.join(agentHome, "history")), false);
+});
+
+test("in a bundled install prompt history lives under the agent home Pi runs with", async (t) => {
+  const agentHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-agent-home-"));
+  const prefix = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "pi-history-prefix-")));
+  // The testing overlay stands in for this package running from that prefix.
+  setBundledInstallForTesting({ root: prefix });
+  t.after(() => {
+    setBundledInstallForTesting(undefined);
+    for (const dir of [agentHome, prefix]) fs.rmSync(dir, { recursive: true, force: true });
+  });
+  await load({ PI_CODING_AGENT_DIR: agentHome, GENTLE_SHELL_PREFIX: prefix })("bundled prompt");
+  assert.ok(holds(path.join(agentHome, "history"), "bundled prompt"));
+  assert.equal(holds(path.join(osHome, ".pi", "agent", "history"), "bundled prompt"), false);
+});