@ilya-lesikov/pi-pi 0.8.0 → 0.10.0

package/extensions/orchestrator/pp-menu.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, readdirSync } from "fs";
 import { join, relative, basename } from "path";
 import { isDeepStrictEqual } from "util";
 import { askUser, isCancel, type CancelReason } from "../../3p/pi-ask-user/index.js";
@@ -14,20 +14,23 @@ import {
   readRawConfig,
   removeConfigValue,
   resolvePreset,
+  reviewPresetGroupForPhase,
   writeConfigValue,
+  MAX_CONCURRENT_SUBAGENTS_CEILING,
   type PiPiConfig,
   type PresetGroup,
+  type PoolKey,
+  type PoolEntry,
   type OrchestratorRole,
   type VariantConfig,
 } from "./config.js";
 import {
-  loadBrainstormReviewOutputs,
-  loadCodeReviewOutputs,
-  loadPlanReviewOutputs,
+  loadPhaseReviewOutputs,
+  hasFinalPassAnchors,
 } from "./context.js";
-import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle } from "./event-handlers.js";
+import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle, isReviewCycleLive, registerFeatureToolsAndAgents } from "./event-handlers.js";
 import { Orchestrator } from "./orchestrator.js";
-import { cancelPendingPlannotatorWait, openPlannotator, waitForPlannotatorResult } from "./plannotator.js";
+import { cancelPendingPlannotatorWait, openPlannotator, openAnnotateReview, waitForPlannotatorResult } from "./plannotator.js";
 import { advanceBanner } from "./messages.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
