@ilya-lesikov/pi-pi 0.6.0 → 0.8.0

package/extensions/orchestrator/orchestrator.ts

@@ -24,7 +24,10 @@ import { registerAgentDefinitions, unregisterAgentDefinitions } from "./agents/r
 import { createExploreAgent } from "./agents/explore.js";
 import { createLibrarianAgent } from "./agents/librarian.js";
 import { createTaskAgent } from "./agents/task.js";
-import { resolveModel, getModelInfo } from "./model-registry.js";
+import { createAdvisorAgent } from "./agents/advisor.js";
+import { createDeepDebuggerAgent } from "./agents/deep-debugger.js";
+import { createReviewerAgent } from "./agents/reviewer.js";
+import { resolveModel, getModelInfo, findLatestFamilyMatch, setSubscriptionFallbackActive } from "./model-registry.js";
 import { buildRepoContext } from "./agents/repo-context.js";
 import { getLogger, addTaskDestination, removeTaskDestination, setLogLevel } from "./log.js";
 import { handleSpawnResult } from "./spawn-cleanup.js";
@@ -77,10 +80,36 @@ export class Orchestrator {
   nudgeHalted = false;
   pendingSubagentSpawns = 0;
   errorRetryCount = 0;
+  // Halts the API-error auto-retry once errorRetryCount exceeds its cap, mirroring
+  // nudgeHalted. Without this, a benign intervening turn (e.g. the retried turn
+  // ends as a text-only "I'll wait") reset errorRetryCount to 0, so the 5-retry
+  // cap never accumulated and the "Previous request failed" nudge could fire
+  // unbounded (hundreds of times) against transient errors. Cleared only on
+  // genuine (non-[PI-PI]) user re-engagement, like nudgeHalted.
+  errorNudgeHalted = false;
   commitReminderSent = false;
   phaseStartTime = 0;
   pendingRetryTimer: ReturnType<typeof setTimeout> | null = null;
+  // Unsubscribe for the direct ESC interrupt armed while pendingRetryTimer is
+  // live. pi-pi's own post-error retry is NOT covered by any SDK/interactive ESC
+  // binding (the turn already ended in error, the session is not streaming), so
+  // without this ESC would not cancel it.
+  pendingRetryEscUnsub: (() => void) | null = null;
   activeTaskToken = 0;
+  // Subscription rate-limit fallback (Issue 5). subFallbackActive mirrors the
+  // model-registry override flag; subFallbackDialogPending guards against
+  // opening more than one switch dialogue at a time (across main + subagents);
+  // subFallbackModelId records the sub model that hit the limit (used by the
+  // switch-back probe); subSwitchBackTimer is the fixed-interval probe timer.
+  subFallbackActive = false;
+  subFallbackDialogPending = false;
+  // 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-
+  // sub-routed model while the fallback decision is in flight.
+  subFallbackPendingDecision = false;
+  subFallbackModelId: string | null = null;
+  subSwitchBackTimer: ReturnType<typeof setTimeout> | null = null;
   userGatePending = false;
   lastCtx: any = null;
   failedPlannerVariants: string[] = [];
@@ -123,6 +152,87 @@ export class Orchestrator {
     };
   }
 
