gentle-pi 2.5.0 → 2.6.0

package/tests/agents-runner.test.ts

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
-import { TASK_STATUS, TaskStore } from "../lib/agents-protocol.ts";
-import { AgentRunner, childArguments, JsonLines, piCommand, type RunnerDeps, type TaskRequest } from "../lib/agents-runner.ts";
+import { AGENT_MODE, parseAgentsConfig, resolveAgentProfile, type AgentDefinition } from "../lib/agents-config.ts";
+import { TASK_STATUS, TaskStore, type RemediationTaskState, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentRunner, childArguments, JsonLines, piCommand, abortReasonText, type RemediationPlan, type RemediationTerminalFacts, type RunnerDeps, type RunnerHooks, type TaskRequest } from "../lib/agents-runner.ts";
 import { fakeChild, type FakeChild } from "./agents-fake-child.ts";
 
 // Gentle Agents runner: every subagent is a child `pi --mode rpc` process.
@@ -22,10 +22,10 @@ interface Harness {
 	timers: Array<{ fn: () => void; ms: number; cancelled: boolean }>;
 	asks: Array<{ taskId: string; method: string }>;
 	finishes: string[];
-	spawnOptions: Array<{ stdio?: string[] }>;
+	spawnOptions: Array<{ env: NodeJS.ProcessEnv; stdio?: string[] }>;
 }
 