@@ -46,13 +49,17 @@ import {
   taskAge,
   taskName,
   taskNameFromState,
+  taskFullName,
   taskShortId,
   type AutonomousConfig,
   type TaskMode,
   type TaskInfo,
   type TaskType,
+  type TaskState,
+  type Phase,
 } from "./state.js";
 import {
+  SUB_MODEL_PREFIX,
   clearFlantGeneratedConfig,
   getFlantGeneratedConfig,
   loadFlantSettings,
@@ -85,6 +92,7 @@ type TimeoutKey =
   | "performance.commands.afterEdit"
   | "performance.commands.afterImplement"
   | "performance.internals.subagentStale"
+  | "performance.internals.mainTurnStale"
   | "performance.internals.taskLockStale"
   | "performance.internals.taskLockRefresh";
 
@@ -105,16 +113,22 @@ async function selectOptionCancelable(
   question: string,
   options: OptionInput[],
 ): Promise<{ choice?: string; cancelReason?: CancelReason }> {
-  const result = await askUser(ctx, {
-    question,
-    options,
-    allowFreeform: false,
-    allowComment: false,
-    allowMultiple: false,
-  });
-  if (result && isCancel(result)) return { cancelReason: result.reason };
-  if (!result || result.kind !== "selection") return {};
-  return { choice: result.selections[0] };
+  const orchestrator = Orchestrator.current;
+  if (orchestrator) orchestrator.interactivePromptOpen = true;
+  try {
+    const result = await askUser(ctx, {
+      question,
+      options,
+      allowFreeform: false,
+      allowComment: false,
+      allowMultiple: false,
+    });
+    if (result && isCancel(result)) return { cancelReason: result.reason };
+    if (!result || result.kind !== "selection") return {};
+    return { choice: result.selections[0] };
+  } finally {
+    if (orchestrator) orchestrator.interactivePromptOpen = false;
+  }
 }
 
 function opt(title: string, description: string): OptionInput {
@@ -151,51 +165,7 @@ function formatRepoList(repos: RepoInfo[]): string {
     .join("\n");
 }
 
-function appendSection(content: string, heading: string, body: string): string {
-  const normalized = content.trimEnd();
-  if (normalized.includes(`${heading}\n`)) return normalized + "\n";
-  return `${normalized}\n\n${heading}\n${body}\n`;
-}
-
-function appendToSection(content: string, heading: string, body: string): string {
-  const normalized = content.trimEnd();
-  if (normalized.includes(body)) return normalized + "\n";
-
-  const lines = normalized.split("\n");
-  const sectionIndex = lines.findIndex((line) => line.trim() === heading);
-  if (sectionIndex === -1) {
-    return appendSection(normalized, heading, body);
-  }
-
-  let insertIndex = lines.length;
-  for (let i = sectionIndex + 1; i < lines.length; i += 1) {
-    if (lines[i]?.startsWith("## ")) {
-      insertIndex = i;
-      break;
-    }
-  }
-
-  const insertLines = body.split("\n");
-  if (insertIndex > sectionIndex + 1 && lines[insertIndex - 1]?.trim() !== "") {
-    insertLines.unshift("");
-  }
-  lines.splice(insertIndex, 0, ...insertLines);
-  return lines.join("\n") + "\n";
-}
-
-function appendRepoContext(content: string, repos: RepoInfo[]): string {
-  if (repos.length === 0) return content;
-  const lines = repos.map((repo) => `- ${formatRepoLabel(repo)}${repo.baseBranch ? ` (base: ${repo.baseBranch})` : ""}`);
-  return appendToSection(content, "## Constraints", `Registered repositories:\n${lines.join("\n")}`);
-}
 
-function appendResearchOpenQuestions(content: string, text: string): string {
-  const normalized = content.trimEnd();
-  if (normalized.includes("## Open Questions\n")) {
-    return `${normalized}\n${text}\n`;
-  }
-  return `${normalized}\n\n## Open Questions\n${text}\n`;
-}
 
 async function pickCommitForRepo(orchestrator: Orchestrator, ctx: any, repo: RepoInfo): Promise<string | null> {
   let commits: Array<{ hash: string; message: string; age: string }> = [];
@@ -276,6 +246,84 @@ function setStep(orchestrator: Orchestrator, step: string): void {
   saveTask(orchestrator.active.dir, orchestrator.active.state);
 }
 
+// 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
+// the user's own account. Both are idempotent — the agent checks for markers/
+// comments it already published and skips duplicates, so re-publishing is safe.
+const PRIVACY_INSTRUCTION =
+  "PRIVACY: comment bodies MUST be self-contained observations about the code itself. Do NOT reference " +
+  "private or internal details, \"the ticket\", issue trackers, or internal design docs. Say what is wrong " +
+  "in the code, not that it \"violates the design goal\" of some private document.";
+
+export function publishFileCommentsBanner(taskDir: string): string {
+  const reviewsDir = join(taskDir, "code-reviews");
+  return advanceBanner(
+    "[PI-PI] Publish the synthesized review findings as FILE COMMENTS now.\n\n" +
+    `Use the \`ANCHORS:\` block in the latest \`${reviewsDir}/*_final_pass-*.md\` as the file:line source — do NOT invent locations.\n\n` +
+    "For each accepted finding, insert an `AI_COMMENT:` marker (inside each file's native comment syntax, e.g. `// AI_COMMENT: ...`, `# AI_COMMENT: ...`, `<!-- AI_COMMENT: ... -->`) on or immediately above the cited line, briefly stating the finding. " +
+    "This is the ONLY source edit permitted — no fixes, no other changes.\n\n" +
+    PRIVACY_INSTRUCTION + "\n\n" +
+    "IDEMPOTENT: before inserting, check whether an equivalent `AI_COMMENT:` marker for that finding is already present at that location (e.g. from an earlier publish). If so, skip it — do NOT add a duplicate.\n\n" +
+    "When done, report how many markers you inserted and how many you skipped as already-present, then end your turn.",
+  );
+}
+
+export function publishPrCommentsBanner(taskDir: string): string {
+  const reviewsDir = join(taskDir, "code-reviews");
+  return advanceBanner(
+    "[PI-PI] Publish the synthesized review findings as GITHUB PR COMMENTS now, from the user's own `gh`-authenticated account.\n\n" +
+    `Use the \`ANCHORS:\` block in the latest \`${reviewsDir}/*_final_pass-*.md\` as the file:line source — do NOT invent locations.\n\n` +
+    "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" +
+    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" +
+    "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.",
+  );
+}
+
+// Guard for the Publish menu: both banners consume the `ANCHORS:` block from the
+// latest `code-reviews/*_final_pass-*.md`. If no such file exists, or the newest one
+// carries no `ANCHORS:` block, publishing would spawn an agent that immediately fails.
+// Returns a user-facing message to show instead, or undefined when publishing can proceed.
+export const MISSING_FINAL_PASS_ANCHORS =
+  "No ANCHORS-bearing final review file exists yet. Run or finish a review pass first " +
+  "(/pp → Review) so the findings are synthesized into `code-reviews/*_final_pass-*.md`.";
+
+export function publishGuard(taskDir: string): string | undefined {
+  return hasFinalPassAnchors(taskDir) ? undefined : MISSING_FINAL_PASS_ANCHORS;
+}
+
+const AI_REVIEW_MARKER_SYNTAX =
+  "(inside each file's native comment syntax, e.g. `// AI_REVIEW: ...`, `# AI_REVIEW: ...`, `<!-- AI_REVIEW: ... -->`)";
+
+const AI_REVIEW_MARKER_LOOP =
+  "For each marker: address the request, then remove that marker in the SAME edit. After a pass, re-scan the target files and " +
+  "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
+// 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 {
+  const targets =
+    phase === "plan"
+      ? "the synthesized plan(s) at `" + taskDir + "/plans/*_synthesized.md` ONLY (ignore raw planner outputs, " +
+        "`review_*` files, and the `plan-reviews/`, `brainstorm-reviews/`, `code-reviews/` directories)"
+      : "`" + taskDir + "/USER_REQUEST.md`, `" + taskDir + "/RESEARCH.md`, and `" + taskDir + "/artifacts/*.md`";
+  return advanceBanner(
+    `[PI-PI] The user reviewed this phase's state files in their editor and left inline \`AI_REVIEW:\` markers ` +
+    `${AI_REVIEW_MARKER_SYNTAX}.\n\n` +
+    `Search WITHIN ${targets} for \`AI_REVIEW:\`. Only scan those files — skip any target that does not exist ` +
+    `(a missing \`artifacts/*.md\` or a not-yet-produced state file is fine, not an error).\n\n` +
+    AI_REVIEW_MARKER_LOOP,
+  );
+}
+
 function showStatus(orchestrator: Orchestrator, ctx: any): void {
   if (!orchestrator.active) {
     ctx.ui.notify("No active task.", "info");
@@ -316,6 +364,9 @@ async function pauseTask(orchestrator: Orchestrator, ctx: any): Promise<string>
   const type = orchestrator.active.type;
 
   orchestrator.active.state.reviewCycle = null;
+  // Drop any in-progress per-repo Plannotator cursor so a resumed task does not
+  // auto-reopen Plannotator; the user re-enters Review explicitly.
+  orchestrator.active.state.plannotatorCursor = undefined;
   saveTask(orchestrator.active.dir, orchestrator.active.state);
   unregisterAgentDefinitions(orchestrator.pi);
   await orchestrator.cleanupActive();
@@ -340,6 +391,13 @@ async function pauseTask(orchestrator: Orchestrator, ctx: any): Promise<string>
 async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string> {
   if (!orchestrator.active) return "No active task.";
 
+  // The review phase must produce the ANCHORS-bearing final_pass file Publish
+  // consumes; block the direct Complete path too (it bypasses validateExitCriteria).
+  if (orchestrator.active.state.phase === "review" && !hasFinalPassAnchors(orchestrator.active.dir)) {
+    ctx.ui.notify(MISSING_FINAL_PASS_ANCHORS, "warning");
+    return MISSING_FINAL_PASS_ANCHORS;
+  }
+
   cancelPendingPlannotatorWait(orchestrator);
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
@@ -351,7 +409,11 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
 
   orchestrator.lastCtx = ctx;
 
+  // Record the phase we finished FROM so a later Resume can reopen the task at
+  // its real last working phase (done carries no phase history of its own).
+  orchestrator.active.state.completedFrom = orchestrator.active.state.phase;
   orchestrator.active.state.phase = "done";
+  orchestrator.active.state.step = null;
   orchestrator.active.state.reviewCycle = null;
   saveTask(orchestrator.active.dir, orchestrator.active.state);
   unregisterAgentDefinitions(orchestrator.pi);
@@ -366,7 +428,8 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
   // is over, nothing awaits this compaction).
   void orchestrator.transitionController.requestTransition({
     kind: "done",
-    summary: `Task "${name}" (${type}) completed.`,
+    discard: true,
+    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.`,
   });
 
   const urExists = existsSync(join(dir, "USER_REQUEST.md"));
@@ -385,16 +448,8 @@ async function finishTask(orchestrator: Orchestrator, ctx: any): Promise<string>
   return `Task "${name}" completed.`;
 }
 
-function loadPhaseReviewOutputs(taskDir: string, phase: string, pass: number): { name: string; content: string }[] {
-  if (phase === "brainstorm") return loadBrainstormReviewOutputs(taskDir, pass);
-  if (phase === "plan") return loadPlanReviewOutputs(taskDir, pass);
-  return loadCodeReviewOutputs(taskDir, pass);
-}
-
 function getDefaultReviewPresetName(config: PiPiConfig, phase: string): string {
-  if (phase === "brainstorm") return config.agents.subagents.presetGroups.brainstormReviewers.default;
-  if (phase === "plan") return config.agents.subagents.presetGroups.planReviewers.default;
-  return config.agents.subagents.presetGroups.codeReviewers.default;
+  return config.agents.subagents.presetGroups[reviewPresetGroupForPhase(phase)].default;
 }
 
 function isPresetEnabled(preset: { enabled?: boolean } | undefined): boolean {
@@ -402,9 +457,7 @@ function isPresetEnabled(preset: { enabled?: boolean } | undefined): boolean {
 }
 
 function getReviewPresetGroup(phase: string): PresetGroup {
-  if (phase === "brainstorm") return "brainstormReviewers";
-  if (phase === "plan") return "planReviewers";
-  return "codeReviewers";
+  return reviewPresetGroupForPhase(phase);
 }
 
 export async function pickPreset(
@@ -440,6 +493,18 @@ export async function pickPreset(
   return byTitle.get(choice) ?? null;
 }
 
+// The phase to restore when reopening a done task (#2). Prefer the recorded
+// completedFrom; for legacy done tasks that lack it, fall back to the phase whose
+// transition target is "done" (approximate — assumes the task ran to its terminal
+// 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[]) {
+    if (nextPhase(type, phase) === "done") return phase;
+  }
+  return "implement" as Phase;
+}
+
 export async function resumeTask(
   orchestrator: Orchestrator,
   ctx: any,
@@ -470,6 +535,19 @@ export async function resumeTask(
   orchestrator.resetTaskScopedState();
   orchestrator.activeTaskToken++;
 
+  // Reopen a done task (#2): now that the lock is held, reload under the lock and
+  // restore the phase the task was completed FROM so it re-enters at a sensible
+  // working phase (done leaves step=null). Lock-first, then mutate, then save.
+  if (task.state.phase === "done") {
+    task.state = loadTask(task.dir);
+    if (task.state.phase === "done") {
+      task.state.phase = reopenPhaseForDoneTask(task.type, task.state);
+      task.state.step = "llm_work";
+      task.state.completedFrom = undefined;
+      saveTask(task.dir, task.state);
+    }
+  }
+
   const normalizedRoot = normalizeRepoPath(orchestrator.cwd);
   if (!task.state.repos || task.state.repos.length === 0) {
     task.state.repos = [{ path: normalizedRoot, isRoot: true }];
@@ -612,11 +690,7 @@ export async function resumeTask(
         "warning",
       );
     }
-    const reviewers = phase === "brainstorm"
-      ? resolvePreset(orchestrator.config, "brainstormReviewers", presetName)
-      : phase === "plan"
-      ? resolvePreset(orchestrator.config, "planReviewers", presetName)
-      : resolvePreset(orchestrator.config, "codeReviewers", presetName);
+    const reviewers = resolvePreset(orchestrator.config, group, presetName);
     const reviewerCount = Object.values(reviewers).filter((v) => isEnabled(v)).length;
 
     if (cycle.kind === "auto" && (cycle.step === "spawn_reviewers" || cycle.step === "await_reviewers")) {
@@ -665,7 +739,7 @@ export async function resumeTask(
           orchestrator.active.state.activeReviewPreset = presetName;
           saveTask(orchestrator.active.dir, orchestrator.active.state);
           orchestrator.pendingSubagentSpawns = missingVariants.length;
-          const spawnFn = phase === "brainstorm"
+          const spawnFn = reviewPresetGroupForPhase(phase) === "brainstormReviewers"
             ? () => spawnBrainstormReviewers(
               pi,
               orchestrator.cwd,
@@ -677,7 +751,7 @@ export async function resumeTask(
               missingReviewerConfig,
               orchestrator.active?.state.repos ?? [],
             )
-            : phase === "plan"
+            : reviewPresetGroupForPhase(phase) === "planReviewers"
             ? () => spawnPlanReviewers(
               pi,
               orchestrator.cwd,
@@ -788,18 +862,25 @@ function listCompletedFromTasks(cwd: string): TaskInfo[] {
 }
 
 async function showSubagentsMenu(ctx: any): Promise<void> {
-  const api = (globalThis as any)[Symbol.for("pi-subagents:menu")] as { showMenu?: (menuCtx: any) => Promise<void> } | undefined;
-  if (!api?.showMenu) {
+  const api = (globalThis as any)[Symbol.for("pi-subagents:menu")] as {
+    showFleet?: (menuCtx: any) => Promise<void>;
+  } | undefined;
+  // showFleet opens the navigable running-agents list (the FleetView replacement).
+  if (!api?.showFleet) {
     ctx.ui.notify("Subagents menu API is not available.", "warning");
     return;
   }
-  await api.showMenu(ctx);
+  await api.showFleet(ctx);
 }
 
-function countFlantProviders(settings: FlantSettings): { anthropic: number; openai: number } {
+function countFlantProviders(settings: FlantSettings): { anthropic: number; openai: number; sub: number } {
   const models = settings.cachedFlantModels ?? [];
   const anthropic = models.filter((m) => m.startsWith("claude-")).length;
-  return { anthropic, openai: Math.max(0, models.length - anthropic) };
+  const subConfirmed = models.filter((m) => m.startsWith(SUB_MODEL_PREFIX)).length;
+  // Model lists cached before the gateway exposed sub/ ids have none — the
+  // sub provider then registers all claude models (see registerFlantProviders).
+  const sub = subConfirmed > 0 ? subConfirmed : anthropic;
+  return { anthropic, openai: Math.max(0, models.length - anthropic - subConfirmed), sub };
 }
 
 function collectRoleAssignments(config: Partial<PiPiConfig> | null): string[] {
@@ -839,9 +920,13 @@ function collectRoleAssignments(config: Partial<PiPiConfig> | null): string[] {
   add("agents.subagents.simple.explore", config.agents?.subagents?.simple?.explore?.model);
   add("agents.subagents.simple.librarian", config.agents?.subagents?.simple?.librarian?.model);
   add("agents.subagents.simple.task", config.agents?.subagents?.simple?.task?.model);
-  add("agents.subagents.simple.advisor", config.agents?.subagents?.simple?.advisor?.model);
-  add("agents.subagents.simple.deep-debugger", config.agents?.subagents?.simple?.["deep-debugger"]?.model);
-  add("agents.subagents.simple.reviewer", config.agents?.subagents?.simple?.reviewer?.model);
+  for (const poolKey of ["advisors", "reviewers", "deepDebuggers"] as const) {
+    const pool = config.agents?.subagents?.pools?.[poolKey];
+    if (!Array.isArray(pool)) continue;
+    pool.forEach((entry: any, i: number) => {
+      if (entry?.enabled !== false) add(`agents.subagents.pools.${poolKey}[${i}]`, entry?.model);
+    });
+  }
   return out;
 }
 
@@ -859,7 +944,7 @@ function flantStatusText(settings: FlantSettings): string {
     const hasGatewayKey = !!readGatewayApiKey();
     const subActive = hasOAuth && hasGatewayKey;
     lines.push(
-      `Personal subscription: on (${subActive ? `active — pp-flant-anthropic-sub, ${providers.anthropic} models` : "inactive"})`,
+      `Personal subscription: on (${subActive ? `active — pp-flant-anthropic-sub, ${providers.sub} models` : "inactive"})`,
     );
     lines.push(`Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`);
     if (!subActive) {
@@ -917,7 +1002,7 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
     }
     options.push({ title: "Back", description: "Return to the previous menu" });
 
-    const choice = await selectOption(ctx, "Flant AI Infrastructure", options);
+    const choice = await selectOption(ctx, "Flant", options);
     if (!choice || choice === "Back") return BACK;
 
     if (choice === enableLabel) {
@@ -926,7 +1011,7 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
         saveFlantSettings(next);
         unregisterFlantProviders(orchestrator.pi);
         clearFlantGeneratedConfig();
-        ctx.ui.notify("Flant AI Infrastructure disabled.", "info");
+        ctx.ui.notify("Flant disabled.", "info");
       } else {
         if (!process.env.FLANT_API_KEY) {
           ctx.ui.notify("Set FLANT_API_KEY environment variable first.", "warning");
@@ -1207,7 +1292,6 @@ export function showUsage(ctx: any): void {
 async function showInfoMenu(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
     const options: OptionInput[] = [];
-    options.push({ title: "Subagents", description: "Manage running agents" });
     options.push({ title: "Usage", description: "Show session token usage and cost breakdown" });
     options.push({ title: "Doctor", description: "Run diagnostic checks" });
     if (orchestrator.active) {
@@ -1218,10 +1302,6 @@ async function showInfoMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
 
     const choice = await selectOption(ctx, "Info", options);
     if (!choice || choice === "Back") return BACK;
-    if (choice === "Subagents") {
-      await showSubagentsMenu(ctx);
-      continue;
-    }
     if (choice === "Usage") {
       showUsage(ctx);
       continue;
@@ -1270,9 +1350,12 @@ const SUBAGENT_ROLES: Array<{ role: AgentRole; label: string; description: strin
   { role: "explore", label: "Explore", description: "agents.subagents.simple.explore" },
   { role: "librarian", label: "Librarian", description: "agents.subagents.simple.librarian" },
   { role: "task", label: "Task", description: "agents.subagents.simple.task" },
-  { role: "advisor", label: "Advisor", description: "agents.subagents.simple.advisor" },
-  { role: "deep-debugger", label: "Deep debugger", description: "agents.subagents.simple.deep-debugger" },
-  { role: "reviewer", label: "Reviewer", description: "agents.subagents.simple.reviewer" },
+];
+
+const POOL_ITEMS: Array<{ pool: PoolKey; label: string }> = [
+  { pool: "advisors", label: "Advisors" },
+  { pool: "reviewers", label: "Reviewers" },
+  { pool: "deepDebuggers", label: "Deep debuggers" },
 ];
 
 const PRESET_GROUP_ITEMS: Array<{ group: PresetGroup; label: string }> = [
@@ -1286,6 +1369,7 @@ const TIMEOUT_LABELS: Record<TimeoutKey, string> = {
   "performance.commands.afterEdit": "Command after file edit",
   "performance.commands.afterImplement": "Command after implementation",
   "performance.internals.subagentStale": "Subagent stale",
+  "performance.internals.mainTurnStale": "Main turn stale",
   "performance.internals.taskLockStale": "Lock stale",
   "performance.internals.taskLockRefresh": "Lock update",
 };
@@ -1692,6 +1776,12 @@ function refreshSubagentDefinitions(orchestrator: Orchestrator, keyPath: string[
   orchestrator.registerAgents();
 }
 
+function applyConcurrencyIfChanged(orchestrator: Orchestrator, keyPath: string[]): void {
+  if (keyPath[0] === "agents" && keyPath[1] === "maxConcurrentSubagents") {
+    orchestrator.applySubagentConcurrency();
+  }
+}
+
 function applyConfigChange(orchestrator: Orchestrator, scope: Scope, keyPath: string[], value: any): void {
   const result = tryApplyConfigChange(orchestrator, scope, keyPath, value);
   if (!result.ok) {
@@ -1710,6 +1800,7 @@ function applyConfigChange(orchestrator: Orchestrator, scope: Scope, keyPath: st
     updateRegistryFromAvailableModels(modelIds);
   }
   refreshSubagentDefinitions(orchestrator, keyPath);
+  applyConcurrencyIfChanged(orchestrator, keyPath);
 }
 
 function clearConfigOverride(orchestrator: Orchestrator, scope: Scope, keyPath: string[]): void {
@@ -1719,6 +1810,7 @@ function clearConfigOverride(orchestrator: Orchestrator, scope: Scope, keyPath:
     return;
   }
   refreshSubagentDefinitions(orchestrator, keyPath);
+  applyConcurrencyIfChanged(orchestrator, keyPath);
 }
 
 function thinkingLabel(value: string): string {
@@ -1827,8 +1919,8 @@ async function showOrchestratorEditor(
     const current = orchestrator.config.agents.orchestrators[role];
     const basePath = ["agents", "orchestrators", role];
     const choice = await selectOption(ctx, label, [
-      opt(`Model: ${current.model}`, "Select model"),
-      opt(`Thinking: ${thinkingLabel(current.thinking)}`, "Select thinking level"),
+      opt(`Model: ${current.model}`, "Choose the model for this agent"),
+      opt(`Thinking: ${thinkingLabel(current.thinking)}`, "Choose how much this agent thinks before acting"),
       ...buildResetOptions(orchestrator, basePath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -1874,8 +1966,8 @@ async function showSimpleSubagentEditor(
     const current = orchestrator.config.agents.subagents.simple[role];
     const basePath = ["agents", "subagents", "simple", role];
     const choice = await selectOption(ctx, label, [
-      opt(`Model: ${current.model}`, "Select model"),
-      opt(`Thinking: ${thinkingLabel(current.thinking)}`, "Select thinking level"),
+      opt(`Model: ${current.model}`, "Choose the model for this agent"),
+      opt(`Thinking: ${thinkingLabel(current.thinking)}`, "Choose how much this agent thinks before acting"),
       ...buildResetOptions(orchestrator, basePath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -1976,8 +2068,8 @@ async function showPresetVariantEditor(
     const variantPath = ["agents", "subagents", "presetGroups", group, "presets", presetName, "agents", variantName];
     const options: OptionInput[] = [
       opt(`Enabled: ${isEnabled(variant) ? "Yes" : "No"}`, "Toggle enabled state"),
-      opt(`Model: ${variant.model}`, "Select model"),
-      opt(`Thinking: ${thinkingLabel(variant.thinking)}`, "Select thinking level"),
+      opt(`Model: ${variant.model}`, "Choose the model for this agent"),
+      opt(`Thinking: ${thinkingLabel(variant.thinking)}`, "Choose how much this agent thinks before acting"),
     ];
     if (getOwnedScopes(orchestrator, variantPath).length > 0) {
       options.push(opt("Delete", "Delete this agent override"));
@@ -2029,7 +2121,7 @@ async function showPresetAgentsMenu(
       options.push(opt(title, `${variant.model} / ${thinkingLabel(variant.thinking)}`));
       byTitle.set(title, variantName);
     }
-    options.push(opt("New agent", "Add a new agent"));
+    options.push(opt("New agent", "Add an agent variant to this preset"));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, "Agents", options);
     if (!choice || choice === "Back") return BACK;
@@ -2198,7 +2290,7 @@ async function showPresetSettings(
       options.push(opt(optionTitle, enabledPresetSummary(preset.agents)));
       byTitle.set(optionTitle, presetName);
     }
-    options.push(opt("New preset", "Create preset"));
+    options.push(opt("New preset", "Create a preset in this group"));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, title, options);
     if (!choice || choice === "Back") return BACK;
@@ -2212,12 +2304,118 @@ async function showPresetSettings(
   }
 }
 
+// The dynamic on-demand pools (advisors/reviewers/deepDebuggers) are arrays, not
+// keyed records. writeConfigValue treats arrays as opaque leaves, so every edit
+// rewrites the WHOLE array into the chosen scope (deepMerge replaces arrays).
+function poolModelLabel(pool: PoolKey): string {
+  return pool === "deepDebuggers" ? "deep-debugger" : pool.replace(/s$/, "");
+}
+
+async function writePool(orchestrator: Orchestrator, ctx: any, pool: PoolKey, next: PoolEntry[]): Promise<boolean> {
+  const scope = await pickScope(ctx, orchestrator);
+  if (!scope) return false;
+  applyConfigChange(orchestrator, scope, ["agents", "subagents", "pools", pool], next);
+  return true;
+}
+
+async function showPoolEntryEditor(
+  orchestrator: Orchestrator,
+  ctx: any,
+  pool: PoolKey,
+  index: number,
+): Promise<typeof BACK> {
+  while (true) {
+    const entries = orchestrator.config.agents.subagents.pools[pool] ?? [];
+    const entry = entries[index];
+    if (!entry) return BACK;
+    const options: OptionInput[] = [
+      opt(`Enabled: ${entry.enabled === false ? "No" : "Yes"}`, "Toggle whether this model registers as a subagent"),
+      opt(`Model: ${entry.model}`, "Choose the model for this pool entry"),
+      opt(`Thinking: ${thinkingLabel(entry.thinking)}`, "Choose how much this agent thinks before acting"),
+      opt("Delete", "Remove this entry from the pool"),
+      opt("Back", "Return to the previous menu"),
+    ];
+    const choice = await selectOption(ctx, `${poolModelLabel(pool)} entry`, options);
+    if (!choice || choice === "Back") return BACK;
+    if (choice.startsWith("Model:")) {
+      const model = await pickModel(ctx, entry.model);
+      if (!model) continue;
+      const next = structuredClone(entries);
+      next[index] = { ...next[index], model };
+      await writePool(orchestrator, ctx, pool, next);
+      continue;
+    }
+    if (choice.startsWith("Thinking:")) {
+      const thinking = await pickThinking(ctx, true);
+      if (!thinking) continue;
+      const next = structuredClone(entries);
+      next[index] = { ...next[index], thinking };
+      await writePool(orchestrator, ctx, pool, next);
+      continue;
+    }
+    if (choice.startsWith("Enabled:")) {
+      const next = structuredClone(entries);
+      next[index] = { ...next[index], enabled: entry.enabled === false };
+      await writePool(orchestrator, ctx, pool, next);
+      continue;
+    }
+    const confirm = await selectOption(ctx, "Confirm delete?", [
+      opt("Yes, delete", "This cannot be undone"),
+      opt("Back", "Cancel"),
+    ]);
+    if (confirm !== "Yes, delete") continue;
+    const next = structuredClone(entries);
+    next.splice(index, 1);
+    if (await writePool(orchestrator, ctx, pool, next)) return BACK;
+  }
+}
+
+async function addPoolEntry(orchestrator: Orchestrator, ctx: any, pool: PoolKey): Promise<void> {
+  const model = await pickModel(ctx);
+  if (!model) return;
+  const thinking = await pickThinking(ctx, true);
+  if (!thinking) return;
+  const next = structuredClone(orchestrator.config.agents.subagents.pools[pool] ?? []);
+  next.push({ enabled: true, model, thinking });
+  await writePool(orchestrator, ctx, pool, next);
+}
+
+async function showPoolSettings(orchestrator: Orchestrator, ctx: any, pool: PoolKey, label: string): Promise<typeof BACK> {
+  while (true) {
+    const entries = orchestrator.config.agents.subagents.pools[pool] ?? [];
+    const options: OptionInput[] = [];
+    const byTitle = new Map<string, number>();
+    entries.forEach((entry, i) => {
+      const tag = entry.enabled === false ? " (disabled)" : "";
+      const title = `${entry.model}${tag}`;
+      options.push(opt(title, `thinking ${thinkingLabel(entry.thinking)}`));
+      byTitle.set(title, i);
+    });
+    options.push(opt("New entry", `Add a model to the ${label.toLowerCase()} pool`));
+    options.push(opt("Back", "Return to the previous menu"));
+    const choice = await selectOption(ctx, label, options);
+    if (!choice || choice === "Back") return BACK;
+    if (choice === "New entry") {
+      await addPoolEntry(orchestrator, ctx, pool);
+      continue;
+    }
+    const idx = byTitle.get(choice);
+    if (idx === undefined) continue;
+    await showPoolEntryEditor(orchestrator, ctx, pool, idx);
+  }
+}
+
 async function showSubagentSettings(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
     const options: OptionInput[] = SUBAGENT_ROLES.map(({ role, label, description }) => {
       const current = orchestrator.config.agents.subagents.simple[role];
       return opt(label, `${current.model} / ${thinkingLabel(current.thinking)} — ${description}`);
     });
+    for (const item of POOL_ITEMS) {
+      const pool = orchestrator.config.agents.subagents.pools[item.pool] ?? [];
+      const enabled = pool.filter((e) => e.enabled !== false).length;
+      options.push(opt(item.label, `${enabled}/${pool.length} enabled — on-demand model pool`));
+    }
     for (const item of PRESET_GROUP_ITEMS) {
       options.push(opt(item.label, `${Object.keys(orchestrator.config.agents.subagents.presetGroups[item.group].presets ?? {}).length} presets`));
     }
@@ -2229,6 +2427,11 @@ async function showSubagentSettings(orchestrator: Orchestrator, ctx: any): Promi
       await showSimpleSubagentEditor(orchestrator, ctx, simple.role, simple.label);
       continue;
     }
+    const pool = POOL_ITEMS.find((item) => item.label === choice);
+    if (pool) {
+      await showPoolSettings(orchestrator, ctx, pool.pool, pool.label);
+      continue;
+    }
     const group = PRESET_GROUP_ITEMS.find((item) => item.label === choice);
     if (!group) continue;
     await showPresetSettings(orchestrator, ctx, group.group, group.label);
@@ -2272,7 +2475,7 @@ async function showAfterEditCommands(orchestrator: Orchestrator, ctx: any): Prom
       options.push(opt(`${title}${enabledTag}`, `${globsCount} patterns — ${cmd.run}`));
       byTitle.set(`${title}${enabledTag}`, id);
     }
-    options.push(opt("New command", "Add command"));
+    options.push(opt("New command", "Add a command to run after a file edit"));
     options.push(...buildResetOptions(orchestrator, ["commands", "afterEdit"]));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, `After file edit: ${entries.length} commands`, options);
@@ -2401,7 +2604,7 @@ async function showAfterImplementCommands(orchestrator: Orchestrator, ctx: any):
       options.push(opt(title, cmd.run));
       byTitle.set(title, id);
     }
-    options.push(opt("New command", "Add command"));
+    options.push(opt("New command", "Add a command to run after implementation"));
     options.push(...buildResetOptions(orchestrator, ["commands", "afterImplement"]));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, `After implementation: ${entries.length} commands`, options);
@@ -2461,11 +2664,11 @@ async function showCommandsSettings(orchestrator: Orchestrator, ctx: any): Promi
     const choice = await selectOption(ctx, "Commands", [
       opt(
         `After file edit: ${afterEditCount} commands`,
-        `${afterEditCount} commands`,
+        "Commands run when a matching file is edited (e.g. format, lint)",
       ),
       opt(
         `After implementation: ${afterImplementCount} commands`,
-        `${afterImplementCount} commands`,
+        "Commands run once the implement phase completes (e.g. build, test)",
       ),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2496,6 +2699,11 @@ async function showTimeoutsSettings(orchestrator: Orchestrator, ctx: any): Promi
         path: ["performance", "internals", "subagentStale"],
         value: orchestrator.config.performance.internals.subagentStale,
       },
+      {
+        key: "performance.internals.mainTurnStale",
+        path: ["performance", "internals", "mainTurnStale"],
+        value: orchestrator.config.performance.internals.mainTurnStale,
+      },
       {
         key: "performance.internals.taskLockStale",
         path: ["performance", "internals", "taskLockStale"],
@@ -2510,7 +2718,7 @@ async function showTimeoutsSettings(orchestrator: Orchestrator, ctx: any): Promi
     const options: OptionInput[] = timeoutEntries.map((entry) => {
       const value = entry.value;
       const key = entry.key;
-      return opt(`${TIMEOUT_LABELS[key]}: ${formatDuration(value)}`, "Edit timeout");
+      return opt(`${TIMEOUT_LABELS[key]}: ${formatDuration(value)}`, "Change this time limit");
     });
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, "Timeouts", options);
@@ -2548,7 +2756,7 @@ async function showTimeoutsSettings(orchestrator: Orchestrator, ctx: any): Promi
 async function showPerformanceSettings(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
     const choice = await selectOption(ctx, "Performance", [
-      opt("Timeouts", "Timeout configuration"),
+      opt("Timeouts", "Adjust per-operation time limits"),
       opt("Back", "Return to the previous menu"),
     ]);
     if (!choice || choice === "Back") return BACK;
@@ -2649,10 +2857,10 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
   while (true) {
     const choice = await selectOption(ctx, "General", [
       opt(`Commit automatically: ${orchestrator.config.general.autoCommit ? "Yes" : "No"}`, "Enable or disable auto commits"),
+      opt(`Inject root AGENTS.md: ${orchestrator.config.general.injectAgentsMd ? "Yes" : "No"}`, "Inject the working repo's root AGENTS.md into the agent system prompt"),
       opt(`Ignore configs from other repos: ${orchestrator.config.general.loadExtraRepoConfigs ? "No" : "Yes"}`, "Load only root repo config"),
       opt(`Log level: ${logLevelLabel(orchestrator.config.general.logLevel)}`, "Logging verbosity"),
       opt(`Tracing: ${orchestrator.config.general.tracing ? "Yes" : "No"}`, "Capture full session traces to .pp/logs/traces/"),
-      opt("Flant AI Infrastructure", "Configure corporate AI model provider"),
       opt("Back", "Return to the previous menu"),
     ]);
     if (!choice || choice === "Back") return BACK;
@@ -2660,6 +2868,10 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
       await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"], "Commit changes automatically as work progresses", "Leave committing to you");
       continue;
     }
+    if (choice.startsWith("Inject root AGENTS.md:")) {
+      await showBooleanSetting(orchestrator, ctx, "Inject root AGENTS.md", ["general", "injectAgentsMd"], "Inject the working repo's root AGENTS.md into the agent system prompt", "Do not inject AGENTS.md");
+      continue;
+    }
     if (choice.startsWith("Ignore configs from other repos:")) {
       await showInvertedBooleanSetting(orchestrator, ctx, "Ignore configs from other repos", ["general", "loadExtraRepoConfigs"], "Use only the root repo config and ignore configs from other registered repos", "Also load configs from the other registered repos");
       continue;
@@ -2672,15 +2884,19 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
       await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"], "Capture full session traces to .pp/logs/traces/", "Do not record session traces");
       continue;
     }
-    await showFlantInfraMenu(orchestrator, ctx);
   }
 }
 
+const MAX_CONCURRENT_SUBAGENTS_LABEL = "Max concurrent subagents";
+const MAX_CONCURRENT_SUBAGENTS_PATH = ["agents", "maxConcurrentSubagents"];
+
 async function showAgentsSettings(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
+    const limit = orchestrator.config.agents.maxConcurrentSubagents;
     const choice = await selectOption(ctx, "Agents", [
       opt("Orchestrators", "Orchestrator and subagent configuration"),
       opt("Subagents", "Simple subagents and preset groups"),
+      opt(`${MAX_CONCURRENT_SUBAGENTS_LABEL}: ${limit}`, "Max background/orchestrated subagents run at once; extras queue"),
       opt("Back", "Return to the previous menu"),
     ]);
     if (!choice || choice === "Back") return BACK;
@@ -2688,10 +2904,56 @@ async function showAgentsSettings(orchestrator: Orchestrator, ctx: any): Promise
       await showOrchestratorsSettings(orchestrator, ctx);
       continue;
     }
+    if (choice.startsWith(`${MAX_CONCURRENT_SUBAGENTS_LABEL}:`)) {
+      await showMaxConcurrentSubagentsSetting(orchestrator, ctx);
+      continue;
+    }
     await showSubagentSettings(orchestrator, ctx);
   }
 }
 
+async function showMaxConcurrentSubagentsSetting(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
+  while (true) {
+    const current = getNestedValue(orchestrator.config, MAX_CONCURRENT_SUBAGENTS_PATH);
+    if (typeof current !== "number") break;
+    const action = await selectOption(ctx, `${MAX_CONCURRENT_SUBAGENTS_LABEL}: ${current}`, [
+      opt("Edit", "Set the maximum number of concurrent background subagents"),
+      ...buildResetOptions(orchestrator, MAX_CONCURRENT_SUBAGENTS_PATH),
+      opt("Back", "Return to the previous menu"),
+    ]);
+    if (!action || action === "Back") break;
+    if (action === "Edit") {
+      const value = await pickMaxConcurrentSubagents(ctx, current);
+      if (value === null) continue;
+      applyScopeChoice(orchestrator, MAX_CONCURRENT_SUBAGENTS_PATH, value, await pickScope(ctx, orchestrator));
+      continue;
+    }
+    await maybeHandleResetChoice(orchestrator, ctx, action, MAX_CONCURRENT_SUBAGENTS_PATH);
+  }
+  return BACK;
+}
+
+async function pickMaxConcurrentSubagents(ctx: any, current: number): Promise<number | null> {
+  while (true) {
+    const input = await ctx.ui.input(
+      `Max concurrent subagents (positive integer, 1-${MAX_CONCURRENT_SUBAGENTS_CEILING}) [${current}]`,
+    );
+    if (input === undefined || input === null) return null;
+    const trimmed = String(input).trim();
+    if (trimmed === "") return null;
+    if (!/^\d+$/.test(trimmed)) {
+      ctx.ui.notify(`Please enter a positive integer between 1 and ${MAX_CONCURRENT_SUBAGENTS_CEILING}.`, "warning");
+      continue;
+    }
+    const parsed = Number.parseInt(trimmed, 10);
+    if (parsed < 1 || parsed > MAX_CONCURRENT_SUBAGENTS_CEILING) {
+      ctx.ui.notify(`Please enter a positive integer between 1 and ${MAX_CONCURRENT_SUBAGENTS_CEILING}.`, "warning");
+      continue;
+    }
+    return parsed;
+  }
+}
+
 async function showReposSettings(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
     const repos = orchestrator.active?.state.repos ?? [];
@@ -2760,11 +3022,13 @@ async function showLspSettings(ctx: any): Promise<typeof BACK> {
 async function showSettingsMenu(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK> {
   while (true) {
     const options: OptionInput[] = [
-      opt("General", "Commit, log level, Flant AI, repos"),
+      opt("General", "Commit, log level, repos"),
       opt("Agents", "Orchestrator and subagent configuration"),
       opt("Commands", "After file edit and after implementation"),
-      opt("Performance", "Timeout configuration"),
+      opt("Performance", "Per-operation timeout limits"),
       opt("LSP", "Language server controls"),
+      opt("Flant", "Configure corporate AI model provider"),
+      opt("Info", "Usage and task status"),
       opt("Back", "Return to the previous menu"),
     ];
 
@@ -2776,12 +3040,14 @@ async function showSettingsMenu(orchestrator: Orchestrator, ctx: any): Promise<t
     else if (choice === "Commands") await showCommandsSettings(orchestrator, ctx);
     else if (choice === "Performance") await showPerformanceSettings(orchestrator, ctx);
     else if (choice === "LSP") await showLspSettings(ctx);
+    else if (choice === "Flant") await showFlantInfraMenu(orchestrator, ctx);
+    else if (choice === "Info") await showInfoMenu(orchestrator, ctx);
   }
 }
 
 // First phases (brainstorm/debug/review) are always interactive and can never run
 // autonomously — autonomous configs only ever cover plan/implement.
-function autonomousPhasesForTask(type: TaskType): string[] {
+export function autonomousPhasesForTask(type: TaskType): string[] {
   if (type === "implement" || type === "debug" || type === "review") return ["plan", "implement"];
   return [];
 }
@@ -2855,10 +3121,10 @@ async function showAutonomousPhaseSettings(
     const reviewPreset = phaseConfig.reviewPreset ?? defaultAutonomousReviewPreset(type, phase);
     const maxReview = phaseConfig.maxReviewPasses >= 999 ? "No limit" : String(phaseConfig.maxReviewPasses);
     const options: OptionInput[] = [
-      opt(`Review preset: ${reviewPreset}`, "Select review preset"),
+      opt(`Review preset: ${reviewPreset}`, "Pick which reviewer group runs in this phase"),
     ];
     if (phase === "plan") {
-      options.push(opt(`Planner preset: ${phaseConfig.plannerPreset ?? "regular"}`, "Select planner preset"));
+      options.push(opt(`Planner preset: ${phaseConfig.plannerPreset ?? "regular"}`, "Pick which planner group runs in this phase"));
     }
     options.push(opt(`Max review passes: ${maxReview}`, "Safety cap for autonomous review loops"));
     options.push(opt("Back", "Return to autonomous settings"));
@@ -2927,7 +3193,8 @@ async function pickModeForTaskStart(
 // uniqueness across the menu (see buildResumeOptions) so the option->task
 // mapping stays stable.
 function resumeOptionTitle(t: TaskInfo): string {
-  return `${taskNameFromState(t.dir, t.state)} — ${taskAge(t.state)}`;
+  const marker = t.state.phase === "done" ? "✓ done · " : "";
+  return `${marker}${taskNameFromState(t.dir, t.state)} — ${taskAge(t.state)}`;
 }
 
 // Description: rich per-entry detail sourced entirely from the already-loaded
@@ -2955,7 +3222,12 @@ function resumeOptionDescription(t: TaskInfo, cwd: string): string {
   }
 
   parts.push(`id ${taskShortId(t.dir)}`);
-  return parts.join(" · ");
+
+  // Metadata line first, then a blank line, then the full (untrimmed) intent, so
+  // the right pane leads with phase/mode/id and still shows the real task below.
+  const full = taskFullName(t.dir, s);
+  const meta = parts.join(" · ");
+  return full && full !== meta ? `${meta}\n\n${full}` : meta;
 }
 
 // Build menu options with a stable option->task index. Titles are made unique
@@ -2978,24 +3250,114 @@ function buildResumeOptions(tasks: TaskInfo[], cwd: string): { options: OptionIn
   return { options, byTitle };
 }
 
+type StatusFilter = "Active" | "Active + Done" | "Done only" | "All";
+interface ResumeFilters {
+  status: StatusFilter;
+  type: "All" | TaskType;
+  mode: "All" | TaskMode;
+  repo: string;
+}
+
+const STATUS_CYCLE: StatusFilter[] = ["Active", "Active + Done", "Done only", "All"];
+const TYPE_CYCLE: Array<"All" | TaskType> = ["All", "implement", "debug", "brainstorm", "review", "quick"];
+const MODE_CYCLE: Array<"All" | TaskMode> = ["All", "guided", "autonomous"];
+
+function defaultResumeFilters(): ResumeFilters {
+  return { status: "Active", type: "All", mode: "All", repo: "All" };
+}
+
+function filtersSummary(f: ResumeFilters): string {
+  return `Status: ${f.status} · Type: ${f.type} · Mode: ${f.mode} · Repo: ${f.repo}`;
+}
+
+function applyResumeFilters(tasks: TaskInfo[], f: ResumeFilters): TaskInfo[] {
+  return tasks.filter((t) => {
+    const isDone = t.state.phase === "done";
+    if (f.status === "Active" && isDone) return false;
+    if (f.status === "Done only" && !isDone) return false;
+    if (f.type !== "All" && t.type !== f.type) return false;
+    if (f.mode !== "All" && (t.state.effectiveMode ?? t.state.mode) !== f.mode) return false;
+    if (f.repo !== "All") {
+      const rootRepo = t.state.repos?.find((r) => r.isRoot) ?? t.state.repos?.[0];
+      if (!rootRepo || basename(rootRepo.path) !== f.repo) return false;
+    }
+    return true;
+  });
+}
+
+function cycle<T>(values: readonly T[], current: T): T {
+  const idx = values.indexOf(current);
+  return values[(idx + 1) % values.length]!;
+}
+
+async function showResumeFilters(
+  orchestrator: Orchestrator,
+  ctx: any,
+  filters: ResumeFilters,
+  lockToType: TaskType | undefined,
+): Promise<void> {
+  const repoNames = Array.from(
+    new Set(
+      listTasks(orchestrator.cwd, { type: lockToType, includeDone: true })
+        .map((t) => {
+          const rootRepo = t.state.repos?.find((r) => r.isRoot) ?? t.state.repos?.[0];
+          return rootRepo ? basename(rootRepo.path) : null;
+        })
+        .filter((n): n is string => !!n),
+    ),
+  );
+  const repoCycle = ["All", ...repoNames];
+  while (true) {
+    const options: OptionInput[] = [
+      opt(`Status: ${filters.status}`, "Cycle: Active / Active + Done / Done only / All"),
+    ];
+    if (!lockToType) options.push(opt(`Type: ${filters.type}`, "Cycle task type"));
+    options.push(opt(`Mode: ${filters.mode}`, "Cycle: All / guided / autonomous"));
+    options.push(opt(`Repo: ${filters.repo}`, "Cycle registered repo"));
+    options.push(opt("Clear filters", "Reset to defaults"));
+    options.push(opt("Back", "Return to the Resume list"));
+
+    const choice = await selectOption(ctx, "Filters", options);
+    if (!choice || choice === "Back") return;
+    if (choice.startsWith("Status:")) filters.status = cycle(STATUS_CYCLE, filters.status);
+    else if (choice.startsWith("Type:")) filters.type = cycle(TYPE_CYCLE, filters.type);
+    else if (choice.startsWith("Mode:")) filters.mode = cycle(MODE_CYCLE, filters.mode);
+    else if (choice.startsWith("Repo:")) filters.repo = cycle(repoCycle, filters.repo);
+    else if (choice === "Clear filters") {
+      const cleared = defaultResumeFilters();
+      filters.status = cleared.status;
+      filters.type = cleared.type;
+      filters.mode = cleared.mode;
+      filters.repo = cleared.repo;
+    }
+  }
+}
+
 async function showResumeMenu(
   orchestrator: Orchestrator,
   ctx: any,
   type: TaskType | undefined,
   emptyMessage: string,
 ): Promise<typeof BACK | "started"> {
+  const filters = defaultResumeFilters();
   while (true) {
-    const tasks = listTasks(orchestrator.cwd, type);
-    if (tasks.length === 0) {
+    const all = listTasks(orchestrator.cwd, { type, includeDone: true });
+    if (all.length === 0) {
       ctx.ui.notify(emptyMessage, "info");
       return BACK;
     }
+    const tasks = applyResumeFilters(all, filters);
 
     const { options, byTitle } = buildResumeOptions(tasks, orchestrator.cwd);
+    options.unshift({ title: "⚙  Filters", description: filtersSummary(filters) });
     options.push({ title: "Back", description: "Return to the previous menu" });
 
     const choice = await selectOption(ctx, "Resume", options);
     if (!choice || choice === "Back") return BACK;
+    if (choice === "⚙  Filters") {
+      await showResumeFilters(orchestrator, ctx, filters, type);
+      continue;
+    }
 
     const task = byTitle.get(choice);
     if (!task) continue;
@@ -3036,7 +3398,10 @@ async function showFromMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
 
     const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "implement");
     if (!modeSelection) continue;
-    await orchestrator.startTask(ctx, "implement", "implement", selected.dir, true, modeSelection.mode);
+    // Carry the source task's resolved name so the new implement task shows a
+    // real name instead of the literal "implement" (#7).
+    const inheritedName = taskFullName(selected.dir, selected.state);
+    await orchestrator.startTask(ctx, "implement", inheritedName, selected.dir, true, modeSelection.mode);
     if (orchestrator.active) {
       orchestrator.active.state.autonomousConfig = modeSelection.autonomousConfig;
       saveTask(orchestrator.active.dir, orchestrator.active.state);
@@ -3134,9 +3499,14 @@ async function openCodeReviewInPlannotator(
   if (payload.diffType) requestPayload.diffType = payload.diffType;
   if (payload.defaultBranch) requestPayload.defaultBranch = payload.defaultBranch;
 
-  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", requestPayload);
+  const { opened, reviewId, outcome } = await openPlannotator(orchestrator.pi, "code-review", requestPayload);
   if (!opened) {
-    return { status: "error", error: "Plannotator is not available." };
+    return {
+      status: "error",
+      error: outcome === "timeout"
+        ? "Plannotator did not respond within 30s (is the browser extension running?)."
+        : "Plannotator is not available (no handler responded — is the browser extension installed?).",
+    };
   }
 
   let result: { approved: boolean; feedback?: string; error?: string };
@@ -3154,175 +3524,139 @@ async function openCodeReviewInPlannotator(
   return { status: result.approved ? "approved" : "needs_changes", feedback };
 }
 
-async function startReviewTask(
-  orchestrator: Orchestrator,
-  ctx: any,
-  userRequestContent: string,
-  researchContent: string | null,
-  description: string,
-  mode?: TaskMode,
-  autonomousConfig?: AutonomousConfig,
-): Promise<"started" | typeof BACK> {
-  await orchestrator.startTask(ctx, "review", description, undefined, undefined, mode);
-  if (!orchestrator.active || orchestrator.active.type !== "review") return BACK;
-  orchestrator.active.state.autonomousConfig = autonomousConfig;
-  saveTask(orchestrator.active.dir, orchestrator.active.state);
-  const repos = getRegisteredRepos(orchestrator);
-  const userRequestWithRepos = appendRepoContext(userRequestContent, repos);
-  writeFileSync(join(orchestrator.active.dir, "USER_REQUEST.md"), userRequestWithRepos, "utf-8");
-  if (researchContent) {
-    writeFileSync(join(orchestrator.active.dir, "RESEARCH.md"), researchContent, "utf-8");
+// Per-repo interleaved Plannotator loop (#3a). Runs from the persisted cursor: for
+// each repo, ask the diff scope, open Plannotator and WAIT (dialogue closed). On
+// NEEDS_CHANGES, persist the cursor advanced past this repo and return a work
+// instruction (mirrors the plan path: answer questions + apply changes) so the
+// agent fixes THIS repo before the next opens; the next /pp resumes the loop. On
+// approved, advance and continue in-loop. On error the repo is left UNREVIEWED:
+// 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;
+
+  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"),
+    ]);
+
+    if (!diffChoice || diffChoice === "Done (stop reviewing)") {
+      task.state.plannotatorCursor = undefined;
+      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"),
+      ]);
+      if (!errorChoice || errorChoice === "Done (stop reviewing)") {
+        task.state.plannotatorCursor = undefined;
+        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;
+    }
+
+    // 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;
+
+    if (result.status === "needs_changes") {
+      if (exhausted) task.state.plannotatorCursor = undefined;
+      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}`,
+      );
+    }
+
+    ctx.ui.notify(`${formatRepoLabel(repo)}: APPROVED`, "info");
+    saveTask(task.dir, task.state);
   }
-  return "started";
+
+  // Cursor exhausted with no outstanding changes: clear it and fall back to /pp.
+  task.state.plannotatorCursor = undefined;
+  saveTask(task.dir, task.state);
+  return null;
 }
 
 async function showReviewMenu(orchestrator: Orchestrator, ctx: any): Promise<typeof BACK | "started"> {
   while (true) {
-    const options: OptionInput[] = [
-      { title: "Current branch", description: "Review changes on current branch vs base" },
-      { title: "Last commit", description: "Review changes in the most recent commit" },
-      { title: "Since commit", description: "Review all changes since a specific commit" },
-      { title: "Uncommitted changes", description: "Review working directory changes" },
-      { title: "Describe", description: "Describe what to review and let the agent figure it out" },
+    const choice = await selectOption(ctx, "Review", [
+      { title: "New", description: "Start a new review — type what to review (a branch, commit range, uncommitted changes, or a PR URL) as your first chat message" },
       { title: "Resume", description: "Resume a previously unfinished review" },
       { title: "Back", description: "Return to the previous menu" },
-    ];
-    const choice = await selectOption(ctx, "Review", options);
+    ]);
     if (!choice || choice === "Back") return BACK;
 
-    if (choice === "Resume") {
-      const result = await showResumeMenu(orchestrator, ctx, "review", "No paused review tasks found.");
-      if (result === "started") return result;
-      continue;
-    }
-
-    if (choice === "Current branch") {
-      const repos = getRegisteredRepos(orchestrator);
-      const repoRanges = await Promise.all(
-        repos.map(async (repo) => `- ${formatRepoLabel(repo)}: ${await detectDefaultBranch(orchestrator, repos, repo.path)}..HEAD`),
-      );
-      const prContexts = await detectCurrentPrContext(orchestrator, repos);
-
-      const urLines = [
-        "# User Request",
-        "Review current branch changes across registered repositories.",
-        "",
-        "Diff ranges:",
-        ...repoRanges,
-      ];
-      const prUrls = prContexts
-        .filter((pr) => pr.prUrl)
-        .map((pr) => `- ${pr.repoPath}: ${pr.prUrl}`);
-      if (prUrls.length > 0) {
-        urLines.push("", "Open PRs:", ...prUrls);
-      }
-      urLines.push("", "## Problem", "Review and identify issues in the code changes.", "", "## Constraints", "Focus on correctness, edge cases, style, missing tests, potential bugs.");
-      const urContent = urLines.join("\n") + "\n";
-
-      let resContent = [
-        "## Affected Code",
-        "(to be filled during review)",
-        "",
-        "## Architecture Context",
-        "(to be filled during review)",
-        "",
-        "## Constraints & Edge Cases",
-        "- MUST: Review all changed code across the registered repositories",
-        "- RISK: Issues can span repository boundaries",
-      ].join("\n") + "\n";
-      if (prContexts.length > 0) {
-        const prContextBlocks = prContexts
-          .map((pr) => {
-            const lines = [`${pr.repoPath}`];
-            if (pr.prUrl) lines.push(`URL: ${pr.prUrl}`);
-            if (pr.prContext) lines.push(pr.prContext);
-            return lines.join("\n");
-          })
-          .join("\n\n");
-        resContent = appendResearchOpenQuestions(resContent, `PR context:\n${prContextBlocks}`);
-      }
-
-      const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "review");
-      if (!modeSelection) continue;
-      const description = "review-current-branch";
-      return startReviewTask(orchestrator, ctx, urContent, resContent, description, modeSelection.mode, modeSelection.autonomousConfig);
-    }
-
-    if (choice === "Last commit") {
-      const repos = getRegisteredRepos(orchestrator);
-      const urContent = [
-        "# User Request",
-        "Review last commit changes across registered repositories",
-        "",
-        "## Problem",
-        "Review and identify issues in the most recent commit.",
-        "",
-        "## Constraints",
-        "Focus on correctness, edge cases, style, missing tests, potential bugs.",
-        "",
-      ].join("\n");
-      const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "review");
-      if (!modeSelection) continue;
-      return startReviewTask(orchestrator, ctx, urContent, null, "review-last-commit", modeSelection.mode, modeSelection.autonomousConfig);
-    }
-
-    if (choice === "Since commit") {
-      const repos = getRegisteredRepos(orchestrator);
-      const repoOptions: OptionInput[] = repos.map((repo) => ({
-        title: formatRepoLabel(repo),
-        description: "Choose repository for commit range",
-      }));
-      repoOptions.push({ title: "Back", description: "Return to the previous menu" });
-      const repoChoice = await selectOption(ctx, "Select repository", repoOptions);
-      if (!repoChoice || repoChoice === "Back") continue;
-      const selectedRepo = repos.find((repo) => formatRepoLabel(repo) === repoChoice);
-      if (!selectedRepo) continue;
-      const pickedHash = await pickCommitForRepo(orchestrator, ctx, selectedRepo);
-      if (!pickedHash) continue;
-
-      const urContent = [
-        "# User Request",
-        `Review changes in ${selectedRepo.path} since commit ${pickedHash}`,
-        "",
-        "## Problem",
-        `Review and identify issues in all changes in ${selectedRepo.path} since ${pickedHash}.`,
-        "",
-        "## Constraints",
-        "Focus on correctness, edge cases, style, missing tests, potential bugs.",
-        "",
-      ].join("\n");
-      const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "review");
-      if (!modeSelection) continue;
-      return startReviewTask(orchestrator, ctx, urContent, null, "review-since-commit", modeSelection.mode, modeSelection.autonomousConfig);
-    }
-
-    if (choice === "Uncommitted changes") {
-      const repos = getRegisteredRepos(orchestrator);
-      const urContent = [
-        "# User Request",
-        "Review uncommitted changes across registered repositories",
-        "",
-        "## Problem",
-        "Review and identify issues in uncommitted working directory changes.",
-        "",
-        "## Constraints",
-        "Focus on correctness, edge cases, style, missing tests, potential bugs.",
-        "",
-      ].join("\n");
+    if (choice === "New") {
       const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "review");
       if (!modeSelection) continue;
-      return startReviewTask(orchestrator, ctx, urContent, null, "review-uncommitted", modeSelection.mode, modeSelection.autonomousConfig);
+      await orchestrator.startTask(ctx, "review", "review", undefined, undefined, modeSelection.mode);
+      if (!orchestrator.active || orchestrator.active.type !== "review") return BACK;
+      orchestrator.active.state.autonomousConfig = modeSelection.autonomousConfig;
+      saveTask(orchestrator.active.dir, orchestrator.active.state);
+      return "started";
     }
 
-    const input = await ctx.ui.input("Describe what to review");
-    if (input === undefined || input === null) continue;
-    const trimmed = String(input).trim();
-    const description = trimmed || "review";
-
-    const urContent = `# User Request\n${description}\n\n## Problem\n${description}\n\n## Constraints\nFocus on correctness, edge cases, style, missing tests, potential bugs.\n`;
-    const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "review");
-    if (!modeSelection) continue;
-    return startReviewTask(orchestrator, ctx, urContent, null, description, modeSelection.mode, modeSelection.autonomousConfig);
+    const result = await showResumeMenu(orchestrator, ctx, "review", "No paused review tasks found.");
+    if (result === "started") return result;
   }
 }
 
