@phi-code-admin/phi-code 0.86.0 → 0.88.0

package/extensions/phi/orchestrator.ts

@@ -16,20 +16,21 @@
  *   /plans  — List plans and their execution status
  */
 
-import { Type } from "@sinclair/typebox";
-import type { ExtensionAPI } from "phi-code";
-import { writeFile, mkdir, readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import {
-	extractBlockingFindings,
-	extractHandoff,
-	isTransientError,
-	parsePhaseVerdict,
-} from "./providers/orchestrator-helpers.js";
-import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
+import { join } from "node:path";
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI } from "phi-code";
 import { type AgentDef, loadAgentDef } from "./providers/agent-def.js";
+import { defaultExplorerSpecs, READONLY_EXPLORER_TOOLS, runExploreFanout } from "./providers/explore-fanout.js";
+import {
+	analyzePhaseMessages,
+	buildNextBrief,
+	decidePhaseTransition,
+	resolvePhaseOutcome,
+	type StructuredPhaseResult,
+} from "./providers/phase-machine.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -58,35 +59,51 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	// ─── Plan File Generators ────────────────────────────────────────
 
 	function generateSpec(p: {
-		title: string; description: string; goals: string[]; requirements: string[];
-		architecture?: string[]; constraints?: string[]; successCriteria?: string[]; tasks: TaskDef[];
+		title: string;
+		description: string;
+		goals: string[];
+		requirements: string[];
+		architecture?: string[];
+		constraints?: string[];
+		successCriteria?: string[];
+		tasks: TaskDef[];
 	}): string {
 		let spec = `# ${p.title}\n\n`;
 		spec += `**Created:** ${new Date().toLocaleString()}\n\n`;
 		spec += `## Description\n\n${p.description}\n\n`;
 		spec += `## Goals\n\n`;
-		p.goals.forEach((g, i) => { spec += `${i + 1}. ${g}\n`; });
+		p.goals.forEach((g, i) => {
+			spec += `${i + 1}. ${g}\n`;
+		});
 		spec += "\n## Requirements\n\n";
-		p.requirements.forEach(r => { spec += `- ${r}\n`; });
+		p.requirements.forEach((r) => {
+			spec += `- ${r}\n`;
+		});
 		spec += "\n";
 		if (p.architecture?.length) {
 			spec += `## Architecture\n\n`;
-			p.architecture.forEach(a => { spec += `- ${a}\n`; });
+			p.architecture.forEach((a) => {
+				spec += `- ${a}\n`;
+			});
 			spec += "\n";
 		}
 		if (p.constraints?.length) {
 			spec += `## Constraints\n\n`;
-			p.constraints.forEach(c => { spec += `- ${c}\n`; });
+			p.constraints.forEach((c) => {
+				spec += `- ${c}\n`;
+			});
 			spec += "\n";
 		}
 		if (p.successCriteria?.length) {
 			spec += `## Success Criteria\n\n`;
-			p.successCriteria.forEach(s => { spec += `- [ ] ${s}\n`; });
+			p.successCriteria.forEach((s) => {
+				spec += `- [ ] ${s}\n`;
+			});
 			spec += "\n";
 		}
 		spec += `## Task Overview\n\n| # | Task | Agent | Priority | Dependencies |\n|---|------|-------|----------|-------------|\n`;
 		p.tasks.forEach((t, i) => {
-			const deps = t.dependencies?.map(d => `#${d}`).join(", ") || "—";
+			const deps = t.dependencies?.map((d) => `#${d}`).join(", ") || "—";
 			spec += `| ${i + 1} | ${t.title} | ${t.agent || "code"} | ${t.priority || "medium"} | ${deps} |\n`;
 		});
 		spec += `\n---\n*Generated by Phi Code Orchestrator*\n`;
@@ -102,12 +119,15 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 			const prioTag = t.priority === "high" ? " 🔴" : t.priority === "low" ? " 🟢" : " 🟡";
 			const depsTag = t.dependencies?.length ? ` (after #${t.dependencies.join(", #")})` : "";
 			todo += `## Task ${i + 1}: ${t.title}${prioTag}${agentTag}${depsTag}\n\n- [ ] ${t.description}\n`;
-			if (t.subtasks) t.subtasks.forEach(st => { todo += `  - [ ] ${st}\n`; });
+			if (t.subtasks)
+				t.subtasks.forEach((st) => {
+					todo += `  - [ ] ${st}\n`;
+				});
 			todo += "\n";
 		});
 		todo += `---\n\n## Progress\n\n- Total: ${tasks.length} tasks\n`;
-		todo += `- High priority: ${tasks.filter(t => t.priority === "high").length}\n`;
-		todo += `- Agents: ${[...new Set(tasks.map(t => t.agent || "code"))].join(", ")}\n`;
+		todo += `- High priority: ${tasks.filter((t) => t.priority === "high").length}\n`;
+		todo += `- Agents: ${[...new Set(tasks.map((t) => t.agent || "code"))].join(", ")}\n`;
 		return todo;
 	}
 
@@ -116,8 +136,10 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "orchestrate",
 		label: "Project Orchestrator",
