pi-cohort 5.1.3 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # 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
+
+- `runner.log` diagnostics for the detached async runner: captures the
+  runner's stdout/stderr, spawn-time jiti revalidation, and enriched failure
+  messages that append the log's tail; the run dir is also exported to the
+  child as `PI_SUBAGENT_RUN_DIR` and echoed on an `Async dir:` start line.
+- Builtin `monitor` persona: watches an already-started job (async run dir,
+  PID, log, or probe command), reports progress deltas on a cadence, and
+  flags stalls, plus SKILL.md guidance to pair it with long-running async
+  jobs.
+
 ## [5.1.3] - 2026-08-18
 
 ### Fixed

package/README.md

@@ -101,7 +101,7 @@ Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-a
 | Term | Meaning |
 |---|---|
 | Subagent | A focused child Pi session with one job and (by default) a fresh context. |
-| Agent (persona) | A markdown file with frontmatter defining a specialist: `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `oracle`, `delegate`. Full table: [doc/agents-and-chains.md](doc/agents-and-chains.md#builtin-agents-in-plain-english). |
+| Agent (persona) | A markdown file with frontmatter defining a specialist: `scout`, `planner`, `worker`, `reviewer`, `context-builder`, `oracle`, `delegate`, `monitor`. Full table: [doc/agents-and-chains.md](doc/agents-and-chains.md#builtin-agents-in-plain-english). |
 | Chain | A saved or inline sequence of agent steps, with fan-out/fan-in support. |
 | Fresh vs. forked context | Fresh = clean slate; forked = a real branch of the parent's session history. |
 | Recursion guard | Depth cap on nested delegation so a child can only fan out if explicitly allowed. |
@@ -142,6 +142,10 @@ Optional companions:
 
 See [CHANGELOG.md](CHANGELOG.md) for shipped work in progress.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) - issues follow a Context / Problem / Idea / Acceptance Criteria template; PRs run the [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) workflow (one-liners exempt from ceremony, never from keeping docs truthful).
+
 ## Support
 
 If `pi-cohort` is useful, consider [buying me a coffee](https://buymeacoffee.com/jjurasszek).

package/agents/monitor.md

@@ -0,0 +1,26 @@
+---
+name: monitor
+description: Watches a job you already started - not for doing the work. Reports progress deltas on a cadence, flags stalls, exits when the job ends.
+tools: read, bash
+thinking: low
+completionGuard: false
+---
+
+You observe a job someone else runs. Never execute, restart, or modify it.
+
+The task names your target: an absolute async run dir (preferred - read its status.json, tail output logs and runner.log), a PID (POSIX: ps -p <pid>; Windows: tasklist /FI "PID eq <pid>"), a log file (tail), or a probe command. If the target is already terminated at your first check, report that and exit. If it is unreadable, report "cannot observe target: <reason>" and exit - never guess, never loop.
+
+Write your trail to $PI_SUBAGENT_RUN_DIR/trail.md. If that variable is unset, create a directory with mktemp -d and write there. Never write under the workspace.
+
+Loop:
+1. Record your start time. Run the first check immediately, before any sleep.
+2. Each cycle: check the target is alive, collect progress (new log lines, counts, phases, best-effort ETA), and compose a one-line delta vs the previous cycle.
+3. Append the delta with a timestamp to the trail.
+4. If contact_supervisor is available, send the delta with reason "progress_update".
+5. Sleep the cadence interval in chunks of <= 5 minutes, then repeat.
+
+Cadence: every 15 minutes unless the task sets another interval.
+
+Stall: no growth in the watched log and no change in status.json lastUpdate since the previous cycle. Judge stall only by the signals your target has; a signal that does not exist never counts as change. Report it as "no output for <interval>, possible stall". After two consecutive silent cycles, escalate with contact_supervisor reason "need_decision". Never report "still working" without evidence.
+
+Exit: when the target reaches a terminal state, send a final summary and end - the summary is your run result. Stop 24h after your recorded start time even if the target lives. Without contact_supervisor, the trail and final summary are the record; behave identically otherwise.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "5.1.3",
+  "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/skills/pi-cohort/SKILL.md

@@ -351,6 +351,19 @@ subagent({ action: "doctor" })
 
 Humans can use `/cohort-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
 
