gentle-pi 2.5.0 → 2.6.0

package/tests/agents-completion-delivery.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createCompletionQueue, STALE_COMPLETION_MS } from "../lib/agents-completion-delivery.ts";
+
+// The completion queue owns Gentle Agents' pending background completions so a
+// completion is delivered at most once, promptly, and never replays state the
+// parent already consumed (issue #867).
+
+interface FakeTask {
+	id: string;
+}
+
+const task = (id: string): FakeTask => ({ id });
+
+test("STALE_COMPLETION_MS is pinned so tests can rely on the boundary", () => {
+	assert.equal(STALE_COMPLETION_MS, 90_000);
+});
+
+test("a pending completion is delivered exactly once, in settle order", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	queue.enqueue(task("t2"), 2000);
+	const first = queue.takeDeliverable(2000);
+	assert.deepEqual(first.map((entry) => entry.task.id), ["t1", "t2"]);
+	assert.equal(first[0]!.settledAt, 1000);
+	assert.equal(first[0]!.stale, false, "a completion inside the stale window is fresh");
+	assert.deepEqual(queue.takeDeliverable(2000), [], "a taken entry is never returned twice");
+});
+
+test("duplicate enqueue for a pending task id is a no-op", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	queue.enqueue(task("t1"), 5000);
+	assert.deepEqual(queue.takeDeliverable(5000).map((entry) => entry.task.id), ["t1"]);
+});
+
+test("duplicate enqueue for a delivered task id is a no-op", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	assert.equal(queue.takeDeliverable(1000).length, 1);
+	queue.enqueue(task("t1"), 5000);
+	assert.deepEqual(queue.takeDeliverable(5000), []);
+});
+
+test("duplicate enqueue for a consumed task id is a no-op", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.consume("t1");
+	queue.enqueue(task("t1"), 1000);
+	assert.deepEqual(queue.takeDeliverable(5000), []);
+});
+
+test("a consumed entry is dropped and never returned", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	queue.enqueue(task("t2"), 1000);
+	queue.consume("t1");
+	assert.deepEqual(queue.takeDeliverable(2000).map((entry) => entry.task.id), ["t2"]);
+});
+
+test("consume remembers unknown ids so a later completion is suppressed", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.consume("t9");
+	queue.enqueue(task("t9"), 1000);
+	assert.deepEqual(queue.takeDeliverable(2000), []);
+});
+
+test("consume is idempotent", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.consume("t1");
+	queue.consume("t1");
+	queue.enqueue(task("t1"), 1000);
+	assert.deepEqual(queue.takeDeliverable(2000), []);
+});
+
+test("an entry is stale once now - settledAt reaches STALE_COMPLETION_MS", () => {
+	const fresh = createCompletionQueue<FakeTask>();
+	fresh.enqueue(task("t1"), 1000);
+	assert.equal(fresh.takeDeliverable(1000 + STALE_COMPLETION_MS - 1)[0]!.stale, false);
+	const stale = createCompletionQueue<FakeTask>();
+	stale.enqueue(task("t1"), 1000);
+	assert.equal(stale.takeDeliverable(1000 + STALE_COMPLETION_MS)[0]!.stale, true);
+});
+
+test("dropAll discards pending, consumed, and delivered state", () => {
+	const queue = createCompletionQueue<FakeTask>();
+	queue.enqueue(task("t1"), 1000);
+	assert.equal(queue.takeDeliverable(1000).length, 1, "delivered bookkeeping exists");
+	queue.enqueue(task("t2"), 1000);
+	queue.consume("t3");
+	queue.dropAll();
+	assert.deepEqual(queue.takeDeliverable(5000), [], "nothing pending survives dropAll");
+	queue.enqueue(task("t1"), 5000);
+	assert.deepEqual(queue.takeDeliverable(5000).map((entry) => entry.task.id), ["t1"], "the queue is fresh after dropAll");
+});