-		description: "Create a structured project plan with spec, todo, and task breakdown. Forces the model to decompose the project into goals, requirements, architecture, constraints, and success criteria before execution.",
-		promptSnippet: "Plan + structure projects using the prompt-architect pattern. Each task gets [CONTEXT] → [TASK] → [FORMAT] → [CONSTRAINTS].",
+		description:
+			"Create a structured project plan with spec, todo, and task breakdown. Forces the model to decompose the project into goals, requirements, architecture, constraints, and success criteria before execution.",
+		promptSnippet:
+			"Plan + structure projects using the prompt-architect pattern. Each task gets [CONTEXT] → [TASK] → [FORMAT] → [CONSTRAINTS].",
 		promptGuidelines: [
 			// NOTE: The old guideline "When asked to plan or build a project, call the orchestrate tool"
 			// was REMOVED because it hijacked the /plan command flow. The orchestrate tool is now
@@ -130,30 +152,59 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		],
 		parameters: Type.Object({
 			title: Type.String({ description: "Concise project title" }),
-			description: Type.String({ description: "Full project description: what to build, why, and any relevant context" }),
-			goals: Type.Union([Type.Array(Type.String()), Type.String()], { description: "Measurable project goals (what success looks like)" }),
-			requirements: Type.Union([Type.Array(Type.String()), Type.String()], { description: "Technical and functional requirements" }),
-			architecture: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Architecture decisions, tech stack choices, trade-offs" })),
+			description: Type.String({
+				description: "Full project description: what to build, why, and any relevant context",
+			}),
+			goals: Type.Union([Type.Array(Type.String()), Type.String()], {
+				description: "Measurable project goals (what success looks like)",
+			}),
+			requirements: Type.Union([Type.Array(Type.String()), Type.String()], {
+				description: "Technical and functional requirements",
+			}),
+			architecture: Type.Optional(
+				Type.Union([Type.Array(Type.String()), Type.String()], {
+					description: "Architecture decisions, tech stack choices, trade-offs",
+				}),
+			),
 			tasks: Type.Array(
 				Type.Object({
 					title: Type.String({ description: "Clear, action-oriented task title" }),
-					description: Type.String({ description: "SELF-CONTAINED task description. Include ALL context the sub-agent needs." }),
+					description: Type.String({
+						description: "SELF-CONTAINED task description. Include ALL context the sub-agent needs.",
+					}),
 					agent: Type.Optional(Type.String({ description: "Agent type: explore, plan, code, test, review" })),
 					priority: Type.Optional(Type.String({ description: "high, medium, low" })),
-					dependencies: Type.Optional(Type.Array(Type.Number(), { description: "Task numbers this depends on (1-indexed)" })),
-					subtasks: Type.Optional(Type.Array(Type.String(), { description: "Specific sub-steps within this task" })),
+					dependencies: Type.Optional(
+						Type.Array(Type.Number(), { description: "Task numbers this depends on (1-indexed)" }),
+					),
+					subtasks: Type.Optional(
+						Type.Array(Type.String(), { description: "Specific sub-steps within this task" }),
+					),
+				}),
+				{ description: "Ordered list of tasks" },
+			),
+			constraints: Type.Optional(
+				Type.Union([Type.Array(Type.String()), Type.String()], {
+					description: "Hard constraints: things to avoid, rules",
+				}),
+			),
+			successCriteria: Type.Optional(
+				Type.Union([Type.Array(Type.String()), Type.String()], {
+					description: "How to verify the project is complete",
 				}),
-				{ description: "Ordered list of tasks" }
 			),
-			constraints: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "Hard constraints: things to avoid, rules" })),
-			successCriteria: Type.Optional(Type.Union([Type.Array(Type.String()), Type.String()], { description: "How to verify the project is complete" })),
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
 			// Block if /plan orchestration is active — prevent hijacking
 			if (orchestrationActive) {
 				return {
-					content: [{ type: "text", text: "⚠️ Orchestration is already active via /plan. Do NOT call orchestrate during /plan phases. Follow the phase instructions instead." }],
+					content: [
+						{
+							type: "text",
+							text: "⚠️ Orchestration is already active via /plan. Do NOT call orchestrate during /plan phases. Follow the phase instructions instead.",
+						},
+					],
 					details: undefined,
 				};
 			}
@@ -164,7 +215,11 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 			const toArray = (v: any): string[] => {
 				if (!v) return [];
 				if (Array.isArray(v)) return v;
-				if (typeof v === "string") return v.split("\n").map((s: string) => s.replace(/^[-•*]\s*/, "").trim()).filter(Boolean);
+				if (typeof v === "string")
+					return v
+						.split("\n")
+						.map((s: string) => s.replace(/^[-•*]\s*/, "").trim())
+						.filter(Boolean);
 				return [];
 			};
 
@@ -191,7 +246,8 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 				await writeFile(join(plansDir, specFile), spec, "utf-8");
 				await writeFile(join(plansDir, todoFile), todo, "utf-8");
 
-				const summary = `📋 **Project "${p.title}" — Structured plan created!**\n\n` +
+				const summary =
+					`📋 **Project "${p.title}" — Structured plan created!**\n\n` +
 					`**Spec:** \`${specFile}\` | **Todo:** \`${todoFile}\`\n\n` +
 					`**Goals:** ${p.goals.length} | **Requirements:** ${p.requirements.length} | **Tasks:** ${p.tasks.length}\n\n` +
 					`The spec and todo files are ready in \`.phi/plans/\`. ` +
@@ -234,7 +290,7 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	let phaseQueue: OrchestratorPhase[] = [];
 	let orchestrationActive = false;
 	let activeAgentPrompt: string | null = null;
-	let activeAgentTools: string[] | null = null;
+	let _activeAgentTools: string[] | null = null;
 	let savedTools: string[] | null = null;
 	let phasePending = false; // true while waiting for a phase to complete
 	let phaseTimeoutId: ReturnType<typeof setTimeout> | null = null;
@@ -258,13 +314,89 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	// Set true right before an INTERNAL ctx.abort() (phase timeout) so the
 	// resulting agent_end is not mistaken for a user Ctrl+C cancellation.
 	let internalAbort = false;
