@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/extensions/orchestrator/pp-menu.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, relative, basename } from "path";
 import { isDeepStrictEqual } from "util";
 import { askUser, isCancel, type CancelReason } from "../../3p/pi-ask-user/index.js";
@@ -24,10 +24,12 @@ import {
   loadBrainstormReviewOutputs,
   loadCodeReviewOutputs,
   loadPlanReviewOutputs,
+  hasFinalPassAnchors,
 } from "./context.js";
-import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle } from "./event-handlers.js";
+import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle, isReviewCycleLive } from "./event-handlers.js";
 import { Orchestrator } from "./orchestrator.js";
-import { cancelPendingPlannotatorWait } from "./plannotator.js";
+import { cancelPendingPlannotatorWait, openPlannotator, waitForPlannotatorResult } from "./plannotator.js";
+import { advanceBanner } from "./messages.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
@@ -84,6 +86,7 @@ type TimeoutKey =
   | "performance.commands.afterEdit"
   | "performance.commands.afterImplement"
   | "performance.internals.subagentStale"
+  | "performance.internals.mainTurnStale"
   | "performance.internals.taskLockStale"
   | "performance.internals.taskLockRefresh";
 
@@ -104,16 +107,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 {
@@ -150,51 +159,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 }> = [];
@@ -225,6 +190,44 @@ async function pickCommitForRepo(orchestrator: Orchestrator, ctx: any, repo: Rep
   return pickedHash || null;
 }
 
+async function repoHasReviewableChanges(
+  orchestrator: Orchestrator,
+  repo: RepoInfo,
+  base: string,
+): Promise<{ changed: boolean; error?: string }> {
+  const run = async (args: string[]): Promise<{ out: string; failed: boolean }> => {
+    try {
+      const res = await orchestrator.pi.exec("git", args, { cwd: repo.path, timeout: 5000 });
+      if (res.code !== 0) return { out: "", failed: true };
+      return { out: res.stdout, failed: false };
+    } catch {
+      return { out: "", failed: true };
+    }
+  };
+
+  const committed = await run(["diff", "--name-only", `${base}...HEAD`]);
+  const unstaged = await run(["diff", "--name-only"]);
+  const staged = await run(["diff", "--cached", "--name-only"]);
+  const status = await run(["status", "--porcelain"]);
+
+  const hasCommitted = committed.out.trim().length > 0;
+  const hasUnstaged = unstaged.out.trim().length > 0;
+  const hasStaged = staged.out.trim().length > 0;
+  const hasUntracked = status.out.split("\n").some((line) => line.startsWith("??"));
+  const changed = hasCommitted || hasUnstaged || hasStaged || hasUntracked;
+
+  if (changed) return { changed: true };
+
+  // No change detected — but a failed probe (e.g. a missing/invalid base ref)
+  // could be masking real changes, so surface it rather than silently hiding
+  // the repo.
+  if (committed.failed || unstaged.failed || staged.failed || status.failed) {
+    return { changed: false, error: "git status/diff failed" };
+  }
+
+  return { changed: false };
+}
+
 interface RepoPrContext {
   repoPath: string;
   prUrl: string | null;
@@ -237,6 +240,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");
@@ -252,6 +333,11 @@ function showStatus(orchestrator: Orchestrator, ctx: any): void {
 }
 
 async function abortCurrentWork(orchestrator: Orchestrator, ctx: any): Promise<void> {
+  // Clear pi-pi's own delayed post-error retry (timer + ESC interrupt). Unlike
+  // pause/finish, abortCurrentWork does NOT go through cleanupActive/
+  // resetTaskScopedState, so without this a scheduled retry would survive the
+  // abort and re-nudge seconds later.
+  orchestrator.cancelPendingRetry();
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
   await ctx.waitForIdle?.();
@@ -272,6 +358,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();
@@ -296,6 +385,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));
@@ -322,7 +418,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"));
@@ -795,6 +892,9 @@ 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);
   return out;
 }
 
