@selesai/code 0.8.4 → 0.8.6

package/dist/extensions/pi-subagents/test/unit/model-fallback.test.ts

@@ -2,8 +2,10 @@ import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
 	buildModelCandidates,
+	formatModelRetryNote,
 	fuzzyResolveModel,
 	isRetryableModelFailure,
+	MODEL_RETRY_DELAYS_MS,
 	normalizeModelSegment,
 	resolveEffectiveSubagentModel,
 	resolveModelCandidate,
@@ -74,6 +76,18 @@ describe("model fallback helpers", () => {
 		assert.equal(isRetryableModelFailure("model load failed"), true);
 		assert.equal(isRetryableModelFailure("Stream ended without finish_reason"), true);
 		assert.equal(isRetryableModelFailure("Request timed out."), true);
+		assert.equal(isRetryableModelFailure("503 Service Unavailable"), true);
+		assert.equal(isRetryableModelFailure("No body returned for response"), true);
+		assert.equal(isRetryableModelFailure("no response body"), true);
+		assert.equal(isRetryableModelFailure("ECONNRESET"), true);
+	});
+
+	it("ships a bounded same-model retry schedule and note", () => {
+		assert.deepEqual(MODEL_RETRY_DELAYS_MS, [500, 1500, 4000]);
+		assert.match(
+			formatModelRetryNote({ model: "anthropic/claude-sonnet-4", attempt: 1, maxAttempts: 4, delayMs: 500 }),
+			/\[model-retry\] anthropic\/claude-sonnet-4.*attempt 1\/4.*500ms/,
+		);
 	});
 
 	it("does not treat ordinary task/tool failures as retryable model failures", () => {

package/dist/extensions/pi-subagents/test/unit/owned-process-tree.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import test from "node:test";
+import { createOwnedProcessTreeController } from "../../src/runs/background/owned-process-tree.ts";
+
+function processIsActive(pid: number): boolean {
+	const result = spawnSync("ps", ["-o", "stat=", "-p", String(pid)], { encoding: "utf-8" });
+	return result.status === 0 && Boolean(result.stdout.trim()) && !result.stdout.trim().startsWith("Z");
+}
+
+test("owned process tree fails closed when process-group ownership is unsupported", { skip: process.platform !== "win32" }, async () => {
+	const proof = await createOwnedProcessTreeController(999_999).terminate();
+	assert.deepEqual(proof, { state: "unknown", reason: "unsupported-platform" });
+});
+
+test("owned process tree kills descendants and verifies a TERM-resistant POSIX group", { skip: process.platform === "win32" }, async () => {
+	const writer = spawn(process.execPath, ["-e", `
+		const { spawn } = require("node:child_process");
+		const child = spawn(process.execPath, ["-e", "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000)"], { stdio: "ignore" });
+		process.on("SIGTERM", () => {});
+		process.stdout.write(String(child.pid) + "\\n");
+		setInterval(() => {}, 1000);
+	`], { detached: true, stdio: ["ignore", "pipe", "ignore"] });
+	assert.ok(writer.pid);
+	const grandchildPid = await new Promise<number>((resolve, reject) => {
+		writer.once("error", reject);
+		writer.stdout!.once("data", (chunk) => resolve(Number(String(chunk).trim())));
+	});
+	const proof = await createOwnedProcessTreeController(writer.pid, { termGraceMs: 50, killVerifyMs: 1000 }).terminate();
+	assert.equal(proof.state, "observed", JSON.stringify(proof));
+	assert.equal(processIsActive(writer.pid), false);
+	assert.equal(processIsActive(grandchildPid), false);
+
+	const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-process-tree-ps-"));
+	const realPs = spawnSync("sh", ["-c", "command -v ps"], { encoding: "utf-8" }).stdout.trim();
+	const marker = path.join(fixtureDir, "failed-once");
+	const originalPath = process.env.PATH;
+	try {
+		fs.writeFileSync(path.join(fixtureDir, "ps"), `#!/bin/sh\nif [ ! -e "$PI_TEST_PS_MARKER" ]; then\n  : > "$PI_TEST_PS_MARKER"\n  exit 1\nfi\nexec "$PI_TEST_REAL_PS" "$@"\n`);
+		fs.chmodSync(path.join(fixtureDir, "ps"), 0o755);
+		process.env.PATH = `${fixtureDir}${path.delimiter}${originalPath ?? ""}`;
+		process.env.PI_TEST_PS_MARKER = marker;
+		process.env.PI_TEST_REAL_PS = realPs;
+		const enumerationFailureWriter = spawn(process.execPath, ["-e", `
+			process.on("SIGTERM", () => {});
+			process.stdout.write("ready\\n");
+			setInterval(() => {}, 1000);
+		`], { detached: true, stdio: ["ignore", "pipe", "ignore"] });
+		assert.ok(enumerationFailureWriter.pid);
+		await new Promise<void>((resolve, reject) => {
+			enumerationFailureWriter.once("error", reject);
+			enumerationFailureWriter.stdout!.once("data", () => resolve());
+		});
+		const termGraceMs = 50;
+		const startedAt = Date.now();
+		const failedProof = await createOwnedProcessTreeController(enumerationFailureWriter.pid, { termGraceMs, killVerifyMs: 1000 }).terminate();
+		assert.ok(Date.now() - startedAt >= termGraceMs, "enumeration failure still waits through the TERM grace before SIGKILL");
+		assert.equal(failedProof.state, "observed", JSON.stringify(failedProof));
+		assert.equal(processIsActive(enumerationFailureWriter.pid), false);
+	} finally {
+		process.env.PATH = originalPath;
+		delete process.env.PI_TEST_PS_MARKER;
+		delete process.env.PI_TEST_REAL_PS;
+		fs.rmSync(fixtureDir, { recursive: true, force: true });
+	}
+});

package/dist/extensions/pi-subagents/test/unit/pi-args.test.ts

@@ -68,6 +68,7 @@ const originalEnv = {
 	[PI_INTERCOM_SESSION_ID_ENV]: process.env[PI_INTERCOM_SESSION_ID_ENV],
 	MCP_HASH_ROOT: process.env.MCP_HASH_ROOT,
 	MCP_HASH_TOKEN: process.env.MCP_HASH_TOKEN,
+	SELESAI_SUBAGENT_TASK_DELIVERY: process.env.SELESAI_SUBAGENT_TASK_DELIVERY,
 };
 const originalCwd = process.cwd();
 const tempRoots: string[] = [];
@@ -481,6 +482,88 @@ describe("buildPiArgs model wiring", () => {
 	});
 });
 
