@ilya-lesikov/pi-pi 0.8.0 → 0.9.0

package/extensions/orchestrator/config.ts

@@ -43,6 +43,7 @@ export interface AfterImplementCommandConfig {
 export interface PiPiConfig {
   general: {
     autoCommit: boolean;
+    injectAgentsMd: boolean;
     loadExtraRepoConfigs: boolean;
     logLevel: LogLevel;
     tracing: boolean;
@@ -65,6 +66,7 @@ export interface PiPiConfig {
     };
     internals: {
       subagentStale: DurationValue;
+      mainTurnStale: DurationValue;
       taskLockStale: DurationValue;
       taskLockRefresh: DurationValue;
     };
@@ -79,6 +81,7 @@ export interface NormalizedPiPiConfig extends PiPiConfig {
     };
     internals: {
       subagentStale: number;
+      mainTurnStale: number;
       taskLockStale: number;
       taskLockRefresh: number;
     };
@@ -97,6 +100,7 @@ const SIMPLE_SUBAGENT_ROLES: SimpleSubagentRole[] = ["explore", "librarian", "ta
 const DEFAULT_CONFIG: PiPiConfig = {
   general: {
     autoCommit: true,
+    injectAgentsMd: true,
     loadExtraRepoConfigs: true,
     logLevel: "info",
     tracing: false,
@@ -203,6 +207,7 @@ const DEFAULT_CONFIG: PiPiConfig = {
     },
     internals: {
       subagentStale: "5m",
+      mainTurnStale: "10m",
       taskLockStale: "1m",
       taskLockRefresh: "30s",
     },
@@ -347,6 +352,7 @@ export function validateConfig(config: Record<string, any>): void {
   if (config.general !== undefined) {
     const general = requireObject(config.general, "config.general");
     ensureBool(general.autoCommit, "config.general.autoCommit");
+    ensureBool(general.injectAgentsMd, "config.general.injectAgentsMd");
     ensureBool(general.loadExtraRepoConfigs, "config.general.loadExtraRepoConfigs");
     ensureBool(general.tracing, "config.general.tracing");
     if (general.logLevel !== undefined && !isValidLogLevel(general.logLevel)) {
@@ -417,6 +423,7 @@ export function validateConfig(config: Record<string, any>): void {
     if (performance.internals !== undefined) {
       const internals = requireObject(performance.internals, "config.performance.internals");
       ensureDuration(internals.subagentStale, "config.performance.internals.subagentStale");
+      ensureDuration(internals.mainTurnStale, "config.performance.internals.mainTurnStale");
       ensureDuration(internals.taskLockStale, "config.performance.internals.taskLockStale");
       ensureDuration(internals.taskLockRefresh, "config.performance.internals.taskLockRefresh");
     }
@@ -526,6 +533,9 @@ export function validateMergedConfig(config: Record<string, any>): void {
   if (parseDuration(typed.performance.internals.subagentStale) === null) {
     throw new Error("config.performance.internals.subagentStale must be a valid duration");
   }
+  if (parseDuration(typed.performance.internals.mainTurnStale) === null) {
+    throw new Error("config.performance.internals.mainTurnStale must be a valid duration");
+  }
   if (parseDuration(typed.performance.internals.taskLockStale) === null) {
     throw new Error("config.performance.internals.taskLockStale must be a valid duration");
   }
@@ -540,6 +550,7 @@ export function normalizeConfigDurations(config: PiPiConfig): NormalizedPiPiConf
   const afterEdit = parseDuration(next.performance.commands.afterEdit);
   const afterImplement = parseDuration(next.performance.commands.afterImplement);
   const subagentStale = parseDuration(next.performance.internals.subagentStale);
+  const mainTurnStale = parseDuration(next.performance.internals.mainTurnStale);
   const taskLockStale = parseDuration(next.performance.internals.taskLockStale);
   const taskLockRefresh = parseDuration(next.performance.internals.taskLockRefresh);
 
@@ -547,6 +558,7 @@ export function normalizeConfigDurations(config: PiPiConfig): NormalizedPiPiConf
     afterEdit === null ||
     afterImplement === null ||
     subagentStale === null ||
+    mainTurnStale === null ||
     taskLockStale === null ||
     taskLockRefresh === null
   ) {
@@ -556,6 +568,7 @@ export function normalizeConfigDurations(config: PiPiConfig): NormalizedPiPiConf
   next.performance.commands.afterEdit = afterEdit;
   next.performance.commands.afterImplement = afterImplement;
   next.performance.internals.subagentStale = subagentStale;
+  next.performance.internals.mainTurnStale = mainTurnStale;
   next.performance.internals.taskLockStale = taskLockStale;
   next.performance.internals.taskLockRefresh = taskLockRefresh;
   return next;

package/extensions/orchestrator/context.ts

@@ -279,6 +279,22 @@ export function getLatestSynthesizedPlan(taskDir: string): string | null {
   return readFileSync(join(plansDir, synthFiles[synthFiles.length - 1]), "utf-8");
 }
 
+// True when the newest `code-reviews/*_final_pass-*.md` exists and carries an
+// `ANCHORS:` block. Shared by publishGuard (Publish menu) and the review-phase
+// completion gates so a review cannot finish without the deliverable Publish
+// consumes. A zero-findings `ANCHORS: (none)` still satisfies this (the line exists).
+export function hasFinalPassAnchors(taskDir: string): boolean {
+  const reviewsDir = join(taskDir, "code-reviews");
+  if (!existsSync(reviewsDir)) return false;
+  const finalPassFiles = readdirSync(reviewsDir)
+    .filter((f) => f.endsWith(".md") && f.includes("_final_pass-"))
+    .sort();
+  if (finalPassFiles.length === 0) return false;
+  const latest = finalPassFiles[finalPassFiles.length - 1];
+  const content = readFileSync(join(reviewsDir, latest), "utf8");
+  return /^ANCHORS:/m.test(content);
+}
+
 function getLatestSynthesizedPlanPath(taskDir: string): string | null {
   const plansDir = join(taskDir, "plans");
   if (!existsSync(plansDir)) return null;

package/extensions/orchestrator/custom-footer.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { createCustomFooter, setFooterContext, setFooterTracker, setFooterOrchestrator } from "./custom-footer.js";
+
+const theme = { fg: (_color: string, text: string) => text } as any;
+const footerData = { getGitBranch: () => "main" } as any;
+
+function render(width = 200): string[] {
+  const footer = createCustomFooter({} as any, theme, footerData);
+  return footer.render(width);
+}
+
+function makeCtx(usage?: { tokens: number | null; contextWindow: number; percent: number | null }): any {
+  return {
+    cwd: "/tmp/project",
+    model: { id: "test-model", provider: "test" },
+    sessionManager: { getSessionName: () => undefined, getEntries: () => [] },
+    getContextUsage: () => usage,
+  };
+}
+
+describe("createCustomFooter", () => {
+  beforeEach(() => {
+    setFooterTracker(undefined as any);
+    setFooterOrchestrator(undefined as any);
+  });
+
+  it("renders exactly two lines (no status/LSP line)", () => {
+    setFooterContext(makeCtx());
+    const lines = render();
+    expect(lines).toHaveLength(2);
+  });
+
+  it("line 1 shows task/phase/mode when a task is active", () => {
+    setFooterContext(makeCtx());
+    setFooterOrchestrator({
+      active: { type: "implement", state: { phase: "plan", mode: "autonomous" } },
+    } as any);
+    const [line1] = render();
+    expect(line1).toContain("task: implement");
+    expect(line1).toContain("phase: plan");
+    expect(line1).toContain("mode: autonomous");
+  });
+
+  it("line 1 shows autonomous mode in a read-only phase for an autonomous task", () => {
+    setFooterContext(makeCtx());
+    setFooterOrchestrator({
+      active: { type: "implement", state: { phase: "brainstorm", mode: "autonomous" } },
+    } as any);
+    const [line1] = render();
+    expect(line1).toContain("phase: brainstorm");
+    expect(line1).toContain("mode: autonomous");
+  });
+
+  it("line 1 shows guided mode for a guided task", () => {
+    setFooterContext(makeCtx());
+    setFooterOrchestrator({
+      active: { type: "implement", state: { phase: "implement", mode: "guided" } },
+    } as any);
+    const [line1] = render();
+    expect(line1).toContain("mode: guided");
+  });
+
+  it("line 1 omits the mode segment for a quick task", () => {
+    setFooterContext(makeCtx());
+    setFooterOrchestrator({
+      active: { type: "quick", state: { phase: "quick", mode: "autonomous" } },
+    } as any);
+    const [line1] = render();
+    expect(line1).toContain("task: quick");
+    expect(line1).not.toContain("mode:");
+  });
+
+  it("line 1 omits task metadata when no task is active", () => {
+    setFooterContext(makeCtx());
+    const [line1] = render();
+    expect(line1).not.toContain("task:");
+    expect(line1).toContain("main");
+  });
+
+  it("context indicator shows percent/used/max", () => {
+    setFooterContext(makeCtx({ tokens: 38000, contextWindow: 1000000, percent: 3.8 }));
+    const [, line2] = render();
+    expect(line2).toContain("3.8%/38k/1.0M (auto)");
+  });
+
+  it("context indicator degrades gracefully when tokens are null", () => {
+    setFooterContext(makeCtx({ tokens: null, contextWindow: 1000000, percent: null }));
+    const [, line2] = render();
+    expect(line2).toContain("?%/?/1.0M (auto)");
+  });
+});

package/extensions/orchestrator/custom-footer.ts

@@ -2,9 +2,12 @@ import { homedir } from "node:os";
 import type { ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, type Component, type TUI } from "@earendil-works/pi-tui";
 import type { UsageTracker } from "./usage-tracker.js";
+import type { Orchestrator } from "./orchestrator.js";
+import { formatModeIndicator } from "./state.js";
 
 let footerCtx: ExtensionContext | undefined;
 let footerTracker: UsageTracker | undefined;
+let footerOrchestrator: Orchestrator | undefined;
 
 export function setFooterContext(ctx: ExtensionContext): void {
   footerCtx = ctx;
@@ -14,6 +17,10 @@ export function setFooterTracker(tracker: UsageTracker): void {
   footerTracker = tracker;
 }
 
+export function setFooterOrchestrator(orchestrator: Orchestrator): void {
+  footerOrchestrator = orchestrator;
+}
+
 function formatTokens(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -22,10 +29,6 @@ function formatTokens(count: number): string {
   return `${Math.round(count / 1000000)}M`;
 }
 
-function sanitizeStatusText(text: string): string {
-  return text.replace(/[\r\n\t]/g, " ").replace(/ +/g, " ").trim();
-}
-
 function formatPath(cwd: string): string {
   const home = homedir();
   return cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
@@ -47,8 +50,10 @@ function toContextUsagePart(ctx: ExtensionContext | undefined, theme: Theme): st
   const usage = ctx?.getContextUsage();
   const contextWindow = usage?.contextWindow ?? 0;
   const percentValue = usage?.percent ?? null;
+  const tokensValue = usage?.tokens ?? null;
   const percentText = percentValue === null ? "?" : percentValue.toFixed(1);
-  const display = `${percentText}%/${formatTokens(contextWindow)} (auto)`;
+  const tokensText = tokensValue === null ? "?" : formatTokens(tokensValue);
+  const display = `${percentText}%/${tokensText}/${formatTokens(contextWindow)} (auto)`;
   if (percentValue !== null && percentValue > 90) return theme.fg("error", display);
   if (percentValue !== null && percentValue > 70) return theme.fg("warning", display);
   return display;
@@ -115,23 +120,19 @@ function renderPathLine(width: number, theme: Theme, footerData: ReadonlyFooterD
   const ctx = footerCtx;
   const path = formatPath(ctx?.cwd ?? process.cwd());
   const branch = footerData.getGitBranch();
-  const sessionName = ctx?.sessionManager.getSessionName();
 
   let line = path;
   if (branch) line += ` (${branch})`;
-  if (sessionName) line += ` • ${sessionName}`;
-
-  return truncateToWidth(theme.fg("dim", line), width, theme.fg("dim", "..."));
-}
-
-function renderStatusLine(width: number, theme: Theme, footerData: ReadonlyFooterDataProvider): string | undefined {
-  const statuses = footerData.getExtensionStatuses();
-  if (statuses.size === 0) return undefined;
 
-  const line = Array.from(statuses.entries())
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([, text]) => sanitizeStatusText(text))
-    .join(" ");
+  const task = footerOrchestrator?.active;
+  if (task && task.state.phase !== "done") {
+    line += ` • task: ${task.type} • phase: ${task.state.phase}`;
+    const mode = formatModeIndicator(task.state, task.type);
+    if (mode) line += ` • mode: ${mode}`;
+  } else {
+    const sessionName = ctx?.sessionManager.getSessionName();
+    if (sessionName) line += ` • ${sessionName}`;
+  }
 
   return truncateToWidth(theme.fg("dim", line), width, theme.fg("dim", "..."));
 }
@@ -141,8 +142,7 @@ export function createCustomFooter(_tui: TUI, theme: Theme, footerData: Readonly
     render(width: number): string[] {
       const line1 = renderPathLine(width, theme, footerData);
       const line2 = renderStatsLine(width, theme);
-      const line3 = renderStatusLine(width, theme, footerData) ?? theme.fg("dim", "");
-      return [line1, line2, line3];
+      return [line1, line2];
     },
     invalidate(): void {},
     dispose(): void {},

package/extensions/orchestrator/event-handlers.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, it, vi, beforeEach } from "vitest";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
-import { registerEventHandlers } from "./event-handlers.js";
+import { registerEventHandlers, checkoutPrHead, isReviewCycleLive, finalizeReviewCycle } from "./event-handlers.js";
 import { Orchestrator, type ActiveTask } from "./orchestrator.js";
 import { getDefaultConfig } from "./config.js";
 
@@ -22,6 +22,7 @@ function makePi() {
       emit: vi.fn(),
     },
     getAllTools: vi.fn().mockReturnValue([{ name: "lsp" }]),
+    registerTool: vi.fn(),
     sendMessage: vi.fn(),
     sendUserMessage: vi.fn(),
     setModel: vi.fn(),
@@ -144,6 +145,55 @@ describe("tool_call write protection", () => {
   });
 });
 
+describe("review-phase AI_COMMENT write guard", () => {
+  function reviewTask(): ActiveTask {
+    const task = makeActiveTask();
+    task.state.phase = "review";
+    return task;
+  }
+
+  it("allows an edit that only inserts an AI_COMMENT marker", async () => {
+    orchestrator.active = reviewTask();
+    const handler = getHandler("tool_call");
+    const result = await handler(
+      { toolName: "edit", input: { path: "src/a.ts", edits: [{ oldText: "const x = 1;", newText: "const x = 1;\n// AI_COMMENT: check" }] } },
+      {},
+    );
+    expect(result).toBeUndefined();
+  });
+
+  it("blocks an edit that changes real code during review", async () => {
+    orchestrator.active = reviewTask();
+    const handler = getHandler("tool_call");
+    const result = await handler(
+      { toolName: "edit", input: { path: "src/a.ts", edits: [{ oldText: "const x = 1;", newText: "const x = 2;" }] } },
+      {},
+    );
+    expect(result?.block).toBe(true);
+    expect(result?.reason).toContain("AI_COMMENT");
+  });
+
+  it("blocks a brand-new source file write during review", async () => {
+    orchestrator.active = reviewTask();
+    const handler = getHandler("tool_call");
+    const result = await handler(
+      { toolName: "write", input: { path: "src/new.ts", content: "// AI_COMMENT: note\n" } },
+      {},
+    );
+    expect(result?.block).toBe(true);
+  });
+
+  it("does not restrict source edits outside the review phase", async () => {
+    orchestrator.active = makeActiveTask(); // implement phase
+    const handler = getHandler("tool_call");
+    const result = await handler(
+      { toolName: "edit", input: { path: "src/a.ts", edits: [{ oldText: "const x = 1;", newText: "const x = 2;" }] } },
+      {},
+    );
+    expect(result).toBeUndefined();
+  });
+});
+
 describe("tool_result implementation tracking", () => {
   it("adds file to modifiedFiles when input uses path field", async () => {
     orchestrator.active = makeActiveTask();
@@ -347,3 +397,267 @@ describe("tool_call Agent routing and spawn-time context injection", () => {
     expect(input.prompt).toBe("find X");
   });
 });
+
+describe("main-turn stall watchdog (BUG-2)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("recovers a wedged main turn via the idle-gated single-send path", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.config.performance.internals.mainTurnStale = 60000;
+    const sendSpy = vi.spyOn(orchestrator, "sendUserMessageWhenIdle").mockImplementation(() => {});
+    orchestrator.lastCtx = { isIdle: () => true } as any;
+
+    // A turn starts and then never terminates.
+    await getHandler("turn_start")({ type: "turn_start", turnIndex: 0 }, {});
+    expect(orchestrator.mainTurnInFlight).toBe(true);
+
+    // Before the threshold: no recovery.
+    vi.advanceTimersByTime(30000);
+    expect(sendSpy).not.toHaveBeenCalled();
+
+    // Past the threshold with no activity: watchdog fires once.
+    vi.advanceTimersByTime(61000);
+    expect(sendSpy).toHaveBeenCalledTimes(1);
+    expect(sendSpy.mock.calls[0][0]).toContain("stalled without completing");
+    expect(orchestrator.mainTurnRecovering).toBe(true);
+  });
+
+  it("does not fire while the turn keeps making activity", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.config.performance.internals.mainTurnStale = 60000;
+    const sendSpy = vi.spyOn(orchestrator, "sendUserMessageWhenIdle").mockImplementation(() => {});
+
+    await getHandler("turn_start")({ type: "turn_start", turnIndex: 0 }, {});
+    for (let i = 0; i < 5; i++) {
+      vi.advanceTimersByTime(30000);
+      await getHandler("tool_call")({ toolName: "read", input: { path: "a.ts" } }, {});
+    }
+    expect(sendSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not fire after the turn terminates", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.config.performance.internals.mainTurnStale = 60000;
+    const sendSpy = vi.spyOn(orchestrator, "sendUserMessageWhenIdle").mockImplementation(() => {});
+
+    const ctx = { ui: { setStatus: vi.fn(), setWorkingMessage: vi.fn(), notify: vi.fn() }, isIdle: () => true } as any;
+    await getHandler("turn_start")({ type: "turn_start", turnIndex: 0 }, ctx);
+    await getHandler("turn_end")({ type: "turn_end", turnIndex: 0, message: {}, toolResults: [] }, ctx);
+    expect(orchestrator.mainTurnInFlight).toBe(false);
+    vi.advanceTimersByTime(120000);
+    expect(sendSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not fire while an interactive dialogue is open (#11)", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.config.performance.internals.mainTurnStale = 60000;
+    const sendSpy = vi.spyOn(orchestrator, "sendUserMessageWhenIdle").mockImplementation(() => {});
+    orchestrator.lastCtx = { isIdle: () => true } as any;
+
+    await getHandler("turn_start")({ type: "turn_start", turnIndex: 0 }, {});
+    orchestrator.interactivePromptOpen = true;
+    // Well past the stale threshold: the user is parked on a prompt, not wedged.
+    vi.advanceTimersByTime(600000);
+    expect(sendSpy).not.toHaveBeenCalled();
+
+    // Once the dialogue closes, a genuinely stalled turn recovers again.
+    orchestrator.interactivePromptOpen = false;
+    vi.advanceTimersByTime(61000);
+    expect(sendSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire while the subscription fallback dialogue is open (#11)", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.config.performance.internals.mainTurnStale = 60000;
+    const sendSpy = vi.spyOn(orchestrator, "sendUserMessageWhenIdle").mockImplementation(() => {});
+    orchestrator.lastCtx = { isIdle: () => true } as any;
+
+    await getHandler("turn_start")({ type: "turn_start", turnIndex: 0 }, {});
+    orchestrator.subFallbackDialogPending = true;
+    vi.advanceTimersByTime(600000);
+    expect(sendSpy).not.toHaveBeenCalled();
+    orchestrator.subFallbackDialogPending = false;
+  });
+});
+
+describe("checkoutPrHead", () => {
+  type GitResult = { code: number; stdout?: string; stderr?: string };
+  // A key maps to a single result, or an array consumed in call order (last entry repeats).
+  function makeGitOrchestrator(script: Record<string, GitResult | GitResult[]>) {
+    const calls: string[][] = [];
+    const seen: Record<string, number> = {};
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      calls.push(args);
+      const key = args.join(" ");
+      const matched = Object.keys(script).find((k) => key.startsWith(k));
+      const entry = matched ? script[matched] : { code: 0, stdout: "", stderr: "" };
+      let res: GitResult;
+      if (Array.isArray(entry)) {
+        const i = Math.min(seen[matched!] ?? 0, entry.length - 1);
+        seen[matched!] = (seen[matched!] ?? 0) + 1;
+        res = entry[i];
+      } else {
+        res = entry;
+      }
+      return { code: res.code, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+    });
+    return { orchestrator: { pi: { exec } } as any, calls };
+  }
+
+  it("is a no-op when no PR head is provided (non-PR review scope)", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({});
+    const result = await checkoutPrHead(orchestrator, "/repo", "", "");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain("non-PR review scope");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("HALTs on a dirty working tree without checking out", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: " M src/a.ts\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("uncommitted changes");
+    expect(calls.some((c) => c[0] === "checkout")).toBe(false);
+  });
+
+  it("HALTs when on a different branch, and never runs git checkout", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": { code: 0, stdout: "othersha\n" },
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "main\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("feature");
+    expect(calls.some((c) => c[0] === "checkout")).toBe(false);
+    expect(calls.some((c) => c[0] === "merge")).toBe(false);
+  });
+
+  it("fast-forwards a clean branch that is behind the PR head, without checkout or force", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": [{ code: 0, stdout: "oldsha\n" }, { code: 0, stdout: "abc123\n" }],
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "feature\n" },
+      "merge --ff-only abc123": { code: 0, stdout: "Updating oldsha..abc123\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain("fast-forwarded");
+    expect(calls.some((c) => c[0] === "merge" && c[1] === "--ff-only" && c[2] === "abc123")).toBe(true);
+    expect(calls.some((c) => c[0] === "checkout")).toBe(false);
+  });
+
+  it("HALTs when the branch is AHEAD of the PR head (ff-only is a no-op that leaves HEAD ahead)", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      // ff-only to an ancestor returns exit 0 ("Already up to date") without moving HEAD.
+      "rev-parse HEAD": { code: 0, stdout: "aheadsha\n" },
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "feature\n" },
+      "merge --ff-only abc123": { code: 0, stdout: "Already up to date.\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("ahead of the PR head");
+    expect(calls.some((c) => c[0] === "checkout")).toBe(false);
+  });
+
+  it("HALTs when the branch has diverged and cannot fast-forward", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": { code: 0, stdout: "oldsha\n" },
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "feature\n" },
+      "merge --ff-only abc123": { code: 1, stderr: "fatal: Not possible to fast-forward, aborting." },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("diverged");
+    expect(calls.some((c) => c[0] === "checkout")).toBe(false);
+  });
+
+  it("succeeds without any checkout or merge when already on the PR head commit", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": { code: 0, stdout: "abc123\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain("on PR head");
+    expect(calls.some((c) => c[0] === "checkout" || c[0] === "merge")).toBe(false);
+  });
+
+  it("succeeds on a detached HEAD already at the PR head (re-entrant)", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": { code: 0, stdout: "abc123\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(calls.some((c) => c[0] === "checkout" || c[0] === "merge")).toBe(false);
+  });
+
+  it("HALTs on a detached HEAD that is not at the PR head", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": { code: 0, stdout: "oldsha\n" },
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "HEAD\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("detached HEAD");
+    expect(calls.some((c) => c[0] === "checkout" || c[0] === "merge")).toBe(false);
+  });
+});
+
+describe("pp_checkout_pr_head tool registration", () => {
+  it("registers the checkout tool during orchestrator tool setup", async () => {
+    const { registerOrchestratorToolsForTest } = await import("./event-handlers.js");
+    orchestrator.active = makeActiveTask();
+    registerOrchestratorToolsForTest(orchestrator);
+    const names = (pi.registerTool as any).mock.calls.map((c: any[]) => c[0].name);
+    expect(names).toContain("pp_checkout_pr_head");
+  });
+});
+
+describe("isReviewCycleLive (#3b re-entrancy guard)", () => {
+  it("is true only for a cycle awaiting reviewers", () => {
+    const task = makeActiveTask();
+    task.state.reviewCycle = null;
+    expect(isReviewCycleLive(task)).toBe(false);
+    task.state.reviewCycle = { kind: "auto", step: "spawn_reviewers", pass: 1 };
+    expect(isReviewCycleLive(task)).toBe(false);
+    task.state.reviewCycle = { kind: "auto", step: "await_reviewers", pass: 1 };
+    expect(isReviewCycleLive(task)).toBe(true);
+    task.state.reviewCycle = { kind: "auto", step: "apply_feedback", pass: 1 };
+    expect(isReviewCycleLive(task)).toBe(false);
+  });
+
+  it("a live await_reviewers cycle is left intact when the guard blocks (no finalize)", () => {
+    const task = makeActiveTask();
+    task.state.reviewCycle = { kind: "auto", step: "await_reviewers", pass: 2 };
+    // The menu action returns early on isReviewCycleLive WITHOUT calling
+    // finalizeReviewCycle, so the running cycle survives a second selection.
+    expect(isReviewCycleLive(task)).toBe(true);
+    expect(task.state.reviewCycle).toEqual({ kind: "auto", step: "await_reviewers", pass: 2 });
+  });
+
+  it("finalizeReviewCycle only clears a completed (non-live) cycle for the next pass", () => {
+    const task = makeActiveTask();
+    task.dir = mkdtempSync(join(tmpdir(), "pp-review-"));
+    task.state.reviewCycle = { kind: "auto", step: "apply_feedback", pass: 1 };
+    expect(isReviewCycleLive(task)).toBe(false);
+    finalizeReviewCycle(task);
+    expect(task.state.reviewCycle).toBeNull();
+    rmSync(task.dir, { recursive: true, force: true });
+  });
+});