@ilya-lesikov/pi-pi 0.1.0

package/extensions/orchestrator/phases/machine.ts

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import type { TaskType, Phase } from "../state.js";
+import { getLatestSynthesizedPlan } from "../context.js";
+import { validatePlan, validateResearch, validateUserRequest } from "../validate-artifacts.js";
+
+const USER_REQUEST_TEMPLATE = [
+  "# User Request",
+  "<1-3 sentence distillation>",
+  "",
+  "## Problem",
+  "<What's broken, user's perspective>",
+  "",
+  "## Constraints",
+  "<User-stated boundaries>",
+].join("\n");
+
+const RESEARCH_TEMPLATE = [
+  "## Affected Code",
+  "<file:symbol — one-line role, per line>",
+  "",
+  "## Architecture Context",
+  "<Dense bullets. How affected pieces connect.>",
+  "",
+  "## Constraints & Edge Cases",
+  "- MUST: <hard requirements discovered from code>",
+  "- RISK: <things that could break>",
+  "",
+  "## Open Questions",
+  "<Unresolved items needing user input. Omit section if none.>",
+].join("\n");
+
+const PLAN_TEMPLATE = [
+  "# Plan",
+  "",
+  "## Scope",
+  "<2-4 lines summarizing what changes and what doesn't>",
+  "",
+  "## Checklist",
+  "- [ ] <Outcome> — Done when: <observable condition>",
+  "",
+  "## Blockers",
+  "<Unresolved issues. Omit section if none.>",
+].join("\n");
+
+function isMissingOrEmpty(filePath: string): boolean {
+  return !existsSync(filePath) || readFileSync(filePath, "utf-8").trim().length === 0;
+}
+
+function formatValidationErrors(fileName: string, errors: string[], expectedStructure: string): string {
+  return `${fileName} validation failed:\n${errors.map((error) => `- ${error}`).join("\n")}\n\nExpected structure:\n${expectedStructure}`;
+}
+
+const TRANSITIONS: Record<TaskType, Record<string, string[]>> = {
+  implement: {
+    brainstorm: ["plan"],
+    plan: ["implement"],
+    implement: ["done"],
+  },
+  debug: {
+    debug: ["plan"],
+    plan: ["implement"],
+    implement: ["done"],
+  },
+  brainstorm: {
+    brainstorm: ["plan"],
+    plan: ["implement"],
+    implement: ["done"],
+  },
+};
+
+export function canTransition(taskType: TaskType, from: Phase, to: Phase): boolean {
+  const targets = TRANSITIONS[taskType]?.[from];
+  return targets?.includes(to) ?? false;
+}
+
+export function nextPhase(taskType: TaskType, from: Phase): Phase | null {
+  const targets = TRANSITIONS[taskType]?.[from];
+  return targets?.[0] as Phase | null ?? null;
+}
+
+export function validateExitCriteria(
+  taskDir: string,
+  taskType: TaskType,
+  phase: Phase,
+): { ok: true } | { ok: false; reason: string } {
+  switch (phase) {
+    case "brainstorm": {
+      const ur = join(taskDir, "USER_REQUEST.md");
+      const res = join(taskDir, "RESEARCH.md");
+      if (isMissingOrEmpty(ur)) {
+        return { ok: false, reason: "USER_REQUEST.md does not exist or is empty" };
+      }
+      if (isMissingOrEmpty(res)) {
+        return { ok: false, reason: "RESEARCH.md does not exist or is empty" };
+      }
+      const urContent = readFileSync(ur, "utf-8");
+      const resContent = readFileSync(res, "utf-8");
+
+      const userRequestValidation = validateUserRequest(urContent);
+      if (!userRequestValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("USER_REQUEST.md", userRequestValidation.errors, USER_REQUEST_TEMPLATE),
+        };
+      }
+
+      const researchValidation = validateResearch(resContent);
+      if (!researchValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("RESEARCH.md", researchValidation.errors, RESEARCH_TEMPLATE),
+        };
+      }
+
+      return { ok: true };
+    }
+
+    case "plan": {
+      const plan = getLatestSynthesizedPlan(taskDir);
+      if (!plan) {
+        return { ok: false, reason: "No synthesized plan found in plans/" };
+      }
+
+      const planValidation = validatePlan(plan);
+      if (!planValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("Synthesized plan", planValidation.errors, PLAN_TEMPLATE),
+        };
+      }
+
+      return { ok: true };
+    }
+
+    case "implement": {
+      const content = getLatestSynthesizedPlan(taskDir);
+      if (!content) {
+        return { ok: false, reason: "No synthesized plan found" };
+      }
+
+      const planValidation = validatePlan(content);
+      if (!planValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("Synthesized plan", planValidation.errors, PLAN_TEMPLATE),
+        };
+      }
+
+      const checklistStart = content.indexOf("## Checklist");
+      const checklistEnd = checklistStart === -1 ? -1 : content.indexOf("\n## ", checklistStart + 1);
+      const checklistContent = checklistStart === -1
+        ? ""
+        : checklistEnd === -1
+        ? content.slice(checklistStart)
+        : content.slice(checklistStart, checklistEnd);
+      const unchecked = checklistContent.match(/^- \[ \]/gm);
+      if (unchecked && unchecked.length > 0) {
+        return { ok: false, reason: `${unchecked.length} plan items still unchecked` };
+      }
+      return { ok: true };
+    }
+
+    case "debug": {
+      const ur = join(taskDir, "USER_REQUEST.md");
+      const res = join(taskDir, "RESEARCH.md");
+      if (isMissingOrEmpty(ur)) {
+        return { ok: false, reason: "USER_REQUEST.md does not exist or is empty" };
+      }
+      if (isMissingOrEmpty(res)) {
+        return { ok: false, reason: "RESEARCH.md does not exist or is empty" };
+      }
+      const urContent = readFileSync(ur, "utf-8");
+      const resContent = readFileSync(res, "utf-8");
+
+      const userRequestValidation = validateUserRequest(urContent);
+      if (!userRequestValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("USER_REQUEST.md", userRequestValidation.errors, USER_REQUEST_TEMPLATE),
+        };
+      }
+
+      const researchValidation = validateResearch(resContent);
+      if (!researchValidation.ok) {
+        return {
+          ok: false,
+          reason: formatValidationErrors("RESEARCH.md", researchValidation.errors, RESEARCH_TEMPLATE),
+        };
+      }
+
+      return { ok: true };
+    }
+
+    default:
+      return { ok: false, reason: `Unknown phase: ${phase}` };
+  }
+}
+
+export function phasePipeline(taskType: TaskType): Phase[] {
+  switch (taskType) {
+    case "implement":
+      return ["brainstorm", "plan", "implement", "done"];
+    case "debug":
+      return ["debug", "plan", "implement", "done"];
+    case "brainstorm":
+      return ["brainstorm", "plan", "implement", "done"];
+  }
+}