@@ -814,6 +914,7 @@ function flantStatusText(settings: FlantSettings): string {
     lines.push(
       `Personal subscription: on (${subActive ? `active — pp-flant-anthropic-sub, ${providers.anthropic} models` : "inactive"})`,
     );
+    lines.push(`Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`);
     if (!subActive) {
       if (!hasOAuth) lines.push("  - missing Claude OAuth token (run pi /login for Anthropic)");
       if (!hasGatewayKey) lines.push("  - missing gateway key (set LLM_API_KEY or FLANT_API_KEY)");
@@ -849,15 +950,22 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
   while (true) {
     const settings = loadFlantSettings();
     const enableLabel = `Enable: ${settings.enabled ? "ON" : "OFF"}`;
-    const options: OptionInput[] = [enableLabel];
+    const options: OptionInput[] = [
+      { title: enableLabel, description: "Turn the Flant AI model providers on or off" },
+    ];
     const subscriptionLabel = `Personal Claude subscription: ${settings.subscription ? "ON" : "OFF"}`;
     if (settings.enabled) {
       options.push(
-        `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`,
-        `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`,
-        subscriptionLabel,
-        "Update now",
-        "Current status",
+        { title: subscriptionLabel, description: "Route Claude roles through your personal Claude subscription instead of the gateway" },
+        { title: `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`, description: "Refresh the available model list automatically each time pi starts" },
+        { title: `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`, description: "How long the fetched model list is reused before it is refreshed" },
+      );
+      if (settings.subscription) {
+        options.push({ title: `Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`, description: "How often to retry your subscription after it was rate-limited and traffic fell back to the gateway" });
+      }
+      options.push(
+        { title: "Update now", description: "Fetch the latest model list from Flant right away" },
+        { title: "Current status", description: "Show the current Flant configuration, providers, and model counts" },
       );
     }
     options.push({ title: "Back", description: "Return to the previous menu" });
@@ -920,6 +1028,22 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
       continue;
     }
 
+    if (choice.startsWith("Rate-limit switch-back check:")) {
+      const selected = await selectOption(ctx, "Switch-back check interval", [
+        { title: "15 min", description: "Probe the subscription limit every 15 minutes" },
+        { title: "30 min", description: "Default — probe every 30 minutes" },
+        { title: "60 min", description: "Probe hourly" },
+        { title: "120 min", description: "Probe every two hours" },
+        { title: "Back", description: "Return to the previous menu" },
+      ]);
+      if (!selected || selected === "Back") continue;
+      const mins = Number(selected.split(" ")[0]);
+      if (!Number.isFinite(mins) || mins <= 0) continue;
+      saveFlantSettings({ ...settings, switchBackIntervalMinutes: mins });
+      ctx.ui.notify(`Switch-back check interval set to ${mins} min.`, "info");
+      continue;
+    }
+
     if (choice.startsWith("Cache period:")) {
       const selected = await selectOption(ctx, "Cache period", [
         { title: "1 day", description: "Refresh model metadata daily" },
@@ -1199,6 +1323,9 @@ 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 PRESET_GROUP_ITEMS: Array<{ group: PresetGroup; label: string }> = [
@@ -1212,6 +1339,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",
 };
@@ -1753,8 +1881,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"),
     ]);
@@ -1800,8 +1928,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"),
     ]);
@@ -1902,8 +2030,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"));
@@ -1924,7 +2052,7 @@ async function showPresetVariantEditor(
       continue;
     }
     if (choice.startsWith("Enabled:")) {
-      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"]);
+      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"], "Make this agent available for use", "Disable this agent so it is not used");
       continue;
     }
     const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -1955,7 +2083,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;
@@ -2065,8 +2193,8 @@ async function showPresetEnabledSetting(
   const yesTitle = withTags("Yes", formatSourceTags(true, info));
   const noTitle = withTags("No", formatSourceTags(false, info));
   const choice = await selectOption(ctx, "Enabled", [
-    yesTitle,
-    noTitle,
+    { title: yesTitle, description: "Make this preset available for selection" },
+    { title: noTitle, description: "Hide this preset so it can no longer be selected" },
     opt("Back", "Return to the previous menu"),
   ]);
   if (!choice || choice === "Back") return;
@@ -2124,7 +2252,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;
@@ -2198,7 +2326,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);
@@ -2247,7 +2375,7 @@ async function showAfterEditCommands(orchestrator: Orchestrator, ctx: any): Prom
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       if (commandChoice === "Triggers") {
@@ -2327,7 +2455,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);
@@ -2364,7 +2492,7 @@ async function showAfterImplementCommands(orchestrator: Orchestrator, ctx: any):
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -2387,11 +2515,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"),
     ]);