+  // Arm a direct ESC interrupt for the post-error retry window. Idempotent: a
+  // single onTerminalInput handler stays registered until the retry is delivered,
+  // cancelled, or the task is reset. While pendingRetryTimer is live, ESC cancels
+  // the pending retry (no other binding covers this window).
+  armRetryEscInterrupt(ctx: any): void {
+    if (this.pendingRetryEscUnsub) return;
+    const onTerminalInput = ctx?.ui?.onTerminalInput;
+    if (typeof onTerminalInput !== "function") return;
+    const unsub = onTerminalInput.call(ctx.ui, (data: string) => {
+      if (!this.pendingRetryTimer) return undefined;
+      // Match a STANDALONE ESC only. Arrow/function/mouse sequences also start
+      // with 0x1b (e.g. "\x1b[A"), so `includes` would misfire on navigation
+      // keys and swallow them; a bare ESC is exactly the one-byte string.
+      if (data === "\x1b") {
+        this.cancelPendingRetry();
+        ctx?.ui?.notify?.("Retry cancelled.", "info");
+        return { consume: true };
+      }
+      return undefined;
+    });
+    this.pendingRetryEscUnsub = typeof unsub === "function" ? unsub : null;
+  }
+
+  disarmRetryEscInterrupt(): void {
+    if (this.pendingRetryEscUnsub) {
+      try {
+        this.pendingRetryEscUnsub();
+      } catch {
+        // ignore unsubscribe failures
+      }
+      this.pendingRetryEscUnsub = null;
+    }
+  }
+
+  // Cancel a pending post-error retry (timer + ESC interrupt) and reset the retry
+  // counter. Used by the ESC interrupt handler and by abort paths.
+  cancelPendingRetry(): void {
+    if (this.pendingRetryTimer) {
+      clearTimeout(this.pendingRetryTimer);
+      this.pendingRetryTimer = null;
+    }
+    this.disarmRetryEscInterrupt();
+    this.errorRetryCount = 0;
+    this.errorNudgeHalted = false;
+  }
+
+  // Deliver a queued message only once the main session is idle. Firing a
+  // followUp while the SDK still has an active run triggers an async, runtime-
+  // swallowed "Agent is already processing" rejection (surfaces as
+  // Extension "<runtime>" error), so we PRE-CHECK idle and DEFER (bounded poll)
+  // rather than dropping the nudge. Guarded by activeTaskToken; the poll reuses
+  // pendingRetryTimer so ESC/abort cancels it.
+  sendUserMessageWhenIdle(text: string, taskToken: number, attempt = 0): void {
+    const log = getLogger();
+    if (this.activeTaskToken !== taskToken || !this.active) {
+      this.disarmRetryEscInterrupt();
+      return;
+    }
+    const idleFn = this.lastCtx?.isIdle;
+    const idle = typeof idleFn === "function" ? !!idleFn.call(this.lastCtx) : true;
+    if (idle) {
+      this.disarmRetryEscInterrupt();
+      this.safeSendUserMessage(text);
+      return;
+    }
+    const MAX_ATTEMPTS = 120; // ~2min at 1s poll
+    if (attempt >= MAX_ATTEMPTS) {
+      log.warn({ s: "orchestrator", attempt }, "sendUserMessageWhenIdle gave up waiting for idle");
+      this.disarmRetryEscInterrupt();
+      this.lastCtx?.ui?.notify?.(
+        "pi-pi stopped waiting for the agent to go idle; auto-continuation was dropped. Send any message to resume.",
+        "warning",
+      );
+      return;
+    }
+    this.pendingRetryTimer = setTimeout(() => {
+      this.pendingRetryTimer = null;
+      this.sendUserMessageWhenIdle(text, taskToken, attempt + 1);
+    }, 1000);
+  }
+
   safeSendUserMessage(text: string): void {
     const log = getLogger();
     const attempt = (retries: number) => {
@@ -175,6 +285,16 @@ export class Orchestrator {
           (m) => m.provider.toLowerCase() === provider && m.id.toLowerCase() === modelId,
         );
       }
+      if (!resolved) {
+        const allSpecs = allModels.map((m) => `${m.provider}/${m.id}`);
+        const familyMatch = findLatestFamilyMatch(spec, allSpecs);
+        if (familyMatch) {
+          const fmLower = familyMatch.toLowerCase();
+          resolved = allModels.find(
+            (m) => `${m.provider.toLowerCase()}/${m.id.toLowerCase()}` === fmLower,
+          );
+        }
+      }
       if (!resolved) {
         const pattern = spec.toLowerCase();
         const matches = allModels.filter(
@@ -301,7 +421,7 @@ export class Orchestrator {
 
     if (this.active.state.reviewCycle?.step === "apply_feedback") {
       const pass = this.active.state.reviewCycle.pass;
-      return reviewCycleSystemPrompt(this.active.dir, pass, this.active.state.phase);
+      return reviewCycleSystemPrompt(this.active.dir, pass, this.active.state.phase, mode);
     }
 
     switch (this.active.state.phase) {
@@ -445,6 +565,7 @@ export class Orchestrator {
       type === "debug" ? "debug"
       : type === "brainstorm" ? "brainstorm"
       : type === "review" ? "review"
+      : type === "quick" ? "quick"
       : "implement"
     ];
     const modelOk = await this.switchModel(ctx, modelConfig.model, modelConfig.thinking);
@@ -528,6 +649,7 @@ export class Orchestrator {
     this.agentLifecycle.clear();
     this.pendingSubagentSpawns = 0;
     this.errorRetryCount = 0;
+    this.errorNudgeHalted = false;
     this.commitReminderSent = false;
     this.consecutiveNudges = 0;
     this.nudgeHalted = false;
@@ -541,10 +663,27 @@ export class Orchestrator {
       clearTimeout(this.pendingRetryTimer);
       this.pendingRetryTimer = null;
     }
+    this.disarmRetryEscInterrupt();
     if (this.staleAgentTimer) {
       clearInterval(this.staleAgentTimer);
       this.staleAgentTimer = null;
     }
+    this.clearSubscriptionFallback();
+  }
+
+  // Reset the subscription rate-limit fallback: cancel the switch-back probe
+  // timer, clear the model-registry override, and reset guards. Called on task
+  // reset/cleanup so the sticky override never leaks across tasks.
+  clearSubscriptionFallback(): void {
+    if (this.subSwitchBackTimer) {
+      clearTimeout(this.subSwitchBackTimer);
+      this.subSwitchBackTimer = null;
+    }
+    this.subFallbackActive = false;
+    this.subFallbackDialogPending = false;
+    this.subFallbackPendingDecision = false;
+    this.subFallbackModelId = null;
+    setSubscriptionFallbackActive(false);
   }
 
   async cleanupActive(): Promise<void> {
@@ -567,7 +706,10 @@ export class Orchestrator {
     const log = getLogger();
     const explore = createExploreAgent(this.config);
     const librarian = createLibrarianAgent(this.config);
-    const taskAgent = createTaskAgent(this.config, "{{subtask}}", { userRequest: "", synthesizedPlan: "" });
+    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");
@@ -604,6 +746,24 @@ 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))),
+      },
     ]);
   }
 

