@ilya-lesikov/pi-pi 0.9.0 → 0.10.0

package/extensions/orchestrator/phases/review.ts

@@ -1,12 +1,13 @@
 import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { resolvePreset, type PiPiConfig, type VariantConfig } from "../config.js";
+import { resolvePreset, reviewPresetGroupForPhase, 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, getArtifactManifest } from "../context.js";
 import type { RepoInfo } from "../repo-utils.js";
 import type { PhaseSend } from "../transition-controller.js";
+import { isReviewFileForRound } from "../review-files.js";
 
 function isEnabled(value: { enabled?: boolean } | undefined): boolean {
   return value?.enabled !== false;
@@ -14,19 +15,23 @@ function isEnabled(value: { enabled?: boolean } | undefined): boolean {
 
 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
+  // brainstorm/debug -> 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 reviewsDirName = reviewPresetGroupForPhase(phase ?? "") === "brainstormReviewers"
+    ? "brainstorm-reviews"
+    : phase === "plan"
+    ? "plan-reviews"
+    : "code-reviews";
   const reviewsDir = join(taskDir, reviewsDirName);
   const plansDir = join(taskDir, "plans");
 
-  if (phase === "brainstorm") {
+  if (reviewPresetGroupForPhase(phase ?? "") === "brainstormReviewers") {
     return [
-      `[PI-PI — BRAINSTORM REVIEW CYCLE (pass ${pass})]`,
+      `[PI-PI — ${phase === "debug" ? "DEBUG" : "BRAINSTORM"} REVIEW CYCLE (pass ${pass})]`,
       "",
-      "Brainstorm reviewer outputs are ready.",
+      `${phase === "debug" ? "Debug" : "Brainstorm"} reviewer outputs are ready.`,
       `Read them from ${reviewsDir}/.`,
       "",
       "# FORBIDDEN:",
@@ -42,6 +47,11 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
       "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",
       "",
+      "# Interaction (adapted streamlined flow for this synthesis step):",
+      "- Work autonomously through the reviewer outputs; do NOT interrupt with mid-flow questions — a genuine blocker is the only reason to stop and ask.",
+      `- For a hard or contentious call (reviewers disagree, or a high-stakes change to USER_REQUEST/RESEARCH), consult an advisor whose model family differs from yours before committing — you run on ${phase === "debug" ? "GPT, so default to a Claude-family advisor" : "Claude, so default to a GPT-family advisor"}; escalate for the hardest calls.`,
+      "- Before finalizing any concrete, costly-to-reverse or opinion-heavy edit (exact wording, structure, naming, defaults), surface the ACTUAL proposed change rather than silently burying it.",
+      "",
       "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.",
@@ -71,6 +81,11 @@ export function reviewSystemPrompt(taskDir: string, pass: number, phase?: string
       `2. Synthesize into ${reviewsDir}/<unix-epoch-seconds>_final_pass-${pass}.md (prefix with the current Unix epoch seconds, e.g. \`date +%s\`, so the file orders chronologically)`,
       "3. Present the synthesis to the user",
       "",
+      "# Interaction (adapted streamlined flow for this synthesis step):",
+      "- Work autonomously through the reviewer outputs; do NOT interrupt with mid-flow questions — a genuine blocker is the only reason to stop and ask.",
+      "- For a hard or contentious call (reviewers disagree, or a high-stakes accept/reject), consult an advisor whose model family differs from yours before committing — you run on Claude, so default to a GPT-family advisor; escalate for the hardest calls.",
+      "- Surface committed specifics rather than burying them: present the synthesis (and any contentious accept/reject decisions) to the user clearly before finalizing.",
+      "",
       "In the synthesized final-review file you MUST include a machine-readable `ANCHORS:` block for the accepted findings — one line per finding in EXACTLY this format (a later publish step consumes these lines):",
       "ANCHORS:",
       "<relative/path/from/repo/root>:<line> — <one-line finding>",
@@ -237,7 +252,7 @@ export async function spawnCodeReviewers(
   await Promise.allSettled(results);
 
   const reviewFiles = existsSync(reviewsDir)
-    ? readdirSync(reviewsDir).filter((f) => f.includes(`round-${round}`) && !f.includes("final"))
+    ? readdirSync(reviewsDir).filter((f) => isReviewFileForRound(f, round))
     : [];
 
   if (reviewFiles.length > 0) {

package/extensions/orchestrator/phases/spawn-blocking.test.ts

@@ -9,6 +9,7 @@ let waitStarted = false;
 vi.mock("../agents/registry.js", () => ({
   registerAgentDefinitions: vi.fn(),
   unregisterAgentDefinitions: vi.fn(),
+  getAgentConfigSnapshot: vi.fn(() => undefined),
   spawnViaRpc: vi.fn(async () => ({ id: `agent-${Math.random().toString(36).slice(2)}` })),
   waitForCompletion: vi.fn(
     () =>

package/extensions/orchestrator/phases/verdict.ts

@@ -1,6 +1,8 @@
 import { readFileSync, existsSync, readdirSync } from "fs";
 import { join } from "path";
 import type { Phase } from "../state.js";
+import { isReviewFileForRound } from "../review-files.js";
+import { reviewPresetGroupForPhase } from "../config.js";
 
 export type ReviewVerdict = "approve" | "changes" | "unknown";
 
@@ -50,8 +52,9 @@ export function hasActionableFindings(reviewContent: string): boolean {
 }
 
 function reviewsDirForPhase(taskDir: string, phase: Phase): string {
-  if (phase === "brainstorm") return join(taskDir, "brainstorm-reviews");
-  if (phase === "plan") return join(taskDir, "plan-reviews");
+  const group = reviewPresetGroupForPhase(phase);
+  if (group === "brainstormReviewers") return join(taskDir, "brainstorm-reviews");
+  if (group === "planReviewers") return join(taskDir, "plan-reviews");
   return join(taskDir, "code-reviews");
 }
 
@@ -64,9 +67,7 @@ export function reviewPassUnanimousApprove(
   if (expectedReviewerCount <= 0) return false;
   const dir = reviewsDirForPhase(taskDir, phase);
   if (!existsSync(dir)) return false;
-  const files = readdirSync(dir).filter(
-    (f) => f.includes(`round-${round}`) && !f.includes("final") && f.endsWith(".md"),
-  );
+  const files = readdirSync(dir).filter((f) => isReviewFileForRound(f, round));
   if (files.length < expectedReviewerCount) return false;
   for (const f of files) {
     let content: string;

package/extensions/orchestrator/plannotator-open-failure.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+const openOutcome = { value: "not-handled" as "opened" | "timeout" | "not-handled" };
+vi.mock("./plannotator.js", () => ({
+  cancelPendingPlannotatorWait: () => {},
+  waitForPlannotatorResult: vi.fn(async () => ({ approved: true })),
+  openPlannotator: vi.fn(async () => ({
+    opened: false,
+    reviewId: null,
+    outcome: openOutcome.value,
+  })),
+}));
+
+import { enterReviewCycle } from "./event-handlers.js";
+import { getDefaultConfig } from "./config.js";
+
+const tempDirs: string[] = [];
+function makeTaskDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-plan-open-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function makeOrchestrator(): any {
+  const dir = makeTaskDir();
+  mkdirSync(join(dir, "plans"), { recursive: true });
+  writeFileSync(join(dir, "plans", "1_synthesized.md"), "# Plan\n\n## Scope\nx\n\n## Checklist\n- [ ] a — Done when: b\n", "utf-8");
+  return {
+    active: {
+      dir,
+      type: "implement",
+      state: { phase: "plan", step: "llm_work", reviewCycle: null, reviewPass: 0 },
+    },
+    pi: {},
+    config: getDefaultConfig(),
+    cwd: dir,
+  };
+}
+
+afterEach(() => {
+  for (const d of tempDirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+describe("enterReviewCycle plan-phase Plannotator open failure", () => {
+  const ctx = { ui: { setWorkingMessage: () => {}, notify: () => {} } };
+
+  it("timeout failure ends with the 'Choose another option.' sentinel so the menu loops back", async () => {
+    openOutcome.value = "timeout";
+    const orchestrator = makeOrchestrator();
+    const msg = await enterReviewCycle(orchestrator, ctx, "plannotator");
+    expect(msg).toContain("did not respond within 30s");
+    // handleReviewResult (pp-menu.ts) matches the exact "Choose another option."
+    // sentinel to keep the inline Review menu open for retry/another method.
+    expect(msg).toContain("Choose another option.");
+  });
+
+  it("not-handled failure ends with the same sentinel and a distinct diagnosis", async () => {
+    openOutcome.value = "not-handled";
+    const orchestrator = makeOrchestrator();
+    const msg = await enterReviewCycle(orchestrator, ctx, "plannotator");
+    expect(msg).toContain("no handler responded");
+    expect(msg).toContain("Choose another option.");
+  });
+});

package/extensions/orchestrator/plannotator.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   cancelPendingPlannotatorWait,
   openPlannotator,
+  openAnnotateReview,
   waitForPlannotatorResult,
 } from "./plannotator.js";
 import type { Orchestrator } from "./orchestrator.js";
@@ -79,7 +80,43 @@ describe("openPlannotator", () => {
     });
     const pi = { events } as any;
     const result = await openPlannotator(pi, "open", {});
-    expect(result).toEqual({ opened: true, reviewId: "rev-9" });
+    expect(result).toEqual({ opened: true, reviewId: "rev-9", outcome: "opened" });
     expect(clearSpy).toHaveBeenCalled();
   });
+
+  it("reports the not-handled outcome when no handler claims the request", async () => {
+    const events = makeEvents();
+    events.on("plannotator:request", (req: any) => {
+      req.respond({ status: "not-handled" });
+    });
+    const result = await openPlannotator({ events } as any, "open", {});
+    expect(result).toEqual({ opened: false, reviewId: null, outcome: "not-handled" });
+  });
+
+  it("reports the timeout outcome when nothing responds within 30s", async () => {
+    vi.useFakeTimers();
+    const events = makeEvents();
+    const p = openPlannotator({ events } as any, "open", {});
+    await vi.advanceTimersByTimeAsync(30000 + 1);
+    await expect(p).resolves.toEqual({ opened: false, reviewId: null, outcome: "timeout" });
+  });
+});
+
+describe("openAnnotateReview", () => {
+  it("resolves with the synchronous annotate result", async () => {
+    const events = makeEvents();
+    events.on("plannotator:request", (req: any) => {
+      req.respond({ status: "handled", result: { feedback: "tighten scope" } });
+    });
+    const result = await openAnnotateReview({ events } as any, { folderPath: "/task" });
+    expect(result).toEqual({ opened: true, result: { feedback: "tighten scope" } });
+  });
+
+  it("does not hang forever when no handler responds (bounded timeout)", async () => {
+    vi.useFakeTimers();
+    const events = makeEvents();
+    const p = openAnnotateReview({ events } as any, { folderPath: "/task" }, 1000);
+    await vi.advanceTimersByTimeAsync(1001);
+    await expect(p).resolves.toEqual({ opened: false, result: null });
+  });
 });

package/extensions/orchestrator/plannotator.ts

@@ -1,16 +1,18 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Orchestrator } from "./orchestrator.js";
 
+export type PlannotatorOpenOutcome = "opened" | "timeout" | "not-handled";
+
 export function openPlannotator(
   pi: ExtensionAPI,
   action: string,
   payload: Record<string, unknown>,
-): Promise<{ opened: boolean; reviewId: string | null }> {
+): Promise<{ opened: boolean; reviewId: string | null; outcome: PlannotatorOpenOutcome }> {
   const requestId = crypto.randomUUID();
   return new Promise((resolve) => {
     let handled = false;
     const timer = setTimeout(() => {
-      if (!handled) resolve({ opened: false, reviewId: null });
+      if (!handled) resolve({ opened: false, reviewId: null, outcome: "timeout" });
     }, 30000);
     pi.events.emit("plannotator:request", {
       requestId,
@@ -20,14 +22,59 @@ export function openPlannotator(
         handled = true;
         clearTimeout(timer);
         const reviewId = response?.result?.reviewId ?? null;
-        resolve({ opened: response.status === "handled", reviewId });
+        const opened = response.status === "handled";
+        resolve({ opened, reviewId, outcome: opened ? "opened" : "not-handled" });
       },
     });
   });
 }
 
+export interface AnnotateReviewResult {
+  feedback: string;
+  exit?: boolean;
+  approved?: boolean;
+}
+
 const PLANNOTATOR_RESULT_TIMEOUT_MS = 30 * 60 * 1000;
 
+// The `annotate` action is a SYNCHRONOUS request/response: its handler awaits the
+// full browser review and only calls respond() with the PlannotatorAnnotationResult
+// once the reviewer approves / submits feedback / closes. That can take minutes, so
+// unlike openPlannotator this helper does NOT wrap respond in a short (30s) ack
+// timer — the result arrives via the (late) respond callback, not a
+// plannotator:review-result event, so waitForPlannotatorResult must NOT be used
+// here. A long review-length timeout still bounds the pathological case where
+// pi-plannotator is not installed/enabled (no listener ever calls respond), so the
+// /pp menu can't hang forever — it resolves as not-opened and the caller recovers.
+export function openAnnotateReview(
+  pi: ExtensionAPI,
+  payload: Record<string, unknown>,
+  timeoutMs: number = PLANNOTATOR_RESULT_TIMEOUT_MS,
+): Promise<{ opened: boolean; result: AnnotateReviewResult | null }> {
+  const requestId = crypto.randomUUID();
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        resolve({ opened: false, result: null });
+      }
+    }, timeoutMs);
+    pi.events.emit("plannotator:request", {
+      requestId,
+      action: "annotate",
+      payload,
+      respond: (response: any) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        const opened = response?.status === "handled";
+        resolve({ opened, result: opened ? (response?.result ?? null) : null });
+      },
+    });
+  });
+}
+
 export function cancelPendingPlannotatorWait(orchestrator: Orchestrator): void {
   if (orchestrator.plannotatorTimer) {
     clearTimeout(orchestrator.plannotatorTimer);