+Long-running job hygiene:
+
+- The job's task must instruct it to emit observable progress as it works (log lines, counts, phase names; best-effort ETA). A silent long job is a defect.
+- Pair the job with a monitor dispatch, giving it the absolute async dir from the `Async dir:` line of the start message:
+
+```typescript
+subagent({ agent: "worker", async: true, task: "<long job - emit progress lines as you work>" })
+  -> Async: worker [R]  Async dir: <D>
+subagent({ agent: "monitor", async: true, task: "Watch async run R at <D>. Report every 15m. Stop when it ends." })
+```
+
+- Live 15m reports require the pi-intercom bridge; without it the monitor's trail and final summary are post-hoc records.
+
 ### Subagent control
 
 Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck.

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";
@@ -88,7 +88,20 @@ function resolveJitiCliPath(): string | undefined {
 	return undefined;
 }
 
-const jitiCliPath = resolveJitiCliPath();
+export function createJitiCliResolver(deps: { resolve?: () => string | undefined; exists?: (p: string) => boolean } = {}): () => string | undefined {
+	const resolve = deps.resolve ?? resolveJitiCliPath;
+	const exists = deps.exists ?? ((p: string) => fs.existsSync(p));
+	let cached = resolve();
+	return () => {
+		if (cached && exists(cached)) return cached;
+		cached = resolve();
+		if (cached && exists(cached)) return cached;
+		cached = undefined;
+		return undefined;
+	};
+}
+
+const ensureJitiCliPath = createJitiCliResolver();
 
 interface AsyncExecutionContext {
 	pi: ExtensionAPI;
@@ -172,13 +185,60 @@ export function formatAsyncStartedMessage(headline: string): string {
  * Check if jiti is available for async execution
  */
 export function isAsyncAvailable(): boolean {
-	return jitiCliPath !== undefined;
+	return ensureJitiCliPath() !== undefined;
+}
+
+/**
+ * Spawn a detached process with stderr/stdout captured to <asyncDir>/runner.log.
+ * Falls back to ignored stdio if the log file cannot be opened; the parent always
+ * closes its copy of the fd, on every exit path.
+ */
+export function spawnDetachedWithLog(command: string, args: string[], cwd: string, asyncDir: string, spawnImpl: typeof spawn = spawn): { pid?: number; error?: string } {
+	let fd: number | undefined;
+	try {
+		try {
+			fd = fs.openSync(path.join(asyncDir, "runner.log"), "a");
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(`[pi-cohort] could not open runner.log in ${asyncDir}: ${message}`);
+		}
+		const proc = spawnImpl(command, args, {
+			cwd,
+			detached: true,
+			stdio: fd === undefined ? "ignore" : ["ignore", fd, fd],
+			windowsHide: true,
+		});
+		proc.on("error", (error) => {
+			console.error(`[pi-cohort] async spawn failed: ${error.message}`);
+		});
+		if (typeof proc.pid !== "number") {
+			return { error: `async runner did not produce a pid for cwd: ${cwd}` };
+		}
+		proc.unref();
+		return { pid: proc.pid };
+	} finally {
+		if (fd !== undefined) {
+			try {
+				fs.closeSync(fd);
+			} catch {
+				// parent-side close failure never misreports a launched child
+			}
+		}
+	}
 }
 
 /**
  * Spawn the async runner process
  */
-function spawnRunner(cfg: object, suffix: string, cwd: string): { pid?: number; error?: string } {
+export function spawnRunner(
+	cfg: object,
+	suffix: string,
+	cwd: string,
+	asyncDir: string,
+	deps: { ensureJiti?: () => string | undefined; spawnImpl?: typeof spawn } = {},
+): { pid?: number; error?: string } {
+	const ensureJiti = deps.ensureJiti ?? ensureJitiCliPath;
+	const jitiCliPath = ensureJiti();
 	if (!jitiCliPath) {
 		return { error: "upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed" };
 	}
@@ -197,20 +257,15 @@ function spawnRunner(cfg: object, suffix: string, cwd: string): { pid?: number;
 	fs.writeFileSync(cfgPath, JSON.stringify(cfg));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
 
-	const proc = spawn(process.execPath, [jitiCliPath, runner, cfgPath], {
-		cwd,
-		detached: true,
-		stdio: "ignore",
-		windowsHide: true,
-	});
-	proc.on("error", (error) => {
-		console.error(`[pi-cohort] async spawn failed: ${error.message}`);
-	});
-	if (typeof proc.pid !== "number") {
-		return { error: `async runner did not produce a pid for cwd: ${cwd}` };
-	}
-	proc.unref();
-	return { pid: proc.pid };
+	return spawnDetachedWithLog(process.execPath, [jitiCliPath, runner, cfgPath], cwd, asyncDir, deps.spawnImpl ?? spawn);
+}
+
+/**
+ * Build the headline shown at the top of an async start message, e.g.
+ * "Async single: my-agent [run-id]\nAsync dir: /tmp/...".
+ */
+export function asyncStartHeadline(prefix: string, id: string, asyncDir: string): string {
+	return `${prefix} [${id}]\nAsync dir: ${asyncDir}`;
 }
 
 function formatAsyncStartError(mode: SubagentRunMode, message: string): AsyncExecutionResult {
@@ -318,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;
@@ -337,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}";
@@ -415,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,
@@ -503,6 +574,7 @@ export function executeAsyncChain(
 			},
 			id,
 			runnerCwd,
+			asyncDir,
 		);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -603,7 +675,7 @@ export function executeAsyncChain(
 		.join(" -> ");
 
 	return {
-		content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`) }],
+		content: [{ type: "text", text: formatAsyncStartedMessage(asyncStartHeadline(`Async ${resultMode}: ${chainDesc}`, id, asyncDir)) }],
 		details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir, workflowGraph },
 	};
 }
@@ -738,6 +810,7 @@ export function executeAsyncSingle(
 			},
 			id,
 			runnerCwd,
+			asyncDir,
 		);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -796,7 +869,7 @@ export function executeAsyncSingle(
 	}
 
 	return {
-		content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`) }],
+		content: [{ type: "text", text: formatAsyncStartedMessage(asyncStartHeadline(`Async: ${agent}`, id, asyncDir)) }],
 		details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir },
 	};
 }

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

