gentle-pi 4.0.0 → 4.2.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,102 @@ 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("alt+shift+down")!.handler(ctx);
+		assert.notDeepEqual(bottom.render(40), collapsed, "keyboard scrolling is available without mouse");
+	}
+	t.after(() => setCardStyle(CARD_STYLE.NEON));
+});
+
+test("Todo shortcuts never take a key Pi binds by default, so startup reports no shortcut conflict", async () => {
+	// Pi keeps its default table in dist/core/keybindings.js, next to the package entry.
+	const { KEYBINDINGS } = await import(new URL("core/keybindings.js", import.meta.resolve("@earendil-works/pi-coding-agent")).href) as
+		{ KEYBINDINGS: Record<string, { defaultKeys?: string | string[] }> };
+	assert.ok("tui.altScreen.previousPrompt" in KEYBINDINGS, "the table includes Pi's built-in prompt navigation");
+	const owners = new Map<string, string[]>();
+	for (const [id, binding] of Object.entries(KEYBINDINGS)) {
+		for (const key of ([] as string[]).concat(binding.defaultKeys ?? [])) owners.set(key, [...(owners.get(key) ?? []), id]);
+	}
+	const { pi, shortcuts } = fakePi();
+	gentleTodo(pi, {});
+	assert.deepEqual([...shortcuts.keys()].sort(), ["alt+shift+down", "alt+shift+up", "ctrl+shift+t"]);
+	for (const key of shortcuts.keys()) assert.equal(owners.get(key), undefined, `${key} is a Pi default for ${owners.get(key)?.join(", ")}`);
+});
+
+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("alt+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("alt+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,35 +297,204 @@ 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: [] };
+}
+
+type ContextMessage = { role: string; content: unknown; customType?: string; display?: boolean; timestamp?: number };
+
+async function contextMessages(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage[] | undefined> {
+	const messages = [{ role: "user", content: "Keep working", timestamp: 1 }];
+	const result = await fire("context", ctx, { messages }) as { messages: ContextMessage[] } | undefined;
+	assert.deepEqual(messages, [{ role: "user", content: "Keep working", timestamp: 1 }], "request-local injection must not mutate the input transcript");
+	if (result === undefined) return undefined;
+	assert.deepEqual(result.messages[0], { role: "user", content: "Keep working", timestamp: 1 }, "the transcript stays first; todo messages trail it");
+	return result.messages;
+}
+
+/** The request-local reminder, if the next model request carries one. */
+async function contextReminder(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage | undefined> {
+	return (await contextMessages(fire, ctx))?.find((message) => message.customType === "gentle-todo-reminder");
+}
+
+/** The request-local current-list message, if the next model request carries one (#1662). */
+async function contextState(fire: ReturnType<typeof fakePi>["fire"], ctx: ExtensionContext): Promise<ContextMessage | undefined> {
+	return (await contextMessages(fire, ctx))?.find((message) => message.customType === "gentle-todo-state");
+}
+
+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 messages = await contextMessages(fire, ctx);
+	assert.ok(messages, "the next model request must carry a reminder within the same run");
+	assert.equal(messages.length, 3, "transcript, current list, then the reminder");
+	assert.equal(messages[1]!.customType, "gentle-todo-state");
+	const reminder = messages[2]!;
+	assert.deepEqual(reminder, { role: "custom", customType: "gentle-todo-reminder", content: REMINDER, display: false, timestamp: reminder.timestamp });
+	const converted = convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+	assert.deepEqual(converted[2], { role: "user", content: [{ type: "text", text: REMINDER }], timestamp: reminder.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: "" } };
 }
 
-test("every turn carries the open tasks in appendSystemPrompt (never a returned systemPrompt) and the card goes stale after two silent turns", async () => {
+test("the system prompt carries only a byte-stable todo block; the current list travels as a request-local message (#1662)", async () => {
 	const { pi, tools, fire } = fakePi();
 	gentleTodo(pi, {});
 	const { ctx, widget } = fakeContext();
 	await fire("session_start", ctx);
-	await fire("before_agent_start", ctx, promptEvent());
+	const emptyEvent = promptEvent();
+	assert.equal(await fire("before_agent_start", ctx, emptyEvent), undefined, "the handler must not return a replacement systemPrompt");
+	assert.match(emptyEvent.systemPromptOptions.appendSystemPrompt, /^## Todo list/);
+	assert.match(emptyEvent.systemPromptOptions.appendSystemPrompt, /mark a task in_progress before starting/);
+	assert.equal(await contextState(fire, ctx), undefined, "an empty list sends no state message");
+
 	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
-
 	const withTasksEvent = promptEvent();
-	const withTasksResult = await fire("before_agent_start", ctx, withTasksEvent);
-	assert.equal(withTasksResult, undefined, "the handler must not return a replacement systemPrompt");
-	assert.match(withTasksEvent.systemPromptOptions.appendSystemPrompt, /^## Todo list/);
-	assert.match(withTasksEvent.systemPromptOptions.appendSystemPrompt, /1\. \[pending\] Fix the bug/);
+	await fire("before_agent_start", ctx, withTasksEvent);
+	assert.equal(withTasksEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "writing a list must not change the system prompt");
+	assert.doesNotMatch(withTasksEvent.systemPromptOptions.appendSystemPrompt, /Fix the bug/, "task content never enters the system prompt");
+	const state = await contextState(fire, ctx);
+	assert.ok(state, "open tasks arrive as a trailing request-local message");
+	assert.equal(state.role, "custom");
+	assert.equal(state.display, false);
+	assert.match(String(state.content), /1\. \[pending\] Fix the bug/);
 	assert.doesNotMatch(widget()![0], /stale/);
 
-	const staleEvent = promptEvent();
-	await fire("before_agent_start", ctx, staleEvent);
-	assert.match(staleEvent.systemPromptOptions.appendSystemPrompt, /stale: 2 turns without an update/);
-	assert.match(widget()![0], /ctrl\+shift\+t collapse/);
-	assert.match(widget()![1], /stale · 2 turns/);
+	// Silent turns: the UI card goes stale, the system prompt stays frozen (#1367).
+	for (const expected of ["stale · 2 turns", "stale · 3 turns"]) {
+		const silent = promptEvent();
+		await fire("before_agent_start", ctx, silent);
+		assert.equal(silent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt);
+		assert.match(widget()![1], new RegExp(expected));
+	}
 
+	// Status, note, title and ordering changes reach the model through the message only.
 	await tools.get("todo")!.execute("c2", { action: "update", id: 1, status: "in_progress", note: "on it" }, undefined, undefined, ctx);
 	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	const updatedEvent = promptEvent();
+	await fire("before_agent_start", ctx, updatedEvent);
+	assert.equal(updatedEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "a status change must not change the system prompt");
+	assert.match(String((await contextState(fire, ctx))!.content), /1\. \[in_progress\] Fix the bug — on it/);
 	assert.doesNotMatch(widget()![0], /stale/);
+
+	await tools.get("todo")!.execute("c3", { action: "update", id: 1, status: "done" }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	assert.equal(await contextState(fire, ctx), undefined, "a finished list sends no state message");
+	const finishedEvent = promptEvent();
+	await fire("before_agent_start", ctx, finishedEvent);
+	assert.equal(finishedEvent.systemPromptOptions.appendSystemPrompt, emptyEvent.systemPromptOptions.appendSystemPrompt, "finishing the list must not change the system prompt");
 });
 
 test("before_agent_start is idempotent: a todo block already present in appendSystemPrompt is not duplicated", async () => {
@@ -309,3 +576,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.doesNotMatch(event.systemPromptOptions.appendSystemPrompt, /Deploy/);
+		assert.match(String((await contextState(fire, ctx))!.content), /2\. \[blocked\] Deploy — waiting for an admin/);
+	}
+	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(); }
+});