@selesai/code 0.6.2 → 0.7.0

package/dist/extensions/pi-subagents/test/unit/tool-description.test.ts

@@ -9,10 +9,8 @@ import {
 	buildSubagentToolDescription,
 	COMPACT_SUBAGENT_TOOL_DESCRIPTION,
 	FULL_SUBAGENT_TOOL_DESCRIPTION,
-	SUBAGENT_PARENT_ROUTING_GUIDANCE,
 	SUBAGENT_SAFETY_GUIDANCE,
 } from "../../src/extension/tool-description.ts";
-import { BUILTIN_AGENT_NAMES } from "../../src/agents/agents.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../../src/runs/shared/pi-args.ts";
 
 const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -30,132 +28,30 @@ function parentToolEnv(agentDir?: string): NodeJS.ProcessEnv {
 }
 
 describe("registered subagent tool description", () => {
-	it("keeps full mode safe and free of hardcoded builtin agent names", () => {
+	it("describes workflowScript as the sole public orchestration surface", () => {
 		const description = buildSubagentToolDescription();
-
-		for (const builtinName of BUILTIN_AGENT_NAMES) {
-			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
-		}
-		for (const legacyName of ["scout", "worker", "planner"]) {
-			assert.doesNotMatch(description, new RegExp(`\\b${legacyName}\\b`));
-		}
-		assert.match(description, /^To delegate work, call with \{ agent, task \}, \{ tasks \}, or \{ chain \}; omit action\./i);
-		assert.match(description, /Use action only for management\/control actions listed below/i);
-		assert.match(description, /use \{ action: "list" \} to inspect configured agents\/chains/i);
-		assert.match(description, /executable\/non-disabled/i);
-		assert.match(description, /proactive skill subagent suggestions/i);
-		assert.doesNotMatch(description, /disabled builtins/i);
-		assert.match(description, /output\?,reads\?,progress\?/i);
-		assert.match(description, /timeoutMs/i);
-		assert.match(description, /maxRuntimeMs/i);
-		assert.match(description, /foreground and async\/background runs/i);
-		assert.match(description, /omit acceptance for reviewer\/read-only calls/i);
-		assert.match(description, /acceptance\.review\.required/i);
-		assert.match(description, /reviewed is achieved only after an independent reviewer result/i);
-		assert.doesNotMatch(description, /only for foreground runs/i);
-		assert.doesNotMatch(description, /omit for async\/background runs/i);
+		assert.match(description, /^Delegate one child with \{ agent, task \} or compose work with \{ workflowScript \}/i);
+		assert.match(description, /workflowScript is the sole public orchestration surface/i);
+		assert.match(description, /runs\.run for one child and runs\.all for parallel children/i);
+		assert.match(description, /repository mutation lanes.*worktree:true.*direct single child.*runs\.run\/runs\.all.*managed isolation.*manual Git worktrees/i);
+		assert.match(description, /Sequential replacement/i);
+		assert.match(description, /Parallel replacement/i);
+		assert.doesNotMatch(description, /Compatibility tasks\[\]|CHAIN EXAMPLES|PARALLEL \(compatibility\)/i);
+		assert.match(description, /append-step.*step:/i);
+		assert.match(description, /cannot access filesystem, shell, arbitrary Pi tools, or host globals/i);
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
-		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
-		assert.match(description, /call \{ action: "list" \} and select only an executable entry using its current role, context, and tool metadata/i);
-		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
-		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
-		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
-		assert.match(description, /Do not sleep or poll status just to wait/i);
-		assert.match(description, /use subagent_wait/i);
-		assert.match(description, /interactive session.*normally return control/i);
-		assert.match(description, /Headless sessions auto-drain current-session work at agent_end/i);
-		assert.doesNotMatch(description, /MUST call subagent_wait/i);
-		assert.match(description, /ordinary child subagents are not orchestrators/i);
-		assert.match(description, /keep one writer/i);
-		assert.match(description, /view: "fleet"/);
-		assert.match(description, /view: "transcript"/);
-		assert.match(description, /action: "steer"/);
-		assert.match(description, /schedule-list/);
-		assert.match(description, /action: "eject"/);
-		assert.match(description, /action: "eject", agent: "agent-name"/);
-		assert.match(description, /action: "disable", agent: "agent-name"/);
-		assert.match(description, /action: "enable", agent: "agent-name"/);
-		assert.match(description, /action: "reset", agent: "agent-name"/);
-		assert.match(description, /action: "disable"/);
-		assert.match(description, /action: "grant-spawn-budget"/);
-		assert.match(description, /root interactive parent/i);
-		assert.match(description, /cumulative grants cannot exceed the original configured cap/i);
-		assert.match(description, /acceptanceRole affects inferred acceptance only/i);
-		assert.match(description, /Explicit task mutation\/no-edit intent wins/i);
-		assert.match(description, /omission preserves name heuristics/i);
-		assert.match(description, /false or an empty string to clear it/i);
 		assert.match(description, /status\.json/);
-		assert.match(description, /events\.jsonl/);
-		// Chain quick-reference: both sequential and parallel fan-out examples (#417)
-		assert.match(description, /CHAIN EXAMPLES/i);
-		assert.match(
-			description,
-			/chain:\s*\[\s*\{\s*agent:\s*"[\w-]+",\s*task:\s*"[^"]*"\s*\}\s*,\s*\{\s*agent:\s*"[\w-]+",\s*task:\s*"[^"]*\{previous\}[^"]*"\s*\}\s*\]/,
-			"full mode should show a sequential chain example using {previous}",
-		);
-		assert.match(
-			description,
-			/\{\s*parallel:\s*\[\s*\{\s*agent:\s*"[\w-]+",\s*task:\s*"[^"]*",\s*count:\s*\d+\s*\}\s*\]\s*\}/,
-			"full mode should show a parallel fan-out chain example with count",
-		);
 	});
 
-	it("offers a compact mode that keeps safety-critical guidance", () => {
+	it("offers a compact mode that keeps the cutover and safety guidance", () => {
 		const description = buildSubagentToolDescription({ toolDescriptionMode: "compact" });
-
 		assert.equal(description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
-		assert.match(description, /^To delegate work, call with \{ agent, task \}, \{ tasks \}, or \{ chain \}; omit action\./i);
-		assert.match(description, /Use action only for management\/control actions listed below/i);
-		assert.ok(description.length < FULL_SUBAGENT_TOOL_DESCRIPTION.length * 0.8, "compact mode should be materially shorter than full mode");
-		assert.match(description, /SINGLE/);
-		assert.match(description, /PARALLEL/);
-		assert.match(description, /CHAIN/);
-		assert.match(description, /action without execution fields/i);
-		assert.match(description, /Parent-only routing/);
-		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
-		assert.match(description, /Keep tiny targeted reads and simple answers local/i);
-		assert.match(description, /broad local investigation, external research, and mutation\/implementation work/i);
-		assert.match(description, /parent remains the decision-maker and normally the sole writer/i);
-		for (const builtinName of BUILTIN_AGENT_NAMES) {
-			assert.doesNotMatch(description, new RegExp(`\\b${builtinName}\\b`));
-		}
+		assert.match(description, /workflowScript is the sole public orchestration surface/i);
+		assert.match(description, /runs\.run for one child and runs\.all for parallel work/i);
+		assert.match(description, /repository mutation lanes.*worktree:true.*direct single child.*runs\.run\/runs\.all.*managed isolation.*manual Git worktrees/i);
+		assert.doesNotMatch(description, /tasks\[\]|chain\[\]/i);
 		assert.match(description, /subagent_wait/i);
-		assert.match(description, /interactive session.*normally return control/i);
-		assert.match(description, /Non-interactive runs.*auto-drain current-session work at agent_end/i);
-		assert.doesNotMatch(description, /MUST call subagent_wait/i);
-		assert.match(description, /Do not sleep or poll/i);
-		assert.match(description, /ordinary child subagents are not orchestrators/i);
-		assert.match(description, /one writer/i);
-		assert.match(description, /omit acceptance for reviewer\/read-only calls/i);
-		assert.match(description, /acceptance\.review\.required/i);
-		assert.match(description, /reviewed is an achieved status/i);
-		assert.match(description, /view:"fleet"/);
-		assert.match(description, /view:"transcript"/);
-		assert.match(description, /steer/);
-		assert.match(description, /schedule-list/);
-		assert.match(description, /eject/);
-		assert.match(description, /disable/);
-		assert.match(description, /grant-spawn-budget/);
-		assert.match(description, /acceptanceRole.*affects inferred acceptance only/i);
-		assert.match(description, /Explicit task intent wins/i);
-		assert.match(description, /omission keeps name heuristics/i);
-		assert.match(description, /false or an empty string to clear it/i);
-		assert.match(description, /status\.json/);
-		assert.match(description, /events\.jsonl/);
-		// Compact mode keeps a chain quick-reference too (#417)
-		assert.match(description, /chain example/i);
-		assert.match(description, /\{previous\}/);
-		assert.match(description, /parallel:/);
-		assert.match(description, /count:/);
-	});
-
-	it("documents task-aware list advice as explicit-only in both modes", () => {
-		for (const description of [FULL_SUBAGENT_TOOL_DESCRIPTION, COMPACT_SUBAGENT_TOOL_DESCRIPTION]) {
-			assert.match(description, /\{ action: "list", task: "\.\.\." \}/);
-			assert.match(description, /advisory/i);
-			assert.match(description, /never launches/i);
-			assert.match(description, /explicitly call subagent|execute the recommended agent explicitly/i);
-		}
+		assert.ok(description.length < FULL_SUBAGENT_TOOL_DESCRIPTION.length);
 	});
 
 	it("renders a custom project description with placeholders and mandatory safety guidance", () => {
@@ -179,8 +75,6 @@ describe("registered subagent tool description", () => {
 		assert.match(description, new RegExp(escapeRegex(agentDir)));
 		assert.match(description, new RegExp(escapeRegex(projectConfigDir)));
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
-		assert.match(description, /PARENT-ONLY SUBAGENT ROUTING/);
-		assert.match(description, /select only an executable entry using its current role, context, and tool metadata/i);
 		assert.equal(warnings.length, 0);
 	});
 
@@ -246,7 +140,7 @@ describe("registered subagent tool description", () => {
 		assert.ok(warnings.some((message) => message.includes("Ignoring invalid toolDescriptionMode")));
 	});
 
-	function readRegisteredTool(agentDir: string): { description: string; promptGuidelines?: string[] } {
+	function readRegisteredDescription(agentDir: string): string {
 		const script = String.raw`
 			import registerSubagentExtension from "./src/extension/index.ts";
 			const events = { on() { return () => {}; }, emit() {} };
@@ -267,10 +161,7 @@ describe("registered subagent tool description", () => {
 			});
 			registerSubagentExtension(fakePi);
 			if (!registeredTool) throw new Error("tool not registered");
-			process.stdout.write(JSON.stringify({
-				description: registeredTool.description,
-				promptGuidelines: registeredTool.promptGuidelines ?? null,
-			}));
+			process.stdout.write(JSON.stringify(registeredTool.description));
 		`;
 		const output = execFileSync(
 			process.execPath,
@@ -284,7 +175,7 @@ describe("registered subagent tool description", () => {
 			],
 			{ cwd: projectRoot, env: parentToolEnv(agentDir), encoding: "utf-8" },
 		);
-		return JSON.parse(output) as { description: string; promptGuidelines?: string[] };
+		return JSON.parse(output) as string;
 	}
 
 	function writeExtensionConfig(agentDir: string, config: Record<string, unknown>): void {
@@ -295,40 +186,25 @@ describe("registered subagent tool description", () => {
 
 	it("registers full, compact, custom, and fallback descriptions from extension config", () => {
 		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-default-"));
-		assert.equal(readRegisteredTool(defaultAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredDescription(defaultAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const compactAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-compact-"));
 		writeExtensionConfig(compactAgentDir, { toolDescriptionMode: "compact" });
-		assert.equal(readRegisteredTool(compactAgentDir).description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredDescription(compactAgentDir), COMPACT_SUBAGENT_TOOL_DESCRIPTION);
 
 		const customAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-custom-"));
 		writeExtensionConfig(customAgentDir, { toolDescriptionMode: "custom" });
 		fs.writeFileSync(path.join(customAgentDir, "subagent-tool-description.md"), "Registered custom description.", "utf-8");
-		const customDescription = readRegisteredTool(customAgentDir).description;
+		const customDescription = readRegisteredDescription(customAgentDir);
 		assert.match(customDescription, /Registered custom description/);
 		assert.match(customDescription, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
 
 		const missingCustomAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-missing-"));
 		writeExtensionConfig(missingCustomAgentDir, { toolDescriptionMode: "custom" });
-		assert.equal(readRegisteredTool(missingCustomAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(readRegisteredDescription(missingCustomAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const invalidAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-invalid-"));
 		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny" });
-		assert.equal(readRegisteredTool(invalidAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
-	});
-
-	it("registers parent-only routing guidance as promptGuidelines on the parent tool", () => {
-		const defaultAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-guidelines-"));
-		const registered = readRegisteredTool(defaultAgentDir);
-
-		assert.ok(Array.isArray(registered.promptGuidelines), "parent subagent tool must expose promptGuidelines");
-		assert.equal(registered.promptGuidelines!.length, 1);
-		assert.equal(registered.promptGuidelines![0], SUBAGENT_PARENT_ROUTING_GUIDANCE);
-		assert.doesNotMatch(SUBAGENT_PARENT_ROUTING_GUIDANCE, new RegExp(BUILTIN_AGENT_NAMES.join("|")));
-		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /\{ action: "list" \}/);
-		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /executable entry/i);
-		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /tiny targeted reads and simple answers local/i);
-		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /broad local investigation, external research, and mutation\/implementation work/i);
-		assert.match(SUBAGENT_PARENT_ROUTING_GUIDANCE, /decision-maker and normally the sole writer/i);
+		assert.equal(readRegisteredDescription(invalidAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
 	});
 });

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

@@ -50,13 +50,13 @@ describe("turn-budget module", () => {
 
 	describe("appendTurnBudgetSystemPrompt", () => {
 		it("returns the system prompt unchanged when no budget is configured", () => {
-			assert.equal(appendTurnBudgetSystemPrompt("You are a reviewer.", undefined), "You are a reviewer.");
+			assert.equal(appendTurnBudgetSystemPrompt("You are a commentator.", undefined), "You are a commentator.");
 			assert.equal(appendTurnBudgetSystemPrompt("", undefined), "");
 		});
 
 		it("appends a turn-budget block after an existing system prompt", () => {
-			const result = appendTurnBudgetSystemPrompt("You are a reviewer.", budget({ maxTurns: 5, graceTurns: 2 }));
-			assert.ok(result.startsWith("You are a reviewer.\n\n## Turn budget\n"), result);
+			const result = appendTurnBudgetSystemPrompt("You are a commentator.", budget({ maxTurns: 5, graceTurns: 2 }));
+			assert.ok(result.startsWith("You are a commentator.\n\n## Turn budget\n"), result);
 			assert.match(result, /soft budget of 5 assistant turns/);
 			assert.match(result, /2 additional assistant turns/);
 		});
@@ -68,8 +68,8 @@ describe("turn-budget module", () => {
 		});
 
 		it("trims surrounding whitespace from the existing system prompt before joining", () => {
-			const result = appendTurnBudgetSystemPrompt("\nYou are a reviewer.\n\n", budget());
-			assert.ok(result.startsWith("You are a reviewer.\n\n## Turn budget\n"), result);
+			const result = appendTurnBudgetSystemPrompt("\nYou are a commentator.\n\n", budget());
+			assert.ok(result.startsWith("You are a commentator.\n\n## Turn budget\n"), result);
 			assert.equal(result.startsWith("\n"), false);
 		});
 
@@ -178,9 +178,10 @@ describe("turn-budget module", () => {
 	});
 
 	describe("turnBudgetDecision", () => {
-		it("continues below the hard limit and for a terminal response on the final grace turn", () => {
+		it("continues for a clean terminal response even after the hard limit", () => {
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 3, false, false), "continue");
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 4, true, false), "continue");
+			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 5, true, false), "continue");
 		});
 
 		it("defers termination when the hard-limit assistant response starts tool work", () => {
@@ -188,14 +189,15 @@ describe("turn-budget module", () => {
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 5, false, true), "defer");
 		});
 
-		it("enforces the hard limit for strict foreground delegation but allows the exact terminal boundary", () => {
+		it("enforces the hard limit for strict foreground delegation but allows terminal completion", () => {
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 4, false, true, true), "abort");
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 4, true, true, true), "continue");
+			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 5, true, true, true), "continue");
 		});
 
-		it("aborts at the next safe assistant boundary", () => {
+		it("aborts non-terminal work at the next safe assistant boundary", () => {
 			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 4, false, false), "abort");
-			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 5, true, false), "abort");
+			assert.equal(turnBudgetDecision(budget({ maxTurns: 3, graceTurns: 1 }), 5, false, false), "abort");
 		});
 
 		it("allows a terminal response at the soft limit when grace turns are zero", () => {

package/dist/extensions/pi-subagents/test/unit/wait-subscriptions.test.ts

@@ -0,0 +1,351 @@
+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 { waitForSubagents } from "../../src/runs/background/subagent-wait.ts";
+import { registerWaitTool } from "../../src/runs/background/wait-tool.ts";
+import { createWaitSubscriptionManager } from "../../src/runs/background/wait-subscriptions.ts";
+import { inspectSubagentStatus } from "../../src/runs/background/run-status.ts";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT, type IntercomEventBus, type SubagentState } from "../../src/shared/types.ts";
+
+function writeStatus(asyncRoot: string, runId: string, state: string, extra: object = {}): void {
+	const dir = path.join(asyncRoot, runId);
+	fs.mkdirSync(dir, { recursive: true });
+	const now = Date.now();
+	fs.writeFileSync(path.join(dir, "status.json"), JSON.stringify({
+		runId,
+		mode: "single",
+		state,
+		startedAt: now,
+		lastUpdate: now,
+		steps: [{ agent: "builder", status: state }],
+		...extra,
+	}), "utf-8");
+}
+
+function makeState(sessionId = "session-a"): SubagentState {
+	return {
+		baseCwd: "",
+		currentSessionId: sessionId,
+		asyncJobs: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: { schedule: () => false, clear: () => {} },
+	} as SubagentState;
+}
+
+class TestBus implements IntercomEventBus {
+	private handlers = new Map<string, Set<(data: unknown) => void>>();
+
+	on(channel: string, handler: (data: unknown) => void): () => void {
+		const handlers = this.handlers.get(channel) ?? new Set();
+		handlers.add(handler);
+		this.handlers.set(channel, handlers);
+		return () => handlers.delete(handler);
+	}
+
+	emit(channel: string, data: unknown): void {
+		for (const handler of this.handlers.get(channel) ?? []) handler(data);
+	}
+}
+
+function textOf(result: { content: Array<{ type: string; text?: string }> }): string {
+	return result.content.map((entry) => entry.text ?? "").join("");
+}
+
+describe("non-blocking wait subscriptions", () => {
+	it("returns immediately and binds an id prefix to one exact run", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-arm-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			writeStatus(asyncRoot, "run-alpha", "running", { sessionId: "session-a", pid: 999_999 });
+			let armed: { targetKind: "async" | "foreground"; runId: string; requestedId: string; timeoutMs: number } | undefined;
+			const result = await waitForSubagents({ id: "run-al", nonBlocking: true, timeoutMs: 5_000 }, undefined, {
+				state: makeState(),
+				asyncDirRoot: asyncRoot,
+				resultsDir: path.join(root, "results"),
+				kill: () => true,
+				sleep: async () => { throw new Error("non-blocking wait must not sleep"); },
+				subscribe: (input) => {
+					armed = input;
+					return { token: "wait-token", expiresAt: 6_000 };
+				},
+			});
+
+			assert.equal(result.isError, undefined);
+			assert.match(textOf(result), /Armed wait subscription wait-token/);
+			assert.deepEqual(armed, { targetKind: "async", runId: "run-alpha", requestedId: "run-al", timeoutMs: 5_000 });
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects non-blocking subscriptions from headless tool calls", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-headless-"));
+		try {
+			const state = makeState();
+			state.foregroundRuns = new Map([["run-headless", {
+				runId: "run-headless",
+				mode: "single",
+				cwd: root,
+				sessionId: "session-a",
+				updatedAt: Date.now(),
+				children: [{ agent: "builder", index: 0, status: "detached" }],
+			}]]);
+			let tool: { execute: (...args: unknown[]) => Promise<{ content: Array<{ text?: string }>; isError?: boolean }> } | undefined;
+			registerWaitTool({
+				events: new TestBus(),
+				registerTool(value: unknown) { tool = value as typeof tool; },
+			} as never, state, true, {
+				arm() { throw new Error("headless calls must not arm subscriptions"); },
+			});
+			const result = await tool!.execute("wait", { id: "run-headless", nonBlocking: true }, undefined, undefined, { hasUI: false });
+			assert.equal(result.isError, true);
+			assert.match(textOf(result), /long-lived interactive subagent runtime/);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("restores durable registrations and wakes on exact completion", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-restore-"));
+		const asyncRoot = path.join(root, "runs");
+		const resultsDir = path.join(root, "results");
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const bus = new TestBus();
+		const sent: Array<{ message: { content?: unknown }; options?: { triggerTurn?: boolean } }> = [];
+		const pi = {
+			events: bus,
+			sendMessage(message: { content?: unknown }, options?: { triggerTurn?: boolean }) { sent.push({ message, options }); },
+		};
+		try {
+			writeStatus(asyncRoot, "run-exact", "running", { sessionId: "session-a", pid: 999_999 });
+			const firstState = makeState();
+			const first = createWaitSubscriptionManager(pi as never, firstState, { asyncDirRoot: asyncRoot, resultsDir, subscriptionsDir, pollIntervalMs: 60_000, kill: () => true });
+			const registration = first.arm({ targetKind: "async", runId: "run-exact", requestedId: "run-ex", timeoutMs: 30_000 });
+			assert.equal(fs.existsSync(path.join(subscriptionsDir, `${registration.token}.json`)), true);
+			first.dispose();
+
+			const restoredState = makeState();
+			const restored = createWaitSubscriptionManager(pi as never, restoredState, { asyncDirRoot: asyncRoot, resultsDir, subscriptionsDir, pollIntervalMs: 60_000, kill: () => true });
+			restored.restore();
+			assert.equal(restoredState.waitSubscriptions?.has(registration.token), true);
+			const status = inspectSubagentStatus({}, { state: restoredState, asyncDirRoot: asyncRoot, resultsDir, kill: () => true });
+			assert.match(textOf(status), new RegExp(`Armed wait subscriptions.*${registration.token}`, "s"));
+
+			writeStatus(asyncRoot, "unrelated-run", "complete", { sessionId: "session-a" });
+			restored.reconcile();
+			assert.equal(sent.length, 0, "an unrelated exact run must not satisfy the subscription");
+
+			writeStatus(asyncRoot, "run-exact", "complete", { sessionId: "session-a" });
+			bus.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, { runId: "run-exact" });
+			assert.equal(sent.length, 1);
+			assert.match(String(sent[0]?.message.content), /run run-exact: completed/);
+			assert.equal(sent[0]?.options?.triggerTurn, true);
+			assert.equal(restoredState.waitSubscriptions?.has(registration.token), false);
+			assert.equal(fs.existsSync(path.join(subscriptionsDir, `${registration.token}.json`)), false);
+			restored.dispose();
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("keeps subscriptions active across a session restart", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-restart-"));
+		const asyncRoot = path.join(root, "runs");
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const bus = new TestBus();
+		const sent: string[] = [];
+		const state = makeState();
+		const manager = createWaitSubscriptionManager({
+			events: bus,
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		} as never, state, { asyncDirRoot: asyncRoot, subscriptionsDir, pollIntervalMs: 60_000, kill: () => true });
+		try {
+			writeStatus(asyncRoot, "run-restart", "running", { sessionId: "session-a", pid: 999_999 });
+			const registration = manager.arm({ targetKind: "async", runId: "run-restart", requestedId: "run-restart", timeoutMs: 30_000 });
+
+			state.currentSessionId = null;
+			manager.restore();
+			state.currentSessionId = "session-a";
+			writeStatus(asyncRoot, "run-restart", "complete", { sessionId: "session-a" });
+			manager.restore();
+
+			assert.match(sent[0] ?? "", /run run-restart: completed/);
+			assert.equal(state.waitSubscriptions?.has(registration.token), false);
+		} finally {
+			manager.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("waits for foreground run restoration before reconciling a restored subscription", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-foreground-restore-"));
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const bus = new TestBus();
+		const sent: string[] = [];
+		const firstState = makeState();
+		firstState.foregroundRuns = new Map([["run-foreground", {
+			runId: "run-foreground",
+			mode: "single",
+			cwd: root,
+			sessionId: "session-a",
+			updatedAt: Date.now(),
+			children: [{ agent: "builder", index: 0, status: "detached" }],
+		}]]);
+		const pi = {
+			events: bus,
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		};
+		const first = createWaitSubscriptionManager(pi as never, firstState, { subscriptionsDir, pollIntervalMs: 60_000 });
+		try {
+			const registration = first.arm({ targetKind: "foreground", runId: "run-foreground", requestedId: "run-foreground", timeoutMs: 30_000 });
+			first.dispose();
+
+			const restoredState = makeState();
+			restoredState.foregroundRuns = new Map();
+			const restored = createWaitSubscriptionManager(pi as never, restoredState, { subscriptionsDir, pollIntervalMs: 60_000 });
+			try {
+				restored.restore();
+				assert.equal(sent.length, 0);
+				assert.equal(restoredState.waitSubscriptions?.has(registration.token), true);
+
+				restoredState.foregroundRuns = new Map([["run-foreground", {
+					runId: "run-foreground",
+					mode: "single",
+					cwd: root,
+					sessionId: "session-a",
+					updatedAt: Date.now(),
+					children: [],
+				}]]);
+				restored.reconcile();
+				assert.match(sent[0] ?? "", /run run-foreground: completed/);
+				assert.equal(restoredState.waitSubscriptions?.has(registration.token), false);
+			} finally {
+				restored.dispose();
+			}
+		} finally {
+			first.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("settles a missing live foreground run as unreconcilable", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-foreground-missing-"));
+		const state = makeState();
+		state.foregroundRuns = new Map();
+		const sent: string[] = [];
+		const manager = createWaitSubscriptionManager({
+			events: new TestBus(),
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		} as never, state, { subscriptionsDir: path.join(root, "subscriptions"), pollIntervalMs: 60_000 });
+		try {
+			manager.arm({ targetKind: "foreground", runId: "run-missing", requestedId: "run-missing", timeoutMs: 30_000 });
+			manager.reconcile();
+			assert.match(sent[0] ?? "", /could not be reconciled/);
+		} finally {
+			manager.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("keeps a subscription armed when cleanup fails before delivery", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-cleanup-failure-"));
+		const asyncRoot = path.join(root, "runs");
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const sent: string[] = [];
+		const state = makeState();
+		const manager = createWaitSubscriptionManager({
+			events: new TestBus(),
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		} as never, state, { asyncDirRoot: asyncRoot, subscriptionsDir, pollIntervalMs: 60_000 });
+		try {
+			const registration = manager.arm({ targetKind: "async", runId: "run-missing", requestedId: "run-missing", timeoutMs: 30_000 });
+			const file = path.join(subscriptionsDir, `${registration.token}.json`);
+			fs.unlinkSync(file);
+			fs.mkdirSync(file);
+
+			manager.reconcile();
+			assert.equal(sent.length, 0);
+			assert.equal(state.waitSubscriptions?.has(registration.token), true);
+
+			fs.rmdirSync(file);
+			manager.reconcile();
+			assert.match(sent[0] ?? "", /could not be reconciled/);
+			assert.equal(sent.length, 1);
+			assert.equal(state.waitSubscriptions?.has(registration.token), false);
+		} finally {
+			manager.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("wakes when async reconciliation throws", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-reconcile-error-"));
+		const asyncRoot = path.join(root, "not-a-directory");
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const bus = new TestBus();
+		const sent: string[] = [];
+		const state = makeState();
+		fs.writeFileSync(asyncRoot, "not a directory", "utf-8");
+		const manager = createWaitSubscriptionManager({
+			events: bus,
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		} as never, state, { asyncDirRoot: asyncRoot, subscriptionsDir, pollIntervalMs: 60_000 });
+		try {
+			const registration = manager.arm({ targetKind: "async", runId: "run-error", requestedId: "run-error", timeoutMs: 30_000 });
+			manager.reconcile();
+			assert.match(sent[0] ?? "", /reconciliation failed/);
+			assert.equal(state.waitSubscriptions?.has(registration.token), false);
+			assert.equal(fs.existsSync(path.join(subscriptionsDir, `${registration.token}.json`)), false);
+		} finally {
+			manager.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("wakes for attention and timeout without treating subscriptions as child work", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-subscribe-outcomes-"));
+		const asyncRoot = path.join(root, "runs");
+		const resultsDir = path.join(root, "results");
+		const subscriptionsDir = path.join(root, "subscriptions");
+		const bus = new TestBus();
+		const sent: string[] = [];
+		let now = 1_000;
+		const state = makeState();
+		const manager = createWaitSubscriptionManager({
+			events: bus,
+			sendMessage(message: { content?: unknown }) { sent.push(String(message.content)); },
+		} as never, state, { asyncDirRoot: asyncRoot, resultsDir, subscriptionsDir, pollIntervalMs: 60_000, now: () => now, kill: () => true });
+		try {
+			writeStatus(asyncRoot, "run-attention", "running", { sessionId: "session-a", pid: 999_999 });
+			manager.arm({ targetKind: "async", runId: "run-attention", requestedId: "run-attention", timeoutMs: 5_000 });
+			writeStatus(asyncRoot, "run-attention", "running", {
+				sessionId: "session-a",
+				pid: 999_999,
+				activityState: "needs_attention",
+				steps: [{ agent: "builder", status: "running", activityState: "needs_attention" }],
+			});
+			manager.reconcile();
+			assert.match(sent.shift() ?? "", /needs attention/);
+
+			writeStatus(asyncRoot, "run-timeout", "running", { sessionId: "session-a", pid: 999_998 });
+			manager.arm({ targetKind: "async", runId: "run-timeout", requestedId: "run-timeout", timeoutMs: 100 });
+			now = 1_101;
+			manager.reconcile();
+			assert.match(sent.shift() ?? "", /timed out/);
+			assert.equal(state.asyncJobs.size, 0);
+			assert.equal(state.waitSubscriptions?.size, 0);
+		} finally {
+			manager.dispose();
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+});