gentle-pi 4.3.0 → 4.4.0

package/tests/agents-config.test.ts

@@ -14,6 +14,7 @@ import {
 	parseFrontmatter,
 	parseModelRef,
 	resolveAgentProfile,
+	unmatchedProfileKeys,
 	withPinnedModelProfiles,
 } from "../lib/agents-config.ts";
 import { THINKING_LEVELS } from "../lib/model-routing-authority.ts";
@@ -247,3 +248,63 @@ test("a pinned profile replaces subagent routing and leaves every other default
 	// repository can pin "everything inherits" without touching the global store.
 	assert.deepEqual(withPinnedModelProfiles(global, {}).modelProfiles, {});
 });
+
+// Issue #2196 rework (PR #2233 maintainer decision): role keys that name no
+// discovered agent must be reported, with a did-you-mean suggestion, instead of
+// being silently ignored while the child inherits the orchestrator model.
+test("unmatchedProfileKeys reports profile keys that match no discovered agent", () => {
+	const worker = {
+		name: "gentle-ai-worker",
+		description: "",
+		filePath: "/x/worker.md",
+		scope: "global" as const,
+		instructions: "",
+		model: undefined,
+		thinking: undefined,
+		mode: undefined,
+		tools: [],
+	};
+	const explore = { ...worker, name: "gentle-ai-explore" };
+	const profiles = {
+		worker: { model: { provider: "nan", id: "glm5.3" }, thinking: undefined },
+		WORKER: { model: { provider: "nan", id: "glm5.3" }, thinking: undefined },
+		review_risk: { model: undefined, thinking: "high" as const },
+		explore: { model: undefined, thinking: undefined },
+	};
+	assert.deepEqual(unmatchedProfileKeys(profiles, [worker, explore]), [
+		{ key: "worker", suggestion: "gentle-ai-worker" },
+		{ key: "WORKER", suggestion: "gentle-ai-worker" },
+		{ key: "review_risk", suggestion: undefined },
+		{ key: "explore", suggestion: "gentle-ai-explore" },
+	]);
+	// A key that exactly matches an agent name never reports, and an empty
+	// profile set reports nothing.
+	assert.deepEqual(unmatchedProfileKeys({ "gentle-ai-worker": { model: undefined, thinking: undefined } }, [worker]), []);
+	assert.deepEqual(unmatchedProfileKeys({}, [worker]), []);
+});
+
+// Cortex QA adversarial follow-up (R5 pin): the did-you-mean mapping exists to
+// make a misconfiguration visible, never to resolve; a short key must keep
+// yielding an unresolved profile so the role inherits frontmatter and default
+// routing exactly as before the fix.
+test("resolveAgentProfile never resolves through the suggestion mapping", () => {
+	const worker = {
+		name: "gentle-ai-worker",
+		description: "",
+		filePath: "/x/worker.md",
+		scope: "global" as const,
+		instructions: "",
+		model: { provider: "openai-codex", id: "gpt-5.6-terra" },
+		thinking: undefined,
+		mode: undefined,
+		tools: [],
+	};
+	const config = parseAgentsConfig(
+		{ model_profiles: { worker: { model: "nan/glm5.3", effort: "high" } } },
+		undefined,
+	);
+	const resolved = resolveAgentProfile(worker, config);
+	assert.equal(resolved.model?.provider, "openai-codex", "the short key must not route; the agent frontmatter model wins");
+	assert.equal(resolved.source.model, "definition");
+	assert.ok(unmatchedProfileKeys(config.modelProfiles, [worker]).some((entry) => entry.key === "worker" && entry.suggestion === "gentle-ai-worker"), "the same short key is still reported with its suggestion");
+});

package/tests/agents-fake-child.ts

@@ -17,7 +17,7 @@ export interface FakeChild {
 	message(event: Record<string, unknown>): void;
 }
 
-export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}): FakeChild {
+export function fakeChild(options: { exitOnKill?: boolean; exitOnStdinEnd?: boolean; pid?: number } = {}): FakeChild {
 	const emitter = new EventEmitter();
 	const stdin = new PassThrough();
 	const stdout = new PassThrough();
@@ -38,6 +38,13 @@ export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}):
 			stdout.write(`${JSON.stringify({ type: "response", id: command.id, command: command.type, success: true, data })}\n`);
 		}
 	});
+	const origEnd = stdin.end.bind(stdin);
+	stdin.end = ((...args: unknown[]) => {
+		const res = (origEnd as Function)(...args);
+		// Preserve existing fixtures while allowing EOF and signal exits to vary independently.
+		if (options.exitOnStdinEnd ?? options.exitOnKill ?? true) queueMicrotask(() => emitter.emit("exit", 0, null));
+		return res;
+	}) as typeof stdin.end;
 	const child: ChildLike = {
 		pid: options.pid,
 		stdin,

package/tests/agents-protocol.test.ts

@@ -10,7 +10,9 @@ import {
 	TASK_STATUS,
 	taskLabel,
 	TaskStore,
+	TERMINAL_RETENTION,
 	THREAD_ITEM,
+	isFinished,
 	type TaskRecord,
 } from "../lib/agents-protocol.ts";
 
@@ -274,6 +276,36 @@ test("TaskStore notifies only the listeners of the task that changed and keeps s
 	assert.deepEqual(store.thread("missing"), emptyThread());
 });
 