-function harness(options: { maxConcurrency?: number; answer?: Record<string, unknown>; exitOnKill?: boolean } = {}): Harness {
+function harness(options: { pid?: number; maxConcurrency?: number; answer?: Record<string, unknown>; exitOnKill?: 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"] = [];
@@ -34,8 +34,17 @@ function harness(options: { maxConcurrency?: number; answer?: Record<string, unk
 	let clock = 1000;
 	const deps: RunnerDeps = {
 		spawn: (_command, _args, launchOptions) => {
-			spawnOptions.push({ stdio: launchOptions.stdio });
-			const fake = fakeChild({ exitOnKill: options.exitOnKill });
+			spawnOptions.push({ env: launchOptions.env, stdio: launchOptions.stdio });
+			const fake = fakeChild({ exitOnKill: options.exitOnKill, pid: options.pid });
+			if (options.state !== undefined) {
+				fake.child.stdin.removeAllListeners("data");
+				fake.child.stdin.on("data", (chunk) => {
+					const command = JSON.parse(String(chunk));
+					fake.written.push(command);
+					fake.emit({ type: "response", id: command.id, success: command.type !== "get_state" || options.stateSuccess !== false,
+						data: command.type === "get_state" ? options.state : undefined });
+				});
+			}
 			children.push(fake);
 			return fake.child;
 		},
@@ -55,19 +64,300 @@ function harness(options: { maxConcurrency?: number; answer?: Record<string, unk
 			asks.push({ taskId, method: ask.method });
 			return options.answer ?? { value: "yes" };
 		},
-		onFinish: (task) => finishes.push(task.id),
+		onFinish: (task, observations) => { finishes.push(task.id); options.onFinish?.(task, observations); },
+		onNotification: options.onNotification,
+		onSuccessfulMutation: options.onSuccessfulMutation,
 	});
 	return { store, runner, children, timers, asks, finishes, spawnOptions };
 }
 
 const tick = () => new Promise((resolve) => setImmediate(resolve));
 
+test("synchronous cancellation before dequeue never invokes the policy callback", async () => {
+	const h = harness(); let checks = 0;
+	const task = h.runner.run(request({ prepareResponseObservations: async () => { checks++; return true; } }));
+	h.runner.cancel(task.id);
+	await tick();
+	assert.equal(checks, 0);
+	assert.equal(h.children.length, 0);
+});
+
+test("hanging preparation never blocks spawn or queued core work; late grants are dropped", async () => {
+	const h = harness({ maxConcurrency: 1 });
+	let grant!: (value: boolean) => void;
+	let checks = 0;
+	const first = h.runner.run(request({ prepareResponseObservations: () => { checks++; return new Promise(resolve => { grant = resolve; }); } }));
+	const second = h.runner.run(request());
+	await tick();
+	assert.equal(checks, 1);
+	assert.equal(h.children.length, 1);
+	assert.equal(h.store.get(second.id)?.status, TASK_STATUS.QUEUED);
+	assert.equal(h.runner.cancel(first.id), true);
+	await tick();
+	assert.equal(h.children.length, 2);
+	grant(true);
+	await tick();
+	assert.equal(h.children.length, 2);
+	assert.equal((await h.runner.waitFor(first.id)).status, TASK_STATUS.CANCELLED);
+	h.runner.cancel(second.id);
+});
+
+for (const outcome of ["ready", "late", "reject", "throw"] as const) {
+	test(`parallel preparation ${outcome} cannot delay execution or revive dropped observations`, async () => {
+		const snapshots: Parameters<NonNullable<RunnerHooks["onFinish"]>>[1][] = [];
+		const h = harness({ onFinish: (_task, snapshot) => snapshots.push(snapshot) });
+		let grant!: (value: boolean) => void;
+		const task = h.runner.run(request({ prepareResponseObservations: () => {
+			if (outcome === "throw") throw new Error("preparation failed");
+			if (outcome === "reject") return Promise.reject(new Error("preparation failed"));
+			return new Promise(resolve => { grant = resolve; });
+		} }));
+		await tick();
+		assert.equal(h.children.length, 1);
+		if (outcome === "ready") { grant(true); await tick(); }
+		const message = { type: "message_end", message: { role: "assistant", provider: "openai", model: "gpt-4o", stopReason: "stop", content: [{ type: "text", text: "done" }] } };
+		h.children[0].emit(message);
+		if (outcome === "late") { grant(true); await tick(); }
+		h.children[0].emit(message);
+		h.children[0].emit({ type: "agent_end" });
+		h.children[0].emit({ type: "agent_settled" });
+		await h.runner.waitFor(task.id);
+		assert.equal(snapshots.length, 1);
+		assert.equal(snapshots[0]?.responses.length, outcome === "ready" ? 2 : undefined);
+	});
+}
+
+for (const checkpoint of ["launch", "stream", "finish", "throw"] as const) {
+	test(`child observation guard discards permanently at ${checkpoint} without changing task execution`, async () => {
+		let allowed = checkpoint !== "launch";
+		let calls = 0;
+		const snapshots: Parameters<NonNullable<RunnerHooks["onFinish"]>>[1][] = [];
+		const h = harness({ onFinish: (_task, snapshot) => snapshots.push(snapshot) });
+		const task = h.runner.run(request({ collectResponseObservations: true,
+			canCollectResponseObservations: () => {
+				calls++;
+				if (checkpoint === "throw") throw new Error("private policy failure");
+				return allowed;
+			} }));
+		await tick();
+		const child = h.children[0];
+		const response = { type: "message_end", message: { role: "assistant", stopReason: "stop", usage: { input: 3 } } };
+		child.emit(response);
+		if (checkpoint === "stream") {
+			allowed = false;
+			child.emit({ type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "progress" } });
+			allowed = true;
+			child.emit(response);
+		}
+		if (checkpoint === "finish") allowed = false;
+		h.runner.cancel(task.id);
+		await tick();
+		assert.equal((await h.runner.waitFor(task.id)).status, TASK_STATUS.CANCELLED);
+		assert.deepEqual(snapshots, [undefined]);
+		assert.ok(calls > 0);
+	});
+}
+
+test("child observation guard is never consulted when collection is default-off", async () => {
+	let calls = 0;
+	const h = harness();
+	const task = h.runner.run(request({ canCollectResponseObservations: () => { calls++; return true; } }));
+	await tick();
+	h.children[0].emit({ type: "message_end", message: { role: "assistant", stopReason: "stop" } });
+	h.runner.cancel(task.id);
+	await tick();
+	assert.equal(calls, 0);
+});
+
+for (const ending of ["cancel", "failure", "hook-error", "hook-async-error"] as const) {
+	test(`successful child mutations require paired RPC events and survive ${ending}`, async () => {
+		const mutations: unknown[] = [];
+		const h = harness({ onSuccessfulMutation: (task, tool) => {
+			mutations.push({ taskId: task.id, parent: task.parentSessionId, ...tool });
+			if (ending === "hook-error") throw new Error("receipt append unavailable");
+			if (ending === "hook-async-error") return Promise.reject(new Error("async receipt append unavailable"));
+		} });
+		const task = h.runner.run(request());
+		await tick();
+		const child = h.children[0];
+		const start = (id: string, toolName: string) => child.emit({ type: "tool_execution_start", toolCallId: id, toolName, args: { path: "src/file.ts" } });
+		const end = (id: string, isError: unknown = false) => child.emit({ type: "tool_execution_end", toolCallId: id, isError, result: { content: [] } });
+		assert.deepEqual(mutations, [], "spawn is not mutation evidence");
+		end("missing");
+		for (const name of ["read", "bash", "subagent_run"]) { start(name, name); end(name); }
+		start("failed", "write"); end("failed", true);
+		start("unknown", "edit"); end("unknown", null);
+		child.emit({ type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "I edited files" } });
+		assert.deepEqual(mutations, []);
+		for (const name of ["write", "edit"]) { start(name, name); end(name); end(name); }
+		assert.deepEqual(mutations, ["write", "edit"].map((toolName) => ({ taskId: task.id, parent: "s1", toolName, toolCallId: toolName, path: "src/file.ts" })));
+		start("unfinished", "write");
+		if (ending === "failure") child.fail("later failure");
+		else h.runner.cancel(task.id);
+		await tick();
+		end("unfinished"); start("late", "write"); end("late");
+		assert.equal(mutations.length, 2, "terminal cleanup rejects late events without retracting successful writes");
+	});
+}
+
+test("launch registration waits for actual spawn, including queued launches, and ignores failed spawns", async () => {
+	const launches: string[] = [];
+	const spawns: Array<() => void> = [];
+	const children: FakeChild[] = [];
+	const cwds: string[] = [];
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 1000 }, {
+		spawn: (_command, _args, options) => {
+			cwds.push(options.cwd);
+			if (options.cwd === "/throws") throw new Error("missing executable");
+			const fake = fakeChild();
+			const on = fake.child.on.bind(fake.child);
+			fake.child.on = ((event: string, listener: () => void) => {
+				if (event === "spawn") spawns.push(listener);
+				else on(event as "exit", listener);
+				return fake.child;
+			}) as typeof fake.child.on;
+			children.push(fake);
+			return fake.child;
+		},
+		now: () => 1000, schedule: () => () => {}, pi: { command: "pi", args: [] },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const first = runner.run(request({ cwd: "/child", onLaunch: () => launches.push("s1:/child") }));
+	const second = runner.run(request({ cwd: "/queued", onLaunch: () => launches.push("s1:/queued") }));
+	assert.deepEqual(launches, []);
+	await tick();
+	assert.deepEqual(launches, [], "returning a child handle is not successful spawn");
+	assert.equal(typeof spawns[0], "function");
+	spawns[0]();
+	assert.deepEqual(launches, ["s1:/child"]);
+	runner.cancel(first.id);
+	await tick();
+	assert.equal(store.get(second.id)?.cwd, "/queued");
+	spawns[1]();
+	assert.deepEqual(launches, ["s1:/child", "s1:/queued"]);
+	runner.cancel(second.id);
+	await tick();
+	const failed = runner.run(request({ cwd: "/missing", onLaunch: () => launches.push("bad") }));
+	await tick();
+	children[2].fail("ENOENT");
+	await tick();
+	assert.equal(store.get(failed.id)?.status, TASK_STATUS.FAILED);
+	const thrown = runner.run(request({ cwd: "/throws", onLaunch: () => launches.push("bad") }));
+	await tick();
+	assert.equal(store.get(thrown.id)?.status, TASK_STATUS.FAILED);
+	assert.deepEqual(launches, ["s1:/child", "s1:/queued"]);
+	assert.deepEqual(cwds, ["/child", "/queued", "/missing", "/throws"]);
+});
+
+test("runner captures resolved model and effort, retaining omitted launch values", async () => {
+	for (const scenario of [
+		{ state: { model: { provider: "anthropic", id: "resolved-model" }, thinkingLevel: "off" }, model: "anthropic/resolved-model", thinking: "off" },
+		{ state: { thinkingLevel: "max" }, model: "openai-codex/gpt-5.6-terra", thinking: "max" },
+		{ state: {}, model: "openai-codex/gpt-5.6-terra", thinking: "high" },
+		{ state: { model: null }, model: "default", thinking: "high" },
+		{ state: { model: { id: 7 }, thinkingLevel: 7 }, model: "openai-codex/gpt-5.6-terra", thinking: "high" },
+	]) {
+		const h = harness({ state: scenario.state });
+		const task = h.runner.run(request());
+		await tick();
+		assert.equal(h.store.get(task.id)?.model, scenario.model);
+		assert.equal(h.store.get(task.id)?.thinking, scenario.thinking);
+		h.runner.cancel(task.id);
+	}
+	const h = harness({ state: { model: { provider: "wrong", id: "wrong" }, thinkingLevel: "low" }, stateSuccess: false });
+	const task = h.runner.run(request({ model: undefined, thinking: undefined }));
+	await tick();
+	assert.equal(h.store.get(task.id)?.model, "default");
+	assert.equal(h.store.get(task.id)?.thinking, undefined);
+	h.runner.cancel(task.id);
+});
+
+test("runner delivers each response combination once at finish, never attributing launch selection", async () => {
+	const snapshots: NonNullable<Parameters<NonNullable<RunnerHooks["onFinish"]>>[1]>[] = [];
+	const h = harness({ exitOnKill: false, state: { model: { provider: "anthropic", id: "launch" }, thinkingLevel: "max" },
+		onFinish: (_task, snapshot) => { assert.ok(snapshot); snapshots.push(snapshot); } });
+	const task = h.runner.run(request({ collectResponseObservations: true }));
+	await tick();
+	const child = h.children[0];
+	const responses = [
+		{ provider: "openai", model: "gpt-4o", providerThinkingLevel: "low", stopReason: "error" },
+		{ provider: "anthropic", model: "claude-sonnet-4", providerThinkingLevel: "high", stopReason: "toolUse" },
+		{ provider: "openai", model: "gpt-4o", providerThinkingLevel: "high", stopReason: "stop" },
+	];
+	for (const response of responses) {
+		const message = { role: "assistant", ...response, usage: { input: 10, totalTokens: 10, cost: { total: 0.1 } }, content: [{ type: "text", text: "private report" }] };
+		child.emit({ type: "message_start", message });
+		child.emit({ type: "message_end", message });
+		child.emit({ type: "turn_end", message });
+		child.emit({ type: "agent_end", messages: [message] });
+	}
+	assert.deepEqual(snapshots, [], "agent_end is not settlement");
+	child.emit({ type: "agent_settled" });
+	assert.deepEqual(snapshots, [], "settlement still waits for process cleanup");
+	child.exit(0);
+	await tick();
+	assert.equal(snapshots.length, 1);
+	const snapshot = snapshots[0];
+	assert.equal(snapshot.agentSettled, true);
+	assert.equal(snapshot.droppedResponses, 0);
+	assert.equal(snapshot.coverage, "final_assistant_messages_only");
+	assert.deepEqual(snapshot.responses.map((response) => [response.provider, response.model, response.providerThinkingLevel]),
+		responses.map((response) => [response.provider, response.model, response.providerThinkingLevel].map((value) => ({ state: "observed", value }))));
+	assert.ok(snapshot.responses.every((response) => Object.values(response.selected).every((field) => field.state === "unavailable")));
+	assert.equal(h.store.get(task.id)?.tokens, 30);
+	assert.equal(h.store.get(task.id)?.cost, 0.1 + 0.1 + 0.1);
+	assert.equal(h.store.get(task.id)?.model, "anthropic/launch");
+	assert.deepEqual(child.written.map((command) => command.type), ["get_state", "prompt"]);
+	assert.doesNotMatch(JSON.stringify(snapshot), /private|launch|s1|modelVersion/);
+	assert.ok(Object.isFrozen(snapshot) && Object.isFrozen(snapshot.responses) && Object.isFrozen(snapshot.responses[0].tokens.input));
+	child.emit({ type: "agent_settled" }); child.exit(0);
+	assert.equal(snapshots.length, 1);
+});
+
+for (const ending of ["cancel", "exit", "error", "timeout", "settled-error"] as const) test(`bounded response coverage survives ${ending} honestly`, async () => {
+	let snapshot: Parameters<NonNullable<RunnerHooks["onFinish"]>>[1];
+	const h = harness({ onFinish: (_task, observations) => { snapshot = observations; } });
+	const task = h.runner.run(request({ collectResponseObservations: true }));
+	await tick();
+	const child = h.children[0];
+	for (let index = 0; index < 130; index++) child.emit({ type: "message_end", message: {
+		role: "assistant", model: `model-${index}`, stopReason: "error", usage: { totalTokens: 1 } } });
+	if (ending === "cancel") h.runner.cancel(task.id);
+	else if (ending === "exit") child.exit(1);
+	else if (ending === "error") child.fail("private process error");
+	else if (ending === "timeout") h.timers.filter((timer) => !timer.cancelled && timer.ms === 10_000).at(-1)!.fn();
+	else { child.emit({ type: "agent_end", messages: [{ role: "assistant", stopReason: "error" }] }); child.emit({ type: "agent_settled" }); }
+	await h.runner.waitFor(task.id);
+	assert.ok(snapshot);
+	assert.equal(snapshot.responses.length, 128);
+	assert.equal(snapshot.droppedResponses, 2);
+	assert.equal(snapshot.agentSettled, ending === "settled-error");
+	assert.equal(h.store.get(task.id)?.tokens, 130, "buffer cap never caps existing UI totals");
+	assert.notEqual(h.store.get(task.id)?.status, TASK_STATUS.COMPLETED);
+	child.emit({ type: "message_end", message: { role: "assistant", stopReason: "stop" } });
+	assert.equal(snapshot.responses.length, 128);
+	assert.equal(h.finishes.length, 1);
+});
+
+test("response buffering is disabled by default and absent for tasks cancelled before launch", async () => {
+	const snapshots: unknown[] = [];
+	const h = harness({ maxConcurrency: 1, onFinish: (_task, snapshot) => snapshots.push(snapshot) });
+	const task = h.runner.run(request());
+	const queued = h.runner.run(request({ collectResponseObservations: true }));
+	await tick();
+	h.children[0].emit({ type: "message_end", message: { role: "assistant", stopReason: "stop", usage: { totalTokens: 7 } } });
+	h.runner.cancel(queued.id); h.runner.cancel(task.id);
+	await tick();
+	assert.deepEqual(snapshots, [undefined, undefined]);
+	assert.equal(h.store.get(task.id)?.tokens, 7);
+});
+
 test("childArguments builds an rpc launch with model, thinking, tools, session dir, and instructions", () => {
 	const args = childArguments(request());
 	assert.deepEqual(args.slice(0, 2), ["--mode", "rpc"]);
 	assert.ok(args.includes("--session-dir") && args[args.indexOf("--session-dir") + 1] === "/sessions");
 	assert.equal(args[args.indexOf("--model") + 1], "openai-codex/gpt-5.6-terra:high");
-	assert.equal(args[args.indexOf("--tools") + 1], "read,grep");
+	assert.equal(args[args.indexOf("--tools") + 1], "read,grep,subagent_parent_message");
 	assert.equal(args[args.indexOf("--append-system-prompt") + 1], "You map things.");
 	assert.ok(!args.includes("--session"));
 	const resumed = childArguments(request({ resumeSessionPath: "/sessions/old.jsonl", model: undefined, thinking: undefined, agent: { ...explorer, tools: [] } }));
@@ -75,6 +365,76 @@ test("childArguments builds an rpc launch with model, thinking, tools, session d
 	assert.ok(!resumed.includes("--model") && !resumed.includes("--tools"));
 });
 
+test("childArguments preserves a max profile instead of the definition's medium effort", () => {
+	const agent: AgentDefinition = { ...explorer, name: "worker", thinking: "medium" };
+	const config = parseAgentsConfig({ model_profiles: { worker: { model: "openai-codex/gpt-5.6-luna", effort: "max" } } }, undefined);
+	const profile = resolveAgentProfile(agent, config);
+	const args = childArguments(request({ agent, model: profile.model, thinking: profile.thinking }));
+	assert.equal(args[args.indexOf("--model") + 1], "openai-codex/gpt-5.6-luna:max");
+});
+
+test("childArguments preserves a max default without a selected model", () => {
+	const profile = resolveAgentProfile(explorer, parseAgentsConfig({ default_effort: "max" }, undefined));
+	const args = childArguments(request({ model: profile.model, thinking: profile.thinking }));
+	assert.ok(!args.includes("--model"));
+	assert.equal(args[args.indexOf("--thinking") + 1], "max");
+});
+
+test("childArguments grants every child the notification-only parent message tool", () => {
+	const args = childArguments(request());
+	assert.equal(args[args.indexOf("--tools") + 1], "read,grep,subagent_parent_message");
+});
+
+test("AgentRunner admits strict live notifications once and closes IPC before Stop", async () => {
+	const notifications: string[] = [];
+	const { runner, children, spawnOptions } = harness({ onNotification: (task, message) => task.parentSessionId === "s1" && (notifications.push(message), true) });
+	const task = runner.run(request());
+	await tick();
+	children[0].message({ id: "n1", kind: "notification", message: "checkpoint" });
+	children[0].message({ id: "n1", kind: "notification", message: "checkpoint" });
+	children[0].message({ id: "n2", kind: "notification", message: "x".repeat(8 * 1024 + 1) });
+	children[0].message({ id: "q3", kind: "query", message: "unsupported" });
+	children[0].message({ id: "n4", kind: "notification", message: "\uD800" });
+	children[0].message({ id: "n5", kind: "notification", message: "forged field", sender: "forged" });
+	children[0].message({ id: "n0", kind: "notification", message: "invalid correlation" });
+	children[0].message({ id: `n${"1".repeat(1_000)}`, kind: "notification", message: "invalid correlation" });
+	await tick();
+	assert.deepEqual(spawnOptions[0]?.stdio, ["pipe", "pipe", "pipe", "ipc"]);
+	assert.deepEqual(notifications, ["checkpoint"]);
+	assert.deepEqual(children[0].sent, [
+		{ id: "n1", kind: "ack", accepted: true },
+		{ id: "n2", kind: "ack", accepted: false, error: "invalid child IPC message" },
+		{ id: "q3", kind: "reply", error: "task parent cannot accept queries" },
+		{ id: "n4", kind: "ack", accepted: false, error: "invalid child IPC message" },
+		{ id: "n5", kind: "ack", accepted: false, error: "invalid child IPC frame" },
+	]);
+	runner.cancel(task.id);
+	children[0].message({ id: "after-stop", kind: "notification", message: "ignored" });
+	await tick();
+	assert.equal(children[0].sent.length, 5);
+	assert.ok(children[0].disconnects > 0);
+});
+
+test("AgentRunner rejects notifications from an inactive parent session with a static acknowledgement", async () => {
+	const { runner, children } = harness({ onNotification: () => false });
+	runner.run(request());
+	await tick();
+	children[0].message({ id: "n1", kind: "notification", message: "not active" });
+	await tick();
+	assert.deepEqual(children[0].sent, [{ id: "n1", kind: "ack", accepted: false, error: "task parent is not the active host session" }]);
+});
+
+test("AgentRunner retains only a 64-notification duplicate window", async () => {
+	const notifications: string[] = [];
+	const { runner, children } = harness({ onNotification: (_task, message) => { notifications.push(message); } });
+	runner.run(request());
+	await tick();
+	for (let index = 1; index <= 65; index += 1) children[0].message({ id: `n${index}`, kind: "notification", message: `message ${index}` });
+	children[0].message({ id: "n1", kind: "notification", message: "message 1 again" });
+	await tick();
+	assert.equal(notifications.length, 66, "an ID evicted from the recent 64-ack window can be admitted again");
+});
+
 test("piCommand reuses the running pi entry point and honors the override", () => {
 	assert.deepEqual(piCommand({ execPath: "/bin/node", argv: ["/bin/node", "/x/dist/cli.js"], env: {} }), { command: "/bin/node", args: ["/x/dist/cli.js"] });
 	assert.deepEqual(piCommand({ execPath: "/bin/node", argv: ["/bin/node", "/x/other.js"], env: {} }), { command: "pi", args: [] });
@@ -219,12 +579,43 @@ test("AgentRunner fails if the child exits after agent_end but before agent_sett
 	assert.equal(store.get(task.id)?.result, "partial answer", "the final observed answer remains available for diagnostics");
 });
 
-test("AgentRunner reserves a parent-owned fourth stdio fd only for package-child authorization", async () => {
+for (const [platform, detached] of [["win32", false], ["linux", true]] as const) test(`AgentRunner selects detached=${detached} for ${platform} without changing the launch contract`, async () => {
+	const store = new TaskStore();
+	const launches: Array<{ command: string; args: string[]; options: Parameters<RunnerDeps["spawn"]>[2] }> = [];
+	const child = fakeChild();
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 1_000 }, {
+		spawn: (command, args, options) => {
+			launches.push({ command, args, options });
+			return child.child;
+		},
+		now: () => 1,
+		schedule: () => () => {},
+		pi: { command: "pi-fixture", args: ["--from-host"] },
+		process: { platform, kill: () => {} },
+	}, { askUser: async () => ({ cancelled: true }) });
+	const task = runner.run(request({ env: { PATH: "/fixture", KEEP: "yes" } }));
+	await tick();
+	const ownedIpc = launches[0]?.options.env.GENTLE_PI_AGENTS_OWNED_IPC;
+	assert.match(ownedIpc ?? "", /^\d+-[a-z0-9]+$/, "the runner creates an opaque owned-IPC marker");
+	assert.deepEqual(launches, [{
+		command: "pi-fixture",
+		args: ["--from-host", "--mode", "rpc", "--session-dir", "/sessions", "--model", "openai-codex/gpt-5.6-terra:high", "--tools", "read,grep,subagent_parent_message", "--append-system-prompt", "You map things."],
+		options: { cwd: "/repo", env: { PATH: "/fixture", KEEP: "yes", GENTLE_PI_AGENTS_CHILD: "1", GENTLE_PI_AGENTS_OWNED_IPC: ownedIpc }, detached, stdio: ["pipe", "pipe", "pipe", "ipc"] },
+	}]);
+	child.emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "platform checked" }], stopReason: "stop" }] });
+	child.emit({ type: "agent_settled" });
+	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.COMPLETED);
+});
+
+test("AgentRunner retains permission broker fd3 and assigns messaging IPC to fd4", async () => {
 	const { runner, children, spawnOptions } = harness();
 	const task = runner.run(request({ authorizeParentStandingReviewPermission: () => true }));
 	await tick();
-	assert.deepEqual(spawnOptions[0]?.stdio, ["pipe", "pipe", "pipe", "pipe"]);
-	assert.equal((spawnOptions[0] as { stdio?: string[] } | undefined)?.stdio?.length, 4);
+	const launch = spawnOptions[0];
+	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" });
+	assert.deepEqual(launch?.stdio, ["pipe", "pipe", "pipe", "pipe", "ipc"]);
+	assert.equal(launch?.stdio?.length, 5);
 	children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "channel checked" }], stopReason: "stop" }] });
 	children[0].emit({ type: "agent_settled" });
 	assert.equal((await runner.waitFor(task.id)).status, TASK_STATUS.COMPLETED);