package/extensions/orchestrator/phases/brainstorm.ts

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js";
 import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
 import { createBrainstormReviewerAgent } from "../agents/brainstorm-reviewer.js";
-import { getContextDirs } from "../context.js";
+import { getContextDirs, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { TaskType } from "../state.js";
 import type { PhaseSend } from "../transition-controller.js";
@@ -26,13 +26,8 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     "# Your job:",
     "1. Clarify the problem with the user if needed",
-    "2. Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
-    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups.',
-    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "   Explore is fast and cheap. Use it liberally for codebase questions. Spawn multiple in parallel.",
-    "3. Use bash to run commands, check logs, reproduce issues",
-    "4. Use tools to trace the bug:",
+    "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",
+    "3. Use tools to trace the bug:",
     "   - cbm_search/cbm_search_code: find relevant code by concept or text",
     "   - lsp goToDefinition, findReferences, hover: precise navigation and type info",
     "   - lsp goToImplementation: check interface implementors",
@@ -60,6 +55,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "  <Unresolved items needing user input. Omit section if none.>",
       "",
       "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.",
       "",
       "# Optional: focused analysis artifacts",
       `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
@@ -84,11 +80,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
       "",
       "# How to work:",
       "- Discuss the topic with the user. Ask clarifying questions. Propose approaches. Analyze tradeoffs.",
-    "- Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
-    '  Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '  Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    '  Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "  Spawn multiple Explore agents in parallel for broad searches.",
+      "- 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.",
       "",
@@ -120,11 +112,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "",
     "# Steps:",
     "1. Clarify requirements with the user if anything is ambiguous",
-    "2. Spawn subagents for research (subagent_type is REQUIRED — calls without it are rejected):",
-    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    '   - Agent(subagent_type="Task", ...) — only when you need a subtask that writes files or runs complex multi-step commands.',
-    "   Spawn multiple Explore agents in parallel for broad searches.",
+    "2. Delegate research to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches",
     "3. Use tools to understand code structure:",
     "   - cbm_search: natural-language search across all symbols",
     "   - cbm_search_code: graph-augmented grep (deduplicates into functions)",
@@ -155,6 +143,7 @@ export function brainstormSystemPrompt(taskType: TaskType, taskDescription: stri
     "  <Unresolved items needing user input. Omit section if none.>",
     "",
     "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.",
     "",
     "# Optional: focused analysis artifacts",
     `You may also write additional analysis files to ${taskDir}/artifacts/<name>.md`,
@@ -210,7 +199,7 @@ export async function spawnBrainstormReviewers(
     const agent = createBrainstormReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, artifacts: artifacts.length > 0 ? artifacts : undefined },
+      { userRequest, research, artifacts: artifacts.length > 0 ? artifacts : undefined, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       "brainstorm",
@@ -261,7 +250,7 @@ export async function spawnBrainstormReviewers(
           `${reviewOutputFiles.length} brainstorm reviewer(s) completed (round ${round}). Reviews in ${reviewsDir}:`,
           ...reviewOutputFiles.map((f) => `  - ${f}`),
           "",
-          "Read all reviews and update USER_REQUEST.md and RESEARCH.md if needed.",
+          "Read all reviews and update USER_REQUEST.md, RESEARCH.md, and any artifacts/ files if needed.",
         ].join("\n"),
         display: true,
       },

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

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { implementationSystemPrompt } from "./implementation.js";
+
+describe("implementationSystemPrompt self-complete directive", () => {
+  it("instructs the agent to call pp_phase_complete when the implement phase is complete", () => {
+    const prompt = implementationSystemPrompt("/tmp/task", "/tmp");
+    expect(prompt).toContain("pp_phase_complete");
+    expect(prompt).toContain("Do NOT instead ask the user to run /pp manually");
+    expect(prompt).not.toContain("do NOT wait for the user");
+  });
+});

package/extensions/orchestrator/phases/implementation.ts

@@ -11,7 +11,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "# Instructions:",
     "1. Review the synthesized plan in your context",
     "2. Implement each item in order",
-    "3. Check off items in the plan (change - [ ] to - [x]) as you complete them",
+    "3. Check off items in the plan (change - [ ] to - [x]) as you complete them — use pp_edit_state_file (NOT the generic edit) to update the plan compactly",
     "4. After editing files, run lsp diagnostics to check for errors; use lsp codeActions for auto-fixes",
     "5. Before modifying code, understand it first:",
     "   - cbm_search/cbm_search_code: find relevant functions and their context",
@@ -21,11 +21,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "   - cbm_trace: trace dependencies across the codebase",
     "   - ast_search: find structural patterns (e.g. error handling conventions)",
     "6. After completing changes, run cbm_changes to verify blast radius",
-    "7. Spawn subagents as needed (subagent_type is REQUIRED — calls without it are rejected):",
-    '   - Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '   - Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    '   - Agent(subagent_type="Task", ...) — parallelizable, self-contained implementation subtasks.',
-    "   Spawn multiple Explore agents in parallel for broad searches.",
+    "7. Delegate to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches, and use task for parallelizable self-contained implementation subtasks",
     "",
     "# Commits:",
     "After completing a logical unit of work (a plan item, a bug fix, a test), call pp_commit",
@@ -34,5 +30,7 @@ export function implementationSystemPrompt(taskDir: string, cwd: string): string
     "Don't batch all changes into one commit.",
     "",
     "Fix issues found by lsp diagnostics before moving on.",
+    "",
+    "When you judge the implement phase complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead ask the user to run /pp manually.",
   ].join("\n");
 }

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

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { planningSystemPrompt } from "./planning.js";
+
+describe("planningSystemPrompt self-complete directive", () => {
+  it("guided synthesis instructs the agent to call pp_phase_complete when synthesis is complete", () => {
+    const prompt = planningSystemPrompt("/tmp/task", "guided");
+    expect(prompt).toContain("pp_phase_complete");
+    expect(prompt).toContain("Do NOT instead ask the user to run /pp manually");
+  });
+
+  it("autonomous synthesis does not add the guided self-complete directive", () => {
+    const prompt = planningSystemPrompt("/tmp/task", "autonomous");
+    expect(prompt).not.toContain("pp_phase_complete");
+    expect(prompt).not.toContain("Do NOT instead ask the user to run /pp manually");
+  });
+});

package/extensions/orchestrator/phases/planning.ts

@@ -5,7 +5,7 @@ import { resolvePreset, type PiPiConfig, type VariantConfig } 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 { getContextDirs, getLatestSynthesizedPlan } from "../context.js";
+import { getContextDirs, getLatestSynthesizedPlan, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { validatePlan } from "../validate-artifacts.js";
 import type { TaskMode } from "../state.js";
@@ -21,6 +21,10 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
     mode === "autonomous"
       ? "   If planner outputs CONTRADICT each other on a locked decision, resolve it by favoring USER_REQUEST.md, RECORD the contradiction and your chosen resolution in the plan, and proceed — do NOT stall waiting for the user (there is none)."
       : "   If planner outputs CONTRADICT each other on a locked decision, surface the contradiction to the user and let them decide — do NOT silently invent a compromise.";
+  const synthesizeCompletionRule =
+    mode === "autonomous"
+      ? ""
+      : "When you judge the plan synthesis complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead ask the user to run /pp manually.";
   return [
     "[PI-PI — PLAN PHASE]",
     "",
@@ -46,9 +50,12 @@ export function planningSystemPrompt(taskDir: string, mode: TaskMode): string {
     "- ## 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.",
+    "- ## Pattern constraints: include this section whenever the task adds a type, function, parser, annotation, config key, enum, or any user-facing value. For each, name the CLOSEST EXISTING analog in the codebase (found by behavior, not filename) and the exact conventions the implementer MUST mirror: data shape (prefer one existing shape over inventing parallel/duplicated state), spelling/casing of user-facing values (match existing values — never invent a new casing), and parser/validation/error-handling shape. These are acceptance criteria, not suggestions. Omit the section only if the task adds none of the above.",
     "- ## Blockers: unresolved issues blocking implementation (omit if none)",
+    "Write/update the synthesized plan with pp_write_state_file / pp_edit_state_file (NOT the generic write/edit) — they keep the output compact and validate structure.",
     "- No other top-level sections allowed",
-    "- Describe outcomes, not code-level mechanics",
+    "- Describe outcomes, not code-level mechanics, EXCEPT in ## Pattern constraints where naming the concrete analog and conventions is required",
+    ...(synthesizeCompletionRule ? ["", synthesizeCompletionRule] : []),
   ].join("\n");
 }
 
@@ -84,7 +91,7 @@ export async function spawnPlanners(
 
   for (const [variant] of enabledVariants) {
     const outputPath = join(plansDir, `${timestamp}_${variant}.md`);
-    const agent = createPlannerAgent(variant, plannerVariants, { userRequest, research }, outputPath, contextDirs, "plan", repos);
+    const agent = createPlannerAgent(variant, plannerVariants, { userRequest, research, manifest: getArtifactManifest(taskDir) }, outputPath, contextDirs, "plan", repos);
 
     registerAgentDefinitions(pi, [{ type: "planner", variant, ...agent }]);
 
@@ -211,7 +218,7 @@ export async function spawnPlanReviewers(
     const agent = createPlanReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, synthesizedPlan },
+      { userRequest, research, synthesizedPlan, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       "plan",

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

@@ -12,10 +12,7 @@ export function reviewSystemPrompt(taskDir: string, cwd: string): string {
     "- read, lsp, grep, find for understanding the code",
     "- gh pr view for GitHub PR context if a PR URL is mentioned",
     "",
-    "Spawn subagents as needed (subagent_type is REQUIRED — calls without it are rejected):",
-    '- Agent(subagent_type="Explore", ...) — codebase research. Prefer this for most lookups. Fast and cheap.',
-    '- Agent(subagent_type="Librarian", ...) — external docs, library APIs, web research.',
-    "Spawn multiple Explore agents in parallel for broad searches.",
+    "Delegate to subagents where useful (see the delegation guidance in your system prompt) — spawn multiple explores in parallel for broad searches.",
     "",
     "Write your findings:",
     `- ${taskDir}/USER_REQUEST.md — update with a clear problem statement of issues found`,

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

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { reviewSystemPrompt } from "./review.js";
+
+describe("reviewSystemPrompt apply_feedback wording", () => {
+  it("autonomous plan/implement mandates re-calling pp_phase_complete and does not tell the agent to wait for the user", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "plan", "autonomous");
+    expect(prompt).toContain("pp_phase_complete");
+    expect(prompt).not.toContain("Present the synthesis to the user");
+    expect(prompt).not.toContain("A new review pass will begin");
+  });
+
+  it("guided plan/implement keeps the user-facing synthesis behavior", () => {
+    const prompt = reviewSystemPrompt("/tmp/task", 1, "plan", "guided");
+    expect(prompt).toContain("Present the synthesis to the user");
+    expect(prompt).not.toContain("Call pp_phase_complete again to finalize");
+  });
+
+  it("brainstorm prompt is unaffected by mode (never instructs pp_phase_complete)", () => {
+    const auto = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "autonomous");
+    const guided = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "guided");
+    expect(auto).toBe(guided);
+    expect(auto).toContain("BRAINSTORM REVIEW CYCLE");
+    expect(auto).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/");
+    expect(prompt).toContain("pp_write_state_file");
+    // The no-new-sections rule for the two structured files is retained.
+    expect(prompt).toContain("Do NOT add, rename, or remove sections in USER_REQUEST.md or RESEARCH.md");
+  });
+
+  it("autonomous plan feedback folds into a new synthesized plan, not a separate fix-plan file", () => {
+    // Re-review and the transition read only the latest `*synthesized*` plan, so
+    // plan-phase feedback must land there.
+    const plan = reviewSystemPrompt("/tmp/task", 1, "plan", "autonomous");
+    expect(plan).toContain("synthesized.md");
+    expect(plan).not.toContain("do NOT modify the original synthesized plan");
+
+    // The implement phase keeps the fix-plan/implement pattern (synthesized plan
+    // is code guidance there, not the reviewed artifact).
+    const impl = reviewSystemPrompt("/tmp/task", 1, "implement", "autonomous");
+    expect(impl).toContain("Create a fix plan");
+    expect(impl).toContain("Implement the fixes");
+  });
+
+  it("points each phase at the directory its reviewers actually write to", () => {
+    // plan reviewers write to plan-reviews (planning.ts) and outputs load from
+    // plan-reviews (context.ts); the prompt must match, not code-reviews.
+    const plan = reviewSystemPrompt("/tmp/task", 1, "plan", "autonomous");
+    expect(plan).toContain("plan-reviews/");
+    expect(plan).not.toContain("code-reviews/");
+
+    const impl = reviewSystemPrompt("/tmp/task", 1, "implement", "autonomous");
+    expect(impl).toContain("code-reviews/");
+    expect(impl).not.toContain("plan-reviews/");
+
+    const brainstorm = reviewSystemPrompt("/tmp/task", 1, "brainstorm", "guided");
+    expect(brainstorm).toContain("brainstorm-reviews/");
+  });
+});

package/extensions/orchestrator/phases/review.ts

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js";
 import { registerAgentDefinitions, spawnViaRpc, waitForCompletion } from "../agents/registry.js";
 import { createCodeReviewerAgent } from "../agents/code-reviewer.js";
-import { getContextDirs, getLatestSynthesizedPlan } from "../context.js";
+import { getContextDirs, getLatestSynthesizedPlan, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { PhaseSend } from "../transition-controller.js";
 
@@ -12,8 +12,14 @@ function isEnabled(value: { enabled?: boolean } | undefined): boolean {
   return value?.enabled !== false;
 }
 
-export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string): string {
-  const reviewsDir = phase === "brainstorm" ? join(taskDir, "brainstorm-reviews") : join(taskDir, "code-reviews");
+export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string, mode?: "guided" | "autonomous"): string {
+  // Each phase writes/loads its review outputs in a distinct directory:
+  // brainstorm -> brainstorm-reviews, plan -> plan-reviews, everything else
+  // (implement/review) -> code-reviews. The apply_feedback prompt must point the
+  // agent at the SAME directory the reviewers wrote to (see planning.ts /
+  // context.ts), otherwise it synthesizes against the wrong (empty) directory.
+  const reviewsDirName = phase === "brainstorm" ? "brainstorm-reviews" : phase === "plan" ? "plan-reviews" : "code-reviews";
+  const reviewsDir = join(taskDir, reviewsDirName);
   const plansDir = join(taskDir, "plans");
 
   if (phase === "brainstorm") {
@@ -32,36 +38,73 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
       "# 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",
+      "3. If changes are needed: update the content within existing sections of USER_REQUEST.md / RESEARCH.md, and add/update artifacts/ files as needed",
       "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.",
+      "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.",
     ].join("\n");
   }
 
+  // In autonomous plan/implement the phase does NOT complete until the agent
+  // re-calls pp_phase_complete: that is what finalizes the pass and advances the
+  // phase. Telling it to "present to the user" and wait causes the plan phase to
+  // stall after applying feedback. Guided mode keeps the user-facing behavior.
+  const finalStep =
+    mode === "autonomous"
+      ? "3. Call pp_phase_complete again to finalize this review pass. The phase is NOT complete until you do — do NOT stop or wait for the user"
+      : "3. Present the synthesis to the user";
+
+  // In the plan phase the synthesized plan IS the reviewed artifact: re-review
+  // and the phase transition both read only the LATEST `*synthesized*` file (see
+  // getLatestSynthesizedPlan). So autonomous plan feedback must be folded into a
+  // new synthesized plan, NOT a separate fix-plan file (which those readers
+  // ignore). In the implement phase the synthesized plan is code guidance, so
+  // the fix-plan/implement/afterImplement pattern is correct there.
+  const tail =
+    mode === "autonomous"
+      ? phase === "plan"
+        ? [
+            "",
+            "If the reviewers require changes:",
+            `1. Fold the required changes into a NEW synthesized plan at ${plansDir}/<timestamp>_synthesized.md (re-review and the phase transition read only the latest \`*synthesized*\` plan, so the fixes MUST land there — do not write them to a separate fix-plan file)`,
+            "2. Then call pp_phase_complete again — the extension will start a new review pass or advance the phase as appropriate. Do NOT wait for 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. Then call pp_phase_complete again — the extension will start a new review pass or advance the phase as appropriate. Do NOT wait for 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",
+        ];
+
   return [
     `[PI-PI — REVIEW CYCLE (pass ${pass})]`,
     "",
-    "Code reviewer outputs are ready.",
+    "Reviewer outputs are ready.",
     `Read them from ${reviewsDir}/, synthesize feedback, and implement fixes if needed.`,
     "",
-    "You are a SYNTHESIZER: merge the reviewer outputs. Do NOT write your own code review from scratch.",
-    "- Do NOT create the code-reviews/ directory yourself — the extension manages it.",
+    "You are a SYNTHESIZER: merge the reviewer outputs. Do NOT write your own review from scratch.",
+    `- Do NOT create the ${reviewsDirName}/ directory yourself — the extension manages it.`,
     "- Do NOT call plannotator_submit_plan.",
     "",
     "# 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",
+    finalStep,
+    ...tail,
   ].join("\n");
 }
 
@@ -117,7 +160,7 @@ export async function spawnCodeReviewers(
     const agent = createCodeReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, synthesizedPlan },
+      { userRequest, research, synthesizedPlan, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       reviewerPhase,