+// Finished tasks must release their weight: a bounded window of the most
+// recent ones stays readable, older ones leave the store entirely, and a
+// terminal task's listeners go quiet after the one final transition.
+test("TaskStore keeps a bounded window of finished tasks and silences terminal listeners", () => {
+	const store = new TaskStore();
+	const seen: string[] = [];
+	store.add(record({ id: "watched", status: TASK_STATUS.RUNNING, lastActivityAt: 1 }));
+	store.add(record({ id: "filler", status: TASK_STATUS.RUNNING, lastActivityAt: 2 }));
+	store.subscribe("watched", (task) => seen.push(task.status));
+	// `watched` completes the window once it finishes, so the next terminal
+	// task evicts exactly the oldest one.
+	for (let index = 0; index < TERMINAL_RETENTION - 1; index += 1) {
+		store.add(record({ id: `done-${index}`, status: TASK_STATUS.COMPLETED, lastActivityAt: 10 + index }));
+	}
+	assert.equal(store.list().filter((task) => isFinished(task.status)).length, TERMINAL_RETENTION - 1, "retained finished tasks stay at the cap");
+	assert.ok(store.get("watched") && store.get("filler"), "running tasks are never evicted");
+	store.update("watched", { status: TASK_STATUS.COMPLETED, endedAt: 50 });
+	assert.deepEqual(seen, ["completed"], "the terminal transition itself still notifies exactly once");
+	store.apply("watched", { type: TASK_EVENT.TEXT, text: "late" }, 60);
+	assert.deepEqual(seen, ["completed"], "a terminal task's listener stays quiet afterwards");
+	store.add(record({ id: "newest", status: TASK_STATUS.COMPLETED, lastActivityAt: 1_000 }));
+	assert.equal(store.get("done-0"), undefined, "the oldest finished task is evicted");
+	assert.ok(store.get("done-1") && store.get("newest"), "recent finished tasks remain readable");
+	assert.ok(store.get("filler"), "running tasks survive eviction");
+	assert.equal(store.list().filter((task) => isFinished(task.status)).length, TERMINAL_RETENTION);
+	assert.deepEqual(store.thread("done-0"), emptyThread(), "an evicted task's thread weight is released");
+	assert.ok(store.thread("done-1").limits.maxItems > 0, "a retained finished task stays renderable");
+	assert.equal(store.summary().finished, TERMINAL_RETENTION, "summaries reflect the bounded window");
+});
+
 test("TaskStore.apply moves the task to waiting on ask, back to running on any later event, and counts turns", () => {
 	const store = new TaskStore();
 	store.add(record({ id: "a", status: TASK_STATUS.RUNNING }));

package/tests/agents-runner.test.ts

@@ -34,7 +34,7 @@ interface Harness {
 	advance(ms: number): void;
 }
 
-function harness(options: { resolvePi?: RunnerDeps["resolvePi"]; failStart?: boolean; process?: RunnerDeps["process"]; pid?: number; maxConcurrency?: number; stallTimeoutMs?: number; toolStallTimeoutMs?: number; answer?: Record<string, unknown>; exitOnKill?: boolean; state?: Record<string, unknown>; stateSuccess?: boolean; onNotification?: RunnerHooks["onNotification"]; onSuccessfulMutation?: RunnerHooks["onSuccessfulMutation"]; onFinish?: RunnerHooks["onFinish"] } = {}): Harness {
+function harness(options: { resolvePi?: RunnerDeps["resolvePi"]; failStart?: boolean; process?: RunnerDeps["process"]; pid?: number; maxConcurrency?: number; stallTimeoutMs?: number; toolStallTimeoutMs?: number; cleanupTimeoutMs?: number; answer?: Record<string, unknown>; exitOnKill?: boolean; exitOnStdinEnd?: boolean; state?: Record<string, unknown>; stateSuccess?: boolean; onNotification?: RunnerHooks["onNotification"]; onSuccessfulMutation?: RunnerHooks["onSuccessfulMutation"]; onFinish?: RunnerHooks["onFinish"] } = {}): Harness {
 	const children: FakeChild[] = [];
 	const timers: Harness["timers"] = [];
 	const asks: Harness["asks"] = [];
@@ -48,7 +48,7 @@ function harness(options: { resolvePi?: RunnerDeps["resolvePi"]; failStart?: boo
 		spawn: (command, args, launchOptions) => {
 			if (options.failStart) throw new Error("fixture spawn failed");
 			spawnOptions.push({ command, args, env: launchOptions.env, stdio: launchOptions.stdio });
-			const fake = fakeChild({ exitOnKill: options.exitOnKill, pid: options.pid });
+			const fake = fakeChild({ exitOnKill: options.exitOnKill, exitOnStdinEnd: options.exitOnStdinEnd, pid: options.pid });
 			if (options.state !== undefined) {
 				fake.child.stdin.removeAllListeners("data");
 				fake.child.stdin.on("data", (chunk) => {
@@ -73,7 +73,7 @@ function harness(options: { resolvePi?: RunnerDeps["resolvePi"]; failStart?: boo
 		pi: { command: "pi", args: [] },
 	};
 	const store = new TaskStore();
-	const runner = new AgentRunner(store, { maxConcurrency: options.maxConcurrency ?? 2, stallTimeoutMs: options.stallTimeoutMs ?? 10_000, toolStallTimeoutMs: options.toolStallTimeoutMs }, deps, {
+	const runner = new AgentRunner(store, { maxConcurrency: options.maxConcurrency ?? 2, stallTimeoutMs: options.stallTimeoutMs ?? 10_000, toolStallTimeoutMs: options.toolStallTimeoutMs, cleanupTimeoutMs: options.cleanupTimeoutMs }, deps, {
 		askUser: async (taskId, ask) => {
 			asks.push({ taskId, method: ask.method });
 			return options.answer ?? { value: "yes" };
@@ -95,6 +95,87 @@ function harness(options: { resolvePi?: RunnerDeps["resolvePi"]; failStart?: boo
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 
+for (const mode of [AGENT_MODE.TASK, AGENT_MODE.BACKGROUND]) {
+	for (const policy of [undefined, "off", "malformed"] as const) {
+		test(`background capability admission rejects ${mode} with ${policy ?? "default"} policy`, async (t) => {
+			const root = fs.mkdtempSync(join(tmpdir(), "admission-"));
+			t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+			const config = join(root, "config");
+			const file = join(config, "background-subagents.json");
+			fs.mkdirSync(config);
+			const raw = policy === "malformed" ? "{broken" : JSON.stringify({ schema: "gentle-pi.background-subagents/v1", policy });
+			if (policy) fs.writeFileSync(file, raw);
+			const h = harness({ maxConcurrency: 1 });
+			let launches = 0;
+			const env = { GENTLE_PI_CONFIG_HOME: config, ...(policy === "malformed" ? { GENTLE_PI_BACKGROUND_SUBAGENTS: "on" } : {}) };
+			const task = h.runner.run(request({ cwd: root, env, mode, agent: { ...explorer, tools: ["read", "bash_background"] }, onLaunch: () => { launches++; } }));
+			await tick();
+			assert.equal(h.store.get(task.id)?.status, TASK_STATUS.FAILED);
+			const target = policy ? file : join(root, ".pi", "gentle-ai", "background-subagents.json");
+			assert.equal(h.store.get(task.id)?.error, `could not start pi: explicit tool bash_background requires background-subagents policy on. Set ${target} to {"schema":"gentle-pi.background-subagents/v1","policy":"on"}; inspect or change policy with /gentle:background-subagents enable|disable|status.`);
+			assert.equal(h.children.length, 0);
+			assert.equal(h.spawnOptions.length, 0);
+			assert.equal(h.timers.length, 0);
+			assert.equal(launches, 0);
+			assert.deepEqual(h.finishes, [task.id]);
+			assert.equal((await h.runner.waitFor(task.id)).status, TASK_STATUS.FAILED);
+			assert.equal(existsSync(file), policy !== undefined);
+			if (policy) assert.equal(readFileSync(file, "utf8"), raw);
+			const next = h.runner.run(request({ cwd: root, env }));
+			await tick();
+			assert.equal(h.store.get(next.id)?.status, TASK_STATUS.RUNNING);
+			h.runner.cancel(next.id);
+			await tick();
+		});
+	}
+}
+
+for (const { tools, policy } of [
+	...[undefined, "off"].flatMap(policy => [["read", "unknown_tool"], []].map(tools => ({ tools, policy }))),
+	{ tools: ["read", "bash_background", "grep"], policy: "on" },
+]) {
+	test(`background capability admission preserves launch for ${tools.join(",") || "default tools"} with ${policy ?? "default off"} policy`, async (t) => {
+		const root = fs.mkdtempSync(join(tmpdir(), "admission-"));
+		t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+		const h = harness();
+		const env = { GENTLE_PI_CONFIG_HOME: join(root, "config"), ...(policy === undefined ? {} : { GENTLE_PI_BACKGROUND_SUBAGENTS: policy }), KEEP: "yes" };
+		const task = h.runner.run(request({ cwd: root, env, agent: { ...explorer, tools } }));
+		await tick();
+		assert.equal(h.store.get(task.id)?.status, TASK_STATUS.RUNNING);
+		assert.equal(h.store.get(task.id)?.error, null);
+		assert.equal(h.children.length, 1);
+		const expected = tools.length ? [...tools, "subagent_parent_message"].join(",") : undefined;
+		assert.equal(h.spawnOptions[0].env[REQUESTED_TOOLS_ENV], expected);
+		assert.equal(h.spawnOptions[0].env.KEEP, "yes");
+		assert.deepEqual(h.spawnOptions[0].args, childArguments(request({ cwd: root, env, agent: { ...explorer, tools } })));
+		assert.equal(h.timers.filter(timer => !timer.cancelled).length, 1);
+		h.runner.cancel(task.id);
+		await tick();
+	});
+}
+
+test("background capability admission refreshes project policy when queued work dispatches", async (t) => {
+	const root = fs.mkdtempSync(join(tmpdir(), "admission-"));
+	t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+	const dir = join(root, ".pi", "gentle-ai");
+	fs.mkdirSync(dir, { recursive: true });
+	const file = join(dir, "background-subagents.json");
+	const h = harness({ maxConcurrency: 1 });
+	const env = { GENTLE_PI_CONFIG_HOME: join(root, "config"), GENTLE_PI_BACKGROUND_SUBAGENTS: "on" };
+	const first = h.runner.run(request({ cwd: root, env }));
+	const queued = h.runner.run(request({ cwd: root, env, agent: { ...explorer, tools: ["bash_background"] } }));
+	await tick();
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.QUEUED);
+	const raw = '{"schema":"gentle-pi.background-subagents/v1","policy":"off"}';
+	fs.writeFileSync(file, raw);
+	h.runner.cancel(first.id);
+	await tick();
+	assert.equal(h.store.get(queued.id)?.status, TASK_STATUS.FAILED);
+	assert.equal(h.store.get(queued.id)?.error, `could not start pi: explicit tool bash_background requires background-subagents policy on. Set ${file} to {"schema":"gentle-pi.background-subagents/v1","policy":"on"}; inspect or change policy with /gentle:background-subagents enable|disable|status.`);
+	assert.equal(h.children.length, 1);
+	assert.equal(readFileSync(file, "utf8"), raw);
+});
+
 const FOUR_MIN_MS = 4 * 60_000;
 
 function argumentUpdate(type: string, fields: Record<string, unknown> = {}): Record<string, unknown> {
@@ -923,7 +1004,8 @@ test("AgentRunner runs a task end to end: prompt, deltas into the store, complet
 	assert.equal(finished?.toolCalls, 1);
 	assert.equal(finished?.sessionPath, "/sessions/child.jsonl");
 	assert.equal(finished?.label, "Map the repo");
-	assert.ok(children[0].killed.length > 0, "the child is stopped once the answer is in");
+	assert.ok(children[0].child.stdin.writableEnded, "the child is stopped via orderly shutdown once the answer is in");
+	assert.equal(children[0].killed.length, 0, "no kill signals sent during orderly settlement");
 	assert.equal(store.thread(task.id).items.length, 2);
 	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.COMPLETED);
 });
@@ -973,6 +1055,143 @@ test("AgentRunner queues beyond max concurrency and starts the next task when on
 	assert.equal(store.get(second.id)?.status, TASK_STATUS.RUNNING);
 });
 
+test("AgentRunner requests orderly shutdown via stdin on settlement and does not send SIGTERM immediately (#1740)", async () => {
+	const { store, runner, children } = harness({ exitOnKill: false });
+	const task = runner.run(request());
+	await tick();
+	assert.equal(children.length, 1);
+	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "Done" }] }] });
+	await tick();
+	assert.equal(children[0].killed.length, 0);
+	children[0].emit({ type: "agent_settled" });
+	await tick();
+
+	// Orderly shutdown must have requested stdin.end()
+	assert.equal(children[0].child.stdin.writableEnded, true, "stdin must be ended on settlement to trigger Pi orderly shutdown");
+	// Must NOT send SIGTERM immediately
+	assert.deepEqual(children[0].killed, [], "SIGTERM must not be sent immediately upon settlement");
+	// Task completion and cleanup in flight should be distinguishable
+	assert.equal(store.get(task.id)?.lastStep, "cleaning up", "lastStep distinguishes in-flight cleanup");
+	assert.equal(store.get(task.id)?.status, TASK_STATUS.RUNNING, "task waits for cleanup exit");
+
+	// Child exits cleanly upon session_shutdown completion
+	children[0].exit(0);
+	await tick();
+	await tick();
+	assert.equal(store.get(task.id)?.status, TASK_STATUS.COMPLETED);
+	assert.equal(store.get(task.id)?.lastStep, "done");
+	assert.deepEqual(children[0].killed, [], "clean shutdown completes with zero kill signals sent");
+});
+
+test("AgentRunner allows delayed cleanup and cancels escalation after clean exit (#1740)", async () => {
+	// EOF must be independent of kill behavior: this child honors signals but
+	// needs time to finish asynchronous shutdown after its input closes.
+	const { store, runner, children, timers, advance, finishes } = harness({ exitOnStdinEnd: false });
+	const task = runner.run(request());
+	await tick();
+	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "Done" }] }] });
+	children[0].emit({ type: "agent_settled" });
+	await tick();
+	assert.equal(children[0].child.stdin.writableEnded, true);
+	advance(2_000);
+	await tick();
+	assert.equal(store.get(task.id)?.status, TASK_STATUS.RUNNING);
+	assert.equal(store.get(task.id)?.lastStep, "cleaning up");
+	assert.deepEqual(children[0].killed, []);
+	assert.deepEqual(finishes, []);
+	children[0].exit(0);
+	await tick();
+	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.COMPLETED);
+	assert.equal(store.get(task.id)?.lastStep, "done");
+	assert.deepEqual(finishes, [task.id]);
+	assert.ok(timers.filter((timer) => timer.ms === 5_000).every((timer) => timer.cancelled));
+	advance(5_000);
+	await tick();
+	assert.deepEqual(children[0].killed, []);
+	assert.deepEqual(finishes, [task.id]);
+});
+
+test("AgentRunner escalates to SIGTERM and SIGKILL if orderly cleanup exceeds cleanupTimeoutMs (#1740)", async () => {
+	const { store, runner, children, timers } = harness({ exitOnKill: false, cleanupTimeoutMs: 3000 });
+	const task = runner.run(request());
+	await tick();
+	assert.equal(children.length, 1);
+	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "Done" }] }] });
+	await tick();
+	children[0].emit({ type: "agent_settled" });
+	await tick();
+
+	assert.equal(children[0].child.stdin.writableEnded, true);
+	assert.deepEqual(children[0].killed, []);
+
+	// Find the cleanup timeout timer (3000 ms) and trigger it
+	const cleanupTimer = timers.find((timer) => !timer.cancelled && timer.ms === 3000);
+	assert.ok(cleanupTimer, "cleanup timeout timer must be scheduled");
+	cleanupTimer.fn();
+	await tick();
+
+	// Escalation has fired SIGTERM
+	assert.deepEqual(children[0].killed, ["SIGTERM"]);
+
+	// And termination grace timer (250 ms) is scheduled for SIGKILL
+	const killTimer = timers.find((timer) => !timer.cancelled && timer.ms === 250);
+	assert.ok(killTimer, "SIGKILL escalation timer must be scheduled");
+	killTimer.fn();
+	await tick();
+
+	assert.deepEqual(children[0].killed, ["SIGTERM", "SIGKILL"]);
+});
+
+test("orderly cleanup escalation retains the full exit confirmation deadline after SIGKILL (#1740)", async () => {
+	let groupAlive = true;
+	const { store, runner, children, timers, advance } = harness({
+		exitOnKill: false,
+		pid: 42,
+		cleanupTimeoutMs: 5_000,
+		process: {
+			platform: "linux",
+			kill: () => {
+				if (!groupAlive) throw Object.assign(new Error(), { code: "ESRCH" });
+				return true;
+			},
+		},
+	});
+	const task = runner.run(request());
+	await tick();
+	assert.equal(children.length, 1);
+	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "Done" }] }] });
+	await tick();
+	children[0].emit({ type: "agent_settled" });
+	await tick();
+
+	// Advance time by the cleanup window (5000 ms)
+	const cleanupTimer = timers.find((t) => !t.cancelled && t.ms === 5_000);
+	assert.ok(cleanupTimer, "cleanup timeout timer must be scheduled");
+	advance(5_000);
+	await tick();
+
+	// Advance time by termination grace (250 ms)
+	const killTimer = timers.find((t) => !t.cancelled && t.ms === 250);
+	assert.ok(killTimer, "SIGKILL timer must be scheduled");
+	advance(250);
+	await tick();
+
+	// After SIGKILL, confirmGroupExit checks the process group. Because cleanupDeadlineAt was set
+	// at SIGKILL time, it must NOT immediately fail with capacity quarantined!
+	assert.equal(store.get(task.id)?.status, TASK_STATUS.RUNNING, "must not prematurely quarantine after cleanup window");
+	const probeTimer = timers.find((t) => !t.cancelled && t.ms === 25);
+	assert.ok(probeTimer, "exit confirmation polling timer must be scheduled");
+
+	// If the group exits during the confirmation window:
+	groupAlive = false;
+	children[0].exit(0);
+	advance(25);
+	await tick();
+
+	assert.equal(store.get(task.id)?.status, TASK_STATUS.COMPLETED);
+	assert.equal(store.get(task.id)?.error, null);
+});
+
 test("AgentRunner classifies terminal assistant outcomes only after settlement", async () => {
 	const scenarios = [
 		{ name: "error", messages: [{ role: "assistant", content: [], stopReason: "error", errorMessage: "WebSocket error: secret=never-copy" }], status: TASK_STATUS.FAILED, error: /assistant reported an error/ },
@@ -1136,7 +1355,9 @@ test("AgentRunner retains permission broker fd3 and assigns messaging IPC to fd4
 	const launch = spawnOptions[0];
 	const permissionChannelStdio = process.platform === "win32" ? "overlapped" : "pipe";
 	assert.match(launch?.env.GENTLE_PI_AGENTS_OWNED_IPC ?? "", /^\d+-[a-z0-9]+$/, "the owned-IPC marker has the runner's opaque shape");
-	assert.deepEqual(launch?.env, { GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: launch?.env.GENTLE_PI_AGENTS_OWNED_IPC, GENTLE_PI_AGENTS_PARENT_PERMISSION_FD: "3", [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message", TMPDIR: launch?.env.TMPDIR });
+	const scratch = launch?.env.TMPDIR;
+	const scratchEnv = process.platform === "win32" ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : { TMPDIR: scratch };
+	assert.deepEqual(launch?.env, { GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: launch?.env.GENTLE_PI_AGENTS_OWNED_IPC, GENTLE_PI_AGENTS_PARENT_PERMISSION_FD: "3", [REQUESTED_TOOLS_ENV]: "read,grep,subagent_parent_message", ...scratchEnv });
 	assert.match(basename(launch?.env.TMPDIR ?? ""), /^ga[A-Za-z0-9]{6}$/);
 	assert.deepEqual(launch?.stdio, ["pipe", "pipe", "pipe", permissionChannelStdio, "ipc"]);
 	assert.equal(launch?.stdio?.length, 5);

package/tests/agents-session-transport.test.ts

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { once } from "node:events";
 import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
-import { createConnection, createServer, Socket } from "node:net";
+import { createConnection, createServer, Socket, type Server } from "node:net";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import nodeTest, { type TestContext } from "node:test";
@@ -124,7 +124,12 @@ test("lists only advertised peer IDs without mutating the private registry", asy
 	assert.equal(await snapshot(), before, "listing leaves presence files, directory modes, and socket entries unchanged");
 	assert.equal(alphaNew.createdAt >= alphaOld.createdAt, true);
 	for (let index = 0; index < 65; index++) await transport.publish(await transport.record(`overflow-${index}`, index));
-	await rejected(transport.list(), "busy");
+	// The over-cap scan sweeps provably dead records once instead of failing
+	// busy: the overflow endpoints were never bound, and the missing/malformed/
+	// symlinked fixtures are debris too. Live peers stay listed.
+	assert.deepEqual(await transport.list(self.sessionId), [{ sessionId: "alpha", reachability: "unknown" }]);
+	const remaining = (await readdir(transport.paths.presence)).sort();
+	assert.equal(remaining.length, 3, "only the live records (self, alpha twice) survive the sweep");
 });
 
 test("keeps same-session activations distinct and old cleanup preserves the newest", async (t) => {
@@ -161,7 +166,52 @@ test("isolates two sessions and bounds registry discovery at 65 entries", async
 	assert.deepEqual(await transport.resolve("left"), left);
 	assert.deepEqual(await transport.resolve("right"), right);
 	for (let index = 0; index < 65; index++) await transport.publish(await transport.record("capped", index));
-	await rejected(transport.resolve("capped"), "busy");
+	// The dead-endpoint overflow is swept on the first over-cap scan, so the
+	// retry resolves the truth (nothing left) instead of failing busy.
+	await rejected(transport.resolve("capped"), "not_found");
+	assert.equal((await readdir(transport.paths.presence)).length, 0, "dead overflow records are swept, never retained");
+});
+
+test("foreign-schema presence files never count toward the activation cap", async (t) => {
+	const transport = await registry(t);
+	// The orchestrator publisher shares this directory with a different naming
+	// schema (<sessionHash>.<incarnation>.<kind>.json, three files per peer),
+	// and long-lived profiles accumulate hundreds of those records. They are
+	// never transport activations, so they must not trip the spam guard.
+	const incarnation = (index: number) => `00000000-0000-4000-8000-${index.toString().padStart(12, "0")}`;
+	for (let index = 0; index < 80; index++) {
+		for (const kind of ["header", "activity", "discovery"]) {
+			await writeFile(join(transport.paths.presence, `${"b".repeat(64)}.${incarnation(index)}.${kind}.json`), "{}");
+		}
+	}
+	const self = await raw(t, transport, "self", null);
+	const peer = await raw(t, transport, "peer", null);
+	assert.deepEqual(await transport.list(self.sessionId), [{ sessionId: "peer", reachability: "unknown" }], "listing survives a foreign-schema flood and still sees real activations");
+	assert.deepEqual(await transport.resolve("peer"), peer);
+	// The cap still bounds real transport activations exactly as before: the
+	// 65 advertised dead-endpoint records overflow the guard, the sweep removes
+	// them, and the live peers remain discoverable afterwards.
+	for (let index = 0; index < 65; index++) await transport.publish(await transport.record("capped", index + 10));
+	assert.deepEqual(await transport.list(self.sessionId), [{ sessionId: "peer", reachability: "unknown" }], "dead overflow is swept once and the live peer stays discoverable");
+	await rejected(transport.resolve("capped"), "not_found");
+});
+
+// The sweep must never trade the spam guard for liveness probing: a genuine
+// flood of records backed by real listening sockets stays over the cap, keeps
+// failing busy, and its records are never removed.
+test("a flood of live listeners stays over the cap and keeps failing busy", async (t) => {
+	const transport = await registry(t);
+	const servers: Server[] = [];
+	t.after(() => { for (const server of servers) server.close(); });
+	for (let index = 0; index < 66; index++) {
+		const record = await transport.record(`flood-${index}`, index);
+		const server = createServer(() => {});
+		await new Promise<void>((resolveListen, rejectListen) => { server.once("error", rejectListen); server.listen(record.endpoint, resolveListen); });
+		servers.push(server);
+		await transport.publish(record);
+	}
+	await rejected(transport.list(), "busy");
+	assert.equal((await readdir(transport.paths.presence)).length, 66, "live records are never swept");
 });
 
 test("rejects unsafe IDs, v1 schema violations, prototypes, and content-leaking errors", async (t) => {

package/tests/ask-user-choice.test.ts

@@ -33,6 +33,7 @@ interface ChoiceTool {
 	promptGuidelines?: string[];
 	parameters: ChoiceParameters;
 	execute: (...args: unknown[]) => Promise<ChoiceResult>;
+	renderResult?: (result: unknown, options: unknown, theme: ChoiceTheme) => { render(width: number): string[] };
 }
 
 interface ChoiceLifecycleEvent {
@@ -711,3 +712,32 @@ test("ask_user_choice is offered on an interactive rpc host and withdrawn once t
 	for (const hook of registration.hooks) await hook({}, { mode: "rpc" });
 	assert.deepEqual(registration.activeTools(), ["read"]);
 });
+
+test("ask_user_choice renderResult renders selected, custom response with text, and cancelled states (#1692)", () => {
+	const registration = registerChoiceTool();
+	const theme: ChoiceTheme = { fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text };
+
+	// 1. Selected option
+	const selected = registration.tool.renderResult!(
+		{ details: { selection: { index: 1, label: "Deploy to production" } } },
+		{},
+		theme,
+	).render(80).join("\n");
+	assert.match(selected, /✓ 1\. Deploy to production/);
+
+	// 2. Custom response with submitted text (#1692)
+	const custom = registration.tool.renderResult!(
+		{ details: { customResponse: "use the staging bucket" } },
+		{},
+		theme,
+	).render(80).join("\n");
+	assert.match(custom, /✓ Custom response — use the staging bucket/);
+
+	// 3. Cancelled
+	const cancelled = registration.tool.renderResult!(
+		{ details: { cancelled: true } },
+		{},
+		theme,
+	).render(80).join("\n");
+	assert.match(cancelled, /Cancelled/);
+});

package/tests/auto-mode.test.ts

@@ -42,6 +42,23 @@ test("Auto cannot bypass data-loss, configured confirmation, protected paths or
  assert.equal(h.requests.length,0);
 });
 
+test("production hook classifies companion updates without granting permission to change authority",async t=>{
+ const h=harness(t);await h.enable();await h.input("Update the installed companion tools from main; preserve permissions.");
+ for(const toolName of ["write","edit"]) {
+  assert.equal(await h.call(toolName,{path:join(h.home,"dev-binary.json"),content:"fixture companion update"}),undefined);
+ }
+ assert.equal(h.requests.length,2,"updates reach the ordinary Auto classifier");
+ h.setDecision("deny");
+ assert.equal((await h.call("write",{path:join(h.home,"channel.json"),content:"unapproved"})).block,true);
+ assert.equal(h.requests.length,3);
+ h.setDecision("allow");
+ for(const name of ["permission-mode.json","runtime-guardrails.json","models.json","persona.json"]) {
+  assert.equal((await h.call("write",{path:join(h.home,name),content:"{}"})).block,true);
+ }
+ assert.equal(h.requests.length,3,"a classifier allow cannot override protected authority");
+ assert.equal(h.confirmations(),0);
+});
+
 test("normal mode preserves previous guard behavior and named children do not inherit Auto",async t=>{
  const h=harness(t);assert.equal((await h.call("bash",{command:"git push origin feature"})).block,true);assert.equal(h.requests.length,0);
  await h.enable();await h.emit("before_agent_start",{agent:{name:"worker"},systemPromptOptions:{}});

package/tests/auto-permission-memory-diagnostics.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AutoPermissionMemory } from "../lib/auto-permission-memory.ts";
+test("binder diagnostics retain rejection cause without destination or content",()=>{
+ const memory=new AutoPermissionMemory(()=>[]);
+ const ctx:any={cwd:"PRIVATE_CWD",sessionManager:{getSessionId:()=>"PRIVATE_SESSION",getBranch:()=>[{id:"PRIVATE_ANCHOR"}]}};
+ memory.admitted({toolName:"mem_current_project",toolCallId:"PRIVATE_CALL",input:{cwd:ctx.cwd}},ctx,1);
+ memory.context({toolName:"mem_save",input:{cwd:ctx.cwd,project:"PRIVATE_PROJECT",content:"PRIVATE_CONTENT"}},ctx,1);
+ assert.deepEqual(memory.diagnostic(),{stage:"admission",reason:"untrusted-source",sourceRejection:"tool-missing"});
+ assert.doesNotMatch(JSON.stringify(memory.diagnostic()),/PRIVATE/);
+ memory.clear();
+ memory.context({toolName:"mem_session_summary",input:{}},ctx,1);
+ assert.deepEqual(memory.diagnostic(),{stage:"clear",reason:"binding-cleared"});
+});
+
+test("source rejection reports only the first failed provenance predicate",()=>{
+ const sourceInfo={path:"/installed/engram.ts",source:"npm:gentle-engram@latest",scope:"user",origin:"package"};
+ const tool={name:"mem_current_project",sourceInfo};
+ const cases:[string,any[]][]=[
+  ["tool-missing",[]],["tool-ambiguous",[tool,tool]],
+  ["metadata-missing",[{name:tool.name}]],
+  ["origin",[{...tool,sourceInfo:{...sourceInfo,origin:"top-level",source:"local"}}]],
+  ["source-format",[{...tool,sourceInfo:{...sourceInfo,source:"PRIVATE_SOURCE"}}]],
+  ["path",[{...tool,sourceInfo:{...sourceInfo,path:"<PRIVATE_PATH>"}}]],
+ ];
+ const ctx:any={cwd:"/project",sessionManager:{getSessionId:()=>"session",getBranch:()=>[{id:"human"}]}};
+ const call={toolName:tool.name,toolCallId:"resolve",input:{cwd:ctx.cwd}};
+ for(const [sourceRejection,tools] of cases){
+  const memory=new AutoPermissionMemory(()=>tools);
+  memory.admitted(call,ctx,1);
+  assert.deepEqual(memory.diagnostic(),{stage:"admission",reason:"untrusted-source",sourceRejection});
+  memory.context({toolName:"mem_save",input:{}},ctx,1);
+  assert.equal(memory.diagnostic()?.sourceRejection,sourceRejection);
+  assert.doesNotMatch(JSON.stringify(memory.diagnostic()),/PRIVATE/);
+ }
+ const memory=new AutoPermissionMemory(()=>[tool] as any);
+ memory.admitted(call,ctx,1);
+ assert.deepEqual(memory.diagnostic(),{stage:"admission",reason:"admitted"});
+});
+
+test("registry exceptions replace successful attachment diagnostics",()=>{
+ let fail=false;
+ const sourceInfo={path:"/installed/engram.ts",source:"npm:gentle-engram",scope:"user",origin:"package"};
+ const memory=new AutoPermissionMemory(()=>{if(fail)throw Error("PRIVATE_ERROR");return ["mem_current_project","mem_save"].map(name=>({name,sourceInfo})) as any;});
+ const ctx:any={cwd:"/project",sessionManager:{getSessionId:()=>"session",getBranch:()=>[{id:"human"}]}};
+ const call={toolName:"mem_current_project",toolCallId:"resolve",input:{cwd:ctx.cwd}};
+ memory.admitted(call,ctx,1);
+ memory.result({...call,isError:false,details:{data:{cwd:ctx.cwd,project:"project",project_source:"git_remote"}}} as any,ctx,1);
+ const save={toolName:"mem_save",input:{cwd:ctx.cwd,project:"project"}};
+ assert.ok(memory.context(save,ctx,1));
+ assert.deepEqual(memory.diagnostic(),{stage:"write",reason:"attached"});
+ fail=true;
+ assert.equal(memory.context(save,ctx,1),undefined);
+ assert.deepEqual(memory.diagnostic(),{stage:"write",reason:"unexpected-error"});
+ assert.doesNotMatch(JSON.stringify(memory.diagnostic()),/PRIVATE/);
+});