@@ -7,7 +7,7 @@ import { readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
-import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { readRunnerLogTail, reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
 
 interface AsyncRunStepSummary {
 	index: number;
@@ -64,6 +64,7 @@ export interface AsyncRunSummary {
 	sessionFile?: string;
 	nestedChildren?: NestedRunSummary[];
 	nestedWarnings?: string[];
+	diagnostic?: string;
 }
 
 interface AsyncRunListOptions {
@@ -218,6 +219,29 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 	});
 }
 
+const PRE_STATUS_CRASH_GRACE_MS = 10_000;
+
+function summarizePreStatusCrash(asyncDir: string, now: number): AsyncRunSummary | undefined {
+	const log = readRunnerLogTail(asyncDir);
+	if (!log.tail) return undefined;
+	let startedAt: number;
+	try {
+		startedAt = fs.statSync(asyncDir).mtimeMs;
+	} catch {
+		return undefined;
+	}
+	if (now - startedAt < PRE_STATUS_CRASH_GRACE_MS) return undefined;
+	return {
+		id: path.basename(asyncDir),
+		asyncDir,
+		state: "failed",
+		mode: "single",
+		startedAt,
+		steps: [],
+		diagnostic: `Runner log tail (${log.path}):\n${log.tail}`,
+	};
+}
+
 export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
 	let entries: string[];
 	try {
@@ -237,7 +261,11 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			? undefined
 			: reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		const status = (reconciliation?.status ?? readStatus(asyncDir)) as (AsyncStatus & { cwd?: string }) | null;
-		if (!status) continue;
+		if (!status) {
+			const crashed = summarizePreStatusCrash(asyncDir, options.now?.() ?? Date.now());
+			if (crashed && (!allowedStates || allowedStates.has(crashed.state))) runs.push(crashed);
+			continue;
+		}
 		const nestedWarnings: string[] = [];
 		try {
 			const nestedRoute = findNestedRouteForRootId(status.runId || path.basename(asyncDir));
@@ -329,6 +357,7 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
 		const outputPath = formatAsyncRunOutputPath(run);
 		if (outputPath) lines.push(`  output: ${shortenPath(outputPath)}`);
 		if (run.sessionFile) lines.push(`  session: ${shortenPath(run.sessionFile)}`);
+		if (run.diagnostic) for (const diagLine of run.diagnostic.split("\n")) lines.push(`  ${diagLine}`);
 		lines.push("");
 	}
 	return lines.join("\n").trimEnd();

package/src/runs/background/run-status.ts

@@ -10,7 +10,7 @@ import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts
 import { resolveAsyncRunLocation } from "./async-resume.ts";
 import { resolveSubagentRunId } from "./run-id-resolver.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
-import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { readRunnerLogTail, reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
 import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 
 interface RunStatusParams {
@@ -238,6 +238,8 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			}
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+			const runnerLogPath = path.join(asyncDir, "runner.log");
+			if (fs.existsSync(runnerLogPath)) lines.push(`Runner log: ${runnerLogPath}`);
 
 			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
 		}
@@ -264,6 +266,18 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 		}
 	}
 
