@ilya-lesikov/pi-pi 0.7.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, findLatestFamilyMatch } 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) => {
@@ -539,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;
@@ -552,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> {
@@ -578,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");
@@ -615,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

@@ -23,6 +23,14 @@ describe("reviewSystemPrompt apply_feedback wording", () => {
     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.

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";
 
@@ -38,13 +38,14 @@ 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");
   }
 
@@ -159,7 +160,7 @@ export async function spawnCodeReviewers(
     const agent = createCodeReviewerAgent(
       variant,
       reviewerVariants,
-      { userRequest, research, synthesizedPlan },
+      { userRequest, research, synthesizedPlan, manifest: getArtifactManifest(taskDir) },
       outputPath,
       contextDirs,
       reviewerPhase,

package/extensions/orchestrator/plannotator.ts

@@ -46,7 +46,8 @@ export function cancelPendingPlannotatorWait(orchestrator: Orchestrator): void {
 export function waitForPlannotatorResult(
   orchestrator: Orchestrator,
   reviewId: string | null,
-): Promise<{ approved: boolean; feedback?: string }> {
+  timeoutMs: number | null = PLANNOTATOR_RESULT_TIMEOUT_MS,
+): Promise<{ approved: boolean; feedback?: string; error?: string }> {
   cancelPendingPlannotatorWait(orchestrator);
   const pi = orchestrator.pi;
   return new Promise((resolve, reject) => {
@@ -54,7 +55,7 @@ export function waitForPlannotatorResult(
     const unsub = pi.events.on("plannotator:review-result", (data: any) => {
       if (reviewId && data?.reviewId && data.reviewId !== reviewId) return;
       cleanup();
-      resolve({ approved: !!data?.approved, feedback: data?.feedback });
+      resolve({ approved: !!data?.approved, feedback: data?.feedback, error: data?.error });
     });
     orchestrator.plannotatorUnsub = unsub;
     function cleanup() {
@@ -66,9 +67,11 @@ export function waitForPlannotatorResult(
         orchestrator.plannotatorTimer = null;
       }
     }
-    orchestrator.plannotatorTimer = setTimeout(() => {
-      cleanup();
-      reject(new Error("Plannotator review timed out"));
-    }, PLANNOTATOR_RESULT_TIMEOUT_MS);
+    if (timeoutMs !== null) {
+      orchestrator.plannotatorTimer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Plannotator review timed out"));
+      }, timeoutMs);
+    }
   });
 }