package/tests/agents-config.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import test, { after } from "node:test";
 import {
 	AGENT_MODE,
+	THINKING_LEVEL,
 	agentDirectories,
 	discoverAgents,
 	loadAgentsConfig,
@@ -14,6 +15,7 @@ import {
 	parseModelRef,
 	resolveAgentProfile,
 } from "../lib/agents-config.ts";
+import { THINKING_LEVELS } from "../lib/model-routing-authority.ts";
 
 // Gentle Agents configuration: markdown agent definitions (the same files
 // gentle-ai installs) and subagents.json, both parsed without touching pi.
@@ -77,6 +79,66 @@ test("parseAgentDefinition rejects unknown thinking levels, modes, and empty bod
 	assert.match((parseAgentDefinition("---\nname: a\n---\n   \n", "/a.md", "global") as { error: string }).error, /no instructions/);
 });
 
+test("runtime thinking levels stay aligned with model routing authority", () => {
+	assert.deepEqual(Object.values(THINKING_LEVEL), THINKING_LEVELS);
+	assert.equal(THINKING_LEVEL.MAX, "max");
+});
+
+test("parseAgentDefinition accepts max through every thinking alias", () => {
+	for (const field of ["thinking", "effort", "thinking_level"]) {
+		const agent = parseAgentDefinition(`---\nname: worker\n${field}: max\n---\nbody`, "/worker.md", "global");
+		assert.ok(!("error" in agent), `${field} must accept max`);
+		assert.equal(agent.thinking, "max");
+	}
+});
+
+test("discoverAgents retains max definitions instead of falling back to medium", () => {
+	const home = join(root, "max-home");
+	const cwd = join(root, "max-project");
+	const agentHome = join(home, ".pi", "agent");
+	for (const dir of ["agents", "subagents"]) mkdirSync(join(agentHome, dir), { recursive: true });
+	writeFileSync(join(agentHome, "agents", "worker.md"), "---\nname: worker\nthinking: medium\n---\nlegacy worker");
+	writeFileSync(join(agentHome, "subagents", "worker.md"), "---\nname: worker\nthinking: max\n---\nselected worker");
+	writeFileSync(join(agentHome, "subagents.json"), JSON.stringify({ model_profiles: { worker: { model: "openai-codex/gpt-5.6-luna", effort: "max" } } }));
+	const { agents, errors } = discoverAgents({ cwd, home });
+	assert.deepEqual(errors, []);
+	assert.equal(agents.length, 1);
+	assert.equal(agents[0].thinking, "max");
+	assert.equal(agents[0].instructions, "selected worker");
+	const resolved = resolveAgentProfile(agents[0], loadAgentsConfig({ cwd, home }));
+	assert.equal(resolved.model?.id, "gpt-5.6-luna");
+	assert.equal(resolved.thinking, "max");
+	assert.equal(resolved.source.thinking, "profile");
+});
+
+test("max defaults and model profiles preserve routing precedence", () => {
+	const bare = parseAgentDefinition("---\nname: worker\n---\nbody", "/worker.md", "global");
+	const medium = parseAgentDefinition("---\nname: worker\nthinking: medium\n---\nbody", "/worker.md", "global");
+	assert.ok(!("error" in bare));
+	assert.ok(!("error" in medium));
+	for (const field of ["default_effort", "default_thinking_level", "default_thinking"]) {
+		const config = parseAgentsConfig({ [field]: "max" }, undefined);
+		assert.equal(config.defaultThinking, "max");
+		assert.equal(resolveAgentProfile(bare, config).thinking, "max");
+		assert.equal(resolveAgentProfile(bare, config).source.thinking, "default");
+		assert.equal(resolveAgentProfile(medium, config).thinking, "medium");
+	}
+	for (const field of ["effort", "thinking"]) {
+		const global = { model_profiles: { worker: { [field]: "max" } } };
+		const config = parseAgentsConfig(global, { model_profiles: { worker: { model: "openai-codex/gpt-5.6-luna" } } });
+		assert.equal(config.modelProfiles.worker.thinking, "max");
+		assert.equal(resolveAgentProfile(medium, config).thinking, "max");
+		assert.equal(resolveAgentProfile(medium, config).source.thinking, "profile");
+	}
+	const override = parseAgentsConfig(
+		{ model_profiles: { worker: { model: "openai-codex/gpt-5.6-luna", effort: "high" } } },
+		{ model_profiles: { worker: { effort: "max" } } },
+	);
+	assert.equal(override.modelProfiles.worker.thinking, "max");
+	assert.equal(resolveAgentProfile(medium, override).thinking, "max");
+	assert.equal(resolveAgentProfile(medium, override).model?.id, "gpt-5.6-luna");
+});
+
 test("discoverAgents merges the four directories with project over global and subagents over agents", () => {
 	const home = join(root, "home");
 	const cwd = join(root, "project");

package/tests/agents-fake-child.ts

@@ -12,6 +12,9 @@ export interface FakeChild {
 	exit(code: number): void;
 	fail(message: string): void;
 	killed: string[];
+	sent: Array<Record<string, unknown>>;
+	disconnects: number;
+	message(event: Record<string, unknown>): void;
 }
 
 export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}): FakeChild {
@@ -20,6 +23,8 @@ export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}):
 	const stdout = new PassThrough();
 	const written: Array<Record<string, unknown>> = [];
 	const killed: string[] = [];
