pi-crew 0.9.53 → 0.9.55

package/src/runtime/retry-runner.ts

@@ -0,0 +1,336 @@
+/**
+ * RetryRunner - Execute tasks with retry support and summary accumulation.
+ *
+ * Based on pi-boomerang's --rethrow pattern:
+ * - Retries failed tasks up to maxAttempts
+ * - Generates handoffs between attempts
+ * - Accumulates context from previous attempts
+ * - Supports exponential backoff
+ * - Limits handoff accumulation to prevent memory leaks
+ *
+ * @see docs/pi-boomerang-integration-plan.md
+ */
+
+import type { HandoffManager, HandoffSummary, TaskPacket, TaskResult } from "./handoff-manager.ts";
+
+/**
+ * Retry configuration.
+ */
+export interface RetryConfig {
+	/** Maximum number of retry attempts */
+	maxAttempts: number;
+	/** Generate summary between attempts for context accumulation */
+	summaryBetweenAttempts?: boolean;
+	/** Stop retrying if task succeeds */
+	stopOnSuccess?: boolean;
+	/** Base backoff delay in milliseconds (multiplied by attempt number) */
+	backoffMs?: number;
+	/** Backoff multiplier (default: 1) */
+	backoffMultiplier?: number;
+	/** Maximum backoff delay cap in milliseconds */
+	maxBackoffMs?: number;
+	/** Custom retry condition (return true to retry) */
+	retryCondition?: (result: TaskResult, attempt: number) => boolean;
+	/** Maximum handoffs to retain (default: 100) - prevents memory leaks */
+	maxHandoffs?: number;
+}
+
+/**
+ * Result of a single attempt.
+ */
+export interface AttemptResult {
+	attempt: number;
+	result: TaskResult;
+	summary?: HandoffSummary;
+	duration: number;
+	error?: string;
+	timestamp: number;
+}
+
+/**
+ * Final retry result.
+ */
+export interface RetryResult {
+	success: boolean;
+	attempts: AttemptResult[];
+	finalResult?: TaskResult;
+	totalHandoffs: HandoffSummary[];
+	totalDuration: number;
+}
+
+/**
+ * Task runner interface (minimal for retry functionality).
+ */
+export interface TaskRunnerLike {
+	runTask(packet: TaskPacket): Promise<TaskResult>;
+}
+
+/**
+ * RetryRunner handles task execution with automatic retry and summary accumulation.
+ */
+export class RetryRunner {
+	private _disposed = false;
+
+	private taskRunner: TaskRunnerLike;
+	private handoffManager: HandoffManager;
+	private _handoffs: HandoffSummary[] = [];
+
+	constructor(taskRunner: TaskRunnerLike, handoffManager: HandoffManager) {
+		this.taskRunner = taskRunner;
+		this.handoffManager = handoffManager;
+	}
+
+	/**
+	 * Check if this runner has been disposed.
+	 */
+	get isDisposed(): boolean {
+		return this._disposed;
+	}
+
+	/**
+	 * Dispose of resources held by this runner.
+	 * Clears any accumulated state and prevents further operations.
+	 */
+	dispose(): void {
+		this._disposed = true;
+	}
+
+	/**
+	 * Clear accumulated handoffs to free memory.
+	 * Useful when you want to reset state without disposing.
+	 */
+	clearHandoffs(): void {
+		this._handoffs = [];
+	}
+
+	/**
+	 * Get the effective max handoffs limit from config or default.
+	 */
+	private getMaxHandoffs(config: RetryConfig): number {
+		return config.maxHandoffs ?? 100;
+	}
+
+	/**
+	 * Trim handoffs array to max size, keeping most recent.
+	 */
+	private trimHandoffs(handoffs: HandoffSummary[], maxSize: number): HandoffSummary[] {
+		if (handoffs.length <= maxSize) {
+			return handoffs;
+		}
+		// Keep the most recent handoffs (last maxSize items)
+		return handoffs.slice(-maxSize);
+	}
+
+	/**
+	 * Execute task with retry support.
+	 * Summaries accumulate between attempts for better context.
+	 *
+	 * @param packet - Task packet to execute
+	 * @param config - Retry configuration (stopOnSuccess defaults to true)
+	 * @returns Final retry result with all attempts
+	 */
+	async runWithRetry(packet: TaskPacket, config: RetryConfig): Promise<RetryResult> {
+		if (this._disposed) {
+			throw new Error("RetryRunner has been disposed");
+		}
+
+		const attempts: AttemptResult[] = [];
+		const handoffs: HandoffSummary[] = [];
+		const startTime = Date.now();
+		const maxHandoffs = this.getMaxHandoffs(config);
+
+		// Clear previous handoffs at start of each retry run
+		this._handoffs = [];
+
+		for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+			if (this._disposed) {
+				throw new Error("RetryRunner was disposed during retry");
+			}
+			const attemptStart = Date.now();
+
+			try {
+				// Inject accumulated handoffs into context
+				const enrichedPacket = this.enrichPacketWithHandoffs(packet, handoffs, attempt);
+
+				// Execute task
+				const result = await this.taskRunner.runTask(enrichedPacket);
+
+				const attemptResult: AttemptResult = {
+					attempt,
+					result,
+					duration: Date.now() - attemptStart,
+					timestamp: Date.now(),
+				};
+
+				// Generate summary between attempts
+				if (config.summaryBetweenAttempts !== false) {
+					const summary = await this.handoffManager.generateSummary(packet, result);
+					attemptResult.summary = summary;
+					handoffs.push(summary);
+
+					// Trim handoffs to prevent memory leak
+					if (handoffs.length > maxHandoffs) {
+						handoffs.splice(0, handoffs.length - maxHandoffs);
+					}
+				}
+
+				attempts.push(attemptResult);
+
+				// Stop on success if configured (default to true when undefined)
+				if ((config.stopOnSuccess ?? true) && result.outcome === "success") {
+					return {
+						success: true,
+						attempts,
+						finalResult: result,
+						totalHandoffs: handoffs,
+						totalDuration: Date.now() - startTime,
+					};
+				}
+
+				// Check custom retry condition
+				if (config.retryCondition && !config.retryCondition(result, attempt)) {
+					break;
+				}
+
+				// Check default retry condition (retry on failure)
+				if (result.outcome !== "success" && attempt < config.maxAttempts) {
+					// Apply backoff before retry
+					const backoffDelay = this.calculateBackoff(
+						config.backoffMs ?? 1000,
+						attempt,
+						config.backoffMultiplier ?? 1,
+						config.maxBackoffMs,
+					);
+					if (backoffDelay > 0) {
+						await this.sleep(backoffDelay);
+					}
+				}
+			} catch (error) {
+				attempts.push({
+					attempt,
+					result: {
+						outcome: "failure",
+						error: error instanceof Error ? error.message : String(error),
+					},
+					duration: Date.now() - attemptStart,
+					timestamp: Date.now(),
+					error: error instanceof Error ? error.message : String(error),
+				});
+
+				// Apply backoff before retry on error
+				if (config.backoffMs && attempt < config.maxAttempts) {
+					const backoffDelay = this.calculateBackoff(
+						config.backoffMs,
+						attempt,
+						config.backoffMultiplier ?? 1,
+						config.maxBackoffMs,
+					);
+					if (backoffDelay > 0) {
+						await this.sleep(backoffDelay);
+					}
+				}
+			}
+		}
+
+		const finalAttempt = attempts[attempts.length - 1];
+		return {
+			success: finalAttempt?.result.outcome === "success",
+			attempts,
+			finalResult: finalAttempt?.result,
+			totalHandoffs: this.trimHandoffs(handoffs, maxHandoffs),
+			totalDuration: Date.now() - startTime,
+		};
+	}
+
+	/**
+	 * Enrich packet with accumulated handoffs from previous attempts.
+	 */
+	private enrichPacketWithHandoffs(packet: TaskPacket, handoffs: HandoffSummary[], attempt: number): TaskPacket {
+		if (handoffs.length === 0) {
+			return packet;
+		}
+
+		// Build accumulated context from previous attempts
+		const accumulatedContext = handoffs
+			.map(
+				(h, index) =>
+					`## Attempt ${index + 1}: ${h.task}\n` +
+					`Outcome: ${h.outcome}\n` +
+					`Files: created=${h.filesCreated.join(", ")}, modified=${h.filesModified.join(", ")}\n` +
+					`Decisions: ${h.decisions.map((d) => d.rationale).join("; ")}\n` +
+					`Blockers: ${h.blockers.join(", ")}\n` +
+					`Next Steps: ${h.nextSteps.join(", ")}\n`,
+			)
+			.join("\n---\n");
+
+		return {
+			...packet,
+			context: {
+				...packet.context,
+				__boomerangAttempts: attempt,
+				__boomerangHandoffs: handoffs,
+				__boomerangContext: `Previous attempts summary:\n${accumulatedContext}`,
+			},
+		};
+	}
+
+	/**
+	 * Calculate backoff delay with optional capping.
+	 */
+	private calculateBackoff(baseMs: number, attempt: number, multiplier: number, maxBackoffMs?: number): number {
+		let delay = baseMs * multiplier ** (attempt - 1);
+		if (maxBackoffMs !== undefined) {
+			delay = Math.min(delay, maxBackoffMs);
+		}
+		return delay;
+	}
+
+	/**
+	 * Sleep helper.
+	 */
+	private sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+}
+
+/**
+ * Create a RetryRunner with default dependencies.
+ */
+export function createRetryRunner(taskRunner: TaskRunnerLike, handoffManager: HandoffManager): RetryRunner {
+	return new RetryRunner(taskRunner, handoffManager);
+}
+
+/**
+ * Default retry config for common scenarios.
+ */
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 3,
+	summaryBetweenAttempts: true,
+	stopOnSuccess: true,
+	backoffMs: 1000,
+	backoffMultiplier: 2,
+	maxBackoffMs: 30000,
+};
+
+/**
+ * Retry config for transient failures (quick retries).
+ */
+export const TRANSIENT_FAILURE_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 2,
+	summaryBetweenAttempts: false,
+	stopOnSuccess: true,
+	backoffMs: 500,
+	backoffMultiplier: 1,
+};
+
+/**
+ * Retry config for persistent failures (exponential backoff).
+ */
+export const PERSISTENT_FAILURE_RETRY_CONFIG: RetryConfig = {
+	maxAttempts: 5,
+	summaryBetweenAttempts: true,
+	stopOnSuccess: true,
+	backoffMs: 2000,
+	backoffMultiplier: 2,
+	maxBackoffMs: 60000,
+};