+describe("buildPiArgs task delivery", () => {
+	const longTask = "x".repeat(8001);
+
+	function taskFileFromArgs(args: string[]): string | undefined {
+		const ref = args.find((arg) => arg.startsWith("@") && arg.endsWith("task.md"));
+		return ref ? ref.slice(1) : undefined;
+	}
+
+	it("delivers short tasks inline by default", () => {
+		const { args } = buildPiArgs({
+			baseArgs: ["-p"],
+			task: "hello",
+			sessionEnabled: false,
+			inheritProjectContext: false,
+			inheritSkills: false,
+		});
+
+		assert.ok(args.includes("Task: hello"));
+		assert.equal(taskFileFromArgs(args), undefined);
+	});
+
+	it("delivers tasks over the argv limit via a temp file by default", () => {
+		const { args } = buildPiArgs({
+			baseArgs: ["-p"],
+			task: longTask,
+			sessionEnabled: false,
+			inheritProjectContext: false,
+			inheritSkills: false,
+		});
+
+		const taskFile = taskFileFromArgs(args);
+		assert.ok(taskFile, "expected an @task.md argv reference");
+		assert.equal(fs.readFileSync(taskFile, "utf-8"), `Task: ${longTask}`);
+		assert.ok(!args.includes(`Task: ${longTask}`));
+	});
+
+	it("delivers short tasks via file when SELESAI_SUBAGENT_TASK_DELIVERY=file", () => {
+		process.env.SELESAI_SUBAGENT_TASK_DELIVERY = "file";
+		const { args } = buildPiArgs({
+			baseArgs: ["-p"],
+			task: "hello",
+			sessionEnabled: false,
+			inheritProjectContext: false,
+			inheritSkills: false,
+		});
+
+		const taskFile = taskFileFromArgs(args);
+		assert.ok(taskFile, "expected an @task.md argv reference");
+		assert.equal(fs.readFileSync(taskFile, "utf-8"), "Task: hello");
+		assert.ok(!args.includes("Task: hello"));
+	});
+
+
+	it("falls back to auto when SELESAI_SUBAGENT_TASK_DELIVERY is invalid", () => {
+		process.env.SELESAI_SUBAGENT_TASK_DELIVERY = "carrier-pigeon";
+		const { args } = buildPiArgs({
+			baseArgs: ["-p"],
+			task: longTask,
+			sessionEnabled: false,
+			inheritProjectContext: false,
+			inheritSkills: false,
+		});
+
+		assert.ok(taskFileFromArgs(args), "expected file delivery for over-limit task");
+	});
+
+	it("lets the per-launch taskDelivery override beat the env setting", () => {
+		delete process.env.SELESAI_SUBAGENT_TASK_DELIVERY;
+		const { args } = buildPiArgs({
+			baseArgs: ["-p"],
+			task: "hello",
+			taskDelivery: "file",
+			sessionEnabled: false,
+			inheritProjectContext: false,
+			inheritSkills: false,
+		});
+
+		assert.ok(taskFileFromArgs(args), "expected an @task.md argv reference");
+		assert.ok(!args.includes("Task: hello"));
+	});
+});
+
 describe("buildPiArgs system prompt mode wiring", () => {
 	it("uses --append-system-prompt by default", () => {
 		const { args } = buildPiArgs({

package/dist/extensions/pi-subagents/test/unit/pi-coding-agent-dir.test.ts

@@ -182,14 +182,14 @@ Package skill content.
 	});
 
 	it("records private redacted run history and cleans session artifacts under the configured agent dir", () => {
-		const task = "Inspect customer ACME token=SECRET";
+		const task = "PROMPT_AUDIT_SENTINEL_1021 Inspect customer ACME token=SECRET";
 		recordRun("env-agent", task, 0, 42);
 		const historyPath = path.join(agentDir, "run-history.jsonl");
 		assert.equal(fs.existsSync(historyPath), true);
 		assertPrivateHistoryModes(historyPath);
 
 		const rawHistory = fs.readFileSync(historyPath, "utf-8");
-		assert.doesNotMatch(rawHistory, /Inspect customer|ACME|SECRET/);
+		assert.doesNotMatch(rawHistory, /PROMPT_AUDIT_SENTINEL_1021|Inspect customer|ACME|SECRET/);
 		assert.match(rawHistory, /"task":"\[redacted\]"/);
 		assert.match(rawHistory, /"taskHash":"[a-f0-9]{64}"/);
 

package/dist/extensions/pi-subagents/test/unit/process-terminal.test.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import test from "node:test";
+import { ACTIVE_RUN_INDEX_DIR, updateActiveRunIndex } from "../../src/runs/background/active-run-index.ts";
 import {
 	finalizeProcessTerminal,
 	processTerminalPath,
@@ -27,6 +28,7 @@ test("process-terminal proof requires the matching runner instance and writer cl
 					closeObservedAt: 10,
 					exitCode: 0,
 					signal: null,
+					processTree: { state: "observed", mechanism: "posix-process-group", processGroupId: 123, verifiedAt: 11 },
 				}],
 			},
 		});
@@ -82,6 +84,57 @@ test("process-terminal rejects missing writer close evidence", () => {
 	}
 });
 
+test("process-terminal fails closed when process-tree verification is unknown", () => {
+	const asyncDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-process-terminal-"));
+	try {
+		writeProcessTerminalCandidate(asyncDir, {
+			version: 1,
+			runId: "run-tree-unknown",
+			runnerProcessInstanceId: "runner-tree-unknown",
+			expectedWriters: { "0": 1 },
+			writers: {
+				"0": [{
+					processInstanceId: "writer-tree-unknown",
+					kind: "pi-writer",
+					attempt: 0,
+					closeObservedAt: 10,
+					exitCode: 1,
+					signal: "SIGKILL",
+					processTree: { state: "unknown", reason: "verification-failed", diagnostic: "still live" },
+				}],
+			},
+		});
+		fs.writeFileSync(path.join(asyncDir, "status.json"), JSON.stringify({ runId: "run-tree-unknown", state: "failed", lifecycleArtifactVersion: 3, steps: [{ agent: "worker", status: "failed" }] }));
+		fs.writeFileSync(path.join(asyncDir, "events.jsonl"), "");
+		updateActiveRunIndex(asyncDir, "running");
+		const markerPath = path.join(path.dirname(asyncDir), ACTIVE_RUN_INDEX_DIR, path.basename(asyncDir));
+		const proof = finalizeProcessTerminal(asyncDir, "run-tree-unknown", {
+			processInstanceId: "runner-tree-unknown",
+			closeObservedAt: 20,
+			exitCode: 1,
+			signal: null,
+		});
+		assert.equal(proof.state, "unknown");
+		assert.equal(proof.reason, "process-tree-unverified");
+		assert.equal(fs.existsSync(markerPath), true);
+		fs.rmSync(processTerminalPath(asyncDir), { force: true });
+		const candidatePath = path.join(asyncDir, "process-terminal-candidate.json");
+		const candidate = JSON.parse(fs.readFileSync(candidatePath, "utf-8"));
+		candidate.writers["0"][0].processTree = { state: "observed", mechanism: "posix-process-group", processGroupId: 126, verifiedAt: 21 };
+		fs.writeFileSync(candidatePath, JSON.stringify(candidate));
+		const observed = finalizeProcessTerminal(asyncDir, "run-tree-unknown", {
+			processInstanceId: "runner-tree-unknown",
+			closeObservedAt: 30,
+			exitCode: 1,
+			signal: null,
+		});
+		assert.equal(observed.state, "observed");
+		assert.equal(fs.existsSync(markerPath), false);
+	} finally {
+		fs.rmSync(asyncDir, { recursive: true, force: true });
+	}
+});
+
 test("malformed process-terminal sidecars project unknown instead of throwing", () => {
 	const asyncDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-process-terminal-"));
 	try {
@@ -112,7 +165,7 @@ test("process-terminal preserves stopped non-resumability and requires lease rel
 			runnerProcessInstanceId: "stopped-runner",
 			expectedWriters: { "0": 1 },
 			writers: {
-				"0": [{ processInstanceId: "stopped-writer", kind: "pi-writer", attempt: 0, closeObservedAt: 10, exitCode: 0, signal: null }],
+				"0": [{ processInstanceId: "stopped-writer", kind: "pi-writer", attempt: 0, closeObservedAt: 10, exitCode: 0, signal: null, processTree: { state: "observed", mechanism: "posix-process-group", processGroupId: 124, verifiedAt: 11 } }],
 			},
 			revivalLeaseToken: "lease-token",
 			revivalLeaseReleaseAcknowledged: false,
@@ -161,7 +214,7 @@ test("process-terminal rejects cross-run observed sidecars and inconsistent expe
 			runnerProcessInstanceId: "runner-1",
 			expectedWriters: { "0": 0 },
 			writers: {
-				"0": [{ processInstanceId: "unexpected-writer", kind: "pi-writer", attempt: 0, closeObservedAt: 10, exitCode: 0, signal: null }],
+				"0": [{ processInstanceId: "unexpected-writer", kind: "pi-writer", attempt: 0, closeObservedAt: 10, exitCode: 0, signal: null, processTree: { state: "observed", mechanism: "posix-process-group", processGroupId: 125, verifiedAt: 11 } }],
 			},
 		});
 		fs.writeFileSync(path.join(asyncDir, "status.json"), JSON.stringify({ runId: "actual-run", state: "complete", lifecycleArtifactVersion: 3, steps: [{ agent: "worker", status: "complete" }] }));

package/dist/extensions/pi-subagents/test/unit/public-execution.test.ts

@@ -19,7 +19,18 @@ describe("public subagent execution normalization", () => {
 		);
 	});
 
-	it("rejects malformed public execution shapes", () => {
+	it("rejects private run fan-out fields at the public boundary", () => {
+		for (const params of [
+			{ workflowScript: "return 1", runFanoutBudget: { version: 1 } },
+			{ workflowScript: "return 1", runFanoutAdmitted: true },
+		] as const) {
+			const result = normalizePublicSubagentExecution(params);
+			assert.equal(result.ok, false);
+			if (!result.ok) assert.match(result.error, /does not accept internal run fan-out fields/);
+		}
+	});
+
+	it("rejects removed public execution shapes", () => {
 		for (const params of [
 			{ action: " " },
 			{ action: "single" },

package/dist/extensions/pi-subagents/test/unit/rpc.test.ts

@@ -146,7 +146,7 @@ describe("subagent extension RPC bridge", () => {
 		assert.deepEqual(executedParams, { action: "status", id: "abc123" });
 		assert.equal((reply as { data: { text?: string } }).data.text, "Run: abc123");
 		assert.deepEqual((reply as { data: { fleet?: unknown } }).data.fleet, {
-			version: 1, entries: [], totalActive: 0, omitted: 0,
+			version: 1, entries: [], totalActive: 0, topLevelAsyncCapacity: { used: 0, limit: 0 }, omitted: 0,
 		});
 
 		bridge.dispose();
@@ -174,8 +174,9 @@ describe("subagent extension RPC bridge", () => {
 		assert.equal((fleet as { omitted?: number }).omitted, 0);
 		assert.deepEqual(fleet.entries[0], {
 			key: "fleet-1", agent: "reviewer", role: "opaque label", model: "anthropic/claude-opus-4-8:high", effort: "high",
-			startedAt: 120, tokens: { input: 12, output: 34, total: 46 }, goal: "Review the diff",
+			startedAt: 120, tokens: { input: 12, output: 34, total: 46 },
 		});
+		assert.equal(JSON.stringify(fleet).includes("Review the diff"), false);
 		assert.equal(JSON.stringify(fleet).includes("async-private-id"), false);
 		bridge.dispose();
 	});
@@ -200,15 +201,13 @@ describe("subagent extension RPC bridge", () => {
 		const malformedSurrogate = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/u;
 
 		assert.doesNotMatch(entry.agent, malformedSurrogate);
-		assert.doesNotMatch(entry.goal, malformedSurrogate);
-		assert.doesNotMatch(entry.goal, /[\r\n]/);
+		assert.equal(entry.goal, undefined);
 		assert.ok(entry.agent.length <= 96);
-		assert.ok(entry.goal.length <= 512);
 		assert.match(entry.agent, /^worker broken/);
 		bridge.dispose();
 	});
 
-	it("projects resolved foreground model, effort, split usage, and goal", async () => {
+	it("projects resolved foreground model, effort, and split usage without prompt goals", async () => {
 		const events = new FakeEvents();
 		const state = {
 			currentSessionId: "session-123",
@@ -231,6 +230,7 @@ describe("subagent extension RPC bridge", () => {
 				}]]),
 			}]]),
 			asyncJobs: new Map(),
+			activeAsyncCapacity: { used: 2, limit: 4 },
 		} as any;
 		state.foregroundControls.set("private-old", {
 			runId: "private-old",
@@ -250,6 +250,7 @@ describe("subagent extension RPC bridge", () => {
 		assert.deepEqual((reply as any).data.fleet, {
 			version: 1,
 			totalActive: 1,
+			topLevelAsyncCapacity: { used: 2, limit: 4 },
 			omitted: 0,
 			entries: [{
 				key: "fleet-1",
@@ -258,7 +259,6 @@ describe("subagent extension RPC bridge", () => {
 				effort: "high",
 				startedAt: 100,
 				tokens: { input: 321, output: 45, total: 366 },
-				goal: "Implement the fix",
 			}],
 		});
 		assert.equal(JSON.stringify((reply as any).data.fleet).includes("private-run"), false);

package/dist/extensions/pi-subagents/test/unit/run-fanout-budget.test.ts

@@ -0,0 +1,121 @@
+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 { spawn } from "node:child_process";
+import { afterEach, describe, it } from "node:test";
+import {
+	claimRunFanoutBatch,
+	claimRunFanoutBatchWithCommit,
+	createRunFanoutBudget,
+	decodeRunFanoutBudgetDescriptor,
+	encodeRunFanoutBudgetDescriptor,
+	getRunFanoutBudgetSnapshot,
+	RunFanoutLimitError,
+	validateRunFanoutBudgetDescriptor,
+} from "../../src/runs/shared/run-fanout-budget.ts";
+import { resolveMaxSubagentSpawnsPerRun } from "../../src/shared/types.ts";
+
+const directories: string[] = [];
+const externalDirectories: string[] = [];
+const previousEnv = process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN;
+
+afterEach(() => {
+	for (const directory of directories.splice(0)) fs.rmSync(directory, { recursive: true, force: true });
+	for (const directory of externalDirectories.splice(0)) fs.rmSync(directory, { recursive: true, force: true });
+	if (previousEnv === undefined) delete process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN;
+	else process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN = previousEnv;
+});
+
+function budget(limit: number) {
+	const descriptor = createRunFanoutBudget(`test-${Date.now()}-${Math.random()}`, limit);
+	directories.push(descriptor.directory);
+	return descriptor;
+}
+
+describe("run fan-out budget", () => {
+	it("resolves environment over config and falls back to 64", () => {
+		delete process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN;
+		assert.equal(resolveMaxSubagentSpawnsPerRun(undefined), 64);
+		assert.equal(resolveMaxSubagentSpawnsPerRun(12), 12);
+		for (const invalid of [0, -1, 1.5, "bad"]) assert.equal(resolveMaxSubagentSpawnsPerRun(invalid as number), 64);
+		process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN = "7";
+		assert.equal(resolveMaxSubagentSpawnsPerRun(12), 7);
+		for (const invalid of ["0", "-1", "1.5", "bad"]) {
+			process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN = invalid;
+			assert.equal(resolveMaxSubagentSpawnsPerRun(undefined), 64);
+		}
+	});
+
+	it("persists claims and rejects the responsible next path at the exact cap", () => {
+		const descriptor = budget(2);
+		assert.deepEqual(claimRunFanoutBatch(descriptor, ["tasks[0]", "tasks[1]"]), { used: 2, limit: 2, remaining: 0 });
+		const restored = decodeRunFanoutBudgetDescriptor(encodeRunFanoutBudgetDescriptor(descriptor));
+		assert.deepEqual(getRunFanoutBudgetSnapshot(restored!), { used: 2, limit: 2, remaining: 0 });
+		assert.throws(() => claimRunFanoutBatch(descriptor, ["tasks[2]"]), (error: unknown) => {
+			assert.ok(error instanceof RunFanoutLimitError);
+			assert.equal(error.rejection.path, "tasks[2]");
+			assert.equal(error.rejection.used, 2);
+			assert.equal(error.rejection.remaining, 0);
+			return true;
+		});
+	});
+
+	it("rolls back only the failed admission batch", () => {
+		const descriptor = budget(2);
+		claimRunFanoutBatch(descriptor, ["single"]);
+		assert.throws(() => claimRunFanoutBatch(descriptor, ["chain[0]", "chain[1]"]), RunFanoutLimitError);
+		assert.deepEqual(getRunFanoutBudgetSnapshot(descriptor), { used: 1, limit: 2, remaining: 1 });
+	});
+
+	it("rolls back a batch when its commit fails", () => {
+		const descriptor = budget(2);
+		claimRunFanoutBatch(descriptor, ["existing"]);
+		assert.throws(
+			() => claimRunFanoutBatchWithCommit(descriptor, ["append"], () => { throw new Error("enqueue failed"); }),
+			/enqueue failed/,
+		);
+		assert.deepEqual(getRunFanoutBudgetSnapshot(descriptor), { used: 1, limit: 2, remaining: 1 });
+	});
+
+	it("reports claims-directory I/O errors instead of ordinary exhaustion", () => {
+		const descriptor = budget(2);
+		fs.rmSync(path.join(descriptor.directory, "claims"), { recursive: true });
+		fs.writeFileSync(path.join(descriptor.directory, "claims"), "not a directory", "utf-8");
+		assert.throws(() => getRunFanoutBudgetSnapshot(descriptor), /claims directory is unreadable.*ENOTDIR/);
+	});
+
+	it("admits exactly one simultaneous two-slot batch at limit two", async () => {
+		const moduleUrl = new URL("../../src/runs/shared/run-fanout-budget.ts", import.meta.url).href;
+		const script = `import { claimRunFanoutBatch } from ${JSON.stringify(moduleUrl)}; const descriptor = JSON.parse(process.argv[1]); try { claimRunFanoutBatch(descriptor, [process.argv[2] + "[0]", process.argv[2] + "[1]"]); process.stdout.write("admitted"); } catch { process.stdout.write("rejected"); }`;
+		for (let iteration = 0; iteration < 12; iteration++) {
+			const descriptor = budget(2);
+			const launch = (claimPath: string) => new Promise<string>((resolve, reject) => {
+				const child = spawn(process.execPath, ["--experimental-strip-types", "--input-type=module", "--eval", script, JSON.stringify(descriptor), claimPath], { stdio: ["ignore", "pipe", "pipe"] });
+				let stdout = "";
+				let stderr = "";
+				child.stdout.on("data", (chunk) => { stdout += chunk; });
+				child.stderr.on("data", (chunk) => { stderr += chunk; });
+				child.on("error", reject);
+				child.on("close", (code) => code === 0 ? resolve(stdout) : reject(new Error(stderr)));
+			});
+
+			assert.deepEqual((await Promise.all([launch("group-a"), launch("group-b")])).sort(), ["admitted", "rejected"], `iteration ${iteration}`);
+			assert.deepEqual(getRunFanoutBudgetSnapshot(descriptor), { used: 2, limit: 2, remaining: 0 });
+		}
+	});
+
+	it("fails closed when descriptor identity or managed-root containment is invalid", () => {
+		const descriptor = budget(2);
+		assert.throws(() => validateRunFanoutBudgetDescriptor({ ...descriptor, limit: 3 }), /does not match/);
+
+		const outside = fs.mkdtempSync(path.join(os.tmpdir(), "pi-run-fanout-outside-"));
+		externalDirectories.push(outside);
+		fs.mkdirSync(path.join(outside, "claims"));
+		fs.writeFileSync(path.join(outside, "manifest.json"), JSON.stringify({ version: 1, rootRunId: descriptor.rootRunId, limit: 2, createdAt: Date.now() }));
+		const linked = path.join(path.dirname(descriptor.directory), `linked-${Date.now()}`);
+		fs.symlinkSync(outside, linked, process.platform === "win32" ? "junction" : "dir");
+		directories.push(linked);
+		assert.throws(() => validateRunFanoutBudgetDescriptor({ ...descriptor, directory: linked }), /resolves outside/);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/run-status.test.ts

@@ -6,6 +6,7 @@ import { describe, it } from "node:test";
 import { updateActiveRunIndex } from "../../src/runs/background/active-run-index.ts";
 import { inspectSubagentStatus } from "../../src/runs/background/run-status.ts";
 import { createNestedRoute, writeNestedEvent } from "../../src/runs/shared/nested-events.ts";
+import { claimRunFanoutBatch, createRunFanoutBudget, writeRunFanoutBudgetDescriptor } from "../../src/runs/shared/run-fanout-budget.ts";
 import { TEMP_ROOT_DIR, type SubagentState } from "../../src/shared/types.ts";
 
 function errno(code: string): NodeJS.ErrnoException {
@@ -22,6 +23,7 @@ function textContent(result: ReturnType<typeof inspectSubagentStatus>): string {
 describe("async run status inspection", () => {
 	it("repairs stale running status and reports diagnosis plus result path", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-run-status-stale-"));
+		let budgetDirectory: string | undefined;
 		try {
 			const asyncRoot = path.join(root, "runs");
 			const resultsDir = path.join(root, "results");
@@ -40,6 +42,10 @@ describe("async run status inspection", () => {
 				sessionFile,
 				steps: [{ agent: "scout", status: "running", startedAt: 100, sessionFile }],
 			}, null, 2), "utf-8");
+			const descriptor = createRunFanoutBudget("run-stale", 64);
+			budgetDirectory = descriptor.directory;
+			writeRunFanoutBudgetDescriptor(asyncDir, descriptor);
+			claimRunFanoutBatch(descriptor, ["single"]);
 
 			const result = inspectSubagentStatus({ id: "run-stale" }, {
 				asyncDirRoot: asyncRoot,
@@ -51,6 +57,8 @@ describe("async run status inspection", () => {
 			const text = textContent(result);
 			assert.equal(result.isError, undefined);
 			assert.match(text, /State: failed/);
+			assert.match(text, /Run fan-out: 1\/64 used, 63 remaining/);
+			assert.deepEqual(result.details.runFanoutBudget, { used: 1, limit: 64, remaining: 63 });
 			assert.match(text, /Diagnosis: Async runner process 12345 exited or disappeared/);
 			assert.match(text, new RegExp(`Result: ${path.join(resultsDir, "run-stale.json").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`));
 			assert.match(text, /Step 1: scout failed, error: Async runner process 12345 exited or disappeared/);
@@ -60,6 +68,7 @@ describe("async run status inspection", () => {
 			assert.equal(resultJson.results[0].sessionFile, sessionFile);
 		} finally {
 			fs.rmSync(root, { recursive: true, force: true });
+			if (budgetDirectory) fs.rmSync(budgetDirectory, { recursive: true, force: true });
 		}
 	});
 

package/dist/extensions/pi-subagents/test/unit/schemas.test.ts

@@ -236,12 +236,13 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.ok(maxRuntimeSchema, "maxRuntimeMs schema should exist");
 		assert.equal(timeoutSchema.minimum, 1);
 		assert.equal(maxRuntimeSchema.minimum, 1);
-		assert.match(String(timeoutSchema.description ?? ""), /foreground runs and async children/i);
-		assert.match(String(timeoutSchema.description ?? ""), /async children default to 30m/i);
+		assert.match(String(timeoutSchema.description ?? ""), /foreground and single async runs/i);
+		assert.match(String(timeoutSchema.description ?? ""), /use config timeoutMs, else 30m/i);
 		assert.match(String(timeoutSchema.description ?? ""), /async composites have no default parent deadline/i);
 		assert.doesNotMatch(String(timeoutSchema.description ?? ""), /foreground-only/i);
 		assert.match(String(maxRuntimeSchema.description ?? ""), /timeoutMs/i);
-		assert.match(String(maxRuntimeSchema.description ?? ""), /async children default to 30m/i);
+		assert.match(String(maxRuntimeSchema.description ?? ""), /foreground and single async runs/i);
+		assert.match(String(maxRuntimeSchema.description ?? ""), /use config timeoutMs, else 30m/i);
 		assert.match(String(maxRuntimeSchema.description ?? ""), /async composites have no default parent deadline/i);
 		assert.equal(turnBudgetSchema?.properties?.maxTurns?.minimum, 1);
 		assert.equal(turnBudgetSchema?.properties?.graceTurns?.minimum, 0);

package/dist/extensions/pi-subagents/test/unit/session-lineage.test.ts

@@ -0,0 +1,73 @@
+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 { describe, it } from "node:test";
+import { resolveSessionLineage } from "../../src/shared/session-lineage.ts";
+
+function sessionFile(dir: string, name: string, parentSession?: string): string {
+	const file = path.join(dir, name);
+	const header = {
+		type: "session",
+		version: 1,
+		id: name,
+		timestamp: new Date().toISOString(),
+		cwd: dir,
+		...(parentSession ? { parentSession } : {}),
+	};
+	fs.writeFileSync(file, `${JSON.stringify(header)}\n`);
+	return file;
+}
+
+describe("session lineage", () => {
+	it("resolves self plus the parent chain from session headers", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "selesai-lineage-"));
+		const grandparent = sessionFile(dir, "a.jsonl");
+		const parent = sessionFile(dir, "b.jsonl", grandparent);
+		const current = sessionFile(dir, "c.jsonl", parent);
+		const lineage = resolveSessionLineage({ sessionManager: { getSessionFile: () => current, getHeader: () => ({ parentSession: parent }) } });
+		assert.deepEqual(lineage, [current, parent, grandparent]);
+	});
+
+	it("prefers an explicit parent hint over the header", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "selesai-lineage-"));
+		const hinted = sessionFile(dir, "hinted.jsonl");
+		const headed = sessionFile(dir, "headed.jsonl");
+		const current = sessionFile(dir, "current.jsonl", headed);
+		const lineage = resolveSessionLineage({ sessionManager: { getSessionFile: () => current, getHeader: () => ({ parentSession: headed }) } }, { parentHint: hinted });
+		assert.deepEqual(lineage, [current, hinted]);
+	});
+
+	it("bounds the walk depth", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "selesai-lineage-"));
+		const files: string[] = [];
+		for (let i = 0; i < 12; i++) files.push(sessionFile(dir, `s${i}.jsonl`, i > 0 ? files[i - 1]! : undefined));
+		const current = sessionFile(dir, "current.jsonl", files[11]);
+		const lineage = resolveSessionLineage({ sessionManager: { getSessionFile: () => current } }, { depth: 3 });
+		assert.equal(lineage.length, 3);
+		assert.equal(lineage[0], current);
+		assert.equal(lineage[1], files[11]);
+		assert.equal(lineage[2], files[10]);
+	});
+
+	it("stops at missing parent files", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "selesai-lineage-"));
+		const missing = path.join(dir, "missing.jsonl");
+		const current = sessionFile(dir, "current.jsonl", missing);
+		const lineage = resolveSessionLineage({ sessionManager: { getSessionFile: () => current, getHeader: () => ({ parentSession: missing }) } });
+		assert.deepEqual(lineage, [current]);
+	});
+
+	it("does not loop on cyclic parent chains", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "selesai-lineage-"));
+		const a = sessionFile(dir, "a.jsonl");
+		const b = sessionFile(dir, "b.jsonl", a);
+		fs.writeFileSync(a, `${JSON.stringify({ type: "session", version: 1, id: "a", timestamp: new Date().toISOString(), cwd: dir, parentSession: b })}\n`);
+		const lineage = resolveSessionLineage({ sessionManager: { getSessionFile: () => b, getHeader: () => ({ parentSession: a }) } });
+		assert.deepEqual(lineage, [b, a]);
+	});
+
+	it("handles session managers without getHeader or session file", () => {
+		assert.deepEqual(resolveSessionLineage({ sessionManager: { getSessionFile: () => null } }, { parentHint: "/nonexistent/parent.jsonl" }), []);
+	});
+});