+	const sent: Array<Record<string, unknown>> = [];
+	let disconnects = 0;
 	let buffer = "";
 	stdin.on("data", (chunk: Buffer) => {
 		buffer += chunk.toString();
@@ -43,10 +48,19 @@ export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}):
 			if (options.exitOnKill !== false) queueMicrotask(() => emitter.emit("exit", 0, signal ?? "SIGTERM"));
 			return true;
 		},
+		send: (message, callback) => {
+			sent.push(message);
+			callback?.(null);
+			return true;
+		},
+		disconnect: () => {
+			disconnects += 1;
+			emitter.emit("disconnect");
+		},
 		on: (event, listener) => {
 			emitter.on(event, listener);
 			return child;
 		},
 	};
-	return { child, written, killed, emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
+	return { child, written, killed, sent, get disconnects() { return disconnects; }, message: (event) => emitter.emit("message", event), emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
 }

package/tests/agents-grouping.test.ts

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentsView, SESSION_FINISHED_TTL_MS } from "../lib/agents-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(id: string, parentSessionId: string, overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return {
+		id,
+		agent: "worker",
+		mode: "task",
+		prompt: "p",
+		label: "p",
+		cwd: "/r",
+		parentSessionId,
+		status: TASK_STATUS.RUNNING,
+		createdAt: 1000,
+		startedAt: 1000,
+		endedAt: null,
+		model: "gpt",
+		thinking: undefined,
+		sessionPath: "/sessions/child.jsonl",
+		error: null,
+		result: null,
+		lastStep: "working",
+		lastActivityAt: 1000,
+		turns: 0,
+		toolCalls: 0,
+		tokens: 0,
+		cost: 0,
+		...overrides,
+	};
+}
+
+function harness(rows = 12, now = () => 10_000) {
+	const store = new TaskStore();
+	const view = new AgentsView({
+		theme: plainTheme,
+		rows,
+		store,
+		sessionId: "current-session-id",
+		now,
+		onCancel: () => {},
+		onOpen: () => {},
+		onClose: () => {},
+		requestRender: () => {},
+	});
+	return { store, view };
+}
+
+function mouse(x: number, y: number, width: number, height: number, type: TuiMouseEvent["type"] = "move"): TuiMouseEvent {
+	return { type, button: type === "move" ? "none" : "left", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false };
+}
+
+test("AgentsView shows direct current children and groups only open orchestrators in the directory", () => {
+	const { store, view } = harness();
+	store.add(task("current", "current-session-id", { agent: "current-worker" }));
+	store.add(task("other", "other-session-123456", { agent: "other-worker" }));
+
+	const plain = view.render(100).map(stripAnsi).join("\n");
+	assert.doesNotMatch(plain, /Current orchestrator/);
+	assert.match(plain, /Subagent current-worker/);
+	assert.doesNotMatch(plain, /other-worker/, "the default scope excludes another parent session");
+	view.handleInput("a");
+	assert.doesNotMatch(view.render(100).map(stripAnsi).join("\n"), /Orchestrator other-se/);
+	assert.match(view.render(100).join("\n"), /Current orchestrator/);
+	view.dispose();
+});
+
+test("AgentsView never infers unknown open sessions and keeps manual directory expansion", () => {
+	const { store, view } = harness();
+	store.add(task("current", "current-session-id", { lastActivityAt: 500 }));
+	store.add(task("other", "other-session-123456", { lastActivityAt: 400 }));
+	store.add(task("unknown-active", "", { agent: "unknown-active", lastActivityAt: 300 }));
+	store.add(task("unknown-terminal", "", { agent: "unknown-terminal", status: TASK_STATUS.COMPLETED, endedAt: 9000, lastActivityAt: 200 }));
+	view.handleInput("a");
+
+	let lines = view.render(100);
+	let plain = lines.map(stripAnsi).join("\n");
+	assert.doesNotMatch(plain, /Unknown session|unknown-active|other-worker/, "retained origins are not presence evidence");
+	assert.doesNotMatch(plain, /unknown-terminal/, "a terminal-only group starts collapsed");
+	const terminalHeading = lines.map(stripAnsi).findIndex((line) => /Current orchestrator/.test(line));
+	assert.equal(view.handleMouse(mouse(4, terminalHeading, 100, lines.length, "click"))?.handled, true, "left click toggles a heading");
+	assert.doesNotMatch(view.render(100).map(stripAnsi).join("\n"), /Subagent worker/, "click collapses the local directory group");
+	store.update("unknown-terminal", { status: TASK_STATUS.FAILED });
+	assert.doesNotMatch(view.render(100).map(stripAnsi).join("\n"), /Subagent worker/, "manual collapse persists across unrelated updates");
+	view.handleMouse(mouse(4, terminalHeading, 100, lines.length, "click"));
+	store.update("unknown-terminal", { status: TASK_STATUS.CANCELLED });
+	assert.match(view.render(100).map(stripAnsi).join("\n"), /Subagent worker/, "manual expansion persists across unrelated updates");
+	assert.doesNotMatch(view.render(100).join("\n"), /unknown-termina/, "unknown terminal history remains excluded");
+	view.dispose();
+});
+
+test("AgentsView keeps headings non-actionable and clears a hidden selected child thread", () => {
+	const { store, view } = harness();
+	store.add(task("first", "current-session-id", { createdAt: 2000, lastActivityAt: 200 }));
+	store.add(task("child", "current-session-id", { lastActivityAt: 100 }));
+	assert.equal(view.selectedTask()?.id, "first", "the first visible child starts selected");
+	view.handleInput("a");
+	view.handleInput("k");
+	view.handleInput("\x1b[D");
+	assert.equal(view.selectedTask(), undefined, "collapsing selects the heading instead of a hidden child");
+	assert.match(view.render(100).map(stripAnsi).join("\n"), /Select a task to inspect its thread/);
+	view.handleInput("\x1b[C");
+	assert.equal(view.selectedTask(), undefined, "expanding preserves heading focus until a child is selected");
+	view.handleInput("s");
+	view.handleInput("o");
+	view.dispose();
+});
+
+test("AgentsView removes terminal children immediately without deleting retained threads", () => {
+	let now = 10_000;
+	const { store, view } = harness(12, () => now);
+	store.add(task("live", "current-session-id", { agent: "retained" }));
+	store.add(task("other", "other-session", { agent: "excluded" }));
+	store.apply("live", { type: "text", text: "kept thread" }, now);
+	store.update("live", { status: TASK_STATUS.COMPLETED, endedAt: now });
+	for (const elapsed of [0, SESSION_FINISHED_TTL_MS - 1]) {
+		now = 10_000 + elapsed;
+		const output = view.render(100).map(stripAnsi).join("\n");
+		assert.doesNotMatch(output, /Subagent retained|kept thread/);
+		assert.equal(store.thread("live").items.length, 1, "retained thread remains available outside the panel");
+		assert.doesNotMatch(output, /excluded/);
+		assert.equal(view.selectedTask(), undefined);
+	}
+	now = 10_000 + SESSION_FINISHED_TTL_MS;
+	assert.doesNotMatch(view.render(100).join("\n"), /Subagent retained/);
+	assert.equal(view.selectedTask(), undefined);
+	store.add(task("archive", "current-session-id", { agent: "archived", status: TASK_STATUS.COMPLETED, endedAt: now }));
+	assert.doesNotMatch(view.render(100).join("\n"), /Subagent archived/, "absent groups lose implicit expansion");
+	view.dispose();
+});
+
+test("AgentsView retains an idle open heading and explicit collapse after the final child finishes", () => {
+	const { store, view } = harness();
+	store.add(task("live", "current-session-id", { agent: "hidden" }));
+	view.handleInput("a");
+	view.render(100);
+	view.handleInput("k");
+	view.handleInput("\x1b[D");
+	store.update("live", { status: TASK_STATUS.COMPLETED, endedAt: 10_000 });
+	assert.doesNotMatch(view.render(100).join("\n"), /Subagent hidden/);
+	view.handleInput("\x1b[C");
+	assert.doesNotMatch(view.render(100).join("\n"), /Subagent hidden/);
+	assert.match(view.render(100).join("\n"), /Current orchestrator.*0/);
+	store.add(task("replacement", "current-session-id", { agent: "replacement" }));
+	assert.match(view.render(100).join("\n"), /Subagent replacement/);
+	view.dispose();
+});
+
+test("AgentsView orders children by creation then ID, not renewed activity", () => {
+	const { store, view } = harness();
+	store.add(task("old", "current-session-id", { agent: "old", createdAt: 100 }));
+	store.add(task("b", "current-session-id", { agent: "new-b", createdAt: 200 }));
+	store.add(task("a", "current-session-id", { agent: "new-a", createdAt: 200 }));
+	store.update("old", { lastActivityAt: 20_000 });
+	const output = view.render(100).join("\n");
+	assert.ok(output.indexOf("Subagent new-a") < output.indexOf("Subagent new-b"));
+	assert.ok(output.indexOf("Subagent new-b") < output.indexOf("Subagent old"));
+	assert.equal(view.selectedTask()?.id, "old", "reordering preserves selection");
+	view.dispose();
+});
+
+test("AgentsView keeps its selected listener stable while another listener receives a stream update", () => {
+	const { store, view } = harness();
+	store.add(task("stream", "current-session-id"));
+	let notifications = 0;
+	const unsubscribe = store.subscribe("stream", () => {
+		notifications += 1;
+		if (notifications > 1) throw new Error("selected listener was re-added during notification");
+	});
+	store.apply("stream", { type: "text", text: "one" }, 2000);
+	assert.equal(notifications, 1, "a live listener set never revisits the same streaming update");
+	unsubscribe();
+	view.dispose();
+});

