pi-subagents 0.35.1 → 0.37.0

package/src/runs/shared/subagent-control.ts

@@ -193,11 +193,15 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
 		].filter((line): line is string => Boolean(line)).join("\n");
 	}
 
+	const supervisorHint = event.reason === "supervisor_request"
+		? "Supervisor request: reply to the pending request. If subagent_supervisor pending is empty, check intercom pending because an external intercom tool may own the request."
+		: undefined;
 	return [
 		`Subagent needs attention: ${event.agent}`,
 		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
 		`Signal: ${event.message}`,
 		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+		supervisorHint,
 		"Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
 		`Top-level live async nudge: ${steerCommand}`,
 		`Routed live nested nudge: ${nestedResumeCommand}`,

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -4,15 +4,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
 import { consumeSteerRequestsFromDir, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
-import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
 import {
 	CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
-	formatChildToolDiagnostic,
+	MCP_DIRECT_CHILD_TOOLS_ENV,
 	REQUIRED_CHILD_TOOLS_ENV,
 	writeChildToolDiagnostic,
 	type ChildToolDiagnostic,
 } from "./tool-availability.ts";
-import { TOOL_BUDGET_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
+import { TOOL_BUDGET_ENV, TOOL_BUDGET_ZERO_AUTH_ENV, decodeToolBudgetEnv, shouldBlockToolForBudget, toolBudgetBlockedMessage, toolBudgetSoftNudge } from "./tool-budget.ts";
 import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../shared/types.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
@@ -69,16 +69,34 @@ function readBooleanEnv(name: string): boolean | undefined {
 	return value !== "0";
 }
 
-function refreshChildToolDiagnostic(pi: ExtensionAPI): ChildToolDiagnostic | undefined {
-	const filePath = process.env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV]?.trim();
+function readRequiredChildTools(): string[] | undefined {
 	const encoded = process.env[REQUIRED_CHILD_TOOLS_ENV]?.trim();
-	if (!filePath || !encoded) return undefined;
+	if (!encoded) return undefined;
 	const required = JSON.parse(encoded) as unknown;
 	if (!Array.isArray(required) || required.some((name) => typeof name !== "string" || !name)) {
 		throw new Error(`Invalid ${REQUIRED_CHILD_TOOLS_ENV} payload.`);
 	}
+	return required;
+}
+
+function readMcpDirectChildTools(): string[] | undefined {
+	const encoded = process.env[MCP_DIRECT_CHILD_TOOLS_ENV]?.trim();
+	if (!encoded) return undefined;
+	try {
+		const tools = JSON.parse(encoded) as unknown;
+		if (!Array.isArray(tools) || tools.some((name) => typeof name !== "string" || !name)) return undefined;
+		return tools;
+	} catch {
+		return undefined;
+	}
+}
+
+function refreshChildToolDiagnostic(pi: ExtensionAPI): ChildToolDiagnostic | undefined {
+	const filePath = process.env[CHILD_TOOL_DIAGNOSTIC_PATH_ENV]?.trim();
+	const required = readRequiredChildTools();
+	if (!filePath || !required) return undefined;
 	const available = pi.getAllTools().map((tool) => tool.name);
-	return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim());
+	return writeChildToolDiagnostic(filePath, required, available, process.env[SUBAGENT_CHILD_AGENT_ENV]?.trim(), readMcpDirectChildTools());
 }
 
 function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
@@ -329,7 +347,7 @@ export function registerSteeringInbox(
 
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerSteeringInbox(pi);
-	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV]));
+	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV], { allowZero: process.env[TOOL_BUDGET_ZERO_AUTH_ENV] === "1" }));
 	registerChildWatchdog(pi);
 	const waitToolEnabled = resolveWaitToolConfig().enabled;
 	const waitState = {
@@ -365,6 +383,9 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		const sessionManager = (ctx as { sessionManager?: Parameters<typeof resolveCurrentSessionId>[0] } | undefined)?.sessionManager;
 		waitState.currentSessionId = sessionManager ? resolveCurrentSessionId(sessionManager) : null;
 		registerNativeSupervisorClientOnce();
+		if (readRequiredChildTools()?.includes("intercom")) registerNativeSupervisorFallbackOnce();
+	});
+	onRuntimeEvent("agent_start", () => {
 		refreshChildToolDiagnostic(pi);
 	});
 	onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
