@kodrunhq/opencode-autopilot 1.14.1 → 1.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kodrunhq/opencode-autopilot",
-	"version": "1.14.1",
+	"version": "1.15.1",
 	"description": "Curated agents, skills, and commands for the OpenCode AI coding CLI — autonomous orchestrator, multi-agent code review, model fallback, and in-session asset creation tools.",
 	"main": "src/index.ts",
 	"keywords": [

package/src/agents/index.ts

@@ -71,6 +71,22 @@ function registerAgents(
 	}
 }
 
+function suppressBuiltInVariants(
+	variants: readonly string[],
+	builtInKeys: ReadonlySet<string>,
+	config: Config,
+): void {
+	if (!config.agent) return;
+	for (const variant of variants) {
+		if (builtInKeys.has(variant) && config.agent[variant] !== undefined) {
+			config.agent[variant] = {
+				...config.agent[variant],
+				disable: true,
+			};
+		}
+	}
+}
+
 export async function configHook(config: Config, configPath?: string): Promise<void> {
 	if (!config.agent) {
 		config.agent = {};
@@ -90,24 +106,20 @@ export async function configHook(config: Config, configPath?: string): Promise<v
 	const overrides: Readonly<Record<string, AgentOverride>> = pluginConfig?.overrides ?? {};
 
 	// Snapshot built-in agent keys BEFORE we register ours — we only suppress
-	// built-in Plan variants, not our own custom "planner" agent.
+	// built-in Plan/Build variants, never our custom planner/coder agents.
 	const builtInKeys = new Set(Object.keys(config.agent));
 
 	// Register standard agents and pipeline agents (v2 orchestrator subagents)
 	registerAgents(agents, config, groups, overrides);
 	registerAgents(pipelineAgents, config, groups, overrides);
 
-	// Suppress built-in Plan agent — our planner agent replaces it (D-17).
+	// Suppress built-in Plan/Build agents — planner/coder replace them.
 	// Only disable keys that existed before our registration (built-ins).
 	const planVariants = ["Plan", "plan", "Planner", "planner"] as const;
-	for (const variant of planVariants) {
-		if (builtInKeys.has(variant) && config.agent[variant] !== undefined) {
-			config.agent[variant] = {
-				...config.agent[variant],
-				disable: true,
-			};
-		}
-	}
+	suppressBuiltInVariants(planVariants, builtInKeys, config);
+
+	const buildVariants = ["Build", "build", "Builder", "builder"] as const;
+	suppressBuiltInVariants(buildVariants, builtInKeys, config);
 }
 
 export { autopilotAgent } from "./autopilot";

package/src/agents/researcher.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 
 export const researcherAgent: Readonly<AgentConfig> = Object.freeze({
 	description: "Searches the web about a topic and produces a comprehensive report with sources",
-	mode: "subagent",
+	mode: "all",
 	prompt: `You are a research specialist. Your job is to thoroughly investigate a given topic and produce a clear, well-organized report.
 
 ## Instructions

package/src/orchestrator/artifacts.ts

@@ -26,7 +26,7 @@ export const PHASE_ARTIFACTS: Readonly<Record<string, readonly string[]>> = Obje
 	CHALLENGE: Object.freeze(["brief.md"]),
 	ARCHITECT: Object.freeze(["design.md"]),
 	EXPLORE: Object.freeze([]),
-	PLAN: Object.freeze(["tasks.md"]),
+	PLAN: Object.freeze(["tasks.json", "tasks.md"]),
 	BUILD: Object.freeze([]),
 	SHIP: Object.freeze(["walkthrough.md", "decisions.md", "changelog.md"]),
 	RETROSPECTIVE: Object.freeze(["lessons.json"]),

package/src/orchestrator/contracts/invariants.ts

@@ -0,0 +1,121 @@
+import type { PipelineState } from "../types";
+
+export interface InvariantViolation {
+	readonly code: string;
+	readonly message: string;
+}
+
+function hasSingleInProgressPhase(state: Readonly<PipelineState>): boolean {
+	const count = state.phases.filter((phase) => phase.status === "IN_PROGRESS").length;
+	if (state.currentPhase === null) {
+		return true;
+	}
+	return count === 1;
+}
+
+function hasMatchingCurrentPhase(state: Readonly<PipelineState>): boolean {
+	if (state.currentPhase === null) {
+		return true;
+	}
+	const phase = state.phases.find((item) => item.name === state.currentPhase);
+	return phase?.status === "IN_PROGRESS";
+}
+
+function isTerminalStatus(state: Readonly<PipelineState>): boolean {
+	return state.status === "COMPLETED" || state.status === "FAILED";
+}
+
+function buildTaskExists(state: Readonly<PipelineState>, taskId: number): boolean {
+	return state.tasks.some((task) => task.id === taskId);
+}
+
+function collectPendingDispatchKeys(state: Readonly<PipelineState>): readonly string[] {
+	return state.pendingDispatches.map((entry) => `${entry.dispatchId}|${entry.phase}`);
+}
+
+export function validateStateInvariants(
+	state: Readonly<PipelineState>,
+): readonly InvariantViolation[] {
+	const violations: InvariantViolation[] = [];
+
+	if (state.currentPhase === null && !isTerminalStatus(state)) {
+		violations.push({
+			code: "E_INVARIANT_PHASE_TERMINAL",
+			message: "currentPhase is null while status is non-terminal",
+		});
+	}
+
+	if (state.currentPhase !== null && isTerminalStatus(state)) {
+		if (state.status === "COMPLETED") {
+			violations.push({
+				code: "E_INVARIANT_PHASE_ACTIVE",
+				message: "currentPhase is set while status is terminal",
+			});
+		}
+	}
+
+	if (!hasSingleInProgressPhase(state)) {
+		violations.push({
+			code: "E_INVARIANT_IN_PROGRESS_COUNT",
+			message: "phase status must have exactly one IN_PROGRESS when pipeline is active",
+		});
+	}
+
+	if (!hasMatchingCurrentPhase(state)) {
+		violations.push({
+			code: "E_INVARIANT_CURRENT_PHASE_MISMATCH",
+			message: "currentPhase does not match an IN_PROGRESS phase entry",
+		});
+	}
+
+	if (
+		state.buildProgress.currentTask !== null &&
+		!buildTaskExists(state, state.buildProgress.currentTask)
+	) {
+		violations.push({
+			code: "E_INVARIANT_BUILD_TASK",
+			message: "buildProgress.currentTask references unknown task",
+		});
+	}
+
+	if (state.buildProgress.reviewPending && state.currentPhase !== "BUILD") {
+		violations.push({
+			code: "E_INVARIANT_REVIEW_PHASE",
+			message: "buildProgress.reviewPending is true outside BUILD phase",
+		});
+	}
+
+	const pendingKeys = collectPendingDispatchKeys(state);
+	if (new Set(pendingKeys).size !== pendingKeys.length) {
+		violations.push({
+			code: "E_INVARIANT_PENDING_DISPATCH_DUP",
+			message: "pendingDispatches contains duplicate dispatch-phase keys",
+		});
+	}
+
+	const processedIds = state.processedResultIds;
+	if (new Set(processedIds).size !== processedIds.length) {
+		violations.push({
+			code: "E_INVARIANT_RESULT_ID_DUP",
+			message: "processedResultIds contains duplicate result IDs",
+		});
+	}
+
+	if (state.stateRevision < 0 || !Number.isInteger(state.stateRevision)) {
+		violations.push({
+			code: "E_INVARIANT_REVISION",
+			message: "stateRevision must be a non-negative integer",
+		});
+	}
+
+	return Object.freeze(violations);
+}
+
+export function assertStateInvariants(state: Readonly<PipelineState>): void {
+	const violations = validateStateInvariants(state);
+	if (violations.length === 0) {
+		return;
+	}
+	const top = violations[0];
+	throw new Error(`${top.code}: ${top.message}`);
+}

package/src/orchestrator/contracts/legacy-result-adapter.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { Phase } from "../types";
+import { type ResultEnvelope, resultEnvelopeSchema } from "./result-envelope";
+
+export interface ParseResultEnvelopeResult {
+	readonly envelope: ResultEnvelope;
+	readonly legacy: boolean;
+}
+
+export function parseResultEnvelope(
+	raw: string,
+	ctx: {
+		readonly runId: string;
+		readonly phase: Phase;
+		readonly fallbackDispatchId: string;
+		readonly fallbackAgent?: string | null;
+	},
+): ParseResultEnvelopeResult {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) {
+		throw new Error("E_INVALID_RESULT: empty result payload");
+	}
+
+	try {
+		const parsed = JSON.parse(trimmed);
+		const envelope = resultEnvelopeSchema.parse(parsed);
+		return { envelope, legacy: false };
+	} catch (error: unknown) {
+		if (error instanceof z.ZodError) {
+			throw new Error(`E_INVALID_RESULT: ${error.issues[0]?.message ?? "invalid envelope"}`);
+		}
+		const legacyEnvelope = resultEnvelopeSchema.parse({
+			schemaVersion: 1,
+			resultId: `legacy-${ctx.fallbackDispatchId}`,
+			runId: ctx.runId,
+			phase: ctx.phase,
+			dispatchId: ctx.fallbackDispatchId,
+			agent: ctx.fallbackAgent ?? null,
+			kind: "phase_output",
+			taskId: null,
+			payload: {
+				text: raw,
+			},
+		});
+		return { envelope: legacyEnvelope, legacy: true };
+	}
+}

package/src/orchestrator/contracts/phase-artifacts.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+
+const taskIdPattern = /^W(\d+)-T(\d+)$/i;
+
+export const planTaskArtifactItemSchema = z
+	.object({
+		taskId: z.string().regex(taskIdPattern),
+		title: z.string().min(1).max(2048),
+		wave: z.number().int().positive(),
+		depends_on: z.array(z.string().regex(taskIdPattern)).default([]),
+	})
+	.superRefine((task, ctx) => {
+		const parsed = taskIdPattern.exec(task.taskId);
+		if (!parsed) {
+			return;
+		}
+		const waveFromTaskId = Number.parseInt(parsed[1], 10);
+		if (waveFromTaskId !== task.wave) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `wave mismatch for ${task.taskId}: expected ${waveFromTaskId}, got ${task.wave}`,
+				path: ["wave"],
+			});
+		}
+	});
+
+export const planTasksArtifactSchema = z
+	.object({
+		schemaVersion: z.literal(1).default(1),
+		tasks: z.array(planTaskArtifactItemSchema).min(1),
+	})
+	.superRefine((artifact, ctx) => {
+		const seen = new Set<string>();
+		for (let i = 0; i < artifact.tasks.length; i++) {
+			const id = artifact.tasks[i].taskId.toUpperCase();
+			if (seen.has(id)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: `duplicate taskId: ${artifact.tasks[i].taskId}`,
+					path: ["tasks", i, "taskId"],
+				});
+				continue;
+			}
+			seen.add(id);
+		}
+
+		for (let i = 0; i < artifact.tasks.length; i++) {
+			for (const dep of artifact.tasks[i].depends_on) {
+				if (!seen.has(dep.toUpperCase())) {
+					ctx.addIssue({
+						code: z.ZodIssueCode.custom,
+						message: `unknown dependency ${dep}`,
+						path: ["tasks", i, "depends_on"],
+					});
+				}
+			}
+		}
+	});
+
+export interface NormalizedPlanTask {
+	readonly id: number;
+	readonly title: string;
+	readonly wave: number;
+	readonly dependsOnIndexes: readonly number[];
+}
+
+export function normalizePlanTasks(
+	artifact: z.infer<typeof planTasksArtifactSchema>,
+): readonly NormalizedPlanTask[] {
+	const ordered = artifact.tasks.map((task) => ({ ...task }));
+	const indexByTaskId = new Map<string, number>();
+	for (let i = 0; i < ordered.length; i++) {
+		indexByTaskId.set(ordered[i].taskId.toUpperCase(), i + 1);
+	}
+
+	return Object.freeze(
+		ordered.map((task, idx) => {
+			const deps = task.depends_on
+				.map((id) => indexByTaskId.get(id.toUpperCase()))
+				.filter((n): n is number => typeof n === "number")
+				.sort((a, b) => a - b);
+			return Object.freeze({
+				id: idx + 1,
+				title: task.title,
+				wave: task.wave,
+				dependsOnIndexes: Object.freeze(deps),
+			});
+		}),
+	);
+}

package/src/orchestrator/contracts/result-envelope.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { dispatchResultKindSchema, type pendingDispatchSchema, phaseSchema } from "../schemas";
+
+export const resultKindSchema = dispatchResultKindSchema;
+
+export const resultEnvelopeSchema = z.object({
+	schemaVersion: z.literal(1).default(1),
+	resultId: z.string().min(1).max(128),
+	runId: z.string().min(1).max(128),
+	phase: phaseSchema,
+	dispatchId: z.string().min(1).max(128),
+	agent: z.string().min(1).max(128).nullable().default(null),
+	kind: resultKindSchema,
+	taskId: z.number().int().positive().nullable().default(null),
+	payload: z
+		.object({
+			text: z.string().max(1_048_576).default(""),
+		})
+		.passthrough(),
+});
+
+export type PendingDispatch = z.infer<typeof pendingDispatchSchema>;
+export type ResultEnvelope = z.infer<typeof resultEnvelopeSchema>;

package/src/orchestrator/handlers/architect.ts

@@ -6,7 +6,7 @@ import { getMemoryTunedDepth } from "../arena";
 import { ensurePhaseDir, getArtifactRef, getPhaseDir } from "../artifacts";
 import { filterByPhase } from "../confidence";
 import type { PipelineState } from "../types";
-import { AGENT_NAMES, type DispatchResult } from "./types";
+import { AGENT_NAMES, type DispatchResult, type PhaseHandlerContext } from "./types";
 
 const CONSTRAINT_FRAMINGS: readonly string[] = Object.freeze([
 	"Optimize for simplicity and minimal dependencies",
@@ -26,6 +26,7 @@ export async function handleArchitect(
 	state: Readonly<PipelineState>,
 	artifactDir: string,
 	_result?: string,
+	_context?: PhaseHandlerContext,
 ): Promise<DispatchResult> {
 	// _result is received from the orchestrator but completion is determined by
 	// artifact existence (design.md/critique.md), not by result truthiness.
@@ -51,6 +52,7 @@ export async function handleArchitect(
 		return Object.freeze({
 			action: "dispatch" as const,
 			agent: AGENT_NAMES.CRITIC,
+			resultKind: "phase_output",
 			prompt: [
 				`Review architecture proposals in ${proposalsDir}/`,
 				`Read ${getArtifactRef(artifactDir, "RECON", "report.md")} and ${getArtifactRef(artifactDir, "CHALLENGE", "brief.md")} for context.`,
@@ -74,6 +76,7 @@ export async function handleArchitect(
 		return Object.freeze({
 			action: "dispatch" as const,
 			agent: AGENT_NAMES.ARCHITECT,
+			resultKind: "phase_output",
 			prompt: [
 				`Read ${reconRef} and ${challengeRef} for context.`,
 				`Design architecture for: ${safeIdea}`,
@@ -89,6 +92,7 @@ export async function handleArchitect(
 		const label = String.fromCharCode(65 + i); // A, B, C
 		return Object.freeze({
 			agent: AGENT_NAMES.ARCHITECT,
+			resultKind: "phase_output" as const,
 			prompt: [
 				`Read ${reconRef} and ${challengeRef} for context.`,
 				`Design architecture for: ${safeIdea}`,

package/src/orchestrator/handlers/build.ts

@@ -1,9 +1,10 @@
 import { sanitizeTemplateContent } from "../../review/sanitize";
+import { fileExists } from "../../utils/fs-helpers";
 import { getArtifactRef } from "../artifacts";
 import { groupByWave } from "../plan";
 import type { BuildProgress, Task } from "../types";
 import { assignWaves } from "../wave-assigner";
-import type { DispatchResult, PhaseHandler } from "./types";
+import type { DispatchResult, PhaseHandler, PhaseHandlerContext } from "./types";
 import { AGENT_NAMES } from "./types";
 
 const MAX_STRIKES = 3;
@@ -55,12 +56,14 @@ function markTasksInProgress(tasks: readonly Task[], taskIds: readonly number[])
 /**
  * Build a prompt for a single task dispatch.
  */
-function buildTaskPrompt(task: Task, artifactDir: string): string {
-	const planRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+async function buildTaskPrompt(task: Task, artifactDir: string): Promise<string> {
+	const planRef = getArtifactRef(artifactDir, "PLAN", "tasks.json");
+	const planFallbackRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
 	const designRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
+	const planPath = (await fileExists(planRef)) ? planRef : planFallbackRef;
 	return [
 		`Implement task ${task.id}: ${task.title}.`,
-		`Reference the plan at ${planRef}`,
+		`Reference the plan at ${planPath}`,
 		`and architecture at ${designRef}.`,
 		`If a CLAUDE.md file exists in the project root, read it for project-specific conventions.`,
 		`Check ~/.config/opencode/skills/coding-standards/SKILL.md for coding standards.`,
@@ -110,8 +113,14 @@ function hasCriticalFindings(resultStr: string): boolean {
 	}
 }
 
-export const handleBuild: PhaseHandler = async (state, artifactDir, result?) => {
+export const handleBuild: PhaseHandler = async (
+	state,
+	artifactDir,
+	result?,
+	context?: PhaseHandlerContext,
+) => {
 	const { tasks, buildProgress } = state;
+	const resultText = context?.envelope.payload.text ?? result;
 
 	// Edge case: no tasks
 	if (tasks.length === 0) {
@@ -123,9 +132,10 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 	}
 
 	// Edge case: strike count exceeded
-	if (buildProgress.strikeCount > MAX_STRIKES && buildProgress.reviewPending && result) {
+	if (buildProgress.strikeCount > MAX_STRIKES && buildProgress.reviewPending && resultText) {
 		return Object.freeze({
 			action: "error",
+			code: "E_BUILD_MAX_STRIKES",
 			phase: "BUILD",
 			message: "Max retries exceeded — too many CRITICAL review findings",
 		} satisfies DispatchResult);
@@ -171,15 +181,26 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 		});
 	}
 
+	if (buildProgress.reviewPending && !resultText) {
+		return Object.freeze({
+			action: "dispatch",
+			agent: AGENT_NAMES.REVIEW,
+			prompt: "Review completed wave. Scope: branch. Report any CRITICAL findings.",
+			phase: "BUILD",
+			resultKind: "review_findings",
+			progress: "Review pending — dispatching reviewer",
+		} satisfies DispatchResult);
+	}
+
 	// Case 1: Review pending + result provided -> process review outcome
-	if (buildProgress.reviewPending && result) {
-		if (hasCriticalFindings(result)) {
+	if (buildProgress.reviewPending && resultText) {
+		if (hasCriticalFindings(resultText)) {
 			// Re-dispatch implementer with fix instructions
-			const safeResult = sanitizeTemplateContent(result).slice(0, 4000);
+			const safeResult = sanitizeTemplateContent(resultText).slice(0, 4000);
 			const prompt = [
 				`CRITICAL review findings detected. Fix the following issues:`,
 				safeResult,
-				`Reference ${getArtifactRef(artifactDir, "PLAN", "tasks.md")} for context.`,
+				`Reference ${getArtifactRef(artifactDir, "PLAN", "tasks.json")} for context.`,
 			].join(" ");
 
 			return Object.freeze({
@@ -187,6 +208,8 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 				agent: AGENT_NAMES.BUILD,
 				prompt,
 				phase: "BUILD",
+				resultKind: "task_completion",
+				taskId: buildProgress.currentTask,
 				progress: "Fix dispatch — CRITICAL findings",
 				_stateUpdates: {
 					buildProgress: {
@@ -224,11 +247,14 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 
 		if (pendingTasks.length === 1) {
 			const task = pendingTasks[0];
+			const prompt = await buildTaskPrompt(task, artifactDir);
 			return Object.freeze({
 				action: "dispatch",
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(task, artifactDir),
+				prompt,
 				phase: "BUILD",
+				resultKind: "task_completion",
+				taskId: task.id,
 				progress: `Wave ${nextWave} — task ${task.id}`,
 				_stateUpdates: {
 					buildProgress: { ...updatedProgress, currentTask: task.id },
@@ -237,11 +263,19 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 		}
 
 		const dispatchedIds = pendingTasks.map((t) => t.id);
+		const promptsByTaskId = new Map<number, string>();
+		await Promise.all(
+			pendingTasks.map(async (task) => {
+				promptsByTaskId.set(task.id, await buildTaskPrompt(task, artifactDir));
+			}),
+		);
 		return Object.freeze({
 			action: "dispatch_multi",
 			agents: pendingTasks.map((task) => ({
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(task, artifactDir),
+				prompt: promptsByTaskId.get(task.id) ?? "",
+				taskId: task.id,
+				resultKind: "task_completion" as const,
 			})),
 			phase: "BUILD",
 			progress: `Wave ${nextWave} — ${pendingTasks.length} concurrent tasks`,
@@ -254,9 +288,50 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 
 	// Case 2: Result provided + not review pending -> mark task done
 	// For dispatch_multi, currentTask may be null — find the first IN_PROGRESS task instead
-	const taskToComplete =
-		buildProgress.currentTask ?? effectiveTasks.find((t) => t.status === "IN_PROGRESS")?.id ?? null;
-	if (result && !buildProgress.reviewPending && taskToComplete !== null) {
+	const hasTypedContext = context !== undefined && !context.legacy;
+	const isTaskCompletion = hasTypedContext && context.envelope.kind === "task_completion";
+	const isLegacyContext = context !== undefined && context.legacy;
+	const taskToComplete = isTaskCompletion
+		? context.envelope.taskId
+		: hasTypedContext
+			? buildProgress.currentTask
+			: (buildProgress.currentTask ??
+				effectiveTasks.find((t) => t.status === "IN_PROGRESS")?.id ??
+				null);
+
+	if (
+		resultText &&
+		!buildProgress.reviewPending &&
+		isLegacyContext &&
+		buildProgress.currentTask === null
+	) {
+		return Object.freeze({
+			action: "error",
+			code: "E_BUILD_TASK_ID_REQUIRED",
+			phase: "BUILD",
+			message:
+				"Legacy BUILD result cannot be attributed when currentTask is null. Submit typed envelope with taskId.",
+		} satisfies DispatchResult);
+	}
+	if (resultText && !buildProgress.reviewPending && taskToComplete === null) {
+		return Object.freeze({
+			action: "error",
+			code: "E_BUILD_TASK_ID_REQUIRED",
+			phase: "BUILD",
+			message: "Cannot attribute BUILD result to a task. Provide taskId in result envelope.",
+		} satisfies DispatchResult);
+	}
+
+	if (resultText && !buildProgress.reviewPending && taskToComplete !== null) {
+		if (!effectiveTasks.some((t) => t.id === taskToComplete)) {
+			return Object.freeze({
+				action: "error",
+				code: "E_BUILD_UNKNOWN_TASK",
+				phase: "BUILD",
+				message: `Unknown taskId in BUILD result: ${taskToComplete}`,
+			} satisfies DispatchResult);
+		}
+
 		const updatedTasks = markTaskDone(effectiveTasks, taskToComplete);
 		const waveMap = groupByWave(updatedTasks);
 		const currentWave = buildProgress.currentWave ?? 1;
@@ -268,6 +343,7 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 				agent: AGENT_NAMES.REVIEW,
 				prompt: "Review completed wave. Scope: branch. Report any CRITICAL findings.",
 				phase: "BUILD",
+				resultKind: "review_findings",
 				progress: `Wave ${currentWave} complete — review pending`,
 				_stateUpdates: {
 					tasks: [...updatedTasks],
@@ -284,11 +360,14 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 		const pendingInWave = findPendingTasks(waveMap, currentWave);
 		if (pendingInWave.length > 0) {
 			const next = pendingInWave[0];
+			const prompt = await buildTaskPrompt(next, artifactDir);
 			return Object.freeze({
 				action: "dispatch",
 				agent: AGENT_NAMES.BUILD,
-				prompt: buildTaskPrompt(next, artifactDir),
+				prompt,
 				phase: "BUILD",
+				resultKind: "task_completion",
+				taskId: next.id,
 				progress: `Wave ${currentWave} — task ${next.id}`,
 				_stateUpdates: {
 					tasks: [...updatedTasks],
@@ -308,6 +387,7 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 				agent: AGENT_NAMES.BUILD,
 				prompt: `Wave ${currentWave} has ${inProgressInWave.length} task(s) still in progress. Continue working on remaining tasks.`,
 				phase: "BUILD",
+				resultKind: "phase_output",
 				progress: `Wave ${currentWave} — waiting for ${inProgressInWave.length} in-progress task(s)`,
 				_stateUpdates: {
 					tasks: [...updatedTasks],
@@ -344,6 +424,7 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 			agent: AGENT_NAMES.BUILD,
 			prompt: `Resume: wave ${currentWave} has ${inProgressTasks.length} task(s) still in progress. Wait for agent results and pass them back.`,
 			phase: "BUILD",
+			resultKind: "phase_output",
 			progress: `Wave ${currentWave} — waiting for ${inProgressTasks.length} in-progress task(s)`,
 			_stateUpdates: {
 				buildProgress: {
@@ -366,11 +447,14 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 
 	if (pendingTasks.length === 1) {
 		const task = pendingTasks[0];
+		const prompt = await buildTaskPrompt(task, artifactDir);
 		return Object.freeze({
 			action: "dispatch",
 			agent: AGENT_NAMES.BUILD,
-			prompt: buildTaskPrompt(task, artifactDir),
+			prompt,
 			phase: "BUILD",
+			resultKind: "task_completion",
+			taskId: task.id,
 			progress: `Wave ${currentWave} — task ${task.id}`,
 			_stateUpdates: {
 				buildProgress: {
@@ -384,11 +468,19 @@ export const handleBuild: PhaseHandler = async (state, artifactDir, result?) =>
 
 	// Multiple pending tasks in wave -> dispatch_multi
 	const dispatchedIds = pendingTasks.map((t) => t.id);
+	const promptsByTaskId = new Map<number, string>();
+	await Promise.all(
+		pendingTasks.map(async (task) => {
+			promptsByTaskId.set(task.id, await buildTaskPrompt(task, artifactDir));
+		}),
+	);
 	return Object.freeze({
 		action: "dispatch_multi",
 		agents: pendingTasks.map((task) => ({
 			agent: AGENT_NAMES.BUILD,
-			prompt: buildTaskPrompt(task, artifactDir),
+			prompt: promptsByTaskId.get(task.id) ?? "",
+			taskId: task.id,
+			resultKind: "task_completion" as const,
 		})),
 		phase: "BUILD",
 		progress: `Wave ${currentWave} — ${pendingTasks.length} concurrent tasks`,