@kodrunhq/opencode-autopilot 1.15.2 → 1.17.0

package/src/tools/orchestrate.ts

@@ -1,20 +1,33 @@
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
 import { tool } from "@opencode-ai/plugin";
-import { parseResultEnvelope } from "../orchestrator/contracts/legacy-result-adapter";
-import type { ResultEnvelope } from "../orchestrator/contracts/result-envelope";
+import { getLogger } from "../logging/domains";
+import { parseTypedResultEnvelope } from "../orchestrator/contracts/legacy-result-adapter";
+import type { PendingDispatch, ResultEnvelope } from "../orchestrator/contracts/result-envelope";
+import { enrichErrorMessage } from "../orchestrator/error-context";
 import { PHASE_HANDLERS } from "../orchestrator/handlers/index";
 import type { DispatchResult, PhaseHandlerContext } from "../orchestrator/handlers/types";
 import { buildLessonContext } from "../orchestrator/lesson-injection";
 import { loadLessonMemory } from "../orchestrator/lesson-memory";
 import { logOrchestrationEvent } from "../orchestrator/orchestration-logger";
 import { completePhase, getNextPhase, PHASE_INDEX, TOTAL_PHASES } from "../orchestrator/phase";
+import { getPhaseProgressString } from "../orchestrator/progress";
 import { loadAdaptiveSkillContext } from "../orchestrator/skill-injection";
-import { createInitialState, loadState, patchState, saveState } from "../orchestrator/state";
-import type { PendingDispatch, Phase, PipelineState } from "../orchestrator/types";
+import {
+	createInitialState,
+	isStateConflictError,
+	loadState,
+	patchState,
+	saveState,
+	updatePersistedState,
+} from "../orchestrator/state";
+import type { Phase, PipelineState } from "../orchestrator/types";
 import { isEnoentError } from "../utils/fs-helpers";
 import { ensureGitignore } from "../utils/gitignore";
-import { getGlobalConfigDir, getProjectArtifactDir } from "../utils/paths";
+import {
+	getGlobalConfigDir,
+	getProjectArtifactDir,
+	getProjectRootFromArtifactDir,
+} from "../utils/paths";
 import { reviewCore } from "./review";
 
 interface OrchestrateArgs {
@@ -28,6 +41,8 @@ const ORCHESTRATE_ERROR_CODES = Object.freeze({
 	PHASE_MISMATCH: "E_PHASE_MISMATCH",
 	UNKNOWN_DISPATCH: "E_UNKNOWN_DISPATCH",
 	DUPLICATE_RESULT: "E_DUPLICATE_RESULT",
+	PENDING_RESULT_REQUIRED: "E_PENDING_RESULT_REQUIRED",
+	RESULT_KIND_MISMATCH: "E_RESULT_KIND_MISMATCH",
 });
 
 function createDispatchId(): string {
@@ -56,6 +71,10 @@ function removePendingDispatch(state: Readonly<PipelineState>, dispatchId: strin
 	});
 }
 
+function expectedResultKindForPending(pending: Readonly<PendingDispatch>): string {
+	return pending.resultKind;
+}
+
 function markResultProcessed(
 	state: Readonly<PipelineState>,
 	envelope: ResultEnvelope,
@@ -172,6 +191,11 @@ function applyResultEnvelope(
 			`${ORCHESTRATE_ERROR_CODES.PHASE_MISMATCH}: result phase ${envelope.phase} != pending ${pending.phase}`,
 		);
 	}