@@ -375,12 +396,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
 	if (structuredOutputPath && structuredSchemaPath) {
 		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
-		const parameters = {
-			type: "object",
-			properties: { value: schema },
-			required: ["value"],
-			additionalProperties: false,
-		};
+		const parameters = createStructuredOutputToolParameters(schema);
 		const registerTool = pi.registerTool as unknown as (tool: {
 			name: string;
 			label: string;
@@ -394,7 +410,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 			description: "Submit the required final structured output for this subagent step. This terminates the step.",
 			parameters: parameters as never,
 			async execute(_id: string, params: { value: unknown }) {
-				const validation = validateStructuredOutputValue(schema, params.value);
+				const validation = await validateStructuredOutputValue(schema, params.value);
 				if (validation.status === "invalid") {
 					throw new Error(`Structured output validation failed: ${validation.message}`);
 				}
@@ -417,7 +433,6 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 
 	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
 		registerNativeSupervisorFallbackOnce();
-		const toolDiagnostic = refreshChildToolDiagnostic(pi);
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);
@@ -434,9 +449,6 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 				fanoutChild: fanoutChild === true,
 			});
 		}
-		if (toolDiagnostic) {
-			rewritten = `${formatChildToolDiagnostic(toolDiagnostic)}\nDo not claim tool-dependent work succeeded; report this configuration error to the parent.\n\n${rewritten}`;
-		}
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});

package/src/runs/shared/task-intent.ts

@@ -25,10 +25,11 @@ const REVIEW_ONLY_PATTERNS = [
 ];
 
 const REVIEWER_REQUIRED_EDIT_PATTERNS = [
-	/\bmust\s+(?:edit|modify|change|fix|patch|apply)\b/i,
-	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\bmust\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/\brequired\s+to\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
+	/(?:^|[.!?\n]\s*)implement\s+(?:the\s+)?(?:approved|requested|specified|file|code|source|fix(?:es)?|changes?)\b/i,
 	/\bregardless\s+of\s+findings\b/i,
-	/\balways\s+(?:edit|modify|change|fix|patch|apply)\b/i,
+	/\balways\s+(?:edit|modify|change|fix|patch|apply|implement)\b/i,
 	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
 	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
 ];
@@ -134,8 +135,12 @@ function taskHasReadOnlyDeliverable(taskText: string): boolean {
 	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
 }
 