package/tests/agents-integration.test.ts

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentsView } from "../lib/agents-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(id: string, overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return { id, agent: id, mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "session", status: TASK_STATUS.RUNNING, createdAt: 1000, startedAt: 1000, endedAt: null, model: "model", thinking: undefined, sessionPath: "/sessions/task.jsonl", error: null, result: null, lastStep: "working", lastActivityAt: 1000, turns: 0, toolCalls: 0, tokens: 0, cost: 0, ...overrides };
+}
+
+function mouse(x: number, y: number, width: number, height: number, type: TuiMouseEvent["type"] = "click"): TuiMouseEvent {
+	return { type, button: type === "move" || type === "wheel" ? "none" : "left", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false };
+}
+
+test("AgentsView integrates flat current-session selection, semantic scrolling, live geometry, and idempotent close", () => {
+	const store = new TaskStore();
+	let rows = 8;
+	const closes: string[] = [];
+	const view = new AgentsView({
+		theme: plainTheme,
+		rows: () => rows,
+		store,
+		sessionId: "session",
+		now: () => 61_000,
+		onCancel() {},
+		onOpen() {},
+		onClose: () => closes.push("close"),
+		requestRender() {},
+	});
+	store.add(task("first"));
+	store.add(task("second"));
+	for (let index = 0; index < 12; index += 1) store.apply("first", { type: TASK_EVENT.TEXT, text: `semantic line ${index}\n` }, 2000);
+
+	const wide = 80;
+	let frame = view.render(wide);
+	const header = stripAnsi(frame[0] ?? "");
+	assert.equal(visibleWidth(header), wide);
+	assert.match(header, /\[× Close\]/, "a pane-capable header exposes the wide close control");
+	const closeX = visibleWidth(header.slice(0, header.indexOf("[× Close]")));
+
+	view.handleInput("k");
+	view.handleInput("\x1b[D");
+	assert.equal(view.selectedTask()?.id, "first", "up and left keep the first task selected without a group heading");
+	rows = 6;
+	assert.equal(view.handleMouse(mouse(closeX, 0, wide, frame.length)), undefined, "old close bounds are inert before the live resize frame");
+	frame = view.render(wide);
+	assert.equal(frame.length, rows, "the next frame uses the live height budget");
+	assert.doesNotMatch(frame.map(stripAnsi).join("\n"), /Current orchestrator|Select a task to inspect its thread/, "current-session tasks stay flat with an active detail pane");
+	assert.match(frame.map(stripAnsi).join("\n"), /semantic line 11/, "the selected task still follows its thread after resizing");
+
+	view.handleInput("\x1b[C");
+	assert.equal(view.selectedTask()?.id, "first", "right does not expand a heading in the flat list");
+	view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "second", "down selects the next task directly");
+	view.handleInput("k");
+	assert.equal(view.selectedTask()?.id, "first", "up returns directly to the first task");
+	view.render(wide);
+	view.handleInput("\x1b[5~");
+	frame = view.render(wide);
+	assert.doesNotMatch(frame.map(stripAnsi).join("\n"), /semantic line 11/, "manual thread scrolling remains off the tail after resizing");
+	const narrow = view.render(59).map(stripAnsi);
+	assert.equal(narrow.length, rows, "width 59 keeps a narrow single viewport");
+	assert.match(narrow[0] ?? "", /\[×\]/, "narrow mode keeps only the compact close control");
+	view.handleInput("\t");
+	const details = view.render(59).map(stripAnsi);
+	assert.match(details[0] ?? "", /\[← Back\]/, "Tab opens selected-task details directly from the flat list");
+	assert.match(details.join("\n"), /first · running/, "details belong to the selected task");
+	view.handleInput("\t");
+	assert.equal(view.selectedTask()?.id, "first", "returning from details preserves task selection");
+	rows = 2;
+	const fallback = view.render(59).map(stripAnsi);
+	assert.equal(fallback.length, 1, "a two-row terminal uses the one-line fallback");
+	assert.match(fallback[0] ?? "", /^× Close/, "fallback mode keeps a single Close cell");
+	assert.equal(view.handleMouse(mouse(1, 0, 59, fallback.length)), undefined, "fallback routing outside the Close cell is inert");
+
+	rows = 6;
+	frame = view.render(wide);
+	const reopenedHeader = stripAnsi(frame[0] ?? "");
+	const reopenedCloseX = visibleWidth(reopenedHeader.slice(0, reopenedHeader.indexOf("[× Close]")));
+	let notifications = 0;
+	const unsubscribe = store.subscribe("first", () => {
+		notifications += 1;
+		if (notifications > 1) throw new Error("the selected listener was rebound during a live update");
+	});
+	store.apply("first", { type: TASK_EVENT.TEXT, text: "after reopen" }, 2000);
+	assert.equal(notifications, 1, "reopening panes retains an idempotent selected-task subscription");
+	assert.equal(view.handleMouse(mouse(reopenedCloseX, 0, wide, frame.length)), undefined, "a task update invalidates the old close bounds");
+	frame = view.render(wide);
+	const currentHeader = stripAnsi(frame[0] ?? "");
+	const currentCloseX = visibleWidth(currentHeader.slice(0, currentHeader.indexOf("[× Close]")));
+	unsubscribe();
+	assert.equal(view.handleMouse(mouse(currentCloseX, 0, wide, frame.length))?.handled, true);
+	view.handleInput("\x1b");
+	view.handleInput("q");
+	assert.deepEqual(closes, ["close"], "pointer, Escape, and q share the same idempotent close action");
+	view.dispose();
+});

