pi-cohort 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [5.3.0] - 2026-09-01
+
+### Changed
+
+- Foreground parallel `worktree: true` patches now write to a run-scoped
+  directory (`<session artifacts>/<runId>/worktree-diffs`) instead of a
+  session-wide `worktree-diffs` directory shared by every dispatch, so
+  concurrent or sequential worktree runs no longer overwrite each other's
+  patches. Background (`<asyncDir>/worktree-diffs/step-<i>`) and chain
+  (`<chainDir>/worktree-diffs/step-<i>`) paths are unchanged. A relative
+  `output:` on a `worktree: true` task now resolves to the run's per-task
+  directory (`<session artifacts>/<runId>/task-<i>/` foreground,
+  `<asyncDir>/step-<i>/task-<j>/` async) instead of inside the throwaway
+  checkout, so the report survives worktree teardown and no longer pollutes
+  the captured patch; an absolute `output:` is unaffected, and `reads:` plus
+  the task's working directory still resolve inside the checkout. This is a
+  behavior change for anyone relying on the old patch/output paths, not a
+  breaking API change - no parameter, schema, or return shape changed.
+- Stale artifact directories are now pruned recursively by the artifact
+  cleanup sweep, alongside files (previously only files were pruned, since
+  `unlinkSync` throws on a directory).
+
+### Fixed
+
+- A relative `output:` that escapes its per-task directory (`../report.md`)
+  or normalizes to the directory itself (`.`) is now rejected at dispatch
+  with a tool error instead of writing outside the intended location.
+- Worktree diffs are now captured before every post-execution return
+  (normal, interrupted, detached, intercom-receipt), so the diff summary is
+  attached even when a run ends early; a patch-capture failure is now
+  surfaced in the summary instead of silently reporting an empty patch.
+
 ## [5.2.0] - 2026-09-01
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/runs/background/async-execution.ts

@@ -11,7 +11,7 @@ import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
-import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -373,7 +373,7 @@ export function executeAsyncChain(
 			...(s.model ? { model: s.model } : {}),
 		};
 	};
-	const buildSeqStep = (s: SequentialStep, sessionFile?: string, behaviorCwd?: string, progressPrecreated = false, resolvedBehavior?: ResolvedStepBehavior) => {
+	const buildSeqStep = (s: SequentialStep, sessionFile?: string, behaviorCwd?: string, progressPrecreated = false, resolvedBehavior?: ResolvedStepBehavior, isolatedLeaf?: { runDir: string; index: number }) => {
 		const a = agents.find((x) => x.name === s.agent)!;
 		const stepCwd = resolveChildCwd(runnerCwd, s.cwd);
 		const instructionCwd = behaviorCwd ?? stepCwd;
@@ -392,7 +392,16 @@ export function executeAsyncChain(
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
 		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, runnerCwd, isFirstProgressAgent);
-		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd);
+		const resolvedOutput = resolveParallelTaskOutputPath({
+			output: behavior.output,
+			ctxCwd: ctx.cwd,
+			taskCwd: instructionCwd,
+			isolated: Boolean(isolatedLeaf),
+			runDir: isolatedLeaf?.runDir,
+			index: isolatedLeaf?.index ?? 0,
+		});
+		if ("error" in resolvedOutput) throw new AsyncStartValidationError(resolvedOutput.error);
+		const outputPath = resolvedOutput.path;
 		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
 		let taskTemplate = s.task ?? "{previous}";
@@ -470,7 +479,14 @@ export function executeAsyncChain(
 								behaviorCwd = undefined;
 							}
 						}
-						return buildSeqStep(t, nextSessionFile(), behaviorCwd, progressPrecreated, parallelBehaviors[taskIndex]);
+						return buildSeqStep(
+							t,
+							nextSessionFile(),
+							behaviorCwd,
+							progressPrecreated,
+							parallelBehaviors[taskIndex],
+							s.worktree ? { runDir: path.join(asyncDir, `step-${stepIndex}`), index: taskIndex } : undefined,
+						);
 					}),
 					concurrency: s.concurrency,
 					failFast: s.failFast,

package/src/runs/foreground/subagent-executor.ts

