@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/extensions/orchestrator/event-handlers.ts

@@ -1,5 +1,4 @@
-import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "fs";
-import { tmpdir } from "os";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { resolve, basename, join, relative, dirname, isAbsolute, sep } from "path";
 import { validateUserRequest, validateResearch, validateArtifact } from "./validate-artifacts.js";
 import { Type } from "@sinclair/typebox";
@@ -14,28 +13,33 @@ import {
   loadAllContextFiles,
   getPhaseArtifacts,
   getLatestSynthesizedPlan,
+  getArtifactManifest,
   loadBrainstormReviewOutputs,
   loadCodeReviewOutputs,
   loadPlanReviewOutputs,
 } from "./context.js";
-import { PRINCIPLES_BLOCK, TOOLS_BLOCK } from "./agents/tool-routing.js";
+import { PRINCIPLES_BLOCK, TOOLS_BLOCK, DELEGATION_BLOCK } from "./agents/tool-routing.js";
 import { constraintsBlock, phaseConstraint } from "./agents/constraints.js";
 import { registerCbmTools } from "./cbm.js";
 import { registerExaTools } from "./exa.js";
 import { registerAstSearchTool } from "./ast-search.js";
 import { SUBAGENT_SESSION_KEY } from "./index.js";
-import { registerCommandHandlers } from "./command-handlers.js";
+import { registerCommandHandlers, runAfterImplementForActive } from "./command-handlers.js";
+import { registerStateFileTools } from "./pp-state-tools.js";
+import { isAiCommentOnlyChange } from "./ai-comment-cleanup.js";
+import { handleMainRateLimit, handleSubagentRateLimit, isRateLimitError, isSdkRetryableError } from "./rate-limit-fallback.js";
 import { setExtensionOnlyMode, unregisterAgentDefinitions } from "./agents/registry.js";
 import { resolveModel, getModelInfo, updateRegistryFromAvailableModels } from "./model-registry.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
 import { reviewPassUnanimousApprove } from "./phases/verdict.js";
-import { validateExitCriteria } from "./phases/machine.js";
+import { nextPhase, validateExitCriteria } from "./phases/machine.js";
 import { openPlannotator, waitForPlannotatorResult, cancelPendingPlannotatorWait } from "./plannotator.js";
+import { advanceBanner } from "./messages.js";
 import { Orchestrator, type ActiveTask } from "./orchestrator.js";
-import { createCustomFooter, setFooterContext, setFooterTracker } from "./custom-footer.js";
-import { createUsageTracker, dumpUsageSummary, loadUsageSummary, type UsageTracker } from "./usage-tracker.js";
+import { createCustomFooter, setFooterContext, setFooterTracker, setFooterOrchestrator } from "./custom-footer.js";
+import { createUsageTracker, dumpUsageSummary, loadUsageSummary, isSubscriptionRouted, type UsageTracker } from "./usage-tracker.js";
 import { askUser, isCancel } from "../../3p/pi-ask-user/index.js";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { findRootRepo, normalizeRepoPath, resolveRepoForFile, type RepoInfo } from "./repo-utils.js";
@@ -51,6 +55,34 @@ function isPathInside(basePath: string, targetPath: string): boolean {
   return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
 
+// Builds the spawn-time context block appended to a free agent's spawn prompt:
+// inlines USER_REQUEST + RESEARCH (always present by spawn time) and appends a
+// path-aware manifest of additional on-demand documents (artifacts + plan).
+function buildSpawnContextBlock(taskDir: string): string {
+  const parts: string[] = [];
+
+  const userRequestPath = join(taskDir, "USER_REQUEST.md");
+  if (existsSync(userRequestPath)) {
+    parts.push("=== USER REQUEST ===\n" + readFileSync(userRequestPath, "utf-8").trimEnd());
+  }
+  const researchPath = join(taskDir, "RESEARCH.md");
+  if (existsSync(researchPath)) {
+    parts.push("=== RESEARCH ===\n" + readFileSync(researchPath, "utf-8").trimEnd());
+  }
+
+  const manifest = getArtifactManifest(taskDir);
+  if (manifest.length > 0) {
+    const lines = manifest.map((m) => `- ${m.path}  — ${m.title}`);
+    parts.push(
+      "=== ADDITIONAL DOCUMENTS (read from disk if relevant) ===\n" +
+        lines.join("\n") +
+        "\nDo NOT re-read USER_REQUEST/RESEARCH from disk (already above).",
+    );
+  }
+
+  return parts.join("\n\n");
+}
+
 export async function detectDefaultBranch(orchestrator: Orchestrator, repos: RepoInfo[], repoPath: string): Promise<string> {
   const normalizedPath = normalizeRepoPath(repoPath);
   const repo = repos.find((r) => r.path === normalizedPath);
@@ -89,15 +121,21 @@ export async function detectDefaultBranch(orchestrator: Orchestrator, repos: Rep
 }
 
 export async function selectOption(ctx: any, question: string, options: string[]): Promise<string | undefined> {
-  const result = await askUser(ctx, {
-    question,
-    options,
-    allowFreeform: false,
-    allowComment: false,
-    allowMultiple: false,
-  });
-  if (!result || isCancel(result) || result.kind !== "selection") return undefined;
-  return 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) || result.kind !== "selection") return undefined;
+    return result.selections[0];
+  } finally {
+    if (orchestrator) orchestrator.interactivePromptOpen = false;
+  }
 }
 
 function resolveReviewers(
@@ -206,7 +244,7 @@ function tryCompleteReviewCycle(orchestrator: Orchestrator, spawnedReviewers?: n
     },
     "instruction",
   );