package/extensions/orchestrator/phases/planning.ts

@@ -0,0 +1,255 @@
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { PiPiConfig } from "../config.js";
+import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
+import { createPlannerAgent } from "../agents/planner.js";
+import { createPlanReviewerAgent } from "../agents/plan-reviewer.js";
+import { getLatestSynthesizedPlan } from "../context.js";
+import { validatePlan } from "../validate-artifacts.js";
+
+export function planningSystemPrompt(taskDir: string): string {
+  const plansDir = join(taskDir, "plans");
+  return [
+    "[PI-PI — PLAN PHASE]",
+    "",
+    "Planning subagents are working in parallel to create plans.",
+    `They will write their outputs to ${plansDir}/. Wait for the notification that all planners completed.`,
+    "",
+    "# FORBIDDEN — do NOT do any of these:",
+    "- Do NOT write your own plan from scratch. You are a SYNTHESIZER, not a planner.",
+    "- Do NOT create the plans/ directory yourself — the extension manages it.",
+    "- Do NOT check the plans directory yourself — wait for the notification that all planners completed.",
+    "- Do NOT read project source code directly — the planner outputs already contain the analysis.",
+    "- Do NOT call plannotator_submit_plan — plan review is handled by the user via /pp menu.",
+    "",
+    "# Your job (in this order):",
+    "1. Wait for the notification that says 'All planners completed' — do NOT proceed before this",
+    `2. Read ALL planner outputs from ${plansDir}/`,
+    "3. USER_REQUEST.md and RESEARCH.md are already provided in your context above — do NOT re-read them from disk",
+    `4. Synthesize all plans into a single plan at ${plansDir}/<timestamp>_synthesized.md`,
+    "5. Ask the user for clarifications if unsure about anything",
+    "",
+    "Plan format:",
+    "- Start with # Plan",
+    "- ## Scope: 2-4 lines — what changes, what doesn't, critical constraints",
+    "- ## Checklist: each item is - [ ] <outcome> — Done when: <observable condition>",
+    "  Each item = one independently verifiable outcome. No code snippets or file-by-file instructions.",
+    "- ## Blockers: unresolved issues blocking implementation (omit if none)",
+    "- No other top-level sections allowed",
+    "- Describe outcomes, not code-level mechanics",
+    "",
+    "When the synthesized plan is ready, call pp_phase_complete with a brief summary of the plan.",
+  ].join("\n");
+}
+
+export async function spawnPlanners(
+  pi: ExtensionAPI,
+  cwd: string,
+  taskDir: string,
+  taskId: string,
+  config: PiPiConfig,
+): Promise<{ spawned: number; agentIds: string[]; failedVariants: string[] }> {
+  const urPath = join(taskDir, "USER_REQUEST.md");
+  const resPath = join(taskDir, "RESEARCH.md");
+  if (!existsSync(urPath) || !existsSync(resPath)) return { spawned: 0, agentIds: [], failedVariants: [] };
+
+  const userRequest = readFileSync(urPath, "utf-8");
+  const research = readFileSync(resPath, "utf-8");
+
+  const plansDir = join(taskDir, "plans");
+  if (!existsSync(plansDir)) {
+    mkdirSync(plansDir, { recursive: true });
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000);
+  const enabledVariants = Object.entries(config.planners).filter(([, v]) => v.enabled);
+  const agentIds: string[] = [];
+  const failedVariants: string[] = [];
+  const results: Promise<void>[] = [];
+
+  for (const [variant] of enabledVariants) {
+    const outputPath = join(plansDir, `${timestamp}_${variant}.md`);
+    const agent = createPlannerAgent(variant, config, { userRequest, research }, outputPath);
+
+    registerAgentDefinitions(pi, [{ type: "planner", variant, ...agent }]);
+
+    results.push(
+      (async () => {
+        try {
+          const { id } = await spawnViaRpc(pi, `planner_${variant}`, "Begin planning.", {
+            description: `Planner (${variant})`,
+            validateCompletion: () => {
+              if (!existsSync(outputPath) || statSync(outputPath).size === 0) {
+                return `You finished without writing your plan file. Write your plan to: ${outputPath}`;
+              }
+              const content = readFileSync(outputPath, "utf-8");
+              const validation = validatePlan(content);
+              if (!validation.ok) {
+                return `Plan validation failed:\n${validation.errors.join("\n")}\n\nFix the plan at ${outputPath}`;
+              }
+            },
+          });
+          agentIds.push(id);
+          await waitForCompletion(pi, id);
+
+          if (existsSync(outputPath)) {
+            const planContent = readFileSync(outputPath, "utf-8");
+            const validation = validatePlan(planContent);
+            if (!validation.ok) {
+              pi.sendMessage(
+                {
+                  customType: "pp-planner-error",
+                  content: `Planner "${variant}" produced invalid plan (errors were shown to the agent but it did not fix them): ${validation.errors.join("; ")}`,
+                  display: true,
+                },
+                { deliverAs: "steer" },
+              );
+            }
+          }
+        } catch (err: any) {
+          failedVariants.push(variant);
+          pi.sendMessage(
+            {
+              customType: "pp-planner-error",
+              content: `Planner variant "${variant}" failed: ${err.message}`,
+              display: true,
+            },
+            { deliverAs: "steer" },
+          );
+        }
+      })(),
+    );
+  }
+
+  await Promise.allSettled(results);
+
+  const planFiles = existsSync(plansDir) ? readdirSync(plansDir).filter((f) => !f.includes("synthesized") && !f.includes("review_")) : [];
+  if (planFiles.length > 0) {
+    pi.sendMessage(
+      {
+        customType: "pp-planners-done",
+        content: [
+          `${planFiles.length} planner(s) completed. Plans available in ${plansDir}:`,
+          ...planFiles.map((f) => `  - ${f}`),
+          "",
+          "Read all plans and synthesize them into a single plan.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  } else {
+    pi.sendMessage(
+      {
+        customType: "pp-planners-error",
+        content: [
+          "All planner variants failed — no plan files were produced.",
+          "You must create the plan yourself based on USER_REQUEST.md and RESEARCH.md.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  }
+
+  return { spawned: enabledVariants.length, agentIds, failedVariants };
+}
+
+export async function spawnPlanReviewers(
+  pi: ExtensionAPI,
+  cwd: string,
+  taskDir: string,
+  taskId: string,
+  config: PiPiConfig,
+): Promise<{ spawned: number; files: string[]; agentIds: string[]; failedVariants: string[] }> {
+  const urPath = join(taskDir, "USER_REQUEST.md");
+  const resPath = join(taskDir, "RESEARCH.md");
+  if (!existsSync(urPath) || !existsSync(resPath)) return { spawned: 0, files: [], agentIds: [], failedVariants: [] };
+
+  const userRequest = readFileSync(urPath, "utf-8");
+  const research = readFileSync(resPath, "utf-8");
+  const synthesizedPlan = getLatestSynthesizedPlan(taskDir);
+  if (!synthesizedPlan) return { spawned: 0, files: [], agentIds: [], failedVariants: [] };
+
+  const planReviewsDir = join(taskDir, "plan-reviews");
+  if (!existsSync(planReviewsDir)) {
+    mkdirSync(planReviewsDir, { recursive: true });
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000);
+  const enabledVariants = Object.entries(config.planReviewers).filter(([, v]) => v.enabled);
+  const reviewFiles: string[] = [];
+  const agentIds: string[] = [];
+  const failedVariants: string[] = [];
+
+  const results: Promise<void>[] = [];
+  for (const [variant] of enabledVariants) {
+    const outputPath = join(planReviewsDir, `${timestamp}_${variant}.md`);
+    reviewFiles.push(outputPath);
+
+    const agent = createPlanReviewerAgent(variant, config, { userRequest, research, synthesizedPlan }, outputPath);
+
+    registerAgentDefinitions(pi, [{ type: "plan_reviewer", variant, ...agent }]);
+
+    results.push(
+      (async () => {
+        try {
+          const { id } = await spawnViaRpc(pi, `plan_reviewer_${variant}`, "Begin plan review.", {
+            description: `Plan reviewer (${variant})`,
+            validateCompletion: () => {
+              if (!existsSync(outputPath) || statSync(outputPath).size === 0) {
+                return `You finished without writing your review file. Write your review to: ${outputPath}`;
+              }
+            },
+          });
+          agentIds.push(id);
+          await waitForCompletion(pi, id);
+        } catch (err: any) {
+          failedVariants.push(variant);
+          pi.sendMessage(
+            {
+              customType: "pp-plan-reviewer-error",
+              content: `Plan reviewer variant "${variant}" failed: ${err.message}`,
+              display: true,
+            },
+            { deliverAs: "steer" },
+          );
+        }
+      })(),
+    );
+  }
+
+  await Promise.allSettled(results);
+
+  const actualReviewFiles = existsSync(planReviewsDir)
+    ? readdirSync(planReviewsDir).filter((f) => f.startsWith(`${timestamp}`) && f.endsWith(".md"))
+    : [];
+
+  if (actualReviewFiles.length > 0) {
+    pi.sendMessage(
+      {
+          customType: "pp-plan-reviews-done",
+          content: [
+          `${actualReviewFiles.length} plan reviewer(s) completed. Reviews in ${planReviewsDir}:`,
+          ...actualReviewFiles.map((f) => `  - ${f}`),
+          "",
+          "Read all plan reviews and incorporate feedback into the synthesized plan if needed.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  } else if (enabledVariants.length > 0) {
+    pi.sendMessage(
+      {
+        customType: "pp-plan-reviews-error",
+        content: "All plan reviewer variants failed — no reviews were produced. Proceeding without plan review.",
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  }
+
+  return { spawned: enabledVariants.length, files: reviewFiles, agentIds, failedVariants };
+}

package/extensions/orchestrator/phases/review.ts

@@ -0,0 +1,193 @@
+import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { PiPiConfig } from "../config.js";
+import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
+import { createCodeReviewerAgent } from "../agents/code-reviewer.js";
+import { getLatestSynthesizedPlan } from "../context.js";
+
+export function reviewSystemPrompt(taskDir: string, pass: number, manualReview = false, phase?: string): string {
+  const reviewsDir = phase === "brainstorm" ? join(taskDir, "brainstorm-reviews") : join(taskDir, "code-reviews");
+  const plansDir = join(taskDir, "plans");
+
+  if (phase === "brainstorm") {
+    return [
+      `[PI-PI — BRAINSTORM REVIEW CYCLE (pass ${pass})]`,
+      "",
+      "Brainstorm reviewer outputs are ready.",
+      `Read them from ${reviewsDir}/.`,
+      "",
+      "# FORBIDDEN:",
+      "- Do NOT modify project source code",
+      "- Do NOT write your own review from scratch",
+      "- Do NOT add, rename, or remove sections in USER_REQUEST.md or RESEARCH.md",
+      "- Do NOT invent new headings (e.g. '## Current State', '## Critical Finding')",
+      "",
+      "# Your job:",
+      `1. Read ALL reviewer outputs from ${reviewsDir}/`,
+      "2. Identify valid gaps and inaccuracies that would block planning",
+      "3. If changes are needed: update ONLY the content within existing sections of USER_REQUEST.md / RESEARCH.md",
+      "4. If reviewers found no actionable gaps (e.g. task already done, minor suggestions only): do NOT modify the files",
+      "5. Ignore suggestions that don't affect downstream planning quality",
+      "",
+      "USER_REQUEST.md MUST keep exactly: # User Request, ## Problem, ## Constraints",
+      "RESEARCH.md MUST keep exactly: ## Affected Code, ## Architecture Context, ## Constraints & Edge Cases, ## Open Questions (optional)",
+      "Any other sections will fail validation.",
+      "",
+      "When done (or no changes needed), call pp_phase_complete with a brief summary.",
+    ].join("\n");
+  }
+
+  if (manualReview) {
+    return [
+      `[PI-PI — REVIEW CYCLE (pass ${pass}, manual)]`,
+      "",
+      "Review the implementation yourself using the available tools.",
+      "",
+      `Write your review to ${reviewsDir}/<timestamp>_final_pass-${pass}.md`,
+      "",
+      "If changes are needed:",
+      `1. Create a fix plan at ${plansDir}/<timestamp>_<description>.md`,
+      "2. Implement the fixes",
+      "3. Run afterImplement commands",
+      "",
+    "When done, call pp_phase_complete with a brief summary.",
+    ].join("\n");
+  }
+
+  return [
+    `[PI-PI — REVIEW CYCLE (pass ${pass})]`,
+    "",
+    "Code reviewer outputs are ready.",
+    `Read them from ${reviewsDir}/, synthesize feedback, and implement fixes if needed.`,
+    "",
+    "# FORBIDDEN — do NOT do any of these:",
+    "- Do NOT write your own code review from scratch. You are a SYNTHESIZER, not a reviewer.",
+    "- Do NOT create the code-reviews/ directory yourself — the extension manages it.",
+    "- Do NOT call plannotator_submit_plan — code review is handled by the user via /pp menu.",
+    "",
+    "# Your job (in this order):",
+    `1. Read ALL reviewer outputs from ${reviewsDir}/`,
+    `2. Synthesize into ${reviewsDir}/<timestamp>_final_pass-${pass}.md`,
+    "3. Present the synthesis to the user",
+    "",
+    "If changes are needed:",
+    `1. Create a fix plan at ${plansDir}/<timestamp>_<description>.md (do NOT modify the original synthesized plan)`,
+    "2. Implement the fixes",
+    "3. Run afterImplement commands",
+    "4. A new review pass will begin",
+    "",
+    "When the synthesized review is ready, call pp_phase_complete with a brief summary.",
+  ].join("\n");
+}
+
+export async function spawnCodeReviewers(
+  pi: ExtensionAPI,
+  cwd: string,
+  taskDir: string,
+  taskId: string,
+  config: PiPiConfig,
+  round: number,
+): Promise<{ spawned: number; agentIds: string[]; failedVariants: string[] }> {
+  const urPath = join(taskDir, "USER_REQUEST.md");
+  const resPath = join(taskDir, "RESEARCH.md");
+  if (!existsSync(urPath) || !existsSync(resPath)) {
+    pi.sendMessage(
+      { customType: "pp-code-reviews-error", content: "Cannot start code review: USER_REQUEST.md or RESEARCH.md is missing.", display: true },
+      { deliverAs: "steer" },
+    );
+    return { spawned: 0, agentIds: [], failedVariants: [] };
+  }
+
+  const userRequest = readFileSync(urPath, "utf-8");
+  const research = readFileSync(resPath, "utf-8");
+  const synthesizedPlan = getLatestSynthesizedPlan(taskDir);
+  if (!synthesizedPlan) {
+    pi.sendMessage(
+      { customType: "pp-code-reviews-error", content: "Cannot start code review: no synthesized plan found.", display: true },
+      { deliverAs: "steer" },
+    );
+    return { spawned: 0, agentIds: [], failedVariants: [] };
+  }
+
+  const reviewsDir = join(taskDir, "code-reviews");
+  if (!existsSync(reviewsDir)) {
+    mkdirSync(reviewsDir, { recursive: true });
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000);
+  const enabledVariants = Object.entries(config.codeReviewers).filter(([, v]) => v.enabled);
+  const agentIds: string[] = [];
+  const failedVariants: string[] = [];
+  const results: Promise<void>[] = [];
+
+  for (const [variant] of enabledVariants) {
+    const outputPath = join(reviewsDir, `${timestamp}_${variant}_round-${round}.md`);
+    const agent = createCodeReviewerAgent(variant, config, { userRequest, research, synthesizedPlan }, outputPath);
+
+    registerAgentDefinitions(pi, [{ type: "code_reviewer", variant, ...agent }]);
+
+    results.push(
+      (async () => {
+        try {
+          const { id } = await spawnViaRpc(pi, `code_reviewer_${variant}`, "Begin code review.", {
+            description: `Code reviewer (${variant})`,
+            validateCompletion: () => {
+              if (!existsSync(outputPath) || statSync(outputPath).size === 0) {
+                return `You finished without writing your review file. Write your review to: ${outputPath}`;
+              }
+            },
+          });
+          agentIds.push(id);
+          await waitForCompletion(pi, id);
+        } catch (err: any) {
+          failedVariants.push(variant);
+          pi.sendMessage(
+            {
+              customType: "pp-code-reviewer-error",
+              content: `Code reviewer variant "${variant}" failed: ${err.message}`,
+              display: true,
+            },
+            { deliverAs: "steer" },
+          );
+        }
+      })(),
+    );
+  }
+
+  await Promise.allSettled(results);
+
+  const reviewFiles = existsSync(reviewsDir)
+    ? readdirSync(reviewsDir).filter((f) => f.includes(`round-${round}`) && !f.includes("final"))
+    : [];
+
+  if (reviewFiles.length > 0) {
+    pi.sendMessage(
+      {
+        customType: "pp-code-reviews-done",
+        content: [
+          `${reviewFiles.length} code reviewer(s) completed (round ${round}). Reviews in ${reviewsDir}:`,
+          ...reviewFiles.map((f) => `  - ${f}`),
+          "",
+          "Read all reviews and synthesize them into a final review.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  } else {
+    pi.sendMessage(
+      {
+        customType: "pp-code-reviews-error",
+        content: [
+          `All code reviewer variants failed (round ${round}) — no reviews were produced.`,
+          "You must review the implementation yourself and decide whether to approve or request changes.",
+        ].join("\n"),
+        display: true,
+      },
+      { deliverAs: "steer" },
+    );
+  }
+
+  return { spawned: enabledVariants.length, agentIds, failedVariants };
+}