+	// Structured result emitted by the current phase via the `phase_result` tool
+	// (robust primary path). Reset at each phase start; read in agent_end and
+	// merged with the parsed markdown report (fallback) by resolvePhaseOutcome.
+	// currentPhaseResultKey stamps which phase produced it, so a stale result
+	// from a previous run/phase (or a tool call that lands after the phase
+	// transition) is never mistaken for the current phase's output.
+	let currentPhaseResult: StructuredPhaseResult | null = null;
+	let currentPhaseResultKey: string | null = null;
+
+	// ─── phase_result Tool — structured phase outcome (robust primary path) ───
+	// A phase agent CALLS this to emit its verdict/handoff/blocking as data
+	// instead of relying on the orchestrator regex-scraping its markdown report.
+	// It is only meaningful during /plan; outside orchestration it is a no-op so
+	// a stray call never errors. The markdown report is still written (it is the
+	// human-readable artifact); this just makes the machine-read path exact.
+	pi.registerTool({
+		name: "phase_result",
+		label: "Phase Result",
+		description:
+			"Report THIS /plan phase's structured outcome so the orchestrator reads it exactly instead of parsing your markdown. Call it once, at the end, IN ADDITION to writing your report file. TEST and REVIEW phases MUST call it with a verdict.",
+		promptGuidelines: [
+			"During a /plan phase, after writing your report file, call phase_result once with your verdict (TEST/REVIEW) and a concise handoff for the next phase.",
+			"verdict: PASS only if you OBSERVED success; FAIL if any blocking issue; BLOCKED if you could not run; SKIP if not applicable.",
+			"blocking: the must-fix findings (REVIEW), one per line. handoff: what is done, open risks, and the single most important next action.",
+		],
+		parameters: Type.Object({
+			verdict: Type.Optional(
+				Type.Union([Type.Literal("PASS"), Type.Literal("FAIL"), Type.Literal("BLOCKED"), Type.Literal("SKIP")], {
+					description: "Phase verdict (required for TEST and REVIEW phases)",
+				}),
+			),
+			blocking: Type.Optional(
+				Type.String({ description: "Must-fix findings, one per line (REVIEW). Empty when none." }),
+			),
+			handoff: Type.Optional(
+				Type.String({ description: "Concise handoff for the next phase: state, open risks, next action." }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!orchestrationActive) {
+				return {
+					content: [{ type: "text", text: "phase_result is only used during /plan orchestration; ignored here." }],
+					details: undefined,
+				};
+			}
+			const raw = params as { verdict?: StructuredPhaseResult["verdict"]; blocking?: string; handoff?: string };
+			// Merge only the fields this call actually set, so a phase that emits
+			// its result across several calls (verdict first, handoff later — a
+			// common LLM pattern) does not erase earlier fields. Start fresh when
+			// the previous result belonged to a different phase.
+			const defined: StructuredPhaseResult = {};
+			if (raw.verdict !== undefined) defined.verdict = raw.verdict;
+			if (typeof raw.blocking === "string") defined.blocking = raw.blocking;
+			if (typeof raw.handoff === "string") defined.handoff = raw.handoff;
+			const samePhase = currentPhaseResultKey === (currentPhase?.key ?? null);
+			currentPhaseResult = { ...(samePhase && currentPhaseResult ? currentPhaseResult : {}), ...defined };
+			currentPhaseResultKey = currentPhase?.key ?? null;
+			const parts = [
+				raw.verdict ? `verdict ${raw.verdict}` : null,
+				raw.blocking?.trim() ? "blocking findings" : null,
+				raw.handoff?.trim() ? "handoff" : null,
+			].filter(Boolean);
+			return {
+				content: [{ type: "text", text: `Phase result recorded${parts.length ? ` (${parts.join(", ")})` : ""}.` }],
+				details: undefined,
+			};
+		},
+	});
+
+	// A phase's report file is not always named <key>-<ts>.md: PLAN writes its
+	// handoff into todo-<ts>.md and CODE into progress-<ts>.md. Map key -> file
+	// stem so the text fallback for HANDOFF/BLOCKING actually finds them.
+	const REPORT_FILE_STEM: Record<string, string> = { plan: "todo", code: "progress" };
 
-	/** Read a phase's report file (.phi/plans/<key>-<ts>.md). Null-safe. */
+	/** Read a phase's report file (.phi/plans/<stem>-<ts>.md). Null-safe. */
 	function readPhaseReport(key: string, ts: string): string | null {
 		try {
-			const f = join(process.cwd(), ".phi", "plans", `${key}-${ts}.md`);
+			const stem = REPORT_FILE_STEM[key] ?? key;
+			const f = join(process.cwd(), ".phi", "plans", `${stem}-${ts}.md`);
 			if (existsSync(f)) return readFileSync(f, "utf-8");
-		} catch { /* ignore */ }
+		} catch {
+			/* ignore */
+		}
 		return null;
 	}
 
@@ -277,13 +409,18 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 	}
 	function writeCheckpoint(nextBaseIndex: number): void {
 		try {
-			if (nextBaseIndex >= 5) { clearCheckpoint(); return; }
+			if (nextBaseIndex >= 5) {
+				clearCheckpoint();
+				return;
+			}
 			writeFileSync(
 				checkpointPath(),
 				JSON.stringify({ description: currentDescription, ts: currentRunTs, nextBaseIndex }, null, 2),
 				"utf-8",
 			);
-		} catch { /* best effort */ }
+		} catch {
+			/* best effort */
+		}
 	}
 	function readCheckpoint(): { description: string; ts: string; nextBaseIndex: number } | null {
 		try {
@@ -293,14 +430,18 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 			if (typeof c?.description === "string" && typeof c?.ts === "string" && typeof c?.nextBaseIndex === "number") {
 				return c;
 			}
-		} catch { /* ignore */ }
+		} catch {
+			/* ignore */
+		}
 		return null;
 	}
 	function clearCheckpoint(): void {
 		try {
 			const p = checkpointPath();
 			if (existsSync(p)) unlinkSync(p);
-		} catch { /* best effort */ }
+		} catch {
+			/* best effort */
+		}
 	}
 
 	/**
@@ -344,7 +485,9 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 				const fmMatch = content.match(/^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)$/);
 				const body = (fmMatch ? fmMatch[1] : content).trim();
 				if (body) return body;
-			} catch { /* try next dir */ }
+			} catch {
+				/* try next dir */
+			}
 		}
 		return null;
 	}
