@selesai/code 0.13.3 → 0.13.5

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

@@ -145,6 +145,47 @@ function writeMcpFixture(
 	});
 }
 
+type RuntimeMcpDefinition = { command: string; args: string[] };
+
+function buildLegacyAliasLaunch(params: {
+	definitions: Record<string, RuntimeMcpDefinition>;
+	mcpDirectTools: string[];
+	allowedTools: string[];
+}) {
+	const fixture = createMcpFixture();
+	writeJson(path.join(fixture.agentDir, "mcp.json"), { mcpServers: {} });
+	writeJson(path.join(fixture.agentDir, "mcp-cache.json"), {
+		version: 1,
+		servers: Object.fromEntries(Object.entries(params.definitions).map(([name, definition]) => [
+			name,
+			{ configHash: computeMcpServerHash(definition), cachedAt: Date.now(), tools: [{ name: "search" }] },
+		])),
+	});
+	const runtimeSnapshotHost: McpRuntimeSnapshotHost = {
+		events: {
+			emit(_event, request) {
+				const definition = params.definitions[request.name];
+				if (!definition) {
+					request.result = { ok: false, error: new Error(`unknown runtime server ${request.name}`) };
+					return;
+				}
+				request.result = { ok: true, snapshot: { name: request.name, definition, runtime: true, persisted: false } };
+			},
+		},
+	};
+	return buildPiArgs({
+		baseArgs: ["-p"],
+		task: "hello",
+		sessionEnabled: false,
+		inheritProjectContext: false,
+		inheritSkills: false,
+		tools: ["read"],
+		mcpDirectTools: params.mcpDirectTools,
+		capabilityCeiling: { version: 1, allowedTools: params.allowedTools, denyExtensions: false, sources: ["test"] },
+		runtimeSnapshotHost,
+	});
+}
+
 afterEach(() => {
 	process.chdir(originalCwd);
 	for (const [key, value] of Object.entries(originalEnv)) {
@@ -1125,7 +1166,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 
 		assert.equal(
 			args[args.indexOf("--tools") + 1],
-			"read,bash,chrome_devtools_take_screenshot,chrome_devtools_click",
+			"read,bash,chrome-devtools_take_screenshot,chrome-devtools_click",
 		);
 		assert.equal(env.MCP_DIRECT_TOOLS, "chrome-devtools");
 		assert.equal(
@@ -1133,15 +1174,15 @@ describe("buildPiArgs system prompt mode wiring", () => {
 			JSON.stringify([
 				"read",
 				"bash",
-				"chrome_devtools_take_screenshot",
-				"chrome_devtools_click",
+				"chrome-devtools_take_screenshot",
+				"chrome-devtools_click",
 			]),
 		);
 		assert.equal(
 			env[MCP_DIRECT_CHILD_TOOLS_ENV],
 			JSON.stringify([
-				"chrome_devtools_take_screenshot",
-				"chrome_devtools_click",
+				"chrome-devtools_take_screenshot",
+				"chrome-devtools_click",
 			]),
 		);
 	});
@@ -1224,8 +1265,8 @@ describe("buildPiArgs system prompt mode wiring", () => {
 			runtimeSnapshotHost,
 		});
 		assert.deepEqual(requestedNames, [serverName, serverName]);
-		assert.equal(serverLaunch.args[serverLaunch.args.indexOf("--tools") + 1], "read,runtime_github_search_repositories,runtime_github_create_issue");
-		assert.equal(toolLaunch.args[toolLaunch.args.indexOf("--tools") + 1], "read,runtime_github_search_repositories");
+		assert.equal(serverLaunch.args[serverLaunch.args.indexOf("--tools") + 1], "read,runtime-github_search_repositories,runtime-github_create_issue");
+		assert.equal(toolLaunch.args[toolLaunch.args.indexOf("--tools") + 1], "read,runtime-github_search_repositories");
 		assert.ok(serverLaunch.args.indexOf("--mcp-config") < serverLaunch.args.indexOf("Task: hello"));
 		for (const launch of [serverLaunch, toolLaunch]) {
 			const configPath = launch.args[launch.args.indexOf("--mcp-config") + 1];
@@ -1240,11 +1281,11 @@ describe("buildPiArgs system prompt mode wiring", () => {
 			[serverName, `${serverName}/search_repositories`],
 		);
 		assert.deepEqual(JSON.parse(serverLaunch.env[MCP_DIRECT_CHILD_TOOLS_ENV]!), [
-			"runtime_github_search_repositories",
-			"runtime_github_create_issue",
+			"runtime-github_search_repositories",
+			"runtime-github_create_issue",
 		]);
 		assert.deepEqual(JSON.parse(toolLaunch.env[MCP_DIRECT_CHILD_TOOLS_ENV]!), [
-			"runtime_github_search_repositories",
+			"runtime-github_search_repositories",
 		]);
 	});
 
@@ -1354,15 +1395,50 @@ describe("buildPiArgs system prompt mode wiring", () => {
 			capabilityCeiling: { version: 1, allowedTools: ["read", "runtime_a_search"], denyExtensions: false, sources: ["test"] },
 			runtimeSnapshotHost,
 		});
-		assert.equal(launch.args[launch.args.indexOf("--tools") + 1], "read,runtime_a_search");
+		assert.equal(launch.args[launch.args.indexOf("--tools") + 1], "read,runtime-a_search");
 		const configPath = launch.args[launch.args.indexOf("--mcp-config") + 1];
 		assert.ok(configPath);
 		assert.deepEqual(JSON.parse(fs.readFileSync(configPath, "utf-8")), {
 			mcpServers: { "runtime-a": definitions["runtime-a"] },
 		});
+		assert.deepEqual(JSON.parse(launch.env[MCP_DIRECT_CHILD_TOOLS_ENV]!), ["runtime-a_search"]);
+	});
+
+	it("does not let legacy MCP ceiling aliases cross server boundaries", () => {
+		const definitions = {
+			"runtime-a": { command: "runtime-a", args: ["--stdio"] },
+			runtime_a: { command: "runtime_a", args: ["--stdio"] },
+		};
+		const launch = buildLegacyAliasLaunch({
+			definitions,
+			mcpDirectTools: ["runtime-a", "runtime_a"],
+			allowedTools: ["read", "runtime_a_search"],
+		});
+
+		assert.equal(launch.args[launch.args.indexOf("--tools") + 1], "read,runtime_a_search");
+		const configPath = launch.args[launch.args.indexOf("--mcp-config") + 1];
+		assert.ok(configPath);
+		assert.deepEqual(JSON.parse(fs.readFileSync(configPath, "utf-8")), {
+			mcpServers: { runtime_a: definitions.runtime_a },
+		});
 		assert.deepEqual(JSON.parse(launch.env[MCP_DIRECT_CHILD_TOOLS_ENV]!), ["runtime_a_search"]);
 	});
 
+	it("does not allow ambiguous legacy MCP ceiling aliases", () => {
+		const launch = buildLegacyAliasLaunch({
+			definitions: {
+			"runtime-a-b": { command: "runtime-a-b", args: ["--stdio"] },
+			"runtime_a-b": { command: "runtime_a-b", args: ["--stdio"] },
+			},
+			mcpDirectTools: ["runtime-a-b", "runtime_a-b"],
+			allowedTools: ["read", "runtime_a_b_search"],
+		});
+
+		assert.equal(launch.args[launch.args.indexOf("--tools") + 1], "read");
+		assert.equal(launch.args.includes("--mcp-config"), false);
+		assert.equal(launch.env[MCP_DIRECT_CHILD_TOOLS_ENV], undefined);
+	});
+
 	it("emits --no-tools for explicit empty tool allowlists", () => {
 		for (const requireReadTool of [false, true]) {
 			const { args, env } = buildPiArgs({
@@ -1398,7 +1474,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 
 			assert.equal(
 				args[args.indexOf("--tools") + 1],
-				"chrome_devtools_take_screenshot,chrome_devtools_click",
+				"chrome-devtools_take_screenshot,chrome-devtools_click",
 			);
 			assert.equal(env.MCP_DIRECT_TOOLS, "chrome-devtools");
 		}
@@ -1451,7 +1527,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 
 	it("matches adapter prefix modes for direct MCP names", () => {
 		for (const [prefix, expected] of [
-			["server", "read,linear_mcp_list_issues"],
+			["server", "read,linear-mcp_list_issues"],
 			["short", "read,linear_list_issues"],
 			["none", "read,list_issues"],
 		] as const) {
@@ -1497,7 +1573,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 
 		assert.equal(
 			args[args.indexOf("--tools") + 1],
-			"read,browser_mcp_navigate,browser_mcp_get_console_logs",
+			"read,browser-mcp_navigate,browser-mcp_get_console_logs",
 		);
 	});
 
@@ -1614,7 +1690,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 			cwd: fixture.projectDir,
 		});
 
-		assert.equal(args[args.indexOf("--tools") + 1], "read,project_mcp_inspect");
+		assert.equal(args[args.indexOf("--tools") + 1], "read,project-mcp_inspect");
 	});
 
 	it("resolves direct MCP tools from Pi package manifests", () => {
@@ -1680,7 +1756,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 		}), /Unresolved MCP direct-tool selectors: acme_tools__wiki\./);
 	});
 
