@selesai/code 0.8.3 → 0.8.4

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

@@ -3,10 +3,12 @@ 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 { updateActiveRunIndex } from "../../src/runs/background/active-run-index.ts";
 import { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, waitForSubagents, type SubagentWaitDeps } from "../../src/runs/background/subagent-wait.ts";
-import type { SubagentState } from "../../src/shared/types.ts";
+import { recordWaitCompletion } from "../../src/runs/background/wait-completions.ts";
+import type { AsyncStatus, SubagentState } from "../../src/shared/types.ts";
 
-function writeStatus(asyncRoot: string, runId: string, state: string, extra: object = {}): void {
+function writeStatus(asyncRoot: string, runId: string, state: AsyncStatus["state"], extra: object = {}): void {
 	const dir = path.join(asyncRoot, runId);
 	fs.mkdirSync(dir, { recursive: true });
 	// Use a recent timestamp so the stale-run reconciler doesn't mark a live
@@ -20,11 +22,12 @@ function writeStatus(asyncRoot: string, runId: string, state: string, extra: obj
 			state,
 			startedAt: nowMs,
 			lastUpdate: nowMs,
-			steps: [{ agent: "builder", status: state }],
+			steps: [{ agent: "worker", status: state }],
 			...extra,
 		}),
 		"utf-8",
 	);
