@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/test/unit/control-channel.test.ts

@@ -13,6 +13,9 @@ import {
 	deliverInterruptRequest,
 	enqueueStepSteer,
 	interruptRequestPath,
+	MAX_STEER_QUEUE_SIZE,
+	queueRevivalBrief,
+	readRevivalBriefs,
 	requestAsyncInterrupt,
 	requestAsyncSteer,
 	requestAsyncStop,
@@ -108,13 +111,13 @@ describe("control channel: request file", () => {
 	it("writes and consumes ordered steer requests", () => {
 		const asyncDir = tmpAsyncDir("pi-control-steer-");
 		try {
-			requestAsyncSteer(asyncDir, { message: "  later guidance  ", targetIndex: 1, id: "b", ts: 200, source: "test" });
+			requestAsyncSteer(asyncDir, { message: "  later guidance  ", mode: "follow_up", targetIndex: 1, id: "b", ts: 200, source: "test" });
 			requestAsyncSteer(asyncDir, { message: "first guidance", targetIndexes: [0, 2], id: "a", ts: 100 });
 			assert.equal(fs.readdirSync(steerRequestsDir(asyncDir)).length, 2);
 
 			assert.deepEqual(consumeSteerRequests(asyncDir), [
 				{ type: "steer", id: "a", ts: 100, message: "first guidance", targetIndexes: [0, 2] },
-				{ type: "steer", id: "b", ts: 200, message: "later guidance", targetIndex: 1, source: "test" },
+				{ type: "steer", id: "b", ts: 200, message: "later guidance", mode: "follow_up", targetIndex: 1, source: "test" },
 			]);
 			assert.deepEqual(consumeSteerRequests(asyncDir), []);
 		} finally {
@@ -210,6 +213,19 @@ describe("control channel: request file", () => {
 		}
 	});
 
+	it("bounds retained revival briefs and keeps them FIFO", () => {
+		const asyncDir = tmpAsyncDir("pi-control-revival-brief-");
+		try {
+			for (let index = 0; index < MAX_STEER_QUEUE_SIZE; index++) {
+				queueRevivalBrief(asyncDir, { type: "steer", id: `brief-${index}`, ts: index + 1, message: `brief ${index}`, mode: "follow_up" });
+			}
+			assert.deepEqual(readRevivalBriefs(asyncDir).map(({ request }) => request.id), Array.from({ length: MAX_STEER_QUEUE_SIZE }, (_, index) => `brief-${index}`));
+			assert.throws(() => queueRevivalBrief(asyncDir, { type: "steer", id: "full", ts: 99, message: "too much", mode: "follow_up" }), /queue is full/);
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
+
 	it("rejects empty steer messages and invalid target indexes", () => {
 		const asyncDir = tmpAsyncDir("pi-control-steer-invalid-");
 		try {
@@ -232,16 +248,27 @@ describe("control channel: request file", () => {
 		try {
 			const capabilityPath = writeSteerCapability(asyncDir, { index: 0, pid: 42, readyAt: 100, supported: true });
 			assert.equal(capabilityPath, steerCapabilityPath(asyncDir, 0));
-			writeSteerAck(asyncDir, { requestId: "../request", index: 0, ts: 101, state: "delivered", message: "accepted" });
+			writeSteerAck(asyncDir, { requestId: "../request", index: 0, ts: 101, state: "queued", deliveryStatus: "queued", message: "accepted" });
 			assert.equal(path.dirname(steerAckPathFromDir(steerAcksDir(asyncDir, 0), "../request")), steerAcksDir(asyncDir, 0));
 			assert.deepEqual(consumeSteerCapabilities(asyncDir), [{ type: "steer-capability", protocolVersion: 1, index: 0, pid: 42, readyAt: 100, supported: true }]);
-			assert.deepEqual(consumeSteerAcks(asyncDir), [{ type: "steer-ack", protocolVersion: 1, requestId: "../request", index: 0, ts: 101, state: "delivered", message: "accepted" }]);
+			assert.deepEqual(consumeSteerAcks(asyncDir), [{ type: "steer-ack", protocolVersion: 1, requestId: "../request", index: 0, ts: 101, state: "queued", deliveryStatus: "queued", message: "accepted" }]);
 			assert.deepEqual(consumeSteerAcks(asyncDir), []);
 		} finally {
 			cleanup(asyncDir);
 		}
 	});
 
+	it("preserves queued and delivered receipts for the same request", () => {
+		const asyncDir = tmpAsyncDir("pi-control-steer-ack-order-");
+		try {
+			writeSteerAck(asyncDir, { requestId: "follow", index: 0, ts: 101, state: "queued", deliveryStatus: "queued", message: "queued" });
+			writeSteerAck(asyncDir, { requestId: "follow", index: 0, ts: 102, state: "delivered", deliveryStatus: "delivered", message: "delivered" });
+			assert.deepEqual(consumeSteerAcks(asyncDir).map((ack) => ack.state), ["queued", "delivered"]);
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
+
 	it("ignores malformed capabilities and acknowledgments", () => {
 		const asyncDir = tmpAsyncDir("pi-control-steer-malformed-");
 		try {
@@ -260,75 +287,22 @@ describe("control channel: request file", () => {
 });
 
 describe("control channel: deliverInterruptRequest", () => {
-	it("writes the portable request and signals best-effort when kill succeeds", () => {
-		const asyncDir = tmpAsyncDir("pi-control-deliver-ok-");
+	it("writes the portable request without signaling an unverified pid", () => {
+		const asyncDir = tmpAsyncDir("pi-control-deliver-file-only-");
 		try {
 			const kills: Array<{ pid: number; signal?: NodeJS.Signals | 0 }> = [];
-			deliverInterruptRequest({
+			const unverifiedInput = {
 				asyncDir,
 				pid: 4242,
-				signal: "SIGUSR2",
-				kill: (pid, signal) => {
+				signal: "SIGUSR2" as NodeJS.Signals,
+				kill: (pid: number, signal?: NodeJS.Signals | 0) => {
 					kills.push({ pid, signal });
 					return true;
 				},
-			});
-			assert.equal(fs.existsSync(interruptRequestPath(asyncDir)), true);
-			assert.deepEqual(kills, [{ pid: 4242, signal: "SIGUSR2" }]);
-		} finally {
-			cleanup(asyncDir);
-		}
-	});
-
-	it("still writes the request when the OS signal throws ENOSYS (Windows)", () => {
-		const asyncDir = tmpAsyncDir("pi-control-deliver-enosys-");
-		try {
-			assert.doesNotThrow(() =>
-				deliverInterruptRequest({
-					asyncDir,
-					pid: 4242,
-					kill: () => {
-						const error = new Error("kill ENOSYS") as NodeJS.ErrnoException;
-						error.code = "ENOSYS";
-						throw error;
-					},
-				}),
-			);
-			assert.equal(fs.existsSync(interruptRequestPath(asyncDir)), true);
-		} finally {
-			cleanup(asyncDir);
-		}
-	});
-
-	it("surfaces non-portability signal failures and removes the stale request", () => {
-		const asyncDir = tmpAsyncDir("pi-control-deliver-esrch-");
-		try {
-			assert.throws(
-				() =>
-					deliverInterruptRequest({
-						asyncDir,
-						pid: 4242,
-						kill: () => {
-							const error = new Error("missing process") as NodeJS.ErrnoException;
-							error.code = "ESRCH";
-							throw error;
-						},
-					}),
-				/missing process/,
-			);
-			assert.equal(fs.existsSync(interruptRequestPath(asyncDir)), false);
-		} finally {
-			cleanup(asyncDir);
-		}
-	});
-
-	it("skips signalling when no live pid is provided", () => {
-		const asyncDir = tmpAsyncDir("pi-control-deliver-nopid-");
-		try {
-			let killed = false;
-			deliverInterruptRequest({ asyncDir, kill: () => { killed = true; return true; } });
-			assert.equal(killed, false);
+			};
+			deliverInterruptRequest(unverifiedInput);
 			assert.equal(fs.existsSync(interruptRequestPath(asyncDir)), true);
+			assert.deepEqual(kills, []);
 		} finally {
 			cleanup(asyncDir);
 		}
@@ -339,14 +313,19 @@ describe("control channel: watchAsyncControlInbox", () => {
 	type WatchHarness = {
 		fsImpl: import("../../src/runs/background/control-channel.ts").ControlChannelFs;
 		timers: import("../../src/runs/background/control-channel.ts").ControlChannelTimers;
-		trigger: () => void;
+		trigger: (dir?: string) => void;
+		triggerError: (dir?: string) => void;
 		closed: () => boolean;
+		intervalCount: () => number;
+		intervalDelays: () => number[];
 		watchedDir: () => string | undefined;
 	};
 
 	function harness(nativeDir?: string): WatchHarness {
-		let listener: (() => void) | undefined;
+		const listeners = new Map<string, () => void>();
+		const errorListeners = new Map<string, () => void>();
 		let closed = false;
+		const intervalDelays: number[] = [];
 		let watchedDir: string | undefined;
 		const realpathSync = ((target: fs.PathLike, options?: unknown) => fs.realpathSync(target, options as BufferEncoding)) as typeof fs.realpathSync;
 		realpathSync.native = ((target: fs.PathLike) => nativeDir ?? fs.realpathSync.native(target)) as typeof fs.realpathSync.native;
@@ -359,15 +338,38 @@ describe("control channel: watchAsyncControlInbox", () => {
 			realpathSync,
 			watch: ((dir: string, cb: () => void) => {
 				watchedDir = dir;
-				listener = cb;
-				return { close: () => { closed = true; }, on: () => {} };
+				listeners.set(dir, cb);
+				return {
+					close: () => { closed = true; },
+					on: (event: string, handler: () => void) => {
+						if (event === "error") errorListeners.set(dir, handler);
+					},
+				};
 			}),
 		} as unknown as WatchHarness["fsImpl"];
 		const timers = {
-			setInterval: (() => ({ unref() {} })) as unknown as typeof setInterval,
+			setInterval: ((_handler: Parameters<typeof setInterval>[0], delay?: number) => {
+				intervalDelays.push(delay ?? 0);
+				return { unref() {} };
+			}) as unknown as typeof setInterval,
 			clearInterval: (() => {}) as unknown as typeof clearInterval,
 		};
-		return { fsImpl, timers, trigger: () => listener?.(), closed: () => closed, watchedDir: () => watchedDir };
+		return {
+			fsImpl,
+			timers,
+			trigger: (dir?: string) => {
+				if (dir) listeners.get(dir)?.();
+				else for (const listener of listeners.values()) listener();
+			},
+			triggerError: (dir?: string) => {
+				if (dir) errorListeners.get(dir)?.();
+				else for (const listener of errorListeners.values()) listener();
+			},
+			closed: () => closed,
+			intervalCount: () => intervalDelays.length,
+			intervalDelays: () => [...intervalDelays],
+			watchedDir: () => watchedDir,
+		};
 	}
 
 	it("registers the native canonical control inbox path", () => {
@@ -383,6 +385,32 @@ describe("control channel: watchAsyncControlInbox", () => {
 		}
 	});
 
+	it("does not start fast polling when native watch is available", () => {
+		const asyncDir = tmpAsyncDir("pi-control-watch-no-poll-");
+		try {
+			const h = harness();
+			const dispose = watchAsyncControlInbox(asyncDir, { onInterrupt() {}, fs: h.fsImpl, timers: h.timers });
+			assert.deepEqual(h.intervalDelays(), [5000]);
+			dispose();
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
+
+	it("starts portable polling once when the native watcher fails", () => {
+		const asyncDir = tmpAsyncDir("pi-control-watch-fallback-");
+		try {
+			const h = harness();
+			const dispose = watchAsyncControlInbox(asyncDir, { onInterrupt() {}, fs: h.fsImpl, timers: h.timers });
+			h.triggerError();
+			h.triggerError();
+			assert.deepEqual(h.intervalDelays(), [5000, 250]);
+			dispose();
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
+
 	it("fires on a request that arrived before the watcher started", () => {
 		const asyncDir = tmpAsyncDir("pi-control-watch-early-");
 		try {
@@ -471,4 +499,30 @@ describe("control channel: watchAsyncControlInbox", () => {
 			cleanup(asyncDir);
 		}
 	});
+
+	it("delivers later steer files from the watched request directory without polling", () => {
+		const asyncDir = tmpAsyncDir("pi-control-watch-steer-nested-");
+		try {
+			const steers: string[] = [];
+			const h = harness();
+			const dispose = watchAsyncControlInbox(asyncDir, {
+				onInterrupt() {},
+				onSteer: (request) => steers.push(request.message),
+				fs: h.fsImpl,
+				timers: h.timers,
+			});
+
+			const watchedSteerDir = fs.realpathSync.native(steerRequestsDir(asyncDir));
+			requestAsyncSteer(asyncDir, { message: "first", id: "s1", ts: 1 });
+			h.trigger(watchedSteerDir);
+			requestAsyncSteer(asyncDir, { message: "second", id: "s2", ts: 2 });
+			h.trigger(watchedSteerDir);
+
+			assert.deepEqual(steers, ["first", "second"]);
+			assert.deepEqual(h.intervalDelays(), [5000]);
+			dispose();
+		} finally {
+			cleanup(asyncDir);
+		}
+	});
 });

package/dist/extensions/pi-subagents/test/unit/control-notices.test.ts

@@ -26,9 +26,9 @@ function needsAttentionEvent(overrides: Partial<ControlEvent> = {}): ControlEven
 		to: "needs_attention",
 		ts: 1,
 		runId: "run-1",
-		agent: "builder",
+		agent: "worker",
 		index: 0,
-		message: "builder needs attention",
+		message: "worker needs attention",
 		reason: "idle",
 		...overrides,
 	};
@@ -62,6 +62,21 @@ describe("subagent control notice delivery", () => {
 		assert.deepEqual(recorder.sent[0]?.options, { triggerTurn: true });
 	});
 
+	it("delivers goal notices without starting a new turn", () => {
+		const state = makeState();
+		const recorder = makeRecorder();
+
+		handleSubagentControlNotice({
+			pi: recorder.pi,
+			state,
+			visibleControlNotices: new Set(),
+			details: { source: "goal", event: needsAttentionEvent(), noticeText: "Goal is ready." },
+		});
+
+		assert.equal(recorder.sent.length, 1);
+		assert.deepEqual(recorder.sent[0]?.options, { triggerTurn: false });
+	});
+
 	it("does not queue a foreground notice that Pi could flush after completion", () => {
 		const state = makeState();
 		state.foregroundControls.set("run-1", {
@@ -69,7 +84,7 @@ describe("subagent control notice delivery", () => {
 			mode: "parallel",
 			startedAt: 0,
 			updatedAt: 0,
-			currentAgent: "builder",
+			currentAgent: "worker",
 			currentIndex: 0,
 			currentActivityState: "needs_attention",
 		});

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

@@ -55,18 +55,18 @@ describe("subagents.defaultExtensions", () => {
 	});
 
 	it("preserves ambient discovery when omitted and disables it when empty", () => {
-		let explorer = discoverAgentsAll(tempProject).builtin.find(
-			(agent) => agent.name === "explorer",
+		let scout = discoverAgentsAll(tempProject).builtin.find(
+			(agent) => agent.name === "scout",
 		);
-		assert.equal(explorer?.extensions, undefined);
+		assert.equal(scout?.extensions, undefined);
 
 		writeJson(path.join(tempHome, ".selesai", "agent", "settings.json"), {
 			subagents: { defaultExtensions: [] },
 		});
-		explorer = discoverAgentsAll(tempProject).builtin.find(
-			(agent) => agent.name === "explorer",
+		scout = discoverAgentsAll(tempProject).builtin.find(
+			(agent) => agent.name === "scout",
 		);
-		assert.deepEqual(explorer?.extensions, []);
+		assert.deepEqual(scout?.extensions, []);
 	});
 
 	it("applies the allowlist only when an agent has no extensions field", () => {
@@ -97,7 +97,7 @@ describe("subagents.defaultExtensions", () => {
 			subagents: {
 				defaultExtensions: [],
 				agentOverrides: {
-					explorer: { extensions: ["./explorer.ts"] },
+					scout: { extensions: ["./scout.ts"] },
 					inherited: { extensions: ["./inherited.ts"] },
 					explicit: { extensions: ["./ignored.ts"] },
 				},
@@ -108,8 +108,8 @@ describe("subagents.defaultExtensions", () => {
 
 		const agents = discoverAgents(tempProject, "both").agents;
 		assert.deepEqual(
-			agents.find((agent) => agent.name === "explorer")?.extensions,
-			["./explorer.ts"],
+			agents.find((agent) => agent.name === "scout")?.extensions,
+			["./scout.ts"],
 		);
 		assert.deepEqual(
 			agents.find((agent) => agent.name === "inherited")?.extensions,
@@ -185,19 +185,19 @@ describe("subagents.defaultExtensions", () => {
 
 		assert.deepEqual(
 			discoverAgents(tempProject, "both").agents.find(
-				(agent) => agent.name === "explorer",
+				(agent) => agent.name === "scout",
 			)?.extensions,
 			[],
 		);
 		assert.deepEqual(
 			discoverAgents(tempProject, "user").agents.find(
-				(agent) => agent.name === "explorer",
+				(agent) => agent.name === "scout",
 			)?.extensions,
 			["./user.ts"],
 		);
 		assert.deepEqual(
 			discoverAgents(tempProject, "project").agents.find(
-				(agent) => agent.name === "explorer",
+				(agent) => agent.name === "scout",
 			)?.extensions,
 			[],
 		);

package/dist/extensions/pi-subagents/test/unit/delegation-api.test.ts

@@ -48,7 +48,7 @@ const request: SubagentDelegationRequest = {
 	requestId: "attempt-1",
 	ownerRunId: "owner-1",
 	nodeId: "node-1",
-	agent: "commentator",
+	agent: "reviewer",
 	task: "Review evidence",
 	context: "fresh",
 	cwd: "/repo",
@@ -137,13 +137,13 @@ describe("public subagent delegation contract", () => {
 			},
 			executeStructured: async (_id, params, _signal, _ctx, onUpdate) => {
 				observedParams = params as unknown as Record<string, unknown>;
-				onUpdate({ details: { mode: "single", runId: "run-1", results: [{ agent: "commentator", model: "openai/gpt-5", thinking: "high" }], progress: [{ currentTool: "read" }] } });
+				onUpdate({ details: { mode: "single", runId: "run-1", results: [{ agent: "reviewer", model: "openai/gpt-5", thinking: "high" }], progress: [{ currentTool: "read" }] } });
 				return {
 					details: {
 						mode: "single",
 						runId: "run-1",
 						results: [{
-							agent: "commentator",
+							agent: "reviewer",
 							exitCode: 0,
 							model: "openai/gpt-5",
 							thinking: "high",
@@ -169,7 +169,7 @@ describe("public subagent delegation contract", () => {
 			nodeId: "node-1",
 			status: "completed",
 			runId: "run-1",
-			agent: "commentator",
+			agent: "reviewer",
 			model: "openai/gpt-5",
 			thinking: "high",
 			exitCode: 0,
@@ -179,7 +179,7 @@ describe("public subagent delegation contract", () => {
 		} satisfies SubagentDelegationResponse);
 		assert.equal(ordinaryCalls, 0);
 		assert.deepEqual(observedParams, {
-			agent: "commentator",
+			agent: "reviewer",
 			task: "Review evidence",
 			context: "fresh",
 			cwd: "/repo",
@@ -217,7 +217,7 @@ describe("public subagent delegation contract", () => {
 					details: {
 						mode: "single",
 						results: [{
-							agent: "commentator",
+							agent: "reviewer",
 							exitCode: 0,
 							...(structuredOutput === undefined ? {} : { structuredOutput }),
 							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
@@ -345,7 +345,7 @@ describe("public subagent delegation contract", () => {
 					details: {
 						mode: "single",
 						results: [{
-							agent: "commentator",
+							agent: "reviewer",
 							exitCode: 0,
 							finalOutput: requestId,
 							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
@@ -399,7 +399,7 @@ describe("public subagent delegation contract", () => {
 					details: {
 						mode: "single",
 						results: [{
-							agent: "commentator",
+							agent: "reviewer",
 							exitCode: 0,
 							finalOutput: requestId,
 							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 1 },
@@ -445,37 +445,31 @@ describe("public subagent delegation contract", () => {
 		settledBridge.dispose();
 	});
 
-	it("retains the unversioned prompt-template bridge as legacy fallback", async () => {
+	it("rejects the unversioned prompt-template direct delegation fallback", async () => {
 		const events = new FakeEvents();
-		let structuredCalls = 0;
-		let legacyCalls = 0;
+		let executeCalls = 0;
 		const bridge = registerPromptTemplateDelegationBridge({
 			events,
 			getContext: () => ({ cwd: "/repo" }),
 			execute: async () => {
-				legacyCalls++;
-				return { content: [{ type: "text", text: "legacy done" }], details: { mode: "single", results: [{ agent: "commentator", finalOutput: "legacy done", exitCode: 0 }] } };
-			},
-			executeStructured: async () => {
-				structuredCalls++;
-				return { details: { mode: "single", results: [] } };
+				executeCalls++;
+				return { content: [{ type: "text", text: "unreachable" }], details: { mode: "single", results: [] } };
 			},
 		});
 		const responsePromise = once(events, SUBAGENT_DELEGATION_RESPONSE_EVENT);
 		events.emit(SUBAGENT_DELEGATION_REQUEST_EVENT, {
 			requestId: "legacy-1",
-			agent: "commentator",
+			agent: "reviewer",
 			task: "Legacy prompt-template delegation",
 			context: "fresh",
 			model: "openai/gpt-5",
 			cwd: "/repo",
 		});
-		const response = await responsePromise as { requestId: string; isError: boolean; contentText?: string };
+		const response = await responsePromise as { requestId: string; isError: boolean; errorText?: string };
 		assert.equal(response.requestId, "legacy-1");
-		assert.equal(response.isError, false);
-		assert.equal(response.contentText, "legacy done");
-		assert.equal(legacyCalls, 1);
-		assert.equal(structuredCalls, 0);
+		assert.equal(response.isError, true);
+		assert.match(response.errorText ?? "", /Legacy prompt-template direct delegation was removed/);
+		assert.equal(executeCalls, 0);
 		bridge.dispose();
 	});
 });

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

@@ -43,7 +43,7 @@ function makeChain(name: string, source: ChainConfig["source"]): ChainConfig {
 		description: `${name} chain`,
 		source,
 		filePath: `/tmp/${name}.chain.md`,
-		steps: [{ agent: "builder", task: "Work" }],
+		steps: [{ agent: "worker", task: "Work" }],
 	};
 }
 
@@ -69,7 +69,7 @@ describe("buildDoctorReport", () => {
 
 			const report = buildDoctorReport({
 				cwd: root,
-				config: { defaultSessionDir: "~/subagent-sessions", intercomBridge: { mode: "always" }, maxSubagentSpawnsPerSession: 4 },
+				config: { defaultSessionDir: "~/subagent-sessions", intercomBridge: { mode: "always" }, maxSubagentSpawnsPerSession: 4, maxActiveAsyncRunsPerSession: 2 },
 				state,
 				currentSessionFile: path.join(root, "sessions", "parent.jsonl"),
 				currentSessionId: "session-abc123",
@@ -116,6 +116,10 @@ describe("buildDoctorReport", () => {
 			assert.match(report, /Spawn budget\n- usage: 3\/5 used, 2 remaining \(configured 4; granted 1; grant allowance 3\)/);
 			assert.match(report, /- recent grants: \+1 at 1970-01-01T00:00:00\.000Z \(4 → 5\)/);
 			assert.match(report, /new parent session resets usage and grants; compaction does not/);
+			assert.match(report, /Run fan-out budget\n- configured limit: 64 \(default\)/);
+			assert.match(report, /cumulative claims are never released; a new top-level run creates a new budget/);
+			assert.match(report, /Active async capacity\n- usage: 0\/2 used/);
+			assert.match(report, /missing or unknown cleanup proof retains capacity/);
 			assert.match(report, /- skills: total 2 \(project 1, user-package 1\)/);
 			assert.match(report, /- bridge: active/);
 			assert.match(report, /- supervisor channel: available \(native:pi-subagents-supervisor-channel\)/);
@@ -125,6 +129,30 @@ describe("buildDoctorReport", () => {
 		}
 	});
 
+	it("reports the effective source when the run fan-out environment value is invalid", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-doctor-fanout-source-"));
+		const previous = process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN;
+		try {
+			process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN = "invalid";
+			const report = buildDoctorReport({
+				cwd: root,
+				config: { maxSubagentSpawnsPerRun: 12 },
+				state: makeState(root),
+				deps: {
+					isAsyncAvailable: () => true,
+					discoverAgentsAll: () => ({ builtin: [], user: [], project: [], chains: [], userDir: root, projectDir: root, userChainDir: root, projectChainDir: root, userSettingsPath: path.join(root, "user.json"), projectSettingsPath: path.join(root, "project.json") }),
+					discoverAvailableSkills: () => [],
+					diagnoseIntercomBridge: () => ({ active: false, mode: "off", wantsIntercom: false, supervisorChannelAvailable: false, extensionDir: "none" }),
+				},
+			});
+			assert.match(report, /Run fan-out budget\n- configured limit: 12 \(config\)/);
+		} finally {
+			if (previous === undefined) delete process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN;
+			else process.env.SELESAI_SUBAGENT_MAX_SPAWNS_PER_RUN = previous;
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
 	it("keeps reporting when a directory or discovery check fails", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-doctor-failure-"));
 		try {