package/tests/agents-messaging.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { join } from "node:path";
+import test from "node:test";
+import { CHILD_MESSAGE_MAX_BYTES, ChildMessenger, parseChildFrame } from "../lib/agents-messaging.ts";
+
+test("notification and query frames admit only bounded exact schemas", () => {
+	assert.deepEqual(parseChildFrame({ id: "n1", kind: "notification", message: "💡\nready" }).frame, { id: "n1", kind: "notification", message: "💡\nready" });
+	assert.deepEqual(parseChildFrame({ id: "q1", kind: "query", message: "💡\nready" }).frame, { id: "q1", kind: "query", message: "💡\nready" });
+	for (const frame of [
+		{ id: "n1", kind: "notification", message: "ready", sender: "forged" },
+		{ id: "n1", kind: "query", message: "wrong grammar" },
+		{ id: "q1", kind: "notification", message: "wrong grammar" },
+		{ id: "q0", kind: "query", message: "leading zero" },
+		{ id: `q${"1".repeat(1_000)}`, kind: "query", message: "unbounded correlation" },
+		{ id: "q9007199254740992", kind: "query", message: "unsafe correlation" },
+		{ id: "q1", kind: "query", message: "\uD800" },
+		{ id: "q1", kind: "query", message: "💡".repeat(Math.floor(CHILD_MESSAGE_MAX_BYTES / 4) + 1) },
+		{ id: 3, kind: "notification", message: "ready" },
+	]) assert.ok(parseChildFrame(frame).error, `reject ${JSON.stringify(frame).slice(0, 80)}`);
+});
+
+test("child notification admissions require an exact acknowledgement and clean up", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const frames: Array<Record<string, unknown>> = [];
+	const timers: Array<() => void> = [];
+	const endpoint = { send: (frame: Record<string, unknown>) => { frames.push(frame); return true; }, on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]) };
+	const messenger = new ChildMessenger(endpoint, (fn) => { timers.push(fn); return () => {}; });
+	const pending = messenger.notify("wait");
+	let settled = false;
+	void pending.then(() => { settled = true; });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true, sender: "forged" });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: false, error: "x".repeat(257) });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true, error: "x".repeat(8 * 1024 + 1) });
+	await Promise.resolve();
+	assert.equal(settled, false, "malformed acknowledgements cannot settle a pending notification");
+	assert.deepEqual(frames, [{ id: "n1", kind: "notification", message: "wait" }]);
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true });
+	await pending;
+	const timedOut = messenger.notify("timeout");
+	timers.at(-1)!();
+	await assert.rejects(timedOut, /timed out/);
+	const inflight = Array.from({ length: 8 }, (_, index) => messenger.notify(`pending ${index}`));
+	await assert.rejects(messenger.notify("over capacity"), /too many/);
+	for (const listener of listeners.get("disconnect") ?? []) listener({});
+	assert.ok((await Promise.allSettled(inflight)).every((result) => result.status === "rejected"));
+	const afterDisconnect = messenger.notify("after disconnect");
+	void afterDisconnect.catch(() => {});
+	await Promise.resolve();
+	assert.equal(frames.length, 10, "a disconnected messenger cannot send another notification");
+});
+
+test("callback failures clear pending work but a closed messenger cannot retry", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const callbacks: Array<(error: Error | null) => void> = [];
+	const timers: Array<{ cancelled: boolean }> = [];
+	const endpoint = { send: (_frame: Record<string, unknown>, callback?: (error: Error | null) => void) => { callbacks.push(callback!); return true; }, on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]) };
+	const messenger = new ChildMessenger(endpoint, () => {
+		const timer = { cancelled: false };
+		timers.push(timer);
+		return () => { timer.cancelled = true; };
+	});
+	const failed = messenger.notify("first");
+	callbacks[0](new Error("send failed"));
+	await assert.rejects(failed, /send failed/);
+	const retry = messenger.notify("retry");
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n2", kind: "ack", accepted: true });
+	await retry;
+	messenger.close();
+	assert.ok(timers.every((timer) => timer.cancelled), "settled and closed work cancels every timer");
+	const afterClose = messenger.notify("after close");
+	void afterClose.catch(() => {});
+	await Promise.resolve();
+	assert.equal(callbacks.length, 2, "a closed messenger cannot retry through its endpoint");
+	const exhausted = new ChildMessenger(endpoint, () => () => {});
+	(exhausted as unknown as { nextId: number }).nextId = Number.MAX_SAFE_INTEGER;
+	await assert.rejects(exhausted.notify("overflow"), /correlation exhausted/);
+});
+
+test("a real Node IPC child exchanges a notification acknowledgement without stdout framing", async () => {
+	const child = spawn(process.execPath, [join(import.meta.dirname, "fixtures", "agents-messaging-child.mjs")], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+	const messages: unknown[] = [];
+	let output = "";
+	const closed = once(child, "close");
+	child.on("message", (message) => messages.push(message));
+	child.stdout.on("data", (chunk) => { output += chunk; });
+	await once(child, "message");
+	assert.deepEqual(messages, [{ id: "n1", kind: "notification", message: "fixture ready" }]);
+	child.send({ id: "n1", kind: "ack", accepted: true });
+	const [code] = await closed;
+	assert.equal(code, 0);
+	assert.equal(output, '{"accepted":true}\n');
+});

package/tests/agents-protocol.test.ts

@@ -67,6 +67,51 @@ test("normalizeRpcEvent maps pi RPC events to task deltas and ignores the rest",
 	assert.deepEqual(normalizeRpcEvent("garbage"), []);
 });
 