@@ -336,6 +727,7 @@ for (const lateEvents of [false, true]) test(`AgentRunner releases quarantined c
 	let launches = 0;
 	let asks = 0;
 	const finishes: string[] = [];
+	const observations: Parameters<NonNullable<RunnerHooks["onFinish"]>>[1][] = [];
 	let resolveAnswer!: (answer: { value: string }) => void;
 	const answer = new Promise<{ value: string }>((resolve) => { resolveAnswer = resolve; });
 	const child = fakeChild({ exitOnKill: false, pid: 71 });
@@ -351,11 +743,12 @@ for (const lateEvents of [false, true]) test(`AgentRunner releases quarantined c
 		process: { platform: "linux", kill: (_pid, signal) => {
 			if (signal === 0) throw Object.assign(new Error("group probe"), { code: groupGone ? "ESRCH" : "EPERM" });
 		} },
-	}, { askUser: async () => { asks += 1; return answer; }, onFinish: (task) => finishes.push(task.id) });
-	const first = runner.run(request());
+	}, { askUser: async () => { asks += 1; return answer; }, onFinish: (task, snapshot) => { finishes.push(task.id); observations.push(snapshot); } });
+	const first = runner.run(request({ collectResponseObservations: true }));
 	const second = runner.run(request({ prompt: "queued" }));
 	await tick();
 	const waiter = runner.waitFor(first.id);