package/src/runtime/role-permission.ts

@@ -0,0 +1,59 @@
+export type RolePermissionMode = "read_only" | "workspace_write" | "danger_full_access" | "explicit_confirm";
+
+// (FIND-12 R1 review: the AgentPermissionOptions opt-in was dropped — no caller
+// passed `options` and AgentConfig has no `permissions` field, so it was dead
+// code. Custom write-capable roles must instead be added to WRITE_ROLES below.)
+
+// Read-only roles: cannot mutate files/source. `verifier` is NOT here — it runs
+// tests (bash + cache writes) so it is a WRITE role (F4). `planner` stays
+// read-only to preserve the plan-approval gate boundary (F3).
+const READ_ONLY_ROLES = new Set(["explorer", "reviewer", "security-reviewer", "analyst", "critic", "planner"]);
+// Write-capable roles: can mutate files/source within the workspace.
+// FIND-12 (R1 review): this is an EXPLICIT allowlist — every shipped write-capable
+// role must be listed here, otherwise default-deny demotes it to read-only.
+// `agent` is the default direct-agent role (run.ts); `cold-verifier` runs bash/
+// cache writes; `chain-executor` is the chain-workflow executor variant;
+// `worker` is the autonomous goal-loop + dynamic-workflow executor role
+// (goal-loop-runner.ts, run.ts dynamic workflow synthesis).
+const WRITE_ROLES = new Set(["executor", "test-engineer", "writer", "verifier", "agent", "cold-verifier", "chain-executor", "worker"]);
+export interface PermissionCheckResult {
+	allowed: boolean;
+	mode: RolePermissionMode;
+	reason?: string;
+}
+
+/**
+ * Resolve the permission mode for a given role.
+ *
+ * FIND-12 (2026-07-20): **default-deny** — unknown/unrecognized roles now
+ * receive `"read_only"` instead of the previous permissive `"workspace_write"`.
+ * This prevents privilege escalation via typo'd or custom agent names that
+ * accidentally inherit write capabilities. Write-capable roles are an EXPLICIT
+ * allowlist (`WRITE_ROLES`); to add a custom write-capable role, add it there.
+ * (R1 review: a per-agent-config `permissions.workspaceWrite` opt-in was
+ * considered but dropped — it was unreachable from all 8 call sites.)
+ *
+ * @param role the role name (case-sensitive, must match exactly)
+ */
+export function permissionForRole(role: string): RolePermissionMode {
+	if (READ_ONLY_ROLES.has(role)) return "read_only";
+	if (WRITE_ROLES.has(role)) return "workspace_write";
+	// FIND-12: default-deny for unknown/unrecognized roles.
+	return "read_only";
+}
+
+export function currentCrewRole(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	return env.PI_CREW_ROLE?.trim() || env.PI_TEAMS_ROLE?.trim() || undefined;
+}
+
+export function checkSubagentSpawnPermission(role: string | undefined): PermissionCheckResult {
+	if (!role) return { allowed: true, mode: "workspace_write" };
+	const mode = permissionForRole(role);
+	if (mode === "read_only")
+		return {
+			allowed: false,
+			mode,
+			reason: `Role '${role}' is read-only and cannot spawn additional subagents.`,
+		};
+	return { allowed: true, mode };
+}