@@ -358,7 +501,9 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		let routing: any = { routes: {}, default: { model: "default" } };
 		try {
 			routing = JSON.parse(readFileSync(routingPath, "utf-8"));
-		} catch { /* no routing config */ }
+		} catch {
+			/* no routing config */
+		}
 
 		function getModel(routeKey: string): { preferred: string; fallback: string } {
 			const route = routing.routes?.[routeKey];
@@ -377,9 +522,10 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		const ts = tsOverride || timestamp();
 		currentRunTs = ts; // shared by all phase report file names this run (or resumed)
 		// Inject runtime info so agents can adapt to the host OS
-		const shellNote = process.platform === 'win32'
-			? `\nShell: bash (Git Bash), NOT cmd.exe. Always use Unix syntax: rm not del, test -f not if exist, / not \\\\`
-			: '';
+		const shellNote =
+			process.platform === "win32"
+				? `\nShell: bash (Git Bash), NOT cmd.exe. Always use Unix syntax: rm not del, test -f not if exist, / not \\\\`
+				: "";
 		const runtimeInfo = `\n\nRuntime: ${process.platform} (${process.arch})${shellNote}`;
 
 		// Embed the prompt-architect skill so the PLAN phase applies it to every
@@ -393,9 +539,13 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 
 		const phases: OrchestratorPhase[] = [
 			{
-				key: "explore", label: "🔍 Phase 1 — EXPLORE", model: explore.preferred, fallback: explore.fallback,
+				key: "explore",
+				label: "🔍 Phase 1 — EXPLORE",
+				model: explore.preferred,
+				fallback: explore.fallback,
 				agent: loadAgentDef("explore"),
-				instruction: `You are the EXPLORE agent. Analyze the project requirements and existing codebase.
+				instruction:
+					`You are the EXPLORE agent. Analyze the project requirements and existing codebase.
 
 **FIRST ACTION (MANDATORY):** Call \`memory_search\` with project-relevant keywords to check for prior context.
 
@@ -448,12 +598,18 @@ After your analysis, use \`ontology_add\` to save key project entities AND their
 - Every function fully implemented
 - Follow existing patterns if codebase exists
 - [Any other specific constraints]
-\`\`\`` + runtimeInfo + COMMON_PHASE_RULES,
+\`\`\`` +
+					runtimeInfo +
+					COMMON_PHASE_RULES,
 			},
 			{
-				key: "plan", label: "📐 Phase 2 — PLAN", model: plan.preferred, fallback: plan.fallback,
+				key: "plan",
+				label: "📐 Phase 2 — PLAN",
+				model: plan.preferred,
+				fallback: plan.fallback,
 				agent: loadAgentDef("plan"),
-				instruction: `You are the PLAN agent. Design the architecture and create a detailed task list.
+				instruction:
+					`You are the PLAN agent. Design the architecture and create a detailed task list.
 
 **Context Retrieval:**
 1. Use \`ontology_query\` to retrieve all entities and relations from Phase 1
@@ -496,12 +652,18 @@ After your analysis, use \`ontology_add\` to save key project entities AND their
 - Dependencies: Task 1
 \`\`\`
 ${promptArchitectSection}
-Before finishing, use \`memory_write\` to save your plan summary with relevant tags for future reference.` + runtimeInfo + COMMON_PHASE_RULES,
+Before finishing, use \`memory_write\` to save your plan summary with relevant tags for future reference.` +
+					runtimeInfo +
+					COMMON_PHASE_RULES,
 			},
 			{
-				key: "code", label: "💻 Phase 3 — CODE", model: code.preferred, fallback: code.fallback,
+				key: "code",
+				label: "💻 Phase 3 — CODE",
+				model: code.preferred,
+				fallback: code.fallback,
 				agent: loadAgentDef("code"),
-				instruction: `You are the CODE agent. Implement the complete project.
+				instruction:
+					`You are the CODE agent. Implement the complete project.
 
 **Context Retrieval:**
 1. Use \`memory_search\` with project keywords to find notes from previous phases
@@ -545,12 +707,18 @@ After implementation, use \`memory_write\` to save a summary of what was built,
 **CRITICAL RULES:**
 - Write ONE file per tool call — NEVER combine multiple files in a single response
 - Keep each file under 500 lines. If longer, split into modules
-- After writing ALL files, verify they exist with a single \`find . -name '*.ts' -o -name '*.js' -o -name '*.html' | sort\`` + runtimeInfo + COMMON_PHASE_RULES,
+- After writing ALL files, verify they exist with a single \`find . -name '*.ts' -o -name '*.js' -o -name '*.html' | sort\`` +
+					runtimeInfo +
+					COMMON_PHASE_RULES,
 			},
 			{
-				key: "test", label: "🧪 Phase 4 — TEST", model: test.preferred, fallback: test.fallback,
+				key: "test",
+				label: "🧪 Phase 4 — TEST",
+				model: test.preferred,
+				fallback: test.fallback,
 				agent: loadAgentDef("test"),
-				instruction: `You are the TEST agent. Verify the implementation.
+				instruction:
+					`You are the TEST agent. Verify the implementation.
 
 **Context Retrieval:**
 1. Use \`memory_search\` to find implementation notes from the CODE phase
@@ -569,6 +737,7 @@ After implementation, use \`memory_write\` to save a summary of what was built,
    - Running \`npm test\` alone is NOT sufficient proof for a feature.
 **Step 4:** Fix any real errors you find (root cause, not a workaround).
 **Step 5:** Write test results to \`.phi/plans/test-${ts}.md\`, starting the file with a VERDICT line.
+**Step 6 (MANDATORY):** Call the \`phase_result\` tool with your \`verdict\` (PASS/FAIL/BLOCKED) and a concise \`handoff\`. This is how the orchestrator reads your outcome exactly; the report file above is the human-readable copy.
 
 **Test report format (the FIRST line MUST be the verdict):**
 \`\`\`markdown
@@ -609,12 +778,18 @@ $ <command actually executed>
 
 After testing, use \`memory_write\` to save test results, bugs found, and lessons learned.
 
-**Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "test-results" type "Phase" with properties {passed: "N", failed: "M", coverage: "X%"}) and add a relation to the project entity.` + runtimeInfo + COMMON_PHASE_RULES,
+**Ontology update:** Use \`ontology_add\` to update the project status (e.g., entity "test-results" type "Phase" with properties {passed: "N", failed: "M", coverage: "X%"}) and add a relation to the project entity.` +
+					runtimeInfo +
+					COMMON_PHASE_RULES,
 			},
 			{
-				key: "review", label: "🔍 Phase 5 — REVIEW", model: review.preferred, fallback: review.fallback,
+				key: "review",
+				label: "🔍 Phase 5 — REVIEW",
+				model: review.preferred,
+				fallback: review.fallback,
 				agent: loadAgentDef("review"),
-				instruction: `You are the REVIEW agent. Final quality review.
+				instruction:
+					`You are the REVIEW agent. Final quality review.
 
 **FIRST ACTIONS (MANDATORY — do these before anything else):**
 1. Call \`memory_search\` to find all notes from previous phases (explore, plan, code, test)
@@ -636,6 +811,7 @@ After testing, use \`memory_write\` to save test results, bugs found, and lesson
    - **REFUTED** - drop it. Only refute if you can quote the line that proves it cannot happen (a type, guard, or constant). When unsure, keep it PLAUSIBLE.
    Keep only CONFIRMED + PLAUSIBLE. A finding with no concrete failure scenario is noise: drop it.
 **Step 4:** Write \`.phi/plans/review-${ts}.md\`, starting with the VERDICT line.
+**Step 5 (MANDATORY):** Call the \`phase_result\` tool with your \`verdict\` (PASS/FAIL), the \`blocking\` findings (one per line, empty when none), and a short \`handoff\`. A FAIL here drives the one bounded fix→re-review cycle, so the orchestrator must read it exactly — do not rely on markdown parsing alone.
 
 **Final report format (the FIRST line MUST be the verdict):**
 \`\`\`markdown
@@ -666,10 +842,14 @@ Tag the note with relevant keywords for vector search.
 **Ontology enrichment:** After your review, use \`ontology_add\` to save your key findings:
 - Add a "review-report" entity with type "Document"
 - Add relations to the project: "reviews" → project, quality score as entity property
-- Save any new architectural decisions or patterns discovered` + runtimeInfo + COMMON_PHASE_RULES,
+- Save any new architectural decisions or patterns discovered` +
+					runtimeInfo +
+					COMMON_PHASE_RULES,
 			},
 		];
-		phases.forEach((p, i) => { p.baseIndex = i; });
+		phases.forEach((p, i) => {
+			p.baseIndex = i;
+		});
 		return phases;
 	}
 
@@ -733,7 +913,7 @@ Tag the note with relevant keywords for vector search.
 	/**
 	 * Activate agent for a phase: set system prompt + restrict tools.
 	 */
-	function activateAgent(phase: OrchestratorPhase, ctx: any) {
+	function activateAgent(phase: OrchestratorPhase, _ctx: any) {
 		// Fallback capture: savedTools is normally taken in the /plan handler at
 		// orchestration start, but capture it here too so restoration is always defined.
 		if (!savedTools) {
@@ -745,22 +925,29 @@ Tag the note with relevant keywords for vector search.
 			activeAgentPrompt = agentDef.systemPrompt;
 			// Restrict tools to agent's allowed tools
 			if (agentDef.tools.length > 0) {
-				// Always include memory tools in orchestration phases
-				const memoryTools = ['memory_search', 'memory_write', 'memory_read', 'ontology_add', 'ontology_query'];
-				const agentTools = [...agentDef.tools, ...memoryTools.filter(t => !agentDef.tools.includes(t))];
-				activeAgentTools = agentTools;
+				// Always include the memory tools and phase_result in orchestration phases.
+				const forcedTools = [
+					"memory_search",
+					"memory_write",
+					"memory_read",
+					"ontology_add",
+					"ontology_query",
+					"phase_result",
+				];
+				const agentTools = [...agentDef.tools, ...forcedTools.filter((t) => !agentDef.tools.includes(t))];
+				_activeAgentTools = agentTools;
 				pi.setActiveTools(agentTools);
 			} else if (savedTools) {
 				// Agent with no tool restriction: reset to the full toolset so the
 				// previous phase's narrower restriction does not leak into this one.
-				activeAgentTools = null;
+				_activeAgentTools = null;
 				pi.setActiveTools(savedTools);
 			}
 		} else {
 			// No agent for this phase: restore the full toolset, otherwise the prior
 			// phase's restriction would persist.
 			activeAgentPrompt = null;
-			activeAgentTools = null;
+			_activeAgentTools = null;
 			if (savedTools) {
 				pi.setActiveTools(savedTools);
 			}
@@ -772,7 +959,7 @@ Tag the note with relevant keywords for vector search.
 	 */
 	function deactivateAgent() {
 		activeAgentPrompt = null;
-		activeAgentTools = null;
+		_activeAgentTools = null;
 		if (savedTools) {
 			pi.setActiveTools(savedTools);
 			savedTools = null;
@@ -796,11 +983,16 @@ Tag the note with relevant keywords for vector search.
 		setOrchestrationActive(false);
 		phasePending = false;
 		deactivateAgent();
-		if (phaseTimeoutId) { clearTimeout(phaseTimeoutId); phaseTimeoutId = null; }
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
+		}
 		if (originalModel) {
 			const toRestore = originalModel;
 			originalModel = null;
-			Promise.resolve(pi.setModel(toRestore)).catch(() => { /* best effort */ });
+			Promise.resolve(pi.setModel(toRestore)).catch(() => {
+				/* best effort */
+			});
 		}
 	}
 
@@ -815,18 +1007,26 @@ Tag the note with relevant keywords for vector search.
 			if (originalModel) {
 				const toRestore = originalModel;
 				originalModel = null;
-				Promise.resolve(pi.setModel(toRestore)).catch(() => { /* best effort */ });
+				Promise.resolve(pi.setModel(toRestore)).catch(() => {
+					/* best effort */
+				});
+			}
+			if (phaseTimeoutId) {
+				clearTimeout(phaseTimeoutId);
+				phaseTimeoutId = null;
 			}
-			if (phaseTimeoutId) { clearTimeout(phaseTimeoutId); phaseTimeoutId = null; }
 			// Generate global final summary using the real phase counters
 			const elapsed = phaseStartTime ? Math.round((Date.now() - phaseStartTime) / 1000) : 0;
 			const minutes = Math.floor(elapsed / 60);
 			const seconds = elapsed % 60;
 			const skippedNote = skippedPhases ? ` (${skippedPhases} skipped on timeout)` : "";
-			ctx.ui.notify(`\n📊 **Orchestration Summary**\n` +
-				`  Phases: ${completedPhases}/5 completed${skippedNote}\n` +
-				`  Duration: ${minutes}m ${seconds}s\n` +
-				`  Check \`.phi/plans/\` for all reports`, "info");
+			ctx.ui.notify(
+				`\n📊 **Orchestration Summary**\n` +
+					`  Phases: ${completedPhases}/5 completed${skippedNote}\n` +
+					`  Duration: ${minutes}m ${seconds}s\n` +
+					`  Check \`.phi/plans/\` for all reports`,
+				"info",
+			);
 			const allDone = completedPhases >= 5 && skippedPhases === 0;
 			const doneMsg = allDone
 				? `\n✅ **All 5 phases complete!**`
@@ -835,7 +1035,11 @@ Tag the note with relevant keywords for vector search.
 				ctx.ui.notify(doneMsg, "info");
 			} catch {
 				// Fallback: inject completion message into conversation stream
-				try { pi.sendUserMessage(`Orchestration finished: ${completedPhases}/5 phases completed${skippedNote}.`); } catch { /* best effort */ }
+				try {
+					pi.sendUserMessage(`Orchestration finished: ${completedPhases}/5 phases completed${skippedNote}.`);
+				} catch {
+					/* best effort */
+				}
 			}
 			return;
 		}
