@ilya-lesikov/pi-pi 0.8.0 → 0.10.0

package/extensions/orchestrator/integration.test.ts

@@ -40,23 +40,30 @@ vi.mock("./cbm.js", () => ({ registerCbmTools: vi.fn() }));
 vi.mock("./exa.js", () => ({ registerExaTools: vi.fn() }));
 vi.mock("./ast-search.js", () => ({ registerAstSearchTool: vi.fn() }));
 vi.mock("./doctor.js", () => ({ runDoctor: vi.fn(async () => undefined) }));
-vi.mock("./agents/registry.js", () => ({
-  registerAgentDefinitions: vi.fn(),
-  unregisterAgentDefinitions: vi.fn(),
-  setExtensionOnlyMode: vi.fn(),
-  spawnViaRpc: vi.fn(async (_pi: any, _type: string) => ({ id: `mock-${Math.random().toString(36).slice(2)}` })),
-  waitForCompletion: vi.fn(async () => undefined),
-}));
+vi.mock("./agents/registry.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./agents/registry.js")>();
+  return {
+    ...actual,
+    registerAgentDefinitions: vi.fn(),
+    unregisterAgentDefinitions: vi.fn(),
+    setExtensionOnlyMode: vi.fn(),
+    getAgentConfigSnapshot: vi.fn(() => undefined),
+    spawnViaRpc: vi.fn(async (_pi: any, _type: string) => ({ id: `mock-${Math.random().toString(36).slice(2)}` })),
+    waitForCompletion: vi.fn(async () => undefined),
+  };
+});
 
 vi.mock("./config.js", async (importOriginal) => {
   const original = await importOriginal<typeof import("./config.js")>();
   return { ...original, loadConfig: () => ({
     general: {
       autoCommit: false,
+      injectAgentsMd: true,
       loadExtraRepoConfigs: true,
       logLevel: "info",
     },
     agents: {
+      maxConcurrentSubagents: 7,
       orchestrators: {
         implement: { model: "test/model", thinking: "high" },
         plan: { model: "test/model", thinking: "high" },
@@ -70,9 +77,14 @@ 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" },
+        },
+        pools: {
+          advisors: [
+            { enabled: true, model: "test/advisor-fable", thinking: "high" },
+            { enabled: true, model: "test/advisor-gpt", thinking: "high" },
+          ],
+          reviewers: [{ enabled: true, model: "test/reviewer", thinking: "high" }],
+          deepDebuggers: [{ enabled: true, model: "test/deep-debugger", thinking: "high" }],
         },
         presetGroups: {
           planners: {
@@ -209,10 +221,12 @@ function makeConfig() {
   return {
     general: {
       autoCommit: false,
+      injectAgentsMd: true,
       loadExtraRepoConfigs: true,
       logLevel: "info",
     },
     agents: {
+      maxConcurrentSubagents: 7,
       orchestrators: {
         implement: { model: "test/model", thinking: "high" },
         plan: { model: "test/model", thinking: "high" },
@@ -226,9 +240,14 @@ 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" },
+        },
+        pools: {
+          advisors: [
+            { enabled: true, model: "test/advisor-fable", thinking: "high" },
+            { enabled: true, model: "test/advisor-gpt", thinking: "high" },
+          ],
+          reviewers: [{ enabled: true, model: "test/reviewer", thinking: "high" }],
+          deepDebuggers: [{ enabled: true, model: "test/deep-debugger", thinking: "high" }],
         },
         presetGroups: {
           planners: {
@@ -677,8 +696,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, "Skip markers");
+    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");
@@ -1311,6 +1334,49 @@ describe("edge cases and regressions", () => {
     expect(finalState.reviewCycle).toBeNull();
   });
 
+  it("manual auto-review (item 5) loops in a guided phase then stops in-phase on clean approve", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx();
+
+    // Guided implement task, parked in the implement phase.
+    await orchestrator.startTask(ctx as any, "implement", "Manual auto-review test", undefined, undefined, "guided");
+    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");
+    const plansDir = join(taskDir, "plans");
+    mkdirSync(plansDir, { recursive: true });
+    writeFileSync(
+      join(plansDir, `${Math.floor(Date.now() / 1000)}_synthesized.md`),
+      makeValidPlan(["- [x] P1. Done item — Done when: synthesized plan is fully checked"]),
+      "utf-8",
+    );
+    orchestrator.active!.state.phase = "implement";
+    orchestrator.active!.state.step = "llm_work";
+    // Arm the item-5 flag (advanceOnComplete=false): stop in-phase on approve.
+    orchestrator.active!.state.manualAutoReview = { phase: "implement", preset: "regular", maxPasses: 3, advanceOnComplete: false };
+    saveTask(taskDir, orchestrator.active!.state);
+
+    const ppPhaseComplete = getTool(pi, "pp_phase_complete");
+    // First call: enters the review cycle (spawns reviewers).
+    const first = await ppPhaseComplete.execute("m-1", { summary: "implemented" }, undefined, undefined, ctx);
+    expect(first.content[0].text).toContain("pass 1/3");
+    expect(orchestrator.active!.state.reviewCycle).not.toBeNull();
+
+    // Reviewer approves.
+    const reviewsDir = join(taskDir, "code-reviews");
+    mkdirSync(reviewsDir, { recursive: true });
+    writeFileSync(join(reviewsDir, `${Math.floor(Date.now() / 1000)}_test_round-1.md`), "VERDICT: APPROVE", "utf-8");
+    emitSubagentCreated(pi, "reviewer-1", "Code reviewer (test)");
+    emitSubagentCompleted(pi, "reviewer-1", "Code reviewer (test)");
+
+    // Second call: finalizes the clean pass; item 5 stops in-phase and clears the flag.
+    const second = await ppPhaseComplete.execute("m-2", { summary: "fixes applied" }, undefined, undefined, ctx);
+    expect(second.content[0].text).toContain("Staying in the implement phase");
+    expect(orchestrator.active!.state.phase).toBe("implement");
+    expect(orchestrator.active!.state.manualAutoReview).toBeUndefined();
+  });
+
   it("continue brainstorming sets step back to llm_work", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -1318,7 +1384,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);
 
@@ -1400,7 +1466,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");
@@ -1449,6 +1515,83 @@ describe("edge cases and regressions", () => {
     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);
@@ -1595,7 +1738,7 @@ describe("task modes and quick task", () => {
     const ctx = makeCtx();
 
     await orchestrator.startTask(ctx as any, "quick", "quick");
-    menu.expect({ question: m.taskMenu("quick", "quick"), options: { include: ["Complete", "Pause"], exclude: ["Next", "Review"] }, choose: "Back" });
+    menu.expect({ question: m.taskMenu("quick", "quick"), options: { include: ["Complete", "Pause"], exclude: ["Next", "Review"] }, choose: "Back to prompt" });
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
   });
@@ -1713,7 +1856,7 @@ describe("task modes and quick task", () => {
     expect(orchestrator.transitionController.isRunning()).toBe(true);
 
     // Explicit "Back" navigation (not an ESC): the reminder must be preserved.
-    menu.expect({ question: m.anyTaskMenu, options: { include: ["Back"] }, choose: "Back" });
+    menu.expect({ question: m.anyTaskMenu, options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const ppPhaseComplete = getTool(pi, "pp_phase_complete");
     const result = await ppPhaseComplete.execute("back-1", { summary: "done" }, undefined, undefined, ctx);
@@ -1788,8 +1931,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");
   });
@@ -1831,8 +1977,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");
@@ -1912,8 +2061,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");
   });
@@ -2038,7 +2190,7 @@ describe("task modes and quick task", () => {
       .expect({ question: "Implement", options: { include: ["Resume", "Back"] }, choose: "Resume" })
       .expect({ question: "Implement", options: { include: ["Back"] }, choose: "Back" })
       .expect({ question: "Task", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
 
@@ -2102,7 +2254,8 @@ describe("task modes and quick task", () => {
     const beforeStart = pi._handlers.get("before_agent_start")!;
     const result = await beforeStart({ systemPrompt: "HARNESS_BASE_PROMPT" }, ctx);
     const prompt = result?.systemPrompt ?? "";
-    expect(prompt.startsWith("<constraints>")).toBe(true);
+    expect(prompt.startsWith("<identity>")).toBe(true);
+    expect(prompt).toContain("<constraints>");
     expect(prompt).not.toContain("HARNESS_BASE_PROMPT");
     expect(prompt).toContain("The moment its work is complete, call pp_phase_complete");
     // No interactive '/pp menu' advance guidance in autonomous mode.
@@ -2121,7 +2274,8 @@ describe("task modes and quick task", () => {
 
     const beforeStart = pi._handlers.get("before_agent_start")!;
     const prompt = (await beforeStart({ systemPrompt: "HARNESS_BASE_PROMPT" }, ctx))?.systemPrompt ?? "";
-    expect(prompt.startsWith("<constraints>")).toBe(true);
+    expect(prompt.startsWith("<identity>")).toBe(true);
+    expect(prompt).toContain("<constraints>");
     expect(prompt).toContain("ACTIVE PHASE: plan (READ-ONLY)");
     expect(prompt).toContain("<principles>");
     expect(prompt).toContain("<tools>");
@@ -2173,6 +2327,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);
@@ -2199,6 +2413,52 @@ describe("task modes and quick task", () => {
     expect(state.reviewerFailureAutoRetried).toBe(false);
   });
 
+  it("captures the initiating prompt into a generic-description task name (#7)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "review", "review", undefined, undefined, "guided");
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    await beforeStart({ systemPrompt: "base", prompt: "  Review the   payment refactor PR  " }, ctx);
+    expect(orchestrator.active!.state.description).toBe("Review the payment refactor PR");
+    expect(orchestrator.active!.description).toBe("Review the payment refactor PR");
+  });
+
+  it("does not overwrite a non-generic description or capture a [PI-PI] injection", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "review", "review", undefined, undefined, "guided");
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    await beforeStart({ systemPrompt: "base", prompt: "[PI-PI] Continue working on the current phase" }, ctx);
+    expect(orchestrator.active!.state.description).toBe("review");
+  });
+
+  it("collapses a multi-line initiating prompt into one line (#8), bounded by the 700-char cap", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "review", "review", undefined, undefined, "guided");
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    await beforeStart({ systemPrompt: "base", prompt: "Review the auth refactor\nand the token store\nfor race conditions" }, ctx);
+    expect(orchestrator.active!.state.description).toBe("Review the auth refactor and the token store for race conditions");
+  });
+
+  it("caps the collapsed multi-line description at 700 chars (#8)", async () => {
+    const cwd = makeTempDir();
+    const { pi, orchestrator } = await setupOrchestrator(cwd);
+    const ctx = makeCtx({ cwd });
+
+    await orchestrator.startTask({ ...ctx, cwd } as any, "review", "review", undefined, undefined, "guided");
+    const beforeStart = pi._handlers.get("before_agent_start")!;
+    const longPrompt = "line one\n" + "x".repeat(2000);
+    await beforeStart({ systemPrompt: "base", prompt: longPrompt }, ctx);
+    expect(orchestrator.active!.state.description.length).toBe(700);
+  });
+
   it("blocks ask_user in autonomous mode after first phase", async () => {
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
@@ -2347,8 +2607,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();
   });
 
@@ -2393,10 +2656,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);
 
@@ -2466,6 +2728,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");
 
@@ -2557,6 +2824,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);
@@ -3287,10 +3570,10 @@ describe("tool blocking", () => {
 });
 
 describe("error retry", () => {
-  // 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.
+  // Both SDK-retryable and non-SDK-retryable errors now exercise pi-pi's OWN
+  // idle-gated retry. By the time turn_end fires, the SDK's short in-prompt
+  // retry budget is already exhausted, so pi-pi's longer retry (8×, up to ~4min)
+  // takes over instead of the session silently dying after the SDK's ~14s budget.
   it("turn_end with a non-SDK-retryable error uses pi-pi's idle-gated retry", async () => {
     vi.useFakeTimers();
     const cwd = makeTempDir();
@@ -3303,28 +3586,33 @@ describe("error retry", () => {
     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");
+    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Retrying in 2s"), "info");
 
     await vi.advanceTimersByTimeAsync(2000);
-    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Previous request failed"), { deliverAs: "followUp" });
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Transient API error"), { deliverAs: "followUp" });
     vi.useRealTimers();
   });
 
-  it("turn_end defers SDK-retryable errors to the SDK (no pi-pi retry)", async () => {
+  it("turn_end retries SDK-retryable errors via pi-pi's idle-gated retry", async () => {
+    vi.useFakeTimers();
     const cwd = makeTempDir();
     const { pi, orchestrator } = await setupOrchestrator(cwd);
     const ctx = makeCtx();
 
-    await orchestrator.startTask(ctx as any, "implement", "sdk defer test");
+    await orchestrator.startTask(ctx as any, "implement", "sdk retryable 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()).
+    // "stream ended before message_stop" is SDK-retryable, but by turn_end the
+    // SDK's own short retry budget is exhausted, so pi-pi's longer retry takes
+    // over rather than letting the autonomous session die.
     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");
+    expect(orchestrator.errorRetryCount).toBe(1);
+    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Retrying in 2s"), "info");
+
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Transient API error"), { deliverAs: "followUp" });
+    vi.useRealTimers();
   });
 
   it("turn_end stops retrying after max retries (non-SDK-retryable)", async () => {
@@ -3336,7 +3624,8 @@ describe("error retry", () => {
     await orchestrator.startTask(ctx as any, "implement", "retry max test");
     const turnEnd = pi._handlers.get("turn_end")!;
 
-    for (let i = 0; i < 6; i++) {
+    // 8 retries then a 9th error turn that trips the halt.
+    for (let i = 0; i < 9; i++) {
       await turnEnd({ message: { stopReason: "error", errorMessage: "invalid tool arguments", content: [] } }, ctx);
     }
 
@@ -3403,6 +3692,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);
@@ -3634,6 +3993,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);
@@ -3745,7 +4152,7 @@ describe("session lifecycle", () => {
     expect(toolNames).toContain("pp_register_repo");
   });
 
-  it("session_start detects paused tasks and notifies", async () => {
+  it("session_start does not notify about paused tasks (#1: all hints removed)", async () => {
     const cwd = makeTempDir();
     createTask(cwd, "implement", "Paused task");
     const pi = makePi();
@@ -3757,7 +4164,7 @@ describe("session lifecycle", () => {
     const sessionStart = pi._handlers.get("session_start")!;
     await sessionStart({}, ctx);
 
-    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("Paused task"), "info");
+    expect(ctx.ui.notify).not.toHaveBeenCalledWith(expect.stringContaining("Paused task"), "info");
   });
 
   it("session_start loads config", async () => {
@@ -3789,29 +4196,31 @@ describe("menu contracts", () => {
 
     menu
       .expect({ question: "/pp", options: { include: ["Settings"] }, choose: "Settings" })
-      .expect({ question: "Settings", options: { exact: ["General", "Agents", "Commands", "Performance", "LSP", "Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "Settings", options: { exact: ["General", "Agents", "Commands", "Performance", "LSP", "Flant", "Info", "Back"] }, choose: "Back" })
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
   });
 
-  it("info menu shows Doctor and hides LSP", async () => {
+  it("info menu (under Settings) shows Doctor and hides LSP", async () => {
     const cwd = makeTempDir();
     const { pi } = await setupOrchestrator(cwd);
     const ctx = makeCtx();
 
     menu
-      .expect({ question: "/pp", options: { include: ["Info"] }, choose: "Info" })
+      .expect({ question: "/pp", options: { include: ["Settings"] }, choose: "Settings" })
+      .expect({ question: "Settings", options: { include: ["Info"] }, choose: "Info" })
       .expect({
         question: "Info",
         options: {
-          include: ["Subagents", "Usage", "Doctor", "Back"],
-          exclude: ["LSP"],
+          include: ["Usage", "Doctor", "Back"],
+          exclude: ["LSP", "Subagents"],
         },
         choose: "Back",
       })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "Settings", options: { include: ["Back"] }, choose: "Back" })
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -3824,10 +4233,12 @@ describe("menu contracts", () => {
     const runDoctorSpy = vi.mocked(doctorModule.runDoctor);
 
     menu
-      .expect({ question: "/pp", options: { include: ["Info"] }, choose: "Info" })
+      .expect({ question: "/pp", options: { include: ["Settings"] }, choose: "Settings" })
+      .expect({ question: "Settings", options: { include: ["Info"] }, choose: "Info" })
       .expect({ question: "Info", options: { include: ["Doctor", "Back"] }, choose: "Doctor" })
       .expect({ question: "Info", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "Settings", options: { include: ["Back"] }, choose: "Back" })
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -3849,7 +4260,7 @@ describe("menu contracts", () => {
       .expect({ question: "LSP", options: { exact: ["Restart all servers", "Back"] }, choose: "Restart all servers" })
       .expect({ question: "LSP", options: { include: ["Back"] }, choose: "Back" })
       .expect({ question: "Settings", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -3869,7 +4280,7 @@ describe("menu contracts", () => {
       .expect({ question: "LSP", options: { exact: ["Restart all servers", "Back"] }, choose: "Restart all servers" })
       .expect({ question: "LSP", options: { include: ["Back"] }, choose: "Back" })
       .expect({ question: "Settings", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -3885,9 +4296,9 @@ describe("menu contracts", () => {
     menu
       .expect({ question: "/pp", options: { include: ["Settings"] }, choose: "Settings" })
       .expect({ question: "Settings", options: { include: ["Agents", "Back"] }, choose: "Agents" })
-      .expect({ question: "Agents", options: { exact: ["Orchestrators", "Subagents", "Back"] }, choose: "Back" })
+      .expect({ question: "Agents", options: { exact: ["Orchestrators", "Subagents", "Max concurrent subagents: 7", "Back"] }, choose: "Back" })
       .expect({ question: "Settings", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -3903,9 +4314,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("implement", "brainstorm"),
       options: {
-        exact: ["Next", "Review", "Info", "Settings", "Back"],
+        exact: ["Next", "Review", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -3925,9 +4336,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("implement", "plan"),
       options: {
-        exact: ["Next", "Info", "Settings", "Back"],
+        exact: ["Next", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -3946,9 +4357,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("implement", "brainstorm"),
       options: {
-        exact: ["Next", "Review", "Info", "Settings", "Back"],
+        exact: ["Next", "Review", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -3965,9 +4376,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("debug", "debug"),
       options: {
-        exact: ["Next", "Review", "Info", "Settings", "Back"],
+        exact: ["Next", "Review", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -3984,9 +4395,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("review", "review"),
       options: {
-        exact: ["Next", "Review", "Info", "Settings", "Back"],
+        exact: ["Next", "Review", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -4085,9 +4496,9 @@ describe("menu contracts", () => {
     menu.expect({
       question: m.taskMenu("quick", "quick"),
       options: {
-        exact: ["Complete", "Pause", "Info", "Settings", "Back"],
+        exact: ["Complete", "Pause", "Subagents", "Settings", "Back to prompt"],
       },
-      choose: "Back",
+      choose: "Back to prompt",
     });
 
     const pp = getCommand(pi, "pp");
@@ -4102,8 +4513,8 @@ describe("menu contracts", () => {
     await orchestrator.startTask(ctx as any, "implement", "contract next");
     menu
       .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Next"] }, choose: "Next" })
-      .expect({ question: "Next", options: { exact: ["Continue to plan & implement", "Complete", "Pause", "Back"] }, choose: "Back" })
-      .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "Next", options: { exact: ["Continue to plan & implement", "Auto review, then continue to plan & implement", "Complete", "Pause", "Back"] }, choose: "Back" })
+      .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -4115,7 +4526,7 @@ describe("menu contracts", () => {
     menu
       .expect({ question: m.taskMenu("implement", "implement"), options: { include: ["Next"] }, choose: "Next" })
       .expect({ question: "Next", options: { exact: ["Complete", "Pause", "Back"] }, choose: "Back" })
-      .expect({ question: m.taskMenu("implement", "implement"), options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: m.taskMenu("implement", "implement"), options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     await pp(undefined, ctx);
   });
@@ -4129,8 +4540,8 @@ describe("menu contracts", () => {
 
     menu
       .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Review"] }, choose: "Review" })
-      .expect({ question: "Review", options: { exact: [m.autoReview, "Review on my own", "Back"] }, choose: "Back" })
-      .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "Review", options: { exact: [m.autoReview, "Auto review until approved", "Review in Plannotator", "Review on my own", "Back"] }, choose: "Back" })
+      .expect({ question: m.taskMenu("implement", "brainstorm"), options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -4148,7 +4559,7 @@ describe("menu contracts", () => {
       .expect({ question: "Mode", options: { exact: ["Guided", "Autonomous", "Back"] }, choose: "Back" })
       .expect({ question: "Implement", options: { include: ["Back"] }, choose: "Back" })
       .expect({ question: "Task", options: { include: ["Back"] }, choose: "Back" })
-      .expect({ question: "/pp", options: { include: ["Back"] }, choose: "Back" });
+      .expect({ question: "/pp", options: { include: ["Back to prompt"] }, choose: "Back to prompt" });
 
     const pp = getCommand(pi, "pp");
     await pp(undefined, ctx);
@@ -4234,6 +4645,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();