gentle-pi 2.4.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

@@ -0,0 +1,205 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import {
+	AGENT_MODE,
+	THINKING_LEVEL,
+	agentDirectories,
+	discoverAgents,
+	loadAgentsConfig,
+	parseAgentDefinition,
+	parseAgentsConfig,
+	parseFrontmatter,
+	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.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-config-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+const EXPLORER = `---
+name: gentle-ai-explore
+description: Read-only exploration and mapping.
+model: openai-codex/gpt-5.6-terra
+thinking: high
+tools:
+  - read
+  - grep
+  - codegraph
+---
+
+You are the read-only explorer.
+Map files and return a compressed handoff.
+`;
+
+test("parseFrontmatter reads scalars, inline lists, and block lists, and keeps the body", () => {
+	const { data, body } = parseFrontmatter("---\nname: a\ntools: [read, grep]\nlist:\n  - one\n  - two\nquoted: \"x: y\"\n---\nBody here\n");
+	assert.deepEqual(data, { name: "a", tools: ["read", "grep"], list: ["one", "two"], quoted: "x: y" });
+	assert.equal(body, "Body here");
+	assert.deepEqual(parseFrontmatter("no frontmatter"), { data: {}, body: "no frontmatter" });
+});
+
+test("parseModelRef splits provider/id and accepts a bare id", () => {
+	assert.deepEqual(parseModelRef("openai-codex/gpt-5.6-terra"), { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.deepEqual(parseModelRef("sonnet"), { provider: undefined, id: "sonnet" });
+	assert.equal(parseModelRef("   "), undefined);
+});
+
+test("parseAgentDefinition builds a definition from the gentle-ai agent format", () => {
+	const agent = parseAgentDefinition(EXPLORER, "/home/x/.pi/agent/agents/gentle-ai-explore.md", "global");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "gentle-ai-explore");
+	assert.equal(agent.description, "Read-only exploration and mapping.");
+	assert.deepEqual(agent.model, { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.equal(agent.thinking, "high");
+	assert.deepEqual(agent.tools, ["read", "grep", "codegraph"]);
+	assert.equal(agent.mode, undefined);
+	assert.equal(agent.scope, "global");
+	assert.match(agent.instructions, /^You are the read-only explorer\./);
+});
+
+test("parseAgentDefinition accepts effort and subagent_mode aliases, csv tools, and names from the file", () => {
+	const agent = parseAgentDefinition("---\ndescription: d\neffort: low\nsubagent_mode: background\ntools: read, bash\n---\nbody", "/p/.pi/agents/worker.md", "project");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "worker");
+	assert.equal(agent.thinking, "low");
+	assert.equal(agent.mode, AGENT_MODE.BACKGROUND);
+	assert.deepEqual(agent.tools, ["read", "bash"]);
+});
+
+test("parseAgentDefinition rejects unknown thinking levels, modes, and empty bodies", () => {
+	assert.match((parseAgentDefinition("---\nname: a\nthinking: extreme\n---\nbody", "/a.md", "global") as { error: string }).error, /thinking "extreme"/);
+	assert.match((parseAgentDefinition("---\nname: a\nsubagent_mode: forever\n---\nbody", "/a.md", "global") as { error: string }).error, /mode "forever"/);
+	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");
+	for (const dir of [".pi/agent/agents", ".pi/agent/subagents"]) mkdirSync(join(home, dir), { recursive: true });
+	for (const dir of [".pi/agents", ".pi/subagents"]) mkdirSync(join(cwd, dir), { recursive: true });
+	writeFileSync(join(home, ".pi/agent/agents/explore.md"), EXPLORER);
+	writeFileSync(join(home, ".pi/agent/agents/shared.md"), "---\ndescription: global agents\n---\nglobal");
+	writeFileSync(join(home, ".pi/agent/subagents/shared.md"), "---\ndescription: global subagents\n---\nglobal sub");
+	writeFileSync(join(cwd, ".pi/agents/shared.md"), "---\ndescription: project agents\n---\nproject");
+	writeFileSync(join(cwd, ".pi/agents/broken.md"), "---\nthinking: nope\n---\nx");
+	writeFileSync(join(cwd, ".pi/agents/notes.txt"), "ignored");
+	const { agents, errors } = discoverAgents({ cwd, home });
+	assert.deepEqual(agents.map((agent) => `${agent.name}:${agent.description}:${agent.scope}`), ["gentle-ai-explore:Read-only exploration and mapping.:global", "shared:project agents:project"]);
+	assert.equal(errors.length, 1);
+	assert.match(errors[0], /broken\.md/);
+	assert.deepEqual(discoverAgents({ cwd: join(root, "empty"), home: join(root, "nohome") }), { agents: [], errors: [] });
+});
+
+test("profile agent roots isolate global definitions and subagents.json while explicit homes keep their fallback", () => {
+	const cwd = join(root, "profile-project");
+	const principal = join(root, "pi-principal", "agent");
+	const lab = join(root, "pi-lab", "agent");
+	for (const [agentHome, name, model] of [[principal, "principal", "openai/principal"], [lab, "lab", "openai/lab"]] as const) {
+		mkdirSync(join(agentHome, "agents"), { recursive: true });
+		writeFileSync(join(agentHome, "agents", `${name}.md`), `---\ndescription: ${name}\n---\n${name}`);
+		writeFileSync(join(agentHome, "subagents.json"), JSON.stringify({ default_model: model }));
+	}
+	assert.deepEqual(agentDirectories({ cwd, home: join(root, "legacy-home"), agentHome: principal }).slice(0, 2).map(({ dir }) => dir), [join(principal, "agents"), join(principal, "subagents")]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: principal }).agents.map((agent) => agent.name), ["principal"]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: lab }).agents.map((agent) => agent.name), ["lab"]);
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: principal }).defaultModel?.id, "principal");
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: lab }).defaultModel?.id, "lab");
+	assert.equal(agentDirectories({ cwd, home: join(root, "legacy-home") })[0].dir, join(root, "legacy-home", ".pi", "agent", "agents"));
+});
+
+test("parseAgentsConfig applies defaults, validates values, and silently ignores the retired total-timeout key", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", max_concurrency: 3, timeout_ms: 1000, stall_timeout_ms: 12_000, model_profiles: { explore: { model: "openai-codex/gpt-5.6-terra", effort: "high" } } }, { max_concurrency: 2, timeout_ms: 500, model_profiles: { explore: { effort: "low" }, worker: { model: "anthropic/claude-sonnet-5" } } });
+	assert.deepEqual(config.defaultModel, { provider: "openai-codex", id: "gpt-6-astra" });
+	assert.equal(config.defaultThinking, "medium");
+	assert.equal(config.maxConcurrency, 2);
+	assert.equal(config.stallTimeoutMs, 12_000);
+	assert.equal("timeoutMs" in config, false, "legacy timeout_ms must not become an active runtime setting");
+	assert.deepEqual(config.modelProfiles.explore, { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "low" });
+	assert.deepEqual(config.modelProfiles.worker, { model: { provider: "anthropic", id: "claude-sonnet-5" }, thinking: undefined });
+	const defaults = parseAgentsConfig(undefined, undefined);
+	assert.equal(defaults.maxConcurrency, 5);
+	assert.equal("timeoutMs" in defaults, false);
+	assert.equal(defaults.stallTimeoutMs, 4 * 60_000);
+	assert.equal(defaults.defaultMode, AGENT_MODE.TASK);
+	assert.equal(defaults.historyMaxTasks, 200);
+	assert.equal(parseAgentsConfig({ max_concurrency: "many", default_effort: "wild", default_mode: "background" }, undefined).maxConcurrency, 5);
+	assert.equal(parseAgentsConfig({ default_mode: "background" }, undefined).defaultMode, AGENT_MODE.BACKGROUND);
+});
+
+test("resolveAgentProfile prefers the profile, then the definition, then the defaults", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", model_profiles: { "gentle-ai-explore": { effort: "high" } } }, undefined);
+	const explore = parseAgentDefinition(EXPLORER, "/x/explore.md", "global");
+	assert.ok(!("error" in explore));
+	assert.deepEqual(resolveAgentProfile(explore, config), { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "high", source: { model: "definition", thinking: "profile" } });
+	const bare = parseAgentDefinition("---\nname: bare\n---\nbody", "/x/bare.md", "global");
+	assert.ok(!("error" in bare));
+	assert.deepEqual(resolveAgentProfile(bare, config), { model: { provider: "openai-codex", id: "gpt-6-astra" }, thinking: "medium", source: { model: "default", thinking: "default" } });
+	assert.deepEqual(resolveAgentProfile(bare, parseAgentsConfig(undefined, undefined)).source, { model: "unresolved", thinking: "unresolved" });
+});

