@ilya-lesikov/pi-pi 0.10.0 → 0.12.0

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

@@ -365,6 +365,109 @@ describe("checkoutPrHead additional branches", () => {
     expect(result.message).toContain("no PR head commit provided");
     expect(exec).toHaveBeenCalledTimes(1);
   });
+
+  it("creates a tracking branch and switches when the local branch is missing", async () => {
+    // HEAD is asked twice: initial (not on oid) then post-switch (on oid).
+    let headCalls = 0;
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args[1] === "HEAD") return { code: 0, stdout: headCalls++ === 0 ? "othersha" : "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "main", stderr: "" };
+      if (args[0] === "fetch") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/remotes/origin/feature")) return { code: 0, stdout: "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/heads/feature")) return { code: 1, stdout: "", stderr: "" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain('switched to PR head branch "feature"');
+    const createdTracking = exec.mock.calls.some((c: any[]) => c[1][0] === "checkout" && c[1].includes("-b"));
+    expect(createdTracking).toBe(true);
+  });
+
+  it("HALTs when the PR head branch cannot be fetched from origin (fork PR)", async () => {
+    let headCalls = 0;
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args[1] === "HEAD") return { code: 0, stdout: headCalls++ === 0 ? "othersha" : "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "main", stderr: "" };
+      if (args[0] === "fetch") return { code: 128, stdout: "", stderr: "couldn't find remote ref" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("could not fetch PR head branch");
+  });
+
+  it("HALTs when the fetched origin tip does not match the advertised oid", async () => {
+    let headCalls = 0;
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args[1] === "HEAD") return { code: 0, stdout: headCalls++ === 0 ? "othersha" : "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "main", stderr: "" };
+      if (args[0] === "fetch") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/remotes/origin/feature")) return { code: 0, stdout: "differentsha", stderr: "" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("not the advertised PR head");
+  });
+
+  it("fast-forwards and switches an existing local branch that is a safe ancestor of the PR head", async () => {
+    let headCalls = 0;
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args[1] === "HEAD") return { code: 0, stdout: headCalls++ === 0 ? "othersha" : "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "main", stderr: "" };
+      if (args[0] === "fetch") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/remotes/origin/feature")) return { code: 0, stdout: "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/heads/feature")) return { code: 0, stdout: "localtip", stderr: "" };
+      if (args[0] === "merge-base" && args.includes("--is-ancestor")) return { code: 0, stdout: "", stderr: "" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain('switched to PR head branch "feature"');
+    // Ancestry was proven BEFORE the checkout.
+    const order = exec.mock.calls.map((c: any[]) => c[1].join(" "));
+    const ancestorIdx = order.findIndex((c: string) => c.includes("merge-base --is-ancestor"));
+    const checkoutIdx = order.findIndex((c: string) => c.startsWith("checkout feature"));
+    expect(ancestorIdx).toBeGreaterThanOrEqual(0);
+    expect(checkoutIdx).toBeGreaterThan(ancestorIdx);
+  });
+
+  it("HALTs on a diverged local branch WITHOUT checking it out (never switches then fails)", async () => {
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args[1] === "HEAD") return { code: 0, stdout: "othersha", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("--abbrev-ref")) return { code: 0, stdout: "main", stderr: "" };
+      if (args[0] === "fetch") return { code: 0, stdout: "", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/remotes/origin/feature")) return { code: 0, stdout: "abc123", stderr: "" };
+      if (args[0] === "rev-parse" && args.includes("refs/heads/feature")) return { code: 0, stdout: "divergedtip", stderr: "" };
+      if (args[0] === "merge-base" && args.includes("--is-ancestor")) return { code: 1, stdout: "", stderr: "" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("HALT");
+    expect(result.message).toContain("has diverged");
+    // The critical guarantee: no checkout was issued — the user stays on their branch.
+    const checkedOut = exec.mock.calls.some((c: any[]) => c[1][0] === "checkout");
+    expect(checkedOut).toBe(false);
+  });
+
+  it("still HALTs on a dirty tree regardless of branch", async () => {
+    const exec = vi.fn(async (_cmd: string, args: string[]) => {
+      if (args[0] === "status") return { code: 0, stdout: " M file.ts", stderr: "" };
+      return { code: 0, stdout: "", stderr: "" };
+    });
+    const result = await checkoutPrHead(orchWithExec(exec), "/repo", "feature", "abc123");
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("uncommitted changes");
+  });
 });
 
 describe("registered handler branches", () => {
@@ -428,6 +531,33 @@ describe("registered handler branches", () => {
     }
   });
 
+  it("marks a phased-batch agent's record consumed to suppress the vendor nudge; leaves free agents alone", () => {
+    const records = new Map<string, { resultConsumed?: boolean }>();
+    const managerKey = Symbol.for("pi-subagents:manager");
+    (globalThis as any)[managerKey] = { getRecord: (id: string) => records.get(id) };
+    try {
+      // Phased batch: the record IS marked consumed (nudge suppressed).
+      records.set("agent-p", {});
+      orchestrator.active = makeActiveTask();
+      orchestrator.active.state.step = "await_reviewers";
+      orchestrator.spawnedAgentIds.add("agent-p");
+      orchestrator.agentDescriptions.set("agent-p", "reviewer gpt");
+      getEventHandler("subagents:completed")({ id: "agent-p", description: "reviewer gpt" }, {});
+      expect(records.get("agent-p")!.resultConsumed).toBe(true);
+
+      // Free (non-phased) agent: the record is NOT touched (keeps its nudge).
+      records.set("agent-free", {});
+      orchestrator.active = makeActiveTask();
+      orchestrator.active.state.step = "llm_work";
+      orchestrator.spawnedAgentIds.add("agent-free");
+      orchestrator.agentDescriptions.set("agent-free", "advisor gpt");
+      getEventHandler("subagents:completed")({ id: "agent-free", description: "advisor gpt" }, {});
+      expect(records.get("agent-free")!.resultConsumed).toBeUndefined();
+    } finally {
+      delete (globalThis as any)[managerKey];
+    }
+  });
+
   it("cleans up a stopped subagent without emitting an error", () => {
     orchestrator.active = makeActiveTask();
     orchestrator.spawnedAgentIds.add("agent-1");
@@ -528,6 +658,7 @@ describe("pp_phase_complete tool", () => {
     orchestrator.active.state.phase = "plan";
     orchestrator.active.state.step = "llm_work";
     orchestrator.active.state.mode = "autonomous";
+    orchestrator.active.state.reconciledPhase = "plan";
     const transitionSpy = vi.fn(async () => ({ ok: true as const }));
     orchestrator.transitionToNextPhase = transitionSpy;
     registerOrchestratorToolsForTest(orchestrator);
@@ -542,6 +673,7 @@ describe("pp_phase_complete tool", () => {
     orchestrator.active.state.phase = "plan";
     orchestrator.active.state.step = "llm_work";
     orchestrator.active.state.mode = "autonomous";
+    orchestrator.active.state.reconciledPhase = "plan";
     orchestrator.transitionToNextPhase = async () => ({ ok: false, error: "boom" });
     registerOrchestratorToolsForTest(orchestrator);
     const tool = getTool("pp_phase_complete");
@@ -553,9 +685,62 @@ describe("pp_phase_complete tool", () => {
     orchestrator.active = makeActiveTask();
     orchestrator.active.state.phase = "implement";
     orchestrator.active.state.step = "llm_work";
+    orchestrator.active.state.reconciledPhase = "implement";
+    registerOrchestratorToolsForTest(orchestrator);
+    const tool = getTool("pp_phase_complete");
+    const result = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(result.content[0].text).toBe("MENU_RESULT");
+  });
+
+  it("prompts to reconcile on the first call of a phase, then proceeds on the re-call", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.active.state.phase = "implement";
+    orchestrator.active.state.step = "llm_work";
+    const transitionSpy = vi.fn(async () => ({ ok: true as const }));
+    orchestrator.transitionToNextPhase = transitionSpy;
     registerOrchestratorToolsForTest(orchestrator);
     const tool = getTool("pp_phase_complete");
+
+    const first = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(first.content[0].text).toContain("reconcile the task's state files");
+    expect(first.isError).toBeUndefined();
+    expect(transitionSpy).not.toHaveBeenCalled();
+    expect(orchestrator.active.state.phase).toBe("implement");
+    expect(orchestrator.active.state.reviewCycle).toBeNull();
+
+    const second = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(second.content[0].text).toBe("MENU_RESULT");
+  });
+
+  it("an autonomous run reconciles once then advances on the immediate re-call (no loop)", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.active.state.phase = "plan";
+    orchestrator.active.state.step = "llm_work";
+    orchestrator.active.state.mode = "autonomous";
+    const transitionSpy = vi.fn(async () => ({ ok: true as const }));
+    orchestrator.transitionToNextPhase = transitionSpy;
+    registerOrchestratorToolsForTest(orchestrator);
+    const tool = getTool("pp_phase_complete");
+
+    const first = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(first.content[0].text).toContain("reconcile the task's state files");
+    expect(transitionSpy).not.toHaveBeenCalled();
+
+    const second = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(second.content[0].text).toBe("");
+    expect(transitionSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("never gates a quick-phase task", async () => {
+    orchestrator.active = makeActiveTask();
+    orchestrator.active.type = "quick";
+    orchestrator.active.state.phase = "quick";
+    orchestrator.active.state.step = "llm_work";
+    registerOrchestratorToolsForTest(orchestrator);
+    const tool = getTool("pp_phase_complete");
+
     const result = await tool.execute("id", { summary: "s" }, undefined, undefined, ctxWithUi());
+    expect(result.content[0].text).not.toContain("reconcile the task's state files");
     expect(result.content[0].text).toBe("MENU_RESULT");
   });
 });

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

@@ -615,16 +615,36 @@ describe("checkoutPrHead", () => {
     expect(calls.some((c) => c[0] === "checkout")).toBe(false);
   });
 
-  it("HALTs when on a different branch, and never runs git checkout", async () => {
+  it("switches to the PR head branch (clean tree, different branch) after fetch+verify", async () => {
+    const { orchestrator, calls } = makeGitOrchestrator({
+      "status --porcelain": { code: 0, stdout: "" },
+      "rev-parse HEAD": [{ code: 0, stdout: "othersha\n" }, { code: 0, stdout: "abc123\n" }],
+      "rev-parse --abbrev-ref HEAD": { code: 0, stdout: "main\n" },
+      "fetch origin": { code: 0, stdout: "" },
+      "rev-parse --verify refs/remotes/origin/feature": { code: 0, stdout: "abc123\n" },
+      "rev-parse --verify --quiet refs/heads/feature": { code: 0, stdout: "localsha\n" },
+      "checkout feature": { code: 0, stdout: "" },
+      "merge --ff-only abc123": { code: 0, stdout: "Updating localsha..abc123\n" },
+    });
+    const result = await checkoutPrHead(orchestrator, "/repo", "feature", "abc123");
+    expect(result.ok).toBe(true);
+    expect(result.message).toContain('switched to PR head branch "feature"');
+    expect(calls.some((c) => c[0] === "checkout" && c[1] === "feature")).toBe(true);
+    expect(calls.some((c) => c[0] === "fetch")).toBe(true);
+  });
+
+  it("HALTs on a different branch when the fetched tip does not match the advertised oid", 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" },
+      "fetch origin": { code: 0, stdout: "" },
+      "rev-parse --verify refs/remotes/origin/feature": { code: 0, stdout: "differentsha\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(result.message).toContain("not the advertised PR head");
     expect(calls.some((c) => c[0] === "checkout")).toBe(false);
     expect(calls.some((c) => c[0] === "merge")).toBe(false);
   });

package/extensions/orchestrator/event-handlers.ts

@@ -16,8 +16,8 @@ import {
   getArtifactManifest,
   loadPhaseReviewOutputs,
 } from "./context.js";
-import { PRINCIPLES_BLOCK, toolsBlock, identityBlock, delegationBlock } from "./agents/tool-routing.js";
-import { constraintsBlock, phaseConstraint } from "./agents/constraints.js";
+import { PRINCIPLES_BLOCK, IMPLEMENTATION_PRINCIPLES_BLOCK, toolsBlock, identityBlock, delegationBlock } from "./agents/tool-routing.js";
+import { constraintsBlock, phaseConstraint, isReadOnlyPhase } from "./agents/constraints.js";
 import { registerCbmTools } from "./cbm.js";
 import { registerExaTools } from "./exa.js";
 import { registerAstSearchTool } from "./ast-search.js";
@@ -564,11 +564,15 @@ function registerOrchestratorTools(orchestrator: Orchestrator): void {
 // Extension-side PR-head checkout for the review phase. Performed here (never via the
 // agent prompt) so REVIEW_READONLY_CONSTRAINT stays truthful — the agent never runs
 // `git checkout` itself. Lands the repo on its PR head under strict safety rules (no stash,
-// no --force, no branch switch, no worktree, no detached checkout): when the tree is clean
-// and on the PR head's branch but merely behind, it fast-forwards the branch to the head
-// (`git merge --ff-only`, which never detaches, never rewrites, and refuses a non-ff move).
-// A dirty tree, a different branch, or a non-fast-forwardable divergence all HALT with a
-// message for the user. Checking HEAD's SHA first makes this re-entrant and detached-safe.
+// no --force, no worktree, no detached checkout): when the tree is clean and on the PR head's
+// branch but merely behind, it fast-forwards the branch to the head (`git merge --ff-only`,
+// which never detaches, never rewrites, and refuses a non-ff move). When the tree is clean but
+// on a DIFFERENT branch, it fetches the PR head ref from origin (forced refspec into the
+// remote-tracking ref only), verifies the fetched tip equals the advertised oid, then fast-
+// forwards an existing local branch or creates a tracking branch at the oid and checks it out.
+// A dirty tree, a detached HEAD, a fork/unfetchable ref, an oid mismatch, or a non-fast-
+// forwardable divergence all HALT with a message for the user. Checking HEAD's SHA first makes
+// this re-entrant and detached-safe.
 export async function checkoutPrHead(
   orchestrator: Orchestrator,
   repoPath: string,
@@ -632,12 +636,91 @@ export async function checkoutPrHead(
     };
   }
   if (name && currentBranch !== name) {
-    return {
-      ok: false,
-      message:
-        `HALT: ${repoPath} is on "${currentBranch}", not the PR head branch "${name}" (target commit ${oid}). ` +
-        "Check out that branch at its PR head, then ask me to continue. I will not switch branches for you.",
-    };
+    // Clean tree on the wrong branch: switch to the PR head branch when it is
+    // provably safe. The tree is already known clean (checked above), so no
+    // stash is ever needed. We fetch the head ref, verify it matches the
+    // advertised oid, then either fast-forward an existing local branch to it
+    // or create a fresh tracking branch at it. Anything ambiguous HALTs.
+    if (!/^[^\s]+$/.test(name) || name.startsWith("-")) {
+      return {
+        ok: false,
+        message: `HALT: ${repoPath} PR head branch name "${name}" is not a safe ref to fetch. Bring the repo to its PR head (${oid}) yourself, then ask me to continue.`,
+      };
+    }
+    const fetchRes = await run(["fetch", "origin", `+refs/heads/${name}:refs/remotes/origin/${name}`]);
+    if (fetchRes.code !== 0) {
+      return {
+        ok: false,
+        message:
+          `HALT: ${repoPath} could not fetch PR head branch "${name}" from origin (a fork PR, or the branch is not on origin). ` +
+          `Fetch/add the correct remote and bring the repo to the PR head ${oid} yourself, then ask me to continue. I will not guess a remote for you.` +
+          `${fetchRes.stderr?.trim() ? `\n\n${fetchRes.stderr.trim()}` : ""}`,
+      };
+    }
+    let remoteTip;
+    try {
+      remoteTip = await run(["rev-parse", "--verify", `refs/remotes/origin/${name}`]);
+    } catch (err: any) {
+      return { ok: false, message: `Cannot resolve origin/${name} in ${repoPath} after fetch: ${err?.message ?? "git rev-parse failed"}` };
+    }
+    if (remoteTip.code !== 0 || remoteTip.stdout.trim() !== oid) {
+      return {
+        ok: false,
+        message:
+          `HALT: ${repoPath} fetched origin/${name} is ${remoteTip.stdout.trim() || "unresolvable"}, not the advertised PR head ${oid}. ` +
+          "The PR head may have moved or lives on a fork. Bring the repo to the exact PR head yourself, then ask me to continue.",
+      };
+    }
+    const localExists = (await run(["rev-parse", "--verify", "--quiet", `refs/heads/${name}`])).code === 0;
+    if (localExists) {
+      // Prove the fast-forward is safe BEFORE moving HEAD: if the local branch tip
+      // is not an ancestor of the PR head, it has diverged and we must HALT while
+      // the user is still on their original branch (never switch then fail).
+      const localTip = await run(["rev-parse", "--verify", `refs/heads/${name}`]);
+      const ancestry = await run(["merge-base", "--is-ancestor", localTip.stdout.trim(), oid]);
+      if (ancestry.code !== 0) {
+        return {
+          ok: false,
+          message:
+            `HALT: ${repoPath} local branch "${name}" cannot fast-forward to PR head ${oid} — it has diverged. ` +
+            "Reconcile it with the PR head, then ask me to continue. I will not force-move or rebase it for you.",
+        };
+      }
+      const co = await run(["checkout", name]);
+      if (co.code !== 0) {
+        return { ok: false, message: `HALT: ${repoPath} could not check out "${name}": ${co.stderr?.trim() || "git checkout failed"}. Resolve it, then ask me to continue.` };
+      }
+      const ffSwitch = await run(["merge", "--ff-only", oid]);
+      if (ffSwitch.code !== 0) {
+        return {
+          ok: false,
+          message:
+            `HALT: ${repoPath} local branch "${name}" cannot fast-forward to PR head ${oid} — it has diverged. ` +
+            "Reconcile it with the PR head, then ask me to continue. I will not force-move or rebase it for you." +
+            `${ffSwitch.stderr?.trim() ? `\n\n${ffSwitch.stderr.trim()}` : ""}`,
+        };
+      }
+    } else {
+      const co = await run(["checkout", "-b", name, "--track", `refs/remotes/origin/${name}`]);
+      if (co.code !== 0) {
+        return { ok: false, message: `HALT: ${repoPath} could not create tracking branch "${name}" at the PR head: ${co.stderr?.trim() || "git checkout -b failed"}. Resolve it, then ask me to continue.` };
+      }
+    }
+    let switched;
+    try {
+      switched = await run(["rev-parse", "HEAD"]);
+    } catch (err: any) {
+      return { ok: false, message: `Cannot confirm HEAD of ${repoPath} after switching to "${name}": ${err?.message ?? "git rev-parse failed"}` };
+    }
+    if (switched.stdout.trim() !== oid) {
+      return {
+        ok: false,
+        message:
+          `HALT: ${repoPath} is on "${name}" but at ${switched.stdout.trim()}, not the PR head ${oid}. ` +
+          "Bring it to the exact PR head yourself, then ask me to continue.",
+      };
+    }
+    return { ok: true, message: `${repoPath} switched to PR head branch "${name}" at ${oid}.` };
   }
 
   // Clean tree, on the PR head's branch, but behind: advance the branch to the head with a
@@ -690,10 +773,13 @@ function registerCheckoutPrHeadTool(orchestrator: Orchestrator): void {
       "Call this ONLY for a PR-scoped review, once per repo, AFTER you have resolved the PR " +
       "(e.g. via `gh pr view --json headRefName,headRefOid`). Do NOT call it for a branch, " +
       "commit-range, or uncommitted-changes review. The extension does this safely (no worktree, " +
-      "no stash, no --force, no branch switch, no detached checkout): a clean repo already on the " +
+      "no stash, no --force, no detached checkout): a clean repo already on the " +
       "PR head succeeds; a clean repo on the PR head's branch but behind is fast-forwarded to the " +
-      "head; a dirty tree, a different branch, or a diverged branch HALTS with a message for you to " +
-      "relay to the user. You never run `git checkout` yourself.",
+      "head; a clean repo on a DIFFERENT branch is switched to the PR head branch only after fetching " +
+      "origin and verifying the fetched tip matches the advertised commit (fast-forwarding an existing " +
+      "local branch or creating a tracking one); a dirty tree, a detached HEAD, a fork/unfetchable ref, " +
+      "an oid mismatch, or a diverged branch HALTS with a message for you to relay to the user. You " +
+      "never run `git checkout` yourself.",
     parameters: Type.Object({
       repoPath: Type.String({ description: "Absolute path to the registered repository" }),
       headRefName: Type.String({ description: "PR head branch name (headRefName)" }),
@@ -937,6 +1023,37 @@ function registerCommitTool(orchestrator: Orchestrator): void {
   });
 }
 
+// Returns a one-time reconcile directive on the first pp_phase_complete of a
+// phase, null on the acknowledging re-call. Bounded to one round-trip so
+// autonomous runs never loop.
+function maybePromptReconcile(orchestrator: Orchestrator): string | null {
+  const active = orchestrator.active;
+  if (!active) return null;
+  const phase = active.state.phase;
+  if (phase === "quick") return null;
+
+  if (active.state.reconciledPhase === phase && !active.state.reconcilePending) {
+    return null;
+  }
+  const alreadyPrompted = active.state.reconcilePromptedPhase === phase && !active.state.reconcilePending;
+  if (alreadyPrompted) {
+    active.state.reconciledPhase = phase;
+    active.state.reconcilePending = false;
+    saveTask(active.dir, active.state);
+    return null;
+  }
+  active.state.reconcilePromptedPhase = phase;
+  active.state.reconcilePending = false;
+  saveTask(active.dir, active.state);
+  return (
+    "Before finishing this phase, reconcile the task's state files with everything you've learned so far: " +
+    "update USER_REQUEST.md, RESEARCH.md, the active synthesized plan, and any artifacts/*.md you own so a " +
+    "freshly-spawned planner or reviewer (which only sees these files) is not working from a stale snapshot. " +
+    "Use pp_write_state_file / pp_edit_state_file. Then call pp_phase_complete again to proceed — if nothing " +
+    "needed changing, just call it again. (This one-time reconcile check runs once per phase.)"
+  );
+}
+
 function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
   const pi = orchestrator.pi;
 
@@ -961,6 +1078,12 @@ function registerPhaseCompleteTool(orchestrator: Orchestrator): void {
         const count = orchestrator.spawnedAgentIds.size + orchestrator.pendingSubagentSpawns;
         return { content: [{ type: "text" as const, text: `${count} subagent(s) still running. Wait for them to complete before calling pp_phase_complete.` }], isError: true as const, details: {} };
       }
+
+      const reconcileDirective = maybePromptReconcile(orchestrator);
+      if (reconcileDirective) {
+        return { content: [{ type: "text" as const, text: reconcileDirective }], details: {} };
+      }
+
       // Gate on the effective PHASE mode, not the task mode: brainstorm/debug/
       // review are always user-driven even for an autonomous task, so they must
       // fall through to the guided menu path below rather than auto-advancing.
@@ -1441,6 +1564,18 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     }
   }
 
+  // Mark ONE agent's record consumed. The subagents:completed event is emitted
+  // synchronously from pi-subagents' onComplete callback BEFORE it checks
+  // record.resultConsumed to decide whether to send the individual nudge, so
+  // setting the flag here (during the event) suppresses the per-agent nudge for
+  // a phased-batch member whose completion is instead reported by the single
+  // aggregated signal once the whole batch finishes.
+  function markAgentConsumed(id: string): void {
+    const mgr = (globalThis as any)[Symbol.for("pi-subagents:manager")];
+    const record = mgr?.getRecord?.(id);
+    if (record) record.resultConsumed = true;
+  }
+
   function checkPlannerCompletion(): void {
     if (
       !orchestrator.active ||
@@ -1866,7 +2001,9 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
     // only completion signal.
     const step = orchestrator.active.state.step;
     const isPhasedBatch = step === "await_planners" || step === "await_reviewers";
-    if (!isPhasedBatch) {
+    if (isPhasedBatch) {
+      markAgentConsumed(data.id);
+    } else {
       const desc = data.description || data.type || data.id;
       const duration = data.durationMs ? `${(data.durationMs / 1000).toFixed(1)}s` : "";
       const tokens = data.tokens?.total ? `${data.tokens.total} tok` : "";
@@ -2134,7 +2271,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       // user's initiating prompt, collapse whitespace, and cap at ~700 chars so
       // the state file never holds an unbounded prompt. Only the genuine first
       // user prompt qualifies (not a [PI-PI] injection).
-      const GENERIC_DESCRIPTIONS = ["implement", "debug", "brainstorm", "review", "quick"];
+      const GENERIC_DESCRIPTIONS = ["implement", "brainstorm", "review", "quick"];
       if (GENERIC_DESCRIPTIONS.includes(orchestrator.active.state.description) && event.prompt) {
         // Collapse the whole multi-line prompt into one line (newlines → spaces)
         // so a request whose intent spans several lines isn't cut off at line 1;
@@ -2202,6 +2339,7 @@ export function registerEventHandlers(orchestrator: Orchestrator): void {
       identity,
       constraintsBlock(phase as Phase, effectiveMode),
       PRINCIPLES_BLOCK,
+      isReadOnlyPhase(phase as Phase) ? "" : IMPLEMENTATION_PRINCIPLES_BLOCK,
       toolsBlock(mainToolNames),
       delegation,
       projectContext,

package/extensions/orchestrator/flant-infra.more.test.ts

@@ -235,6 +235,61 @@ describe("updateFlantInfra", () => {
     expect([...pi.registered.keys()].sort()).toEqual(["pp-flant-anthropic", "pp-flant-openai"]);
   });
 
+  it("serves a fresh cache without re-fetching by default", async () => {
+    const dir = makeTempDir();
+    const cacheDir = join(dir, "extensions", "pp", "cache");
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(
+      join(cacheDir, "flant-models.json"),
+      JSON.stringify({
+        enabled: true,
+        cacheTTLDays: 7,
+        lastUpdated: new Date().toISOString(),
+        cachedFlantModels: ["claude-opus-4-8"],
+        cachedOpenRouterData: {},
+      }),
+      "utf-8",
+    );
+    process.env.FLANT_API_KEY = "flant-k";
+    const mod = await loadModule(dir);
+    const fetchFn = stubFetch(() => { throw new Error("should not fetch"); });
+    const res = await mod.updateFlantInfra(makePi());
+    expect(res.ok).toBe(true);
+    expect(res.models).toEqual(["claude-opus-4-8"]);
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+
+  it("force bypasses a fresh cache and re-fetches the model list", async () => {
+    const dir = makeTempDir();
+    const cacheDir = join(dir, "extensions", "pp", "cache");
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(
+      join(cacheDir, "flant-models.json"),
+      JSON.stringify({
+        enabled: true,
+        cacheTTLDays: 7,
+        lastUpdated: new Date().toISOString(),
+        cachedFlantModels: ["claude-opus-4-8"],
+        cachedOpenRouterData: {},
+      }),
+      "utf-8",
+    );
+    process.env.FLANT_API_KEY = "flant-k";
+    const mod = await loadModule(dir);
+    stubFetch((url: string) => {
+      if (url.includes("llm-api.flant.ru/v1/models")) {
+        return { ok: true, status: 200, json: async () => ({ data: [{ id: "sub/claude-fable-5" }, { id: "claude-fable-5" }] }) };
+      }
+      if (url.includes("openrouter.ai")) {
+        return { ok: true, status: 200, json: async () => ({ data: [] }) };
+      }
+      throw new Error(`unexpected ${url}`);
+    });
+    const res = await mod.updateFlantInfra(makePi(), { force: true });
+    expect(res.ok).toBe(true);
+    expect(res.models).toContain("sub/claude-fable-5");
+  });
+
   it("falls back to cached models when discovery throws", async () => {
     const dir = makeTempDir();
     const cacheDir = join(dir, "extensions", "pp", "cache");

package/extensions/orchestrator/flant-infra.test.ts

@@ -422,7 +422,6 @@ describe("flant-infra", () => {
 
     expect(config.agents.orchestrators.implement.model).toBe("pp-flant-anthropic/claude-opus-4-6");
     expect(config.agents.orchestrators.plan.model).toBe("pp-flant-anthropic/claude-opus-4-6");
-    expect(config.agents.orchestrators.debug.model).toBe("pp-flant-openai/gpt-5-4");
     expect(config.agents.orchestrators.brainstorm.model).toBe("pp-flant-anthropic/claude-opus-4-6");
     expect(config.agents.orchestrators.review.model).toBe("pp-flant-anthropic/claude-opus-4-6");
     expect(config.agents.subagents.simple.explore.model).toBe("pp-flant-openai/gemini-3-1-flash");
@@ -448,7 +447,6 @@ describe("flant-infra", () => {
     expect(config.agents.subagents.simple.task.model).toBe("pp-flant-anthropic-sub/sub/claude-opus-4-8");
     expect(config.agents.subagents.presetGroups.planners.presets.regular.agents.opus.model).toBe("pp-flant-anthropic-sub/sub/claude-opus-4-8");
     // Non-Claude roles stay on the openai (company-billed) provider
-    expect(config.agents.orchestrators.debug.model).toBe("pp-flant-openai/gpt-5-4");
     expect(config.agents.subagents.simple.explore.model).toBe("pp-flant-openai/gemini-3-1-flash");
     expect(config.agents.subagents.presetGroups.planners.presets.regular.agents.gpt.model).toBe("pp-flant-openai/gpt-5-4");
   });
@@ -541,7 +539,6 @@ describe("flant-infra", () => {
 
     expect(config.agents.orchestrators.implement.model).toBe("pp-flant-anthropic/claude-opus-4-7");
     expect(config.agents.orchestrators.plan.model).toBe("pp-flant-anthropic/claude-opus-4-7");
-    expect(config.agents.orchestrators.debug.model).toBe("pp-flant-openai/gpt-5-4");
     expect(config.agents.subagents.presetGroups.planners.presets.regular.agents.gemini.model).toBe("pp-flant-openai/gemini-3-1-pro");
     expect(config.agents.subagents.simple.explore.model).toBe("pp-flant-openai/gemini-3-1-flash-lite");
   });

package/extensions/orchestrator/flant-infra.ts

@@ -606,10 +606,10 @@ export function registerFlantProviders(
   const subscription = options.subscription ?? loadFlantSettings().subscription;
   let subModels: string[] = [];
   if (subscription) {
-    // The gateway only defines `sub/` model groups for a subset of claude
-    // models (e.g. no sub/claude-fable-5) — registering unconfirmed ones
-    // yields "Invalid model name" 400s. Model lists cached before the gateway
-    // exposed `sub/…` ids have none; fall back to all claude models then.
+    // The gateway defines `sub/` model groups for only some claude models —
+    // registering unconfirmed ones yields "Invalid model name" 400s. Model
+    // lists cached before the gateway exposed `sub/…` ids have none; fall back
+    // to all claude models then.
     const subEligible = subConfirmed.size > 0
       ? anthropicModels.filter((m) => subConfirmed.has(m))
       : anthropicModels;
@@ -786,7 +786,6 @@ export function generateFlantConfig(models: string[], subscriptionActive = false
       orchestrators: {
         implement: { model: modelSpec(implementModel, sub(implementModel)), thinking: "high" },
         plan: { model: modelSpec(implementModel, sub(implementModel)), thinking: "high" },
-        debug: { model: modelSpec(debugModel, sub(debugModel)), thinking: "high" },
         brainstorm: { model: modelSpec(brainstormModel, sub(brainstormModel)), thinking: "high" },
         review: { model: modelSpec(implementModel, sub(implementModel)), thinking: "high" },
         quick: { model: modelSpec(implementModel, sub(implementModel)), thinking: "high" },
@@ -899,8 +898,18 @@ export function getFlantGeneratedConfig(): Partial<PiPiConfig> | null {
 
 (globalThis as any)[Symbol.for("pi-pi:flant-config")] = getFlantGeneratedConfig;
 
+export interface UpdateFlantOptions {
+  /**
+   * Bypass the TTL cache and re-fetch the model list from the gateway even when
+   * the cache is still fresh. Set by the explicit "Update now" action so it does
+   * what its label promises; auto/startup callers omit it and stay cache-bound.
+   */
+  force?: boolean;
+}
+
 export async function updateFlantInfra(
   pi: ExtensionAPI,
+  options: UpdateFlantOptions = {},
 ): Promise<{ ok: boolean; error?: string; models?: string[] }> {
   setPI(pi);
   const settings = loadFlantSettings();
@@ -911,8 +920,9 @@ export async function updateFlantInfra(
     await refreshClaudeOAuthToken();
   }
 
-  let models = isCacheValid(settings) ? settings.cachedFlantModels : null;
-  let metadata = isCacheValid(settings) ? settings.cachedOpenRouterData : null;
+  const cacheOk = !options.force && isCacheValid(settings);
+  let models = cacheOk ? settings.cachedFlantModels : null;
+  let metadata = cacheOk ? settings.cachedOpenRouterData : null;
   let refreshed = false;
 
   if (!models || !metadata) {