@ilya-lesikov/pi-pi 0.9.0 → 0.11.0

package/extensions/orchestrator/orchestrator.ts

@@ -7,6 +7,7 @@ import {
   loadTask,
   saveTask,
   lockTask,
+  validateFromPath,
   getEffectivePhaseMode,
   type TaskType,
   type TaskMode,
@@ -19,7 +20,7 @@ import { planningSystemPrompt, spawnPlanners } from "./phases/planning.js";
 import { implementationSystemPrompt } from "./phases/implementation.js";
 import { reviewSystemPrompt as reviewCycleSystemPrompt } from "./phases/review.js";
 import { reviewSystemPrompt as reviewTaskSystemPrompt } from "./phases/review-task.js";
-import { registerAgentDefinitions, unregisterAgentDefinitions } from "./agents/registry.js";
+import { registerAgentDefinitions, unregisterAgentDefinitions, encodePoolVariant } from "./agents/registry.js";
 import { createExploreAgent } from "./agents/explore.js";
 import { createLibrarianAgent } from "./agents/librarian.js";
 import { createTaskAgent } from "./agents/task.js";
@@ -57,6 +58,10 @@ export interface ActiveTask {
 export class Orchestrator {
   active: ActiveTask | null = null;
   config!: NormalizedPiPiConfig;
+  // Non-null when loadConfig threw on session_start. While set, only a minimal
+  // read-only /pp path is available and `config` holds a rendering-only default
+  // fallback (NOT the user's config, which is invalid).
+  configError: string | null = null;
   cwd = "";
   spawnedAgentIds = new Set<string>();
   agentDescriptions = new Map<string, string>();
@@ -126,6 +131,12 @@ export class Orchestrator {
   // legitimately parked on a human is not aborted. Set on dialogue open, cleared
   // in finally on every exit (resolve, ESC/cancel, error).
   interactivePromptOpen = false;
+  // One-shot review-ready instruction (item 9). While a menu/ask turn is live,
+  // the review-ready banner must NOT be queued as a followUp (ESC/abort flushes
+  // the queue into the editor input — the stray-banner bug). Instead it is
+  // stashed here and delivered as a FRESH idle-gated turn once the dialogue
+  // closes. Cleared after delivery so it fires exactly once.
+  pendingReviewReady: string | null = null;
   // Set SYNCHRONOUSLY the moment a sub-429 is detected (before any async dialog),
   // and cleared once the decision resolves. The autonomous planner/reviewer
   // auto-retry consults this to avoid re-spawning a failed variant on the still-
@@ -288,6 +299,30 @@ export class Orchestrator {
     attempt(0);
   }
 
+  // Deliver the review-ready instruction WITHOUT leaking it into the editor on
+  // ESC/abort (item 9). If a menu/ask dialogue is live, the followUp queue would
+  // be dumped into the prompt input by restoreQueuedMessagesToEditor on abort —
+  // so stash the message and deliver it as a fresh idle-gated turn once the
+  // dialogue closes (flushPendingReviewReady). If nothing is open, deliver now.
+  deliverReviewReady(text: string): void {
+    if (this.interactivePromptOpen) {
+      this.pendingReviewReady = text;
+      return;
+    }
+    this.pendingReviewReady = null;
+    this.sendUserMessageWhenIdle(text, this.activeTaskToken);
+  }
+
+  // Deliver a stashed review-ready instruction (if any) as a fresh idle-gated
+  // turn. One-shot: cleared before sending so it never re-fires on a later idle.
+  // Called when a menu/ask dialogue closes (including ESC/abort).
+  flushPendingReviewReady(): void {
+    const text = this.pendingReviewReady;
+    if (!text || !this.active) return;
+    this.pendingReviewReady = null;
+    this.sendUserMessageWhenIdle(text, this.activeTaskToken);
+  }
+
   truncateResult(result: string): string {
     const trimmed = result.trim();
     if (!trimmed) return "";
@@ -474,13 +509,28 @@ export class Orchestrator {
     setLogLevel(this.config.general.logLevel);
     ensureGitignore(this.cwd);
 
+    // Validate the fork source BEFORE creating the new task so an invalid or
+    // escaping path cannot leave a half-created task behind. validateFromPath
+    // resolves against .pp/state/, so feed it the stateDir-relative form (the
+    // same shape stored in state.from) rather than the absolute dir.
+    let validatedFromDir: string | undefined;
+    if (fromTaskDir) {
+      const fromRel = relative(join(this.cwd, ".pp", "state"), fromTaskDir);
+      const validation = validateFromPath(this.cwd, fromRel);
+      if (!validation.ok) {
+        ctx.ui.notify(validation.reason, "error");
+        return;
+      }
+      validatedFromDir = validation.dir;
+    }
+
     const dir = createTask(this.cwd, type, description, mode);
     const state = loadTask(dir);
 
-    if (fromTaskDir) {
-      const srcUr = join(fromTaskDir, "USER_REQUEST.md");
-      const srcRes = join(fromTaskDir, "RESEARCH.md");
-      const srcArtifacts = join(fromTaskDir, "artifacts");
+    if (validatedFromDir) {
+      const srcUr = join(validatedFromDir, "USER_REQUEST.md");
+      const srcRes = join(validatedFromDir, "RESEARCH.md");
+      const srcArtifacts = join(validatedFromDir, "artifacts");
       if (existsSync(srcUr)) {
         const originalUr = readFileSync(srcUr, "utf-8");
         const implNote =
@@ -501,7 +551,7 @@ export class Orchestrator {
           copyFileSync(join(srcArtifacts, f), join(destArtifacts, f));
         }
       }
-      state.from = relative(join(this.cwd, ".pp", "state"), fromTaskDir);
+      state.from = relative(join(this.cwd, ".pp", "state"), validatedFromDir);
       if (skipBrainstorm && type === "implement") {
         state.phase = "plan";
         state.initialPhase = "plan";
@@ -636,6 +686,7 @@ export class Orchestrator {
     this.pendingNudges.clear();
     this.phaseStartTime = 0;
     this.userGatePending = false;
+    this.pendingReviewReady = null;
     this.failedPlannerVariants = [];
     this.failedReviewerVariants = [];
     this.plannerFailureDialogPending = false;
@@ -695,9 +746,6 @@ export class Orchestrator {
     const explore = createExploreAgent(this.config);
     const librarian = createLibrarianAgent(this.config);
     const taskAgent = createTaskAgent(this.config);
-    const advisor = createAdvisorAgent(this.config);
-    const deepDebugger = createDeepDebuggerAgent(this.config);
-    const reviewer = createReviewerAgent(this.config);
     const phase = this.active?.state.phase;
     const repos = this.active?.state.repos ?? [];
     log.debug({ s: "agents", phase, repoCount: repos.length }, "registering agent definitions");
@@ -734,27 +782,60 @@ export class Orchestrator {
         ...taskAgent,
         prompt: appendContext("task", taskAgent.prompt, getModelInfo(resolveModel(this.config.agents.subagents.simple.task.model))),
       },
-      {
-        type: "advisor",
-        variant: null,
-        ...advisor,
-        prompt: appendContext("advisor", advisor.prompt, getModelInfo(resolveModel(this.config.agents.subagents.simple.advisor.model))),
-      },
-      {
-        type: "deep-debugger",
-        variant: null,
-        ...deepDebugger,
-        prompt: appendContext("deep-debugger", deepDebugger.prompt, getModelInfo(resolveModel(this.config.agents.subagents.simple["deep-debugger"].model))),
-      },
-      {
-        type: "reviewer",
-        variant: null,
-        ...reviewer,
-        prompt: appendContext("reviewer", reviewer.prompt, getModelInfo(resolveModel(this.config.agents.subagents.simple.reviewer.model))),
-      },
+      ...this.buildPoolAgentDefinitions(appendContext),
     ]);
   }
 
+  // Register one model-named subagent per ENABLED entry in each on-demand pool
+  // (advisors / reviewers / deep-debuggers). The variant token encodes the
+  // model+thinking so the caller can see exactly what each is; the base `type`
+  // (advisor/reviewer/deep-debugger) drives context-file lookup. A collision
+  // after name sanitization is skipped (do not silently merge two entries).
+  private buildPoolAgentDefinitions(
+    appendContext: (agentType: string, prompt: string, modelInfo: { vendor: string; family: string; tier: string }) => string,
+  ): Array<{ type: string; variant: string; frontmatter: any; prompt: string }> {
+    const pools = this.config.agents.subagents.pools;
+    const defs: Array<{ type: string; variant: string; frontmatter: any; prompt: string }> = [];
+    const seen = new Set<string>();
+    const add = (
+      baseType: "advisor" | "reviewer" | "deep-debugger",
+      entry: { model: string; thinking: string; enabled?: boolean },
+      make: (e: { model: string; thinking: string }) => { frontmatter: any; prompt: string },
+    ) => {
+      if (entry.enabled === false) return;
+      const variant = encodePoolVariant(resolveModel(entry.model), entry.thinking);
+      const name = `${baseType}_${variant}`;
+      if (seen.has(name)) {
+        getLogger().warn({ s: "agents", name }, "pool entry collides after sanitization; skipping");
+        return;
+      }
+      seen.add(name);
+      const agent = make(entry);
+      defs.push({
+        type: baseType,
+        variant,
+        frontmatter: agent.frontmatter,
+        prompt: appendContext(baseType, agent.prompt, getModelInfo(resolveModel(entry.model))),
+      });
+    };
+    for (const e of pools.advisors) add("advisor", e, createAdvisorAgent);
+    for (const e of pools.reviewers) add("reviewer", e, createReviewerAgent);
+    for (const e of pools.deepDebuggers) add("deep-debugger", e, createDeepDebuggerAgent);
+    return defs;
+  }
+
+  // The orchestrator (main-agent) model config that applies to a phase — the
+  // source of truth for the thinking level shown in the main agent's identity
+  // block. Mirrors the phase→model selection in injectContextAndArtifacts.
+  mainAgentConfigForPhase(phase: Phase | undefined): { model: string; thinking: string } {
+    const o = this.config.agents.orchestrators;
+    if (phase === "debug" && this.active?.type === "debug") return o.debug;
+    if (phase === "brainstorm" && this.active?.type === "brainstorm") return o.brainstorm;
+    if (phase === "review" && this.active?.type === "review") return o.review;
+    if (phase === "plan") return o.plan;
+    return o.implement;
+  }
+
   injectContextAndArtifacts(taskDir: string, phase: Phase): void {
     const log = getLogger();
     log.debug({ s: "context", taskDir, phase }, "injecting context and artifacts");
@@ -831,6 +912,17 @@ export class Orchestrator {
     }
     return [...seen.entries()].filter(([, count]) => count > 1).map(([name]) => name);
   }
+
+  applySubagentConcurrency(): void {
+    const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+    const limit = this.config?.agents?.maxConcurrentSubagents;
+    if (typeof mgr?.setMaxConcurrent !== "function" || typeof limit !== "number") {
+      getLogger().debug({ s: "config", limit }, "subagents manager unavailable; skipped concurrency apply");
+      return;
+    }
+    mgr.setMaxConcurrent(limit);
+    getLogger().debug({ s: "config", limit }, "applied subagent concurrency limit");
+  }
 }
 
 export function ensureGitignore(cwd: string): void {

package/extensions/orchestrator/phases/brainstorm.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { brainstormSystemPrompt } from "./brainstorm.js";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { brainstormSystemPrompt, spawnBrainstormReviewers } from "./brainstorm.js";
+import { getDefaultConfig } from "../config.js";
 
 describe("brainstormSystemPrompt", () => {
   it("debug prompt body is pure procedure (no completion/menu restatements)", () => {
@@ -16,3 +20,28 @@ describe("brainstormSystemPrompt", () => {
     expect(prompt).not.toContain("/pp");
   });
 });
+
+describe("spawnBrainstormReviewers missing prerequisites", () => {
+  it("emits a displayed error and spawns nothing when artifacts are missing", async () => {
+    const taskDir = mkdtempSync(join(tmpdir(), "pi-pi-brainstorm-spawn-"));
+    try {
+      const sent: any[] = [];
+      const send = ((msg: any, _mode: any) => { sent.push(msg); }) as any;
+      const result = await spawnBrainstormReviewers(
+        {} as any,
+        taskDir,
+        taskDir,
+        "task-id",
+        getDefaultConfig(),
+        1,
+        send,
+      );
+      expect(result.spawned).toBe(0);
+      expect(sent).toHaveLength(1);
+      expect(sent[0].customType).toBe("pp-brainstorm-reviews-error");
+      expect(sent[0].display).toBe(true);
+    } finally {
+      rmSync(taskDir, { recursive: true, force: true });
+    }
+  });
+});

package/extensions/orchestrator/phases/brainstorm.ts

@@ -7,12 +7,30 @@ import { createBrainstormReviewerAgent } from "../agents/brainstorm-reviewer.js"
 import { getContextDirs, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { TaskType } from "../state.js";
+import { isReviewFileForRound } from "../review-files.js";
 import type { PhaseSend } from "../transition-controller.js";
 
 function isEnabled(value: { enabled?: boolean } | undefined): boolean {
   return value?.enabled !== false;
 }
 
+// The streamlined interactive-phase flow (design-decisions §3b). driverFamily is
+// the phase's own orchestrator model family; defaultAdvisor is the family-differing
+// advisor to consult by default (Claude-driven → a GPT-family advisor; GPT-driven
+// → a Claude-family advisor). Advisors are model-named pool subagents; pick one
+// from the roster in the delegation guidance.
+export function interactiveFlowBlock(driverFamily: string, defaultAdvisor: string): string {
+  return [
+    "# Flow (minimize interruptions):",
+    "1. CLARIFY UP-FRONT: if the request is ambiguous, ask your clarifying question(s) now, at the very start — batch them. If it's clear, skip straight to step 2.",
+    "2. WORK AUTONOMOUSLY: research, explore, and design without stopping to ask. Delegate to subagents (parallel explores for broad searches). Do NOT interrupt mid-flow with questions — collect uncertainties for step 4 instead. Only a genuine blocker (you cannot proceed at all) justifies an ask here.",
+    `3. CONSULT AN ADVISOR: before presenting, get an independent second opinion from an advisor whose model family differs from yours. You run on ${driverFamily}, so default to ${defaultAdvisor}. Escalate to more advisors for hard or high-stakes calls.`,
+    "4. CLARIFY AT THE END: surface any remaining decisions as focused asks — one at a time.",
+    "5. APPROVE COMMITTED SPECIFICS: before finalizing, when your output commits to concrete, costly-to-reverse or opinion-heavy choices — exact wording, structure, naming, default values, or interface signatures — show the ACTUAL proposed text/values inline in your message, then ask for explicit approval. Don't silently invent and bury them.",
+    "6. PRESENT RESULTS: end with a structured summary (what you found, the decisions, the recommended direction) and hand back with the standard closing block.",
+  ].join("\n");
+}
+
 export function brainstormSystemPrompt(taskType: TaskType, taskDescription: string, taskDir: string, cwd: string): string {
   const registerReposInstruction = `First, register all git repositories you'll work in using pp_register_repo (including the root: ${cwd}). For each, determine the base branch by examining the current branch and remote tracking.`;
   if (taskType === "debug") {
@@ -23,7 +41,9 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       registerReposInstruction,
       "",
     "Read-only diagnosis mode. You MAY use write/edit for diagnosis only (repro/test/analysis files) — never to implement the actual fix or feature.",
-    "",
+      "",
+      interactiveFlowBlock("GPT", "a Claude-family advisor"),
+      "",
     "# Your job:",
     "1. Clarify the problem with the user if needed",
     "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt), and use bash to run commands, check logs, reproduce issues",
@@ -54,6 +74,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "  ## Open Questions",
       "  <Unresolved items needing user input. Omit section if none.>",
       "",
+      "This is the LAST interactive phase. If the task continues in autonomous mode, the downstream plan/implement phases cannot ask the user anything — so resolve every Open Question now (answer it, or mark it DECIDED:/ASSUMED: with rationale). Do NOT defer questions to the plan phase.",
       "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
       "Use pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) for .pp state files — they keep the output compact and validate structure.",
       "",
@@ -78,11 +99,19 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "Your primary job is to TALK WITH THE USER. Explore ideas, analyze tradeoffs, answer questions, discuss approaches.",
       "Do NOT rush to produce artifacts or finish. Stay in the conversation until the user is satisfied.",
       "",
+      "# Flow (minimize interruptions — the streamlined flow, adapted to conversation):",
+      "1. CLARIFY UP-FRONT: if the topic is ambiguous, ask your clarifying question(s) at the very start — batch them into one focused round rather than dripping them out.",
+      "2. WORK AUTONOMOUSLY IN THE MIDDLE: once the topic is clear, research/explore/design without stopping to ask. Delegate to subagents (parallel explores for broad searches) and use tools directly for quick lookups. Do NOT interrupt with piecemeal mid-flow questions — collect uncertainties and raise them together at a natural checkpoint.",
+      "3. CONSULT AN ADVISOR: before landing on a recommendation, get an independent second opinion from an advisor whose model family differs from yours. You run on Claude, so default to a GPT-family advisor. Escalate to more advisors for hard or high-stakes calls.",
+      "4. CLARIFY AT THE END: before finalizing, surface any remaining open decisions as focused asks — one at a time. Don't bury unresolved questions inside an approval prompt or the summary.",
+      "5. APPROVE COMMITTED SPECIFICS: when you commit to concrete, costly-to-reverse or opinion-heavy choices — exact wording, structure, naming, default values, or interface signatures — show the ACTUAL proposed text/values inline, then get explicit approval. Don't silently invent and bury them.",
+      "6. PRESENT RESULTS: give conclusions as a clear, structured summary (findings, decisions, recommended direction) — don't just dump raw results.",
+      "This is still a conversation: the user drives it and may steer at any time. The flow shapes HOW you work between their messages — it does not forbid responding to what they say.",
+      "",
       "# How to work:",
-      "- Discuss the topic with the user. Ask clarifying questions. Propose approaches. Analyze tradeoffs.",
+      "- Discuss the topic with the user. Propose approaches. Analyze tradeoffs.",
       "- Delegate research to subagents where useful (see the delegation guidance in your system prompt).",
       "- Use tools directly for quick lookups (cbm_search, lsp, ast_search, grep, etc.)",
-      "- Present findings to the user and discuss them. Don't just dump raw results.",
       "",
       "# Optional artifacts (only when the conversation naturally produces them):",
       "If the discussion leads to a clear action plan or the user asks you to capture conclusions,",
@@ -112,6 +141,8 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "exists, but exploring the design space: weigh the viable approaches and their tradeoffs so the plan phase inherits a clear",
     "direction rather than an open-ended problem.",
     "",
+    interactiveFlowBlock("Claude", "a GPT-family advisor"),
+    "",
     "# Steps:",
     "1. Clarify requirements with the user if anything is ambiguous",
     "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches",
@@ -123,7 +154,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "   - ast_search: find structural patterns across the codebase",
     "4. Explore design options: identify the viable approaches, weigh their tradeoffs, and land on a recommended direction (capture the reasoning in RESEARCH.md / an artifact)",
     "5. Ask the user follow-up questions as needed",
-    "6. Actively drive every Open Question to resolution — chase down answers via research or by asking the user; the Open Questions section should be empty (or every entry marked DECIDED) before you hand off, not a passive backlog",
+    "6. Actively drive every Open Question to resolution — chase down answers via research or by asking the user; the Open Questions section should be empty (or every entry marked DECIDED:/ASSUMED: with rationale) before you hand off, not a passive backlog. This is the LAST interactive phase: if the task continues in autonomous mode, the downstream plan/implement phases cannot ask the user anything, so a deferred question becomes an unanswered one. Resolve or explicitly ASSUME each now — do NOT defer to the plan phase.",
     "7. Write findings into RESEARCH.md as results come back — don't wait for all subagents",
     "8. Keep USER_REQUEST.md current: update it whenever the user's request changes or clarifies, so it reflects what the user actually wants — don't write it once and leave it stale",
     "",
@@ -170,7 +201,13 @@ export async function spawnBrainstormReviewers(
 ): 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: [] };
+  if (!existsSync(urPath) || !existsSync(resPath)) {
+    send(
+      { customType: "pp-brainstorm-reviews-error", content: "Cannot start artifact review: USER_REQUEST.md or RESEARCH.md is missing.", display: true },
+      "context",
+    );
+    return { spawned: 0, files: [], agentIds: [], failedVariants: [] };
+  }
 
   const userRequest = readFileSync(urPath, "utf-8");
   const research = readFileSync(resPath, "utf-8");
@@ -243,7 +280,7 @@ export async function spawnBrainstormReviewers(
   await Promise.allSettled(results);
 
   const reviewOutputFiles = existsSync(reviewsDir)
-    ? readdirSync(reviewsDir).filter((f) => f.includes(`round-${round}`) && f.endsWith(".md"))
+    ? readdirSync(reviewsDir).filter((f) => isReviewFileForRound(f, round))
     : [];
 
   if (reviewOutputFiles.length > 0) {

package/extensions/orchestrator/phases/implementation.ts

@@ -6,6 +6,8 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "",
     "The plan has been approved. Implement it.",
     "",
+    "If you need clarification, batch it early rather than interrupting mid-work. Avoid mid-flight questions; you run off the approved USER_REQUEST/RESEARCH/plan. A genuine blocker is the only reason to stop and ask.",
+    "",
     "USER_REQUEST.md, RESEARCH.md, and the synthesized plan are already provided in your context above — do NOT re-read them from disk.",
     "",
     "# Instructions:",

package/extensions/orchestrator/phases/machine.test.ts

@@ -2,7 +2,8 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { afterEach, describe, expect, it } from "vitest";
-import { canTransition, nextPhase, phasePipeline, validateExitCriteria } from "./machine.js";
+import { canTransition, nextPhase, phasePipeline, validateExitCriteria, PLAN_TEMPLATE } from "./machine.js";
+import { PLAN_ALLOWED_SECTIONS } from "../validate-artifacts.js";
 
 const tempDirs: string[] = [];
 
@@ -346,3 +347,18 @@ Fix bug.
     expect(validateExitCriteria(dir, "quick", "quick")).toEqual({ ok: true });
   });
 });
+
+describe("PLAN_TEMPLATE / validator alignment", () => {
+  it("only uses section headings the plan validator allows", () => {
+    const headings = PLAN_TEMPLATE.split("\n")
+      .filter((l) => l.startsWith("## "))
+      .map((l) => l.slice(3).trim());
+    for (const h of headings) {
+      expect(PLAN_ALLOWED_SECTIONS).toContain(h);
+    }
+  });
+
+  it("includes the optional Pattern constraints section", () => {
+    expect(PLAN_TEMPLATE).toContain("## Pattern constraints");
+  });
+});

package/extensions/orchestrator/phases/machine.ts

@@ -30,7 +30,7 @@ const RESEARCH_TEMPLATE = [
   "<Unresolved items needing user input. Omit section if none.>",
 ].join("\n");
 
-const PLAN_TEMPLATE = [
+export const PLAN_TEMPLATE = [
   "# Plan",
   "",
   "## Scope",
@@ -39,6 +39,9 @@ const PLAN_TEMPLATE = [
   "## Checklist",
   "- [ ] <Outcome> — Done when: <observable condition>",
   "",
+  "## Pattern constraints",
+  "<Closest existing analog + conventions to mirror. Omit section if none.>",
+  "",
   "## Blockers",
   "<Unresolved issues. Omit section if none.>",
 ].join("\n");

package/extensions/orchestrator/phases/planning.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from "vitest";
-import { planningSystemPrompt } from "./planning.js";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { planningSystemPrompt, spawnPlanReviewers } from "./planning.js";
+import { getDefaultConfig } from "../config.js";
 
 describe("planningSystemPrompt self-complete directive", () => {
   it("guided synthesis instructs the agent to call pp_phase_complete when synthesis is complete", () => {
@@ -14,3 +18,45 @@ describe("planningSystemPrompt self-complete directive", () => {
     expect(prompt).not.toContain("Do NOT instead ask the user to run /pp manually");
   });
 });
+
+describe("spawnPlanReviewers missing prerequisites", () => {
+  async function run(setup: (dir: string) => void) {
+    const taskDir = mkdtempSync(join(tmpdir(), "pi-pi-plan-spawn-"));
+    setup(taskDir);
+    const sent: any[] = [];
+    const send = ((msg: any, _mode: any) => { sent.push(msg); }) as any;
+    try {
+      const result = await spawnPlanReviewers(
+        {} as any,
+        taskDir,
+        taskDir,
+        "task-id",
+        getDefaultConfig(),
+        1,
+        send,
+      );
+      return { result, sent };
+    } finally {
+      rmSync(taskDir, { recursive: true, force: true });
+    }
+  }
+
+  it("emits a displayed error when USER_REQUEST/RESEARCH are missing", async () => {
+    const { result, sent } = await run(() => {});
+    expect(result.spawned).toBe(0);
+    expect(sent).toHaveLength(1);
+    expect(sent[0].customType).toBe("pp-plan-reviews-error");
+    expect(sent[0].display).toBe(true);
+  });
+
+  it("emits a displayed error when the synthesized plan is missing", async () => {
+    const { result, sent } = await run((dir) => {
+      writeFileSync(join(dir, "USER_REQUEST.md"), "# User Request\n", "utf-8");
+      writeFileSync(join(dir, "RESEARCH.md"), "## Affected Code\n", "utf-8");
+    });
+    expect(result.spawned).toBe(0);
+    expect(sent).toHaveLength(1);
+    expect(sent[0].customType).toBe("pp-plan-reviews-error");
+    expect(sent[0].content).toContain("no synthesized plan");
+  });
+});

package/extensions/orchestrator/phases/planning.ts

@@ -8,6 +8,7 @@ import { createPlanReviewerAgent } from "../agents/plan-reviewer.js";
 import { getContextDirs, getLatestSynthesizedPlan, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { validatePlan } from "../validate-artifacts.js";
+import { isReviewFileForRound } from "../review-files.js";
 import type { TaskMode } from "../state.js";
 import type { PhaseSend } from "../transition-controller.js";
 
@@ -28,6 +29,8 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
   return [
     "[PI-PI — PLAN PHASE]",
     "",
+    "If you need clarification, batch it early rather than interrupting mid-work. Avoid mid-flight questions; you run off the approved USER_REQUEST/RESEARCH/plan. A genuine blocker is the only reason to stop and ask.",
+    "",
     "You are a SYNTHESIZER: you MERGE the planner outputs into one plan. Do NOT write your own plan from scratch.",
     "Planning subagents are working in parallel to create plans.",
     `They will write their outputs to ${plansDir}/. Wait for the notification that all planners completed.`,
@@ -190,12 +193,24 @@ export async function spawnPlanReviewers(
 ): 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: [] };
+  if (!existsSync(urPath) || !existsSync(resPath)) {
+    send(
+      { customType: "pp-plan-reviews-error", content: "Cannot start plan review: USER_REQUEST.md or RESEARCH.md is missing.", display: true },
+      "context",
+    );
+    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: [] };
+  if (!synthesizedPlan) {
+    send(
+      { customType: "pp-plan-reviews-error", content: "Cannot start plan review: no synthesized plan found.", display: true },
+      "context",
+    );
+    return { spawned: 0, files: [], agentIds: [], failedVariants: [] };
+  }
 
   const planReviewsDir = join(taskDir, "plan-reviews");
   if (!existsSync(planReviewsDir)) {
@@ -258,7 +273,7 @@ export async function spawnPlanReviewers(
   await Promise.allSettled(results);
 
   const actualReviewFiles = existsSync(planReviewsDir)
-    ? readdirSync(planReviewsDir).filter((f) => f.startsWith(`${timestamp}`) && f.includes(`round-${pass}`) && f.endsWith(".md"))
+    ? readdirSync(planReviewsDir).filter((f) => f.startsWith(`${timestamp}`) && isReviewFileForRound(f, pass))
     : [];
 
   if (actualReviewFiles.length > 0) {

package/extensions/orchestrator/phases/review-task.ts

@@ -1,9 +1,13 @@
+import { interactiveFlowBlock } from "./brainstorm.js";
+
 export function reviewSystemPrompt(taskDir: string, cwd: string): string {
   return [
     "[PI-PI — REVIEW PHASE]",
     "",
     `First, register all git repositories you'll work in using pp_register_repo (including the root: ${cwd}). For each, determine the base branch by examining the current branch and remote tracking.`,
     "",
+    interactiveFlowBlock("Claude", "a GPT-family advisor"),
+    "",
     "You are reviewing code changes. The user will describe what to review in their first chat message",
     "(e.g. a branch, a commit range, uncommitted changes, or a GitHub PR URL). There is NO pre-seeded",
     "USER_REQUEST.md — you must capture the user's request and your findings into the state files yourself.",
@@ -38,6 +42,7 @@ export function reviewSystemPrompt(taskDir: string, cwd: string): string {
     "  ## Open Questions",
     "  <Low-confidence concerns or items needing user input. Omit section if none.>",
     "",
+    "This is the LAST interactive phase. If the task continues in autonomous mode, the downstream plan/implement phases cannot ask the user anything — so resolve every Open Question now (answer it, or mark it DECIDED:/ASSUMED: with rationale). Do NOT defer questions to the plan phase.",
     "These files are validated programmatically. Missing sections or unexpected sections will be rejected.",
     "Use pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) for these .pp state files — they keep the output compact and validate structure.",
     "Keep USER_REQUEST.md current: update it whenever the user clarifies the review scope, so it never goes stale.",

package/extensions/orchestrator/phases/review.test.ts

@@ -23,6 +23,16 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     expect(auto).not.toContain("pp_phase_complete");
   });
 
+  it("debug uses the artifact-review branch: DEBUG header, brainstorm-reviews dir, no code-review tail", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "debug", "guided");
+    expect(prompt).toContain("DEBUG REVIEW CYCLE");
+    expect(prompt).toContain("Debug reviewer outputs are ready.");
+    expect(prompt).toContain("/tmp/task/brainstorm-reviews/");
+    expect(prompt).not.toContain("code-reviews");
+    expect(prompt).not.toContain("Create a fix plan");
+    expect(prompt).not.toContain("pp_phase_complete");
+  });
+
   it("brainstorm apply-feedback prompt permits artifact updates and steers to the compact tools", () => {
     const prompt = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "autonomous");
     expect(prompt).toContain("artifacts/");