+	child.emit({ type: "message_end", message: { role: "assistant", stopReason: "aborted", usage: { input: 3 } } });
 	if (lateEvents) child.emit({ type: "extension_ui_request", id: "early", method: "input", title: "Pending?" });
 	runner.cancel(first.id);
 	const grace = timers.find((timer) => timer.ms === 250);
@@ -369,6 +762,9 @@ for (const lateEvents of [false, true]) test(`AgentRunner releases quarantined c
 	assert.equal(store.get(first.id)?.status, TASK_STATUS.FAILED);
 	assert.equal((await waiter).status, TASK_STATUS.FAILED);
 	assert.match(store.get(first.id)?.error ?? "", /cleanup unconfirmed/);
+	assert.equal(observations.length, 1);
+	assert.equal(observations[0]?.agentSettled, false);
+	assert.equal(observations[0]?.responses.length, 1);
 	assert.equal(store.get(second.id)?.status, TASK_STATUS.QUEUED, "the unconfirmed group retains its capacity");
 	assert.equal(timers.filter((timer) => timer.ms === 25 && !timer.cancelled).length, 0, "confirmation polling stops at its deadline");
 	const finished = structuredClone(store.get(first.id));
@@ -398,5 +794,166 @@ for (const lateEvents of [false, true]) test(`AgentRunner releases quarantined c
 	child.exit(0);
 	await tick();
 	assert.deepEqual(finishes, [first.id], "cleanup must not finish the quarantined task twice");
+	assert.equal(observations.length, 1, "late cleanup does not redeliver observations");
 	assert.deepEqual(store.get(first.id), finished);
 });