@@ -843,6 +1047,10 @@ Tag the note with relevant keywords for vector search.
 		const phase = phaseQueue.shift()!;
 		phasePending = true;
 		currentPhase = phase;
+		// New phase starts with no structured result; it is set only if this
+		// phase's agent calls phase_result.
+		currentPhaseResult = null;
+		currentPhaseResultKey = null;
 
 		switchModelForPhase(phase, ctx).then(({ modelId, warning }) => {
 			activateAgent(phase, ctx);
@@ -862,7 +1070,11 @@ Tag the note with relevant keywords for vector search.
 					// race a still-streaming phase. Mark it internal so the resulting
 					// agent_end is not treated as a user cancellation.
 					internalAbort = true;
-					try { ctx.abort(); } catch { /* best effort */ }
+					try {
+						ctx.abort();
+					} catch {
+						/* best effort */
+					}
 					// Retry the SAME phase once on the fallback model before skipping:
 					// a timed-out phase usually means the model/route stalled, and a
 					// different family often gets through (cap = one retry per phase).
@@ -870,7 +1082,10 @@ Tag the note with relevant keywords for vector search.
 						phase.retried = true;
 						phase.useFallback = true;
 						phaseQueue.unshift(phase);
-						ctx.ui.notify(`\n⏰ **Phase timed out** (${MAX_PHASE_DURATION_MS / 60000} min) — retrying once on the fallback model.`, "warning");
+						ctx.ui.notify(
+							`\n⏰ **Phase timed out** (${MAX_PHASE_DURATION_MS / 60000} min) — retrying once on the fallback model.`,
+							"warning",
+						);
 					} else {
 						skippedPhases++;
 						ctx.ui.notify(`\n⏰ **Phase timed out again** — skipping to next phase.`, "warning");
@@ -883,9 +1098,9 @@ Tag the note with relevant keywords for vector search.
 
 	// ─── System Prompt Injection — Agent personas ────────────────────
 
-	pi.on("before_agent_start", async (event, _ctx) => {
+	pi.on("before_agent_start", async (_event, _ctx) => {
 		if (!orchestrationActive || !activeAgentPrompt) {
-			return { };
+			return {};
 		}
 		// Replace system prompt with the active agent's prompt
 		return { systemPrompt: activeAgentPrompt };
@@ -905,15 +1120,21 @@ Tag the note with relevant keywords for vector search.
 		// An internal abort (phase timeout) re-emits agent_end; that transition was
 		// already handled by the timeout. Consume the flag and ignore this event so
 		// it is not mistaken for a user cancellation below.
-		if (internalAbort) { internalAbort = false; return; }
+		if (internalAbort) {
+			internalAbort = false;
+			return;
+		}
+
+		const messages = event.messages || [];
+		// Analyze what happened, read the phase's report, and let the pure state
+		// machine (providers/phase-machine.ts, unit tested) decide the transition.
+		// This hook only interprets the decision: notifications, queue edits,
+		// checkpoints, model switches.
+		const analysis = analyzePhaseMessages(messages);
 
 		// User abort (Ctrl+C / ESC): the aborted run still emits agent_end, but it
-		// must NOT be treated as phase completion. Detect the aborted assistant
-		// message and stop the whole workflow instead of chaining the next phase.
-		const userAborted = (event.messages || []).some(
-			(m: any) => m.role === 'assistant' && m.stopReason === 'aborted',
-		);
-		if (userAborted) {
+		// must NOT be treated as phase completion.
+		if (analysis.userAborted) {
 			ctx.ui.notify(`\n🛑 **Orchestration cancelled** by user. Remaining phases skipped.`, "warning");
 			stopOrchestration();
 			return;
@@ -929,163 +1150,123 @@ Tag the note with relevant keywords for vector search.
 		}
 
 		// Clear phase timeout on normal completion
-		if (phaseTimeoutId) { clearTimeout(phaseTimeoutId); phaseTimeoutId = null; }
-
-		// Build a structured summary of what happened in this phase
-		// Instead of raw LLM text, extract concrete actions: files created/modified,
-		// errors encountered, test results. This gives the next phase actionable context.
-		const messages = event.messages || [];
-		const filesWritten: string[] = [];
-		const filesEdited: string[] = [];
-		const errorsHit: string[] = [];
-		const testResults: string[] = [];
-		let toolCallCount = 0;
-
-		for (const rawMsg of messages) {
-			// Pi message variants are scanned dynamically; cast to a loose shape once.
-			const msg = rawMsg as { role?: string; content?: unknown; name?: string; toolName?: string; isError?: boolean };
-			// Pi uses role: "toolResult" instead of "tool"
-			if (msg.role === 'tool' || msg.role === 'function' || msg.role === 'toolResult') {
-				toolCallCount++;
-				const content = Array.isArray(msg.content)
-					? msg.content.map((c: any) => c.text || '').join('')
-					: String(msg.content || '');
-				const name = msg.name || msg.toolName || '';
-				// Track writes
-				if (name === 'write' && content.includes('Successfully wrote')) {
-					const match = content.match(/wrote \d+ bytes to (.+)/);
-					if (match) filesWritten.push(match[1]);
-				}
-				// Track edits — the edit tool returns "Successfully replaced N block(s) in <path>."
-				// Anchor the path capture so it does not over-capture unrelated text.
-				if (name === 'edit' && !content.includes('ERR') && !msg.isError) {
-					const match = content.match(/replaced \d+ block\(s\) in (.+?)\.?$/m);
-					if (match) filesEdited.push(match[1]);
-				}
-				// Track errors — but filter out edit retries (old_text mismatch = normal retry, not error)
-				if ((content.includes('ERR:') || content.includes('Error:') || content.includes('FAIL'))
-					&& !content.includes('old text must match')
-					&& !content.includes('The old text')
-					&& !content.includes('oldText not found')
-					&& !content.includes('old_text not found')) {
-					const preview = content.slice(0, 150).replace(/\n/g, ' ');
-					errorsHit.push(`${name}: ${preview}`);
-				}
-				// Track test results
-				if (content.includes('PASS') || content.includes('✅') || content.includes('✗') || content.includes('❌')) {
-					const lines = content.split('\n').filter((l: string) => /PASS|FAIL|✅|❌|✗/.test(l));
-					testResults.push(...lines.slice(0, 10));
-				}
-			}
+		if (phaseTimeoutId) {
+			clearTimeout(phaseTimeoutId);
+			phaseTimeoutId = null;
 		}
 
-		// Detect API errors (401, auth failures) — abort workflow if found
-		const hasAuthError = messages.some((msg: any) => {
-			const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content || '');
-			return content.includes('401') && (content.includes('invalid access token') || content.includes('token expired') || content.includes('Unauthorized'));
+		// Resolve the phase outcome: prefer the structured phase_result emission
+		// (exact) and fall back per-field to the regex-scraped markdown report.
+		// Only trust a structured result stamped with THIS phase's key — a stale
+		// result from a previous run or a late tool call is ignored.
+		const reportContent = currentPhase ? readPhaseReport(currentPhase.key, currentRunTs) : null;
+		const structuredForThisPhase = currentPhaseResultKey === (currentPhase?.key ?? null) ? currentPhaseResult : null;
+		const outcome = resolvePhaseOutcome(structuredForThisPhase, reportContent);
+		const verdict = outcome.verdict;
+		const decision = decidePhaseTransition({
+			analysis,
+			phase: currentPhase ? { key: currentPhase.key, retried: currentPhase.retried } : null,
+			verdict,
+			reviewFixRounds,
+			maxToolCallsPerPhase: MAX_TOOL_CALLS_PER_PHASE,
 		});
-		// Only a genuine auth failure (401) is fatal — abort the whole workflow.
-		if (hasAuthError) {
-			ctx.ui.notify(`\n❌ **Orchestrator aborted:** API authentication error (401)\nCheck your API key and model configuration.`, "error");
+
+		if (decision.action === "stop") {
+			// Only a genuine auth failure (401) is fatal — abort the whole workflow.
+			ctx.ui.notify(
+				`\n❌ **Orchestrator aborted:** API authentication error (401)\nCheck your API key and model configuration.`,
+				"error",
+			);
 			stopOrchestration();
 			return;
 		}
 
-		// Transient provider/proxy failure (timeout text / 5xx / 429 / broken JSON
-		// tool call) that is NOT a 401: retry the SAME phase once on the fallback
-		// model (a different family often gets through) before chaining onward.
-		if (currentPhase && !currentPhase.retried && isTransientError(messages)) {
-			if (phaseTimeoutId) { clearTimeout(phaseTimeoutId); phaseTimeoutId = null; }
+		if (decision.action === "retry-fallback" && currentPhase) {
+			// Transient provider/proxy failure (timeout text / 5xx / 429 / broken
+			// JSON tool call) that is NOT a 401: retry the SAME phase once on the
+			// fallback model (a different family often gets through).
 			currentPhase.retried = true;
 			currentPhase.useFallback = true;
 			phaseQueue.unshift(currentPhase);
 			phasePending = false;
-			ctx.ui.notify(`\n🔁 **Transient provider error** in ${currentPhase.label} — retrying once on the fallback model.`, "warning");
+			ctx.ui.notify(
+				`\n🔁 **Transient provider error** in ${currentPhase.label} — retrying once on the fallback model.`,
+				"warning",
+			);
 			sendNextPhase(ctx);
 			return;
 		}
 
-		// A phase that made 0 tool calls is NOT fatal: a model may legitimately
-		// answer with text only (e.g. an inline plan). Warn and continue rather
-		// than killing phases 2-5, mirroring the graceful phase-timeout path.
-		if (toolCallCount === 0 && messages.length > 0) {
-			ctx.ui.notify(`\n⚠️ **Phase made 0 tool calls** — it may have responded with text only. Continuing to the next phase.`, "warning");
+		if (decision.action === "pause-blocked" && currentPhase) {
+			ctx.ui.notify(
+				`\n⏸️ **${currentPhase.label} reported BLOCKED.** Pausing /plan — see \`.phi/plans/${currentPhase.key}-${currentRunTs}.md\`. Fix the blocker and re-run \`/plan\` to continue.`,
+				"warning",
+			);
+			stopOrchestration();
+			return;
+		}
+
+		if (decision.action === "continue" && decision.zeroToolCalls && messages.length > 0) {
+			// A phase that made 0 tool calls is NOT fatal: a model may legitimately
+			// answer with text only (e.g. an inline plan). Warn and continue rather
+			// than killing phases 2-5, mirroring the graceful phase-timeout path.
+			ctx.ui.notify(
+				`\n⚠️ **Phase made 0 tool calls** — it may have responded with text only. Continuing to the next phase.`,
+				"warning",
+			);
 			if (phaseQueue.length > 0) {
 				phaseQueue[0].instruction += `\n\n**Note:** The previous phase made 0 tool calls and may have responded with text only. Make sure you actually call the required tools.`;
 			}
 		}
 
-		// Build the summary
-		const summaryParts: string[] = [];
-		summaryParts.push(`Tool calls: ${toolCallCount}`);
-		// Anti-loop guard: warn if tool calls are excessive
-		if (toolCallCount > MAX_TOOL_CALLS_PER_PHASE) {
-			summaryParts.push(`⚠️ WARNING: Phase used ${toolCallCount} tool calls (limit: ${MAX_TOOL_CALLS_PER_PHASE}). Possible loop detected.`);
+		if (decision.action === "continue" && decision.missingVerdict && currentPhase) {
+			// The model deviated from BOTH contract paths: it neither called
+			// phase_result with a verdict nor wrote a parseable "VERDICT:" line.
+			// Surface it instead of silently treating the phase as passed.
+			ctx.ui.notify(
+				`\n⚠️ **${currentPhase.label} reported no verdict** (no phase_result call and no VERDICT line in \`.phi/plans/${currentPhase.key}-${currentRunTs}.md\`) — treating it as passed. Check the report manually.`,
+				"warning",
+			);
 		}
-		if (filesWritten.length > 0) summaryParts.push(`Files created/written: ${filesWritten.join(', ')}`);
-		if (filesEdited.length > 0) summaryParts.push(`Files edited: ${filesEdited.join(', ')}`);
-		if (testResults.length > 0) summaryParts.push(`Test results:\n${testResults.join('\n')}`);
-		if (errorsHit.length > 0) summaryParts.push(`Errors encountered: ${errorsHit.length}\n${errorsHit.slice(0, 5).join('\n')}`);
-
-		// Verify mandatory tool usage
-		const toolNames = messages
-			.filter((m: any) => m.role === 'tool' || m.role === 'function' || m.role === 'toolResult')
-			.map((m: any) => (m as any).name || (m as any).toolName || '');
-		const hasMemorySearch = toolNames.includes('memory_search');
-		const hasMemoryWrite = toolNames.includes('memory_write');
-		if (!hasMemorySearch) summaryParts.push(`⚠️ Phase did NOT call memory_search (mandatory)`);
-		if (!hasMemoryWrite) summaryParts.push(`⚠️ Phase did NOT call memory_write (mandatory)`);
-
-		const phaseSummary = summaryParts.join('\n');
-
-		// Prefer the phase's canonical "## HANDOFF" block (a deterministic text
-		// contract written to its report file) over the heuristic summary; fall back
-		// to the heuristic when the model did not write one.
-		const reportContent = currentPhase ? readPhaseReport(currentPhase.key, currentRunTs) : null;
-		const handoff = reportContent ? extractHandoff(reportContent) : "";
-		const nextBrief = handoff
-			? `Tool calls: ${toolCallCount}\n## HANDOFF (from ${currentPhase?.label || "previous phase"})\n${handoff}`
-			: phaseSummary;
+
+		// Prefer the resolved HANDOFF (structured phase_result, else the report's
+		// "## HANDOFF" block) over the heuristic summary; fall back to the
+		// heuristic when neither was provided.
+		const nextBrief = buildNextBrief(
+			analysis,
+			outcome.handoff,
+			currentPhase?.label || "previous phase",
+			MAX_TOOL_CALLS_PER_PHASE,
+		);
 		if (nextBrief && phaseQueue.length > 0) {
 			phaseQueue[0].instruction += `\n\n**Previous phase summary:**\n${nextBrief}`;
 		}
 
-		// Verdict-driven control (best-effort, never breaks the chain):
-		// - BLOCKED: the phase could not run; pause the run for the user.
-		// - REVIEW FAIL: open ONE bounded fix -> re-review cycle.
-		try {
-			const verdict = reportContent ? parsePhaseVerdict(reportContent) : null;
-			const looped = toolCallCount > MAX_TOOL_CALLS_PER_PHASE;
-
-			if (verdict === "BLOCKED" && currentPhase) {
-				ctx.ui.notify(`\n⏸️ **${currentPhase.label} reported BLOCKED.** Pausing /plan — see \`.phi/plans/${currentPhase.key}-${currentRunTs}.md\`. Fix the blocker and re-run \`/plan\` to continue.`, "warning");
-				stopOrchestration();
-				return;
-			}
-
-			if (currentPhase?.key === "review" && verdict === "FAIL" && reviewFixRounds < 1 && !looped) {
-				reviewFixRounds++;
-				const blocking = (reportContent ? extractBlockingFindings(reportContent) : "").slice(0, 4000);
-				const fixPhase: OrchestratorPhase = {
-					key: "code",
-					label: "🔧 Fix — CODE (review remediation)",
-					model: currentPhase.model,
-					fallback: currentPhase.fallback,
-					agent: loadAgentDef("code"),
-					instruction: `You are the CODE agent. REVIEW found BLOCKING issues. Fix ONLY these, root cause not workaround, then update \`.phi/plans/progress-${currentRunTs}.md\`.\n\n## BLOCKING findings to fix:\n${blocking || "(see the review report in .phi/plans/)"}\n` + COMMON_PHASE_RULES,
-				};
-				const reReviewPhase: OrchestratorPhase = {
-					...currentPhase,
-					retried: false,
-					useFallback: false,
-					label: "🔍 Re-REVIEW (after fix)",
-				};
-				// Run next: fix, then re-review.
-				phaseQueue.unshift(reReviewPhase);
-				phaseQueue.unshift(fixPhase);
-				ctx.ui.notify(`\n🔁 **REVIEW verdict: FAIL** — running one targeted fix + re-review cycle.`, "warning");
-			}
-		} catch { /* verdict logic is best-effort */ }
+		if (decision.action === "review-fix-cycle" && currentPhase) {
+			// REVIEW FAIL: open ONE bounded fix -> re-review cycle.
+			reviewFixRounds++;
+			const blocking = outcome.blocking.slice(0, 4000);
+			const fixPhase: OrchestratorPhase = {
+				key: "code",
+				label: "🔧 Fix — CODE (review remediation)",
+				model: currentPhase.model,
+				fallback: currentPhase.fallback,
+				agent: loadAgentDef("code"),
+				instruction:
+					`You are the CODE agent. REVIEW found BLOCKING issues. Fix ONLY these, root cause not workaround, then update \`.phi/plans/progress-${currentRunTs}.md\`.\n\n## BLOCKING findings to fix:\n${blocking || "(see the review report in .phi/plans/)"}\n` +
+					COMMON_PHASE_RULES,
+			};
+			const reReviewPhase: OrchestratorPhase = {
+				...currentPhase,
+				retried: false,
+				useFallback: false,
+				label: "🔍 Re-REVIEW (after fix)",
+			};
+			// Run next: fix, then re-review.
+			phaseQueue.unshift(reReviewPhase);
+			phaseQueue.unshift(fixPhase);
+			ctx.ui.notify(`\n🔁 **REVIEW verdict: FAIL** — running one targeted fix + re-review cycle.`, "warning");
+		}
 
 		// Checkpoint resume position after each base phase (synthetic fix/re-review
 		// phases have no baseIndex and do not advance it).
@@ -1132,11 +1313,18 @@ Tag the note with relevant keywords for vector search.
 				skippedPhases = 0;
 				reviewFixRounds = 0;
 				internalAbort = false;
+				// Clear any structured result left over from a prior run so this
+				// resumed phase's outcome is read fresh (see phase-result leak guard).
+				currentPhaseResult = null;
+				currentPhaseResultKey = null;
 				phaseStartTime = Date.now();
 				const firstResume = remaining[0];
 				currentPhase = firstResume;
 				phaseQueue = remaining.slice(1);
-				ctx.ui.notify(`📋 **Resuming orchestration** at ${firstResume.label} (${remaining.length} phase(s) left)\n`, "info");
+				ctx.ui.notify(
+					`📋 **Resuming orchestration** at ${firstResume.label} (${remaining.length} phase(s) left)\n`,
+					"info",
+				);
 				const { modelId, warning } = await switchModelForPhase(firstResume, ctx);
 				activateAgent(firstResume, ctx);
 				ctx.ui.notify(`${firstResume.label} → \`${modelId}\``, "info");
@@ -1151,7 +1339,8 @@ Tag the note with relevant keywords for vector search.
 			const description = rawArgs.replace(/(^|\s)--fanout\b/g, " ").trim();
 
 			if (!description) {
-				ctx.ui.notify(`**Usage:** \`/plan <project description>\` (or \`/plan --resume\` to continue a checkpointed run, \`/plan --fanout <desc>\` for parallel exploration)
+				ctx.ui.notify(
+					`**Usage:** \`/plan <project description>\` (or \`/plan --resume\` to continue a checkpointed run, \`/plan --fanout <desc>\` for parallel exploration)
 
 **Examples:**
   /plan Build a REST API for user authentication with JWT
@@ -1159,7 +1348,9 @@ Tag the note with relevant keywords for vector search.
   /plan Add test coverage to the payment module
 
 **Other commands:**
-  /plans — List all plans`, "info");
+  /plans — List all plans`,
+					"info",
+				);
 				return;
 			}
 
@@ -1167,7 +1358,11 @@ Tag the note with relevant keywords for vector search.
 			await ensurePlansDir();
 			const ts = timestamp();
 			const specFile = `spec-${ts}.md`;
-			await writeFile(join(plansDir, specFile), `# ${description}\n\n**Created:** ${new Date().toLocaleString()}\n`, "utf-8");
+			await writeFile(
+				join(plansDir, specFile),
+				`# ${description}\n\n**Created:** ${new Date().toLocaleString()}\n`,
+				"utf-8",
+			);
 
 			// Build phases with model assignments + agent definitions
 			currentDescription = description;
@@ -1184,6 +1379,11 @@ Tag the note with relevant keywords for vector search.
 			skippedPhases = 0;
 			reviewFixRounds = 0;
 			internalAbort = false;
+			// Clear any structured result left over from a previous /plan run in
+			// this session; the first phase is launched directly (not via
+			// sendNextPhase), so without this a stale verdict/handoff would leak.
+			currentPhaseResult = null;
+			currentPhaseResultKey = null;
 			const firstPhase = phases[0];
 			currentPhase = firstPhase;
 
@@ -1207,7 +1407,10 @@ Tag the note with relevant keywords for vector search.
 				try {
 					const available = ctx.modelRegistry?.getAvailable?.() || [];
 					const exploreModelId = resolveModelRef(available, firstPhase.model)?.id || firstPhase.model;
-					ctx.ui.notify(`\n🔭 **Parallel exploration** (read-only, up to 2 concurrent) — building a fuller map before phase 1...`, "info");
+					ctx.ui.notify(
+						`\n🔭 **Parallel exploration** (read-only, up to 2 concurrent) — building a fuller map before phase 1...`,
+						"info",
+					);
 					const fan = await runExploreFanout(defaultExplorerSpecs(description), {
 						model: exploreModelId,
 						tools: READONLY_EXPLORER_TOOLS,
@@ -1217,14 +1420,22 @@ Tag the note with relevant keywords for vector search.
 					});
 					const okCount = fan.results.filter((r) => r.ok).length;
 					if (fan.merged.trim()) {
-						firstPhase.instruction =
-							`## Parallel exploration findings (${okCount} read-only sub-explorer(s))\nUse these as a starting map; verify and synthesize them into your brief, do not trust them blindly.\n\n${fan.merged}\n\n---\n${firstPhase.instruction}`;
-						ctx.ui.notify(`\n🔭 ${okCount} sub-exploration(s) merged into EXPLORE${fan.rateLimited ? " (rate limit hit — ran the rest sequentially)" : ""}.`, "info");
+						firstPhase.instruction = `## Parallel exploration findings (${okCount} read-only sub-explorer(s))\nUse these as a starting map; verify and synthesize them into your brief, do not trust them blindly.\n\n${fan.merged}\n\n---\n${firstPhase.instruction}`;
+						ctx.ui.notify(
+							`\n🔭 ${okCount} sub-exploration(s) merged into EXPLORE${fan.rateLimited ? " (rate limit hit — ran the rest sequentially)" : ""}.`,
+							"info",
+						);
 					} else {
-						ctx.ui.notify(`\n🔭 Parallel exploration returned nothing usable${fan.rateLimited ? " (rate-limited)" : ""} — running the normal single-agent EXPLORE.`, "warning");
+						ctx.ui.notify(
+							`\n🔭 Parallel exploration returned nothing usable${fan.rateLimited ? " (rate-limited)" : ""} — running the normal single-agent EXPLORE.`,
+							"warning",
+						);
 					}
 				} catch {
-					ctx.ui.notify(`\n🔭 Parallel exploration skipped (error) — running the normal single-agent EXPLORE.`, "warning");
+					ctx.ui.notify(
+						`\n🔭 Parallel exploration skipped (error) — running the normal single-agent EXPLORE.`,
+						"warning",
+					);
 				}
 			}
 
@@ -1261,7 +1472,10 @@ Tag the note with relevant keywords for vector search.
 			}
 
 			const files = await readdir(plansDir);
-			const specs = files.filter(f => f.startsWith("spec-") && f.endsWith(".md")).sort().reverse();
+			const specs = files
+				.filter((f) => f.startsWith("spec-") && f.endsWith(".md"))
+				.sort()
+				.reverse();
 
 			if (specs.length === 0) {
 				ctx.ui.notify("No plans found.", "info");