@ilya-lesikov/pi-pi 0.8.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";
@@ -25,8 +24,9 @@ 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";
@@ -34,11 +34,11 @@ 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 { 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";
@@ -121,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(
@@ -318,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;
@@ -411,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;
@@ -448,14 +464,176 @@ 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 {
   const pi = orchestrator.pi;
 
@@ -595,190 +773,6 @@ function registerRepoTool(orchestrator: Orchestrator): void {
   });
 }
 
-async function openCodeReviewDirect(
-  orchestrator: Orchestrator,
-  payload: Record<string, unknown>,
-): Promise<{ approved: boolean; feedback?: string } | { error: string }> {
-  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", payload);
-  if (!opened) {
-    return { error: "Plannotator not available" };
-  }
-  let result: { approved: boolean; feedback?: string; error?: string };
-  try {
-    result = await waitForPlannotatorResult(orchestrator, reviewId, null);
-  } catch (err) {
-    return { error: err instanceof Error ? err.message : "Plannotator review failed" };
-  }
-  if (result.error) {
-    return { error: result.error };
-  }
-  return { approved: result.approved, feedback: result.feedback };
-}
-
-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(orchestrator, {
-          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);
@@ -948,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) {
@@ -1022,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;
 
@@ -1077,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) => {
@@ -1084,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
@@ -1203,6 +1302,10 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     }
 
     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);
@@ -1789,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);
     }
 
@@ -1874,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-
@@ -1907,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 = [
@@ -1925,6 +2058,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       TOOLS_BLOCK,
       DELEGATION_BLOCK,
       projectContext,
+      agentsMd,
       taskBlock,
     ]
       .filter(Boolean)
@@ -1936,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") {
@@ -1993,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.
@@ -2066,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 ?? [];
@@ -2126,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,
         },
       };
@@ -2159,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) {
@@ -2362,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);
   });