+	if (asyncDir) {
+		const log = readRunnerLogTail(asyncDir);
+		const text = log.tail
+			? `Status file not found.\nRunner log tail (${log.path}):\n${log.tail}`
+			: `Status file not found.\nRunner log (empty or missing): expected at ${log.path}`;
+		return {
+			content: [{ type: "text", text }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
 	return {
 		content: [{ type: "text", text: "Status file not found." }],
 		isError: true,

package/src/runs/background/stale-run-reconciler.ts

@@ -164,10 +164,35 @@ function buildStartedStatus(asyncDir: string, startedRun: StartedRunMetadata, no
 	};
 }
 
+export function readRunnerLogTail(asyncDir: string, maxBytes = 4096, maxLines = 20): { path: string; tail?: string } {
+	const logPath = path.join(asyncDir, "runner.log");
+	try {
+		const stat = fs.statSync(logPath);
+		if (stat.size === 0) return { path: logPath };
+		const fd = fs.openSync(logPath, "r");
+		try {
+			const length = Math.min(stat.size, maxBytes);
+			const buffer = Buffer.alloc(length);
+			fs.readSync(fd, buffer, 0, length, Math.max(0, stat.size - maxBytes));
+			const lines = buffer.toString("utf-8").split("\n").filter((line) => line.trim() !== "");
+			const tail = lines.slice(-maxLines).join("\n");
+			return tail ? { path: logPath, tail } : { path: logPath };
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch {
+		return { path: logPath };
+	}
+}
+
 function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, reason?: string): { status: AsyncStatus; result: object; message: string } {
 	const runId = status.runId || path.basename(asyncDir);
 	const pid = typeof status.pid === "number" ? status.pid : "unknown";
 	const message = reason ?? `Async runner process ${pid} exited or disappeared before writing a result. Marked run failed by stale-run reconciliation.`;
+	const log = readRunnerLogTail(asyncDir);
+	const enrichedMessage = log.tail
+		? `${message}\nRunner log tail (${log.path}):\n${log.tail}`
+		: `${message}\nRunner log (empty or missing): expected at ${log.path}`;
 	const steps = status.steps?.length ? status.steps : [{ agent: "subagent", status: "running" as const }];
 	const repairedSteps = steps.map((step) => step.status === "running" || step.status === "pending"
 		? {
@@ -177,7 +202,7 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
 			endedAt: step.endedAt ?? now,
 			durationMs: step.startedAt !== undefined && step.durationMs === undefined ? Math.max(0, now - step.startedAt) : step.durationMs,
 			exitCode: step.exitCode ?? 1,
-			error: step.error ?? message,
+			error: step.error ?? enrichedMessage,
 		}
 		: step);
 	const repairedStatus: AsyncStatus = {
@@ -191,18 +216,18 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
 	const resultAgent = repairedSteps[status.currentStep ?? 0]?.agent ?? repairedSteps[0]?.agent ?? "subagent";
 	return {
 		status: repairedStatus,
-		message,
+		message: enrichedMessage,
 		result: {
 			id: runId,
 			agent: resultAgent,
 			mode: status.mode,
 			success: false,
 			state: "failed",
-			summary: message,
+			summary: enrichedMessage,
 			results: repairedSteps.map((step) => ({
 				agent: step.agent,
-				output: step.status === "complete" || step.status === "completed" ? "" : message,
-				error: step.status === "complete" || step.status === "completed" ? undefined : step.error ?? message,
+				output: step.status === "complete" || step.status === "completed" ? "" : enrichedMessage,
+				error: step.status === "complete" || step.status === "completed" ? undefined : step.error ?? enrichedMessage,
 				success: step.status === "complete" || step.status === "completed",
 				model: step.model,
 				attemptedModels: step.attemptedModels,

package/src/runs/background/subagent-runner.ts

@@ -44,7 +44,7 @@ import {
 	aggregateParallelOutputs,
 	MAX_PARALLEL_CONCURRENCY,
 } from "../shared/parallel-utils.ts";
-import { buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
+import { buildPiArgs, cleanupTempDir, runDirEnv } from "../shared/pi-args.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
 import { createStructuredOutputRuntime, readStructuredOutput } from "../shared/structured-output.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
@@ -967,6 +967,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	const overallStartTime = Date.now();
 	const shareEnabled = config.share === true;
 	const asyncDir = config.asyncDir;
+	Object.assign(process.env, runDirEnv(asyncDir));
 	const statusPath = path.join(asyncDir, "status.json");
 	const eventsPath = path.join(asyncDir, "events.jsonl");
 	const logPath = path.join(asyncDir, `subagent-log-${id}.md`);

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/pi-args.ts

@@ -13,6 +13,7 @@ const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.
 export const SUBAGENT_CHILD_ENV = "PI_SUBAGENT_CHILD";
 export const SUBAGENT_ORCHESTRATOR_TARGET_ENV = "PI_SUBAGENT_ORCHESTRATOR_TARGET";
 export const SUBAGENT_RUN_ID_ENV = "PI_SUBAGENT_RUN_ID";
+export const SUBAGENT_RUN_DIR_ENV = "PI_SUBAGENT_RUN_DIR";
 export const SUBAGENT_CHILD_AGENT_ENV = "PI_SUBAGENT_CHILD_AGENT";
 export const SUBAGENT_CHILD_INDEX_ENV = "PI_SUBAGENT_CHILD_INDEX";
 export const SUBAGENT_FANOUT_CHILD_ENV = "PI_SUBAGENT_FANOUT_CHILD";
@@ -68,6 +69,10 @@ interface BuildPiArgsResult {
 	tempDir?: string;
 }
 
+export function runDirEnv(asyncDir: string): Record<string, string> {
+	return { [SUBAGENT_RUN_DIR_ENV]: asyncDir };
+}
+
 export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
 	if (!model || !thinking || thinking === "off") return model;
 	const colonIdx = model.lastIndexOf(":");

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