+
+test("a confirmed-gone group completes the exit and frees its slot without an observed exit", async () => {
+	// The group probe reports ESRCH (the group is gone) while the child never emits
+	// its exit event. Returning without finishing left the task terminal in memory
+	// with no record and no retry; finishing without releasing the live entry would
+	// keep the concurrency slot occupied and never pump queued work.
+	const store = new TaskStore();
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	const finishes: string[] = [];
+	let now = 1_000;
+	let launches = 0;
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 10_000 }, {
+		spawn: () => fakeChild({ exitOnKill: false, pid: 90 + (launches += 1) }).child,
+		now: () => now,
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => { timer.cancelled = true; };
+		},
+		pi: { command: "pi", args: [] },
+		process: { platform: "linux", kill: (_pid, signal) => {
+			if (signal === 0) throw Object.assign(new Error("group probe"), { code: "ESRCH" });
+		} },
+	}, { askUser: async () => ({ value: "yes" }), onFinish: (task) => { finishes.push(task.id); } });
+	const first = runner.run(request());
+	const second = runner.run(request({ prompt: "queued" }));
+	await tick();
+	const waiter = runner.waitFor(first.id);
+	runner.cancel(first.id);
+	const grace = timers.find((timer) => timer.ms === 250);
+	assert.ok(grace, "termination grace is scheduled");
+	grace.fn();
+	await tick();
+	assert.equal(store.get(first.id)?.status, TASK_STATUS.CANCELLED);
+	assert.equal((await waiter).status, TASK_STATUS.CANCELLED, "the waiter receives the recorded outcome");
+	assert.equal(finishes.length, 1, "the run is recorded exactly once");
+	assert.equal(store.get(second.id)?.status, TASK_STATUS.RUNNING, "the freed slot starts queued work");
+});
+
+test("an unprobeable process group quarantines at its deadline and still records the run", async () => {
+	// On win32 the child is not detached, so there is no process group to probe and
+	// an observed exit is the only confirmation available. With no exit event the
+	// run must still be recorded at the deadline, and its slot must be retained
+	// rather than freed on an unproven assumption.
+	const store = new TaskStore();
+	const timers: Array<{ fn: () => void; ms: number; cancelled: boolean }> = [];
+	const finishes: string[] = [];
+	let now = 1_000;
+	let launches = 0;
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 10_000 }, {
+		spawn: () => fakeChild({ exitOnKill: false, pid: 90 + (launches += 1) }).child,		now: () => now,
+		schedule: (fn, ms) => {
+			const timer = { fn, ms, cancelled: false };
+			timers.push(timer);
+			return () => { timer.cancelled = true; };
+		},
+		pi: { command: "pi", args: [] },
+		process: { platform: "win32", kill: () => {} },
+	}, { askUser: async () => ({ value: "yes" }), onFinish: (task) => { finishes.push(task.id); } });
+	const first = runner.run(request());
+	const second = runner.run(request({ prompt: "queued" }));
+	await tick();
+	runner.cancel(first.id);
+	const grace = timers.find((timer) => timer.ms === 250);
+	assert.ok(grace, "termination grace is scheduled");
+	grace.fn();
+	now = 5_000;
+	const check = timers.filter((timer) => timer.ms === 25).at(-1);
+	assert.ok(check, "an unprobeable group must keep polling instead of stopping silently");
+	check.fn();
+	await tick();
+	assert.equal(store.get(first.id)?.status, TASK_STATUS.FAILED);
+	assert.match(store.get(first.id)?.error ?? "", /capacity quarantined/);
+	assert.equal(finishes.length, 1, "the run is recorded exactly once");
+	assert.equal(store.get(second.id)?.status, TASK_STATUS.QUEUED, "an unconfirmed exit retains its capacity");
+	assert.equal(launches, 1, "no further launch happens while the slot is quarantined");
+});
+
+test("abortReasonText renders an Error, a string, and nothing for unknown reasons", () => {
+	assert.equal(abortReasonText(undefined), "");
+	assert.equal(abortReasonText(new Error("interrupted by user")), " (interrupted by user)");
+	assert.equal(abortReasonText("host timeout"), " (host timeout)");
+	assert.equal(abortReasonText(new Error("")), "");
+	assert.equal(abortReasonText(42), "");
+});
+
+test("research narrowing transport keeps exact argv paths and replaces inherited selection", async () => {
+ const h = harness();
+ const selection = { documentation: { tools: ["fetch_content"], extensions: { fetch_content: "/installed/docs tools.ts" } } };
+ for (const researchSelection of [selection, undefined]) {
+  const artifact = { store: "none" as const, worktree: "/work", changeName: "demo", retainedIntent: "denied questions", locators: [] };
+  const expected = structuredClone(artifact);
+  const launch = request({ researchSelection, researchArtifact: artifact, extensionPaths: researchSelection ? ["/installed/docs tools.ts"] : [],
+   env: { PATH: "/bin", GENTLE_PI_RESEARCH_SELECTION: "stale broad selection", GENTLE_PI_RESEARCH_ARTIFACT: "stale broader scope" } });
+  const argv = childArguments(launch);
+  assert.deepEqual(argv.filter((_, i) => argv[i - 1] === "--extension"), launch.extensionPaths);
+  const task = h.runner.run(launch);
+  artifact.worktree = "/wrong";
+  await tick();
+  assert.deepEqual(JSON.parse(h.spawnOptions.at(-1)!.env.GENTLE_PI_RESEARCH_ARTIFACT!), expected);
+  assert.deepEqual("researchArtifact" in task ? task.researchArtifact : undefined, expected);
+  assert.deepEqual(JSON.parse(h.spawnOptions.at(-1)!.env.GENTLE_PI_RESEARCH_SELECTION!), researchSelection ?? null);
+  assert.equal(h.spawnOptions.at(-1)!.env.PATH, "/bin");
+  h.runner.cancel(task.id);
+  assert.equal((await h.runner.waitFor(task.id)).status, TASK_STATUS.CANCELLED);
+ }
+});
+
+
+test("runner retains remediation observations and awaits terminal settlement", async () => {
+	const h = harness({ pid: 123 });
+	let finalized: { record: TaskRecord; facts: RemediationTerminalFacts } | undefined;
+	let release: () => void;
+	const gate = new Promise<void>(resolve => { release = resolve; });
+	const remediationPlan: RemediationPlan = { cwd: "/repo", commands: ["pnpm test"], runtimeHarness: { naReason: "Not applicable because the fixture has no runtime boundary." }, rollback: { boundary: "Revert fixture", command: "git diff --check" } };
+	const remediation: RemediationTaskState = { failedEvidenceRevision: `sha256:${"a".repeat(64)}`, plan: remediationPlan, pending: {}, observations: [], invalid: false, token: "opaque", acquire: { workspaceRoot: "/repo", changeName: "demo", requestId: "fixture", workUnit: "correct", evidenceGoal: "Observed correction" } };
+	const task = h.runner.run(request({ sddRemediation: remediation, finalizeRemediation: async (record, facts) => { finalized = { record, facts }; await gate; } }));
+	await tick();
+	for (const command of ["pnpm test", "git diff --check"]) {
+		h.children[0].emit({ type: "tool_execution_start", toolName: "bash", toolCallId: command, args: { command } });
+		h.children[0].emit({ type: "tool_execution_end", toolName: "bash", toolCallId: command, isError: false, result: { content: [{ type: "text", text: "command output" }], details: { remediationCommand: { command, toolCallId: command, cwd: "/repo", exitCode: 0 } } } });
+	}
+	h.children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "done" }], stopReason: "stop" }] });
+	h.children[0].emit({ type: "agent_settled" });
+	await tick();
+	assert.ok(finalized);
+	assert.equal(finalized.record.sddRemediation?.observations.length, 2);
+	const prompt = h.children[0].written.find(value => value.type === "prompt").message;
+	assert.ok(typeof prompt === "string");
+	assert.match(prompt, /pnpm test/);
+	assert.doesNotMatch(prompt, /opaque/);
+	assert.equal(finalized.facts.cleanupConfirmed, true);
+	assert.equal(h.finishes.length, 0);
+	release(); await h.runner.waitFor(task.id);
+	assert.equal(h.finishes.length, 1);
+	assert.equal(remediation.observations.length, 0);
+});
+
+
+test("admitted no-PID failure settles interrupted before sending a prompt", async () => {
+	const h = harness(); let facts;
+	const task = h.runner.run(request({ sddRemediation: { plan: {} } as unknown as RemediationTaskState, finalizeRemediation: async (_task, observed) => { facts = observed; } }));
+	await tick();
+	assert.equal(h.children[0].written.some(value => value.type === "prompt"), false);
+	await h.runner.waitFor(task.id);
+	assert.equal(facts.spawned, false);
+	assert.equal(facts.exited, false);
+	assert.equal(facts.cleanupConfirmed, false);
+});
+
+
+test("admitted synchronous spawn failure finalizes without launching another actor", async () => {
+	let spawns = 0, facts;
+	const store = new TaskStore();
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 100 }, { spawn: () => { spawns++; throw new Error("spawn refused"); }, pi: { command: "pi", args: [] }, now: () => 1, schedule: () => () => {} }, { askUser: async () => ({}) });
+	const task = runner.run(request({ sddRemediation: { plan: {} } as unknown as RemediationTaskState, finalizeRemediation: async (_task, value) => { facts = value; } }));
+	await runner.waitFor(task.id);
+	assert.deepEqual(facts, { spawned: false, exited: false, cleanupConfirmed: true });
+	assert.equal(spawns, 1);
+});