@ilya-lesikov/pi-pi 0.10.0 → 0.12.0

package/extensions/orchestrator/pp-menu.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from "fs";
+import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, relative, basename } from "path";
 import { isDeepStrictEqual } from "util";
 import { askUser, isCancel, type CancelReason } from "../../3p/pi-ask-user/index.js";
@@ -32,6 +32,7 @@ import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle, isReviewCyc
 import { Orchestrator } from "./orchestrator.js";
 import { cancelPendingPlannotatorWait, openPlannotator, openAnnotateReview, waitForPlannotatorResult } from "./plannotator.js";
 import { advanceBanner } from "./messages.js";
+import { openAssumptionsBanner, terminalAssumptionsSummary } from "./assumptions.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
@@ -246,6 +247,53 @@ function setStep(orchestrator: Orchestrator, step: string): void {
   saveTask(orchestrator.active.dir, orchestrator.active.state);
 }
 
+// Pause/finish abort the agent, so they cannot reconcile in-line; flag pending so
+// the next resume re-prompts. Set unconditionally (not gated on reconciledPhase):
+// work done AFTER a phase was reconciled would otherwise resume from a stale stamp.
+function flagReconcilePending(state: { phase: string; reconcilePending?: boolean }): void {
+  if (state.phase !== "quick") {
+    state.reconcilePending = true;
+  }
+}
+
+// Manual /pp → Review launches reviewer subagents while the main agent is idle, so
+// the pp_phase_complete reconcile gate never ran and cannot run (no live turn to
+// prompt). Reviewers read the on-disk state files at spawn, which may lag the
+// agent's latest work. Guard just those synchronous automated-review launches with
+// a confirm; the guided flow reaches Review right after pp_phase_complete
+// reconciled (reconciledPhase === phase, not pending), so it never prompts.
+async function confirmReviewDespiteStaleState(orchestrator: Orchestrator, ctx: any): Promise<boolean> {
+  const state = orchestrator.active?.state;
+  if (!state) return true;
+  const stale = state.reconcilePending || state.reconciledPhase !== state.phase;
+  if (!stale) return true;
+  const choice = await selectOption(ctx, "Reviewers will use the current on-disk state files, which may not include the agent's latest findings. Continue?", [
+    opt("Review anyway", "Spawn reviewers against the on-disk state files"),
+    opt("Cancel", "Return to the menu without reviewing"),
+  ]);
+  if (choice !== "Review anyway") return false;
+  // The manual bypass must not count as a fresh reconciliation: keep it pending so
+  // the next live-agent pp_phase_complete re-prompts.
+  state.reconcilePending = true;
+  saveTask(orchestrator.active!.dir, state);
+  return true;
+}
+
+// Leaving a Plannotator/review flow (stop, exhaust, or cancel) must return the
+// task's step to an interactive value. Otherwise a step left at "await_reviewers"
+// keeps transitionController.isRunning() false, which hides the Review/Continue
+// actions in /pp and starves the idle watchdog until it stalls (the reported
+// post-"Stop reviewing" deadlock). Also drop any pending Plannotator wait so a
+// stale reject/timeout can't fire after the user has moved on. The caller owns
+// the subsequent saveTask.
+export function restoreMenuStepAfterReview(orchestrator: Orchestrator, task: { state: { phase: string; step: string | null } }): void {
+  cancelPendingPlannotatorWait(orchestrator);
+  const step = task.state.step;
+  if (step === "await_reviewers" || step === "await_planners" || step === null) {
+    task.state.step = task.state.phase === "plan" ? "synthesize" : "llm_work";
+  }
+}
+
 // Publish the latest synthesized review findings to a target. The agent (not the
 // extension) performs the writes: file comments = insert `AI_COMMENT:` markers at
 // each finding's line; PR comments = run `gh` to post line-anchored comments from