@@ -2422,6 +2550,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"],
@@ -2436,7 +2569,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);
@@ -2474,7 +2607,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;
@@ -2487,14 +2620,16 @@ async function showBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(true, info));
     const noTitle = withTags("No", formatSourceTags(false, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2516,14 +2651,16 @@ async function showInvertedBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(false, info));
     const noTitle = withTags("No", formatSourceTags(true, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2541,15 +2678,15 @@ async function showInvertedBooleanSetting(
 }
 
 async function showLogLevelSetting(orchestrator: Orchestrator, ctx: any): Promise<void> {
-  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string }> = [
-    { value: "debug", label: "Debug" },
-    { value: "info", label: "Info" },
-    { value: "warn", label: "Warning" },
-    { value: "error", label: "Error" },
+  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string; description: string }> = [
+    { value: "debug", label: "Debug", description: "Log everything, including detailed diagnostics for troubleshooting" },
+    { value: "info", label: "Info", description: "Log normal activity plus warnings and errors" },
+    { value: "warn", label: "Warning", description: "Log only warnings and errors" },
+    { value: "error", label: "Error", description: "Log only errors" },
   ];
   while (true) {
     const info = getConfigSourceInfo(orchestrator, ["general", "logLevel"]);
-    const options: OptionInput[] = levels.map((entry) => withTags(entry.label, formatSourceTags(entry.value, info)));
+    const options: OptionInput[] = levels.map((entry) => ({ title: withTags(entry.label, formatSourceTags(entry.value, info)), description: entry.description }));
     options.push(...buildResetOptions(orchestrator, ["general", "logLevel"]));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, "Log level", options);
@@ -2571,6 +2708,7 @@ 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/"),
@@ -2579,11 +2717,15 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
     ]);
     if (!choice || choice === "Back") return BACK;
     if (choice.startsWith("Commit automatically:")) {
-      await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"]);
+      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"]);
+      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;
     }
     if (choice.startsWith("Log level:")) {
@@ -2591,7 +2733,7 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
       continue;
     }
     if (choice.startsWith("Tracing:")) {
-      await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"]);
+      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);
@@ -2685,7 +2827,7 @@ async function showSettingsMenu(orchestrator: Orchestrator, ctx: any): Promise<t
       opt("General", "Commit, log level, Flant AI, 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("Back", "Return to the previous menu"),
     ];
@@ -2777,10 +2919,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"));
@@ -3056,201 +3198,138 @@ async function openCodeReviewInPlannotator(
   if (payload.diffType) requestPayload.diffType = payload.diffType;
   if (payload.defaultBranch) requestPayload.defaultBranch = payload.defaultBranch;
 
-  return await new Promise((resolve) => {
-    let handled = false;
-    const timer = setTimeout(() => {
-      if (!handled) resolve({ status: "error", error: "Plannotator is not available." });
-    }, 30000);
-    orchestrator.pi.events.emit("plannotator:request", {
-      requestId: crypto.randomUUID(),
-      action: "code-review",
-      payload: requestPayload,
-      respond: (response: any) => {
-        handled = true;
-        clearTimeout(timer);
-        if (response?.status !== "handled") {
-          resolve({ status: "error", error: response?.error || "Plannotator is not available." });
-          return;
-        }
-        const approved = !!response?.result?.approved;
-        const feedback = typeof response?.result?.feedback === "string" && response.result.feedback.trim().length > 0
-          ? response.result.feedback
-          : undefined;
-        resolve({ status: approved ? "approved" : "needs_changes", feedback });
-      },
-    });
-  });
-}
+  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", requestPayload);
+  if (!opened) {
+    return { status: "error", error: "Plannotator is not available." };
+  }
 
-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");
+  let result: { approved: boolean; feedback?: string; error?: string };
+  try {
+    result = await waitForPlannotatorResult(orchestrator, reviewId, null);
+  } catch (err) {
+    return { status: "error", error: err instanceof Error ? err.message : "Plannotator review failed." };
+  }
+  if (result.error) {
+    return { status: "error", error: result.error };
+  }
+  const feedback = typeof result.feedback === "string" && result.feedback.trim().length > 0
+    ? result.feedback
+    : undefined;
+  return { status: result.approved ? "approved" : "needs_changes", feedback };
+}
+
+// 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/error/skip, advance and continue in-loop. 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 });
+
+    // Advance past this repo regardless of 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}`,
+      );
+    }
+
+    if (result.status === "error") {
+      ctx.ui.notify(`${formatRepoLabel(repo)}: ERROR${result.error ? ` — ${result.error}` : ""}`, "warning");
+    } else {
+      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;
   }
 }
 