-	it("resolves direct MCP tools from the git-root package when child cwd has an incidental .pi directory", () => {
+	it("resolves direct MCP tools from the git-root package when child cwd has an incidental .selesai directory", () => {
 		const fixture = createMcpFixture();
 		const nestedCwd = path.join(fixture.projectDir, "packages", "app");
 		const packageRoot = path.join(fixture.projectDir, ".selesai", "npm", "node_modules", "@acme", "tools");
@@ -1861,7 +1937,7 @@ describe("buildPiArgs system prompt mode wiring", () => {
 		);
 		assert.equal(
 			args[args.indexOf("--tools") + 1],
-			"read,chrome_devtools_take_screenshot",
+			"read,chrome-devtools_take_screenshot",
 		);
 		assert.ok(
 			extensionArgs.some((arg) =>

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

@@ -49,6 +49,7 @@ describe("public subagent execution normalization", () => {
 			},
 		});
 		assert.deepEqual(normalizePublicSubagentExecution({ action: " list " }), { ok: true, params: { action: "list" } });
+		assert.deepEqual(normalizePublicSubagentExecution({ action: " list ", capabilities: true }), { ok: true, params: { action: "list", capabilities: true } });
 		assert.deepEqual(
 			normalizePublicSubagentExecution({ action: " validate ", workflowScript: "return 1" }),
 			{ ok: true, params: { action: "validate", workflowScript: "return 1" } },

package/dist/extensions/pi-subagents/test/unit/render-helpers.test.ts

@@ -2,8 +2,8 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { row } from "../../src/tui/render-helpers.ts";
-import { renderSubagentResult, truncLine, widgetRenderKey } from "../../src/tui/render.ts";
+import { row, shouldSuppressSingleStep, stripRepeatedAgentPrefix, withDuplicateLabelDiscriminators } from "../../src/tui/render-helpers.ts";
+import { buildWidgetLines, renderSubagentResult, truncLine, widgetRenderKey } from "../../src/tui/render.ts";
 import type { AsyncJobState } from "../../src/shared/types.ts";
 
 const theme = {
@@ -38,6 +38,43 @@ test("row clips content to the available width", () => {
 	assert.equal(visibleWidth(rendered), 6);
 });
 
+test("stripRepeatedAgentPrefix removes only safe repeated job-name prefixes", () => {
+	assert.equal(stripRepeatedAgentPrefix("  reviewer: Review the diff  ", "reviewer"), "Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("reviewer · Review the diff", "reviewer"), "Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("reviewer Review the diff", "reviewer"), "Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("reviewer-2: Review the diff", "reviewer"), "reviewer-2: Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("reviewerhood: Review the diff", "reviewer"), "reviewerhood: Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("worker: Review the diff", "reviewer"), "worker: Review the diff");
+	assert.equal(stripRepeatedAgentPrefix("reviewer", "reviewer"), "reviewer");
+});
+
+test("shouldSuppressSingleStep uses logical totals instead of materialized step count", () => {
+	assert.equal(shouldSuppressSingleStep(undefined, 1), true);
+	assert.equal(shouldSuppressSingleStep(1, 1), true);
+	assert.equal(shouldSuppressSingleStep(2, 1), false);
+	assert.equal(shouldSuppressSingleStep(undefined, 2), false);
+	assert.equal(shouldSuppressSingleStep(undefined, undefined), false);
+});
+
+test("withDuplicateLabelDiscriminators preserves unique labels and stable duplicate fractions", () => {
+	const rows = [
+		{ index: 0, displayName: "Gather context" },
+		{ index: 1, displayName: "Review diff" },
+		{ index: 2, displayName: "Review diff" },
+	];
+
+	assert.deepEqual(
+		withDuplicateLabelDiscriminators(rows, 3).map((row) => row.rowLabel),
+		["Gather context", "Agent 2/3: Review diff", "Agent 3/3: Review diff"],
+	);
+
+	const reordered = [rows[2]!, rows[0]!, rows[1]!];
+	assert.deepEqual(
+		withDuplicateLabelDiscriminators(reordered, 3).map((row) => row.rowLabel),
+		["Agent 3/3: Review diff", "Gather context", "Agent 2/3: Review diff"],
+	);
+});
+
 test("row normalizes multiline content before clipping", () => {
 	const rendered = row("bash failed: line 1\nline 2\tvalue", 20, theme as any);
 	assert.equal(visibleWidth(rendered), 20);
@@ -123,6 +160,42 @@ test("widget render keys keep compact payloads quiet and expanded payloads fresh
 	assert.notEqual(widgetRenderKey(warningDetailChange, true), widgetRenderKey(preflightJob, true));
 });
 
+test("seeded running glyphs advance at wall-clock frame boundaries while unseeded glyphs stay static", () => {
+	const originalNow = Date.now;
+	const runningGlyph = (lines: string[]): string => lines
+		.map((line) => line.match(/[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏●]/u)?.[0])
+		.find((glyph): glyph is string => glyph !== undefined) ?? "";
+	const seededJob: AsyncJobState = {
+		asyncId: "seeded",
+		asyncDir: "/tmp/seeded",
+		status: "running",
+		mode: "single",
+		updatedAt: 1,
+	};
+	const unseededJob: AsyncJobState = {
+		asyncId: "unseeded",
+		asyncDir: "/tmp/unseeded",
+		status: "running",
+		mode: "single",
+	};
+
+	try {
+		Date.now = () => 1_000;
+		const seededBeforeBoundary = runningGlyph(buildWidgetLines([seededJob], theme, 180));
+		const unseededBeforeBoundary = runningGlyph(buildWidgetLines([unseededJob], theme, 180));
+
+		Date.now = () => 1_125;
+		const seededAfterBoundary = runningGlyph(buildWidgetLines([seededJob], theme, 180));
+		const unseededAfterBoundary = runningGlyph(buildWidgetLines([unseededJob], theme, 180));
+
+		assert.notEqual(seededAfterBoundary, seededBeforeBoundary);
+		assert.equal(unseededAfterBoundary, unseededBeforeBoundary);
+		assert.equal(unseededBeforeBoundary, "●");
+	} finally {
+		Date.now = originalNow;
+	}
+});
+
 test("multiline rendering omits two-column graphemes at one-column width", () => {
 	const originalColumns = Object.getOwnPropertyDescriptor(process.stdout, "columns");
 	Object.defineProperty(process.stdout, "columns", { configurable: true, value: 5 });
@@ -211,7 +284,7 @@ test("compact multi-result cards prefer bounded workflow labels over raw tasks",
 	assert.match(text, /Ctrl\+Alt\+F Fleet/);
 });
 
-test("compact chain rendering uses workflow graph spans for dynamic fanout results", () => {
+test("compact chain rendering uses workflow graph labels and parallel groups", () => {
 	const component = renderSubagentResult({
 		content: [{ type: "text", text: "done" }],
 		details: {
@@ -244,10 +317,11 @@ test("compact chain rendering uses workflow graph spans for dynamic fanout resul
 	}, { expanded: false }, theme as any);
 
 	const text = componentText(component);
-	assert.match(text, /Step 1: scout/);
-	assert.match(text, /Agent 1\/2: reviewer/);
-	assert.match(text, /Agent 2\/2: reviewer/);
-	assert.match(text, /Step 3: writer/);
+	assert.match(text, /Step 1\/3: Scout/);
+	assert.match(text, /Step 2\/3: parallel group \(Review targets\)/);
+	assert.match(text, /Review A/);
+	assert.match(text, /Review B/);
+	assert.match(text, /Step 3\/3: Writer/);
 });
 
 test("compact chain rendering shows failed zero-child dynamic fanout groups", () => {
@@ -283,10 +357,10 @@ test("compact chain rendering shows failed zero-child dynamic fanout groups", ()
 	const text = componentText(component);
 	assert.match(text, /step 1\/3/);
 	assert.doesNotMatch(text, /step 3\/3/);
-	assert.match(text, /Step 1: scout/);
-	assert.match(text, /Step 2: Review targets .* failed/);
+	assert.match(text, /Step 1\/3: Scout/);
+	assert.match(text, /Step 2\/3: parallel group \(Review targets\) · failed/);
 	assert.match(text, /No review targets materialized/);
-	assert.match(text, /Step 3: writer .* pending/);
+	assert.match(text, /Step 3\/3: writer .* pending/);
 });
 
 test("expanded chain rendering uses workflow graph spans for dynamic fanout results", () => {
@@ -322,10 +396,11 @@ test("expanded chain rendering uses workflow graph spans for dynamic fanout resu
 	}, { expanded: true }, theme as any);
 
 	const text = componentText(component);
-	assert.match(text, /Step 1: scout/);
-	assert.match(text, /Agent 1\/2: reviewer/);
-	assert.match(text, /Agent 2\/2: reviewer/);
-	assert.match(text, /Step 3: writer/);
+	assert.match(text, /Step 1\/3: Scout/);
+	assert.match(text, /Step 2\/3: parallel group \(Review targets\)/);
+	assert.match(text, /Review A/);
+	assert.match(text, /Review B/);
+	assert.match(text, /Step 3\/3: Writer/);
 });
 
 test("compact multi-result rendering shows total cost in the header", () => {
@@ -342,7 +417,7 @@ test("compact multi-result rendering shows total cost in the header", () => {
 	assert.match(text, /in:30 out:12 \$0\.0400/);
 });
 
-test("static sequential and static parallel chain rendering keep existing labels", () => {
+test("static sequential and static parallel chain rendering keep logical labels", () => {
 	const sequential = componentText(renderSubagentResult({
 		content: [{ type: "text", text: "done" }],
 		details: {
@@ -352,8 +427,8 @@ test("static sequential and static parallel chain rendering keep existing labels
 			results: [result("scout", "a"), result("writer", "b")],
 		},
 	}, { expanded: false }, theme as any));
-	assert.match(sequential, /Step 1: scout/);
-	assert.match(sequential, /Step 2: writer/);
+	assert.match(sequential, /Step 1\/2: scout task/);
+	assert.match(sequential, /Step 2\/2: writer task/);
 
 	const parallel = componentText(renderSubagentResult({
 		content: [{ type: "text", text: "done" }],
@@ -364,13 +439,14 @@ test("static sequential and static parallel chain rendering keep existing labels
 			results: [result("scout", "a"), result("reviewer", "b"), result("auditor", "c"), result("writer", "d")],
 		},
 	}, { expanded: false }, theme as any));
-	assert.match(parallel, /Step 1: scout/);
-	assert.match(parallel, /Agent 1\/2: reviewer/);
-	assert.match(parallel, /Agent 2\/2: auditor/);
-	assert.match(parallel, /Step 3: writer/);
+	assert.match(parallel, /Step 1\/3: scout task/);
+	assert.match(parallel, /Step 2\/3: parallel group/);
+	assert.match(parallel, /reviewer task/);
+	assert.match(parallel, /auditor task/);
+	assert.match(parallel, /Step 3\/3: writer task/);
 });
 
-test("expanded simple chain summaries prefer result session names", () => {
+test("expanded simple chain summaries strip repeated agent prefixes", () => {
 	const expanded = componentText(renderSubagentResult({
 		content: [{ type: "text", text: "done" }],
 		details: {
@@ -380,8 +456,9 @@ test("expanded simple chain summaries prefer result session names", () => {
 			results: [{ ...result("worker", "done"), sessionName: "  worker: named task  " }],
 		},
 	}, { expanded: true }, theme as any));
-	assert.match(expanded, /Step 1: worker: named task/);
-	assert.doesNotMatch(expanded, /Step 1: chain-label/);
+	assert.match(expanded, /named task/);
+	assert.doesNotMatch(expanded, /worker:\s+named task/);
+	assert.doesNotMatch(expanded, /Step 1\/1/);
 });
 
 test("main-window renderer config removes compact result indentation without changing status glyphs", () => {
@@ -395,8 +472,8 @@ test("main-window renderer config removes compact result indentation without cha
 
 	const text = componentText(component);
 	assert.match(text, /^✗ parallel/m);
-	assert.match(text, /^✓ Agent 1\/2: scout/m);
-	assert.match(text, /^✗ Agent 2\/2: reviewer/m);
+	assert.match(text, /^✓ scout task/m);
+	assert.match(text, /^✗ reviewer task/m);
 	assert.match(text, /^⎿  Error: failed/m);
 });
 

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

@@ -78,6 +78,50 @@ describe("async run status inspection", () => {
 		}
 	});
 
+	it("renders bounded recovery guidance from a failed status step", () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-run-status-recovery-"));
+		try {
+			const asyncRoot = path.join(root, "runs");
+			const asyncDir = path.join(asyncRoot, "run-recovery");
+			fs.mkdirSync(asyncDir, { recursive: true });
+			const changedFiles = Array.from({ length: 25 }, (_, index) => `src/file-${String(index + 1).padStart(2, "0")}.ts`);
+			fs.writeFileSync(path.join(asyncDir, "status.json"), JSON.stringify({
+				runId: "run-recovery",
+				mode: "single",
+				state: "failed",
+				startedAt: 100,
+				lastUpdate: 200,
+				steps: [{
+					agent: "worker",
+					status: "failed",
+					timedOut: true,
+					timeoutRecovery: {
+						termination: "timed-out",
+						changedFiles,
+						truncated: true,
+						recoveryNeeded: true,
+						reason: "timed-out-with-dirty-worktree",
+						reportStatus: "missing",
+						message: "raw recovery message must not be rendered",
+						effects: { settlementDiagnostic: { finalTextPresent: true } },
+					},
+				}],
+			}, null, 2), "utf-8");
+
+			const result = inspectSubagentStatus({ id: "run-recovery" }, { asyncDirRoot: asyncRoot, resultsDir: path.join(root, "results") });
+			const text = textContent(result);
+			assert.equal(result.isError, undefined);
+			assert.match(text, /State: failed/);
+			assert.match(text, /Recovery needed: review the diff and artifacts before resuming or launching dependent stages\./);
+			assert.match(text, /requested report: missing/);
+			assert.match(text, /changed tracked files: src\/file-01\.ts, src\/file-02\.ts/);
+			assert.match(text, /file-20\.ts, …/);
+			assert.doesNotMatch(text, /raw recovery message|settlementDiagnostic/);
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
 	it("shows a follow-up hint for completed external-job runs when the provider supports it", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-run-status-external-follow-up-"));
 		try {
@@ -1399,6 +1443,17 @@ describe("async run status inspection", () => {
 				state: "failed",
 				sessionFile,
 				summary: "result survived missing status",
+				results: [{
+					agent: "worker",
+					success: false,
+					timeoutRecovery: {
+						termination: "timed-out",
+						changedFiles: ["input.md"],
+						recoveryNeeded: true,
+						reason: "timed-out-with-dirty-worktree",
+						reportStatus: "missing",
+					},
+				}],
 			}, null, 2), "utf-8");
 
 			const result = inspectSubagentStatus({ id: "run-result-only" }, {
@@ -1412,6 +1467,9 @@ describe("async run status inspection", () => {
 			assert.match(text, /Result: /);
 			assert.match(text, /Revive: subagent\(\{ action: "resume", id: "run-result-only", message: "\.\.\." \}\)/);
 			assert.match(text, /result survived missing status/);
+			assert.match(text, /Recovery needed: review the diff and artifacts before resuming or launching dependent stages\./);
+			assert.match(text, /requested report: missing/);
+			assert.match(text, /changed tracked files: input\.md/);
 		} finally {
 			fs.rmSync(root, { recursive: true, force: true });
 		}

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

@@ -78,6 +78,10 @@ interface SubagentParamsSchema {
 			enum?: string[];
 			description?: string;
 		};
+		capabilities?: {
+			type?: string;
+			description?: string;
+		};
 		view?: {
 			type?: string;
 			enum?: string[];
@@ -255,6 +259,22 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.doesNotMatch(description, /orchestration\./);
 	});
 
+	it("accepts prompt-free capability discovery on list requests", () => {
+		const capabilitiesSchema = SubagentParams?.properties?.capabilities;
+		assert.ok(capabilitiesSchema, "capabilities schema should exist");
+		assert.equal(capabilitiesSchema.type, "boolean");
+		const description = String(capabilitiesSchema.description ?? "");
+		assert.match(description, /action=['\"]list['\"]/i);
+		assert.match(description, /compact/i);
+		assert.match(description, /system prompt/i);
+
+		if (CompileSchema) {
+			const validator = CompileSchema(SubagentParams);
+			assert.equal(validator.Check({ action: "list", capabilities: true }), true);
+			assert.equal(validator.Check({ action: "list", capabilities: "true" }), false);
+		}
+	});
+
 	it("keeps agentContract.version as integer bounds without an enum (Gemini schema subset)", () => {
 		const agentContract = (SubagentParams?.properties as Record<string, JsonSchemaNode> | undefined)?.agentContract;
 		assert.ok(agentContract, "agentContract schema should exist");
@@ -418,8 +438,8 @@ describe("SubagentParams schema", { skip: !schemasAvailable ? "typebox not avail
 		assert.ok(SubagentParams, "SubagentParams schema should exist");
 		const schema = SubagentParams as unknown as JsonSchemaNode;
 		const serialized = JSON.stringify(schema);
-		// Mission, inspector, inline workflow, guide, and toolTimeoutMs fields intentionally expanded the public tool surface.
-		assert.ok(serialized.length < 17_400, `expected compact schema under 17.4k chars, got ${serialized.length}`);
+		// Mission, inspector, inline workflow, guide, toolTimeoutMs, and capability-list fields intentionally expanded the public tool surface.
+		assert.ok(serialized.length < 17_600, `expected compact schema under 17.6k chars, got ${serialized.length}`);
 		assert.equal(serialized.includes('"$ref"'), false);
 		assert.equal(serialized.includes('"$defs"'), false);
 		assert.equal(serialized.split("Optional acceptance policy.").length - 1, 1);

package/dist/extensions/pi-subagents/test/unit/scripted-workflow.test.ts

@@ -106,6 +106,27 @@ describe("scripted workflow runtime", () => {
 			`return runs.host("tests", { kind: "command", command: "npm test" });`,
 			`return runs.host("tests", { kind: "command", command: "npm test", timeoutMs: 1000, output: "../tests.log" });`,
 		]) assert.equal(validateWorkflowScript(script).ok, false);
+		const cwd = validateWorkflowScript(`return runs.host("tests", { kind: "command", command: "npm test", timeoutMs: 1000, cwd: "/tmp" });`);
+		assert.equal(cwd.ok, false);
+		assert.ok(cwd.errors.some((error) => /unsupported field 'cwd'.*does not accept per-step cwd.*workflow cwd.*outer subagent request.*cd \/path\/to\/worktree/.test(error.message)));
+	});
+
+	it("explains the workflow cwd workaround for dynamic runs.host params", async () => {
+		let called = false;
+		await assert.rejects(
+			runWorkflowScript({
+				script: `const params = { kind: "command", command: "npm test", timeoutMs: 1000, cwd: "/tmp" }; return await runs.host("tests", params);`,
+				async host() {
+					called = true;
+					return { key: "tests", kind: "command", ok: true, state: "passed", exitCode: 0, stdout: "", stderr: "", outputPath: "tests.log", durationMs: 1 };
+				},
+				async launch(key) { return { key, ok: true, output: "unused", artifactPaths: [] }; },
+				async status(key) { return { key, ok: true, output: "unused", artifactPaths: [] }; },
+			}),
+			(error: unknown) => error instanceof WorkflowScriptError
+				&& /does not accept per-step cwd.*workflow cwd.*outer subagent request.*cd \/path\/to\/worktree/.test(error.message),
+		);
+		assert.equal(called, false);
 	});
 
 	it("runs an awaited host command through the host boundary", async () => {

package/dist/extensions/pi-subagents/test/unit/single-output.test.ts

@@ -169,6 +169,19 @@ describe("resolveSingleOutput", () => {
 		assert.equal(result.savedPath, undefined);
 		assert.match(result.saveError ?? "", /Failed to read changed output file/);
 	});
+
+	it("fails closed when the pre-run output snapshot could not be inspected", () => {
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-output-test-"));
+		tempDirs.push(dir);
+		const outputPath = path.join(dir, "review.md");
+
+		const result = resolveSingleOutput(outputPath, "fallback output", { exists: false, error: "permission denied" });
+
+		assert.equal(result.fullOutput, "fallback output");
+		assert.equal(result.savedPath, undefined);
+		assert.match(result.saveError ?? "", /Failed to inspect output file: permission denied/);
+		assert.equal(fs.existsSync(outputPath), false);
+	});
 });
 
 describe("extractChildWrittenOutput", () => {

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

@@ -370,6 +370,60 @@ describe("subagent_wait tool", () => {
 		}
 	});
 
+	it("surfaces bounded recovery guidance for a failed completion", async () => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-recovery-completion-"));
+		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-recovery", "running", { sessionId: "sess-1", pid: 999999 });
+			const result = await waitForSubagents({ all: true }, undefined, baseDeps(root, state, {
+				sleep: async () => {
+					const recovery = {
+						termination: "timed-out",
+						changedFiles: ["input.md"],
+						recoveryNeeded: true,
+						reason: "timed-out-with-dirty-worktree",
+						reportStatus: "missing",
+						message: "raw recovery message must not cross the wait boundary",
+						effects: { settlementDiagnostic: { finalTextPresent: true } },
+					};
+					writeStatus(asyncRoot, "run-recovery", "failed", {
+						sessionId: "sess-1",
+						steps: [{ agent: "worker", status: "failed", timedOut: true, timeoutRecovery: recovery }],
+					});
+					fs.writeFileSync(path.join(resultsDir, "run-recovery.json"), JSON.stringify({
+						id: "run-recovery",
+						runId: "run-recovery",
+						mode: "single",
+						state: "failed",
+						success: false,
+						results: [{ agent: "worker", success: false, error: "Subagent timed out.", output: "raw output must not be copied", timeoutRecovery: recovery }],
+					}), "utf-8");
+				},
+			}));
+
+			assert.equal(result.isError, undefined);
+			const text = textOf(result);
+			assert.match(text, /Recovery needed: review the diff and artifacts before resuming or launching dependent stages\./);
+			assert.match(text, /requested report: missing/);
+			assert.match(text, /changed tracked files: input\.md/);
+			assert.doesNotMatch(text, /raw recovery message|settlementDiagnostic|raw output/);
+			const completion = result.details.completions?.[0];
+			assert.equal(completion?.success, false);
+			assert.deepEqual(completion?.results?.[0]?.timeoutRecovery, {
+				termination: "timed-out",
+				changedFiles: ["input.md"],
+				recoveryNeeded: true,
+				reason: "timed-out-with-dirty-worktree",
+				reportStatus: "missing",
+			});
+		} finally {
+			fs.rmSync(root, { recursive: true, force: true });
+		}
+	});
+
 	it("surfaces terminal completion payloads from an indexed pending result file", async () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wait-completions-pending-"));
 		const originalError = console.error;