@selesai/code 0.5.20 → 0.5.21

package/dist/extensions/pi-subagents/src/runs/shared/task-intent.ts

@@ -0,0 +1,181 @@
+/**
+ * Shared task mutation-intent classifier.
+ *
+ * Single authority for reading a task's wording, answering two different
+ * questions from one prohibition analysis:
+ *
+ * - `classifyTaskMutationIntent` / `expectsImplementationMutation`: does the
+ *   task REQUIRE file changes? Consumed by the completion mutation guard,
+ *   which blocks completion, so its vocabulary is deliberately narrow.
+ * - `taskMayMutate`: COULD the task plausibly change files? Consumed by
+ *   acceptance level inference, which only raises evidence gates, so its
+ *   vocabulary is deliberately broad (any bare write verb).
+ *
+ * Explicit read-only wording ("do not modify", "review only") is a task-level
+ * intent only when no write imperative survives outside those phrases. A task
+ * like "Do not modify tests; implement the fix" is an implementation task with
+ * a scoped constraint, not a read-only task.
+ */
+
+const REVIEW_ONLY_PATTERNS = [
+	/\breview only\b/i,
+	/\bsuggest fixes only\b/i,
+	/\bonly return findings\b/i,
+	/\breturn findings only\b/i,
+];
+
+const REVIEWER_REQUIRED_EDIT_PATTERNS = [
+	/\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|implement)\b/i,
+	/\bapply\s+(?:the\s+)?fix(?:es)?\s+directly\b/i,
+	/\bmake\s+(?:the\s+)?code\s+changes\b/i,
+];
+
+// The prohibition's object ends at punctuation or at a coordinating word
+// (but/and/then), so a follow-on clause like "but implement the fix" stays in
+// the text for write-intent testing instead of being swallowed as the object.
+const NO_EDIT_PROHIBITION_PATTERN = /\b(?:do not|don't|must not)\s+(?:edit|modify|write(?:\s+to)?|touch|change)\b((?:(?!\b(?:but|and|then)\b)[^.;,:!?\n–—-])*)/gi;
+
+/** Objects of a no-edit prohibition that mean "the codebase in general" rather than a named scope. */
+const GENERIC_PROHIBITION_OBJECT = /^\s*(?:(?:any|all|the|these|those|your|our|existing|project|source|sources|repo|repository)[\s/,-]*)*(?:files?|code|codebase|sources?|anything|repo(?:sitory)?)?\s*$/i;
+
+const SCOPED_NO_EDIT_CONSTRAINT_PATTERNS = [
+	/\bdo not edit files?\s+outside\b/i,
+	/\bdo not edit\s+outside\b/i,
+	/\bdo not edit\s+unrelated files?\b/i,
+	/\bdo not change\s+unrelated files?\b/i,
+	/\bdo not modify\s+unrelated files?\b/i,
+];
+
+const NO_TOOL_INTENT_PATTERNS = [
+	/\bno tools? needed\b/i,
+	/\bno tools? required\b/i,
+	/\bwithout using tools\b/i,
+	/\bdo not use tools\b/i,
+	/\bdon't use tools\b/i,
+];
+
+const READ_ONLY_DELIVERABLE_PATTERNS = [
+	/\b(?:draft|write|compose|prepare|produce)\s+(?:(?:a|an|the)\s+)?(?:github\s+)?(?:issue|bug report|issue draft|issue body|proposal|plan|report|summary|findings?|analysis|recommendations?)\b/i,
+	/\b(?:issue|bug report)\s+(?:draft|body|template)\b/i,
+	/\b(?:return|provide|produce)\s+(?:text|markdown|answer|findings?|recommendations?)\s+only\b/i,
+];
+
+const RESEARCH_AGENT_PATTERNS = [
+	/\binvestigate\b/i,
+	/\bscout\b/i,
+	/\bresearch(?:er)?\b/i,
+];
+
+const FIX_OR_PATCH_IMPLEMENTATION_PATTERN = /\b(?:fix|patch)\s+(?:(?:it|this|that|them|each|any|all|these|those)\b|(?:(?:a|an|the|any|all)\s+)?(?:(?:failing|failed|broken|flaky|red|cold|start|current|existing|reported|approved|known|regression|unit|integration|e2e|source|typescript|type-?script|ts|type-?check|compiler)\s+)*(?:bug|defect|issues?|problems?|failures?|regressions?|tests?|errors?|items?|typos?|code|source|implementation|component|function|module|class|method|logic|file|files|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command|lint(?:ing)?|build|ci|type-?check|type\s+checking)\b)/i;
+
+const WORKER_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor|delete)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\b(?:update|add|remove|replace|create)\b(?!\s+(?:(?:a|an|the)\s+)?(?:report|summary|findings?)(?:\b|$))/i,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+];
+
+const GENERAL_IMPLEMENTATION_PATTERNS = [
+	/\b(?:implement|edit|modify|refactor)\b/i,
+	FIX_OR_PATCH_IMPLEMENTATION_PATTERN,
+	/\bapply\s+(?:the\s+)?(?:(?:suggested|proposed|recommended)\s+)?(?:changes?|fix(?:es)?|patch)\b/i,
+	/\bmake\s+(?:the\s+)?changes\b/i,
+	/\bdo those fixes\b/i,
+	/\b(?:update|add|remove|replace|delete|create)\s+(?:the\s+)?(?:file|files|code|source|implementation|test|tests|component|function|module|class|method|logic|import|imports|readme|docs?|changelog|package\.json|config|manifest|extension|prompt|command)\b/i,
+];
+
+export type TaskMutationIntent = { kind: "implementation" } | { kind: "read-only" } | { kind: "unknown" };
+
+function stripFrameworkInstructions(task: string): string {
+	return task
+		.split("\n")
+		.filter((line) => !/^\s*\[(?:Write to|Read from):/i.test(line))
+		.filter((line) => !/^\s*(?:Create and maintain progress at:|Update progress at:|\*\*Output:\*\*|Write your findings to(?: exactly this path)?:|Return the complete artifact in your final response\.|The runtime will persist it to exactly this path:|Do not call contact_supervisor merely because no write-capable tool is available\.|This path is authoritative for this run\.|Ignore any other output filename or output path mentioned elsewhere)/i.test(line))
+		.join("\n");
+}
+
+function stripPatterns(task: string, patterns: RegExp[]): string {
+	let stripped = task;
+	for (const pattern of patterns) {
+		const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+		stripped = stripped.replace(new RegExp(pattern.source, flags), " ");
+	}
+	return stripped;
+}
+
+interface NoEditProhibitionAnalysis {
+	/** True when any prohibition (or review-only/no-tool wording) is present. */
+	present: boolean;
+	/** True when a prohibition covers files/code in general; such wording wins over write verbs. */
+	blanket: boolean;
+	/** Task text with prohibition phrases and their objects removed, for write-intent testing. */
+	strippedText: string;
+}
+
+function analyzeNoEditProhibitions(taskText: string): NoEditProhibitionAnalysis {
+	let present = REVIEW_ONLY_PATTERNS.some((pattern) => pattern.test(taskText))
+		|| NO_TOOL_INTENT_PATTERNS.some((pattern) => pattern.test(taskText));
+	let blanket = present;
+	let strippedText = stripPatterns(taskText, [...REVIEW_ONLY_PATTERNS, ...NO_TOOL_INTENT_PATTERNS]);
+	strippedText = strippedText.replace(new RegExp(NO_EDIT_PROHIBITION_PATTERN.source, NO_EDIT_PROHIBITION_PATTERN.flags), (_match, object: string) => {
+		present = true;
+		if (GENERIC_PROHIBITION_OBJECT.test(object)) blanket = true;
+		return " ";
+	});
+	return { present, blanket, strippedText };
+}
+
+function taskHasReadOnlyDeliverable(taskText: string): boolean {
+	return READ_ONLY_DELIVERABLE_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+function isReviewerStyleAgent(agent: string): boolean {
+	return /\b(?:architect|commentator|explorer|recapper|researcher)\b/i.test(agent);
+}
+
+function hasImplementationIntent(agent: string, taskText: string): boolean {
+	if (isReviewerStyleAgent(agent)) return REVIEWER_REQUIRED_EDIT_PATTERNS.some((pattern) => pattern.test(taskText));
+	if (agent === "builder") return WORKER_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+	return GENERAL_IMPLEMENTATION_PATTERNS.some((pattern) => pattern.test(taskText));
+}
+
+export function classifyTaskMutationIntent(agent: string, task: string): TaskMutationIntent {
+	const taskText = stripFrameworkInstructions(task);
+	const taskTextWithoutScopedConstraints = stripPatterns(taskText, SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskTextWithoutScopedConstraints);
+	if (prohibitions.present) {
+		if (prohibitions.blanket) return { kind: "read-only" };
+		return hasImplementationIntent(agent, prohibitions.strippedText) ? { kind: "implementation" } : { kind: "read-only" };
+	}
+
+	if (RESEARCH_AGENT_PATTERNS.some((pattern) => pattern.test(agent))) return { kind: "read-only" };
+	if (hasImplementationIntent(agent, taskText)) return { kind: "implementation" };
+	if (isReviewerStyleAgent(agent)) return { kind: "read-only" };
+	return taskHasReadOnlyDeliverable(taskTextWithoutScopedConstraints) ? { kind: "read-only" } : { kind: "unknown" };
+}
+
+export function expectsImplementationMutation(agent: string, task: string): boolean {
+	return classifyTaskMutationIntent(agent, task).kind === "implementation";
+}
+
+/** Bare write verbs that make a task write-capable for acceptance inference. */
+const MAY_MUTATE_VERB_PATTERN = /\b(?:fix|implement|update|write|edit|modify|migrate|delete|remove|refactor|commit)\b/i;
+
+/**
+ * Whether the task could plausibly change files. Blanket prohibitions win;
+ * write verbs inside a scoped prohibition's object or a read-only deliverable
+ * phrase ("write a summary report") do not count; any other bare write verb
+ * does.
+ */
+export function taskMayMutate(task: string): boolean {
+	const taskText = stripPatterns(stripFrameworkInstructions(task), SCOPED_NO_EDIT_CONSTRAINT_PATTERNS);
+	const prohibitions = analyzeNoEditProhibitions(taskText);
+	if (prohibitions.blanket) return false;
+	return MAY_MUTATE_VERB_PATTERN.test(stripPatterns(prohibitions.strippedText, READ_ONLY_DELIVERABLE_PATTERNS));
+}

package/dist/extensions/pi-subagents/src/runs/shared/tool-availability.ts

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const REQUIRED_CHILD_TOOLS_ENV = "SELESAI_SUBAGENT_REQUIRED_TOOLS";
+export const MCP_DIRECT_CHILD_TOOLS_ENV = "SELESAI_SUBAGENT_MCP_DIRECT_TOOLS";
+export const CHILD_TOOL_DIAGNOSTIC_PATH_ENV = "SELESAI_SUBAGENT_TOOL_DIAGNOSTIC_PATH";
+
+export interface ChildToolDiagnostic {
+	agent?: string;
+	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, ...PI_CORE_CHILD_TOOLS]);
+	const missing = required.filter((name) => !availableNames.has(name));
+	if (missing.length === 0) {
+		fs.rmSync(filePath, { force: true });
+		return undefined;
+	}
+
+	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;
+}
+
+export function readChildToolDiagnostic(filePath: string | undefined): ChildToolDiagnostic | undefined {
+	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") || (parsed.missingMcpDirectTools !== undefined && !stringArray(parsed.missingMcpDirectTools))) {
+		throw new Error(`Malformed child tool diagnostic at '${filePath}'.`);
+	}
+	return {
+		...(parsed.agent ? { agent: parsed.agent } : {}),
+		required: parsed.required,
+		available: parsed.available,
+		missing: parsed.missing,
+		...(parsed.missingMcpDirectTools ? { missingMcpDirectTools: parsed.missingMcpDirectTools } : {}),
+	};
+}
+
+export function formatChildToolDiagnostic(diagnostic: ChildToolDiagnostic): string {
+	const subject = diagnostic.agent ? `Agent '${diagnostic.agent}'` : "Subagent";
+	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");
+}
+
+export function readChildToolDiagnosticError(filePath: string | undefined): string | undefined {
+	try {
+		const diagnostic = readChildToolDiagnostic(filePath);
+		return diagnostic ? formatChildToolDiagnostic(diagnostic) : undefined;
+	} catch (error) {
+		return `Failed to read child tool availability diagnostic: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}

package/dist/extensions/pi-subagents/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 = "SELESAI_SUBAGENT_TOOL_BUDGET";
+export const TOOL_BUDGET_ZERO_AUTH_ENV = "SELESAI_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/dist/extensions/pi-subagents/src/runs/shared/turn-budget.ts

@@ -2,6 +2,27 @@ import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts"
 
 export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
 
+export function resolveTurnBudgetConfig(
+	raw: unknown,
+	label = "turnBudget",
+): { turnBudget?: ResolvedTurnBudget; error?: string } {
+	if (raw === undefined) return {};
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { error: `${label} must be an object with maxTurns and optional graceTurns.` };
+	}
+	const unknownField = Object.keys(raw).find((key) => key !== "maxTurns" && key !== "graceTurns");
+	if (unknownField) return { error: `${label}.${unknownField} is not supported.` };
+	const budget = raw as { maxTurns?: unknown; graceTurns?: unknown };
+	if (typeof budget.maxTurns !== "number" || !Number.isInteger(budget.maxTurns) || budget.maxTurns < 1) {
+		return { error: `${label}.maxTurns must be an integer >= 1.` };
+	}
+	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+	if (typeof graceTurns !== "number" || !Number.isInteger(graceTurns) || graceTurns < 0) {
+		return { error: `${label}.graceTurns must be an integer >= 0.` };
+	}
+	return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
+}
+
 export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: ResolvedTurnBudget | undefined): string {
 	if (!budget) return systemPrompt;
 	const grace = budget.graceTurns === 1 ? "1 additional assistant turn" : `${budget.graceTurns} additional assistant turns`;
@@ -24,6 +45,10 @@ export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount:
 	return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
 }
 
+export function turnBudgetDeferredNote(budget: ResolvedTurnBudget, turnCount: number): string {
+	return `Turn-budget termination was deferred at ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}) because the assistant started tool work. The run ended before another safe assistant boundary; output may be partial.`;
+}
+
 export function formatTurnBudgetOutput(message: string, output: string): string {
 	return output.trim()
 		? `${message}\n\nPartial output before turn-budget abort:\n${output}`
@@ -44,9 +69,30 @@ export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, e
 	};
 }
 
-export function shouldAbortForTurnBudget(budget: ResolvedTurnBudget, turnCount: number, terminalAssistantStop: boolean): boolean {
+export function turnBudgetDeferredState(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminationDeferredAtTurn = turnCount,
+): TurnBudgetState {
+	return {
+		...budget,
+		turnCount,
+		outcome: "termination-deferred",
+		wrapUpRequestedAtTurn: budget.maxTurns,
+		terminationDeferredAtTurn,
+	};
+}
+
+export function turnBudgetDecision(
+	budget: ResolvedTurnBudget,
+	turnCount: number,
+	terminalAssistantStop: boolean,
+	toolWorkActiveOrStarting: boolean,
+	enforceHardLimit = false,
+): "continue" | "defer" | "abort" {
 	const hardLimit = budget.maxTurns + budget.graceTurns;
-	if (turnCount < hardLimit) return false;
-	if (turnCount > hardLimit) return true;
-	return !terminalAssistantStop;
+	if (turnCount < hardLimit) return "continue";
+	if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
+	if (turnCount === hardLimit && terminalAssistantStop) return "continue";
+	return "abort";
 }

package/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/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/dist/extensions/pi-subagents/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");
 }