@@ -3344,7 +3423,7 @@ async function showNoActiveMenu(orchestrator: Orchestrator, ctx: any): Promise<s
     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: "Settings", description: "Models, agents, commands, and other configuration" },
       { title: "Back", description: "Close this menu" },
     ]);
     if (!choice || choice === "Back") return undefined;
@@ -3405,7 +3484,7 @@ async function showQuickTaskMenu(
       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("Settings", "Models, agents, commands, and other configuration"),
       opt("Back", "Return to the prompt and keep working"),
     ]);
     // A deliberate ESC in tool mode must stop the turn cleanly (mirror the
@@ -3434,8 +3513,13 @@ 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 = "User wants to continue. Run /pp when ready to advance.";
+  const continueMessage = advanceBanner("[PI-PI] User wants to continue. Run /pp when ready to advance.");
 
   while (true) {
     if (!orchestrator.active) return "No active task.";
@@ -3444,6 +3528,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);
@@ -3455,15 +3548,21 @@ 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 getReviewPresetGroup: brainstorm →
+    // brainstormReviewers (state files), plan → planReviewers (synthesized plan), every other
+    // phase → 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, e.g. state files in a debug/review phase).
+    const reviewTarget = phase === "plan" ? "the synthesized plan" : phase === "brainstorm" ? "this phase's state files" : "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("Settings", "Models, agents, commands, and other configuration"),
         opt("Back", "Return to the prompt and keep working"),
       ]);
       // A deliberate ESC only needs distinct handling in tool mode (so
@@ -3490,10 +3589,10 @@ 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("Settings", "Models, agents, commands, and other configuration"));
     options.push(opt("Back", "Return to the prompt and keep working"));
 
     const headerLines = [`/pp\n\nTask: ${task.type}\nPhase: ${phase}`];
@@ -3518,68 +3617,109 @@ 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"));
+        }
+        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") break;
+        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}`),
       ];
       if (hasPlannotator) {
         reviewOptions.push(opt("Review in Plannotator", phase === "plan" ? "Open plan review in browser" : "Open code diff review in browser"));
       }
-      reviewOptions.push(opt("Review on my own", "Review manually, then continue"));
+      reviewOptions.push(opt("Review on my own", phase === "implement"
+        ? "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 (phase === "plan") {
@@ -3591,80 +3731,51 @@ export async function showActiveTaskMenu(
           if (handled.continueLoop) continue;
           return handled.text ?? text;
         }
-        const repos = getRegisteredRepos(orchestrator);
-        const summaries: string[] = [];
-        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;
-          }
+        const allRepos = getRegisteredRepos(orchestrator);
+        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 || changed) eligible.push(repo.path);
         }
-
-        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");
+        if (eligible.length === 0) {
+          ctx.ui.notify("No registered repositories have changes to review.", "info");
+          continue;
         }
+        // Start (or restart) the interleaved per-repo cursor and run it. On
+        // needs_changes runPlannotatorCursor persists the cursor and returns a
+        // work instruction (exits the menu to start the agent turn); the next /pp
+        // resumes at the following repo.
+        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");
-        } else {
-          setStep(orchestrator, "llm_work");
+        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, 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 continueMessage;
+        return readOnlyReviewBanner(phase, task.dir);
       }
 
       const reviewPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");
@@ -3681,6 +3792,7 @@ export async function showActiveTaskMenu(
       const handled = handleReviewResult(ctx, text);
       if (handled.continueLoop) continue;
       return handled.text ?? text;
+      }
     }
   }
 }