@@ -3411,15 +3745,56 @@ async function showTaskMenu(orchestrator: Orchestrator, ctx: any): Promise<typeo
   }
 }
 
+// Minimal read-only path shown when loadConfig threw on session_start. It must NOT
+// register or trigger normal task execution against the invalid config — it only
+// helps the user locate and fix the broken config, then re-check it.
+async function showConfigErrorMenu(orchestrator: Orchestrator, ctx: any): Promise<string | undefined> {
+  const projectConfigPath = join(orchestrator.cwd, ".pp", "config.json");
+  while (true) {
+    const choice = await selectOption(
+      ctx,
+      `/pp — config error\n\n${orchestrator.configError}\n\nProject config: ${projectConfigPath}\nGlobal config: ${GLOBAL_CONFIG_PATH}`,
+      [
+        { title: "Re-check config", description: "Reload config after fixing it" },
+        { title: "Doctor", description: "Run diagnostic checks" },
+        { title: "Back", description: "Close this menu" },
+      ],
+    );
+    if (!choice || choice === "Back") return undefined;
+
+    if (choice === "Re-check config") {
+      try {
+        orchestrator.config = loadConfig(orchestrator.cwd);
+        orchestrator.configError = null;
+        // session_start skipped feature/tool/agent registration when config
+        // loading failed; register them now that the config is valid so the
+        // orchestration tools exist, not just the menu.
+        registerFeatureToolsAndAgents(orchestrator);
+        ctx.ui.notify("Config loaded successfully. Run /pp again to continue.", "info");
+        return undefined;
+      } catch (err: any) {
+        orchestrator.configError = err.message;
+        ctx.ui.notify(`Config error: ${err.message}`, "error");
+        continue;
+      }
+    }
+
+    if (choice === "Doctor") {
+      await runDoctor(orchestrator, ctx);
+      continue;
+    }
+  }
+}
+
 async function showNoActiveMenu(orchestrator: Orchestrator, ctx: any): Promise<string | undefined> {
   while (true) {
     const choice = await selectOption(ctx, "/pp", [
       { title: "Task", description: "Start a new task or resume a paused one" },
-      { title: "Info", description: "Subagents, usage, and task status" },
-      { title: "Settings", description: "Flant AI and other configuration" },
-      { title: "Back", description: "Close this menu" },
+      { title: "Subagents", description: "View and manage running subagents" },
+      { title: "Settings", description: "Models, agents, commands, and other configuration" },
+      { title: "Back to prompt", description: "Close this menu" },
     ]);
-    if (!choice || choice === "Back") return undefined;
+    if (!choice || choice === "Back to prompt") return undefined;
 
     if (choice === "Task") {
       const result = await showTaskMenu(orchestrator, ctx);
@@ -3427,8 +3802,8 @@ async function showNoActiveMenu(orchestrator: Orchestrator, ctx: any): Promise<s
       continue;
     }
 
-    if (choice === "Info") {
-      await showInfoMenu(orchestrator, ctx);
+    if (choice === "Subagents") {
+      await showSubagentsMenu(ctx);
       continue;
     }
 
@@ -3476,16 +3851,16 @@ async function showQuickTaskMenu(
     const { choice, cancelReason } = await selectOptionCancelable(ctx, menuTitle, [
       opt("Complete", "Mark task as done and clean up"),
       opt("Pause", "Suspend task to resume later"),
-      opt("Info", "Subagents, usage, and task status"),
-      opt("Settings", "Flant AI and other configuration"),
-      opt("Back", "Return to the prompt and keep working"),
+      opt("Subagents", "View and manage running subagents"),
+      opt("Settings", "Models, agents, commands, and other configuration"),
+      opt("Back to prompt", "Return to the prompt and keep working"),
     ]);
     // A deliberate ESC in tool mode must stop the turn cleanly (mirror the
     // guided/autonomous branches); in command mode ESC just closes the menu.
     if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
-    if (!choice || choice === "Back") return "";
-    if (choice === "Info") {
-      await showInfoMenu(orchestrator, ctx);
+    if (!choice || choice === "Back to prompt") return "";
+    if (choice === "Subagents") {
+      await showSubagentsMenu(ctx);
       continue;
     }
     if (choice === "Settings") {
@@ -3506,6 +3881,11 @@ export async function showActiveTaskMenu(
   ctx: any,
   summary: string,
   mode: MenuMode = "command",
+  // Display-only override for the autonomous terminal implement handoff (#1):
+  // render the guided Next/Review menu even though the task is autonomous, WITHOUT
+  // mutating task.state.mode. Never persisted; does not affect the footer indicator
+  // or getEffectivePhaseMode.
+  forceGuided = false,
 ): Promise<string> {
   const continueMessage = advanceBanner("[PI-PI] User wants to continue. Run /pp when ready to advance.");
 
@@ -3516,6 +3896,15 @@ export async function showActiveTaskMenu(
     if (task.type === "quick") {
       return showQuickTaskMenu(orchestrator, ctx, summary, mode);
     }
+    // Auto-resume an in-progress per-repo Plannotator review (#3a): if the agent
+    // just finished fixing one repo's feedback and ran /pp, continue the loop at
+    // the next repo instead of showing the top-level menu. On another
+    // needs_changes this returns a fresh work instruction; when exhausted it
+    // clears the cursor and falls through to the normal menu.
+    if (task.state.plannotatorCursor) {
+      const resumeText = await runPlannotatorCursor(orchestrator, ctx);
+      if (resumeText) return resumeText;
+    }
     const phase = task.state.phase;
     const step = task.state.step;
     const effectiveMode = getEffectivePhaseMode(task.state);
@@ -3527,24 +3916,35 @@ export async function showActiveTaskMenu(
     const { autoLabel } = getReviewLabels(orchestrator);
     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
+    // (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).
+    const reviewGroup = reviewPresetGroupForPhase(phase);
+    const reviewTarget = reviewGroup === "planReviewers"
+      ? "the synthesized plan"
+      : reviewGroup === "brainstormReviewers"
+      ? "this phase's research artifacts"
+      : "the code changes";
 
     const opt = (title: string, description: string): OptionInput => ({ title, description });
 
-    if (effectiveMode === "autonomous") {
+    if (effectiveMode === "autonomous" && !forceGuided) {
       const { choice: autoChoice, cancelReason } = await selectOptionCancelable(ctx, `/pp\n\nTask: ${task.type}\nPhase: ${phase}${summary !== "/pp" ? `\n\n${summary}` : ""}`, [
         opt("Complete task", "Mark task as done and clean up"),
         opt("Pause task", "Suspend task to resume later"),
-        opt("Info", "Subagents, usage, and task status"),
-        opt("Settings", "Flant AI and other configuration"),
-        opt("Back", "Return to the prompt and keep working"),
+        opt("Subagents", "View and manage running subagents"),
+        opt("Settings", "Models, agents, commands, and other configuration"),
+        opt("Back to prompt", "Return to the prompt and keep working"),
       ]);
       // A deliberate ESC only needs distinct handling in tool mode (so
       // pp_phase_complete can stop the turn); in command mode ESC just closes
       // the menu like "Back".
       if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
-      if (!autoChoice || autoChoice === "Back") return "";
-      if (autoChoice === "Info") {
-        await showInfoMenu(orchestrator, ctx);
+      if (!autoChoice || autoChoice === "Back to prompt") return "";
+      if (autoChoice === "Subagents") {
+        await showSubagentsMenu(ctx);
         continue;
       }
       if (autoChoice === "Settings") {
@@ -3562,23 +3962,23 @@ export async function showActiveTaskMenu(
     const options: OptionInput[] = [];
     options.push(opt("Next", "Complete, pause, or continue to next phase"));
     if (!waiting) {
-      options.push(opt("Review", "Auto review, Plannotator, or manual review"));
+      options.push(opt("Review", `Review ${reviewTarget}: automated reviewers${hasPlannotator ? ", Plannotator, or" : " or"} your own editor pass`));
     }
-    options.push(opt("Info", "Subagents, usage, and task status"));
-    options.push(opt("Settings", "Flant AI and other configuration"));
-    options.push(opt("Back", "Return to the prompt and keep working"));
+    options.push(opt("Subagents", "View and manage running subagents"));
+    options.push(opt("Settings", "Models, agents, commands, and other configuration"));
+    options.push(opt("Back to prompt", "Return to the prompt and keep working"));
 
     const headerLines = [`/pp\n\nTask: ${task.type}\nPhase: ${phase}`];
     if (summary !== "/pp") headerLines.push(`\n\n${summary}`);
     const menuTitle = headerLines.join("");
     const { choice, cancelReason } = await selectOptionCancelable(ctx, menuTitle, options);
     if (cancelReason === "user" && mode === "tool") return USER_CANCELLED;
-    if (!choice || choice === "Back") {
+    if (!choice || choice === "Back to prompt") {
       return "";
     }
 
-    if (choice === "Info") {
-      await showInfoMenu(orchestrator, ctx);
+    if (choice === "Subagents") {
+      await showSubagentsMenu(ctx);
       continue;
     }
     if (choice === "Settings") {
@@ -3590,72 +3990,197 @@ export async function showActiveTaskMenu(
     }
 
     if (choice === "Next") {
-      const canContinue = phase !== "implement" && !waiting;
-      const continueLabel = phase === "plan" ? "Continue to implement" : "Continue to plan & implement";
-      const finishOptions: OptionInput[] = [];
-      if (canContinue) {
-        finishOptions.push(opt(continueLabel, "Approve and advance to the next phase"));
-      }
-      finishOptions.push(opt("Complete", "Mark task as done and clean up"));
-      finishOptions.push(opt("Pause", "Suspend task to resume later"));
-      finishOptions.push(opt("Back", "Return to the previous menu"));
-
-      const finishChoice = await selectOption(ctx, "Next", finishOptions);
-      if (!finishChoice || finishChoice === "Back") continue;
-      if (finishChoice === "Pause") {
-        const text = await pauseTask(orchestrator, ctx);
-        return mode === "tool" ? text : "";
-      }
-      if (finishChoice === "Complete") {
-        const text = await finishTask(orchestrator, ctx);
-        return mode === "tool" ? text : "";
-      }
-      const next = nextPhase(task.type, phase);
-
-      if (
-        next === "plan" &&
-        task.type === "brainstorm"
-      ) {
-        const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "implement");
-        if (!modeSelection) continue;
-        task.state.mode = modeSelection.mode;
-        task.state.effectiveMode = undefined;
-        task.state.autonomousConfig = modeSelection.autonomousConfig;
-        saveTask(task.dir, task.state);
-      }
+      // The Next submenu runs its own loop so that a deeper submenu's "Back"
+      // (e.g. Publish) returns here rather than overshooting to the top-level menu.
+      while (true) {
+        const canContinue = phase !== "implement" && !waiting;
+        const continueLabel = phase === "plan" ? "Continue to implement" : "Continue to plan & implement";
+        const finishOptions: OptionInput[] = [];
+        if (phase === "review") {
+          finishOptions.push(opt("Publish", "Publish the synthesized review findings as file comments or GitHub PR comments"));
+        }
+        const nextPhaseName = phase === "plan" ? "implement" : "plan & implement";
+        const autoThenContinueLabel = `Auto review, then continue to ${nextPhaseName}`;
+        if (canContinue) {
+          finishOptions.push(opt(continueLabel, "Approve and advance to the next phase"));
+          finishOptions.push(opt(autoThenContinueLabel, "Loop reviewers over this phase until they approve (up to N passes), then advance"));
+        }
+        finishOptions.push(opt("Complete", "Mark task as done and clean up"));
+        finishOptions.push(opt("Pause", "Suspend task to resume later"));
+        finishOptions.push(opt("Back", "Return to the previous menu"));
+
+        const finishChoice = await selectOption(ctx, "Next", finishOptions);
+        if (!finishChoice || finishChoice === "Back") break;
+        if (finishChoice === autoThenContinueLabel) {
+          const next = nextPhase(task.type, phase);
+          // Collect the SAME advance inputs the plain-continue path would, NOW,
+          // and stash them on the flag — the later headless pp_phase_complete
+          // branch that advances cannot prompt the user.
+          const deferred: { mode?: TaskMode; autonomousConfig?: AutonomousConfig; plannerPreset?: string } = {};
+          if (next === "plan" && task.type === "brainstorm") {
+            const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "implement");
+            if (!modeSelection) continue;
+            deferred.mode = modeSelection.mode;
+            deferred.autonomousConfig = modeSelection.autonomousConfig;
+          }
+          if (next === "plan" && getEffectiveMode(task.state) !== "autonomous") {
+            const pickedPlannerPreset = await pickPreset(ctx, orchestrator, "planners", "Planner preset");
+            if (!pickedPlannerPreset) continue;
+            deferred.plannerPreset = pickedPlannerPreset;
+          }
+          // Already approved clean this phase: skip review, advance straight through.
+          if (task.state.reviewApprovedClean) {
+            if (deferred.mode) task.state.mode = deferred.mode;
+            if (deferred.autonomousConfig) task.state.autonomousConfig = deferred.autonomousConfig;
+            task.state.effectiveMode = undefined;
+            finalizeReviewCycle(task);
+            const advResult = await orchestrator.transitionToNextPhase(ctx, deferred.plannerPreset);
+            if (!advResult.ok) return `Transition blocked: ${advResult.error}`;
+            return "";
+          }
+          const loopPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");
+          if (!loopPreset) continue;
+          if (!hasEnabledReviewers(orchestrator, loopPreset)) {
+            const rg = reviewPresetGroupForPhase(phase);
+            const label = rg === "brainstormReviewers" ? "artifact" : rg === "planReviewers" ? "plan" : "code";
+            ctx.ui.notify(`No ${label} reviewers enabled.`, "info");
+            continue;
+          }
+          const passes = await pickMaxReviewPasses(ctx, 3);
+          if (passes === null) continue;
+          finalizeReviewCycle(task);
+          if (task.state.reviewPassByKind?.[phase]) task.state.reviewPassByKind[phase].auto = 0;
+          task.state.reviewApprovedClean = false;
+          task.state.manualAutoReview = { phase, preset: loopPreset, maxPasses: passes, advanceOnComplete: true, deferredAdvance: deferred };
+          saveTask(task.dir, task.state);
+          return advanceBanner(
+            `[PI-PI] Auto-review-then-continue started over ${reviewTarget} (up to ${passes >= 999 ? "unlimited" : passes} passes). ` +
+            "Call pp_phase_complete now to run the first review pass; after each pass, apply the reviewers' feedback and call pp_phase_complete again. " +
+            "Do NOT pause to ask for design or user approval while this loop runs — it supersedes the pre-finalization approval rule. " +
+            `When reviewers unanimously approve or the pass cap is reached, the task advances to ${nextPhaseName} automatically.`,
+          );
+        }
+        if (finishChoice === "Publish") {
+          const target = await selectOption(ctx, "Publish", [
+            opt("As file comments", "Insert AI_COMMENT: markers at each finding's location in the source"),
+            opt("As GitHub PR comments", "Post line-anchored comments to the branch's PR from your GitHub account"),
+            opt("Back", "Return to the previous menu"),
+          ]);
+          if (!target || target === "Back") continue;
+          const guardMessage = publishGuard(task.dir);
+          if (guardMessage) {
+            ctx.ui.notify(guardMessage, "info");
+            continue;
+          }
+          return target === "As file comments"
+            ? publishFileCommentsBanner(task.dir)
+            : publishPrCommentsBanner(task.dir);
+        }
+        if (finishChoice === "Pause") {
+          const text = await pauseTask(orchestrator, ctx);
+          return mode === "tool" ? text : "";
+        }
+        if (finishChoice === "Complete") {
+          const text = await finishTask(orchestrator, ctx);
+          return mode === "tool" ? text : "";
+        }
+        const next = nextPhase(task.type, phase);
+
+        if (
+          next === "plan" &&
+          task.type === "brainstorm"
+        ) {
+          const modeSelection = await pickModeForTaskStart(orchestrator, ctx, "implement");
+          if (!modeSelection) continue;
+          task.state.mode = modeSelection.mode;
+          task.state.effectiveMode = undefined;
+          task.state.autonomousConfig = modeSelection.autonomousConfig;
+          saveTask(task.dir, task.state);
+        }
 
-      let plannerPreset: string | undefined;
-      if (next === "plan") {
-        if (getEffectiveMode(task.state) !== "autonomous") {
-          const pickedPlannerPreset = await pickPreset(ctx, orchestrator, "planners", "Planner preset");
-          if (!pickedPlannerPreset) continue;
-          plannerPreset = pickedPlannerPreset;
+        let plannerPreset: string | undefined;
+        if (next === "plan") {
+          if (getEffectiveMode(task.state) !== "autonomous") {
+            const pickedPlannerPreset = await pickPreset(ctx, orchestrator, "planners", "Planner preset");
+            if (!pickedPlannerPreset) continue;
+            plannerPreset = pickedPlannerPreset;
+          }
         }
+        finalizeReviewCycle(task);
+        const result = await orchestrator.transitionToNextPhase(ctx, plannerPreset);
+        if (!result.ok) return `Transition blocked: ${result.error}`;
+        // Transition is now owned by the controller (state ≠ running) or we're
+        // awaiting subagents; either way the menu returns empty.
+        return "";
       }
-      finalizeReviewCycle(task);
-      const result = await orchestrator.transitionToNextPhase(ctx, plannerPreset);
-      if (!result.ok) return `Transition blocked: ${result.error}`;
-      // Transition is now owned by the controller (state ≠ running) or we're
-      // awaiting subagents; either way the menu returns empty.
-      return "";
+      continue;
     }
 
     if (choice === "Review") {
+      // The Review submenu runs its own loop so a recoverable choice (no reviewers
+      // enabled, preset cancelled, "Review on my own" Back, a plannotator early
+      // exit) returns HERE rather than overshooting to the top-level /pp menu.
+      // Only an explicit "Back" breaks out; start/wait/instruction paths return.
+      while (true) {
+      // A review already running: block re-entry BEFORE any finalizeReviewCycle
+      // (which would null the live cycle and hide it), so we never double-spawn.
+      // Notify and break back to the top-level menu with the live cycle intact
+      // rather than exiting /pp.
+      if (isReviewCycleLive(task)) {
+        ctx.ui.notify("A review is already running", "info");
+        break;
+      }
       const reviewOptions: OptionInput[] = [
-        opt(autoLabel, "Run automated review with configured reviewers"),
+        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";
       if (hasPlannotator) {
         reviewOptions.push(opt("Review in Plannotator", phase === "plan" ? "Open plan review in browser" : "Open code diff review in browser"));
+      } else if (hasArtifactPlannotator) {
+        reviewOptions.push(opt("Review in Plannotator", "Open USER_REQUEST.md, RESEARCH.md, and artifacts/*.md for review in browser"));
       }
       reviewOptions.push(opt("Review on my own", phase === "implement"
-        ? "Review in your editor: mark spots with AI_REVIEW: comments, then have the agent address them"
-        : "Review manually, then continue"));
+        ? "Mark spots in the changed files with AI_REVIEW: comments; the agent then addresses each and removes the marker"
+        : phase === "plan"
+          ? "Mark spots in the synthesized plan with AI_REVIEW: comments; the agent then addresses each and removes the marker"
+          : "Mark spots in USER_REQUEST.md, RESEARCH.md, and artifacts/*.md with AI_REVIEW: comments; the agent then addresses each and removes the marker"));
       reviewOptions.push(opt("Back", "Return to the previous menu"));
 
       const reviewChoice = await selectOption(ctx, "Review", reviewOptions);
-      if (!reviewChoice || reviewChoice === "Back") continue;
+      if (!reviewChoice || reviewChoice === "Back") break;
 
       if (reviewChoice === "Review in Plannotator") {
+        if (hasArtifactPlannotator) {
+          // brainstorm/debug have 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.
+          const { opened, result } = await openAnnotateReview(orchestrator.pi, {
+            filePath: task.dir,
+            folderPath: task.dir,
+            mode: "annotate-folder",
+            gate: true,
+          });
+          if (!opened || !result) {
+            ctx.ui.notify("Could not open Plannotator for review.", "error");
+            continue;
+          }
+          if (result.approved) {
+            ctx.ui.notify("Plannotator review approved. Choose next action.", "info");
+            continue;
+          }
+          const feedback = result.feedback?.trim();
+          if (feedback) {
+            setStep(orchestrator, "llm_work");
+            return advanceBanner(
+              "[PI-PI] The user reviewed this phase's artifacts in Plannotator and left the following feedback. " +
+              "Address each point, updating USER_REQUEST.md, RESEARCH.md, and artifacts/*.md as needed:\n\n" +
+              feedback,
+            );
+          }
+          continue;
+        }
         if (phase === "plan") {
           finalizeReviewCycle(task);
           const text = await enterReviewCycle(orchestrator, ctx, "plannotator");
@@ -3666,118 +4191,75 @@ export async function showActiveTaskMenu(
           return handled.text ?? text;
         }
         const allRepos = getRegisteredRepos(orchestrator);
-        const summaries: string[] = [];
-        const repos: RepoInfo[] = [];
+        const eligible: string[] = [];
         for (const repo of allRepos) {
           const base = await detectDefaultBranch(orchestrator, allRepos, repo.path);
           const { changed, error } = await repoHasReviewableChanges(orchestrator, repo, base);
-          if (error) {
-            summaries.push(`${formatRepoLabel(repo)}: ERROR — ${error}`);
-            repos.push(repo);
-          } else if (changed) {
-            repos.push(repo);
-          }
+          if (error || changed) eligible.push(repo.path);
         }
-        if (repos.length === 0) {
+        if (eligible.length === 0) {
           ctx.ui.notify("No registered repositories have changes to review.", "info");
           continue;
         }
-        let stopReviewing = false;
-
-        for (const repo of repos) {
-          if (stopReviewing) break;
-
-          while (true) {
-            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"),
-            ]);
-
-            if (!diffChoice || diffChoice === "Done (stop reviewing)") {
-              stopReviewing = true;
-              break;
-            }
-            if (diffChoice === "Skip this repo") {
-              summaries.push(`${formatRepoLabel(repo)}: SKIPPED`);
-              break;
-            }
-
-            let diffType: string | undefined;
-            let defaultBranch: string | undefined;
-
-            if (diffChoice === "All branch changes") {
-              diffType = "branch";
-              defaultBranch = await detectDefaultBranch(orchestrator, repos, 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,
-            });
-            if (result.status === "error") {
-              summaries.push(`${formatRepoLabel(repo)}: ERROR${result.error ? ` — ${result.error}` : ""}`);
-            } else if (result.status === "approved") {
-              summaries.push(`${formatRepoLabel(repo)}: APPROVED`);
-            } else {
-              summaries.push(`${formatRepoLabel(repo)}: NEEDS_CHANGES${result.feedback ? `\nFeedback: ${result.feedback}` : ""}`);
-            }
-            break;
-          }
-        }
-
-        if (summaries.length > 0) {
-          ctx.ui.notify(`Plannotator review summary:\n\n${summaries.join("\n\n")}`, "info");
-        } else {
-          ctx.ui.notify("No repositories were reviewed in Plannotator.", "info");
-        }
+        // 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.
+        task.state.plannotatorCursor = { repoPaths: eligible, index: 0 };
+        saveTask(task.dir, task.state);
+        const cursorText = await runPlannotatorCursor(orchestrator, ctx);
+        if (cursorText) return cursorText;
         continue;
       }
 
       if (reviewChoice === "Review on my own") {
-        if (phase === "plan") {
-          setStep(orchestrator, "synthesize");
-          return continueMessage;
-        }
-        if (phase !== "implement") {
-          setStep(orchestrator, "llm_work");
-          return continueMessage;
-        }
-
         const gate = await selectOption(ctx, "Editor review", [
           opt("Done", "I've added AI_REVIEW: markers and saved my files"),
           opt("Skip markers", "Continue without the marker workflow"),
           opt("Back", "Return to the review menu"),
         ]);
         if (!gate || gate === "Back") continue;
-        setStep(orchestrator, "llm_work");
+        setStep(orchestrator, phase === "plan" ? "synthesize" : "llm_work");
         if (gate === "Skip markers") {
           return continueMessage;
         }
+        if (phase === "implement") {
+          return advanceBanner(
+            "[PI-PI] The user reviewed the changes in their editor and left inline `AI_REVIEW:` markers " +
+            `${AI_REVIEW_MARKER_SYNTAX}.\n\n` +
+            "For each registered repo, enumerate the CHANGED files only — union of `git diff --name-only <base>...HEAD`, " +
+            "`git diff --name-only`, `git diff --cached --name-only`, and untracked-non-ignored files from `git status --porcelain` " +
+            "(base = each repo's configured base branch) — and search WITHIN those files for `AI_REVIEW:`. Do NOT grep the whole " +
+            "worktree (avoid vendored/generated/node_modules and historical markers).\n\n" +
+            AI_REVIEW_MARKER_LOOP,
+          );
+        }
+        return readOnlyReviewBanner(phase, task.dir);
+      }
+
+      if (reviewChoice === "Auto review until approved") {
+        const loopPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");
+        if (!loopPreset) continue;
+        if (!hasEnabledReviewers(orchestrator, loopPreset)) {
+          const rg = reviewPresetGroupForPhase(phase);
+          const label = rg === "brainstormReviewers" ? "artifact" : rg === "planReviewers" ? "plan" : "code";
+          ctx.ui.notify(`No ${label} reviewers enabled.`, "info");
+          continue;
+        }
+        const passes = await pickMaxReviewPasses(ctx, 3);
+        if (passes === null) 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.
+        if (task.state.reviewPassByKind?.[phase]) task.state.reviewPassByKind[phase].auto = 0;
+        task.state.reviewApprovedClean = false;
+        task.state.manualAutoReview = { phase, preset: loopPreset, maxPasses: passes, advanceOnComplete: false };
+        saveTask(task.dir, task.state);
         return advanceBanner(
-          "[PI-PI] The user reviewed the changes in their editor and left inline `AI_REVIEW:` markers " +
-          "(inside each file's native comment syntax, e.g. `// AI_REVIEW: ...`, `# AI_REVIEW: ...`, " +
-          "`<!-- AI_REVIEW: ... -->`).\n\n" +
-          "For each registered repo, enumerate the CHANGED files only — union of `git diff --name-only <base>...HEAD`, " +
-          "`git diff --name-only`, `git diff --cached --name-only`, and untracked-non-ignored files from `git status --porcelain` " +
-          "(base = each repo's configured base branch) — and search WITHIN those files for `AI_REVIEW:`. Do NOT grep the whole " +
-          "worktree (avoid vendored/generated/node_modules and historical markers).\n\n" +
-          "For each marker: address the request, then remove that marker in the SAME edit. After a pass, re-scan the changed " +
-          "files and repeat until no `AI_REVIEW:` markers remain. Then verify your work and report what you changed per marker. " +
-          "When complete, call pp_phase_complete.",
+          `[PI-PI] Auto-review-until-approved started over ${reviewTarget} (up to ${passes >= 999 ? "unlimited" : passes} passes). ` +
+          "Call pp_phase_complete now to run the first review pass; after each pass, apply the reviewers' feedback and call pp_phase_complete again. " +
+          "Do NOT pause to ask for design or user approval while this loop runs — it supersedes the pre-finalization approval rule. " +
+          "The loop stops when reviewers unanimously approve or the pass cap is reached. Do NOT advance the phase yourself.",
         );
       }
 
@@ -3785,7 +4267,8 @@ export async function showActiveTaskMenu(
       if (!reviewPreset) continue;
       finalizeReviewCycle(task);
       if (!hasEnabledReviewers(orchestrator, reviewPreset)) {
-        const label = phase === "brainstorm" ? "brainstorm" : phase === "plan" ? "plan" : "code";
+        const reviewGroup = reviewPresetGroupForPhase(phase);
+        const label = reviewGroup === "brainstormReviewers" ? "artifact" : reviewGroup === "planReviewers" ? "plan" : "code";
         ctx.ui.notify(`No ${label} reviewers enabled.`, "info");
         continue;
       }
@@ -3795,11 +4278,15 @@ export async function showActiveTaskMenu(
       const handled = handleReviewResult(ctx, text);
       if (handled.continueLoop) continue;
       return handled.text ?? text;
+      }
     }
   }
 }
 
 export async function showPpMenu(orchestrator: Orchestrator, ctx: any, mode: MenuMode = "command"): Promise<string | undefined> {
+  if (orchestrator.configError) {
+    return showConfigErrorMenu(orchestrator, ctx);
+  }
   if (!orchestrator.active) {
     return showNoActiveMenu(orchestrator, ctx);
   }