@@ -277,11 +325,11 @@ export function publishPrCommentsBanner(taskDir: string): string {
     "For each registered repo, resolve the branch's PR with `gh pr view --json number,headRefName,headRefOid,url` (skip the repo if there is no PR or `gh auth status` fails). Derive owner/repo from the PR `url` (the base repo).\n\n" +
     "PRE-VALIDATE each anchor against the PR diff BEFORE building the review: fetch the diff (e.g. `gh pr diff <number>`) and keep, in a `comments` array, ONLY findings whose path+line are part of that diff. A single GitHub review is all-or-nothing — one invalid line comment rejects the WHOLE review — so an unvalidated anchor must NEVER go into `comments`.\n\n" +
     "Post ONE bundled review per repo via `gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews` with `commit_id=<headRefOid>`, `event=COMMENT` (neutral — never APPROVE or REQUEST_CHANGES), a summary `body`, and a `comments` array of `{path, line, side: RIGHT, body}` for the validated findings.\n\n" +
-    "NON-DIFF findings (anchors not in the diff) are NEVER dropped: list them in the review `body` under a `Findings not anchorable to the diff:` heading, one per line ending with the exact ` (generated by pi-pi)` footer, using `file:—` (never an invented line). Do NOT rely on GitHub rejecting them.\n\n" +
-    "The LAST line of every finding's comment body MUST be exactly:\n(generated by pi-pi)\n\n" +
+    "NON-DIFF findings (anchors not in the diff) are NEVER dropped: list them in the review `body` under a `Findings not anchorable to the diff:` heading, each finding as its own block that ends with a blank line then the exact `(generated by pi-pi)` footer on its own line, using `file:—` (never an invented line). Do NOT rely on GitHub rejecting them.\n\n" +
+    "The comment body of every finding MUST end with a blank line followed by exactly:\n(generated by pi-pi)\n(i.e. there is always an empty line immediately before that footer, separating it from the finding text).\n\n" +
     PRIVACY_INSTRUCTION + "\n\n" +
     "IDEMPOTENT (line comments): first list existing PR comments (`gh api repos/<owner>/<repo>/pulls/<number>/comments`, which also returns comments from earlier per-comment publishes) and do NOT re-post a finding whose path, line, `(generated by pi-pi)` footer, AND body text all match one already present. Two distinct findings on the same line are NOT duplicates. Skip only true duplicates.\n\n" +
-    "IDEMPOTENT (body findings): also list existing reviews (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`) and read their `body`. A GitHub review body cannot be deduped per-line, so before creating a new review, drop any non-diff finding whose `<file:—> — <text> (generated by pi-pi)` body line already appears in a prior pi-pi review body. If, after that, there are NO new line comments AND NO new body findings for a repo, do NOT create an empty duplicate review — report it as fully-published instead.\n\n" +
+    "IDEMPOTENT (body findings): also list existing reviews (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`) and read their `body`. A GitHub review body cannot be deduped per-line, so before creating a new review, drop any non-diff finding whose `<file:—> — <text>` block (matched by its file, text, and `(generated by pi-pi)` footer, ignoring blank-line spacing) already appears in a prior pi-pi review body. If, after that, there are NO new line comments AND NO new body findings for a repo, do NOT create an empty duplicate review — report it as fully-published instead.\n\n" +
     "When done, report per repo how many comments you posted, how many you skipped as duplicates, and how many were unanchorable (in the body), then end your turn.",
   );
 }
@@ -306,7 +354,7 @@ const AI_REVIEW_MARKER_LOOP =
   "repeat until no `AI_REVIEW:` markers remain. Then verify your work and report what you changed per marker. When complete, " +
   "call pp_phase_complete.";
 
-// Read-only phases (brainstorm/debug/review) and plan produce markdown state files rather than
+// Read-only phases (brainstorm/review) and plan produce markdown state files rather than
 // source changes, so their AI_REVIEW scan targets those artifacts. Missing targets are skipped,
 // not errors. Kept as literal-token guidance (no regexp/parser), mirroring the implement banner.
 function readOnlyReviewBanner(phase: string, taskDir: string): string {
@@ -355,6 +403,8 @@ async function abortCurrentWork(orchestrator: Orchestrator, ctx: any): Promise<v
 async function pauseTask(orchestrator: Orchestrator, ctx: any): Promise<string> {
   if (!orchestrator.active) return "No active task.";
 
+  flagReconcilePending(orchestrator.active.state);
+
   cancelPendingPlannotatorWait(orchestrator);
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
@@ -398,6 +448,8 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
     return MISSING_FINAL_PASS_ANCHORS;
   }
 
+  flagReconcilePending(orchestrator.active.state);
+
   cancelPendingPlannotatorWait(orchestrator);
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
@@ -406,6 +458,7 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
   const name = orchestrator.active.description;
   const type = orchestrator.active.type;
   const dir = orchestrator.active.dir;
+  const wasAutonomous = getEffectiveMode(orchestrator.active.state) === "autonomous";
 
   orchestrator.lastCtx = ctx;
 
@@ -432,10 +485,16 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
     summary: `Task "${name}" (${type}) is finished — DISCARD its entire conversation. Do NOT carry forward, reference, or act on any of this task's messages, phase, plan, or aborted turns; the next task starts from a clean slate.`,
   });
 
+  // Terminal assumptions summary (#B/e): mirror the automatic done transition so a
+  // /pp → Complete finish of an autonomous run also lists recorded assumptions.
+  if (wasAutonomous) {
+    ctx.ui.notify(terminalAssumptionsSummary(dir), "info");
+  }
+
   const urExists = existsSync(join(dir, "USER_REQUEST.md"));
   const resExists = existsSync(join(dir, "RESEARCH.md"));
 
