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

package/extensions/phi/orchestrator.ts

@@ -16,20 +16,16 @@
  *   /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 { extractBlockingFindings, extractHandoff, parsePhaseVerdict } from "./providers/orchestrator-helpers.js";
+import { analyzePhaseMessages, buildNextBrief, decidePhaseTransition } from "./providers/phase-machine.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -58,35 +54,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 +114,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 +131,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 +147,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 +210,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 +241,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 +285,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;
@@ -264,7 +315,9 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		try {
 			const f = join(process.cwd(), ".phi", "plans", `${key}-${ts}.md`);
 			if (existsSync(f)) return readFileSync(f, "utf-8");
-		} catch { /* ignore */ }
+		} catch {
+			/* ignore */
+		}
 		return null;
 	}
 
@@ -277,13 +330,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 +351,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 +406,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 +422,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 +443,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 +460,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 +519,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 +573,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 +628,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
@@ -609,12 +698,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)
@@ -666,10 +761,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 +832,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) {
@@ -746,21 +845,21 @@ Tag the note with relevant keywords for vector search.
 			// 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;
+				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;
 				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 +871,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 +895,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 +919,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 +947,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;
 		}
@@ -862,7 +978,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 +990,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 +1006,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 +1028,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 +1058,119 @@ 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'));
+		const reportContent = currentPhase ? readPhaseReport(currentPhase.key, currentRunTs) : null;
+		const verdict = reportContent ? parsePhaseVerdict(reportContent) : null;
+		const decision = decidePhaseTransition({
+			analysis,
+			phase: currentPhase ? { key: currentPhase.key, retried: currentPhase.retried } : null,
+			verdict,
+			hasReport: reportContent !== null,
+			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 the text contract: this phase must start its
+			// report with "VERDICT: ..." and nothing parseable was found. Surface it
+			// instead of silently treating the phase as passed.
+			ctx.ui.notify(
+				`\n⚠️ **${currentPhase.label} wrote no parseable 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;
+		const nextBrief = buildNextBrief(
+			analysis,
+			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 = (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");
+		}
 
 		// Checkpoint resume position after each base phase (synthetic fix/re-review
 		// phases have no baseIndex and do not advance it).
@@ -1136,7 +1221,10 @@ Tag the note with relevant keywords for vector search.
 				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 +1239,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 +1248,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 +1258,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;
@@ -1207,7 +1302,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 +1315,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 +1367,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");