package/src/runtime/run-coalesced-task-group.ts

@@ -0,0 +1,308 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendEventAsync } from "../state/event-log.ts";
+import { saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { DEFAULT_RETRY_POLICY, executeWithRetry } from "./retry-executor.ts";
+import { permissionForRole } from "./role-permission.ts";
+import { runWorker } from "./run-worker.ts";
+import type { CrewRuntimeMode } from "./runtime-resolver.ts";
+import { sanitizeTaskText } from "./task-packet.ts";
+import { splitCoalescedOutput } from "./task-runner/output-splitter.ts";
+import { mergeArtifacts } from "./team-runner-artifacts.ts";
+import { createWorkerHeartbeat, touchWorkerHeartbeat } from "./worker-heartbeat.ts";
+import { buildWorkspaceTree } from "./workspace-tree.ts";
+
+export interface CoalescedTaskGroupInput {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	groupTasks: TeamTaskState[];
+	step: WorkflowStep;
+	agent: AgentConfig;
+	signal?: AbortSignal;
+	executeWorkers: boolean;
+	runtimeKind?: CrewRuntimeMode;
+	workspaceId: string;
+	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
+	teamRole?: unknown;
+	perTaskRuntime?: CrewRuntimeMode;
+}
+
+export interface CoalescedTaskGroupResult {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	taskIds: string[];
+	rawOutput: string;
+	success: boolean;
+}
+
+export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Promise<CoalescedTaskGroupResult> {
+	const { manifest, groupTasks, step, agent, signal, executeWorkers } = input;
+	const groupId = groupTasks.map((t) => t.id).join("+");
+	const firstTask = groupTasks[0]!;
+	const taskIds = groupTasks.map((t) => t.id);
+
+	// Set ALL N tasks to "running" before spawn so the dashboard reflects
+	// the in-flight state.
+	let updatedTasks: TeamTaskState[] = input.tasks.map((t) => {
+		if (taskIds.includes(t.id) && t.status !== "running") {
+			return { ...t, status: "running" as const, startedAt: new Date().toISOString() };
+		}
+		return t;
+	});
+	await saveRunTasksAsync(manifest, updatedTasks);
+	await appendEventAsync(manifest.eventsPath, {
+		type: "task.coalesced_dispatch_start",
+		runId: manifest.runId,
+		message: `Dispatching ${groupTasks.length} coalesced tasks in 1 worker (role=${firstTask.role}, cwd=${firstTask.cwd})`,
+		data: { groupId, role: firstTask.role, cwd: firstTask.cwd, taskIds },
+	});
+
+	const combinedPrompt = await buildCoalescedPrompt(manifest, step, groupTasks, agent);
+
+	// FIX (M6): write heartbeats for ALL N tasks in the coalesced group so the
+	// background watcher doesn't fire heartbeat_dead against the (single)
+	// child pi worker. Previously runCoalescedTaskGroup never wrote heartbeats,
+	// so the watcher saw `heartbeat.lastSeenAt: undefined` within 2 seconds of
+	// spawn and emitted heartbeat_dead even though the worker continued to
+	// completion (false-positive stuck-worker alarms). The singleton path
+	// (runTeamTask) writes heartbeats via persistHeartbeat — M6 needs the
+	// equivalent to avoid the false-positive.
+	updatedTasks = updatedTasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t;
+		return {
+			...t,
+			heartbeat: t.heartbeat ?? createWorkerHeartbeat(t.id),
+		};
+	});
+	await saveRunTasksAsync(manifest, updatedTasks);
+
+	let rawOutput = "";
+	let success = false;
+	// FIND-06: serialize heartbeat saves and retain the active save so terminal
+	// results can drain it before their final write.
+	let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	let heartbeatInFlight = false;
+	let heartbeatPromise: Promise<void> | null = null;
+	// FIND-06 P1 fix (R1 review): a heartbeat save that exceeds the 5s drain
+	// timeout continues in the background and can rename its temp file AFTER
+	// the terminal write, clobbering terminal state with the pre-terminal
+	// snapshot. finalWriteStarted lets the IIFE repair that by re-writing the
+	// (now-terminal) updatedTasks AFTER its own save resolves, so the terminal
+	// state always lands last regardless of disk timing.
+	let finalWriteStarted = false;
+	if (!executeWorkers) {
+		rawOutput = buildScaffoldOutput(groupTasks);
+		success = true;
+	} else {
+		// Heartbeat refresher: touch every task's heartbeat every 15s while the
+		// worker is alive. Set `alive: true` explicitly so post-completion
+		// staleness checks immediately recognize liveness.
+		heartbeatTimer = setInterval(() => {
+			// FIND-06: setInterval does not await async callbacks. Do not start a
+			// second read/modify/write while the preceding heartbeat save is active.
+			if (heartbeatInFlight) return;
+			heartbeatInFlight = true;
+			heartbeatPromise = (async () => {
+				try {
+					updatedTasks = updatedTasks.map((t) => {
+						if (!taskIds.includes(t.id)) return t;
+						// FIND-06 belt-and-suspenders: never replace terminal state or its
+						// resultArtifact with a heartbeat-only snapshot.
+						if (t.status === "completed" || t.status === "failed") return t;
+						return {
+							...t,
+							heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
+						};
+					});
+					await saveRunTasksAsync(manifest, updatedTasks);
+				} catch {
+					// Run may have been pruned mid-dispatch — best-effort only.
+				} finally {
+					heartbeatInFlight = false;
+					// FIND-06 P1 fix: if the terminal write started while our heartbeat
+					// save was in flight, re-write the (now-terminal) updatedTasks so
+					// our late snapshot cannot leave stale pre-terminal state on disk.
+					// Runs after our own save resolves, so it always lands last.
+					if (finalWriteStarted) {
+						try {
+							await saveRunTasksAsync(manifest, updatedTasks);
+						} catch {
+							// best-effort repair — same swallow policy as the heartbeat.
+						}
+					}
+				}
+			})();
+		}, 15_000);
+		try {
+			const result = await executeWithRetry(
+				async () => {
+					return await runWorker({
+						cwd: firstTask.cwd,
+						task: combinedPrompt,
+						agent,
+						signal,
+						excludeContextBash: true,
+						maxTurns: 5,
+						onJsonEvent: (e) => input.onJsonEvent?.(firstTask.id, manifest.runId, e),
+					});
+				},
+				DEFAULT_RETRY_POLICY,
+				{ signal },
+			);
+			rawOutput = result.rawFinalText ?? result.stdout ?? "";
+			success = result.exitStatus?.exitCode === 0;
+		} catch (err) {
+			rawOutput = `Worker dispatch failed: ${err instanceof Error ? err.message : String(err)}`;
+			success = false;
+		} finally {
+			if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
+		}
+	}
+
+	const split = splitCoalescedOutput(rawOutput, taskIds);
+
+	const finishedAt = new Date().toISOString();
+	const newArtifacts: TeamRunManifest["artifacts"] = [];
+	updatedTasks = updatedTasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t;
+		const entry = split.find((s) => s.taskId === t.id);
+		const ok = success && Boolean(entry?.text);
+		const text = entry?.text ?? rawOutput;
+		// BUGFIX (M6 real dispatch): write to artifactsRoot via writeArtifact
+		// so task.resultArtifact is set and aggregateTaskOutputs can read
+		// the per-task text. Previously the coalesced path used a raw
+		// writeFile to stateRoot/results/<id>.txt which aggregated task
+		// outputs could not locate — they only consult task.resultArtifact.
+		// Result: tasks reported "EMPTY OUTPUT" in the batch summary even
+		// though on-disk results were correct.
+		const resultArtifact = writeArtifact(manifest.artifactsRoot, {
+			kind: "result",
+			relativePath: `results/${t.id}.txt`,
+			content: text,
+			producer: t.id,
+		});
+		newArtifacts.push(resultArtifact);
+		return {
+			...t,
+			status: ok ? ("completed" as const) : ("failed" as const),
+			finishedAt,
+			result: {
+				text,
+				producer: groupId,
+				strategy: entry?.strategy ?? "broadcast",
+			},
+			resultArtifact,
+		};
+	});
+
+	// FIND-06: stop ticks and drain the snapshot captured by any active
+	// heartbeat before persisting terminal results. Bound the wait so a stuck
+	// filesystem operation cannot block dispatch completion indefinitely.
+	// P1 fix (R1 review): set finalWriteStarted BEFORE the drain so any pending
+	// heartbeat IIFE observes it and re-writes the terminal state after its
+	// own (possibly late) save resolves — preventing a late heartbeat snapshot
+	// from clobbering the terminal write.
+	finalWriteStarted = true;
+	if (heartbeatTimer !== null) clearInterval(heartbeatTimer);
+	const pendingHeartbeat = heartbeatPromise;
+	if (pendingHeartbeat) {
+		let drainTimeout: ReturnType<typeof setTimeout> | undefined;
+		try {
+			await Promise.race([
+				pendingHeartbeat,
+				new Promise<void>((resolve) => {
+					drainTimeout = setTimeout(resolve, 5_000);
+				}),
+			]);
+		} finally {
+			if (drainTimeout !== undefined) clearTimeout(drainTimeout);
+		}
+	}
+	await saveRunTasksAsync(manifest, updatedTasks);
+	let updatedManifest: TeamRunManifest = {
+		...manifest,
+		artifacts: mergeArtifacts([...manifest.artifacts, ...newArtifacts]),
+	};
+
+	if (success) {
+		updatedManifest = updateRunStatus(updatedManifest, "running");
+	}
+	await appendEventAsync(updatedManifest.eventsPath, {
+		type: "task.coalesced_dispatch_end",
+		runId: manifest.runId,
+		message: `Coalesced dispatch ${success ? "completed" : "failed"} (${taskIds.length} tasks, ${split[0]?.strategy ?? "broadcast"} split)`,
+		data: { groupId, taskIds, success, strategy: split[0]?.strategy },
+	});
+
+	return { manifest: updatedManifest, tasks: updatedTasks, taskIds, rawOutput, success };
+}
+
+async function buildCoalescedPrompt(
+	manifest: TeamRunManifest,
+	step: WorkflowStep,
+	groupTasks: TeamTaskState[],
+	agent: AgentConfig,
+): Promise<string> {
+	const tree = await buildWorkspaceTree(groupTasks[0]!.cwd);
+	const treeBlock = tree.rendered ? `# Workspace Structure\n${tree.rendered}` : "";
+	const roleInstructions =
+		permissionForRole(groupTasks[0]!.role) === "read_only"
+			? `You are running in READ-ONLY mode. Do not create, modify, delete, or move files. Emit your findings as TEXT in your final output.`
+			: "";
+
+	const taskBlocks = groupTasks
+		.map((task, idx) => {
+			return [
+				`### Task ${idx + 1} of ${groupTasks.length} (id: ${task.id})`,
+				`Step: ${step.id}`,
+				`Role: ${step.role}`,
+				`Task: ${sanitizeTaskText(step.task.replaceAll("{goal}", manifest.goal))}`,
+			].join("\n");
+		})
+		.join("\n\n---\n\n");
+
+	const outputInstructions = groupTasks.map((task) => `<<<TASK_RESULT:${task.id}>>>`).join(" ... ");
+
+	return [
+		"# pi-crew Coalesced Worker Prompt",
+		`Run ID: ${manifest.runId}`,
+		`Team: ${manifest.team}`,
+		`Workflow: ${manifest.workflow ?? "(none)"}`,
+		`Goal: ${manifest.goal}`,
+		`Tasks in this batch: ${groupTasks.length}`,
+		``,
+		roleInstructions,
+		``,
+		treeBlock,
+		``,
+		`# Your Tasks`,
+		`Complete ALL ${groupTasks.length} tasks below. For each, structure your final output using the delimiters shown.`,
+		``,
+		taskBlocks,
+		``,
+		`# Output Format (CRITICAL)`,
+		`After completing all tasks, structure your final output using these delimiters:`,
+		``,
+		outputInstructions,
+		``,
+		`Wrap each task's result between the start and end delimiters:`,
+		`<<<TASK_RESULT:{taskId}>>>`,
+		`...your result for this task...`,
+		`<<<END_TASK_RESULT>>>`,
+		``,
+		`If delimiters don't fit your workflow, use \`### Task N of M\` headings and we'll parse those instead.`,
+	]
+		.filter(Boolean)
+		.join("\n");
+}
+
+function buildScaffoldOutput(groupTasks: TeamTaskState[]): string {
+	return groupTasks
+		.map(
+			(task, idx) =>
+				`<<<TASK_RESULT:${task.id}>>>\nScaffold result for task ${idx + 1} of ${groupTasks.length}: ${task.id}\n<<<END_TASK_RESULT>>>`,
+		)
+		.join("\n\n");
+}