@kodrunhq/opencode-autopilot 1.14.0 → 1.15.0

package/src/orchestrator/handlers/plan.ts

@@ -1,19 +1,200 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isEnoentError } from "../../utils/fs-helpers";
 import { getArtifactRef } from "../artifacts";
+import { normalizePlanTasks, planTasksArtifactSchema } from "../contracts/phase-artifacts";
+import { logOrchestrationEvent } from "../orchestration-logger";
+import { renderTasksMarkdown } from "../renderers/tasks-markdown";
+import { taskSchema } from "../schemas";
+import type { Task } from "../types";
 import type { DispatchResult, PhaseHandler } from "./types";
 import { AGENT_NAMES } from "./types";
 
+const EXPECTED_COLUMN_COUNT = 6;
+const taskIdPattern = /^W(\d+)-T(\d+)$/i;
+const separatorCellPattern = /^:?-{3,}:?$/;
+
+function parseTableColumns(line: string): readonly string[] | null {
+	const trimmed = line.trim();
+	if (!trimmed.includes("|")) {
+		return null;
+	}
+
+	const withoutLeadingBoundary = trimmed.startsWith("|") ? trimmed.slice(1) : trimmed;
+	const normalized = withoutLeadingBoundary.endsWith("|")
+		? withoutLeadingBoundary.slice(0, -1)
+		: withoutLeadingBoundary;
+
+	return normalized.split("|").map((col) => col.trim());
+}
+
+function isSeparatorRow(columns: readonly string[]): boolean {
+	return columns.length > 0 && columns.every((col) => separatorCellPattern.test(col));
+}
+
+/**
+ * Parse tasks from markdown table in tasks.md.
+ * Legacy fallback only -- canonical source is tasks.json.
+ */
+async function loadTasksFromMarkdown(tasksPath: string): Promise<Task[]> {
+	const content = await readFile(tasksPath, "utf-8");
+	const lines = content.split("\n");
+
+	const tasks: Task[] = [];
+	for (const line of lines) {
+		const columns = parseTableColumns(line);
+		if (columns === null || columns.length < EXPECTED_COLUMN_COUNT || isSeparatorRow(columns)) {
+			continue;
+		}
+
+		if (columns[0].toLowerCase() === "task id") {
+			continue;
+		}
+
+		const idMatch = taskIdPattern.exec(columns[0]);
+		if (idMatch === null) {
+			continue;
+		}
+
+		const waveFromId = Number.parseInt(idMatch[1], 10);
+		const title = columns[1];
+		const waveFromColumn = Number.parseInt(columns[4], 10);
+
+		if (!title || Number.isNaN(waveFromId) || Number.isNaN(waveFromColumn)) {
+			continue;
+		}
+
+		if (waveFromId !== waveFromColumn) {
+			continue;
+		}
+
+		tasks.push(
+			taskSchema.parse({
+				id: tasks.length + 1,
+				title,
+				status: "PENDING",
+				wave: waveFromColumn,
+				depends_on: [],
+				attempt: 0,
+				strike: 0,
+			}),
+		);
+	}
+
+	if (tasks.length === 0) {
+		throw new Error("No valid task rows found in PLAN tasks.md");
+	}
+
+	return tasks;
+}
+
+async function loadTasksFromJson(tasksPath: string): Promise<Task[]> {
+	const raw = await readFile(tasksPath, "utf-8");
+	const parsed = JSON.parse(raw);
+	const artifact = planTasksArtifactSchema.parse(parsed);
+	const normalized = normalizePlanTasks(artifact);
+	return normalized.map((task) =>
+		taskSchema.parse({
+			id: task.id,
+			title: task.title,
+			status: "PENDING",
+			wave: task.wave,
+			depends_on: task.dependsOnIndexes,
+			attempt: 0,
+			strike: 0,
+		}),
+	);
+}
+
+function buildTasksArtifactFromLegacyTasks(tasks: readonly Task[]) {
+	const countersByWave = new Map<number, number>();
+	return planTasksArtifactSchema.parse({
+		schemaVersion: 1,
+		tasks: tasks.map((task) => {
+			const nextIndex = (countersByWave.get(task.wave) ?? 0) + 1;
+			countersByWave.set(task.wave, nextIndex);
+			return {
+				taskId: `W${task.wave}-T${String(nextIndex).padStart(2, "0")}`,
+				title: task.title,
+				wave: task.wave,
+				depends_on: [] as string[],
+			};
+		}),
+	});
+}
+
 export const handlePlan: PhaseHandler = async (_state, artifactDir, result?) => {
+	// When result is provided, the planner has completed writing tasks
+	// Load them from tasks.json (canonical) and populate state.tasks.
+	// Fall back to tasks.md for compatibility with legacy planners.
 	if (result) {
-		return Object.freeze({
-			action: "complete",
-			phase: "PLAN",
-			progress: "Planning complete — tasks written",
-		} satisfies DispatchResult);
+		const tasksJsonPath = getArtifactRef(artifactDir, "PLAN", "tasks.json");
+		const tasksPath = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+		try {
+			let loadedTasks: Task[];
+			let usedLegacyMarkdown = false;
+
+			try {
+				loadedTasks = await loadTasksFromJson(tasksJsonPath);
+			} catch (jsonError: unknown) {
+				if (!isEnoentError(jsonError)) {
+					throw jsonError;
+				}
+				loadedTasks = await loadTasksFromMarkdown(tasksPath);
+				usedLegacyMarkdown = true;
+			}
+
+			if (usedLegacyMarkdown) {
+				const msg =
+					"PLAN fallback: parsed legacy tasks.md (tasks.json missing). Migrate planner output to tasks.json.";
+				console.warn(`[opencode-autopilot] ${msg}`);
+				logOrchestrationEvent(artifactDir, {
+					timestamp: new Date().toISOString(),
+					phase: "PLAN",
+					action: "error",
+					message: msg,
+				});
+
+				const artifact = buildTasksArtifactFromLegacyTasks(loadedTasks);
+				await writeFile(tasksJsonPath, JSON.stringify(artifact, null, 2), "utf-8");
+			} else {
+				const artifact = planTasksArtifactSchema.parse(
+					JSON.parse(await readFile(tasksJsonPath, "utf-8")),
+				);
+				const markdown = renderTasksMarkdown(artifact);
+				await writeFile(tasksPath, markdown, "utf-8");
+			}
+
+			return Object.freeze({
+				action: "complete",
+				phase: "PLAN",
+				resultKind: "phase_output",
+				progress: usedLegacyMarkdown
+					? `Planning complete — loaded ${loadedTasks.length} task(s) via legacy markdown fallback`
+					: `Planning complete — loaded ${loadedTasks.length} task(s) from tasks.json`,
+				_stateUpdates: {
+					tasks: loadedTasks,
+				},
+			} satisfies DispatchResult);
+		} catch (error: unknown) {
+			const reason = isEnoentError(error)
+				? "tasks.md not found after planner completion"
+				: error instanceof Error
+					? error.message
+					: "Unknown parsing error";
+
+			return Object.freeze({
+				action: "error",
+				code: "E_PLAN_TASK_LOAD",
+				phase: "PLAN",
+				message: `Failed to load PLAN tasks: ${reason}`,
+				progress: "Planning failed — task extraction error",
+			} satisfies DispatchResult);
+		}
 	}
 
 	const architectRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
 	const challengeRef = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
-	const tasksPath = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+	const tasksPath = getArtifactRef(artifactDir, "PLAN", "tasks.json");
 
 	const prompt = [
 		"Read the architecture design at",
@@ -21,7 +202,7 @@ export const handlePlan: PhaseHandler = async (_state, artifactDir, result?) =>
 		"and the challenge brief at",
 		challengeRef,
 		"then produce a task plan.",
-		`Write tasks to ${tasksPath}.`,
+		`Write tasks to ${tasksPath} as strict JSON with shape {"schemaVersion":1,"tasks":[{"taskId":"W1-T01","title":"...","wave":1,"depends_on":[]}]}.`,
 		"Each task should have a 300-line diff max.",
 		"Assign wave numbers for parallel execution.",
 	].join(" ");
@@ -29,6 +210,7 @@ export const handlePlan: PhaseHandler = async (_state, artifactDir, result?) =>
 	return Object.freeze({
 		action: "dispatch",
 		agent: AGENT_NAMES.PLAN,
+		resultKind: "phase_output",
 		prompt,
 		phase: "PLAN",
 		progress: "Dispatching planner",

package/src/orchestrator/handlers/recon.ts

@@ -2,7 +2,7 @@ import { sanitizeTemplateContent } from "../../review/sanitize";
 import { fileExists } from "../../utils/fs-helpers";
 import { ensurePhaseDir, getArtifactRef } from "../artifacts";
 import type { PipelineState } from "../types";
-import { AGENT_NAMES, type DispatchResult } from "./types";
+import { AGENT_NAMES, type DispatchResult, type PhaseHandlerContext } from "./types";
 
 /**
  * RECON phase handler — dispatches oc-researcher with idea and artifact path.
@@ -12,6 +12,7 @@ export async function handleRecon(
 	state: Readonly<PipelineState>,
 	artifactDir: string,
 	result?: string,
+	_context?: PhaseHandlerContext,
 ): Promise<DispatchResult> {
 	if (result) {
 		// Warn if artifact wasn't written (best-effort — still complete the phase)
@@ -34,6 +35,7 @@ export async function handleRecon(
 	return Object.freeze({
 		action: "dispatch" as const,
 		agent: AGENT_NAMES.RECON,
+		resultKind: "phase_output",
 		prompt: [
 			`Research the following idea and write findings to ${outputPath}`,
 			`Idea: ${safeIdea}`,

package/src/orchestrator/handlers/retrospective.ts

@@ -12,6 +12,8 @@ import type { Phase } from "../types";
 import type { DispatchResult, PhaseHandler } from "./types";
 import { AGENT_NAMES } from "./types";
 
+export const LESSONS_PARSE_ERROR_CODE = "E_RETRO_PARSE";
+
 /**
  * Parse and validate lessons from the agent's JSON output.
  * Returns only valid lessons; invalid entries are silently skipped (graceful degradation).
@@ -61,6 +63,8 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 		if (parseError) {
 			return Object.freeze({
 				action: "complete",
+				code: LESSONS_PARSE_ERROR_CODE,
+				resultKind: "phase_output",
 				phase: "RETROSPECTIVE",
 				progress: "Retrospective complete -- no lessons extracted (parse error)",
 			} satisfies DispatchResult);
@@ -69,6 +73,7 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 		if (valid.length === 0) {
 			return Object.freeze({
 				action: "complete",
+				resultKind: "phase_output",
 				phase: "RETROSPECTIVE",
 				progress: "Retrospective complete -- 0 lessons extracted",
 			} satisfies DispatchResult);
@@ -91,6 +96,7 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 			const msg = raw.replace(/[/\\][^\s"']+/g, "[PATH]").slice(0, 256);
 			return Object.freeze({
 				action: "complete",
+				resultKind: "phase_output",
 				phase: "RETROSPECTIVE",
 				progress: `Retrospective complete — ${valid.length} lessons extracted (persistence failed: ${msg})`,
 			} satisfies DispatchResult);
@@ -98,6 +104,7 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 
 		return Object.freeze({
 			action: "complete",
+			resultKind: "phase_output",
 			phase: "RETROSPECTIVE",
 			progress: `Retrospective complete -- ${valid.length} lessons extracted`,
 		} satisfies DispatchResult);
@@ -118,6 +125,7 @@ export const handleRetrospective: PhaseHandler = async (_state, artifactDir, res
 	return Object.freeze({
 		action: "dispatch",
 		agent: AGENT_NAMES.RETROSPECTIVE,
+		resultKind: "phase_output",
 		prompt,
 		phase: "RETROSPECTIVE",
 		progress: "Dispatching retrospector",

package/src/orchestrator/handlers/ship.ts

@@ -1,3 +1,4 @@
+import { fileExists } from "../../utils/fs-helpers";
 import { getArtifactRef, getPhaseDir } from "../artifacts";
 import type { DispatchResult, PhaseHandler } from "./types";
 import { AGENT_NAMES } from "./types";
@@ -6,6 +7,7 @@ export const handleShip: PhaseHandler = async (_state, artifactDir, result?) =>
 	if (result) {
 		return Object.freeze({
 			action: "complete",
+			resultKind: "phase_output",
 			phase: "SHIP",
 			progress: "Shipping complete — documentation written",
 		} satisfies DispatchResult);
@@ -14,7 +16,9 @@ export const handleShip: PhaseHandler = async (_state, artifactDir, result?) =>
 	const reconRef = getArtifactRef(artifactDir, "RECON", "report.md");
 	const challengeRef = getArtifactRef(artifactDir, "CHALLENGE", "brief.md");
 	const architectRef = getArtifactRef(artifactDir, "ARCHITECT", "design.md");
-	const planRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+	const tasksJsonRef = getArtifactRef(artifactDir, "PLAN", "tasks.json");
+	const tasksMarkdownRef = getArtifactRef(artifactDir, "PLAN", "tasks.md");
+	const planRef = (await fileExists(tasksJsonRef)) ? tasksJsonRef : tasksMarkdownRef;
 	const shipDir = getPhaseDir(artifactDir, "SHIP");
 
 	const prompt = [
@@ -32,6 +36,7 @@ export const handleShip: PhaseHandler = async (_state, artifactDir, result?) =>
 	return Object.freeze({
 		action: "dispatch",
 		agent: AGENT_NAMES.SHIP,
+		resultKind: "phase_output",
 		prompt,
 		phase: "SHIP",
 		progress: "Dispatching shipper",

package/src/orchestrator/handlers/types.ts

@@ -1,4 +1,5 @@
-import type { PipelineState } from "../types";
+import type { ResultEnvelope } from "../contracts/result-envelope";
+import type { DispatchResultKind, PipelineState } from "../types";
 
 export const AGENT_NAMES = Object.freeze({
 	RECON: "oc-researcher",
@@ -15,18 +16,36 @@ export const AGENT_NAMES = Object.freeze({
 
 export interface DispatchResult {
 	readonly action: "dispatch" | "dispatch_multi" | "complete" | "error";
+	readonly code?: string;
 	readonly agent?: string;
-	readonly agents?: readonly { readonly agent: string; readonly prompt: string }[];
+	readonly agents?: readonly {
+		readonly agent: string;
+		readonly prompt: string;
+		readonly dispatchId?: string;
+		readonly taskId?: number | null;
+		readonly resultKind?: DispatchResultKind;
+	}[];
 	readonly prompt?: string;
 	readonly phase?: string;
 	readonly progress?: string;
 	readonly message?: string;
+	readonly resultKind?: DispatchResultKind;
+	readonly taskId?: number | null;
+	readonly dispatchId?: string;
+	readonly runId?: string;
+	readonly expectedResultKind?: DispatchResultKind;
 	readonly _stateUpdates?: Partial<PipelineState>;
 	readonly _userProgress?: string;
 }
 
+export interface PhaseHandlerContext {
+	readonly envelope: ResultEnvelope;
+	readonly legacy: boolean;
+}
+
 export type PhaseHandler = (
 	state: Readonly<PipelineState>,
 	artifactDir: string,
 	result?: string,
+	context?: PhaseHandlerContext,
 ) => Promise<DispatchResult>;

package/src/orchestrator/renderers/tasks-markdown.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+import type { planTasksArtifactSchema } from "../contracts/phase-artifacts";
+
+type PlanTasksArtifact = z.infer<typeof planTasksArtifactSchema>;
+
+export function renderTasksMarkdown(artifact: PlanTasksArtifact): string {
+	const header = [
+		"# Implementation Task Plan",
+		"",
+		"## Task Table",
+		"",
+		"| Task ID | Title | Description | Files to Modify | Wave Number | Acceptance Criteria |",
+		"|---|---|---|---|---:|---|",
+	];
+
+	const rows = artifact.tasks.map((task) => {
+		const deps = task.depends_on.length > 0 ? `Depends on: ${task.depends_on.join(", ")}` : "None";
+		return `| ${task.taskId} | ${task.title.replace(/\|/g, "\\|")} | ${deps} | TBD | ${task.wave} | TBD |`;
+	});
+
+	return [...header, ...rows, ""].join("\n");
+}

package/src/orchestrator/replay.ts

@@ -0,0 +1,14 @@
+import { orchestrateCore } from "../tools/orchestrate";
+import type { ResultEnvelope } from "./contracts/result-envelope";
+
+export async function replayEnvelopes(
+	artifactDir: string,
+	envelopes: readonly ResultEnvelope[],
+): Promise<readonly string[]> {
+	const outputs: string[] = [];
+	for (const envelope of envelopes) {
+		const result = await orchestrateCore({ result: JSON.stringify(envelope) }, artifactDir);
+		outputs.push(result);
+	}
+	return Object.freeze(outputs);
+}

package/src/orchestrator/schemas.ts

@@ -55,6 +55,21 @@ export const buildProgressSchema = z.object({
 	reviewPending: z.boolean().default(false),
 });
 
+export const dispatchResultKindSchema = z.enum([
+	"phase_output",
+	"task_completion",
+	"review_findings",
+]);
+
+export const pendingDispatchSchema = z.object({
+	dispatchId: z.string().min(1).max(128),
+	phase: phaseSchema,
+	agent: z.string().min(1).max(128),
+	issuedAt: z.string().max(128),
+	resultKind: dispatchResultKindSchema.default("phase_output"),
+	taskId: z.number().int().positive().nullable().default(null),
+});
+
 export const failureContextSchema = z.object({
 	failedPhase: phaseSchema,
 	failedAgent: z.string().max(128).nullable(),
@@ -66,6 +81,8 @@ export const failureContextSchema = z.object({
 export const pipelineStateSchema = z.object({
 	schemaVersion: z.literal(2),
 	status: z.enum(["NOT_STARTED", "IN_PROGRESS", "COMPLETED", "FAILED"]),
+	runId: z.string().max(128).default("legacy-run"),
+	stateRevision: z.number().int().min(0).default(0),
 	idea: z.string().max(4096),
 	currentPhase: phaseSchema.nullable(),
 	startedAt: z.string().max(128),
@@ -83,6 +100,8 @@ export const pipelineStateSchema = z.object({
 		strikeCount: 0,
 		reviewPending: false,
 	}),
+	pendingDispatches: z.array(pendingDispatchSchema).max(2000).default([]),
+	processedResultIds: z.array(z.string().max(128)).max(10_000).default([]),
 	failureContext: failureContextSchema.nullable().default(null),
 	phaseDispatchCounts: z.record(z.string().max(32), z.number().int().min(0).max(1000)).default({}),
 });

package/src/orchestrator/state.ts

@@ -2,16 +2,23 @@ import { randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { ensureDir, isEnoentError } from "../utils/fs-helpers";
+import { assertStateInvariants } from "./contracts/invariants";
 import { PHASES, pipelineStateSchema } from "./schemas";
 import type { PipelineState } from "./types";
 
 const STATE_FILE = "state.json";
 
+function generateRunId(): string {
+	return `run_${randomBytes(8).toString("hex")}`;
+}
+
 export function createInitialState(idea: string): PipelineState {
 	const now = new Date().toISOString();
 	return pipelineStateSchema.parse({
 		schemaVersion: 2,
 		status: "IN_PROGRESS",
+		runId: generateRunId(),
+		stateRevision: 0,
 		idea,
 		currentPhase: "RECON",
 		startedAt: now,
@@ -25,6 +32,8 @@ export function createInitialState(idea: string): PipelineState {
 		tasks: [],
 		arenaConfidence: null,
 		exploreTriggered: false,
+		pendingDispatches: [],
+		processedResultIds: [],
 	});
 }
 
@@ -42,8 +51,23 @@ export async function loadState(artifactDir: string): Promise<PipelineState | nu
 	}
 }
 
-export async function saveState(state: PipelineState, artifactDir: string): Promise<void> {
+export async function saveState(
+	state: PipelineState,
+	artifactDir: string,
+	expectedRevision?: number,
+): Promise<void> {
+	if (typeof expectedRevision === "number") {
+		const current = await loadState(artifactDir);
+		const currentRevision = current?.stateRevision ?? -1;
+		if (currentRevision !== expectedRevision) {
+			throw new Error(
+				`E_STATE_CONFLICT: expected stateRevision ${expectedRevision}, found ${currentRevision}`,
+			);
+		}
+	}
+
 	const validated = pipelineStateSchema.parse(state);
+	assertStateInvariants(validated);
 	await ensureDir(artifactDir);
 	const statePath = join(artifactDir, STATE_FILE);
 	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
@@ -55,20 +79,38 @@ export function patchState(
 	current: Readonly<PipelineState>,
 	updates: Partial<PipelineState>,
 ): PipelineState {
+	const now = new Date().toISOString();
 	const merged = {
 		...current,
 		...updates,
-		lastUpdatedAt: new Date().toISOString(),
+		stateRevision: current.stateRevision + 1,
+		lastUpdatedAt: now,
 	};
-	return pipelineStateSchema.parse(merged);
+
+	if (merged.status === "COMPLETED") {
+		merged.currentPhase = null;
+		merged.phases = merged.phases.map((phase) => {
+			if (phase.status === "IN_PROGRESS") {
+				return {
+					...phase,
+					status: "DONE" as const,
+					completedAt: phase.completedAt ?? now,
+				};
+			}
+			return phase;
+		});
+	}
+
+	const validated = pipelineStateSchema.parse(merged);
+	assertStateInvariants(validated);
+	return validated;
 }
 
 export function appendDecision(
 	current: Readonly<PipelineState>,
 	decision: { phase: string; agent: string; decision: string; rationale: string },
 ): PipelineState {
-	return {
-		...current,
+	return patchState(current, {
 		decisions: [
 			...current.decisions,
 			{
@@ -76,6 +118,5 @@ export function appendDecision(
 				timestamp: new Date().toISOString(),
 			},
 		],
-		lastUpdatedAt: new Date().toISOString(),
-	};
+	});
 }

package/src/orchestrator/types.ts

@@ -3,7 +3,9 @@ import type {
 	buildProgressSchema,
 	confidenceEntrySchema,
 	decisionEntrySchema,
+	dispatchResultKindSchema,
 	failureContextSchema,
+	pendingDispatchSchema,
 	phaseSchema,
 	phaseStatusSchema,
 	pipelineStateSchema,
@@ -18,3 +20,5 @@ export type ConfidenceEntry = z.infer<typeof confidenceEntrySchema>;
 export type Task = z.infer<typeof taskSchema>;
 export type BuildProgress = z.infer<typeof buildProgressSchema>;
 export type FailureContext = z.infer<typeof failureContextSchema>;
+export type PendingDispatch = z.infer<typeof pendingDispatchSchema>;
+export type DispatchResultKind = z.infer<typeof dispatchResultKindSchema>;

package/src/review/pipeline.ts

@@ -19,8 +19,8 @@ const STAGE3_NAMES: ReadonlySet<string> = new Set(STAGE3_AGENTS.map((a) => a.nam
 
 import { buildFixInstructions, determineFixableFindings } from "./fix-cycle";
 import { buildReport } from "./report";
-import { reviewFindingSchema } from "./schemas";
-import type { ReviewFinding, ReviewReport, ReviewState } from "./types";
+import { reviewFindingSchema, reviewFindingsEnvelopeSchema } from "./schemas";
+import type { ReviewFinding, ReviewFindingsEnvelope, ReviewReport, ReviewState } from "./types";
 
 export type { ReviewState };
 
@@ -32,8 +32,19 @@ export interface ReviewStageResult {
 	readonly stage?: number;
 	readonly agents?: readonly { readonly name: string; readonly prompt: string }[];
 	readonly report?: ReviewReport;
+	readonly findingsEnvelope?: ReviewFindingsEnvelope;
 	readonly message?: string;
 	readonly state?: ReviewState;
+	readonly parseMode?: "typed" | "legacy";
+}
+
+function parseTypedFindingsEnvelope(raw: string): ReviewFindingsEnvelope | null {
+	try {
+		const parsed = JSON.parse(raw);
+		return reviewFindingsEnvelopeSchema.parse(parsed);
+	} catch {
+		return null;
+	}
 }
 
 /**
@@ -145,8 +156,11 @@ export function advancePipeline(
 	currentState: ReviewState,
 	agentName = "unknown",
 ): ReviewStageResult {
-	// Parse new findings
-	const newFindings = parseAgentFindings(findingsJson, agentName);
+	const typedEnvelope = parseTypedFindingsEnvelope(findingsJson);
+	const parseMode = typedEnvelope ? "typed" : "legacy";
+	const newFindings = typedEnvelope
+		? typedEnvelope.findings
+		: parseAgentFindings(findingsJson, agentName);
 	const accumulated = [...currentState.accumulatedFindings, ...newFindings];
 
 	const nextStage = currentState.stage + 1;
@@ -169,6 +183,7 @@ export function advancePipeline(
 				action: "dispatch" as const,
 				stage: nextStage,
 				agents: prompts,
+				parseMode,
 				state: newState,
 			});
 		}
@@ -193,6 +208,7 @@ export function advancePipeline(
 				action: "dispatch" as const,
 				stage: nextStage,
 				agents: Object.freeze(stage3Prompts.map((p) => Object.freeze(p))),
+				parseMode,
 				state: newState,
 			});
 		}
@@ -217,18 +233,37 @@ export function advancePipeline(
 					stage: nextStage,
 					message: "Fix cycle: CRITICAL findings with actionable suggestions detected.",
 					agents: Object.freeze(fixAgents),
+					parseMode,
 					state: newState,
 				});
 			}
 			// No fix cycle needed -- complete
 			const report = buildReport(accumulated, currentState.scope, currentState.selectedAgentNames);
-			return Object.freeze({ action: "complete" as const, report });
+			return Object.freeze({
+				action: "complete" as const,
+				report,
+				findingsEnvelope: Object.freeze({
+					schemaVersion: 1 as const,
+					kind: "review_findings" as const,
+					findings: accumulated,
+				}),
+				parseMode,
+			});
 		}
 
 		case 4: {
 			// Stage 4 -> complete: Build final report with all findings
 			const report = buildReport(accumulated, currentState.scope, currentState.selectedAgentNames);
-			return Object.freeze({ action: "complete" as const, report });
+			return Object.freeze({
+				action: "complete" as const,
+				report,
+				findingsEnvelope: Object.freeze({
+					schemaVersion: 1 as const,
+					kind: "review_findings" as const,
+					findings: accumulated,
+				}),
+				parseMode,
+			});
 		}
 
 		default:

package/src/review/schemas.ts

@@ -65,6 +65,12 @@ export const reviewStateSchema = z.object({
 	startedAt: z.string().max(128),
 });
 
+export const reviewFindingsEnvelopeSchema = z.object({
+	schemaVersion: z.literal(1).default(1),
+	kind: z.literal("review_findings"),
+	findings: z.array(reviewFindingSchema).max(500).default([]),
+});
+
 export const reviewConfigSchema = z.object({
 	parallel: z.boolean().default(true),
 	maxFixAttempts: z.number().int().min(0).max(10).default(3),