@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/test/unit/changelog-format.test.ts

@@ -0,0 +1,11 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import test from "node:test";
+
+test("Unreleased changelog uses each subsection once", () => {
+	const changelog = fs.readFileSync(new URL("../../CHANGELOG.md", import.meta.url), "utf8");
+	const unreleased = changelog.match(/^## \[Unreleased\]\r?\n([\s\S]*?)(?=^## \[)/m)?.[1];
+	assert.ok(unreleased, "Unreleased section should exist");
+	const headings = [...unreleased.matchAll(/^### (.+)$/gm)].map((match) => match[1]);
+	assert.deepEqual(headings, [...new Set(headings)]);
+});

package/dist/extensions/pi-subagents/test/unit/child-cache-retention.test.ts

@@ -0,0 +1,87 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+import { childCacheRetention, childCacheRetentionEnv, pinChildCacheRetention } from "../../src/shared/child-cache-retention.ts";
+
+type StreamOptions = Parameters<StreamFn>[2];
+
+/** Records the options each call receives so tests can assert on the request env. */
+function recordingAgent(): { agent: { streamFunction: StreamFn }; calls: StreamOptions[]; original: StreamFn } {
+	const calls: StreamOptions[] = [];
+	const original = ((_model, _context, options) => {
+		calls.push(options);
+		return undefined as never;
+	}) as StreamFn;
+	return { agent: { streamFunction: original }, calls, original };
+}
+
+function call(agent: { streamFunction: StreamFn }, options?: StreamOptions): void {
+	agent.streamFunction(undefined as never, undefined as never, options);
+}
+
+describe("childCacheRetention", () => {
+	it("is unset by default so children inherit the parent's retention", () => {
+		assert.equal(childCacheRetention({}), undefined);
+		assert.equal(childCacheRetention({ SELESAI_SUBAGENT_CACHE_RETENTION: "" }), undefined);
+	});
+
+	it("returns the configured tier", () => {
+		assert.equal(childCacheRetention({ SELESAI_SUBAGENT_CACHE_RETENTION: "short" }), "short");
+		assert.equal(childCacheRetention({ SELESAI_SUBAGENT_CACHE_RETENTION: "long" }), "long");
+	});
+
+	it("ignores the parent's own retention", () => {
+		assert.equal(childCacheRetention({ PI_CACHE_RETENTION: "long" }), undefined);
+	});
+});
+
+describe("childCacheRetentionEnv", () => {
+	it("contributes nothing when unset so a spawned child inherits the parent value", () => {
+		assert.deepEqual(childCacheRetentionEnv({}), {});
+		const launchEnv = { ...{ PI_CACHE_RETENTION: "long" }, ...childCacheRetentionEnv({}) };
+		assert.equal(launchEnv.PI_CACHE_RETENTION, "long");
+	});
+
+	it("overrides the inherited value in a spawned child's launch environment", () => {
+		const launchEnv = { ...{ PI_CACHE_RETENTION: "long" }, ...childCacheRetentionEnv({ SELESAI_SUBAGENT_CACHE_RETENTION: "short" }) };
+		assert.equal(launchEnv.PI_CACHE_RETENTION, "short");
+	});
+});
+
+describe("pinChildCacheRetention", () => {
+	it("leaves the stream function untouched when no tier is configured", () => {
+		assert.doesNotThrow(() => { pinChildCacheRetention(undefined, {}); pinChildCacheRetention({ streamFunction: undefined as unknown as StreamFn }, {}); });
+		const { agent, calls, original } = recordingAgent();
+		pinChildCacheRetention(agent, {});
+		assert.equal(agent.streamFunction, original);
+		call(agent, { env: { PI_CACHE_RETENTION: "long" } });
+		assert.deepEqual(calls[0]?.env, { PI_CACHE_RETENTION: "long" });
+	});
+
+	it("overrides an inherited parent tier on the request env", () => {
+		const { agent, calls } = recordingAgent();
+		pinChildCacheRetention(agent, { SELESAI_SUBAGENT_CACHE_RETENTION: "short" });
+		call(agent, { env: { PI_CACHE_RETENTION: "long" } });
+		assert.equal(calls[0]?.env?.PI_CACHE_RETENTION, "short");
+	});
+
+	it("preserves other request env values and options", () => {
+		const { agent, calls } = recordingAgent();
+		pinChildCacheRetention(agent, { SELESAI_SUBAGENT_CACHE_RETENTION: "short" });
+		call(agent, { env: { ANTHROPIC_API_KEY: "sk-test" }, headers: { "x-trace": "1" } } as StreamOptions);
+		assert.equal(calls[0]?.env?.ANTHROPIC_API_KEY, "sk-test");
+		assert.equal(calls[0]?.env?.PI_CACHE_RETENTION, "short");
+		assert.deepEqual((calls[0] as { headers?: Record<string, string> })?.headers, { "x-trace": "1" });
+	});
+
+	it("leaves a sibling session's stream function alone", () => {
+		const before = process.env.PI_CACHE_RETENTION;
+		const child = recordingAgent();
+		const parent = recordingAgent();
+		pinChildCacheRetention(child.agent, { SELESAI_SUBAGENT_CACHE_RETENTION: "short" });
+		assert.equal(parent.agent.streamFunction, parent.original);
+		call(parent.agent, { env: { PI_CACHE_RETENTION: "long" } });
+		assert.equal(parent.calls[0]?.env?.PI_CACHE_RETENTION, "long");
+		assert.equal(process.env.PI_CACHE_RETENTION, before);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/child-commands.test.ts

@@ -0,0 +1,243 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createAssistantMessageEventStream, fauxAssistantMessage, fauxToolCall } from "@earendil-works/pi-ai";
+import { createBashToolDefinition, type ExtensionContext, type ToolDefinition } from "@selesai/code";
+import { createChildCommandRuntime, controlChildCommand, readChildCommandState } from "../../src/runs/shared/child-commands.ts";
+
+const ctx = { sessionManager: { getSessionId: () => "test-session", getSessionFile: () => undefined } } as ExtensionContext;
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+async function until(predicate: () => boolean, diagnostic?: () => unknown) {
+	const deadline = Date.now() + 3000;
+	while (!predicate()) { assert.ok(Date.now() < deadline, `condition did not become true${diagnostic ? `: ${JSON.stringify(diagnostic())}` : ""}`); await delay(10); }
+}
+function processAlive(pid: number) { try { process.kill(pid, 0); return true; } catch { return false; } }
+function serviceCommand(pidFile: string) {
+	const script = `${pidFile}.cjs`;
+	const pending = `${pidFile}.pending`;
+	fs.writeFileSync(script, `const fs = require('fs'); fs.writeFileSync(${JSON.stringify(pending)}, String(process.pid)); fs.renameSync(${JSON.stringify(pending)}, ${JSON.stringify(pidFile)}); console.log('ready'); setInterval(() => {}, 1000);`);
+	return `${JSON.stringify(process.execPath.replaceAll("\\", "/"))} ${JSON.stringify(script.replaceAll("\\", "/"))}`;
+}
+
+describe("child commands using Pi's real bash backend", () => {
+	it("yields a live process, runs another command, and cancels only the selected process", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-commands-"));
+		const commands = createChildCommandRuntime(dir);
+		const bash = commands.wrap(createBashToolDefinition(dir));
+		try {
+			const firstPid = path.join(dir, "first.pid");
+			const secondPid = path.join(dir, "second.pid");
+			const first = await bash.execute("first", { command: serviceCommand(firstPid), yieldTimeMs: 0 }, undefined, undefined, ctx);
+			assert.match(first.content[0].text, /not a successful exit/);
+			await bash.execute("second", { command: serviceCommand(secondPid), yieldTimeMs: 0 }, undefined, undefined, ctx);
+			await until(() => fs.existsSync(firstPid) && fs.existsSync(secondPid), commands.state);
+			const pid1 = Number(fs.readFileSync(firstPid));
+			const pid2 = Number(fs.readFileSync(secondPid));
+			assert.ok(pid1 > 0 && pid2 > 0, `services must publish valid PIDs: ${pid1}, ${pid2}`);
+			const continued = await bash.execute("continue", { command: "printf continued" }, undefined, undefined, ctx);
+			assert.equal(continued.content[0].text, "continued");
+			const cancelled = await controlChildCommand(dir, "cancel", "first");
+			assert.equal(cancelled.commands[0].toolCallId, "first");
+			assert.ok(["cancel_requested", "cancelled"].includes(cancelled.commands[0].state));
+			await until(() => commands.operate("status", "first").commands[0].state === "cancelled");
+			await until(() => !processAlive(pid1));
+			assert.equal(processAlive(pid2), true, "sibling command must remain alive");
+			assert.equal(commands.operate("status", "second").commands[0].state, "yielded");
+			await controlChildCommand(dir, "cancel", "second");
+			await commands.shutdown();
+			await until(() => !processAlive(pid2), () => ({ pid2, publishedPid: fs.readFileSync(secondPid, "utf8"), commands: commands.state() }));
+			assert.equal(readChildCommandState(dir)?.closed, true);
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+	it("lets the supervisor yield a bash call that was already blocking", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-yield-"));
+		const commands = createChildCommandRuntime(dir);
+		try {
+			const pidFile = path.join(dir, "service.pid");
+			const pending = commands.wrap(createBashToolDefinition(dir)).execute("blocked", { command: serviceCommand(pidFile) }, undefined, undefined, ctx);
+			await until(() => fs.existsSync(pidFile), commands.state);
+			assert.equal(commands.state().commands[0].state, "running");
+			await controlChildCommand(dir, "yield", "blocked");
+			assert.match((await pending).content[0].text, /still running/);
+			assert.equal(processAlive(Number(fs.readFileSync(pidFile))), true);
+			await controlChildCommand(dir, "cancel", "blocked");
+			await commands.shutdown();
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+	it("returns command failures and per-command timeouts without poisoning the session", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-errors-"));
+		const commands = createChildCommandRuntime(dir);
+		const bash = commands.wrap(createBashToolDefinition(dir));
+		try {
+			// Pi 1.x returns an isError result for non-zero exits; Pi 0.87 threw.
+			const failed = await bash.execute("fail", { command: "exit 7" }, undefined, undefined, ctx).then(
+				(result: { isError?: boolean; content: Array<{ text?: string }> }) => result.isError ? result.content.map((part) => part.text ?? "").join("") : "",
+				(error: Error) => error.message,
+			);
+			assert.match(failed, /code 7/);
+			await assert.rejects(bash.execute("timeout", { command: "sleep 10", timeout: 0.05 }, undefined, undefined, ctx), /timed out/);
+			assert.equal(commands.operate("status", "timeout").commands[0].state, "failed");
+			const result = await bash.execute("recover", { command: "printf recovered" }, undefined, undefined, ctx);
+			assert.equal(result.content[0].text, "recovered");
+			await commands.finish();
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+	it("cancels unfinished background work and fails closed when the child finishes", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-finish-"));
+		const commands = createChildCommandRuntime(dir);
+		try {
+			const pidFile = path.join(dir, "service.pid");
+			await commands.wrap(createBashToolDefinition(dir)).execute("unfinished", { command: serviceCommand(pidFile), yieldTimeMs: 0 }, undefined, undefined, ctx);
+			await until(() => fs.existsSync(pidFile), commands.state);
+			const pid = Number(fs.readFileSync(pidFile));
+			await assert.rejects(commands.finish(), /unfinished commands: unfinished/);
+			await until(() => !processAlive(pid));
+			assert.equal(commands.state().commands[0].state, "cancelled");
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+});
+
+
+describe("Pi agent loop command cancellation", () => {
+	it("continues the same agent turn after the supervisor cancels a blocking command", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-command-agent-"));
+		const commands = createChildCommandRuntime(dir);
+		const pidFile = path.join(dir, "agent.pid");
+		const responses = [
+			fauxAssistantMessage(fauxToolCall("bash", { command: serviceCommand(pidFile) }, { id: "blocked" }), { stopReason: "toolUse" }),
+			fauxAssistantMessage(fauxToolCall("bash", { command: "printf continued" }, { id: "after-cancel" }), { stopReason: "toolUse" }),
+			fauxAssistantMessage("Done"),
+		];
+		const agent = new Agent({
+			initialState: { tools: [commands.wrap(createBashToolDefinition(dir, { exposeSessionEnvironment: false }))] },
+			streamFn: () => {
+				const message = responses.shift()!;
+				const stream = createAssistantMessageEventStream();
+				queueMicrotask(() => stream.push({ type: "done", reason: message.stopReason, message }));
+				return stream;
+			},
+		});
+		try {
+			const run = agent.prompt("Run the commands");
+			await until(() => fs.existsSync(pidFile), commands.state);
+			await controlChildCommand(dir, "cancel", "blocked");
+			await run;
+			await commands.finish();
+			const results = agent.state.messages.filter((message) => message.role === "toolResult");
+			assert.equal(results[0].toolCallId, "blocked");
+			assert.equal(results[0].isError, true);
+			assert.equal(results[1].toolCallId, "after-cancel");
+			assert.equal(results[1].content[0].text, "continued");
+			assert.equal(agent.state.errorMessage, undefined);
+		} finally { agent.abort(); await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+	it("continues after a yielded command and observes targeted cancellation through the child tool", { timeout: 10_000 }, async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-command-yield-agent-"));
+		const commands = createChildCommandRuntime(dir);
+		const responses = [
+			fauxAssistantMessage(fauxToolCall("bash", { command: serviceCommand(path.join(dir, "service.pid")), yieldTimeMs: 0 }, { id: "service" }), { stopReason: "toolUse" }),
+			fauxAssistantMessage(fauxToolCall("bash", { command: "printf continued" }, { id: "continue" }), { stopReason: "toolUse" }),
+			fauxAssistantMessage(fauxToolCall("subagent_command", { action: "cancel", toolCallId: "service", waitMs: 1000 }, { id: "cancel-service" }), { stopReason: "toolUse" }),
+			fauxAssistantMessage("Done"),
+		];
+		const agent = new Agent({
+			initialState: { tools: [commands.wrap(createBashToolDefinition(dir, { exposeSessionEnvironment: false })), commands.tool()] },
+			streamFn: () => {
+				const message = responses.shift()!;
+				const stream = createAssistantMessageEventStream();
+				queueMicrotask(() => stream.push({ type: "done", reason: message.stopReason, message }));
+				return stream;
+			},
+		});
+		try {
+			await agent.prompt("Start the service, continue, and cancel the service");
+			await commands.finish();
+			const results = agent.state.messages.filter((message) => message.role === "toolResult");
+			assert.match(results[0].content[0].text, /still running/);
+			assert.equal(results[1].content[0].text, "continued");
+			assert.equal(results[2].isError, false);
+			assert.equal(JSON.parse(results[2].content[0].text).commands[0].state, "cancelled");
+			assert.equal(agent.state.errorMessage, undefined);
+			await commands.shutdown();
+			assert.deepEqual((await controlChildCommand(dir, "status", "service")).commands.map(({ toolCallId }) => toolCallId), ["service"]);
+			await assert.rejects(controlChildCommand(dir, "status", "unknown"), /No retained command/);
+		} finally { agent.abort(); await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+});
+
+describe("command identities and bounded observation", () => {
+	it("does not cancel a newer command when an old id is supplied, and preserves a custom backend", async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-identity-"));
+		const commands = createChildCommandRuntime(dir);
+		let signal: AbortSignal | undefined;
+		const custom: ToolDefinition = {
+			name: "bash", label: "Custom shell", description: "Custom execution", parameters: Type.Object({ command: Type.String() }),
+			async execute(_id, _params, inputSignal, update) {
+				signal = inputSignal;
+				update?.({ content: [{ type: "text", text: "x".repeat(16_384) }], details: undefined });
+				await new Promise<void>((_resolve, reject) => { inputSignal!.addEventListener("abort", () => reject(new Error("cancelled")), { once: true }); });
+				return { content: [], details: undefined };
+			},
+		};
+		try {
+			await commands.wrap(custom).execute("new", { command: "custom", yieldTimeMs: 0 }, undefined, undefined, ctx);
+			await assert.rejects(controlChildCommand(dir, "cancel", "old"), /No retained command 'old'/);
+			assert.equal(signal?.aborted, false);
+			assert.equal(Buffer.byteLength(commands.state().commands[0].output), 8192);
+			assert.equal(commands.operate("status", "new").commands[0].state, "yielded");
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+	it("answers status without rewriting command state and persists a real change", async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-status-"));
+		const commands = createChildCommandRuntime(dir);
+		const custom: ToolDefinition = {
+			name: "bash", label: "Custom shell", description: "Custom execution", parameters: Type.Object({ command: Type.String() }),
+			async execute(_id, params, inputSignal) {
+				if ((params as { command: string }).command === "done") return { content: [{ type: "text", text: "done" }], details: undefined };
+				await new Promise<void>((_resolve, reject) => { inputSignal!.addEventListener("abort", () => reject(new Error("cancelled")), { once: true }); });
+				return { content: [], details: undefined };
+			},
+		};
+		const statePath = path.join(dir, "commands.json");
+		try {
+			const bash = commands.wrap(custom);
+			await bash.execute("finished", { command: "done" }, undefined, undefined, ctx);
+			await bash.execute("running", { command: "wait", yieldTimeMs: 0 }, undefined, undefined, ctx);
+			fs.rmSync(statePath);
+			await commands.tool().execute("check-finished", { action: "status", toolCallId: "finished", waitMs: 50 }, undefined, undefined, ctx);
+			await commands.tool().execute("check-running", { action: "status", toolCallId: "running" }, undefined, undefined, ctx);
+			assert.equal(fs.existsSync(statePath), false, "child status must not rewrite commands.json");
+			fs.writeFileSync(statePath, JSON.stringify({ ...commands.state(), commands: [] }));
+			assert.equal((await controlChildCommand(dir, "status", "running")).commands[0].state, "yielded");
+			assert.deepEqual(readChildCommandState(dir)?.commands, [], "supervisor status must not rewrite commands.json");
+			await controlChildCommand(dir, "cancel", "running");
+			assert.ok(readChildCommandState(dir)?.commands.some((command) => command.toolCallId === "running"), "cancel must persist");
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+	it("retains the native run abort signal after yielding", async () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-child-abort-"));
+		const commands = createChildCommandRuntime(dir);
+		const controller = new AbortController();
+		const pidFile = path.join(dir, "service.pid");
+		try {
+			await commands.wrap(createBashToolDefinition(dir)).execute("run-abort", { command: serviceCommand(pidFile), yieldTimeMs: 0 }, controller.signal, undefined, ctx);
+			await until(() => fs.existsSync(pidFile), commands.state);
+			const pid = Number(fs.readFileSync(pidFile));
+			controller.abort();
+			await until(() => commands.state().commands[0].endedAt !== undefined);
+			assert.equal(commands.state().commands[0].state, "failed", "run abort is distinct from command cancellation");
+			await until(() => !processAlive(pid), commands.state);
+		} finally { await commands.shutdown(); await fs.promises.rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+	});
+
+});

package/dist/extensions/pi-subagents/test/unit/child-external-job-bridge.test.ts

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
+import { EXTERNAL_JOB_PROVIDER_REGISTRY_KEY, registerExternalJobProvider } from "../../src/api/external-job-provider.ts";
+import { createChildExternalJobBridgeSweeper, EXTERNAL_JOB_BRIDGE_REQUEST_DIR } from "../../src/runs/shared/external-job-bridge.ts";
+import { runExternalJob } from "../../src/runs/shared/external-job-runner.ts";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+	delete (globalThis as Record<PropertyKey, unknown>)[Symbol.for(EXTERNAL_JOB_PROVIDER_REGISTRY_KEY)];
+	for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(prefix: string): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+	tempDirs.push(dir);
+	return dir;
+}
+
+function writeStatus(asyncDir: string, state: string, runnerType: string): void {
+	fs.writeFileSync(path.join(asyncDir, "status.json"), JSON.stringify({ state, steps: [{ runner: { type: runnerType } }] }));
+}
+
+async function sweepUntil<T>(sweeper: ReturnType<typeof createChildExternalJobBridgeSweeper>, promise: Promise<T>): Promise<T> {
+	let done = false;
+	promise.then(() => { done = true; }, () => { done = true; });
+	while (!done) {
+		sweeper.sweep();
+		await new Promise((resolve) => setTimeout(resolve, 10));
+	}
+	return promise;
+}
+
+function runJob(asyncDir: string) {
+	return runExternalJob({ provider: "surf-oracle", options: {}, cwd: asyncDir, prompt: "prompt text", asyncDir, stepIndex: 0, runId: "run-1", agent: "gpt-pro" });
+}
+
+function registerProvider(onStart: () => void): void {
+	registerExternalJobProvider({
+		name: "surf-oracle",
+		start: () => {
+			onStart();
+			return { providerJobId: "job-1", state: "completed" };
+		},
+		status: () => ({ providerJobId: "job-1", state: "completed" }),
+		reattach: () => ({ providerJobId: "job-1", state: "completed" }),
+		result: () => ({ providerJobId: "job-1", state: "completed", output: "advisor result" }),
+	});
+}
+
+describe("child external-job bridge sweeper", () => {
+	it("services a tracked run before its status exists, starts the provider job once, and releases the run when final", async () => {
+		const dir = tempDir("pi-child-bridge-");
+		let starts = 0;
+		registerProvider(() => { starts += 1; });
+		const sweeper = createChildExternalJobBridgeSweeper();
+		try {
+			sweeper.track("run-1", dir);
+			assert.equal(sweeper.sweep(), 1);
+			const result = await sweepUntil(sweeper, runJob(dir));
+			assert.equal(result.output, "advisor result");
+			assert.equal(starts, 1);
+			writeStatus(dir, "complete", "external-job");
+			assert.equal(sweeper.sweep(), 0);
+		} finally {
+			sweeper.dispose();
+		}
+	});
+
+	it("keeps a run tracked while its launch status has no runner metadata, then services the bridge", async () => {
+		const dir = tempDir("pi-child-bridge-startup-");
+		fs.writeFileSync(path.join(dir, "status.json"), JSON.stringify({ state: "running", steps: [{ agent: "gpt-pro", status: "pending" }] }));
+		let starts = 0;
+		registerProvider(() => { starts += 1; });
+		const sweeper = createChildExternalJobBridgeSweeper();
+		try {
+			sweeper.track("run-1", dir);
+			assert.equal(sweeper.sweep(), 1);
+			writeStatus(dir, "running", "external-job");
+			const result = await sweepUntil(sweeper, runJob(dir));
+			assert.equal(result.output, "advisor result");
+			assert.equal(starts, 1);
+		} finally {
+			sweeper.dispose();
+		}
+	});
+
+	it("fails the run closed when the child has no provider registered", async () => {
+		const dir = tempDir("pi-child-bridge-missing-");
+		writeStatus(dir, "running", "external-job");
+		const sweeper = createChildExternalJobBridgeSweeper();
+		try {
+			sweeper.track("run-1", dir);
+			const result = await sweepUntil(sweeper, runJob(dir));
+			assert.notEqual(result.exitCode, 0);
+			assert.match(result.error ?? "", /not registered/);
+		} finally {
+			sweeper.dispose();
+		}
+	});
+
+	it("never services a run without external-job steps and releases it when final", () => {
+		const dir = tempDir("pi-child-bridge-native-");
+		writeStatus(dir, "running", "pi");
+		fs.mkdirSync(path.join(dir, EXTERNAL_JOB_BRIDGE_REQUEST_DIR));
+		const sweeper = createChildExternalJobBridgeSweeper();
+		sweeper.track("run-2", dir);
+		assert.equal(sweeper.sweep(), 1);
+		assert.equal(fs.existsSync(path.join(dir, "external-job-responses")), false);
+		writeStatus(dir, "complete", "pi");
+		assert.equal(sweeper.sweep(), 0);
+		sweeper.dispose();
+	});
+
+	it("stops tracking every run on dispose", () => {
+		const dir = tempDir("pi-child-bridge-dispose-");
+		writeStatus(dir, "running", "external-job");
+		const sweeper = createChildExternalJobBridgeSweeper();
+		sweeper.track("run-3", dir);
+		sweeper.dispose();
+		assert.equal(sweeper.sweep(), 0);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/child-launch-plan.test.ts

@@ -16,6 +16,17 @@ const agent = {
 } as AgentConfig;
 
 describe("child launch planning", () => {
+	it("inherits, overrides, and explicitly disables an agent output schema", () => {
+		const inherited = { type: "object", required: ["ok"] };
+		const override = { type: "object", required: ["value"] };
+		const schemaAgent = { ...agent, outputSchema: inherited };
+
+		assert.equal(resolveStepBehavior(schemaAgent, {}).outputSchema, inherited);
+		assert.equal(resolveStepBehavior(schemaAgent, { outputSchema: override }).outputSchema, override);
+		assert.equal(resolveStepBehavior(schemaAgent, { outputSchema: false }).outputSchema, undefined);
+		assert.deepEqual(resolveStepBehavior({ ...agent, outputSchema: {} }, {}).outputSchema, {});
+	});
+
 	it("resolves cwd, behavior, skills, model, and output path without side effects", () => {
 		const runnerCwd = path.join("/tmp", "repo");
 		const resolvedRunnerCwd = path.resolve(runnerCwd);
@@ -91,4 +102,4 @@ describe("child launch planning", () => {
 
 		assert.equal(plan.behavior.progress, false);
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/child-lifecycle.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { projectChildLifecycle, type ChildLifecycleState } from "../../src/runs/shared/child-lifecycle.ts";
+
+describe("child lifecycle final drain", () => {
+	for (const type of ["turn_start", "agent_start", "auto_retry_start"]) {
+		it(`cancels the previous final drain when resumed work emits ${type}`, () => {
+			const state: ChildLifecycleState = { compactionRetryActive: false };
+			assert.equal(projectChildLifecycle({ type: "message_end" }, true, state), "start-drain");
+			assert.equal(projectChildLifecycle({ type }, false, state), "cancel-drain");
+			assert.equal(projectChildLifecycle({ type: "agent_settled" }, false, state), "start-drain");
+		});
+	}
+
+	it("does not drain compaction settlement before its retry starts", () => {
+		const state: ChildLifecycleState = { compactionRetryActive: false };
+		assert.equal(projectChildLifecycle({ type: "compaction_end", willRetry: true }, false, state), "cancel-drain");
+		assert.equal(projectChildLifecycle({ type: "agent_settled" }, false, state), "none");
+		assert.equal(projectChildLifecycle({ type: "auto_retry_start" }, false, state), "cancel-drain");
+		assert.equal(state.compactionRetryActive, false);
+		assert.equal(projectChildLifecycle({ type: "agent_settled" }, false, state), "start-drain");
+	});
+
+	it("still drains a final message or settled session without resumed work", () => {
+		assert.equal(projectChildLifecycle({ type: "message_end" }, true), "start-drain");
+		assert.equal(projectChildLifecycle({ type: "agent_settled" }), "start-drain");
+		assert.equal(projectChildLifecycle({ type: "message_update" }), "none");
+	});
+
+	it("cancels the final drain on a plain agent_end", () => {
+		const state: ChildLifecycleState = { compactionRetryActive: false };
+		assert.equal(projectChildLifecycle({ type: "message_end" }, true, state), "start-drain");
+		assert.equal(projectChildLifecycle({ type: "agent_end" }, false, state), "cancel-drain");
+		assert.equal(projectChildLifecycle({ type: "agent_settled" }, false, state), "start-drain");
+	});
+});

package/dist/extensions/pi-subagents/test/unit/child-runtime-config.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import { createChildHooks } from "../../src/runs/shared/child-hooks.ts";
+import { buildInProcessChildLaunch } from "../../src/runs/shared/child-launch.ts";
 import { childSupervisorMetadata, evaluateChildToolDiagnostic, type ChildRuntimeConfig } from "../../src/runs/shared/child-runtime-config.ts";
 
 function baseConfig(overrides: Partial<ChildRuntimeConfig> = {}): ChildRuntimeConfig {
@@ -36,6 +37,29 @@ describe("child runtime config", () => {
 		assert.deepEqual(createChildHooks(baseConfig({ fanoutChild: true })).map((hook) => hook.name), ["pi-subagents:prompt-runtime", "pi-subagents:fanout-child"]);
 	});
 
+	it("provides the coordinator reply tool before agent_start without granting it to leaves", async () => {
+		for (const tools of [["subagent", "contact_supervisor", "subagent_supervisor"], ["subagent", "contact_supervisor"], ["contact_supervisor"]]) {
+			const launch = buildInProcessChildLaunch({
+				host: "parent", cwd: process.cwd(), childAgentName: "coordinator", childIndex: 0,
+				sessionEnabled: false, tools, runId: "registration", parentSessionId: "root-A",
+				inheritProjectContext: false, inheritGlobalContext: false, inheritSkills: false,
+			});
+			const pi = fakePi([]);
+			for (const hook of launch.session.hooks) hook.factory(pi.api as never);
+			const ctx = { sessionManager: { getSessionId: () => "coordinator-B", getSessionFile: () => "/sessions/B.jsonl" } };
+			try {
+				for (const handler of pi.handlers.get("session_start") ?? []) await handler({}, ctx);
+				assert.equal(pi.tools.some(tool => tool.name === "subagent_supervisor"), tools.includes("subagent"));
+				for (const handler of pi.handlers.get("agent_start") ?? []) await handler({}, ctx);
+				const selected = pi.tools.map(tool => tool.name).filter(name => launch.session.tools?.includes(name));
+				assert.equal(selected.includes("subagent_supervisor"), tools.includes("subagent_supervisor"));
+				assert.deepEqual(launch.session.tools, tools, "registration must not expand explicit tools");
+			} finally {
+				for (const handler of pi.handlers.get("session_shutdown") ?? []) await handler({}, ctx);
+			}
+		}
+	});
+
 	it("hooks read the config object", async () => {
 		const diagnostics: unknown[] = [];
 		const captured: unknown[] = [];