+	updateActiveRunIndex(dir, state);
 }
 
 function makeState(sessionId: string | null): SubagentState {
@@ -147,7 +150,7 @@ describe("subagent_wait tool", () => {
 				sessionId: "sess-1",
 				pid: 999999,
 				steps: [{
-					agent: "builder",
+					agent: "worker",
 					status: "running",
 					currentTool: "edit",
 					currentPath: "src/render.ts",
@@ -164,7 +167,7 @@ describe("subagent_wait tool", () => {
 			assert.equal(result.isError, undefined);
 			assert.equal(updates.length, 1);
 			assert.match(updates[0]!, /Waiting .* for 1 async run/);
-			assert.match(updates[0]!.split("\n")[0]!, /builder: edit .*src\/render\.ts/);
+			assert.match(updates[0]!.split("\n")[0]!, /worker: edit .*src\/render\.ts/);
 			assert.match(updates[0]!, /run-live/);
 		} finally {
 			fs.rmSync(root, { recursive: true, force: true });
@@ -188,6 +191,138 @@ describe("subagent_wait tool", () => {
 		}
 	});
 
+	it("tells blocking callers to revive resumable failed runs before replacing them", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-revive-first-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			const sessionFile = path.join(root, "worker-session.jsonl");
+			fs.writeFileSync(sessionFile, "{}\n", "utf-8");
+			const state = makeState("sess-1");
+			writeStatus(asyncRoot, "run-revive", "running", { sessionId: "sess-1", pid: 999999 });
+			const result = await waitForSubagents({ all: true }, undefined, baseDeps(root, state, {
+				sleep: async () => writeStatus(asyncRoot, "run-revive", "failed", {
+					sessionId: "sess-1",
+					steps: [{ agent: "worker", status: "failed", sessionFile }],
+				}),
+			}));
+
+			assert.equal(result.isError, undefined);
+			const text = textOf(result);
+			assert.match(text, /1 failed/);
+			assert.match(text, /Resume-first/);
+			assert.match(text, /subagent\(\{ action: "resume", id: "run-revive", message:/);
+			assert.match(text, /before reporting failure or launching a replacement/);
+			assert.match(text, /only if revive fails or the user explicitly asks/);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("surfaces terminal completion payloads from the result file in details.completions", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-completions-file-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			const resultsDir = path.join(root, "results");
+			fs.mkdirSync(resultsDir, { recursive: true });
+			const state = makeState("sess-1");
+			writeStatus(asyncRoot, "run-a", "running", { sessionId: "sess-1", pid: 999999 });
+			const result = await waitForSubagents({ all: true }, undefined, baseDeps(root, state, {
+				sleep: async () => {
+					writeStatus(asyncRoot, "run-a", "complete", { sessionId: "sess-1" });
+					fs.writeFileSync(path.join(resultsDir, "run-a.json"), JSON.stringify({
+						id: "run-a",
+						runId: "run-a",
+						sessionId: "sess-1",
+						agent: "workflow",
+						mode: "workflow",
+						state: "complete",
+						success: true,
+						results: [{
+							agent: "reviewer",
+							runId: "a1b2c3d4",
+							success: true,
+							outputState: "present",
+							output: "full output text stays out of details",
+							artifactPaths: {
+								outputPath: "/tmp/a1b2c3d4_reviewer_0_output.md",
+								metadataPath: "/tmp/a1b2c3d4_reviewer_0_meta.json",
+							},
+						}],
+					}), "utf-8");
+				},
+			}));
+
+			assert.equal(result.isError, undefined);
+			const completions = result.details.completions;
+			assert.equal(completions?.length, 1);
+			assert.equal(completions![0]!.runId, "run-a");
+			assert.equal(completions![0]!.mode, "workflow");
+			assert.equal(completions![0]!.success, true);
+			const child = completions![0]!.results?.[0];
+			assert.equal(child?.agent, "reviewer");
+			assert.equal(child?.runId, "a1b2c3d4");
+			assert.equal(child?.artifactPaths?.metadataPath, "/tmp/a1b2c3d4_reviewer_0_meta.json");
+			assert.equal("output" in (child ?? {}), false);
+			// The result file is the watcher's to consume; the wait must not delete it.
+			assert.equal(fs.existsSync(path.join(resultsDir, "run-a.json")), true);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("reports malformed terminal result files as actionable errors", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-completions-malformed-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			const resultsDir = path.join(root, "results");
+			fs.mkdirSync(resultsDir, { recursive: true });
+			const state = makeState("sess-1");
+			writeStatus(asyncRoot, "run-bad", "running", { sessionId: "sess-1", pid: 999999 });
+			const result = await waitForSubagents({ all: true }, undefined, baseDeps(root, state, {
+				sleep: async () => {
+					writeStatus(asyncRoot, "run-bad", "complete", { sessionId: "sess-1" });
+					fs.writeFileSync(path.join(resultsDir, "run-bad.json"), "{not json", "utf-8");
+				},
+			}));
+
+			assert.equal(result.isError, true);
+			assert.match(textOf(result), /Failed to read subagent result/);
+			assert.match(textOf(result), /run-bad\.json/);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("surfaces completions from the watcher record when the result file is already consumed", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-completions-record-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			const state = makeState("sess-1");
+			writeStatus(asyncRoot, "run-b", "running", { sessionId: "sess-1", pid: 999999 });
+			const result = await waitForSubagents({ all: true }, undefined, baseDeps(root, state, {
+				sleep: async () => {
+					writeStatus(asyncRoot, "run-b", "complete", { sessionId: "sess-1" });
+					// Simulates the watcher: payload recorded, file consumed and deleted.
+					recordWaitCompletion(state, "run-b", {
+						agent: "worker",
+						mode: "single",
+						state: "complete",
+						success: true,
+						results: [{ agent: "worker", success: true, outputState: "present" }],
+					}, Date.now(), 60_000);
+				},
+			}));
+
+			assert.equal(result.isError, undefined);
+			const completions = result.details.completions;
+			assert.equal(completions?.length, 1);
+			assert.equal(completions![0]!.runId, "run-b");
+			assert.equal(completions![0]!.results?.[0]?.agent, "worker");
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
 	it("wakes when a run needs attention, not only on completion", async () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-attn-"));
 		try {
@@ -249,7 +384,7 @@ describe("subagent_wait tool", () => {
 			writeStatus(asyncRoot, "run-step-blocked", "running", {
 				sessionId: "sess-1",
 				pid: 999999,
-				steps: [{ agent: "builder", status: "running", activityState: "needs_attention" }],
+				steps: [{ agent: "worker", status: "running", activityState: "needs_attention" }],
 			});
 
 			let polls = 0;
@@ -343,7 +478,7 @@ describe("subagent_wait tool", () => {
 					cwd: root,
 					sessionId: "sess-1",
 					updatedAt: 1,
-					children: [{ agent: "commentator", index: 0, status: "detached", updatedAt: 1 }],
+					children: [{ agent: "reviewer", index: 0, status: "detached", updatedAt: 1 }],
 				}],
 				["foreground-other", {
 					runId: "foreground-other",
@@ -351,7 +486,7 @@ describe("subagent_wait tool", () => {
 					cwd: root,
 					sessionId: "sess-2",
 					updatedAt: 1,
-					children: [{ agent: "builder", index: 0, status: "detached", updatedAt: 1 }],
+					children: [{ agent: "worker", index: 0, status: "detached", updatedAt: 1 }],
 				}],
 			]);
 			let polls = 0;
@@ -359,7 +494,7 @@ describe("subagent_wait tool", () => {
 				sleep: async () => {
 					polls += 1;
 					state.foregroundRuns!.get("foreground-alpha")!.children[0] = {
-						agent: "commentator",
+						agent: "reviewer",
 						index: 0,
 						status: "completed",
 						finalOutput: "Recovered review",
@@ -427,7 +562,7 @@ describe("subagent_wait tool", () => {
 				cwd: root,
 				sessionId: "sess-1",
 				updatedAt: 1,
-				children: [{ agent: "builder", index: 0, status: "detached", updatedAt: 1 }],
+				children: [{ agent: "worker", index: 0, status: "detached", updatedAt: 1 }],
 			}]]);
 			const handlers = new Map<string, Array<(data: unknown) => void>>();
 			const events = {
@@ -480,14 +615,14 @@ describe("subagent_wait tool", () => {
 				cwd: root,
 				sessionId: "sess-1",
 				updatedAt: ts,
-				children: [{ agent: "builder", index: 0, status: "detached", transcriptPath, updatedAt: ts }],
+				children: [{ agent: "worker", index: 0, status: "detached", transcriptPath, updatedAt: ts }],
 			}]]);
 			const updates: string[] = [];
 			const result = await waitForSubagents({ id: "foreground-live" }, undefined, baseDeps(root, state, {
 				onUpdate: (update) => updates.push(textOf(update)),
 				sleep: async () => {
 					state.foregroundRuns!.get("foreground-live")!.children[0] = {
-						agent: "builder",
+						agent: "worker",
 						index: 0,
 						status: "completed",
 						finalOutput: "Implemented the renderer fix.",
@@ -500,7 +635,7 @@ describe("subagent_wait tool", () => {
 			assert.equal(result.isError, undefined);
 			assert.equal(updates.length, 1);
 			assert.match(updates[0]!, /Waiting for detached foreground run "foreground-live"/);
-			assert.match(updates[0]!, /builder · working after supervisor handoff/);
+			assert.match(updates[0]!, /worker · working after supervisor handoff/);
 			assert.match(updates[0]!, /current: edit: \{ path: src\/render\.ts \}/);
 			assert.match(updates[0]!, /assistant: I found the relevant renderer path\./);
 			assert.doesNotMatch(updates[0]!, /large delegated task/);
@@ -520,7 +655,7 @@ describe("subagent_wait tool", () => {
 					cwd: root,
 					sessionId: "sess-1",
 					updatedAt: 1,
-					children: [{ agent: "commentator", index: 0, status: "detached", updatedAt: 1 }],
+					children: [{ agent: "reviewer", index: 0, status: "detached", updatedAt: 1 }],
 				}]]);
 				const result = await waitForSubagents({ id: "foreground-still", timeoutMs: 5000 }, undefined, baseDeps(root, state, {
 					sleep: async () => {
@@ -549,7 +684,7 @@ describe("subagent_wait tool", () => {
 				cwd: root,
 				sessionId: "sess-1",
 				updatedAt: 1,
-				children: [{ agent: "commentator", index: 0, status: "detached", updatedAt: 1 }],
+				children: [{ agent: "reviewer", index: 0, status: "detached", updatedAt: 1 }],
 			}]]);
 
 			const result = await waitForSubagents({ id: "shared" }, undefined, baseDeps(root, state));

package/dist/extensions/pi-subagents/test/unit/task-intent.test.ts

@@ -4,18 +4,18 @@ import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutat
 
 describe("classifyTaskMutationIntent", () => {
 	it("keeps write imperatives despite investigative wording", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Inspect the failure and implement the fix").kind, "implementation");
-		assert.equal(classifyTaskMutationIntent("builder", "Research the current code path and patch the bug").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Inspect the failure and implement the fix").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Research the current code path and patch the bug").kind, "implementation");
 	});
 
 	it("does not broaden the shared completion-guard classifier for role-only path patches", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Patch src/auth.ts").kind, "unknown");
+		assert.equal(classifyTaskMutationIntent("worker", "Patch src/auth.ts").kind, "unknown");
 	});
 
 	it("treats scoped no-edit constraints as constraints, not task intent", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Do not modify tests; implement the fix").kind, "implementation");
-		assert.equal(classifyTaskMutationIntent("builder", "Fix the bug. Do not edit files outside src/.").kind, "implementation");
-		assert.equal(classifyTaskMutationIntent("builder", "Must not touch the production database; implement the fix locally").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Do not modify tests; implement the fix").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Fix the bug. Do not edit files outside src/.").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Must not touch the production database; implement the fix locally").kind, "implementation");
 	});
 
 	it("stops the prohibition object before a following implementation clause", () => {
@@ -28,42 +28,42 @@ describe("classifyTaskMutationIntent", () => {
 			"Do not modify tests – implement the fix",
 			"Do not modify tests — implement the fix",
 		]) {
-			assert.equal(classifyTaskMutationIntent("builder", task).kind, "implementation", task);
+			assert.equal(classifyTaskMutationIntent("worker", task).kind, "implementation", task);
 		}
-		assert.equal(classifyTaskMutationIntent("builder", "Do not modify tests and fixtures").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Do not modify tests and fixtures").kind, "read-only");
 	});
 
 	it("lets blanket no-edit prohibitions win over write verbs", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Implement this. Do not edit files.").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("builder", "Do not edit files. Tell me how to fix the bug.").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("builder", "Report on the extraction pipeline. Do not modify project/source files.").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("commentator", "Final correctness review after prior fixes. Inspect all changed files and tests. Do not modify project/source files. Report findings.").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("builder", "Verification-only task. Do not edit product/source/config files.\n   Run a disposable check, delete its temporary harness, and retain only\n   a sanitized report at an explicitly named artifact path.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Implement this. Do not edit files.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Do not edit files. Tell me how to fix the bug.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Report on the extraction pipeline. Do not modify project/source files.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("reviewer", "Final correctness review after prior fixes. Inspect all changed files and tests. Do not modify project/source files. Report findings.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Verification-only task. Do not edit product/source/config files.\n   Run a disposable check, delete its temporary harness, and retain only\n   a sanitized report at an explicitly named artifact path.").kind, "read-only");
 	});
 
 	it("strips repeated prohibition phrases before testing write intent", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Do not modify vendor/. Do not modify generated/. Summarize the build.").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("builder", "Do not modify vendor/. Do not modify generated/. Implement the fix in src/.").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("worker", "Do not modify vendor/. Do not modify generated/. Summarize the build.").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Do not modify vendor/. Do not modify generated/. Implement the fix in src/.").kind, "implementation");
 	});
 
-	it("classifies research agents and commentator-style tasks as read-only", () => {
+	it("classifies research agents and reviewer-style tasks as read-only", () => {
 		assert.equal(classifyTaskMutationIntent("researcher", "Research this and patch the bug").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("commentator", "Review this and fix any real issues").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("commentator", "Review findings and determine what to implement with playbooks instead of before").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("commentator", "Review findings and determine what to implement with playbooks instead of before").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("commentator", "Review this; regardless of findings, apply changes directly").kind, "implementation");
-		assert.equal(classifyTaskMutationIntent("commentator", "Implement the approved file changes").kind, "implementation");
-		assert.equal(classifyTaskMutationIntent("commentator", "Implement the approved file changes").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("reviewer", "Review this and fix any real issues").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("oracle", "Review findings and determine what to implement with playbooks instead of before").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("advisor", "Review findings and determine what to implement with playbooks instead of before").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("reviewer", "Review this; regardless of findings, apply changes directly").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("oracle", "Implement the approved file changes").kind, "implementation");
+		assert.equal(classifyTaskMutationIntent("advisor", "Implement the approved file changes").kind, "implementation");
 	});
 
 	it("keeps report-writing deliverables read-only", () => {
-		assert.equal(classifyTaskMutationIntent("builder", "Write a report on the API").kind, "read-only");
-		assert.equal(classifyTaskMutationIntent("builder", "Create a summary").kind, "unknown");
+		assert.equal(classifyTaskMutationIntent("worker", "Write a report on the API").kind, "read-only");
+		assert.equal(classifyTaskMutationIntent("worker", "Create a summary").kind, "unknown");
 	});
 
 	it("expectsImplementationMutation mirrors the classifier", () => {
-		assert.equal(expectsImplementationMutation("builder", "Do not modify tests; implement the fix"), true);
-		assert.equal(expectsImplementationMutation("builder", "Review the diff and suggest fixes only. Do not edit files."), false);
+		assert.equal(expectsImplementationMutation("worker", "Do not modify tests; implement the fix"), true);
+		assert.equal(expectsImplementationMutation("worker", "Review the diff and suggest fixes only. Do not edit files."), false);
 	});
 });
 

package/dist/extensions/pi-subagents/test/unit/timeout-defaults.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	DEFAULT_ASYNC_TIMEOUT_MS,
+	DEFAULT_FOREGROUND_TIMEOUT_MS,
+	resolveSingleAgentLaunchTimeout,
+} from "../../src/runs/foreground/subagent-executor.ts";
+
+describe("single-agent launch timeout wiring", () => {
+	it("async runs default to DEFAULT_ASYNC_TIMEOUT_MS when no explicit/agent timeout", () => {
+		assert.deepEqual(resolveSingleAgentLaunchTimeout({}, true), {
+			timeoutMs: DEFAULT_ASYNC_TIMEOUT_MS,
+		});
+	});
+
+	it("foreground runs default to DEFAULT_FOREGROUND_TIMEOUT_MS when no explicit/agent timeout", () => {
+		assert.deepEqual(resolveSingleAgentLaunchTimeout({}, false), {
+			timeoutMs: DEFAULT_FOREGROUND_TIMEOUT_MS,
+		});
+	});
+
+	it("explicit timeoutMs wins over the async default", () => {
+		assert.deepEqual(resolveSingleAgentLaunchTimeout({ timeoutMs: 5_000 }, true), {
+			timeoutMs: 5_000,
+		});
+	});
+
+	it("maxRuntimeMs alias wins over the async default", () => {
+		assert.deepEqual(resolveSingleAgentLaunchTimeout({ maxRuntimeMs: 7_000 }, true), {
+			timeoutMs: 7_000,
+		});
+	});
+
+	it("rejects non-positive timeouts", () => {
+		const result = resolveSingleAgentLaunchTimeout({ timeoutMs: 0 }, true);
+		assert.ok(result.error);
+		assert.match(result.error!, /positive integer/);
+	});
+
+	it("rejects mismatched alias values", () => {
+		const result = resolveSingleAgentLaunchTimeout({ timeoutMs: 1_000, maxRuntimeMs: 2_000 }, true);
+		assert.ok(result.error);
+		assert.match(result.error!, /aliases/);
+	});
+
+	it("does not apply the async default to async chains (children are bounded individually)", () => {
+		assert.deepEqual(
+			resolveSingleAgentLaunchTimeout({ agent: "worker", task: "x", chain: [{ agent: "worker", task: "y" }] }, true),
+			{},
+		);
+	});
+
+	it("does not apply the async default to async parallel tasks", () => {
+		assert.deepEqual(
+			resolveSingleAgentLaunchTimeout({ agent: "worker", task: "x", tasks: [{ agent: "worker", task: "y" }] }, true),
+			{},
+		);
+	});
+
+	it("does not apply the async default to async workflowScript", () => {
+		assert.deepEqual(
+			resolveSingleAgentLaunchTimeout({ workflowScript: "return runs.run('a', { agent: 'worker', task: 'x' })" }, true),
+			{},
+		);
+	});
+
+	it("explicit top-level timeout still applies to async chains", () => {
+		assert.deepEqual(
+			resolveSingleAgentLaunchTimeout({ agent: "worker", task: "x", chain: [{ agent: "worker", task: "y" }], timeoutMs: 5_000 }, true),
+			{ timeoutMs: 5_000 },
+		);
+	});
+});

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

@@ -28,29 +28,42 @@ function parentToolEnv(agentDir?: string): NodeJS.ProcessEnv {
 }
 
 describe("registered subagent tool description", () => {
-	it("describes workflowScript as the sole public orchestration surface", () => {
+	it("describes the four first-class execution modes", () => {
 		const description = buildSubagentToolDescription();
-		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, /^Delegate one child with \{ agent, task \}/i);
+		assert.match(description, /SINGLE: \{ agent, task\? \}/i);
+		assert.match(description, /CHAIN: \{ chain: \[\{ agent: "explorer"/i);
+		assert.match(description, /PARALLEL: \{ tasks:/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, /repository mutation lanes.*worktree:true.*runs\.run\/runs\.all.*managed isolation/i);
+		assert.match(description, /ordinary JavaScript statement body.*explicit return/i);
+		assert.match(description, /Sequential example/i);
+		assert.match(description, /Parallel example/i);
+		assert.match(description, /append-step/i);
+		assert.match(description, /approve-checkpoint and reject-checkpoint/i);
 		assert.match(description, /cannot access filesystem, shell, arbitrary Pi tools, or host globals/i);
+		assert.match(description, /exactly one non-empty title or summary/i);
+		assert.match(description, /goal may only be true and requires budget:\{tokens\}/i);
 		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
 		assert.match(description, /status\.json/);
 	});
 
+	it("includes legacy chain-control guidance when enabled", () => {
+		const description = buildSubagentToolDescription({ legacyChainControls: true });
+		assert.match(description, /append-step.*step:/i);
+		assert.match(description, /approve-checkpoint|reject-checkpoint/);
+	});
+
 	it("offers a compact mode that keeps the cutover and safety guidance", () => {
-		const description = buildSubagentToolDescription({ toolDescriptionMode: "compact" });
+		const description = buildSubagentToolDescription({ toolDescriptionMode: "compact", legacyChainControls: true });
 		assert.equal(description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
-		assert.match(description, /workflowScript is the sole public orchestration surface/i);
+		assert.match(description, /^Delegate one child with \{ agent, task \}/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, /repository mutation lanes.*worktree:true.*runs\.run\/runs\.all.*managed isolation/i);
+		assert.match(description, /SINGLE \{agent, task\?\}|CHAIN \{chain:/i);
 		assert.match(description, /subagent_wait/i);
+		assert.match(description, /exactly one non-empty title or summary/i);
+		assert.match(description, /goal may only be true and requires budget:\{tokens\}/i);
 		assert.ok(description.length < FULL_SUBAGENT_TOOL_DESCRIPTION.length);
 	});
 
@@ -114,13 +127,33 @@ describe("registered subagent tool description", () => {
 		assert.match(description, /ordinary child subagents are not orchestrators/i);
 	});
 
+	it("preserves custom guidance while trimming built-in legacy chain guidance", () => {
+		const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-legacy-note-"));
+		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-agent-"));
+		fs.mkdirSync(path.join(cwd, ".selesai"), { recursive: true });
+		fs.writeFileSync(
+			path.join(cwd, ".selesai", "subagent-tool-description.md"),
+			[
+				"Custom migration note: append-step, approve-checkpoint, and reject-checkpoint appear here as audit context.",
+				"{{fullDescription}}",
+			].join("\n\n"),
+			"utf-8",
+		);
+
+		const description = buildSubagentToolDescription({ toolDescriptionMode: "custom" }, { cwd, agentDir });
+
+		assert.match(description, /Custom migration note: append-step, approve-checkpoint, and reject-checkpoint/);
+		assert.doesNotMatch(description, /appends one step to an already-running durable legacy chain/);
+		assert.doesNotMatch(description, /decide a paused durable legacy chain checkpoint/);
+	});
+
 	it("falls back to full mode when custom mode has no valid file", () => {
 		const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-missing-"));
 		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-agent-"));
 		const warnings: string[] = [];
 
 		const description = buildSubagentToolDescription(
-			{ toolDescriptionMode: "custom" },
+			{ toolDescriptionMode: "custom", legacyChainControls: true },
 			{ cwd, agentDir, warn: (message) => warnings.push(message) },
 		);
 
@@ -132,7 +165,7 @@ describe("registered subagent tool description", () => {
 		const warnings: string[] = [];
 
 		const description = buildSubagentToolDescription(
-			{ toolDescriptionMode: "tiny" } as never,
+			{ toolDescriptionMode: "tiny", legacyChainControls: true } as never,
 			{ warn: (message) => warnings.push(message) },
 		);
 
@@ -140,7 +173,7 @@ describe("registered subagent tool description", () => {
 		assert.ok(warnings.some((message) => message.includes("Ignoring invalid toolDescriptionMode")));
 	});
 
-	function readRegisteredDescription(agentDir: string): string {
+	function readRegisteredTool(agentDir: string): { description: string; properties: string[] } {
 		const script = String.raw`
 			import registerSubagentExtension from "./src/extension/index.ts";
 			const events = { on() { return () => {}; }, emit() {} };
@@ -161,7 +194,7 @@ describe("registered subagent tool description", () => {
 			});
 			registerSubagentExtension(fakePi);
 			if (!registeredTool) throw new Error("tool not registered");
-			process.stdout.write(JSON.stringify(registeredTool.description));
+			process.stdout.write(JSON.stringify({ description: registeredTool.description, properties: Object.keys(registeredTool.parameters.properties) }));
 		`;
 		const output = execFileSync(
 			process.execPath,
@@ -175,7 +208,7 @@ describe("registered subagent tool description", () => {
 			],
 			{ cwd: projectRoot, env: parentToolEnv(agentDir), encoding: "utf-8" },
 		);
-		return JSON.parse(output) as string;
+		return JSON.parse(output) as { description: string; properties: string[] };
 	}
 
 	function writeExtensionConfig(agentDir: string, config: Record<string, unknown>): void {
@@ -186,25 +219,43 @@ 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(readRegisteredDescription(defaultAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		writeExtensionConfig(defaultAgentDir, { legacyChainControls: true });
+		assert.equal(readRegisteredTool(defaultAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const compactAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-compact-"));
-		writeExtensionConfig(compactAgentDir, { toolDescriptionMode: "compact" });
-		assert.equal(readRegisteredDescription(compactAgentDir), COMPACT_SUBAGENT_TOOL_DESCRIPTION);
+		writeExtensionConfig(compactAgentDir, { toolDescriptionMode: "compact", legacyChainControls: true });
+		assert.equal(readRegisteredTool(compactAgentDir).description, 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 = readRegisteredDescription(customAgentDir);
+		const customDescription = readRegisteredTool(customAgentDir).description;
 		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(readRegisteredDescription(missingCustomAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		writeExtensionConfig(missingCustomAgentDir, { toolDescriptionMode: "custom", legacyChainControls: true });
+		assert.equal(readRegisteredTool(missingCustomAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 
 		const invalidAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-invalid-"));
-		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny" });
-		assert.equal(readRegisteredDescription(invalidAgentDir), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny", legacyChainControls: true });
+		assert.equal(readRegisteredTool(invalidAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+	});
+
+	it("registers the full schema and first-class chain description by default", () => {
+		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-trimmed-"));
+		const tool = readRegisteredTool(agentDir);
+		assert.equal(tool.properties.includes("step"), true);
+		assert.equal(tool.properties.includes("chain"), true);
+		assert.equal(tool.properties.includes("tasks"), true);
+		assert.match(tool.description, /CHAIN: \{ chain:/i);
+	});
+
+	it("registers the trimmed schema and description when legacyChainControls is false", () => {
+		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-legacy-"));
+		writeExtensionConfig(agentDir, { legacyChainControls: false });
+		const tool = readRegisteredTool(agentDir);
+		assert.equal(tool.properties.includes("step"), false);
+		assert.doesNotMatch(tool.description, /append-step/i);
 	});
 });

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 commentator.", undefined), "You are a commentator.");
+			assert.equal(appendTurnBudgetSystemPrompt("You are a reviewer.", undefined), "You are a reviewer.");
 			assert.equal(appendTurnBudgetSystemPrompt("", undefined), "");
 		});
 
 		it("appends a turn-budget block after an existing system prompt", () => {
-			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);
+			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);
 			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 commentator.\n\n", budget());
-			assert.ok(result.startsWith("You are a commentator.\n\n## Turn budget\n"), result);
+			const result = appendTurnBudgetSystemPrompt("\nYou are a reviewer.\n\n", budget());
+			assert.ok(result.startsWith("You are a reviewer.\n\n## Turn budget\n"), result);
 			assert.equal(result.startsWith("\n"), false);
 		});