-  orchestrator.safeSendUserMessage(reviewReadyMessage(phase, getEffectivePhaseMode(orchestrator.active.state)));
+  orchestrator.safeSendUserMessage(advanceBanner(reviewReadyMessage(phase, getEffectivePhaseMode(orchestrator.active.state))));
 }
 
 function reviewReadyMessage(phase: string, mode: TaskMode): string {
@@ -286,7 +324,9 @@ export async function enterReviewCycle(
     orchestrator.active.state.reviewCycle = null;
     orchestrator.active.state.step = "llm_work";
     saveTask(orchestrator.active.dir, orchestrator.active.state);
-    return "User wants a Plannotator code review. Call pp_specify_reviews with the list of repositories and commit ranges to review. Include all repos where you made changes.";
+    // Implement/review-phase Plannotator is driven entirely by the menu's per-repo
+    // interleaved loop (pp-menu runPlannotatorCursor); it never enters this path.
+    return "Plannotator code review runs per-repo from the /pp Review menu. Open /pp → Review → Review in Plannotator.";
   }
 
   const phase = orchestrator.active.state.phase;
@@ -379,6 +419,14 @@ export async function stopTask(orchestrator: Orchestrator): Promise<string> {
   return `Task "${desc}" stopped. Use /pp → Resume to continue.`;
 }
 
+// A review is LIVE when its cycle exists and reviewers are still being awaited.
+// Guards the menu/autonomous callers against re-spawning reviewers on top of a
+// running cycle (the "6 agents" double-spawn). NOT "a cycle object exists": a
+// completed cycle is finalized (and nulled) legitimately before the next pass.
+export function isReviewCycleLive(task: ActiveTask): boolean {
+  return !!task.state.reviewCycle && task.state.reviewCycle.step === "await_reviewers";
+}
+
 export function finalizeReviewCycle(task: ActiveTask): void {
   if (!task.state.reviewCycle) return;
   const kind = task.state.reviewCycle.kind;
@@ -416,11 +464,174 @@ export function finalizeReviewCycleAutonomous(task: ActiveTask): void {
   saveTask(task.dir, task.state);
 }
 
+export function registerOrchestratorToolsForTest(orchestrator: Orchestrator): void {
+  registerOrchestratorTools(orchestrator);
+}
+
 function registerOrchestratorTools(orchestrator: Orchestrator): void {
   registerRepoTool(orchestrator);
+  registerCheckoutPrHeadTool(orchestrator);
   registerPhaseCompleteTool(orchestrator);
   registerCommitTool(orchestrator);
-  registerSpecifyReviewsTool(orchestrator);
+  registerStateFileTools(orchestrator);
+}
+
+// Extension-side PR-head checkout for the review phase. Performed here (never via the
+// agent prompt) so REVIEW_READONLY_CONSTRAINT stays truthful — the agent never runs
+// `git checkout` itself. Lands the repo on its PR head under strict safety rules (no stash,
+// no --force, no branch switch, no worktree, no detached checkout): when the tree is clean
+// and on the PR head's branch but merely behind, it fast-forwards the branch to the head
+// (`git merge --ff-only`, which never detaches, never rewrites, and refuses a non-ff move).
+// A dirty tree, a different branch, or a non-fast-forwardable divergence all HALT with a
+// message for the user. Checking HEAD's SHA first makes this re-entrant and detached-safe.
+export async function checkoutPrHead(
+  orchestrator: Orchestrator,
+  repoPath: string,
+  headRefName: string,
+  headRefOid: string,
+): Promise<{ ok: boolean; message: string }> {
+  const pi = orchestrator.pi;
+  const name = (headRefName ?? "").trim();
+  const oid = (headRefOid ?? "").trim();
+  if (!name && !oid) {
+    return { ok: true, message: `No PR head provided for ${repoPath}; skipping (non-PR review scope).` };
+  }
+
+  const run = (args: string[]) => pi.exec("git", args, { cwd: repoPath, timeout: 15000 });
+  const target = `${name || oid}${name && oid ? ` @ ${oid}` : ""}`;
+
+  let status;
+  try {
+    status = await run(["status", "--porcelain"]);
+  } catch (err: any) {
+    return { ok: false, message: `Cannot inspect ${repoPath}: ${err?.message ?? "git status failed"}` };
+  }
+  if (status.code !== 0) {
+    return { ok: false, message: `Cannot inspect ${repoPath}: ${status.stderr?.trim() || status.stdout?.trim() || "git status failed"}` };
+  }
+  if (status.stdout.trim()) {
+    return {
+      ok: false,
+      message:
+        `HALT: ${repoPath} has uncommitted changes. Commit or stash them, then bring the repo to its PR head (${target}) and ask me to continue.\n\n${status.stdout.trim()}`,
+    };
+  }
+
+  if (!oid) {
+    return { ok: true, message: `${repoPath}: no PR head commit provided; left as-is (clean tree).` };
+  }
+
+  let head;
+  try {
+    head = await run(["rev-parse", "HEAD"]);
+  } catch (err: any) {
+    return { ok: false, message: `Cannot read HEAD of ${repoPath}: ${err?.message ?? "git rev-parse failed"}` };
+  }
+  if (head.stdout.trim() === oid) {
+    return { ok: true, message: `${repoPath} is on PR head ${oid}.` };
+  }
+
+  let branch;
+  try {
+    branch = await run(["rev-parse", "--abbrev-ref", "HEAD"]);
+  } catch (err: any) {
+    return { ok: false, message: `Cannot read current branch of ${repoPath}: ${err?.message ?? "git rev-parse failed"}` };
+  }
+  const currentBranch = branch.stdout.trim();
+  if (currentBranch === "HEAD") {
+    return {
+      ok: false,
+      message:
+        `HALT: ${repoPath} has a detached HEAD, not at the PR head commit ${oid}. ` +
+        `Check out the PR head branch${name ? ` "${name}"` : ""} at ${oid}, then ask me to continue. I will not move HEAD for you.`,
+    };
+  }
+  if (name && currentBranch !== name) {
+    return {
+      ok: false,
+      message:
+        `HALT: ${repoPath} is on "${currentBranch}", not the PR head branch "${name}" (target commit ${oid}). ` +
+        "Check out that branch at its PR head, then ask me to continue. I will not switch branches for you.",
+    };
+  }
+
+  // Clean tree, on the PR head's branch, but behind: advance the branch to the head with a
+  // fast-forward-only merge. This moves the branch ref without detaching, forcing, or stashing,
+  // and fails safely if the branch has diverged from the PR head.
+  let ff;
+  try {
+    ff = await run(["merge", "--ff-only", oid]);
+  } catch (err: any) {
+    return { ok: false, message: `Fast-forward of ${repoPath} to PR head ${oid} failed: ${err?.message ?? "git merge failed"}` };
+  }
+  if (ff.code !== 0) {
+    return {
+      ok: false,
+      message:
+        `HALT: ${repoPath} (branch "${currentBranch}") cannot fast-forward to PR head ${oid} — it has diverged. ` +
+        `Reconcile it with the PR head, then ask me to continue. I will not force-move or rebase it for you.` +
+        `${ff.stderr?.trim() ? `\n\n${ff.stderr.trim()}` : ""}`,
+    };
+  }
+
+  // `git merge --ff-only <ancestor>` returns exit 0 ("Already up to date") WITHOUT moving HEAD
+  // when the branch is already ahead of the PR head, so a zero exit is not proof we landed on it.
+  // Re-read HEAD and HALT if the branch carries commits beyond the PR head.
+  let after;
+  try {
+    after = await run(["rev-parse", "HEAD"]);
+  } catch (err: any) {
+    return { ok: false, message: `Cannot confirm HEAD of ${repoPath} after fast-forward: ${err?.message ?? "git rev-parse failed"}` };
+  }
+  if (after.stdout.trim() !== oid) {
+    return {
+      ok: false,
+      message:
+        `HALT: ${repoPath} (branch "${currentBranch}") is ahead of the PR head ${oid} — it has commits the PR head does not. ` +
+        "Push them to the PR (or check out the exact PR head), then ask me to continue. I will not move HEAD backwards for you.",
+    };
+  }
+  return { ok: true, message: `${repoPath} fast-forwarded to PR head ${oid}.` };
+}
+
+function registerCheckoutPrHeadTool(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+
+  pi.registerTool({
+    name: "pp_checkout_pr_head",
+    label: "pi-pi",
+    description:
+      "Land a registered repository on its PR head commit before reviewing it. " +
+      "Call this ONLY for a PR-scoped review, once per repo, AFTER you have resolved the PR " +
+      "(e.g. via `gh pr view --json headRefName,headRefOid`). Do NOT call it for a branch, " +
+      "commit-range, or uncommitted-changes review. The extension does this safely (no worktree, " +
+      "no stash, no --force, no branch switch, no detached checkout): a clean repo already on the " +
+      "PR head succeeds; a clean repo on the PR head's branch but behind is fast-forwarded to the " +
+      "head; a dirty tree, a different branch, or a diverged branch HALTS with a message for you to " +
+      "relay to the user. You never run `git checkout` yourself.",
+    parameters: Type.Object({
+      repoPath: Type.String({ description: "Absolute path to the registered repository" }),
+      headRefName: Type.String({ description: "PR head branch name (headRefName)" }),
+      headRefOid: Type.String({ description: "PR head commit SHA (headRefOid)" }),
+    }),
+    async execute(_toolCallId, params: any) {
+      if (!orchestrator.active) {
+        return { content: [{ type: "text" as const, text: "No active task." }], isError: true as const, details: {} };
+      }
+      const pathInput = typeof params.repoPath === "string" ? params.repoPath.trim() : "";
+      if (!pathInput) {
+        return { content: [{ type: "text" as const, text: "Missing repoPath." }], isError: true as const, details: {} };
+      }
+      const normalized = normalizeRepoPath(pathInput);
+      const repos = orchestrator.active.state.repos ?? [];
+      const registered = repos.find((repo) => repo.path === normalized);
+      if (!registered) {
+        return { content: [{ type: "text" as const, text: `Repository is not registered: ${params.repoPath}` }], isError: true as const, details: {} };
+      }
+      const result = await checkoutPrHead(orchestrator, registered.path, params.headRefName ?? "", params.headRefOid ?? "");
+      return { content: [{ type: "text" as const, text: result.message }], isError: result.ok ? undefined : (true as const), details: {} };
+    },
+  });
 }
 
 function registerRepoTool(orchestrator: Orchestrator): void {
@@ -562,190 +773,6 @@ function registerRepoTool(orchestrator: Orchestrator): void {
   });
 }
 
-function openCodeReviewDirect(
-  pi: ExtensionAPI,
-  payload: Record<string, unknown>,
-): Promise<{ approved: boolean; feedback?: string } | { error: string }> {
-  return new Promise((resolve) => {
-    pi.events.emit("plannotator:request", {
-      requestId: crypto.randomUUID(),
-      action: "code-review",
-      payload,
-      respond: (response: any) => {
-        if (response.status === "handled") {
-          resolve({ approved: !!response.result?.approved, feedback: response.result?.feedback });
-        } else {
-          resolve({ error: response.error || "Plannotator not available" });
-        }
-      },
-    });
-  });
-}
-
-function registerSpecifyReviewsTool(orchestrator: Orchestrator): void {
-  const pi = orchestrator.pi;
-
-  pi.registerTool({
-    name: "pp_specify_reviews",
-    label: "pi-pi",
-    description:
-      "Specify which repositories and commit ranges to open in Plannotator for code review. " +
-      "Called when the user requests a Plannotator code review. " +
-      "Plannotator will open sequentially for each entry. Results are returned after all reviews complete. " +
-      "Range supports both 'base..HEAD' and 'base..target' (non-HEAD target is reviewed via temporary worktree checkout).",
-    parameters: Type.Object({
-      reviews: Type.Array(Type.Object({
-        cwd: Type.String({ description: "Absolute path to the git repository" }),
-        range: Type.String({ description: "Git commit range, e.g. 'origin/main..HEAD', 'abc123..def456', 'HEAD~3..HEAD'" }),
-      })),
-    }),
-    async execute(_toolCallId, params: any, _signal, _onUpdate, ctx) {
-      if (orchestrator.active && getEffectiveMode(orchestrator.active.state) === "autonomous") {
-        return { content: [{ type: "text" as const, text: "Plannotator review is not available in autonomous mode. Continue with automated reviews via pp_phase_complete." }], isError: true as const, details: {} };
-      }
-      if (!params.reviews || params.reviews.length === 0) {
-        return { content: [{ type: "text" as const, text: "No reviews specified." }], isError: true as const, details: {} };
-      }
-
-      const results: string[] = [];
-      let hasNeedsChanges = false;
-      for (const review of params.reviews) {
-        ctx.ui?.setWorkingMessage?.(`Waiting for Plannotator review: ${review.range}…`);
-        const range = String(review.range ?? "").trim();
-        let compareBase = range;
-        let compareTarget = "HEAD";
-        const rangeSeparatorIdx = range.indexOf("..");
-        if (rangeSeparatorIdx >= 0) {
-          compareBase = range.slice(0, rangeSeparatorIdx).trim();
-          compareTarget = range.slice(rangeSeparatorIdx + 2).trim() || "HEAD";
-        }
-
-        if (!compareBase) {
-          results.push(`${review.cwd} (${review.range}): Invalid range (missing base).`);
-          continue;
-        }
-
-        let reviewCwd = review.cwd;
-        let tempWorktreePath: string | null = null;
-        let tempWorktreeParent: string | null = null;
-        let setupError: string | null = null;
-
-        if (compareTarget !== "HEAD") {
-          tempWorktreeParent = mkdtempSync(join(tmpdir(), "pi-pi-review-worktree-"));
-          tempWorktreePath = join(tempWorktreeParent, "checkout");
-          try {
-            const addResult = await pi.exec("git", ["worktree", "add", "--detach", tempWorktreePath, compareTarget], {
-              cwd: review.cwd,
-              timeout: 20000,
-            });
-            if (addResult.code !== 0) {
-              setupError = addResult.stderr?.trim() || addResult.stdout?.trim() || "Failed to prepare temporary worktree";
-            } else {
-              reviewCwd = tempWorktreePath;
-            }
-          } catch (error: any) {
-            setupError = error?.message ?? String(error);
-          }
-        }
-
-        if (setupError) {
-          results.push(`${review.cwd} (${review.range}): ${setupError}`);
-          if (tempWorktreePath) {
-            try {
-              await pi.exec("git", ["worktree", "remove", "--force", tempWorktreePath], {
-                cwd: review.cwd,
-                timeout: 20000,
-              });
-            } catch {}
-          }
-          if (tempWorktreePath) {
-            try {
-              rmSync(tempWorktreePath, { recursive: true, force: true });
-            } catch {}
-          }
-          if (tempWorktreeParent) {
-            try {
-              rmSync(tempWorktreeParent, { recursive: true, force: true });
-            } catch {}
-          }
-          continue;
-        }
-
-        const result = await openCodeReviewDirect(pi, {
-          cwd: reviewCwd,
-          diffType: "branch",
-          defaultBranch: compareBase,
-        });
-
-        if (tempWorktreePath) {
-          try {
-            await pi.exec("git", ["worktree", "remove", "--force", tempWorktreePath], {
-              cwd: review.cwd,
-              timeout: 20000,
-            });
-          } catch {}
-          try {
-            rmSync(tempWorktreePath, { recursive: true, force: true });
-          } catch {}
-          if (tempWorktreeParent) {
-            try {
-              rmSync(tempWorktreeParent, { recursive: true, force: true });
-            } catch {}
-          }
-        }
-
-        if ("error" in result) {
-          results.push(`${review.cwd} (${review.range}): ${result.error}`);
-        } else {
-          const status = result.approved ? "APPROVED" : "NEEDS_CHANGES";
-          if (!result.approved) hasNeedsChanges = true;
-          const feedback = result.feedback ? `\nFeedback: ${result.feedback}` : "";
-          results.push(`${review.cwd} (${review.range}): ${status}${feedback}`);
-        }
-      }
-      ctx.ui?.setWorkingMessage?.();
-
-      const summary = results.join("\n\n");
-
-      if (hasNeedsChanges) {
-        if (orchestrator.active) {
-          orchestrator.active.state.step = "llm_work";
-          saveTask(orchestrator.active.dir, orchestrator.active.state);
-        }
-        return {
-          content: [{ type: "text" as const, text: `Plannotator review complete.\n\n${summary}\n\nAddress 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.` }],
-          details: {},
-        };
-      }
-
-      ctx.ui?.setWorkingMessage?.("Waiting for user input…");
-      try {
-        const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
-        const text = await showActiveTaskMenu(orchestrator, ctx, `Plannotator review complete.\n\n${summary}`, "tool");
-        // Deliberate user ESC: stop the turn cleanly (mirror ask_user), no
-        // reminder text that would start a new LLM turn.
-        if (text === USER_CANCELLED) {
-          ctx.abort?.();
-          return { content: [{ type: "text" as const, text: "" }], details: {} };
-        }
-        // A transition may have started while the menu was open. The controller
-        // is the source of truth; abort the agent's pending turn so it doesn't
-        // race the transition. (Interactive-UX abort — stays local, not routed.)
-        if (!orchestrator.transitionController.isRunning()) {
-          ctx.abort?.();
-          return { content: [{ type: "text" as const, text: "" }], details: {} };
-        }
-        if (!text) {
-          return { content: [{ type: "text" as const, text: "User dismissed the menu. Wait for the user's next message. When you resume work, update USER_REQUEST.md and RESEARCH.md with any new findings before calling pp_phase_complete." }], details: {} };
-        }
-        return { content: [{ type: "text" as const, text }], details: {} };
-      } finally {
-        ctx.ui?.setWorkingMessage?.();
-      }
-    },
-  });
-}
-
 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);