-  if ((type === "brainstorm" || type === "debug") && urExists && resExists) {
+  if (type === "brainstorm" && urExists && resExists) {
     const taskRelPath = relative(join(orchestrator.cwd, ".pp", "state"), dir);
     ctx.ui.notify(
       `Task "${name}" completed. Artifacts saved.\nUse /pp → Implement → From and choose ${taskRelPath}`,
@@ -499,7 +558,7 @@ export async function pickPreset(
 // phase, which is wrong only for tasks completed early).
 function reopenPhaseForDoneTask(type: TaskType, state: TaskState): Phase {
   if (state.completedFrom) return state.completedFrom;
-  for (const phase of ["implement", "plan", "review", "debug", "brainstorm", "quick"] as Phase[]) {
+  for (const phase of ["implement", "plan", "review", "brainstorm", "quick"] as Phase[]) {
     if (nextPhase(type, phase) === "done") return phase;
   }
   return "implement" as Phase;
@@ -597,8 +656,7 @@ export async function resumeTask(
   getLogger().info({ s: "task", dir: task.dir, type: task.type, phase: task.state.phase }, "task resumed");
 
   const modelConfig = orchestrator.config.agents.orchestrators[
-    task.type === "debug" ? "debug"
-    : task.type === "brainstorm" ? "brainstorm"
+    task.type === "brainstorm" ? "brainstorm"
     : task.type === "review" ? "review"
     : "implement"
   ];
@@ -826,15 +884,14 @@ export async function resumeTask(
   return { ok: true };
 }
 
-function listCompletedFromTasks(cwd: string): TaskInfo[] {
+export function listCompletedFromTasks(cwd: string): TaskInfo[] {
   const paused = new Set<string>([
     ...listTasks(cwd, "brainstorm").map((t) => t.dir),
-    ...listTasks(cwd, "debug").map((t) => t.dir),
     ...listTasks(cwd, "review").map((t) => t.dir),
   ]);
   const results: TaskInfo[] = [];
 
-  for (const type of ["brainstorm", "debug", "review"] as TaskType[]) {
+  for (const type of ["brainstorm", "review"] as TaskType[]) {
     const typeDir = join(cwd, ".pp", "state", type);
     if (!existsSync(typeDir)) continue;
     for (const entry of readdirSync(typeDir, { withFileTypes: true })) {
@@ -852,6 +909,27 @@ function listCompletedFromTasks(cwd: string): TaskInfo[] {
     }
   }
 
+  // Legacy .pp/state/debug/ tasks predate the removal of the debug task type, so
+  // their state.json cannot pass loadTask (its phase is a now-unsupported value).
+  // Read state.json directly so done debug tasks with artifacts stay reachable.
+  const debugDir = join(cwd, ".pp", "state", "debug");
+  if (existsSync(debugDir)) {
+    for (const entry of readdirSync(debugDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const dir = join(debugDir, entry.name);
+      const sp = join(dir, "state.json");
+      if (!existsSync(sp)) continue;
+      try {
+        const state = JSON.parse(readFileSync(sp, "utf-8")) as TaskState;
+        if (state.phase !== "done") continue;
+        if (!existsSync(join(dir, "USER_REQUEST.md")) || !existsSync(join(dir, "RESEARCH.md"))) continue;
+        results.push({ dir, state, type: "implement" });
+      } catch {
+        continue;
+      }
+    }
+  }
+
   results.sort((a, b) => {
     const aTime = a.state.startedAt ? new Date(a.state.startedAt).getTime() : 0;
     const bTime = b.state.startedAt ? new Date(b.state.startedAt).getTime() : 0;
@@ -892,7 +970,6 @@ function collectRoleAssignments(config: Partial<PiPiConfig> | null): string[] {
 
   add("agents.orchestrators.implement", config.agents?.orchestrators?.implement?.model);
   add("agents.orchestrators.plan", config.agents?.orchestrators?.plan?.model);
-  add("agents.orchestrators.debug", config.agents?.orchestrators?.debug?.model);
   add("agents.orchestrators.brainstorm", config.agents?.orchestrators?.brainstorm?.model);
   add("agents.orchestrators.review", config.agents?.orchestrators?.review?.model);
 
@@ -1094,7 +1171,7 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
     }
 
     if (choice === "Update now") {
-      const result = await updateFlantInfra(orchestrator.pi);
+      const result = await updateFlantInfra(orchestrator.pi, { force: true });
       const message = describeUpdateResult(result);
       ctx.ui.notify(message.text, message.kind);
       continue;
@@ -1341,7 +1418,6 @@ const ORCHESTRATOR_ROLES: Array<{ role: MainModelRole; label: string; descriptio
   { role: "brainstorm", label: "Brainstormer", description: "agents.orchestrators.brainstorm" },
   { role: "implement", label: "Implementer", description: "agents.orchestrators.implement" },
   { role: "plan", label: "Planner", description: "agents.orchestrators.plan" },
-  { role: "debug", label: "Debugger", description: "agents.orchestrators.debug" },
   { role: "review", label: "Reviewer", description: "agents.orchestrators.review" },
   { role: "quick", label: "Quick", description: "agents.orchestrators.quick" },
 ];
@@ -2924,7 +3000,7 @@ async function showMaxConcurrentSubagentsSetting(orchestrator: Orchestrator, ctx
     if (!action || action === "Back") break;
     if (action === "Edit") {
       const value = await pickMaxConcurrentSubagents(ctx, current);
-      if (value === null) continue;
+      if (value === null || value === current) continue;
       applyScopeChoice(orchestrator, MAX_CONCURRENT_SUBAGENTS_PATH, value, await pickScope(ctx, orchestrator));
       continue;
     }
@@ -2940,7 +3016,7 @@ async function pickMaxConcurrentSubagents(ctx: any, current: number): Promise<nu
     );
     if (input === undefined || input === null) return null;
     const trimmed = String(input).trim();
-    if (trimmed === "") return null;
+    if (trimmed === "") return current;
     if (!/^\d+$/.test(trimmed)) {
       ctx.ui.notify(`Please enter a positive integer between 1 and ${MAX_CONCURRENT_SUBAGENTS_CEILING}.`, "warning");
       continue;
@@ -3045,10 +3121,10 @@ async function showSettingsMenu(orchestrator: Orchestrator, ctx: any): Promise<t
   }
 }
 
-// First phases (brainstorm/debug/review) are always interactive and can never run
+// First phases (brainstorm/review) are always interactive and can never run
 // autonomously — autonomous configs only ever cover plan/implement.
 export function autonomousPhasesForTask(type: TaskType): string[] {
-  if (type === "implement" || type === "debug" || type === "review") return ["plan", "implement"];
+  if (type === "implement" || type === "review") return ["plan", "implement"];
   return [];
 }
 
@@ -3081,25 +3157,20 @@ async function showTaskModePicker(ctx: any): Promise<TaskMode | "back"> {
 }
 
 export async function pickMaxReviewPasses(ctx: any, current: number): Promise<number | null> {
-  const currentLabel = current >= 999 ? "-" : String(current);
+  const currentLabel = current >= 999 ? "-" : current === 0 ? "0 (disabled)" : String(current);
   while (true) {
     const input = await ctx.ui.input(
-      `Max review passes (enter a positive integer, or "-" for unlimited) [${currentLabel}]`,
+      `Max review passes (0 to disable, a positive integer, or "-" for unlimited) [${currentLabel}]`,
     );
     if (input === undefined || input === null) return null;
     const trimmed = String(input).trim();
-    if (trimmed === "") return null;
+    if (trimmed === "") return current;
     if (trimmed === "-") return 999;
     if (!/^\d+$/.test(trimmed)) {
-      ctx.ui.notify('Please enter a positive integer, or "-" for unlimited.', "warning");
+      ctx.ui.notify('Please enter 0 (disable), a positive integer, or "-" for unlimited.', "warning");
       continue;
     }
-    const parsed = Number.parseInt(trimmed, 10);
-    if (parsed <= 0) {
-      ctx.ui.notify('Please enter a positive integer, or "-" for unlimited.', "warning");
-      continue;
-    }
-    return parsed;
+    return Number.parseInt(trimmed, 10);
   }
 }
 
@@ -3119,7 +3190,7 @@ async function showAutonomousPhaseSettings(
 
   while (true) {
     const reviewPreset = phaseConfig.reviewPreset ?? defaultAutonomousReviewPreset(type, phase);
-    const maxReview = phaseConfig.maxReviewPasses >= 999 ? "No limit" : String(phaseConfig.maxReviewPasses);
+    const maxReview = phaseConfig.maxReviewPasses >= 999 ? "No limit" : phaseConfig.maxReviewPasses === 0 ? "0 (disabled)" : String(phaseConfig.maxReviewPasses);
     const options: OptionInput[] = [
       opt(`Review preset: ${reviewPreset}`, "Pick which reviewer group runs in this phase"),
     ];
@@ -3259,7 +3330,7 @@ interface ResumeFilters {
 }
 
 const STATUS_CYCLE: StatusFilter[] = ["Active", "Active + Done", "Done only", "All"];
-const TYPE_CYCLE: Array<"All" | TaskType> = ["All", "implement", "debug", "brainstorm", "review", "quick"];
+const TYPE_CYCLE: Array<"All" | TaskType> = ["All", "implement", "brainstorm", "review", "quick"];
 const MODE_CYCLE: Array<"All" | TaskMode> = ["All", "guided", "autonomous"];
 
 function defaultResumeFilters(): ResumeFilters {
@@ -3380,7 +3451,7 @@ async function showFromMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
   while (true) {
     const tasks = listCompletedFromTasks(orchestrator.cwd);
     if (tasks.length === 0) {
-      ctx.ui.notify("No completed brainstorm/debug/review tasks with artifacts found.", "info");
+      ctx.ui.notify("No completed brainstorm/review tasks with artifacts found.", "info");
       return BACK;
     }
 
@@ -3414,7 +3485,7 @@ async function showImplementMenu(orchestrator: Orchestrator, ctx: any): Promise<
   while (true) {
     const choice = await selectOption(ctx, "Implement", [
       { title: "New", description: "Start a new implementation from scratch" },
-      { title: "From", description: "Continue from a completed brainstorm or debug task" },
+      { title: "From", description: "Continue from a completed brainstorm task" },
       { title: "Resume", description: "Resume a paused implementation" },
       { title: "Back", description: "Return to the previous menu" },
     ]);
@@ -3533,109 +3604,196 @@ async function openCodeReviewInPlannotator(
 // the cursor stays put and the user chooses Retry / Skip / Done. When the cursor
 // is exhausted or the user stops, clear the cursor and return null (fall back to
 // the menu).
-async function runPlannotatorCursor(orchestrator: Orchestrator, ctx: any): Promise<string | null> {
-  const task = orchestrator.active;
-  if (!task) return null;
-  const cursor = task.state.plannotatorCursor;
-  if (!cursor) return null;
+// Prompt for the diff scope of one repo and open Plannotator for it. Returns the
+// review outcome, or null when the user backed out of the scope prompt (caller
+// decides what that means in its flow).
+async function reviewOneRepoInPlannotator(
+  orchestrator: Orchestrator,
+  ctx: any,
+  repo: { path: string; isRoot: boolean },
+): Promise<{ status: "approved" | "needs_changes" | "error"; feedback?: string; error?: string } | null> {
+  const diffChoice = await selectOption(ctx, `Review: ${formatRepoLabel(repo)}`, [
+    opt("All branch changes", "Committed changes vs base branch"),
+    opt("Last commit", "Changes in the most recent commit"),
+    opt("Since commit", "Review all changes since a specific commit"),
+    opt("Uncommitted changes", "Working directory changes"),
+    opt("Back", "Return without reviewing this repo"),
+  ]);
+  if (!diffChoice || diffChoice === "Back") return null;
+
+  let diffType: string;
+  let defaultBranch: string | undefined;
+  if (diffChoice === "All branch changes") {
+    diffType = "branch";
+    defaultBranch = await detectDefaultBranch(orchestrator, getRegisteredRepos(orchestrator), repo.path);
+  } else if (diffChoice === "Last commit") {
+    diffType = "last-commit";
+  } else if (diffChoice === "Since commit") {
+    const pickedHash = await pickCommitForRepo(orchestrator, ctx, repo);
+    if (!pickedHash) return null;
+    diffType = "branch";
+    defaultBranch = pickedHash;
+  } else {
+    diffType = "uncommitted";
+  }
 
-  while (task.state.plannotatorCursor && task.state.plannotatorCursor.index < task.state.plannotatorCursor.repoPaths.length) {
-    const cur = task.state.plannotatorCursor;
-    const repoPath = cur.repoPaths[cur.index];
-    const repo = getRegisteredRepos(orchestrator).find((r) => r.path === repoPath) ?? { path: repoPath, isRoot: false };
-
-    const diffChoice = await selectOption(ctx, `Review: ${formatRepoLabel(repo)}`, [
-      opt("All branch changes", "Committed changes vs base branch"),
-      opt("Last commit", "Changes in the most recent commit"),
-      opt("Since commit", "Review all changes since a specific commit"),
-      opt("Uncommitted changes", "Working directory changes"),
-      opt("Skip this repo", "Move to the next repository"),
-      opt("Done (stop reviewing)", "Stop iterating repositories"),
-    ]);
+  return openCodeReviewInPlannotator(orchestrator, { cwd: repo.path, diffType, defaultBranch });
+}
+
+function resolveRepo(orchestrator: Orchestrator, repoPath: string): { path: string; isRoot: boolean } {
+  return getRegisteredRepos(orchestrator).find((r) => r.path === repoPath) ?? { path: repoPath, isRoot: false };
+}
+
+function plannotatorFixBanner(repo: { path: string; isRoot: boolean }, feedback: string | undefined, more: string): string {
+  const fb = feedback ? `\n\nFeedback:\n${feedback}` : "";
+  return advanceBanner(
+    `[PI-PI] Plannotator requested changes for ${formatRepoLabel(repo)}.${fb}\n\n` +
+    "Address the user's feedback. If the feedback contains questions, answer them. If it requests changes, " +
+    `make the changes. Then call pp_phase_complete when done.\n\n${more}`,
+  );
+}
 
-    if (!diffChoice || diffChoice === "Done (stop reviewing)") {
+// Single-repo review keeps the streamlined behavior: review the one repo, and on
+// needs_changes return the fix instruction immediately (no picker). Multi-repo
+// review is user-directed via the status picker below.
+async function runSingleRepoCursor(orchestrator: Orchestrator, ctx: any, repoPath: string): Promise<string | null> {
+  const task = orchestrator.active!;
+  const repo = resolveRepo(orchestrator, repoPath);
+  while (true) {
+    const result = await reviewOneRepoInPlannotator(orchestrator, ctx, repo);
+    if (!result) {
       task.state.plannotatorCursor = undefined;
+      restoreMenuStepAfterReview(orchestrator, task);
       saveTask(task.dir, task.state);
       return null;
     }
-    if (diffChoice === "Skip this repo") {
-      cur.index += 1;
-      saveTask(task.dir, task.state);
-      continue;
-    }
-
-    let diffType: string;
-    let defaultBranch: string | undefined;
-    if (diffChoice === "All branch changes") {
-      diffType = "branch";
-      defaultBranch = await detectDefaultBranch(orchestrator, getRegisteredRepos(orchestrator), repo.path);
-    } else if (diffChoice === "Last commit") {
-      diffType = "last-commit";
-    } else if (diffChoice === "Since commit") {
-      const pickedHash = await pickCommitForRepo(orchestrator, ctx, repo);
-      if (!pickedHash) continue;
-      diffType = "branch";
-      defaultBranch = pickedHash;
-    } else {
-      diffType = "uncommitted";
-    }
-
-    const result = await openCodeReviewInPlannotator(orchestrator, { cwd: repo.path, diffType, defaultBranch });
-
-    // On error the repo is UNREVIEWED: do not advance the cursor (that would
-    // silently drop it from the pass). Keep it as the current repo until the
-    // user retries, explicitly skips, or stops.
     if (result.status === "error") {
       ctx.ui.notify(`${formatRepoLabel(repo)}: ERROR${result.error ? ` — ${result.error}` : ""}`, "warning");
       const errorChoice = await selectOption(ctx, `Review failed: ${formatRepoLabel(repo)}`, [
         opt("Retry", "Try reviewing this repository again"),
-        opt("Skip this repo", "Leave this repository unreviewed and move on"),
-        opt("Done (stop reviewing)", "Stop iterating repositories"),
+        opt("Done (stop reviewing)", "Stop reviewing"),
       ]);
       if (!errorChoice || errorChoice === "Done (stop reviewing)") {
         task.state.plannotatorCursor = undefined;
+        restoreMenuStepAfterReview(orchestrator, task);
         saveTask(task.dir, task.state);
         return null;
       }
-      if (errorChoice === "Skip this repo") {
-        cur.index += 1;
-        saveTask(task.dir, task.state);
-      }
-      // Retry: leave cur.index unchanged so the loop re-reviews this repo.
       continue;
     }
+    if (result.status === "needs_changes") {
+      task.state.plannotatorCursor = undefined;
+      setStep(orchestrator, "llm_work");
+      saveTask(task.dir, task.state);
+      return plannotatorFixBanner(repo, result.feedback, "This was the last repo to review.");
+    }
+    ctx.ui.notify(`${formatRepoLabel(repo)}: APPROVED`, "info");
+    task.state.plannotatorCursor = undefined;
+    restoreMenuStepAfterReview(orchestrator, task);
+    saveTask(task.dir, task.state);
+    return null;
+  }
+}
 
-    // Advance past this repo on a resolved outcome; on needs_changes the agent
-    // fixes it during the turn started by the returned instruction, then the next
-    // /pp resumes at the following repo.
-    cur.index += 1;
-    const exhausted = cur.index >= cur.repoPaths.length;
+// Multi-repo review is user-directed (#3): after each repo's review completes
+// (approved OR changes-requested) the loop does NOT auto-advance to the next repo
+// or auto-apply fixes. Instead a status picker lets the user explicitly pick the
+// next repo to review, start applying a changes-requested repo's fixes, or stop.
+async function runMultiRepoCursor(orchestrator: Orchestrator, ctx: any): Promise<string | null> {
+  const task = orchestrator.active!;
+  while (task.state.plannotatorCursor) {
+    const cur = task.state.plannotatorCursor;
+    const status = cur.status ?? {};
+    const feedbackMap = cur.feedback ?? {};
+
+    const options: OptionInput[] = cur.repoPaths.map((repoPath) => {
+      const repo = resolveRepo(orchestrator, repoPath);
+      const st = status[repoPath];
+      const label = st === "approved" ? "approved"
+        : st === "changes-requested" ? "changes requested — select to apply fixes"
+        : st === "fixes-applied" ? "fixes applied — select to re-review"
+        : "unreviewed — select to review";
+      return opt(formatRepoLabel(repo), label);
+    });
+    options.push(opt("Done (stop reviewing)", "Stop reviewing the remaining repositories"));
 
-    if (result.status === "needs_changes") {
-      if (exhausted) task.state.plannotatorCursor = undefined;
+    const choice = await selectOption(ctx, "Plannotator review — pick a repository", options);
+    if (!choice || choice === "Done (stop reviewing)") {
+      task.state.plannotatorCursor = undefined;
+      restoreMenuStepAfterReview(orchestrator, task);
+      saveTask(task.dir, task.state);
+      return null;
+    }
+
+    const repoPath = cur.repoPaths.find((p) => formatRepoLabel(resolveRepo(orchestrator, p)) === choice);
+    if (!repoPath) continue;
+    const repo = resolveRepo(orchestrator, repoPath);
+
+    // A changes-requested repo the user selects: hand off the fix instruction now
+    // (the user explicitly starts applying fixes). Clear its pending feedback and
+    // move it to "fixes-applied" so the picker next offers a re-review (reopening
+    // Plannotator) rather than repeating the fix handoff. The repo stays in the
+    // cursor so the user returns to the picker after the agent's turn.
+    if (status[repoPath] === "changes-requested") {
+      const feedback = feedbackMap[repoPath];
+      delete feedbackMap[repoPath];
+      cur.feedback = feedbackMap;
+      status[repoPath] = "fixes-applied";
+      cur.status = status;
       setStep(orchestrator, "llm_work");
       saveTask(task.dir, task.state);
-      const feedback = result.feedback ? `\n\nFeedback:\n${result.feedback}` : "";
-      const more = exhausted
-        ? "This was the last repo to review."
-        : "After you finish, run /pp to continue Plannotator review of the remaining repositories.";
-      return advanceBanner(
-        `[PI-PI] Plannotator requested changes for ${formatRepoLabel(repo)}.${feedback}\n\n` +
-        "Address the user's feedback. If the feedback contains questions, answer them. If it requests changes, " +
-        `make the changes. Then call pp_phase_complete when done.\n\n${more}`,
+      return plannotatorFixBanner(
+        repo,
+        feedback,
+        "After you finish, run /pp to return to the Plannotator repository picker.",
       );
     }
 
-    ctx.ui.notify(`${formatRepoLabel(repo)}: APPROVED`, "info");
+    // Otherwise (unreviewed or re-review of an approved repo): open Plannotator.
+    const result = await reviewOneRepoInPlannotator(orchestrator, ctx, repo);
+    if (!result) continue;
+    if (result.status === "error") {
+      ctx.ui.notify(`${formatRepoLabel(repo)}: ERROR${result.error ? ` — ${result.error}` : ""}`, "warning");
+      continue;
+    }
+    cur.status = status;
+    if (result.status === "needs_changes") {
+      status[repoPath] = "changes-requested";
+      if (result.feedback) {
+        feedbackMap[repoPath] = result.feedback;
+        cur.feedback = feedbackMap;
+      }
+      ctx.ui.notify(`${formatRepoLabel(repo)}: CHANGES REQUESTED — select it again to apply fixes.`, "info");
+    } else {
+      status[repoPath] = "approved";
+      ctx.ui.notify(`${formatRepoLabel(repo)}: APPROVED`, "info");
+    }
     saveTask(task.dir, task.state);
   }
-
-  // Cursor exhausted with no outstanding changes: clear it and fall back to /pp.
-  task.state.plannotatorCursor = undefined;
+  restoreMenuStepAfterReview(orchestrator, task);
   saveTask(task.dir, task.state);
   return null;
 }
 
+async function runPlannotatorCursor(orchestrator: Orchestrator, ctx: any): Promise<string | null> {
+  const task = orchestrator.active;
+  if (!task) return null;
+  const cursor = task.state.plannotatorCursor;
+  if (!cursor) return null;
+
+  if (cursor.repoPaths.length <= 1) {
+    const only = cursor.repoPaths[cursor.index] ?? cursor.repoPaths[0];
+    if (!only) {
+      task.state.plannotatorCursor = undefined;
+      restoreMenuStepAfterReview(orchestrator, task);
+      saveTask(task.dir, task.state);
+      return null;
+    }
+    return runSingleRepoCursor(orchestrator, ctx, only);
+  }
+  return runMultiRepoCursor(orchestrator, ctx);
+}
+
 async function showReviewMenu(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK | "started"> {
   while (true) {
     const choice = await selectOption(ctx, "Review", [
@@ -3674,19 +3832,7 @@ async function showTaskTypeMenu(
     if (!choice || choice === "Back") return BACK;
 
     if (choice === "New") {
-      let mode: TaskMode | undefined;
-      let autonomousConfig: AutonomousConfig | undefined;
-      if (type === "debug") {
-        const modeSelection = await pickModeForTaskStart(orchestrator, ctx, type);
-        if (!modeSelection) continue;
-        mode = modeSelection.mode;
-        autonomousConfig = modeSelection.autonomousConfig;
-      }
-      await orchestrator.startTask(ctx, type, type, undefined, undefined, mode);
-      if (orchestrator.active) {
-        orchestrator.active.state.autonomousConfig = autonomousConfig;
-        saveTask(orchestrator.active.dir, orchestrator.active.state);
-      }
+      await orchestrator.startTask(ctx, type, type, undefined, undefined, undefined);
       return "started";
     }
 
@@ -3699,7 +3845,6 @@ async function showTaskMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
   while (true) {
     const choice = await selectOption(ctx, "Task", [
       { title: "Implement", description: "Want to make some changes? Research any topic or a codebase, brainstorm solutions and implement the chosen one" },
-      { title: "Debug", description: "Something is broken? Investigate it. If there is an issue — brainstorm solutions and fix it" },
       { title: "Brainstorm", description: "No idea where to start? Research any topic or a codebase. If there is a problem to solve — brainstorm solutions and solve it" },
       { title: "Review", description: "Want to ensure that some commits or a GitHub PR are good to go? Review it. Even fix it yourself, if you want" },
       { title: "Quick", description: "Quick freeform task — no phases, no reviews, just work" },
@@ -3708,12 +3853,6 @@ async function showTaskMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
     ]);
     if (!choice || choice === "Back") return BACK;
 
-    if (choice === "Debug") {
-      const result = await showTaskTypeMenu(orchestrator, ctx, "debug");
-      if (result === "started") return "started";
-      continue;
-    }
-
     if (choice === "Brainstorm") {
       const result = await showTaskTypeMenu(orchestrator, ctx, "brainstorm");
       if (result === "started") return "started";
@@ -3917,7 +4056,7 @@ export async function showActiveTaskMenu(
     const isReviewPhase = phase === "review";
     const hasPlannotator = phase === "plan" || phase === "implement" || isReviewPhase;
     // The artifact the automated reviewers scan, mirroring reviewPresetGroupForPhase:
-    // brainstorm/debug → brainstormReviewers (research artifacts), plan → planReviewers
+    // brainstorm → brainstormReviewers (research artifacts), plan → planReviewers
     // (synthesized plan), implement/review → codeReviewers (code changes). This is the primary
     // "Review" target named at the top level; the per-phase "Review on my own" description names
     // the manual editor pass's target separately (it can differ).
@@ -3969,6 +4108,11 @@ export async function showActiveTaskMenu(
     options.push(opt("Back to prompt", "Return to the prompt and keep working"));
 
     const headerLines = [`/pp\n\nTask: ${task.type}\nPhase: ${phase}`];
+    if (task.state.reconcilePending) {
+      headerLines.push("\n\n⚠ State files may be stale — reconcile pending; they'll be refreshed before the next review/planner run.");
+    }
+    const assumptionsBanner = openAssumptionsBanner(task.dir);
+    if (assumptionsBanner) headerLines.push(`\n\n${assumptionsBanner}`);
     if (summary !== "/pp") headerLines.push(`\n\n${summary}`);
     const menuTitle = headerLines.join("");
     const { choice, cancelReason } = await selectOptionCancelable(ctx, menuTitle, options);
@@ -4047,7 +4191,7 @@ export async function showActiveTaskMenu(
             continue;
           }
           const passes = await pickMaxReviewPasses(ctx, 3);
-          if (passes === null) continue;
+          if (passes === null || passes === 0) continue;
           finalizeReviewCycle(task);
           if (task.state.reviewPassByKind?.[phase]) task.state.reviewPassByKind[phase].auto = 0;
           task.state.reviewApprovedClean = false;
@@ -4134,7 +4278,7 @@ export async function showActiveTaskMenu(
         opt(autoLabel, `Run configured reviewers over ${reviewTarget}`),
         opt("Auto review until approved", `Loop reviewers over ${reviewTarget} until they unanimously approve, up to N passes`),
       ];
-      const hasArtifactPlannotator = phase === "brainstorm" || phase === "debug";
+      const hasArtifactPlannotator = phase === "brainstorm";
       if (hasPlannotator) {
         reviewOptions.push(opt("Review in Plannotator", phase === "plan" ? "Open plan review in browser" : "Open code diff review in browser"));
       } else if (hasArtifactPlannotator) {
@@ -4152,7 +4296,7 @@ export async function showActiveTaskMenu(
 
       if (reviewChoice === "Review in Plannotator") {
         if (hasArtifactPlannotator) {
-          // brainstorm/debug have no diff or plan file: review the whole artifact
+          // brainstorm has no diff or plan file: review the whole artifact
           // set in one annotate-folder pass over the task dir (walks USER_REQUEST.md +
           // RESEARCH.md + artifacts/*.md recursively). The result comes back on the
           // synchronous annotate respond callback, NOT via waitForPlannotatorResult.
@@ -4201,10 +4345,11 @@ export async function showActiveTaskMenu(
           ctx.ui.notify("No registered repositories have changes to review.", "info");
           continue;
         }
-        // Start (or restart) the interleaved per-repo cursor and run it. On
-        // needs_changes runPlannotatorCursor persists the cursor and returns a
-        // work instruction (exits the menu to start the agent turn); the next /pp
-        // resumes at the following repo.
+        // Start (or restart) the per-repo cursor and run it. A single eligible
+        // repo runs the streamlined flow; multiple repos open the user-directed
+        // status picker. On a changes-requested handoff runPlannotatorCursor
+        // persists the cursor and returns a work instruction (exits the menu to
+        // start the agent turn); the next /pp resumes the cursor.
         task.state.plannotatorCursor = { repoPaths: eligible, index: 0 };
         saveTask(task.dir, task.state);
         const cursorText = await runPlannotatorCursor(orchestrator, ctx);
@@ -4247,7 +4392,7 @@ export async function showActiveTaskMenu(
           continue;
         }
         const passes = await pickMaxReviewPasses(ctx, 3);
-        if (passes === null) continue;
+        if (passes === null || passes === 0) continue;
         finalizeReviewCycle(task);
         // Item 5: stop-in-phase loop. Reset the per-phase auto-pass counter so the
         // cap counts THIS run's passes, and clear any stale clean flag.
@@ -4265,6 +4410,7 @@ export async function showActiveTaskMenu(
 
       const reviewPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");
       if (!reviewPreset) continue;
+      if (!(await confirmReviewDespiteStaleState(orchestrator, ctx))) continue;
       finalizeReviewCycle(task);
       if (!hasEnabledReviewers(orchestrator, reviewPreset)) {
         const reviewGroup = reviewPresetGroupForPhase(phase);