+function isReviewerStyleAgent(agent: string): boolean {
+	return /\b(?:advisor|reviewer|oracle)\b/i.test(agent);
+}
+
 function hasImplementationIntent(agent: string, taskText: string): boolean {
-	if (/\breviewer\b/i.test(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (isReviewerStyleAgent(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
 	if (agent === "worker") return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
 	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
 }
@@ -151,7 +156,7 @@ export function classifyTaskMutationIntent(agent: string, task: string): TaskMut
 
 	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
 	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
-	if (/\breviewer\b/i.test(agent)) return { kind: "read-only" };
+	if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
 	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
 }
 

package/src/runs/shared/tool-availability.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 export const REQUIRED_CHILD_TOOLS_ENV = "PI_SUBAGENT_REQUIRED_TOOLS";
+export const MCP_DIRECT_CHILD_TOOLS_ENV = "PI_SUBAGENT_MCP_DIRECT_TOOLS";
 export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "PI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
 
 export interface ChildToolDiagnostic {
@@ -9,22 +10,35 @@ export interface ChildToolDiagnostic {
 	required: string[];
 	available: string[];
 	missing: string[];
+	missingMcpDirectTools?: string[];
 }
 
+const PI_CORE_CHILD_TOOLS = new Set(["bash", "edit", "find", "grep", "ls", "read", "write"]);
+
 export function writeChildToolDiagnostic(
 	filePath: string,
 	required: string[],
 	available: string[],
 	agent?: string,
+	mcpDirectTools?: string[],
 ): ChildToolDiagnostic | undefined {
-	const availableNames = new Set(available);
+	const availableNames = new Set([...available, ...PI_CORE_CHILD_TOOLS]);
 	const missing = required.filter((name) => !availableNames.has(name));
 	if (missing.length === 0) {
 		fs.rmSync(filePath, { force: true });
 		return undefined;
 	}
 
-	const diagnostic: ChildToolDiagnostic = { agent, required, available, missing };
+	const missingMcpDirectTools = mcpDirectTools?.length
+		? missing.filter((name) => mcpDirectTools.includes(name))
+		: [];
+	const diagnostic: ChildToolDiagnostic = {
+		agent,
+		required,
+		available,
+		missing,
+		...(missingMcpDirectTools.length > 0 ? { missingMcpDirectTools } : {}),
+	};
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	fs.writeFileSync(filePath, JSON.stringify(diagnostic), { mode: 0o600 });
 	return diagnostic;
@@ -34,7 +48,7 @@ export function readChildToolDiagnostic(filePath: string | undefined): ChildTool
 	if (!filePath || !fs.existsSync(filePath)) return undefined;
 	const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<ChildToolDiagnostic>;
 	const stringArray = (value: unknown): value is string[] => Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
-	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string")) {
+	if (!stringArray(parsed.required) || !stringArray(parsed.available) || !stringArray(parsed.missing) || (parsed.agent !== undefined && typeof parsed.agent !== "string") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
 		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
 	}
 	return {
@@ -42,6 +56,7 @@ export function readChildToolDiagnostic(filePath: string | undefined): ChildTool
 		required: parsed.required,
 		available: parsed.available,
 		missing: parsed.missing,
+		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
 	};
 }
 
@@ -50,6 +65,9 @@ export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): stri
 	return [
 		`${subject} requested unavailable child tools: ${diagnostic.missing.join(", ")}.`,
 		"The `tools` field is a strict allowlist; it does not load extension code.",
+		...(diagnostic.missingMcpDirectTools?.length
+			? [`Resolved MCP direct tools missing from the child registry: ${diagnostic.missingMcpDirectTools.join(", ")}. This indicates a host/pi-mcp-adapter registration problem, not a tool-call failure.`]
+			: []),
 		"For extension tools, add the provider path to `subagentOnlyExtensions` (child-only), `extensions`, or as a path-like entry in `tools`, while keeping each registered tool name in `tools`.",
 		"For MCP tools, verify the MCP adapter configuration and selected tool names. For builtin tools, verify the name against the installed Pi version.",
 	].join("\n");

package/src/runs/shared/tool-budget.ts

@@ -2,6 +2,7 @@ import type { ResolvedToolBudget, ToolBudgetConfig, ToolBudgetState } from "../.
 
 export const DEFAULT_TOOL_BUDGET_BLOCK = ["read", "grep", "find", "ls"] as const;
 export const TOOL_BUDGET_ENV = "PI_SUBAGENT_TOOL_BUDGET";
+export const TOOL_BUDGET_ZERO_AUTH_ENV = "PI_SUBAGENT_TOOL_BUDGET_ZERO_AUTH";
 
 export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | undefined): "*" | string[] {
 	if (block === "*") return "*";
@@ -9,12 +10,17 @@ export function normalizeToolBudgetBlock(block: ToolBudgetConfig["block"] | unde
 	return [...new Set(block.map((tool) => tool.trim()).filter(Boolean))];
 }
 
-export function validateToolBudgetConfig(raw: unknown, label = "toolBudget"): { budget?: ResolvedToolBudget; error?: string } {
+export function validateToolBudgetConfig(
+	raw: unknown,
+	label = "toolBudget",
+	options: { minimumHard?: 0 | 1 } = {},
+): { budget?: ResolvedToolBudget; error?: string } {
 	if (raw === undefined) return {};
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: `${label} must be an object with hard and optional soft/block.` };
 	const value = raw as ToolBudgetConfig;
-	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < 1) {
-		return { error: `${label}.hard must be an integer >= 1.` };
+	const minimumHard = options.minimumHard ?? 1;
+	if (typeof value.hard !== "number" || !Number.isInteger(value.hard) || value.hard < minimumHard) {
+		return { error: `${label}.hard must be an integer >= ${minimumHard}.` };
 	}
 	if (value.soft !== undefined && (typeof value.soft !== "number" || !Number.isInteger(value.soft) || value.soft < 1)) {
 		return { error: `${label}.soft must be an integer >= 1 when provided.` };
@@ -65,10 +71,10 @@ export function encodeToolBudgetEnv(budget: ResolvedToolBudget | undefined): str
 	return budget ? JSON.stringify(budget) : undefined;
 }
 
-export function decodeToolBudgetEnv(value: string | undefined): ResolvedToolBudget | undefined {
+export function decodeToolBudgetEnv(value: string | undefined, options: { allowZero?: boolean } = {}): ResolvedToolBudget | undefined {
 	if (!value?.trim()) return undefined;
 	const parsed = JSON.parse(value) as unknown;
-	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV);
+	const normalized = validateToolBudgetConfig(parsed, TOOL_BUDGET_ENV, options.allowZero ? { minimumHard: 0 } : undefined);
 	if (normalized.error) throw new Error(normalized.error);
 	return normalized.budget;
 }

package/src/runs/shared/turn-budget.ts

@@ -88,10 +88,11 @@ export function turnBudgetDecision(
 	turnCount: number,
 	terminalAssistantStop: boolean,
 	toolWorkActiveOrStarting: boolean,
+	enforceHardLimit = false,
 ): "continue" | "defer" | "abort" {
 	const hardLimit = budget.maxTurns + budget.graceTurns;
 	if (turnCount < hardLimit) return "continue";
-	if (toolWorkActiveOrStarting) return "defer";
+	if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
 	if (turnCount === hardLimit && terminalAssistantStop) return "continue";
 	return "abort";
 }

package/src/runs/shared/worktree.ts

@@ -18,7 +18,7 @@ interface WorktreeInfo {
 	syntheticPaths: string[];
 }
 
-interface WorktreeDiff {
+export interface WorktreeDiff {
 	index: number;
 	agent: string;
 	branch: string;
@@ -27,6 +27,23 @@ interface WorktreeDiff {
 	insertions: number;
 	deletions: number;
 	patchPath: string;
+	error?: string;
+}
+
+export interface WorktreeCleanupTask {
+	index: number;
+	path: string;
+	branch: string;
+	worktreeRemoved: boolean;
+	branchRemoved: boolean;
+	errors?: string[];
+}
+
+export interface WorktreeCleanupReport {
+	state: "complete" | "partial";
+	tasks: WorktreeCleanupTask[];
+	pruned: boolean;
+	errors?: string[];
 }
 
 interface WorktreeTaskCwdConflict {
@@ -426,7 +443,7 @@ function removeSyntheticPathsBeforeDiff(worktree: WorktreeInfo): void {
 	}
 }
 
-function emptyDiff(index: number, agent: string, branch: string, patchPath: string): WorktreeDiff {
+function emptyDiff(index: number, agent: string, branch: string, patchPath: string, error?: string): WorktreeDiff {
 	return {
 		index,
 		agent,
@@ -436,6 +453,7 @@ function emptyDiff(index: number, agent: string, branch: string, patchPath: stri
 		insertions: 0,
 		deletions: 0,
 		patchPath,
+		...(error ? { error } : {}),
 	};
 }
 
@@ -497,13 +515,30 @@ function writeEmptyPatch(patchPath: string): void {
 	}
 }
 
-function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): WorktreeCleanupTask {
+	const errors: string[] = [];
+	let worktreeRemoved = false;
+	let branchRemoved = false;
+	try {
+		runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]);
+		worktreeRemoved = true;
+	} catch (error) {
+		errors.push(`worktree removal failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+	try {
+		runGitChecked(repoCwd, ["branch", "-D", worktree.branch]);
+		branchRemoved = true;
+	} catch (error) {
+		errors.push(`branch removal failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
+	return {
+		index: worktree.index,
+		path: worktree.path,
+		branch: worktree.branch,
+		worktreeRemoved,
+		branchRemoved,
+		...(errors.length ? { errors } : {}),
+	};
 }
 
 function hasWorktreeChanges(diff: WorktreeDiff): boolean {
@@ -560,23 +595,37 @@ export function diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir:
 		const patchPath = path.join(diffsDir, `task-${index}-${safePatchAgentName(agent)}.patch`);
 		try {
 			diffs.push(captureWorktreeDiff(setup, worktree, agent, patchPath));
-		} catch {
-			// Preserve execution flow; failed diff capture maps to an empty per-task patch.
+		} catch (error) {
+			// Preserve execution flow while retaining the failed capture as handoff evidence.
 			writeEmptyPatch(patchPath);
-			diffs.push(emptyDiff(index, agent, worktree.branch, patchPath));
+			diffs.push(emptyDiff(index, agent, worktree.branch, patchPath, error instanceof Error ? error.message : String(error)));
 		}
 	}
 
 	return diffs;
 }
 
-export function cleanupWorktrees(setup: WorktreeSetup): void {
+export function cleanupWorktrees(setup: WorktreeSetup): WorktreeCleanupReport {
+	const tasks: WorktreeCleanupTask[] = [];
 	for (let index = setup.worktrees.length - 1; index >= 0; index--) {
-		cleanupSingleWorktree(setup.cwd, setup.worktrees[index]!);
+		tasks.push(cleanupSingleWorktree(setup.cwd, setup.worktrees[index]!));
 	}
-	try { runGitChecked(setup.cwd, ["worktree", "prune"]); } catch {
-		// Pruning is best-effort cleanup.
+	tasks.sort((left, right) => left.index - right.index);
+	const errors: string[] = [];
+	let pruned = false;
+	try {
+		runGitChecked(setup.cwd, ["worktree", "prune"]);
+		pruned = true;
+	} catch (error) {
+		errors.push(`worktree prune failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
+	const state = tasks.every((task) => task.worktreeRemoved && task.branchRemoved) && pruned ? "complete" : "partial";
+	return {
+		state,
+		tasks,
+		pruned,
+		...(errors.length ? { errors } : {}),
+	};
 }
 
 export function formatWorktreeDiffSummary(diffs: WorktreeDiff[]): string {

package/src/shared/accessible-dir.ts

@@ -0,0 +1,25 @@
+import * as fs from "node:fs";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
+
+type AccessibleDirFs = Pick<typeof fs, "accessSync" | "mkdirSync">;
+
+type AccessibleDirOptions = {
+	fs?: AccessibleDirFs;
+	retryDirectoryErrors?: boolean;
+	retryDelaysMs?: readonly number[];
+	wait?: (delayMs: number) => void;
+};
+
+export function ensureAccessibleDir(dirPath: string, options: AccessibleDirOptions = {}): void {
+	const fsImpl = options.fs ?? fs;
+	const retryDirectoryErrors = options.retryDirectoryErrors ?? process.platform === "win32";
+	const retryDelaysMs = retryDirectoryErrors ? options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS : [];
+	const wait = options.wait ?? waitForFileSystemRetry;
+
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.mkdirSync(dirPath, { recursive: true });
+	}, { retryDelaysMs, wait });
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+	}, { retryDelaysMs, wait });
+}

package/src/shared/artifacts.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { TEMP_ARTIFACTS_DIR, type ArtifactPaths } from "./types.ts";
+import { TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
@@ -17,13 +17,30 @@ export function getProjectChainRunsDir(cwd: string): string {
 	return path.join(getProjectSubagentsDir(cwd), "chain-runs");
 }
 
-export function getArtifactsDir(sessionFile: string | null, projectCwd?: string): string {
-	if (projectCwd) return getProjectArtifactsDir(projectCwd);
-	if (sessionFile) {
-		const sessionDir = path.dirname(sessionFile);
-		return path.join(sessionDir, "subagent-artifacts");
+export function getArtifactsDir(
+	sessionFile: string | null,
+	projectCwd?: string,
+	dirPreference: ArtifactDirPreference = "project",
+): string {
+	switch (dirPreference) {
+		case "session":
+			if (sessionFile) {
+				const sessionDir = path.dirname(sessionFile);
+				return path.join(sessionDir, "subagent-artifacts");
+			}
+			return TEMP_ARTIFACTS_DIR;
+		case "temp":
+			return TEMP_ARTIFACTS_DIR;
+		case "project":
+			if (projectCwd) return getProjectArtifactsDir(projectCwd);
+			if (sessionFile) {
+				const sessionDir = path.dirname(sessionFile);
+				return path.join(sessionDir, "subagent-artifacts");
+			}
+			return TEMP_ARTIFACTS_DIR;
+		default:
+			throw new Error(`Unsupported artifactDir ${JSON.stringify(dirPreference)}; expected "project", "session", or "temp".`);
 	}
-	return TEMP_ARTIFACTS_DIR;
 }
 
 export function getArtifactPaths(artifactsDir: string, runId: string, agent: string, index?: number): ArtifactPaths {
@@ -47,6 +64,19 @@ export function writeArtifact(filePath: string, content: string): void {
 	fs.writeFileSync(filePath, content, "utf-8");
 }
 
+export function formatOutputArtifactContent(input: {
+	output: string;
+	error?: string;
+	transcriptPath?: string;
+	metadataPath?: string;
+}): string {
+	if (input.output.trim() || !input.error) return input.output;
+	const lines = ["Subagent run failed before producing output.", "", "Error:", input.error];
+	if (input.transcriptPath) lines.push("", `Transcript: ${input.transcriptPath}`);
+	if (input.metadataPath) lines.push(`Metadata: ${input.metadataPath}`);
+	return lines.join("\n");
+}
+
 export function writeMetadata(filePath: string, metadata: object): void {
 	fs.writeFileSync(filePath, JSON.stringify(metadata, null, 2), "utf-8");
 }

package/src/shared/atomic-json.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS, runFileSystemOperationWithRetry, waitForFileSystemRetry } from "./file-system-retry.ts";
 
 type AtomicJsonFs = Pick<typeof fs, "mkdirSync" | "writeFileSync" | "renameSync" | "rmSync">;
 
@@ -10,38 +11,11 @@ type AtomicJsonWriterOptions = {
 	random?: () => number;
 	mode?: number;
 	retryRenameErrors?: boolean;
+	retryDirectoryErrors?: boolean;
 	retryDelaysMs?: readonly number[];
 	wait?: (delayMs: number) => void;
 };
 
-const DEFAULT_RENAME_RETRY_DELAYS_MS = [10, 25, 50, 100, 200, 500, 1000, 2000, 4000] as const;
-const RETRYABLE_RENAME_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
-const WAIT_BUFFER = typeof SharedArrayBuffer !== "undefined" ? new SharedArrayBuffer(4) : undefined;
-const WAIT_VIEW = WAIT_BUFFER ? new Int32Array(WAIT_BUFFER) : undefined;
-
-function waitSync(delayMs: number): void {
-	if (delayMs <= 0) return;
-	if (WAIT_VIEW) {
-		try {
-			// writeAtomicJson is synchronous because callers often update status from sync callbacks.
-			// Atomics.wait gives Windows rename locks time to clear without burning CPU.
-			Atomics.wait(WAIT_VIEW, 0, 0, delayMs);
-			return;
-		} catch {
-			// Fall through to the portable busy wait below.
-		}
-	}
-	const end = Date.now() + delayMs;
-	while (Date.now() < end) {
-		// Portable fallback for runtimes where Atomics.wait is unavailable.
-	}
-}
-
-function isRetryableRenameError(error: unknown): boolean {
-	const code = (error as NodeJS.ErrnoException | undefined)?.code;
-	return typeof code === "string" && RETRYABLE_RENAME_ERROR_CODES.has(code);
-}
-
 function renameWithRetry(
 	fsImpl: AtomicJsonFs,
 	sourcePath: string,
@@ -49,16 +23,9 @@ function renameWithRetry(
 	retryDelaysMs: readonly number[],
 	wait: (delayMs: number) => void,
 ): void {
-	for (let attempt = 0; ; attempt++) {
-		try {
-			fsImpl.renameSync(sourcePath, targetPath);
-			return;
-		} catch (error) {
-			const delayMs = retryDelaysMs[attempt];
-			if (delayMs === undefined || !isRetryableRenameError(error)) throw error;
-			wait(delayMs);
-		}
-	}
+	runFileSystemOperationWithRetry(() => {
+		fsImpl.renameSync(sourcePath, targetPath);
+	}, { retryDelaysMs, wait });
 }
 
 export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (filePath: string, payload: object) => void {
@@ -68,17 +35,22 @@ export function createAtomicJsonWriter(options: AtomicJsonWriterOptions = {}): (
 	const random = options.random ?? Math.random;
 	const mode = options.mode;
 	const retryRenameErrors = options.retryRenameErrors ?? process.platform === "win32";
-	const retryDelaysMs = retryRenameErrors ? options.retryDelaysMs ?? DEFAULT_RENAME_RETRY_DELAYS_MS : [];
-	const wait = options.wait ?? waitSync;
+	const retryDirectoryErrors = options.retryDirectoryErrors ?? retryRenameErrors;
+	const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS;
+	const renameRetryDelaysMs = retryRenameErrors ? retryDelaysMs : [];
+	const directoryRetryDelaysMs = retryDirectoryErrors ? retryDelaysMs : [];
+	const wait = options.wait ?? waitForFileSystemRetry;
 	return (filePath: string, payload: object): void => {
-		fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
+		runFileSystemOperationWithRetry(() => {
+			fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
+		}, { retryDelaysMs: directoryRetryDelaysMs, wait });
 		const tempPath = path.join(
 			path.dirname(filePath),
 			`.${path.basename(filePath)}.${pid}.${now()}.${random().toString(36).slice(2)}.tmp`,
 		);
 		try {
 			fsImpl.writeFileSync(tempPath, JSON.stringify(payload, null, 2), mode === undefined ? "utf-8" : { encoding: "utf-8", mode });
-			renameWithRetry(fsImpl, tempPath, filePath, retryDelaysMs, wait);
+			renameWithRetry(fsImpl, tempPath, filePath, renameRetryDelaysMs, wait);
 		} finally {
 			fsImpl.rmSync(tempPath, { force: true });
 		}