package/tests/agents-fake-child.ts

@@ -0,0 +1,66 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildLike } from "../lib/agents-runner.ts";
+
+// A fake `pi --mode rpc` child: answers every command with a success
+// response, records what the host wrote, and lets tests emit events.
+
+export interface FakeChild {
+	child: ChildLike;
+	written: Array<Record<string, unknown>>;
+	emit(event: Record<string, unknown>): void;
+	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 {
+	const emitter = new EventEmitter();
+	const stdin = new PassThrough();
+	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();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const command = JSON.parse(line) as Record<string, unknown>;
+			written.push(command);
+			if (command.type === "extension_ui_response") continue;
+			const data = command.type === "get_state" ? { sessionFile: "/sessions/child.jsonl" } : undefined;
+			stdout.write(`${JSON.stringify({ type: "response", id: command.id, command: command.type, success: true, data })}\n`);
+		}
+	});
+	const child: ChildLike = {
+		pid: options.pid,
+		stdin,
+		stdout,
+		stderr: new PassThrough(),
+		kill: (signal) => {
+			killed.push(String(signal ?? "SIGTERM"));
+			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, 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-history.test.ts

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
+import { applyTaskEvent, emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+
+// Gentle Agents history: JSON per task, async, lazy, pruned by count.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-history-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+const dir = join(root, "tasks");
+
+function task(id: string, createdAt: number): TaskRecord {
+	return { id, agent: "explore", mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.COMPLETED, createdAt, startedAt: createdAt, endedAt: createdAt + 5, model: "m", thinking: undefined, sessionPath: null, error: null, result: "ok", lastStep: "done", lastActivityAt: createdAt, turns: 1, toolCalls: 0, tokens: 10, cost: 0.01 };
+}
+
+test("historyDir follows an isolated agent profile while explicit homes retain the default fallback", () => {
+	assert.equal(historyDir("/home/x", "/profiles/pi-principal/agent"), join("/profiles/pi-principal/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x", "/profiles/pi-lab/agent"), join("/profiles/pi-lab/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x"), join("/home/x", ".pi", "agent", "gentle-agents", "tasks"));
+});
+
+test("saveTask writes a task with its thread and loadStoredTask reads it back", async () => {
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.TEXT, text: "hello" });
+	await saveTask(dir, task("a1", 1000), thread);
+	const stored = await loadStoredTask(dir, "a1");
+	assert.equal(stored?.task.result, "ok");
+	assert.deepEqual(stored?.thread.items, [{ kind: "text", text: "hello" }]);
+	assert.equal(await loadStoredTask(dir, "missing"), undefined);
+	assert.equal(await loadStoredTask(dir, "../etc/passwd"), undefined);
+	assert.deepEqual(readdirSync(dir), ["a1.json"], "no temp file is left behind");
+});
+
+test("loadHistory skips broken files, sorts newest first, and pruneHistory keeps the newest N", async () => {
+	await saveTask(dir, task("b2", 3000), emptyThread());
+	await saveTask(dir, task("c3", 2000), emptyThread());
+	writeFileSync(join(dir, "junk.json"), "{not json");
+	writeFileSync(join(dir, "shape.json"), JSON.stringify({ task: { id: 1 } }));
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3", "a1"]);
+	assert.equal(await pruneHistory(dir, 2), 1);
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3"]);
+	assert.deepEqual(await loadHistory(join(root, "nowhere")), []);
+});
+
+test("TaskStore.restore adds a stored task without clobbering a live one", () => {
+	const store = new TaskStore();
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.NOTE, text: "restored" });
+	assert.equal(store.restore(task("r1", 1000), thread), true);
+	assert.equal(store.thread("r1").items.length, 1);
+	assert.equal(store.restore({ ...task("r1", 1000), result: "other" }, emptyThread()), false);
+	assert.equal(store.get("r1")?.result, "ok");
+});