@@ -915,6 +942,33 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
           }
         }
 
+        // Terminal handoff (#1): an autonomous IMPLEMENT phase whose next phase is
+        // "done" should NOT auto-complete. Run afterImplement (transitionToNextPhase
+        // is skipped here, so run it explicitly — once), then open the GUIDED
+        // implement menu and wait, instead of tearing the task down.
+        if (phase === "implement" && nextPhase(orchestrator.active.type, phase) === "done") {
+          if (!orchestrator.active.state.afterImplementRan) {
+            const afterError = runAfterImplementForActive(orchestrator);
+            if (afterError) {
+              return { content: [{ type: "text" as const, text: `${afterError}\n\nDo NOT wait for the user — fix these and call pp_phase_complete again.` }], details: {} };
+            }
+            orchestrator.active.state.afterImplementRan = true;
+            saveTask(orchestrator.active.dir, orchestrator.active.state);
+          }
+          ctx.ui.setWorkingMessage?.("Waiting for user approval…");
+          try {
+            const { showActiveTaskMenu, USER_CANCELLED } = await import("./pp-menu.js");
+            const text = await showActiveTaskMenu(orchestrator, ctx, params.summary, "tool", true);
+            if (text === USER_CANCELLED) {
+              ctx.abort?.();
+              return { content: [{ type: "text" as const, text: "" }], details: {} };
+            }
+            return { content: [{ type: "text" as const, text: text ?? "" }], details: {} };
+          } finally {
+            ctx.ui.setWorkingMessage?.();
+          }
+        }
+
         const plannerPreset = orchestrator.active.state.autonomousConfig?.phases?.plan?.plannerPreset;
         const result = await orchestrator.transitionToNextPhase(ctx, plannerPreset);
         if (!result.ok) {
@@ -989,31 +1043,49 @@ function registerMainTraceHooks(orchestrator: Orchestrator): void {
     tracer?.traceMain("turn_end", { turnIndex: event.turnIndex, message: event.message, toolResults: event.toolResults });
   });
   pi.on("message_start", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("message_start", { turnIndex: tracer.turnIndex, message: event.message });
   });
   pi.on("message_update", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("message_update", { turnIndex: tracer.turnIndex, assistantMessageEvent: event.assistantMessageEvent });
   });
   pi.on("message_end", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("message_end", { turnIndex: tracer.turnIndex, message: event.message });
   });
   pi.on("tool_execution_start", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("tool_execution_start", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, args: event.args });
   });
   pi.on("tool_execution_update", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("tool_execution_update", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, args: event.args, partialResult: event.partialResult });
   });
   pi.on("tool_execution_end", async (event) => {
+    markMainTurnActivity(orchestrator);
     const tracer = getTracer();
     tracer?.traceMain("tool_execution_end", { turnIndex: tracer.turnIndex, toolCallId: event.toolCallId, toolName: event.toolName, result: event.result, isError: event.isError });
   });
 }
 
