@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

package/extensions/orchestrator/integration.test.ts

@@ -53,6 +53,7 @@ vi.mock("./config.js", async (importOriginal) => {
   return { ...original, loadConfig: () => ({
     general: {
       autoCommit: false,
+      injectAgentsMd: true,
       loadExtraRepoConfigs: true,
       logLevel: "info",
     },
@@ -70,6 +71,9 @@ vi.mock("./config.js", async (importOriginal) => {
           explore: { model: "test/explore", thinking: "low" },
           librarian: { model: "test/librarian", thinking: "medium" },
           task: { model: "test/task", thinking: "medium" },
+          advisor: { model: "test/advisor", thinking: "high" },
+          "deep-debugger": { model: "test/deep-debugger", thinking: "high" },
+          reviewer: { model: "test/reviewer", thinking: "high" },
         },
         presetGroups: {
           planners: {
@@ -206,6 +210,7 @@ function makeConfig() {
   return {
     general: {
       autoCommit: false,
+      injectAgentsMd: true,
       loadExtraRepoConfigs: true,
       logLevel: "info",
     },
@@ -223,6 +228,9 @@ function makeConfig() {
           explore: { model: "test/explore", thinking: "low" },
           librarian: { model: "test/librarian", thinking: "medium" },
           task: { model: "test/task", thinking: "medium" },
+          advisor: { model: "test/advisor", thinking: "high" },
+          "deep-debugger": { model: "test/deep-debugger", thinking: "high" },
+          reviewer: { model: "test/reviewer", thinking: "high" },
         },
         presetGroups: {
           planners: {
@@ -671,8 +679,12 @@ describe("review cycle lifecycle", () => {
     await ppPhaseComplete.execute("call-2", { summary: "plan done" }, undefined, undefined, ctx);
     await new Promise((r) => setTimeout(r, 10));
 
+    // Pick the auto preset first: with zero enabled reviewers it notifies and
+    // (#3d) loops back to the Review submenu — NOT the top-level /pp menu — so the
+    // next expectation is the Review submenu directly, without re-selecting "Review".
     expectReviewAuto(menu);
-    expectReviewOnMyOwn(menu);
+    menu.expect({ question: "Review", options: { include: ["Review on my own"] }, choose: "Review on my own" });
+    menu.expect({ question: "Editor review", options: { include: ["Skip markers"] }, choose: "Skip markers" });
     const result = await ppPhaseComplete.execute("call-3", { summary: "implemented" }, undefined, undefined, ctx);
 
     expect(result.content[0].text).toContain("continue");
@@ -1312,7 +1324,7 @@ describe("edge cases and regressions", () => {
 
     await orchestrator.startTask(ctx as any, "implement", "Continue test");
 
-    expectReviewOnMyOwn(menu);
+    expectReviewOnMyOwn(menu, "Skip markers");
     const ppPhaseComplete = getTool(pi, "pp_phase_complete");
     const result = await ppPhaseComplete.execute("call-1", { summary: "not done yet" }, undefined, undefined, ctx);
 
@@ -1355,7 +1367,7 @@ describe("edge cases and regressions", () => {
     await ppPhaseComplete.execute("call-2", { summary: "plan done" }, undefined, undefined, ctx);
     await new Promise((r) => setTimeout(r, 10));
 
-    expectReviewOnMyOwn(menu);
+    expectReviewOnMyOwn(menu, "Skip markers");
     const result = await ppPhaseComplete.execute("call-3", { summary: "partial work" }, undefined, undefined, ctx);
 
     expect(result.content[0].text).toContain("continue");
@@ -1394,7 +1406,7 @@ describe("edge cases and regressions", () => {
       "utf-8",
     );
 
-    expectReviewOnMyOwn(menu);
+    expectReviewOnMyOwn(menu, "Skip markers");
     const result = await ppPhaseComplete.execute("call-2", { summary: "plan ready" }, undefined, undefined, ctx);
 
     expect(result.content[0].text).toContain("continue");
@@ -1402,6 +1414,124 @@ describe("edge cases and regressions", () => {
     expect(orchestrator.active!.state.step).toBe("synthesize");
   });
 
+  it("editor-review Done returns AI_REVIEW marker instructions in implement phase", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "Editor review test");
+    const taskDir = orchestrator.active!.dir;
+    writeFileSync(join(taskDir, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    expectBrainstormToPlan(menu);
+    const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    await ppPhaseComplete.execute("call-1", { summary: "done" }, undefined, undefined, ctx);
+    await new Promise((r) => setTimeout(r, 10));
+
+    emitSubagentCreated(pi, "planner-1", "Planner (test)");
+    const plansDir = join(taskDir, "plans");
+    mkdirSync(plansDir, { recursive: true });
+    writeFileSync(
+      join(plansDir, `${Math.floor(Date.now() / 1000)}_test.md`),
+      makeValidPlan(["- [ ] P1. Planner draft item — Done when: planner output exists"]),
+      "utf-8",
+    );
+    emitSubagentCompleted(pi, "planner-1", "Planner (test)");
+    writeFileSync(
+      join(plansDir, `${Math.floor(Date.now() / 1000) + 1}_synthesized.md`),
+      makeValidPlan(["- [ ] P1. Todo item — Done when: item intentionally remains unchecked"]),
+      "utf-8",
+    );
+    expectPlanToImplement(menu);
+    await ppPhaseComplete.execute("call-2", { summary: "plan done" }, undefined, undefined, ctx);
+    await new Promise((r) => setTimeout(r, 10));
+
+    expectReviewOnMyOwn(menu, "Done");
+    const result = await ppPhaseComplete.execute("call-3", { summary: "implemented" }, undefined, undefined, ctx);
+
+    expect(result.content[0].text).toContain("AI_REVIEW:");
+    expect(result.content[0].text).toContain("CHANGED files");
+    expect(orchestrator.active!.state.phase).toBe("implement");
+    expect(orchestrator.active!.state.step).toBe("llm_work");
+  });
+
+  it("editor-review Done returns AI_REVIEW state-file instructions in brainstorm phase", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "brainstorm", "Brainstorm editor review");
+
+    expectReviewOnMyOwn(menu, "Done");
+    const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    const result = await ppPhaseComplete.execute("call-1", { summary: "researched" }, undefined, undefined, ctx);
+
+    expect(result.content[0].text).toContain("AI_REVIEW:");
+    expect(result.content[0].text).toContain("USER_REQUEST.md");
+    expect(result.content[0].text).toContain("RESEARCH.md");
+    expect(result.content[0].text).toContain("artifacts/*.md");
+    expect(result.content[0].text).not.toContain("CHANGED files");
+    expect(orchestrator.active!.state.phase).toBe("brainstorm");
+    expect(orchestrator.active!.state.step).toBe("llm_work");
+  });
+
+  it("editor-review Done returns AI_REVIEW state-file instructions in debug phase", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "debug", "Debug editor review");
+
+    expectReviewOnMyOwn(menu, "Done");
+    const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    const result = await ppPhaseComplete.execute("call-1", { summary: "diagnosed" }, undefined, undefined, ctx);
+
+    expect(result.content[0].text).toContain("AI_REVIEW:");
+    expect(result.content[0].text).toContain("USER_REQUEST.md");
+    expect(result.content[0].text).not.toContain("CHANGED files");
+    expect(orchestrator.active!.state.phase).toBe("debug");
+    expect(orchestrator.active!.state.step).toBe("llm_work");
+  });
+
+  it("editor-review Done targets synthesized plan in plan phase", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "Plan editor review");
+    const taskDir = orchestrator.active!.dir;
+    writeFileSync(join(taskDir, "USER_REQUEST.md"), VALID_USER_REQUEST, "utf-8");
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    expectBrainstormToPlan(menu);
+    const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    await ppPhaseComplete.execute("call-1", { summary: "done" }, undefined, undefined, ctx);
+    await new Promise((r) => setTimeout(r, 10));
+
+    emitSubagentCreated(pi, "planner-1", "Planner (test)");
+    const plansDir = join(taskDir, "plans");
+    mkdirSync(plansDir, { recursive: true });
+    writeFileSync(
+      join(plansDir, `${Math.floor(Date.now() / 1000)}_test.md`),
+      makeValidPlan(["- [ ] P1. Planner draft item — Done when: planner output exists"]),
+      "utf-8",
+    );
+    emitSubagentCompleted(pi, "planner-1", "Planner (test)");
+    writeFileSync(
+      join(plansDir, `${Math.floor(Date.now() / 1000) + 1}_synthesized.md`),
+      makeValidPlan(["- [ ] P1. Todo item — Done when: item intentionally remains unchecked"]),
+      "utf-8",
+    );
+
+    expectReviewOnMyOwn(menu, "Done");
+    const result = await ppPhaseComplete.execute("call-2", { summary: "plan ready" }, undefined, undefined, ctx);
+
+    expect(result.content[0].text).toContain("AI_REVIEW:");
+    expect(result.content[0].text).toContain("_synthesized.md");
+    expect(result.content[0].text).not.toContain("CHANGED files");
+    expect(orchestrator.active!.state.phase).toBe("plan");
+    expect(orchestrator.active!.state.step).toBe("synthesize");
+  });
+
   it("generic description task does not auto-trigger agent", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -1741,8 +1871,11 @@ describe("task modes and quick task", () => {
     emitSubagentCreated(pi, "reviewer-2", "Code reviewer (test)");
     emitSubagentCompleted(pi, "reviewer-2", "Code reviewer (test)");
 
+    // Terminal handoff (#1): at the cap the autonomous implement no longer auto-
+    // completes — it opens the guided menu; the user drives Next→Complete to finish.
+    expectImplementToDone(menu);
     const fourth = await ppPhaseComplete.execute("call-4", { summary: "applied 2" }, undefined, undefined, ctx);
-    expect(fourth.content[0].text).toBe("");
+    expect(fourth.content[0].text).toMatch(/completed/);
     expect(orchestrator.active).toBeNull();
     expect(loadTask(taskDir).phase).toBe("done");
   });
@@ -1784,8 +1917,11 @@ describe("task modes and quick task", () => {
     emitSubagentCreated(pi, "reviewer-1", "Code reviewer (test)");
     emitSubagentCompleted(pi, "reviewer-1", "Code reviewer (test)");
 
+    // Terminal handoff (#1): instead of auto-completing, the guided menu opens
+    // and the user drives Next→Complete to finish.
+    expectImplementToDone(menu);
     const second = await ppPhaseComplete.execute("call-2", { summary: "applied" }, undefined, undefined, ctx);
-    expect(second.content[0].text).toBe("");
+    expect(second.content[0].text).toMatch(/completed/);
     expect(orchestrator.active).toBeNull();
     const finalState = loadTask(taskDir);
     expect(finalState.phase).toBe("done");
@@ -1865,8 +2001,11 @@ describe("task modes and quick task", () => {
     );
 
     const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    // Terminal handoff (#1): clean-approved re-entry opens the guided menu rather
+    // than auto-completing; the user drives Next→Complete to finish.
+    expectImplementToDone(menu);
     const result = await ppPhaseComplete.execute("call-1", { summary: "checklist repaired" }, undefined, undefined, ctx);
-    expect(result.content[0].text).toBe("");
+    expect(result.content[0].text).toMatch(/completed/);
     expect(orchestrator.active).toBeNull();
     expect(loadTask(taskDir).phase).toBe("done");
   });
@@ -2079,7 +2218,7 @@ describe("task modes and quick task", () => {
     expect(prompt).toContain("<principles>");
     expect(prompt).toContain("<tools>");
     expect(prompt).toContain("<task>");
-    expect(prompt).toContain("let the user review and advance it via the /pp menu");
+    expect(prompt).toContain("call pp_phase_complete");
     expect(prompt).not.toContain("HARNESS_BASE_PROMPT");
     expect(prompt).toContain(`Working directory: ${cwd}.`);
     expect(prompt).toMatch(/Current month: \d{4}-\d{2}\./);
@@ -2126,6 +2265,66 @@ describe("task modes and quick task", () => {
     expect(prompt).not.toContain("advance it via the /pp menu");
   });
 
+  it("injects root AGENTS.md into the system prompt when enabled, ignoring nested/extra-repo files", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    writeFileSync(join(cwd, "AGENTS.md"), "ROOT_AGENTS_CONTENT", "utf-8");
+    mkdirSync(join(cwd, "nested"), { recursive: true });
+    writeFileSync(join(cwd, "nested", "AGENTS.md"), "NESTED_AGENTS_CONTENT", "utf-8");
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "implement", "implement", undefined, undefined, "guided");
+    orchestrator.active!.state.phase = "plan";
+    orchestrator.active!.state.step = "synthesize";
+
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const prompt = (await beforeStart({ systemPrompt: "base" }, ctx))?.systemPrompt ?? "";
+    expect(prompt).toContain(`<agents_md source="${join(cwd, "AGENTS.md")}">`);
+    expect(prompt).toContain("ROOT_AGENTS_CONTENT");
+    expect(prompt).not.toContain("NESTED_AGENTS_CONTENT");
+  });
+
+  it("omits AGENTS.md block when disabled or file absent", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "implement", "implement", undefined, undefined, "guided");
+    orchestrator.active!.state.phase = "plan";
+    orchestrator.active!.state.step = "synthesize";
+
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const absent = (await beforeStart({ systemPrompt: "base" }, ctx))?.systemPrompt ?? "";
+    expect(absent).not.toContain("<agents_md");
+
+    writeFileSync(join(cwd, "AGENTS.md"), "ROOT_AGENTS_CONTENT", "utf-8");
+    orchestrator.config.general.injectAgentsMd = false;
+    const disabled = (await beforeStart({ systemPrompt: "base" }, ctx))?.systemPrompt ?? "";
+    expect(disabled).not.toContain("<agents_md");
+    expect(disabled).not.toContain("ROOT_AGENTS_CONTENT");
+  });
+
+  it("auto-refreshes AGENTS.md content on the next turn without restart", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    writeFileSync(join(cwd, "AGENTS.md"), "FIRST_VERSION", "utf-8");
+    await orchestrator.startTask({ ...ctx, cwd } as any, "implement", "implement", undefined, undefined, "guided");
+    orchestrator.active!.state.phase = "plan";
+    orchestrator.active!.state.step = "synthesize";
+
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const first = (await beforeStart({ systemPrompt: "base" }, ctx))?.systemPrompt ?? "";
+    expect(first).toContain("FIRST_VERSION");
+
+    writeFileSync(join(cwd, "AGENTS.md"), "SECOND_VERSION", "utf-8");
+    const second = (await beforeStart({ systemPrompt: "base" }, ctx))?.systemPrompt ?? "";
+    expect(second).toContain("SECOND_VERSION");
+    expect(second).not.toContain("FIRST_VERSION");
+  });
+
   it("autonomous plan-phase prompt body contains no /pp guidance", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -2300,8 +2499,11 @@ describe("task modes and quick task", () => {
     emitSubagentCreated(pi, "reviewer-auto-1", "Code reviewer (test)");
     emitSubagentCompleted(pi, "reviewer-auto-1", "Code reviewer (test)");
 
+    // Terminal handoff (#1): the clean second pass opens the guided menu; the user
+    // drives Next→Complete to finish rather than auto-completing.
+    expectImplementToDone(menu);
     const second = await ppPhaseComplete.execute("call-autonomous-review-2", { summary: "applied" }, undefined, undefined, ctx);
-    expect(second.content[0].text).toBe("");
+    expect(second.content[0].text).toMatch(/completed/);
     expect(orchestrator.active).toBeNull();
   });
 
@@ -2346,10 +2548,9 @@ describe("task modes and quick task", () => {
     menu
       .expect({ question: "/pp", options: { include: ["Task"] }, choose: "Task" })
       .expect({ question: "Task", options: { include: ["Review"] }, choose: "Review" })
-      .expect({ question: "Review", options: { include: ["Describe"] }, choose: "Describe" })
+      .expect({ question: "Review", options: { exact: ["New", "Resume", "Back"] }, choose: "New" })
       .expect({ question: "Mode", options: { include: ["Autonomous"] }, choose: "Autonomous" })
       .expect({ question: "Autonomous", options: { include: ["Start"] }, choose: "Start" });
-    ctx.ui.input.mockResolvedValueOnce("Review current branch changes");
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
 
@@ -2419,6 +2620,11 @@ describe("review task lifecycle", () => {
     await orchestrator.startTask(ctx as any, "review", "Review flow");
     const taskDir = orchestrator.active!.dir;
 
+    // #10: the review phase cannot complete without an ANCHORS-bearing final_pass file.
+    const reviewsDir = join(taskDir, "code-reviews");
+    mkdirSync(reviewsDir, { recursive: true });
+    writeFileSync(join(reviewsDir, "1_final_pass-1.md"), "# Review\nANCHORS: (none)\n", "utf-8");
+
     await moveTaskToImplementPhase(pi, orchestrator, ctx, "call-review-to-plan", "call-plan-to-implement");
     expect(orchestrator.active!.state.phase).toBe("implement");
 
@@ -2510,6 +2716,22 @@ describe("modified file tracking", () => {
     expect(orchestrator.active!.state.reviewApprovedClean).toBe(false);
   });
 
+  it("source write clears afterImplementRan so post-handoff edits re-run afterImplement (#1)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "Rerun hooks");
+    await moveTaskToImplementPhase(pi, orchestrator, ctx, "call-rerun-brainstorm", "call-rerun-plan");
+    // Simulate the terminal handoff having already run afterImplement.
+    orchestrator.active!.state.afterImplementRan = true;
+
+    const toolResult = pi._handlers.get("tool_result")!;
+    await toolResult({ toolName: "write", input: { path: "src/d.ts" }, isError: false, content: [] }, {});
+
+    expect(orchestrator.active!.state.afterImplementRan).toBe(false);
+  });
+
   it("tool_result ignores writes inside .pp directory", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -3240,7 +3462,11 @@ describe("tool blocking", () => {
 });
 
 describe("error retry", () => {
-  it("turn_end with error retries with exponential backoff", async () => {
+  // Non-SDK-retryable error messages exercise pi-pi's OWN retry path. SDK-
+  // retryable errors (rate limit, overloaded, 5xx, stream-ended, timeout, etc.)
+  // are now deferred to the SDK's own auto-retry (see the defer test below), so
+  // these use a message the SDK does NOT retry.
+  it("turn_end with a non-SDK-retryable error uses pi-pi's idle-gated retry", async () => {
     vi.useFakeTimers();
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -3249,7 +3475,7 @@ describe("error retry", () => {
     await orchestrator.startTask(ctx as any, "implement", "retry test");
     const turnEnd = pi._handlers.get("turn_end")!;
 
-    await turnEnd({ message: { stopReason: "error", errorMessage: "rate limited", content: [] } }, ctx);
+    await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
 
     expect(orchestrator.errorRetryCount).toBe(1);
     expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Retrying in 2s"), "warning");
@@ -3259,7 +3485,24 @@ describe("error retry", () => {
     vi.useRealTimers();
   });
 
-  it("turn_end stops retrying after max retries", async () => {
+  it("turn_end defers SDK-retryable errors to the SDK (no pi-pi retry)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "sdk defer test");
+    const turnEnd = pi._handlers.get("turn_end")!;
+
+    // "stream ended before message_stop" is SDK-retryable — pi-pi must NOT run
+    // its own retry (which would race the SDK's continue()).
+    await turnEnd({ message: { stopReason: "error", errorMessage: "Anthropic stream ended before message_stop", content: [] } }, ctx);
+
+    expect(orchestrator.errorRetryCount).toBe(0);
+    expect(orchestrator.pendingRetryTimer).toBeNull();
+    expect(ctx.ui.notify).not.toHaveBeenCalledWith(expect.stringContaining("Retrying in"), "warning");
+  });
+
+  it("turn_end stops retrying after max retries (non-SDK-retryable)", async () => {
     vi.useFakeTimers();
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -3269,27 +3512,54 @@ describe("error retry", () => {
     const turnEnd = pi._handlers.get("turn_end")!;
 
     for (let i = 0; i < 6; i++) {
-      await turnEnd({ message: { stopReason: "error", errorMessage: "api down", content: [] } }, ctx);
+      await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
     }
 
-    expect(orchestrator.errorRetryCount).toBe(0);
     expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Stopping auto-retry"), "error");
+    expect(orchestrator.errorNudgeHalted).toBe(true);
+
+    // Once halted, further error turns must NOT arm another retry (this is the
+    // guard against the unbounded-nudge bug).
+    ctx.ui.notify.mockClear();
+    await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
+    expect(ctx.ui.notify).not.toHaveBeenCalledWith(expect.stringContaining("Retrying in"), "warning");
     vi.useRealTimers();
   });
 
-  it("successful turn resets error count", async () => {
+  it("a benign turn does NOT reset the error count (cap must accumulate)", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
     const ctx = makeCtx();
 
-    await orchestrator.startTask(ctx as any, "implement", "retry reset test");
+    await orchestrator.startTask(ctx as any, "implement", "retry no-reset test");
     const turnEnd = pi._handlers.get("turn_end")!;
 
-    await turnEnd({ message: { stopReason: "error", errorMessage: "once", content: [] } }, ctx);
+    await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
     expect(orchestrator.errorRetryCount).toBe(1);
 
+    // A benign (non-error) turn must NOT zero the counter — otherwise a harmless
+    // nudge-induced reply would defeat the cap and allow unbounded error nudges.
     await turnEnd({ message: { stopReason: "stop", content: [] } }, ctx);
-    expect(orchestrator.errorRetryCount).toBe(0);
+    expect(orchestrator.errorRetryCount).toBe(1);
+  });
+
+  it("genuine user re-engagement resets the error count and halt", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "retry reengage test");
+    const turnEnd = pi._handlers.get("turn_end")!;
+
+    await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
+    orchestrator.errorNudgeHalted = true;
+
+    const beforeStart = pi._handlers.get("before_agent_start");
+    if (beforeStart) {
+      await beforeStart({ prompt: "user typed something new" }, ctx);
+      expect(orchestrator.errorRetryCount).toBe(0);
+      expect(orchestrator.errorNudgeHalted).toBe(false);
+    }
   });
 
   it("empty turn triggers continuation nudge", async () => {
@@ -3308,6 +3578,76 @@ describe("error retry", () => {
     expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Continue the implement phase"), { deliverAs: "followUp" });
   });
 
+  it("drops a continuation nudge whose phase no longer matches at delivery", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "stale phase nudge");
+    orchestrator.active!.state.phase = "plan";
+    orchestrator.active!.state.step = "llm_work";
+    const turnEnd = pi._handlers.get("turn_end")!;
+    await turnEnd({ message: { stopReason: "stop", content: [] }, toolResults: [] }, ctx);
+    const nudge = (pi.sendUserMessage as any).mock.calls.map((c: any[]) => c[0]).find((t: string) => t.includes("Continue the plan phase"));
+    expect(nudge).toBeDefined();
+    expect(orchestrator.pendingNudges.has(nudge)).toBe(true);
+
+    // Phase advances before the queued nudge is delivered.
+    orchestrator.active!.state.phase = "implement";
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const abort = vi.fn();
+    await beforeStart({ systemPrompt: "base", prompt: nudge }, makeCtx({ abort }));
+
+    expect(abort).toHaveBeenCalledOnce();
+    expect(orchestrator.pendingNudges.has(nudge)).toBe(false);
+  });
+
+  it("drops a continuation nudge whose task token changed at delivery (same phase)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "stale token nudge");
+    orchestrator.active!.state.phase = "plan";
+    orchestrator.active!.state.step = "llm_work";
+    const turnEnd = pi._handlers.get("turn_end")!;
+    await turnEnd({ message: { stopReason: "stop", content: [] }, toolResults: [] }, ctx);
+    const nudge = (pi.sendUserMessage as any).mock.calls.map((c: any[]) => c[0]).find((t: string) => t.includes("Continue the plan phase"));
+    expect(nudge).toBeDefined();
+
+    // A new task starts (token bumped), also at the plan phase — the old nudge
+    // must not drive a turn in the new task even though the phase name matches.
+    orchestrator.activeTaskToken++;
+    orchestrator.active!.state.phase = "plan";
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const abort = vi.fn();
+    await beforeStart({ systemPrompt: "base", prompt: nudge }, makeCtx({ abort }));
+
+    expect(abort).toHaveBeenCalledOnce();
+  });
+
+  it("delivers a continuation nudge whose phase and token still match", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    await orchestrator.startTask(ctx as any, "implement", "fresh nudge");
+    orchestrator.active!.state.phase = "implement";
+    orchestrator.active!.state.step = "llm_work";
+    const turnEnd = pi._handlers.get("turn_end")!;
+    await turnEnd({ message: { stopReason: "stop", content: [] }, toolResults: [] }, ctx);
+    const nudge = (pi.sendUserMessage as any).mock.calls.map((c: any[]) => c[0]).find((t: string) => t.includes("Continue the implement phase"));
+    expect(nudge).toBeDefined();
+
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const abort = vi.fn();
+    const result = await beforeStart({ systemPrompt: "base", prompt: nudge }, makeCtx({ abort }));
+
+    expect(abort).not.toHaveBeenCalled();
+    expect(result?.systemPrompt).toContain("<task>");
+    expect(orchestrator.pendingNudges.has(nudge)).toBe(false);
+  });
+
   it("suppresses nudges while the controller is transitioning (not running)", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -3539,6 +3879,54 @@ describe("compaction", () => {
     expect(result.compaction.summary).toBe("Task done summary");
   });
 
+  it("task-boundary discard uses distinct discard wording and keeps no verbatim transcript", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    orchestrator.lastCtx = makeCtx({ isIdle: vi.fn().mockReturnValue(false) });
+
+    void orchestrator.transitionController.requestTransition({
+      kind: "done",
+      discard: true,
+      summary: "Task \"x\" (implement) is finished — DISCARD its entire conversation. Do NOT carry forward.",
+    });
+    orchestrator.transitionController.onAgentEnd();
+    const beforeCompact = pi._handlers.get("session_before_compact")!;
+    const result = await beforeCompact(
+      {
+        preparation: { firstKeptEntryId: "old-kept", tokensBefore: 999 },
+        branchEntries: [{ id: "e-a" }, { id: "e-b" }, { id: "newest" }],
+      },
+      {},
+    );
+
+    // Distinct from the phase-transition summary, and instructs discard.
+    expect(result.compaction.summary).not.toBe("Phase transition in progress.");
+    expect(result.compaction.summary).toContain("DISCARD");
+    // Verbatim window collapsed to the newest entry — nothing prior kept.
+    expect(result.compaction.firstKeptEntryId).toBe("newest");
+  });
+
+  it("phase transition keeps the default recent verbatim window (no discard)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    orchestrator.lastCtx = makeCtx({ isIdle: vi.fn().mockReturnValue(false) });
+
+    void orchestrator.transitionController.requestTransition({ kind: "phase", summary: "Phase summary text" });
+    orchestrator.transitionController.onAgentEnd();
+    const beforeCompact = pi._handlers.get("session_before_compact")!;
+    const result = await beforeCompact(
+      {
+        preparation: { firstKeptEntryId: "old-kept", tokensBefore: 111 },
+        branchEntries: [{ id: "e-a" }, { id: "newest" }],
+      },
+      {},
+    );
+
+    expect(result.compaction.summary).toBe("Phase summary text");
+    expect(result.compaction.firstKeptEntryId).toBe("old-kept");
+  });
+
+
   it("session_before_compact re-injects artifacts after natural compaction", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -4139,6 +4527,9 @@ describe("full user flows", () => {
     emitSubagentCreated(pi, "flow-auto-reviewer", "Code reviewer (test)");
     emitSubagentCompleted(pi, "flow-auto-reviewer", "Code reviewer (test)");
 
+    // Terminal handoff (#1): autonomous implement does NOT auto-complete. It opens
+    // the GUIDED implement menu and waits; the user drives Next→Complete to finish.
+    expectImplementToDone(menu);
     await ppPhaseComplete.execute("flow-auto-4", { summary: "feedback applied" }, undefined, undefined, ctx);
 
     expect(orchestrator.active).toBeNull();

package/extensions/orchestrator/messages.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { advanceBanner } from "./messages.js";
+
+describe("advanceBanner", () => {
+  it("starts with [PI-PI] so the controller-injection guard still matches", () => {
+    const out = advanceBanner("[PI-PI] User wants to continue. Run /pp when ready to advance.");
+    expect(out.startsWith("[PI-PI]")).toBe(true);
+  });
+
+  it("renders separators around the content for visual distinctness", () => {
+    const out = advanceBanner("[PI-PI] hello");
+    const lines = out.split("\n");
+    expect(lines[0]).toBe("[PI-PI]");
+    expect(lines[1]).toMatch(/^─+$/);
+    expect(lines[2]).toBe("hello");
+    expect(lines[3]).toMatch(/^─+$/);
+  });
+
+  it("does not double up the [PI-PI] prefix when the body already has one", () => {
+    const out = advanceBanner("[PI-PI] hello");
+    expect(out.match(/\[PI-PI\]/g)?.length).toBe(1);
+    expect(out).not.toContain("[PI-PI] [PI-PI]");
+  });
+
+  it("adds the prefix when the body lacks one", () => {
+    const out = advanceBanner("plain body");
+    expect(out.startsWith("[PI-PI]")).toBe(true);
+    expect(out).toContain("plain body");
+  });
+});

package/extensions/orchestrator/messages.ts

@@ -0,0 +1,6 @@
+const BANNER_SEPARATOR = "─".repeat(48);
+
+export function advanceBanner(body: string): string {
+  const content = body.startsWith("[PI-PI]") ? body.slice("[PI-PI]".length).trimStart() : body;
+  return `[PI-PI]\n${BANNER_SEPARATOR}\n${content}\n${BANNER_SEPARATOR}`;
+}