@@ -38,7 +38,7 @@ import { createForkContextResolver } from "../../shared/fork-context.ts";
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { applyIntercomBridgeToAgent, INTERCOM_BRIDGE_MARKER, resolveIntercomBridge, resolveIntercomSessionTarget, resolveSubagentIntercomTarget, type IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
 import { formatControlIntercomMessage, formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
-import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "../../shared/utils.ts";
 import {
 	attachNestedChildrenToResultChildren,
@@ -1468,28 +1468,62 @@ function resolveParallelTaskCwd(
 function buildParallelWorktreeSuffix(
 	worktreeSetup: WorktreeSetup | undefined,
 	artifactsDir: string,
+	runId: string,
 	tasks: TaskParam[],
 ): string {
 	if (!worktreeSetup) return "";
-	const diffsDir = path.join(artifactsDir, "worktree-diffs");
+	const diffsDir = path.join(artifactsDir, runId, "worktree-diffs");
 	const diffs = diffWorktrees(worktreeSetup, tasks.map((task) => task.agent), diffsDir);
 	return formatWorktreeDiffSummary(diffs);
 }
 
+function resolveParallelTaskOutput(input: {
+	output: string | boolean | undefined;
+	task: TaskParam;
+	paramsCwd: string;
+	ctxCwd: string;
+	worktreeSetup: WorktreeSetup | undefined;
+	artifactsDir: string;
+	runId: string;
+	index: number;
+}): { path: string | undefined } | { error: string } {
+	const taskCwd = resolveParallelTaskCwd(input.task, input.paramsCwd, input.worktreeSetup, input.index);
+	return resolveParallelTaskOutputPath({
+		output: input.output,
+		ctxCwd: input.ctxCwd,
+		taskCwd,
+		isolated: Boolean(input.worktreeSetup),
+		runDir: path.join(input.artifactsDir, input.runId),
+		index: input.index,
+	});
+}
+
 function findDuplicateParallelOutputPath(input: {
 	tasks: TaskParam[];
 	behaviors: ResolvedStepBehavior[];
 	paramsCwd: string;
 	ctxCwd: string;
 	worktreeSetup?: WorktreeSetup;
+	artifactsDir: string;
+	runId: string;
 }): string | undefined {
 	const seen = new Map<string, { index: number; agent: string }>();
 	for (let index = 0; index < input.tasks.length; index++) {
 		const behavior = input.behaviors[index];
 		if (!behavior?.output) continue;
 		const task = input.tasks[index]!;
-		const taskCwd = resolveParallelTaskCwd(task, input.paramsCwd, input.worktreeSetup, index);
-		const outputPath = resolveSingleOutputPath(behavior.output, input.ctxCwd, taskCwd);
+		const resolved = resolveParallelTaskOutput({
+			output: behavior.output,
+			task,
+			paramsCwd: input.paramsCwd,
+			ctxCwd: input.ctxCwd,
+			worktreeSetup: input.worktreeSetup,
+			artifactsDir: input.artifactsDir,
+			runId: input.runId,
+			index,
+		});
+		if ("error" in resolved) return resolved.error;
+		const outputPath = resolved.path;
 		if (!outputPath) continue;
 		const previous = seen.get(outputPath);
 		if (previous) {
@@ -1511,7 +1545,17 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 		const progressInstructions = behavior
 			? buildChainInstructions({ ...behavior, output: false, reads: false }, input.paramsCwd, index === input.firstProgressIndex)
 			: { prefix: "", suffix: "" };
-		const outputPath = resolveSingleOutputPath(behavior?.output, input.ctx.cwd, taskCwd);
+		const resolvedOutput = resolveParallelTaskOutput({
+			output: behavior?.output,
+			task,
+			paramsCwd: input.paramsCwd,
+			ctxCwd: input.ctx.cwd,
+			worktreeSetup: input.worktreeSetup,
+			artifactsDir: input.artifactsDir,
+			runId: input.runId,
+			index,
+		});
+		const outputPath = "error" in resolvedOutput ? undefined : resolvedOutput.path;
 		const taskText = injectSingleOutputInstruction(
 			`${readInstructions.prefix}${input.taskTexts[index]!}${progressInstructions.suffix}`,
 			outputPath,
@@ -1799,12 +1843,23 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			paramsCwd: effectiveCwd,
 			ctxCwd: ctx.cwd,
 			worktreeSetup,
+			artifactsDir,
+			runId,
 		});
 		if (duplicateOutputError) return buildParallelModeError(duplicateOutputError);
 		for (let index = 0; index < tasks.length; index++) {
-			const taskCwd = resolveParallelTaskCwd(tasks[index]!, effectiveCwd, worktreeSetup, index);
-			const outputPath = resolveSingleOutputPath(behaviors[index]?.output, ctx.cwd, taskCwd);
-			const validationError = validateFileOnlyOutputMode(behaviors[index]?.outputMode, outputPath, `Parallel task ${index + 1} (${tasks[index]!.agent})`);
+			const resolved = resolveParallelTaskOutput({
+				output: behaviors[index]?.output,
+				task: tasks[index]!,
+				paramsCwd: effectiveCwd,
+				ctxCwd: ctx.cwd,
+				worktreeSetup,
+				artifactsDir,
+				runId,
+				index,
+			});
+			if ("error" in resolved) return buildParallelModeError(resolved.error);
+			const validationError = validateFileOnlyOutputMode(behaviors[index]?.outputMode, resolved.path, `Parallel task ${index + 1} (${tasks[index]!.agent})`);
 			if (validationError) return buildParallelModeError(validationError);
 		}
 
@@ -1871,6 +1926,9 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 		}
 
+		const worktreeSuffix = buildParallelWorktreeSuffix(worktreeSetup, artifactsDir, runId, tasks);
+		const withWorktreeSuffix = (text: string): string => (worktreeSuffix ? `${text}\n\n${worktreeSuffix}` : text);
+
 		const interrupted = results.find((result) => result.interrupted);
 		const details = compactForegroundDetails({
 			mode: "parallel",
@@ -1882,7 +1940,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		rememberForegroundRun(deps.state, { runId, mode: "parallel", cwd: effectiveCwd, results: details.results });
 		if (interrupted) {
 			return {
-				content: [{ type: "text", text: `Parallel run paused after interrupt (${interrupted.agent}). Waiting for explicit next action.` }],
+				content: [{ type: "text", text: withWorktreeSuffix(`Parallel run paused after interrupt (${interrupted.agent}). Waiting for explicit next action.`) }],
 				details,
 			};
 		}
@@ -1890,7 +1948,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		const detached = detachedIndex >= 0 ? results[detachedIndex] : undefined;
 		if (detached) {
 			return {
-				content: [{ type: "text", text: `Parallel run detached for intercom coordination (${detached.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.` }],
+				content: [{ type: "text", text: withWorktreeSuffix(`Parallel run detached for intercom coordination (${detached.agent}). Reply to the supervisor request first. After the child exits, start a fresh follow-up if needed.`) }],
 				details,
 			};
 		}
@@ -1906,12 +1964,11 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		});
 		if (intercomReceipt) {
 			return {
-				content: [{ type: "text", text: intercomReceipt.text }],
+				content: [{ type: "text", text: withWorktreeSuffix(intercomReceipt.text) }],
 				details: intercomReceipt.details,
 			};
 		}
 
-		const worktreeSuffix = buildParallelWorktreeSuffix(worktreeSetup, artifactsDir, tasks);
 		const ok = results.filter((result) => result.exitCode === 0).length;
 		const downgradeNote = backgroundRequestedWhileClarifying ? " (background requested, but clarify kept this run foreground)" : "";
 		const aggregatedOutput = aggregateParallelOutputs(
@@ -1925,9 +1982,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		);
 
 		const summary = `${ok}/${results.length} succeeded${downgradeNote}`;
-		const fullContent = worktreeSuffix
-			? `${summary}\n\n${aggregatedOutput}\n\n${worktreeSuffix}`
-			: `${summary}\n\n${aggregatedOutput}`;
+		const fullContent = withWorktreeSuffix(`${summary}\n\n${aggregatedOutput}`);
 
 		return {
 			content: [{ type: "text", text: fullContent }],

package/src/runs/shared/single-output.ts

@@ -40,6 +40,37 @@ export function resolveSingleOutputPath(
 	return path.resolve(baseCwd, output);
 }
 
+export interface ParallelTaskOutputInput {
+	output: string | boolean | undefined;
+	ctxCwd: string;
+	taskCwd?: string;
+	isolated: boolean;
+	runDir?: string;
+	index: number;
+}
+
+export type ParallelTaskOutputResult = { path: string | undefined } | { error: string };
+
+export function resolveParallelTaskOutputPath(input: ParallelTaskOutputInput): ParallelTaskOutputResult {
+	const { output, ctxCwd, taskCwd, isolated, runDir, index } = input;
+	const redirectable = isolated
+		&& Boolean(runDir)
+		&& typeof output === "string"
+		&& output.length > 0
+		&& output !== "false"
+		&& output !== "true"
+		&& !path.isAbsolute(output);
+	if (!redirectable) return { path: resolveSingleOutputPath(output, ctxCwd, taskCwd) };
+
+	const leaf = path.join(runDir!, `task-${index}`);
+	const resolved = path.resolve(leaf, output as string);
+	const relative = path.relative(leaf, resolved);
+	if (relative === "" || relative.split(path.sep)[0] === ".." || path.isAbsolute(relative)) {
+		return { error: `Parallel task ${index + 1} output '${output}' resolves outside its per-task directory (${resolved}). Use a path inside ${leaf}, or an absolute path.` };
+	}
+	return { path: resolved };
+}
+
 export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
 	if (!outputPath) return task;
 	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;

package/src/runs/shared/worktree.ts

@@ -27,6 +27,7 @@ interface WorktreeDiff {
 	insertions: number;
 	deletions: number;
 	patchPath: string;
+	captureError?: string;
 }
 
 interface WorktreeTaskCwdConflict {
@@ -523,24 +524,28 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 }
 
 export function diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir: string): WorktreeDiff[] {
+	const agentFor = (index: number): string => agents[index] ?? `task-${index + 1}`;
 	try {
 		fs.mkdirSync(diffsDir, { recursive: true });
-	} catch {
-		// Returning no diffs is safer than failing the whole command on artifact-dir issues.
-		return [];
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return setup.worktrees.map((worktree, index) => ({
+			...emptyDiff(index, agentFor(index), worktree.branch, ""),
+			captureError: `could not create patch directory '${diffsDir}': ${message}`,
+		}));
 	}
 
 	const diffs: WorktreeDiff[] = [];
 	for (let index = 0; index < setup.worktrees.length; index++) {
 		const worktree = setup.worktrees[index]!;
-		const agent = agents[index] ?? `task-${index + 1}`;
+		const agent = agentFor(index);
 		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) {
+			const message = error instanceof Error ? error.message : String(error);
 			writeEmptyPatch(patchPath);
-			diffs.push(emptyDiff(index, agent, worktree.branch, patchPath));
+			diffs.push({ ...emptyDiff(index, agent, worktree.branch, patchPath), captureError: message });
 		}
 	}
 
@@ -558,7 +563,8 @@ export function cleanupWorktrees(setup: WorktreeSetup): void {
 
 export function formatWorktreeDiffSummary(diffs: WorktreeDiff[]): string {
 	const changed = diffs.filter(hasWorktreeChanges);
-	if (changed.length === 0) return "";
+	const failed = diffs.filter((diff) => diff.captureError);
+	if (changed.length === 0 && failed.length === 0) return "";
 
 	const lines: string[] = ["=== Worktree Changes ===", ""];
 	for (const diff of changed) {
@@ -570,8 +576,11 @@ export function formatWorktreeDiffSummary(diffs: WorktreeDiff[]): string {
 		}
 		lines.push("");
 	}
+	for (const diff of failed) {
+		lines.push(`--- Task ${diff.index + 1} (${diff.agent}): patch capture FAILED: ${diff.captureError} ---`, "");
+	}
 
-	const patchesDir = path.dirname(changed[0]!.patchPath);
-	lines.push(`Full patches: ${patchesDir}`);
+	const withPatch = changed.find((diff) => diff.patchPath.length > 0);
+	if (withPatch) lines.push(`Full patches: ${path.dirname(withPatch.patchPath)}`);
 	return lines.join("\n").trimEnd();
 }

package/src/shared/artifacts.ts

@@ -60,7 +60,8 @@ export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
 		try {
 			const stat = fs.statSync(filePath);
 			if (stat.mtimeMs < cutoff) {
-				fs.unlinkSync(filePath);
+				if (stat.isDirectory()) fs.rmSync(filePath, { recursive: true, force: true });
+				else fs.unlinkSync(filePath);
 			}
 		} catch {
 			// Artifact cleanup is best-effort housekeeping. Skip files that disappear