+// Main-turn watchdog activity helpers (BUG-2). Kept module-level so they can be
+// called from the several existing main-session handlers without registering a
+// second handler per event.
+function markMainTurnActivity(orchestrator: Orchestrator): void {
+  orchestrator.mainTurnLastActivity = Date.now();
+}
+
+function endMainTurn(orchestrator: Orchestrator): void {
+  orchestrator.mainTurnInFlight = false;
+  orchestrator.mainTurnRecovering = false;
+}
+
 export function registerEventHandlers(orchestrator: Orchestrator): void {
   const pi = orchestrator.pi;
 
@@ -1044,6 +1116,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
   // the subagent branch, so these only ever see root-session events.
   pi.on("agent_end", async (_event, ctx) => {
     if (ctx) orchestrator.lastCtx = ctx;
+    endMainTurn(orchestrator);
     orchestrator.transitionController.onAgentEnd();
   });
   pi.on("session_compact", async (_event, ctx) => {
@@ -1051,6 +1124,65 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     orchestrator.transitionController.onSessionCompact();
   });
 
+  // BUG-2: main-turn stall watchdog. A main turn can start (turn_start / manual
+  // "continue" / SDK auto-retry) and then wedge with no terminal turn_end, so the
+  // session sits "Working…" forever with nothing to recover it (the SDK-retryable
+  // deferral below arms nothing, and startStaleAgentWatchdog only watches
+  // subagents). Activity is marked from the existing main-session handlers
+  // (turn_start below, tool_call, tool_result, turn_end) so we do NOT register a
+  // second handler per event (the runtime allows it, but keeping one owner per
+  // event is simpler and test-mock-friendly). When a turn is in flight with NO
+  // activity beyond the configured threshold, abort + recover via the idle-gated
+  // single-send path so recovery can't itself race into "Agent is already
+  // processing".
+  const startMainTurnWatchdog = () => {
+    if (orchestrator.mainTurnTimer) return;
+    orchestrator.mainTurnTimer = setInterval(() => {
+      if (!orchestrator.active) {
+        clearInterval(orchestrator.mainTurnTimer!);
+        orchestrator.mainTurnTimer = null;
+        return;
+      }
+      if (!orchestrator.mainTurnInFlight || orchestrator.mainTurnRecovering) return;
+      // Only a genuinely stuck turn is a target: an idle session (turn already
+      // settled), an in-progress transition, or an await_* step is not a stall.
+      if (orchestrator.transitionController.isTransitioning()) return;
+      const step = orchestrator.active.state.step;
+      if (step === "await_planners" || step === "await_reviewers") return;
+      // A turn parked on an open user-facing dialogue (ask_user / the /pp menu /
+      // any interactive selectOption / the rate-limit fallback switch) is
+      // user-gated, not wedged — do not abort it out from under the user.
+      if (orchestrator.interactivePromptOpen || orchestrator.subFallbackDialogPending) return;
+      const staleMs = orchestrator.config.performance.internals.mainTurnStale;
+      if (Date.now() - orchestrator.mainTurnLastActivity <= staleMs) return;
+
+      orchestrator.mainTurnRecovering = true;
+      const taskToken = orchestrator.activeTaskToken;
+      const phase = orchestrator.active.state.phase;
+      getLogger().warn({ s: "watchdog", phase, staleMs }, "main turn wedged — aborting and recovering");
+      orchestrator.lastCtx?.ui?.notify?.(
+        `Main turn stalled with no activity for ${Math.round(staleMs / 1000)}s — recovering.`,
+        "warning",
+      );
+      try {
+        orchestrator.transitionController.abortMainAgent(orchestrator.lastCtx?.abort?.bind(orchestrator.lastCtx));
+      } catch {}
+      orchestrator.mainTurnInFlight = false;
+      orchestrator.sendUserMessageWhenIdle(
+        `[PI-PI] The previous turn stalled without completing. Continue working on the current phase (${phase}).`,
+        taskToken,
+      );
+    }, 30000);
+  };
+
+  pi.on("turn_start", async (_event, ctx) => {
+    if (ctx) orchestrator.lastCtx = ctx;
+    orchestrator.mainTurnInFlight = true;
+    orchestrator.mainTurnRecovering = false;
+    markMainTurnActivity(orchestrator);
+    startMainTurnWatchdog();
+  });
+
   // Expose the event-driven planner-completion check so initial plan-entry
   // spawns (in command-handlers / orchestrator) can wire it as their onSettled
   // safety net (the deleted poller's former role). checkPlannerCompletion is a
@@ -1168,7 +1300,12 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (data.description) {
       orchestrator.agentDescriptions.set(data.id, data.description);
     }
+
     trackSubagentEvent(data, "created");
+    // Nudge acceptance/suppression is driven from the root `Agent` tool-call observation
+    // (main-initiated by construction), NOT here — this event also fires for lineage-less
+    // nested spawns, which must not count as the main agent following a nudge.
+
     startStaleAgentWatchdog();
     const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
     mgr?.refreshWidget?.(orchestrator.lastCtx?.ui);
@@ -1214,7 +1351,14 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
     const failedPlannerVariants = [...orchestrator.failedPlannerVariants];
     const effectiveMode = getEffectiveMode(orchestrator.active.state);
-    if (effectiveMode === "autonomous" && failedPlannerVariants.length > 0) {
+    // Do NOT auto-retry failed variants while a subscription-429 fallback decision
+    // is in flight: re-spawning now would use the still-sub-routed model and
+    // re-hit the limit. Once the user decides, the fallback nudge re-drives this.
+    if (
+      effectiveMode === "autonomous" &&
+      failedPlannerVariants.length > 0 &&
+      !orchestrator.subFallbackPendingDecision
+    ) {
       const alreadyRetried = orchestrator.active.state.plannerFailureAutoRetried === true;
       if (!alreadyRetried) {
         const failedSet = new Set(failedPlannerVariants);
@@ -1386,7 +1530,13 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
 
     const failedReviewerVariants = [...orchestrator.failedReviewerVariants];
     const effectiveMode = getEffectiveMode(orchestrator.active.state);
-    if (effectiveMode === "autonomous" && failedReviewerVariants.length > 0) {
+    // See the planner path: suppress auto-retry while a sub-429 fallback decision
+    // is pending so we don't re-spawn on the still-sub-routed model.
+    if (
+      effectiveMode === "autonomous" &&
+      failedReviewerVariants.length > 0 &&
+      !orchestrator.subFallbackPendingDecision
+    ) {
       const cycle = orchestrator.active.state.reviewCycle;
       const phase = orchestrator.active.state.phase;
       const outputs = loadPhaseReviewOutputs(orchestrator.active.dir, phase, cycle.pass);
@@ -1641,6 +1791,23 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.abortAllSubagents();
     }
 
+    // Subscription rate-limit (429) on a sub-routed subagent: offer the ONE
+    // global switch-to-non-sub dialogue (never per-subagent). subagents:failed
+    // carries the subagent's resolved model id.
+    const failedModelId = typeof data.modelId === "string" ? data.modelId : undefined;
+    const subRateLimited =
+      isRateLimitError(data.error) &&
+      isSubscriptionRouted(failedModelId) &&
+      !orchestrator.subFallbackActive;
+    if (subRateLimited) {
+      // Set the decision-pending flag SYNCHRONOUSLY (before the completion checks
+      // below) so the autonomous planner/reviewer auto-retry does NOT re-spawn
+      // the failed variant on the still-sub-routed model while the fallback
+      // dialogue is in flight.
+      orchestrator.subFallbackPendingDecision = true;
+      void handleSubagentRateLimit(orchestrator, orchestrator.lastCtx, failedModelId);
+    }
+
     orchestrator.transitionController.sendCustom(
       {
         customType: "pp-subagent-error",
@@ -1725,6 +1892,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       (globalThis as any)[USAGE_TRACKER_KEY] = tracker;
       setFooterContext(ctx);
       setFooterTracker(tracker);
+      setFooterOrchestrator(orchestrator);
       ctx.ui.setFooter(createCustomFooter);
     }
 
@@ -1810,6 +1978,30 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (orchestrator.transitionController.gateAgentStart(() => ctx.abort())) {
       return;
     }
+
+    // Stale continuation-nudge guard. A `[PI-PI] Continue the <phase> phase…`
+    // nudge is a followUp queued at turn_end; by the time it is delivered the
+    // phase may have advanced (plan→implement) or the task may have changed
+    // (old plan-task → new plan-task). Re-validate against the phase/token
+    // captured at generation time and abort the turn on any mismatch — a stale
+    // nudge is not genuine user re-engagement, so this runs BEFORE the no-active
+    // early return and does NOT clear the nudge/error guards. Checked only for
+    // the tracked "Continue the <phase> phase" shape; other [PI-PI] handoffs are
+    // untouched.
+    const nudgeMeta = orchestrator.pendingNudges.get(event.prompt ?? "");
+    if (nudgeMeta !== undefined) {
+      orchestrator.pendingNudges.delete(event.prompt ?? "");
+      const livePhase = orchestrator.active?.state.phase;
+      if (!orchestrator.active || nudgeMeta.phase !== livePhase || nudgeMeta.taskToken !== orchestrator.activeTaskToken) {
+        getLogger().debug(
+          { s: "hook", hook: "before_agent_start", nudgePhase: nudgeMeta.phase, livePhase, nudgeToken: nudgeMeta.taskToken, liveToken: orchestrator.activeTaskToken },
+          "dropping stale continuation nudge",
+        );
+        ctx.abort();
+        return;
+      }
+    }
+
     if (!orchestrator.active || orchestrator.active.state.phase === "done") return;
 
     // Clear the nudge guard ONLY on a genuine user re-engagement. Controller-
@@ -1821,6 +2013,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (!isControllerInjected) {
       orchestrator.nudgeHalted = false;
       orchestrator.consecutiveNudges = 0;
+      // Genuine user re-engagement also clears the API-error retry halt, so a
+      // fresh request can auto-retry again from a clean counter.
+      orchestrator.errorNudgeHalted = false;
+      orchestrator.errorRetryCount = 0;
     }
     orchestrator.updateStatus(ctx);
 
@@ -1839,6 +2035,11 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     const projectContext = systemSnippets
       ? ["<project_context>", systemSnippets, "</project_context>"].join("\n")
       : "";
+    const agentsMdPath = join(orchestrator.cwd, "AGENTS.md");
+    const agentsMd =
+      orchestrator.config.general.injectAgentsMd && existsSync(agentsMdPath)
+        ? [`<agents_md source="${agentsMdPath}">`, readFileSync(agentsMdPath, "utf-8"), "</agents_md>"].join("\n")
+        : "";
     const checklistLine =
       phase === "implement" ? "Keep the plan checklist current: mark each item done (- [ ] → - [x]) as you complete it." : "";
     const taskBlock = [
@@ -1855,7 +2056,9 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       constraintsBlock(phase as Phase, effectiveMode),
       PRINCIPLES_BLOCK,
       TOOLS_BLOCK,
+      DELEGATION_BLOCK,
       projectContext,
+      agentsMd,
       taskBlock,
     ]
       .filter(Boolean)
@@ -1867,6 +2070,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
   });
 
   pi.on("tool_call", async (event, _ctx) => {
+    markMainTurnActivity(orchestrator);
     getLogger().debug({ s: "hook", hook: "tool_call", tool: event.toolName }, "tool call");
     if (event.toolName === "ask_user" && orchestrator.active) {
       if (getEffectivePhaseMode(orchestrator.active.state) === "autonomous") {
@@ -1877,24 +2081,29 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     if (event.toolName === "Agent" && orchestrator.active) {
       const input = event.input as Record<string, unknown>;
       const requestedType = ((input.subagent_type as string) || "").toLowerCase();
+      const validTypes = ["explore", "librarian", "task", "advisor", "deep-debugger", "reviewer"];
       if (!requestedType) {
-        return { block: true, reason: "subagent_type is required. Use Explore for codebase research, Librarian for external docs, or Task for implementation subtasks." };
+        return { block: true, reason: "subagent_type is required. Valid types: explore (codebase research), librarian (external docs), task (implementation subtask), advisor (design/'why is this broken' judgment), deep-debugger (hard persistent failures), reviewer (code review — only when the user explicitly asks)." };
       }
-      const isExplore = requestedType === "explore";
-      const isLibrarian = requestedType === "librarian";
-
-      if (isExplore) {
-        input.subagent_type = "explore";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.explore.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.explore.thinking;
-      } else if (isLibrarian) {
-        input.subagent_type = "librarian";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.librarian.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.librarian.thinking;
-      } else {
-        input.subagent_type = "task";
-        input.model = resolveModel(orchestrator.config.agents.subagents.simple.task.model);
-        input.thinking = orchestrator.config.agents.subagents.simple.task.thinking;
+      if (!validTypes.includes(requestedType)) {
+        return { block: true, reason: `Unknown subagent_type "${requestedType}". Valid types: ${validTypes.join(", ")}.` };
+      }
+
+      const simple = orchestrator.config.agents.subagents.simple;
+      const role = requestedType as keyof typeof simple;
+      input.subagent_type = requestedType;
+      input.model = resolveModel(simple[role].model);
+      input.thinking = simple[role].thinking;
+
+      // Spawn-time context injection: append USER_REQUEST + RESEARCH content and a
+      // path-aware manifest of on-demand documents to the LLM-supplied spawn prompt.
+      // explore/librarian intentionally get nothing (fast, scoped retrieval).
+      if (["task", "advisor", "deep-debugger", "reviewer"].includes(requestedType)) {
+        const contextBlock = buildSpawnContextBlock(orchestrator.active.dir);
+        if (contextBlock) {
+          const existingPrompt = typeof input.prompt === "string" ? input.prompt : "";
+          input.prompt = existingPrompt ? `${existingPrompt}\n\n${contextBlock}` : contextBlock;
+        }
       }
     }
 
@@ -1919,11 +2128,49 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       if (fileName === "config.json" && isPathInside(ppDir, resolvedPath)) {
         return { block: true, reason: "config.json is managed by the user, not the LLM" };
       }
+
+      // Review-phase read-only exception is scoped to AI_COMMENT markers: the main
+      // agent may only insert/remove `AI_COMMENT:` markers in source files. Enforce
+      // it at the gate (the constraint is otherwise prompt-level only): a source
+      // write/edit is allowed only when it changes nothing but AI_COMMENT markers.
+      // Publishing findings as file comments goes through this path.
+      if (
+        orchestrator.active?.state.phase === "review" &&
+        !isPathInside(ppDir, resolvedPath)
+      ) {
+        const denial = {
+          block: true as const,
+          reason: "Review phase is read-only except for inserting/removing AI_COMMENT: markers. This edit changes non-AI_COMMENT content — record the finding instead of applying a fix.",
+        };
+        if (event.toolName === "edit") {
+          const edits = Array.isArray((event.input as any)?.edits) ? (event.input as any).edits : [];
+          const legacy = event.input as any;
+          const allEdits = [
+            ...edits,
+            ...(typeof legacy?.oldText === "string" && typeof legacy?.newText === "string" ? [{ oldText: legacy.oldText, newText: legacy.newText }] : []),
+          ];
+          for (const e of allEdits) {
+            if (typeof e?.oldText !== "string" || typeof e?.newText !== "string") continue;
+            if (!isAiCommentOnlyChange(e.oldText, e.newText)) return denial;
+          }
+        } else {
+          // Anchoring inserts markers into EXISTING code; creating a new source
+          // file is never a valid AI_COMMENT-only operation.
+          if (!existsSync(resolvedPath)) return denial;
+          const newContent = typeof (event.input as any)?.content === "string" ? (event.input as any).content : "";
+          let before = "";
+          try {
+            before = readFileSync(resolvedPath, "utf-8");
+          } catch {}
+          if (!isAiCommentOnlyChange(before, newContent)) return denial;
+        }
+      }
     }
     return;
   });
 
   pi.on("tool_result", async (event, ctx) => {
+    markMainTurnActivity(orchestrator);
     // ESC in an ask_user dialogue must stop the LLM's turn (treat ESC as
     // "stop, I want to type"). Only a deliberate user cancel aborts — timeout
     // and programmatic signal-aborts carry a non-"user" reason and must not.
@@ -1992,6 +2239,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       orchestrator.active.modifiedFiles.add(resolvedWrite);
       orchestrator.active.state.modifiedFiles = [...orchestrator.active.modifiedFiles];
       orchestrator.active.state.reviewApprovedClean = false;
+      // New implement edits invalidate a prior afterImplement run (e.g. fixes made
+      // via the guided menu after the autonomous terminal handoff), so the hooks
+      // re-run and validate the final code on the next completion.
+      orchestrator.active.state.afterImplementRan = false;
       try { saveTask(orchestrator.active.dir, orchestrator.active.state); } catch {}
 
       const repos = orchestrator.active.state.repos ?? [];
@@ -2052,10 +2303,21 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     // so this works whether or not `active` is still set (done cleanup nulls it).
     if (transitioning) {
       const summary = orchestrator.transitionController.currentSummary() || "Phase transition in progress.";
+      // Task-boundary discard: keep NO verbatim transcript beyond the summary so
+      // the finished/replaced task cannot leak into the next task. Point
+      // firstKeptEntryId at the newest branch entry (nothing before it is kept
+      // verbatim). Phase transitions keep the default recent window so
+      // legitimate context carries forward.
+      const branchEntries = (event as any).branchEntries as Array<{ id: string }> | undefined;
+      const lastEntryId = branchEntries && branchEntries.length > 0 ? branchEntries[branchEntries.length - 1].id : undefined;
+      const firstKeptEntryId =
+        orchestrator.transitionController.isDiscardTransition() && lastEntryId
+          ? lastEntryId
+          : event.preparation.firstKeptEntryId;
       return {
         compaction: {
           summary,
-          firstKeptEntryId: event.preparation.firstKeptEntryId,
+          firstKeptEntryId,
           tokensBefore: event.preparation.tokensBefore,
         },
       };
@@ -2085,6 +2347,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
   });
 
   pi.on("turn_end", async (event, ctx) => {
+    // The turn produced a terminal event — it is no longer wedged. If the SDK
+    // auto-retries a retryable error it will emit a fresh turn_start, which
+    // re-arms the watchdog.
+    endMainTurn(orchestrator);
     const msg = event.message as any;
     const usageTracker = getUsageTracker();
     if (usageTracker && msg?.usage) {
@@ -2146,6 +2412,39 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         contentBlocks: msg.content?.length ?? 0,
         contentSummary,
       }, "turn ended with error");
+      // Subscription rate-limit (429) on a sub-routed main turn: retrying the
+      // same sub model is futile against an account-level limit. Offer a
+      // user-gated switch to non-sub Claude instead of the generic backoff.
+      const activeModelId = (typeof msg.model === "string" && msg.model) || ctx.model?.id;
+      const activeProvider = (typeof msg.provider === "string" && msg.provider) || ctx.model?.provider;
+      if (
+        isRateLimitError(errorMsg) &&
+        isSubscriptionRouted(activeModelId, activeProvider) &&
+        !orchestrator.subFallbackActive
+      ) {
+        void handleMainRateLimit(orchestrator, ctx, activeModelId, activeProvider);
+        return;
+      }
+      // The SDK already auto-retries this class of error itself (abortable
+      // backoff bound to ESC, continuing the SAME turn). Running pi-pi's OWN
+      // independent retry on top would double-fire: its followUp races the SDK's
+      // continue() into "Agent is already processing", and it re-nudges a still-
+      // failing model. So for SDK-retryable errors we defer entirely to the SDK
+      // and do nothing here. pi-pi's own idle-gated retry remains only as the
+      // fallback for errors the SDK does NOT retry.
+      if (isSdkRetryableError(errorMsg)) {
+        getLogger().debug({ s: "turn", err: errorMsg }, "deferring to SDK auto-retry; pi-pi retry skipped");
+        return;
+      }
+      // Halt guard: once the consecutive-error cap is exceeded we stop auto-
+      // retrying until the user re-engages. errorRetryCount is NO LONGER reset on
+      // benign intervening turns (see below) — otherwise a retried turn that ends
+      // as a harmless text-only reply would reset the counter and the cap could
+      // never accumulate, letting transient errors nudge unbounded.
+      if (orchestrator.errorNudgeHalted) {
+        getLogger().debug({ s: "turn", err: errorMsg }, "error auto-retry halted; awaiting user re-engagement");
+        return;
+      }
       orchestrator.errorRetryCount = (orchestrator.errorRetryCount ?? 0) + 1;
       const maxRetries = 5;
       if (orchestrator.errorRetryCount <= maxRetries) {
@@ -2153,18 +2452,44 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
         ctx.ui.notify(`API error (attempt ${orchestrator.errorRetryCount}/${maxRetries}): ${errorMsg}. Retrying in ${delay / 1000}s...`, "warning");
         const taskToken = orchestrator.activeTaskToken;
         if (orchestrator.pendingRetryTimer) clearTimeout(orchestrator.pendingRetryTimer);
+        // Arm a direct ESC interrupt for this retry window — no SDK/interactive
+        // binding covers pi-pi's own timer (the turn already ended in error).
+        orchestrator.armRetryEscInterrupt(ctx);
         orchestrator.pendingRetryTimer = setTimeout(() => {
           orchestrator.pendingRetryTimer = null;
-          if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) return;
-          orchestrator.safeSendUserMessage(`[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`);
+          if (orchestrator.activeTaskToken !== taskToken || !orchestrator.active) {
+            orchestrator.disarmRetryEscInterrupt();
+            return;
+          }
+          // Defer until the main session is idle: sending a followUp while the SDK
+          // still has an active run throws an async, runtime-swallowed "Agent is
+          // already processing" error. sendUserMessageWhenIdle polls (reusing
+          // pendingRetryTimer so ESC/abort still cancels) and disarms the ESC hook
+          // once delivered.
+          orchestrator.sendUserMessageWhenIdle(
+            `[PI-PI] Previous request failed due to an API error. Continue working on the current phase (${phase}).`,
+            taskToken,
+          );
         }, delay);
       } else {
-        ctx.ui.notify(`API error persisted after ${maxRetries} retries: ${errorMsg}. Stopping auto-retry.`, "error");
-        orchestrator.errorRetryCount = 0;
+        ctx.ui.notify(`API error persisted after ${maxRetries} retries: ${errorMsg}. Stopping auto-retry — send any message to resume.`, "error");
+        // Halt (do NOT reset the counter) so no further error turn re-arms a retry
+        // until the user re-engages. cancelPendingRetry would reset the count and
+        // re-open the floodgate, so only clear the live timer/ESC hook here.
+        orchestrator.errorNudgeHalted = true;
+        if (orchestrator.pendingRetryTimer) {
+          clearTimeout(orchestrator.pendingRetryTimer);
+          orchestrator.pendingRetryTimer = null;
+        }
+        orchestrator.disarmRetryEscInterrupt();
       }
       return;
     }
-    orchestrator.errorRetryCount = 0;
+    // NOTE: errorRetryCount is intentionally NOT reset here. Resetting on every
+    // non-error turn let a benign nudge-induced turn zero the counter, defeating
+    // the maxRetries cap and allowing unbounded error nudges. The counter is
+    // reset only on genuine user re-engagement (before_agent_start) and on task
+    // reset / cancelPendingRetry.
 
     if ((globalThis as any)[SUBAGENT_SESSION_KEY]) {
       return;
@@ -2229,6 +2554,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     const nudge = isAutonomous
       ? `[PI-PI] Continue the ${phase} phase. ${phaseConstraint(phase as Phase)} If the phase's objectives are met, call pp_phase_complete now; otherwise call the next tool. Do NOT apologize or reply with text only — respond with a tool call.`
       : `[PI-PI] Continue the ${phase} phase where you left off.`;
+    // Record the nudge's phase/task at generation time so a delivery that lands
+    // after the phase advanced or the task changed can be dropped (the queued
+    // followUp string itself carries no token).
+    orchestrator.pendingNudges.set(nudge, { phase: phase as Phase, taskToken: orchestrator.activeTaskToken });
     orchestrator.safeSendUserMessage(nudge);
   });