@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/3p/pi-subagents/src/agent-runner.ts

@@ -2,6 +2,7 @@
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -27,6 +28,53 @@ const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 const TRACER_KEY = Symbol.for("pi-pi:tracer");
 const SUBAGENT_SESSION_KEY = Symbol.for("pi-pi:subagent-session");
 
+// Concurrency-safe subagent lineage. The previous approach derived parent/depth
+// from the mutable process-global SUBAGENT_SESSION_KEY, which is racy for
+// CONCURRENT siblings: MAIN spawns opus/gpt/gemini in parallel, each runAgent's
+// synchronous prologue read whatever the *previous sibling* had just written to
+// the global — so gpt recorded opus as its parent, gemini recorded gpt, forming a
+// bogus opus→gpt→gemini chain with depth 3-6 instead of three depth-1 children of
+// MAIN. AsyncLocalStorage instead propagates DOWN the async call chain (a nested
+// spawn inherits its true parent's store) but NOT ACROSS sibling promises (each
+// sibling started from MAIN sees no store → parent=undefined, depth=1).
+interface SubagentLineage {
+  depth: number;
+  subagentId?: string;
+}
+const subagentLineage = new AsyncLocalStorage<SubagentLineage>();
+
+// The process-global SUBAGENT_SESSION_KEY marker is read elsewhere purely for
+// truthiness ("is any subagent running in this process?", e.g. orchestrator nudge
+// gates). Manage it with a ref-count so concurrent in-process siblings set/clear
+// it correctly regardless of completion order (a plain save/restore would leak a
+// stale marker whenever the last sibling to finish wasn't the last to start).
+let activeSubagentRuns = 0;
+let markerBeforeFirstRun: unknown;
+function enterSubagentMarker(): void {
+  if (activeSubagentRuns === 0) {
+    // Snapshot whatever was there before our first concurrent run (undefined in
+    // the main process; the orchestrator's persistent bootstrap { depth: 1 } in a
+    // subagent process) so we can restore it exactly when the last run exits.
+    markerBeforeFirstRun = (globalThis as any)[SUBAGENT_SESSION_KEY];
+  }
+  activeSubagentRuns++;
+  const marker = (globalThis as any)[SUBAGENT_SESSION_KEY];
+  if (typeof marker !== "object" || marker === null) {
+    (globalThis as any)[SUBAGENT_SESSION_KEY] = { depth: 1 };
+  }
+}
+function exitSubagentMarker(): void {
+  activeSubagentRuns = Math.max(0, activeSubagentRuns - 1);
+  if (activeSubagentRuns === 0) {
+    if (markerBeforeFirstRun === undefined) {
+      delete (globalThis as any)[SUBAGENT_SESSION_KEY];
+    } else {
+      (globalThis as any)[SUBAGENT_SESSION_KEY] = markerBeforeFirstRun;
+    }
+    markerBeforeFirstRun = undefined;
+  }
+}
+
 interface PiPiTracer {
   openSubagent(meta: {
     subagentId: string;
@@ -45,11 +93,6 @@ function getTracer(): PiPiTracer | undefined {
   return (globalThis as any)[TRACER_KEY];
 }
 
-function subagentDepth(): number {
-  const marker = (globalThis as any)[SUBAGENT_SESSION_KEY];
-  return typeof marker?.depth === "number" ? marker.depth : 1;
-}
-
 function traceSubagentEvent(subagentId: string | undefined, event: AgentSessionEvent, turnIndex: number): void {
   if (!subagentId) return;
   const tracer = getTracer();
@@ -242,21 +285,22 @@ export async function runAgent(
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
-  // Shared marker with extensions/orchestrator/index.ts (SUBAGENT_SESSION_KEY).
-  // Canonical shape is { depth: number }; a legacy boolean true is tolerated as depth 1.
-  const subagentSessionKey = Symbol.for("pi-pi:subagent-session");
-  const previousSubagentSession = (globalThis as any)[subagentSessionKey];
-  const previousDepth = typeof previousSubagentSession === "object" && previousSubagentSession !== null
-    ? ((previousSubagentSession as { depth?: number }).depth ?? 0)
-    : previousSubagentSession
-      ? 1
-      : 0;
-  const parentSubagentId = typeof previousSubagentSession === "object" && previousSubagentSession !== null
-    ? (previousSubagentSession as { subagentId?: string }).subagentId
-    : undefined;
-  const subagentSessionState = { depth: previousDepth + 1, subagentId: options.subagentId };
-  (globalThis as any)[subagentSessionKey] = subagentSessionState;
 
+  // Derive lineage from the async-context store (see subagentLineage above).
+  // Reading it BEFORE entering the child's own als.run means concurrent siblings
+  // each see their real parent (MAIN → undefined store), not a leaked sibling.
+  const parentLineage = subagentLineage.getStore();
+  const parentSubagentId = parentLineage?.subagentId;
+  const traceDepth = (parentLineage?.depth ?? 0) + 1;
+  const childLineage: SubagentLineage = { depth: traceDepth, subagentId: options.subagentId };
+
+  // Mark the process as "running a subagent" for truthiness readers (see
+  // enter/exitSubagentMarker). Lineage (parent/depth) comes from als above, so
+  // this marker no longer participates in nesting math and its old sibling-race
+  // can no longer corrupt the org chart.
+  enterSubagentMarker();
+
+  return subagentLineage.run(childLineage, async () => {
   try {
     const env = await detectEnv(options.pi, effectiveCwd);
 
@@ -460,7 +504,7 @@ export async function runAgent(
           description: options.subagentDescription,
           parentToolCallId: options.parentToolCallId,
           parentSubagentId,
-          depth: subagentDepth(),
+          depth: traceDepth,
           systemPrompt,
           effectivePrompt,
         });
@@ -496,20 +540,9 @@ export async function runAgent(
     }
     return { responseText, session, aborted, steered: softLimitReached };
   } finally {
-    const currentDepth = typeof (globalThis as any)[subagentSessionKey] === "object" && (globalThis as any)[subagentSessionKey] !== null
-      ? ((((globalThis as any)[subagentSessionKey]) as { depth?: number }).depth ?? subagentSessionState.depth)
-      : subagentSessionState.depth;
-    const nextDepth = Math.max(0, currentDepth - 1);
-    if (nextDepth === 0) {
-      if (previousSubagentSession === undefined) {
-        delete (globalThis as any)[subagentSessionKey];
-      } else {
-        (globalThis as any)[subagentSessionKey] = previousSubagentSession;
-      }
-    } else {
-      (globalThis as any)[subagentSessionKey] = { depth: nextDepth };
-    }
+    exitSubagentMarker();
   }
+  });
 }
 
 /**

package/3p/pi-subagents/src/index.ts

@@ -402,13 +402,7 @@ Use get_subagent_result for full output.`,
   }
 
   // Background completion: route through group join or send individual nudge
-  const firstProgressSeen = new Set<string>();
-  const firstTurnSeen = new Set<string>();
-
   const manager = new AgentManager((record) => {
-    firstProgressSeen.delete(record.id);
-    firstTurnSeen.delete(record.id);
-
     let eventData: ReturnType<typeof buildEventData> | undefined;
     try {
       eventData = buildEventData(record);
@@ -907,36 +901,9 @@ Guidelines:
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
 
         let id: string;
-        const emitFirstTool = (toolName: string) => {
-          if (firstProgressSeen.has(id)) return;
-          firstProgressSeen.add(id);
-          pi.events.emit("subagents:first_tool", {
-            id,
-            type: subagentType,
-            description: params.description,
-            toolName,
-          });
-        };
-        const emitFirstTurn = (turnCount: number) => {
-          if (firstTurnSeen.has(id)) return;
-          firstTurnSeen.add(id);
-          pi.events.emit("subagents:first_turn", {
-            id,
-            type: subagentType,
-            description: params.description,
-            turnCount,
-          });
-        };
-        const originalBgToolActivity = bgCallbacks.onToolActivity;
-        bgCallbacks.onToolActivity = (activity) => {
-          originalBgToolActivity(activity);
-          if (activity.type === "start") emitFirstTool(activity.toolName);
-        };
-        const originalBgTurnEnd = bgCallbacks.onTurnEnd;
-        bgCallbacks.onTurnEnd = (turnCount) => {
-          originalBgTurnEnd(turnCount);
-          emitFirstTurn(turnCount);
-        };
+        // first_tool/first_turn are now emitted centrally by AgentManager.startAgent
+        // (the single choke point for ALL spawn paths, including RPC-spawned panels),
+        // so no per-branch wiring is needed here.
 
         // Wrap onSessionCreated to wire output file streaming.
         // The callback lazily reads record.outputFile (set right after spawn)
@@ -944,8 +911,6 @@ Guidelines:
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
           origBgOnSession(session);
-          firstProgressSeen.delete(id);
-          firstTurnSeen.delete(id);
           const rec = manager.getRecord(id);
           if (rec?.outputFile) {
             rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);

package/3p/pi-subagents/src/types.ts

@@ -81,6 +81,10 @@ export interface AgentRecord {
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
+  /** Whether the subagents:first_tool event has been emitted for this run. */
+  firstToolEmitted?: boolean;
+  /** Whether the subagents:first_turn event has been emitted for this run. */
+  firstTurnEmitted?: boolean;
   /** Path to the streaming output transcript file. */
   outputFile?: string;
   /** Cleanup function for the output file stream subscription. */

package/extensions/orchestrator/agents/advisor.ts

@@ -0,0 +1,35 @@
+import type { PiPiConfig } from "../config.js";
+import { resolveModel } from "../model-registry.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
+
+export function createAdvisorAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Deep-reasoning advisor for design decisions and 'why is this broken' analysis (pi-pi)",
+      tools: `read, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple.advisor.model),
+      thinking: config.agents.subagents.simple.advisor.thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a deep-reasoning ADVISOR. You investigate one hard question — a design decision, an architecture tradeoff, a \"why is this broken\", or a correctness/soundness judgment — and return a reasoned recommendation backed by evidence.",
+      "These rules override your default helpfulness. Strict compliance is required.",
+      "You are READ-ONLY: you MUST NOT modify any file. Diagnose and advise; do NOT change code.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "- Verify every claim with tool calls — read the actual code. Never reason from memory about this codebase.",
+      "- Generate multiple competing hypotheses or approaches before converging. Surface and question hidden assumptions.",
+      "- Scope recommendations by effort: name the quick fix vs the thorough one.",
+      "- Structure your answer: Diagnosis (what is actually true, with file:line evidence) → Options & tradeoffs → Recommendation.",
+      "- Be honest about uncertainty. If evidence is thin, say so and state what would resolve it.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/brainstorm-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createBrainstormReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[] },
+  taskArtifacts: { userRequest: string; research: string; artifacts?: { name: string; content: string }[]; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -64,10 +64,10 @@ export function createBrainstormReviewerAgent(
       "- INACCURACIES: (claims that don't match the code)",
       "- SUGGESTIONS: (improvements, not required)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — 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.",
+      "You may spawn ONLY explore/librarian subagents (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. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       "# MANDATORY: Write your review to this exact file using the write tool:",
@@ -88,7 +88,7 @@ export function createBrainstormReviewerAgent(
         : []),
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/code-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createCodeReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan?: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -21,6 +21,9 @@ export function createCodeReviewerAgent(
   const contextFiles = loadAllContextFiles(contextDirs, "codeReviewer", "system", phase, getModelInfo(variantConfig.model));
   const contextBlock = contextFiles.map((f) => f.content).join("\n\n");
   const repoContext = buildRepoContext(repos);
+  // A standalone review task (phase "review") has no synthesized plan: review the
+  // diff against USER_REQUEST.md/RESEARCH.md, not an implementation plan.
+  const hasPlan = typeof taskArtifacts.synthesizedPlan === "string" && taskArtifacts.synthesizedPlan.trim().length > 0;
 
   return {
     frontmatter: {
@@ -53,11 +56,15 @@ export function createCodeReviewerAgent(
       "3. Read changed files for full context",
       "4. Run lsp diagnostics on changed files",
       "5. Use lsp findReferences to check callers of modified functions",
-      "6. Check the implementation against the plan",
+      hasPlan
+        ? "6. Check the implementation against the plan"
+        : "6. Check the changes against USER_REQUEST.md and RESEARCH.md (there is no implementation plan for a standalone review)",
       "",
       "Review criteria:",
       "- Bugs: logic errors, off-by-ones, null handling, race conditions",
-      "- Correctness: does it match the plan and user request?",
+      hasPlan
+        ? "- Correctness: does it match the plan and user request?"
+        : "- Correctness: does it match the user request and the reviewed scope?",
       "- Quality: error handling, edge cases, type safety",
       "- Missing: untested paths, unhandled errors, incomplete implementations",
       "",
@@ -81,10 +88,20 @@ export function createCodeReviewerAgent(
       "- MINOR: (nice to have)",
       "- OPEN QUESTIONS: (low-confidence concerns, speculative follow-ups)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — 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.",
+      "After the findings, include a machine-readable ANCHORS block so the synthesizer can place",
+      "the findings at their exact locations (in source AI_COMMENT markers and/or GitHub PR line comments).",
+      "Emit one line per actionable finding (CRITICAL/MAJOR/MINOR), in this EXACT format:",
+      "ANCHORS:",
+      "<relative/path/from/repo/root>:<line> — <severity>: <one-line finding>",
+      "Rules:",
+      "- Use the repo-relative path (as `git diff` shows it) and a single 1-based line number on the NEW side of the diff.",
+      "- One finding per line; omit findings you cannot pin to a concrete file:line (keep those in OPEN QUESTIONS).",
+      "- If there are no actionable findings, write `ANCHORS:` followed by `(none)`.",
+      "",
+      "You may spawn ONLY explore/librarian subagents (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. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -97,11 +114,10 @@ export function createCodeReviewerAgent(
       "=== RESEARCH ===",
       taskArtifacts.research,
       "",
-      "=== SYNTHESIZED PLAN ===",
-      taskArtifacts.synthesizedPlan,
+      ...(hasPlan ? ["=== SYNTHESIZED PLAN ===", taskArtifacts.synthesizedPlan as string, ""] : []),
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }

package/extensions/orchestrator/agents/constraints.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { closingBlockInstruction, completionLine, constraintsBlock } from "./constraints.js";
+
+describe("completionLine", () => {
+  it("guided plan and implement instruct calling pp_phase_complete on completion", () => {
+    for (const phase of ["plan", "implement"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("call pp_phase_complete");
+      expect(line).not.toContain("Do NOT advance on your own");
+      expect(line).not.toMatch(/do not.*wait for.*input/i);
+    }
+  });
+
+  it("guided review and debug stay hands-off (no unprompted self-complete)", () => {
+    for (const phase of ["review", "debug"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("Do NOT advance on your own or call pp_phase_complete unprompted");
+    }
+  });
+
+  it("guided brainstorm never self-completes", () => {
+    const line = completionLine("brainstorm", "guided");
+    expect(line).toContain("Do NOT call pp_phase_complete yourself");
+  });
+
+  it("autonomous phases always self-complete regardless of phase", () => {
+    for (const phase of ["plan", "implement", "review", "brainstorm"] as const) {
+      expect(completionLine(phase, "autonomous")).toContain("call pp_phase_complete");
+    }
+  });
+
+  it("guided handoff phases require the standardized closing block", () => {
+    for (const phase of ["brainstorm", "review", "debug"] as const) {
+      const line = completionLine(phase, "guided");
+      expect(line).toContain("the standardized block");
+      expect(line).toContain("Advance via the /pp menu");
+    }
+  });
+
+  it("autonomous phases do not emit the prose closing block", () => {
+    expect(completionLine("brainstorm", "autonomous")).not.toContain("Advance via the /pp menu");
+  });
+});
+
+describe("closingBlockInstruction", () => {
+  it("spells out the exact block with a blank line between summary and advance, no rules", () => {
+    const block = closingBlockInstruction("brainstorm");
+    expect(block).toContain("Advance via the /pp menu to move into plan");
+    expect(block).not.toContain("────");
+    expect(block).toContain("/pp");
+    expect(block).toContain("✅ <one-sentence summary of what this phase produced>\n\n▶ Advance via the /pp menu to move into plan.");
+  });
+
+  it("prepends the Review Summary schema ONLY for the review phase, before the closing block", () => {
+    const review = closingBlockInstruction("review");
+    expect(review).toContain("## Review Summary");
+    expect(review).toContain("| # | Severity | Location | Finding |");
+    expect(review).toContain("BLOCKER");
+    // The ✅/▶ lines must remain the final lines of the block.
+    expect(review.trimEnd().endsWith("▶ Advance via the /pp menu to move into plan.")).toBe(true);
+    expect(review.indexOf("## Review Summary")).toBeLessThan(review.indexOf("✅ <one-sentence summary"));
+  });
+
+  it("does NOT emit the Review Summary schema for brainstorm or debug closes", () => {
+    for (const phase of ["brainstorm", "debug"] as const) {
+      expect(closingBlockInstruction(phase)).not.toContain("## Review Summary");
+    }
+  });
+});
+
+describe("constraintsBlock", () => {
+  it("guided implement block tells the agent to self-complete", () => {
+    const block = constraintsBlock("implement", "guided");
+    expect(block).toContain("call pp_phase_complete");
+    expect(block).not.toContain("Do NOT advance on your own");
+  });
+
+  it("guided plan block tells the agent to self-complete", () => {
+    const block = constraintsBlock("plan", "guided");
+    expect(block).toContain("call pp_phase_complete");
+  });
+});

package/extensions/orchestrator/agents/constraints.ts

@@ -3,6 +3,14 @@ import type { Phase, TaskMode } from "../state.js";
 const READONLY_CONSTRAINT =
   "You MUST NOT edit, create, or delete any project file (source, tests, config, docs) — only files under .pp/state/ may be written — and you MUST NOT run state-changing shell commands. If you find a fix worth making, record it in your output; do NOT apply it here.";
 
+// The review phase is read-only EXCEPT for publishing findings: the main agent may
+// insert or remove `AI_COMMENT:` markers in source files (file comments), and may
+// run `gh` to post/read GitHub PR line comments AND bundled pull-request reviews
+// (PR comments) — and nothing else (no fixes, no other edits, no other state-changing
+// commands). This is the reviewer→user mirror of the user→reviewer `AI_REVIEW:` markers.
+const REVIEW_READONLY_CONSTRAINT =
+  "You MUST NOT edit, create, or delete any project file (source, tests, config, docs) — only files under .pp/state/ may be written — and you MUST NOT run state-changing shell commands, WITH ONE EXCEPTION: when publishing review findings you MAY insert or remove `AI_COMMENT:` markers in source files (in each file's native comment syntax) and MAY run `gh` to post or read GitHub PR comments — including line comments and bundled pull-request reviews (a review body plus its line comments) — and nothing else. Do NOT apply fixes or make any other source change. If you find a fix worth making, record it in your output.";
+
 const IMPLEMENT_CONSTRAINT =
   "Implement only the approved plan. Do NOT add scope or change plan items without recording why in the plan. If the same fix fails 3 times, stop and re-plan — do NOT keep retrying the same approach.";
 
@@ -16,9 +24,62 @@ export function isReadOnlyPhase(phase: Phase): boolean {
 export function phaseConstraint(phase: Phase): string {
   if (phase === "implement") return IMPLEMENT_CONSTRAINT;
   if (phase === "quick") return QUICK_CONSTRAINT;
+  if (phase === "review") return REVIEW_READONLY_CONSTRAINT;
   return READONLY_CONSTRAINT;
 }
 
+// Guided phases that stop and hand back to the user (brainstorm, review, debug) end their turn
+// with prose rather than a tool call. To keep that handoff consistent, the model must close with
+// this exact block. NEXT_PHASE_LABEL supplies the phase the /pp menu advances into.
+const NEXT_PHASE_LABEL: Partial<Record<Phase, string>> = {
+  brainstorm: "plan",
+  review: "plan",
+  debug: "plan",
+};
+
+// The structured summary a review must print when it finishes, on BOTH review finish paths
+// (the review-cycle synthesis in review.ts and the ordinary review-task close here). Counts
+// reconcile with the `ANCHORS:` block: when it is `(none)`, Anchored=0 and every finding is
+// Un-anchorable. Location is `file:line`, or `file:—` for un-anchorable findings.
+export const REVIEW_SUMMARY_SCHEMA = [
+  "## Review Summary",
+  "",
+  "Scope: <repos/PR/branch/range + change size>",
+  "",
+  "| Repo | PR | Findings | Anchored | Un-anchorable |",
+  "|------|----|----------|----------|---------------|",
+  "| <owner/repo> | #<n> | <total> | <in-diff> | <not-in-diff> |",
+  "",
+  "### Findings",
+  "| # | Severity | Location | Finding |",
+  "|---|----------|----------|---------|",
+  "| 1 | BLOCKER | <file:line or file:—> | <one line> |",
+  "",
+  "Next step: /pp → Next → Publish to post these as GitHub PR comments or file comments.",
+].join("\n");
+
+// Instruction wrapping REVIEW_SUMMARY_SCHEMA: severity vocabulary is fixed and the summary
+// degrades gracefully to a single-repo / no-PR row when only one repo (or no PR) was resolved.
+export const reviewSummaryInstruction = [
+  "Before the closing block, print a structured Review Summary in EXACTLY this shape (fill in the values; severity is one of BLOCKER / MAJOR / MINOR, uppercase):",
+  "",
+  REVIEW_SUMMARY_SCHEMA,
+  "",
+  "Counts MUST reconcile with the `ANCHORS:` block: an `(none)` block means Anchored=0 and every finding is Un-anchorable. Fill the table from whatever repos/PR you resolved; degrade to a single-repo / no-PR row when there is only one repo or no PR.",
+].join("\n");
+
+export function closingBlockInstruction(phase: Phase): string {
+  const next = NEXT_PHASE_LABEL[phase] ?? "the next phase";
+  const summary = phase === "review" ? reviewSummaryInstruction + "\n\n" : "";
+  return [
+    summary +
+    "End that turn with EXACTLY this block, verbatim, as the final lines of your message (fill the summary line with one sentence; change nothing else):",
+    "✅ <one-sentence summary of what this phase produced>",
+    "",
+    `▶ Advance via the /pp menu to move into ${next}.`,
+  ].join("\n");
+}
+
 export function completionLine(phase: Phase, mode: TaskMode): string {
   if (phase === "quick") {
     return "When the user's request is complete, call pp_phase_complete. Do NOT stop and wait for the user before then.";
@@ -27,9 +88,12 @@ export function completionLine(phase: Phase, mode: TaskMode): string {
     return "There is no user driving this phase. The moment its work is complete, call pp_phase_complete — do NOT pause, ask for confirmation, or wait for input. Never end a turn with prose: every turn ends in a tool call.";
   }
   if (phase === "brainstorm") {
-    return "This is a conversation. Do NOT call pp_phase_complete yourself — keep going until the user ends it or advances via the /pp menu.";
+    return "This is a conversation. Do NOT call pp_phase_complete yourself — keep going until the user ends it or advances via the /pp menu. When you have delivered a complete answer and are handing back for the user to advance, close with the standardized block. " + closingBlockInstruction(phase);
+  }
+  if (phase === "plan" || phase === "implement") {
+    return "When you judge this phase complete, call pp_phase_complete — the extension opens the advance gate for the user to review and confirm. Do NOT instead stop and ask the user to run /pp manually.";
   }
-  return "When the work is complete, stop and let the user review and advance it via the /pp menu. Do NOT advance on your own or call pp_phase_complete unprompted.";
+  return "When the work is complete, stop and let the user review and advance it via the /pp menu. Do NOT advance on your own or call pp_phase_complete unprompted. Close with the standardized block. " + closingBlockInstruction(phase);
 }
 
 const PHASE_IDENTITY: Record<string, string> = {

package/extensions/orchestrator/agents/deep-debugger.ts

@@ -0,0 +1,35 @@
+import type { PiPiConfig } from "../config.js";
+import { resolveModel } from "../model-registry.js";
+import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-routing.js";
+
+export function createDeepDebuggerAgent(config: PiPiConfig) {
+  return {
+    frontmatter: {
+      description: "Deep root-cause analysis for HARD, persistent failures — not every error (pi-pi)",
+      tools: `read, write, edit, bash, grep, find, ls, lsp, ast_search, ${ALL_CBM_TOOLS}, ${EXA_TOOLS}`,
+      model: resolveModel(config.agents.subagents.simple["deep-debugger"].model),
+      thinking: config.agents.subagents.simple["deep-debugger"].thinking,
+      max_turns: 120,
+      prompt_mode: "replace",
+    },
+    prompt: [
+      "<constraints>",
+      "You are a DEEP DEBUGGER. You do root-cause analysis on hard, persistent failures — failing tests, build/compile errors, regressions, flaky behavior — that quick attempts have NOT resolved. Do NOT engage for trivial or first-attempt errors.",
+      "These rules override your default helpfulness. Strict compliance is required.",
+      "You have write/edit access for DIAGNOSIS ONLY: creating repro scripts, adding temporary logging, or running experiments. You MUST NOT write the actual fix in the source code — find the root cause and recommend the fix; do NOT apply it. Remove any temporary diagnostic artifacts you create.",
+      "</constraints>",
+      "",
+      PRINCIPLES_BLOCK,
+      "",
+      TOOLS_BLOCK,
+      "",
+      "<task>",
+      "- Reproduce/inspect first: run the failing command, read the actual error and stack trace, check recent changes (git diff, cbm_changes).",
+      "- Form competing hypotheses. For each, gather evidence FOR and AGAINST with tool calls. Do not commit to the first plausible cause.",
+      "- Trace the failure to its true root, not the surface symptom. Use lsp findReferences / cbm_trace to follow the chain.",
+      "- Report: Symptom → Hypotheses considered (with evidence) → Root cause (with file:line proof) → Minimal recommended fix.",
+      "- If you cannot prove the root cause, say so: report the narrowed-down suspects and the single most useful next probe.",
+      "</task>",
+    ].join("\n"),
+  };
+}

package/extensions/orchestrator/agents/plan-reviewer.ts

@@ -1,5 +1,5 @@
 import type { VariantConfig } from "../config.js";
-import { loadAllContextFiles } from "../context.js";
+import { loadAllContextFiles, formatManifestBlock } from "../context.js";
 import { resolveModel, getModelInfo } from "../model-registry.js";
 import type { RepoInfo } from "../repo-utils.js";
 import { buildRepoContext } from "./repo-context.js";
@@ -8,7 +8,7 @@ import { TOOLS_BLOCK, ALL_CBM_TOOLS, EXA_TOOLS, PRINCIPLES_BLOCK } from "./tool-
 export function createPlanReviewerAgent(
   variant: string,
   variants: Record<string, VariantConfig>,
-  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string },
+  taskArtifacts: { userRequest: string; research: string; synthesizedPlan: string; manifest?: { title: string; path: string }[] },
   outputPath: string,
   contextDirs: string[],
   phase?: string,
@@ -63,10 +63,10 @@ export function createPlanReviewerAgent(
       "- BLOCKERS: (critical issues that must be fixed)",
       "- SUGGESTIONS: (improvements, not required)",
       "",
-      "subagent_type is REQUIRED when spawning subagents — 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.",
+      "You may spawn ONLY explore/librarian subagents (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. Do NOT spawn task, advisor, deep-debugger, or reviewer.",
       "</task>",
       "",
       // --- dynamic suffix ---
@@ -87,7 +87,7 @@ export function createPlanReviewerAgent(
       taskArtifacts.synthesizedPlan,
       ...(repoContext ? [repoContext] : []),
       "",
-      "The artifacts above are already in your context. Do NOT re-read them from disk.",
+      formatManifestBlock(taskArtifacts.manifest ?? []),
     ].join("\n"),
   };
 }