+	if (expectedResultKindForPending(pending) !== envelope.kind) {
+		throw new Error(
+			`${ORCHESTRATE_ERROR_CODES.RESULT_KIND_MISMATCH}: result kind ${envelope.kind} != pending ${pending.resultKind}`,
+		);
+	}
 	if (pending.taskId !== null && envelope.taskId !== pending.taskId) {
 		throw new Error(
 			`${ORCHESTRATE_ERROR_CODES.PHASE_MISMATCH}: taskId ${String(envelope.taskId)} != pending ${pending.taskId}`,
@@ -207,9 +231,7 @@ async function applyStateUpdates(
 ): Promise<PipelineState> {
 	const updates = handlerResult._stateUpdates;
 	if (updates) {
-		const updated = patchState(state, updates);
-		await saveState(updated, artifactDir);
-		return updated;
+		return updatePersistedState(artifactDir, state, (current) => patchState(current, updates));
 	}
 	return state;
 }
@@ -228,7 +250,7 @@ async function maybeInlineReview(
 		handlerResult.agent === "oc-reviewer" &&
 		handlerResult.prompt
 	) {
-		const projectRoot = join(artifactDir, "..");
+		const projectRoot = getProjectRootFromArtifactDir(artifactDir);
 		const reviewResult = await reviewCore({ scope: "branch" }, projectRoot);
 		return { inlined: true, reviewResult };
 	}
@@ -245,7 +267,7 @@ async function injectLessonContext(
 	artifactDir: string,
 ): Promise<string> {
 	try {
-		const projectRoot = join(artifactDir, "..");
+		const projectRoot = getProjectRootFromArtifactDir(artifactDir);
 		const memory = await loadLessonMemory(projectRoot);
 		if (memory && memory.lessons.length > 0) {
 			const ctx = buildLessonContext(memory.lessons, phase as Phase);
@@ -291,17 +313,16 @@ async function injectSkillContext(
 		});
 		if (ctx) return prompt + ctx;
 	} catch (err) {
-		console.warn("[opencode-autopilot] skill injection failed:", err);
+		getLogger("tool", "orchestrate").warn("skill injection failed", { err });
 	}
 	return prompt;
 }
 
 /** Build a human-readable progress string for user-facing display. */
-function buildUserProgress(phase: string, label?: string, attempt?: number): string {
-	const idx = PHASE_INDEX[phase as Phase] ?? 0;
-	const desc = label ?? "dispatching";
+function buildUserProgress(state: PipelineState, label?: string, attempt?: number): string {
+	const baseProgress = getPhaseProgressString(state);
 	const att = attempt != null ? ` (attempt ${attempt})` : "";
-	return `Phase ${idx}/${TOTAL_PHASES}: ${phase} — ${desc}${att}`;
+	return `${baseProgress}${label ? ` — ${label}` : ""}${att}`;
 }
 
 /** Per-phase dispatch limits. BUILD is high because of multi-task waves. */
@@ -332,26 +353,33 @@ async function checkCircuitBreaker(
 }> {
 	const counts = { ...(currentState.phaseDispatchCounts ?? {}) };
 	counts[phase] = (counts[phase] ?? 0) + 1;
-	const newCount = counts[phase];
+	const candidateCount = counts[phase];
 	const limit = MAX_PHASE_DISPATCHES[phase] ?? 5;
-	if (newCount > limit) {
-		const msg = `Phase ${phase} exceeded max dispatches (${newCount}/${limit}) — possible infinite loop detected. Aborting.`;
+	if (candidateCount > limit) {
+		const msg = `Phase ${phase} exceeded max dispatches (${candidateCount}/${limit}) — possible infinite loop detected. Aborting.`;
 		logOrchestrationEvent(artifactDir, {
 			timestamp: new Date().toISOString(),
 			phase,
 			action: "loop_detected",
-			attempt: newCount,
+			attempt: candidateCount,
 			message: msg,
 		});
 		return {
 			abortMsg: JSON.stringify({ action: "error", message: msg }),
-			newCount,
+			newCount: candidateCount,
 			nextState: currentState,
 		};
 	}
-	const withCounts = patchState(currentState, { phaseDispatchCounts: counts });
-	await saveState(withCounts, artifactDir);
-	return { abortMsg: null, newCount, nextState: withCounts };
+	const withCounts = await updatePersistedState(artifactDir, currentState, (current) => {
+		const nextCounts = { ...(current.phaseDispatchCounts ?? {}) };
+		nextCounts[phase] = (nextCounts[phase] ?? 0) + 1;
+		return patchState(current, { phaseDispatchCounts: nextCounts });
+	});
+	return {
+		abortMsg: null,
+		newCount: withCounts.phaseDispatchCounts[phase] ?? candidateCount,
+		nextState: withCounts,
+	};
 }
 
 /**
@@ -400,11 +428,9 @@ async function processHandlerResult(
 				resultKind: normalizedResult.expectedResultKind ?? "phase_output",
 				taskId: normalizedResult.taskId ?? null,
 			};
-			const baseRevision = currentState.stateRevision;
-			const withPendingState = withPendingDispatch(currentState, pendingEntry);
 
 			// Log the dispatch event before any inline-review or context injection
-			const progress = buildUserProgress(phase, normalizedResult.progress, attempt);
+			const progress = buildUserProgress(currentState, normalizedResult.progress, attempt);
 			logOrchestrationEvent(artifactDir, {
 				timestamp: new Date().toISOString(),
 				phase,
@@ -417,7 +443,7 @@ async function processHandlerResult(
 			// Check if this is a review dispatch that should be inlined
 			const { inlined, reviewResult } = await maybeInlineReview(normalizedResult, artifactDir);
 			if (inlined && reviewResult) {
-				if (withPendingState.currentPhase) {
+				if (currentState.currentPhase) {
 					let reviewPayloadText = reviewResult;
 					try {
 						const parsedReview = JSON.parse(reviewResult) as {
@@ -433,8 +459,8 @@ async function processHandlerResult(
 					const inlinedEnvelope: ResultEnvelope = {
 						schemaVersion: 1,
 						resultId: `inline-${createDispatchId()}`,
-						runId: withPendingState.runId,
-						phase: withPendingState.currentPhase,
+						runId: currentState.runId,
+						phase: currentState.currentPhase,
 						dispatchId: pendingEntry.dispatchId,
 						agent: normalizedResult.agent ?? null,
 						kind: "review_findings",
@@ -443,13 +469,16 @@ async function processHandlerResult(
 							text: reviewPayloadText,
 						},
 					};
-					const withInlineResult = applyResultEnvelope(withPendingState, inlinedEnvelope);
-					await saveState(withInlineResult, artifactDir, baseRevision);
+					const withInlineResult = await updatePersistedState(
+						artifactDir,
+						currentState,
+						(current) =>
+							applyResultEnvelope(withPendingDispatch(current, pendingEntry), inlinedEnvelope),
+					);
 
-					const handler = PHASE_HANDLERS[withPendingState.currentPhase];
+					const handler = PHASE_HANDLERS[currentState.currentPhase];
 					const nextResult = await handler(withInlineResult, artifactDir, reviewPayloadText, {
 						envelope: inlinedEnvelope,
-						legacy: false,
 					});
 					return processHandlerResult(nextResult, withInlineResult, artifactDir);
 				}
@@ -461,8 +490,9 @@ async function processHandlerResult(
 				});
 			}
 
-			await saveState(withPendingState, artifactDir, baseRevision);
-			currentState = withPendingState;
+			currentState = await updatePersistedState(artifactDir, currentState, (current) =>
+				withPendingDispatch(current, pendingEntry),
+			);
 
 			// Inject lesson + skill context into dispatch prompt (best-effort)
 			if (normalizedResult.prompt && normalizedResult.phase) {
@@ -473,7 +503,7 @@ async function processHandlerResult(
 				);
 				const withSkills = await injectSkillContext(
 					enrichedPrompt,
-					join(artifactDir, ".."),
+					getProjectRootFromArtifactDir(artifactDir),
 					normalizedResult.phase,
 				);
 				if (withSkills !== normalizedResult.prompt) {
@@ -514,13 +544,8 @@ async function processHandlerResult(
 					resultKind: entry.resultKind ?? inferExpectedResultKindForAgent(entry.agent),
 					taskId: entry.taskId ?? null,
 				})) ?? [];
-			const baseRevision = currentState.stateRevision;
-			let withPendingState = currentState;
-			for (const entry of pendingEntries) {
-				withPendingState = withPendingDispatch(withPendingState, entry);
-			}
 
-			const progress = buildUserProgress(phase, normalizedResult.progress, attempt);
+			const progress = buildUserProgress(currentState, normalizedResult.progress, attempt);
 			logOrchestrationEvent(artifactDir, {
 				timestamp: new Date().toISOString(),
 				phase,
@@ -528,8 +553,13 @@ async function processHandlerResult(
 				agent: `${normalizedResult.agents?.length ?? 0} agents`,
 				attempt,
 			});
-			await saveState(withPendingState, artifactDir, baseRevision);
-			currentState = withPendingState;
+			currentState = await updatePersistedState(artifactDir, currentState, (current) => {
+				let nextState = current;
+				for (const entry of pendingEntries) {
+					nextState = withPendingDispatch(nextState, entry);
+				}
+				return nextState;
+			});
 
 			// Inject lesson + skill context into each agent's prompt (best-effort)
 			// Load lesson and skill context once and reuse for all agents in the batch
@@ -537,7 +567,7 @@ async function processHandlerResult(
 				const lessonSuffix = await injectLessonContext("", normalizedResult.phase, artifactDir);
 				const skillSuffix = await injectSkillContext(
 					"",
-					join(artifactDir, ".."),
+					getProjectRootFromArtifactDir(artifactDir),
 					normalizedResult.phase,
 				);
 				const combinedSuffix = lessonSuffix + (skillSuffix || "");
@@ -575,12 +605,11 @@ async function processHandlerResult(
 				action: "complete",
 			});
 			const nextPhase = getNextPhase(currentState.currentPhase);
-			const advanced = completePhase(currentState);
+			const advanced = await updatePersistedState(artifactDir, currentState, (current) =>
+				completePhase(current),
+			);
 
 			if (nextPhase === null) {
-				// Terminal phase completed
-				const finished = { ...advanced, status: "COMPLETED" as const };
-				await saveState(finished, artifactDir);
 				const idx = PHASE_INDEX[currentState.currentPhase] ?? TOTAL_PHASES;
 				return JSON.stringify({
 					action: "complete",
@@ -589,8 +618,6 @@ async function processHandlerResult(
 				});
 			}
 
-			await saveState(advanced, artifactDir);
-
 			// Invoke the next phase handler immediately
 			const nextHandler = PHASE_HANDLERS[nextPhase];
 			const nextResult = await nextHandler(advanced, artifactDir, undefined, undefined);
@@ -624,7 +651,7 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 
 			// Best-effort .gitignore update
 			try {
-				const projectRoot = join(artifactDir, "..");
+				const projectRoot = getProjectRootFromArtifactDir(artifactDir);
 				await ensureGitignore(projectRoot);
 			} catch {
 				// Swallow gitignore errors -- non-critical
@@ -647,6 +674,18 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 				});
 			}
 
+			if (args.result === undefined && state.pendingDispatches.length > 0) {
+				const pending = state.pendingDispatches.at(-1);
+				const msg = `Pending result required for dispatch ${pending?.dispatchId ?? "unknown"} (${pending?.agent ?? "unknown"} / ${pending?.phase ?? state.currentPhase}). Submit a typed result envelope before calling oc_orchestrate again.`;
+				logDeterministicError(
+					artifactDir,
+					pending?.phase ?? state.currentPhase,
+					ORCHESTRATE_ERROR_CODES.PENDING_RESULT_REQUIRED,
+					msg,
+				);
+				return asErrorJson(ORCHESTRATE_ERROR_CODES.PENDING_RESULT_REQUIRED, msg);
+			}
+
 			if (typeof args.result === "string") {
 				const phaseHint = detectPhaseFromPending(state);
 				if (phaseHint === null) {
@@ -661,7 +700,7 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 				}
 
 				try {
-					const parsed = parseResultEnvelope(args.result, {
+					const parsed = parseTypedResultEnvelope(args.result, {
 						runId: state.runId,
 						phase: phaseHint,
 						fallbackDispatchId: detectDispatchFromPending(state),
@@ -679,39 +718,13 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 						return asErrorJson(ORCHESTRATE_ERROR_CODES.STALE_RESULT, msg);
 					}
 
-					if (parsed.legacy && state.pendingDispatches.length > 1) {
-						const msg =
-							"Legacy result payload cannot be attributed with multiple pending dispatches. Provide typed envelope with dispatchId/taskId.";
-						logDeterministicError(
-							artifactDir,
-							state.currentPhase ?? phaseHint,
-							ORCHESTRATE_ERROR_CODES.INVALID_RESULT,
-							msg,
-						);
-						return asErrorJson(ORCHESTRATE_ERROR_CODES.INVALID_RESULT, msg);
-					}
-
-					const allowMissingPending = parsed.legacy && state.pendingDispatches.length === 0;
-					const nextState = applyResultEnvelope(state, parsed.envelope, {
-						allowMissingPending,
-					});
-					await saveState(nextState, artifactDir);
+					const nextState = await updatePersistedState(artifactDir, state, (current) =>
+						applyResultEnvelope(current, parsed.envelope),
+					);
 					state = nextState;
-					if (!allowMissingPending && parsed.legacy) {
-						const legacyMsg =
-							"Legacy result parser path used. Submit typed envelopes for deterministic replay guarantees.";
-						logOrchestrationEvent(artifactDir, {
-							timestamp: new Date().toISOString(),
-							phase: state.currentPhase ?? phaseHint,
-							action: "error",
-							message: legacyMsg,
-						});
-						console.warn(`[opencode-autopilot] ${legacyMsg}`);
-					}
 
 					phaseHandlerContext = {
 						envelope: parsed.envelope,
-						legacy: parsed.legacy,
 					};
 					handlerInputResult = parsed.envelope.payload.text;
 				} catch (error: unknown) {
@@ -747,12 +760,13 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 	} catch (error: unknown) {
 		const message = error instanceof Error ? error.message : String(error);
 		const parsedErr = parseErrorCode(error);
-		const safeMessage = message.replace(/[/\\][^\s"']+/g, "[PATH]").slice(0, 4096);
+		let safeMessage = message.replace(/[/\\][^\s"']+/g, "[PATH]").slice(0, 4096);
 
 		// Persist failure metadata for forensics (best-effort)
 		try {
 			const currentState = await loadState(artifactDir);
 			if (currentState?.currentPhase) {
+				safeMessage = enrichErrorMessage(safeMessage, currentState);
 				const lastDone = currentState.phases.filter((p) => p.status === "DONE").pop();
 				const failureContext = {
 					failedPhase: currentState.currentPhase,
@@ -761,13 +775,17 @@ export async function orchestrateCore(args: OrchestrateArgs, artifactDir: string
 					timestamp: new Date().toISOString(),
 					lastSuccessfulPhase: lastDone?.name ?? null,
 				};
-				const failed = patchState(currentState, {
-					status: "FAILED" as const,
-					failureContext,
-				});
-				await saveState(failed, artifactDir);
+				await updatePersistedState(artifactDir, currentState, (latest) =>
+					patchState(latest, {
+						status: "FAILED" as const,
+						failureContext,
+					}),
+				);
+			}
+		} catch (persistError: unknown) {
+			if (isStateConflictError(persistError)) {
+				// Swallow conflict after retry exhaustion -- original error takes priority
 			}
-		} catch {
 			// Swallow save errors -- original error takes priority
 		}
 

package/src/tools/pipeline-report.ts

@@ -103,9 +103,10 @@ function buildDisplayText(
  * @param logsDir - Optional override for logs directory (for testing)
  */
 export async function pipelineReportCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const logsRoot = logsDir ?? process.cwd();
 	const log = sessionID
-		? await readSessionLog(sessionID, logsDir)
-		: await readLatestSessionLog(logsDir);
+		? await readSessionLog(sessionID, logsRoot)
+		: await readLatestSessionLog(logsRoot);
 
 	if (!log) {
 		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";

package/src/tools/quick.ts

@@ -5,7 +5,7 @@ import { ensurePhaseDir } from "../orchestrator/artifacts";
 import { PHASES, pipelineStateSchema } from "../orchestrator/schemas";
 import { loadState, saveState } from "../orchestrator/state";
 import { ensureGitignore } from "../utils/gitignore";
-import { getProjectArtifactDir } from "../utils/paths";
+import { getProjectArtifactDir, getProjectRootFromArtifactDir } from "../utils/paths";
 import { orchestrateCore } from "./orchestrate";
 
 /** Phases skipped in quick mode (per D-17: skip RECON, CHALLENGE, ARCHITECT, EXPLORE). */
@@ -109,7 +109,7 @@ export async function quickCore(args: QuickArgs, artifactDir: string): Promise<s
 
 	// 6. Best-effort .gitignore update (same pattern as orchestrateCore)
 	try {
-		await ensureGitignore(join(artifactDir, ".."));
+		await ensureGitignore(getProjectRootFromArtifactDir(artifactDir));
 	} catch {
 		// Non-critical -- swallow gitignore errors
 	}

package/src/tools/replay.ts

@@ -0,0 +1,42 @@
+import { tool } from "@opencode-ai/plugin";
+import type { ReviewState } from "../review/types";
+
+export const ocReplay = tool({
+	description:
+		"Verify determinism by replaying a known sequence of inputs to the review pipeline and ensuring identical state output.",
+	args: {
+		runId: tool.schema.string().describe("The pipeline runId to use as the random seed for replay"),
+		inputs: tool.schema
+			.array(tool.schema.string())
+			.describe("Array of raw JSON findings inputs to feed sequentially into the pipeline"),
+	},
+	async execute(args) {
+		const { advancePipeline } = await import("../review/pipeline");
+
+		let currentState: ReviewState = {
+			stage: 1,
+			scope: "replay-scope",
+			selectedAgentNames: ["logic-auditor", "security-auditor"],
+			accumulatedFindings: [],
+			startedAt: "2026-04-05T00:00:00.000Z",
+		};
+
+		for (const input of args.inputs) {
+			const res = advancePipeline(input, currentState, undefined, args.runId, args.runId);
+			if (res.state) {
+				currentState = res.state;
+			}
+		}
+
+		return JSON.stringify(
+			{
+				success: true,
+				message: `Replayed ${args.inputs.length} inputs deterministically.`,
+				replayedRunId: args.runId,
+				finalState: currentState,
+			},
+			null,
+			2,
+		);
+	},
+});

package/src/tools/review.ts

@@ -17,6 +17,13 @@ import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { tool } from "@opencode-ai/plugin";
+import {
+	clearActiveReviewStateInKernel,
+	loadActiveReviewStateFromKernel,
+	saveActiveReviewStateToKernel,
+} from "../kernel/repository";
+import { getLogger } from "../logging/domains";
+import { loadState as loadPipelineState } from "../orchestrator/state";
 import { REVIEW_AGENTS, SPECIALIZED_AGENTS } from "../review/agents/index";
 import {
 	createEmptyMemory,
@@ -42,6 +49,7 @@ interface ReviewArgs {
 const execFileAsync = promisify(execFile);
 
 const STATE_FILE = "current-review.json";
+let legacyReviewStateMirrorWarned = false;
 
 /**
  * Get changed file paths for the given review scope.
@@ -83,11 +91,18 @@ async function getChangedFiles(
  * Load review state from disk. Returns null if no active review.
  */
 async function loadReviewState(artifactDir: string): Promise<ReviewState | null> {
+	const kernelState = loadActiveReviewStateFromKernel(artifactDir);
+	if (kernelState !== null) {
+		return kernelState;
+	}
+
 	const statePath = join(artifactDir, STATE_FILE);
 	try {
 		const raw = await readFile(statePath, "utf-8");
 		const parsed = JSON.parse(raw);
-		return reviewStateSchema.parse(parsed) as ReviewState;
+		const validated = reviewStateSchema.parse(parsed) as ReviewState;
+		saveActiveReviewStateToKernel(artifactDir, validated);
+		return validated;
 	} catch (error: unknown) {
 		if (isEnoentError(error)) return null;
 		// Treat parse/schema errors as recoverable — delete corrupt file
@@ -103,23 +118,43 @@ async function loadReviewState(artifactDir: string): Promise<ReviewState | null>
 	}
 }
 
+async function writeLegacyReviewStateMirror(
+	state: ReviewState,
+	artifactDir: string,
+): Promise<void> {
+	await ensureDir(artifactDir);
+	const statePath = join(artifactDir, STATE_FILE);
+	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
+	await writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+	await rename(tmpPath, statePath);
+}
+
+async function syncLegacyReviewStateMirror(state: ReviewState, artifactDir: string): Promise<void> {
+	try {
+		await writeLegacyReviewStateMirror(state, artifactDir);
+	} catch (error: unknown) {
+		if (!legacyReviewStateMirrorWarned) {
+			legacyReviewStateMirrorWarned = true;
+			getLogger("tool", "review").warn("current-review.json mirror write failed", { error });
+		}
+	}
+}
+
 /**
  * Save review state atomically.
  */
 async function saveReviewState(state: ReviewState, artifactDir: string): Promise<void> {
-	await ensureDir(artifactDir);
 	// Validate before writing (bidirectional validation, same as orchestrator state)
 	const validated = reviewStateSchema.parse(state);
-	const statePath = join(artifactDir, STATE_FILE);
-	const tmpPath = `${statePath}.tmp.${randomBytes(8).toString("hex")}`;
-	await writeFile(tmpPath, JSON.stringify(validated, null, 2), "utf-8");
-	await rename(tmpPath, statePath);
+	saveActiveReviewStateToKernel(artifactDir, validated);
+	await syncLegacyReviewStateMirror(validated, artifactDir);
 }
 
 /**
  * Delete review state file (pipeline complete or error cleanup).
  */
 async function clearReviewState(artifactDir: string): Promise<void> {
+	clearActiveReviewStateInKernel(artifactDir);
 	const statePath = join(artifactDir, STATE_FILE);
 	try {
 		await unlink(statePath);
@@ -157,7 +192,11 @@ async function startNewReview(
 
 	// Select agents from all candidates (universal + specialized)
 	const allCandidates = [...REVIEW_AGENTS, ...SPECIALIZED_AGENTS];
-	const selection = selectAgents(detectedStacks, diffAnalysis, allCandidates);
+	const artifactDir = getProjectArtifactDir(projectRoot);
+	const pipelineState = await loadPipelineState(artifactDir);
+	const seed = pipelineState ? `${pipelineState.runId}-review-1` : undefined;
+
+	const selection = selectAgents(detectedStacks, diffAnalysis, allCandidates, { seed });
 
 	const selectedNames = selection.selected.map((a) => a.name);
 

package/src/tools/session-stats.ts

@@ -138,9 +138,10 @@ function buildDisplayText(
  * @param logsDir - Optional override for logs directory (for testing)
  */
 export async function sessionStatsCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const logsRoot = logsDir ?? process.cwd();
 	const log = sessionID
-		? await readSessionLog(sessionID, logsDir)
-		: await readLatestSessionLog(logsDir);
+		? await readSessionLog(sessionID, logsRoot)
+		: await readLatestSessionLog(logsRoot);
 
 	if (!log) {
 		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";

package/src/tools/summary.ts

@@ -0,0 +1,43 @@
+import { tool } from "@opencode-ai/plugin";
+import { z } from "zod";
+import { readLatestSessionLog, readSessionLog } from "../observability/log-reader";
+import { generateSessionSummary } from "../observability/summary-generator";
+
+export async function summaryCore(sessionID?: string, logsDir?: string): Promise<string> {
+	const logsRoot = logsDir ?? process.cwd();
+	const log = sessionID
+		? await readSessionLog(sessionID, logsRoot)
+		: await readLatestSessionLog(logsRoot);
+
+	if (!log) {
+		const target = sessionID ? `Session "${sessionID}" not found.` : "No session logs found.";
+		return JSON.stringify({
+			action: "error",
+			message: target,
+		});
+	}
+
+	const summary = generateSessionSummary(log);
+
+	return JSON.stringify({
+		action: "session_summary",
+		sessionId: log.sessionId,
+		summary,
+		displayText: summary,
+	});
+}
+
+export const ocSummary = tool({
+	description:
+		"Generate a markdown summary for the latest session or a specific session ID. Use this to review session outcomes, decisions, and errors.",
+	args: {
+		sessionID: z
+			.string()
+			.regex(/^[a-zA-Z0-9_-]{1,256}$/)
+			.optional()
+			.describe("Session ID to summarize (uses latest if omitted)"),
+	},
+	async execute({ sessionID }) {
+		return summaryCore(sessionID);
+	},
+});