+test("response observations are opt-in, finalized, field-specific and content-free", () => {
+	const message = { role: "assistant", provider: "openai", model: "gpt-4o", responseModel: "gpt-4o-2024-08-06",
+		providerThinkingLevel: "high", stopReason: "stop", content: [{ type: "text", text: "private response" }],
+		errorMessage: "private error", responseId: "private id", modelVersion: "invented",
+		usage: { input: 12, output: 4, cacheRead: 0, cacheWrite: -1, totalTokens: 16, reasoning: 2 } };
+	const raw = { type: "message_end", message };
+	assert.deepEqual(normalizeRpcEvent(raw), [{ type: TASK_EVENT.USAGE, tokens: 16, cost: 0 }]);
+	const events = normalizeRpcEvent(raw, { observeResponses: true });
+	assert.equal(events.length, 2);
+	const observation = events.find((event) => event.type === "response_observation")?.observation;
+	assert.ok(observation);
+	assert.deepEqual(observation.provider, { state: "observed", value: "openai" });
+	assert.deepEqual(observation.model, { state: "observed", value: "gpt-4o" });
+	assert.deepEqual(observation.responseModel, { state: "observed", value: message.responseModel });
+	assert.deepEqual(observation.providerThinkingLevel, { state: "observed", value: "high" });
+	assert.deepEqual(observation.selected, { provider: { state: "unavailable" }, model: { state: "unavailable" }, effort: { state: "unavailable" } });
+	assert.deepEqual(observation.tokens, { input: { state: "reported", value: 12 }, output: { state: "reported", value: 4 },
+		cacheRead: { state: "unavailable" }, cacheWrite: { state: "unavailable" }, totalTokens: { state: "reported", value: 16 },
+		reasoning: { state: "reported", value: 2 } });
+	assert.doesNotMatch(JSON.stringify(observation), /private|invented|modelVersion|content|responseId/);
+	for (const stopReason of ["stop", "length", "toolUse", "error", "aborted"]) {
+		const [event] = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason } }, { observeResponses: true });
+		assert.ok(event?.type === "response_observation", "missing usage still exposes a response");
+		assert.equal(event.observation.stopReason, stopReason);
+	}
+	for (const stopReason of ["pending", "deferred", undefined, "private error"]) {
+		assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason } }, { observeResponses: true }), []);
+	}
+	for (const type of ["message_start", "message_update", "turn_end", "agent_end"]) {
+		assert.ok(!normalizeRpcEvent({ type, message, messages: [message] }, { observeResponses: true }).some((event) => event.type === "response_observation"));
+	}
+	assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { ...message, role: "toolResult" } }, { observeResponses: true }), []);
+});
+
+test("response observations reject malformed counters and unbounded metadata without coercion", () => {
+	for (const value of [0, -1, 1.5, NaN, Infinity, "12", null, undefined, 1_000_000_001]) {
+		const [event] = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason: "error",
+			provider: "x".repeat(33), model: "x".repeat(129), responseModel: "private\ntext", providerThinkingLevel: {},
+			usage: { input: value, output: value, cacheRead: value, cacheWrite: value, totalTokens: value, reasoning: value } } }, { observeResponses: true }).filter((event) => event.type === "response_observation");
+		assert.ok(event);
+		for (const field of Object.values(event.observation.tokens)) assert.deepEqual(field, { state: "unavailable" });
+		for (const field of ["provider", "model", "responseModel", "providerThinkingLevel"] as const) assert.deepEqual(event.observation[field], { state: "unavailable" });
+	}
+});
+
 test("taskLabel prefers an explicit label and otherwise takes the prompt's first sentence", () => {
 	assert.equal(taskLabel("Map the repo. Then report.", "  map  the repo "), "map the repo");
 	assert.equal(taskLabel("Repeat a fresh read-only exploration of lib. Own runtime architecture: extensions, hooks."), "Repeat a fresh read-only exploration of lib");