@ilya-lesikov/pi-pi 0.7.0 → 0.8.0

package/extensions/orchestrator/pp-menu.ts

@@ -27,7 +27,8 @@ import {
 } from "./context.js";
 import { detectDefaultBranch, enterReviewCycle, finalizeReviewCycle } from "./event-handlers.js";
 import { Orchestrator } from "./orchestrator.js";
-import { cancelPendingPlannotatorWait } from "./plannotator.js";
+import { cancelPendingPlannotatorWait, openPlannotator, waitForPlannotatorResult } from "./plannotator.js";
+import { advanceBanner } from "./messages.js";
 import { spawnPlanners, spawnPlanReviewers } from "./phases/planning.js";
 import { spawnCodeReviewers } from "./phases/review.js";
 import { spawnBrainstormReviewers } from "./phases/brainstorm.js";
@@ -225,6 +226,44 @@ async function pickCommitForRepo(orchestrator: Orchestrator, ctx: any, repo: Rep
   return pickedHash || null;
 }
 
+async function repoHasReviewableChanges(
+  orchestrator: Orchestrator,
+  repo: RepoInfo,
+  base: string,
+): Promise<{ changed: boolean; error?: string }> {
+  const run = async (args: string[]): Promise<{ out: string; failed: boolean }> => {
+    try {
+      const res = await orchestrator.pi.exec("git", args, { cwd: repo.path, timeout: 5000 });
+      if (res.code !== 0) return { out: "", failed: true };
+      return { out: res.stdout, failed: false };
+    } catch {
+      return { out: "", failed: true };
+    }
+  };
+
+  const committed = await run(["diff", "--name-only", `${base}...HEAD`]);
+  const unstaged = await run(["diff", "--name-only"]);
+  const staged = await run(["diff", "--cached", "--name-only"]);
+  const status = await run(["status", "--porcelain"]);
+
+  const hasCommitted = committed.out.trim().length > 0;
+  const hasUnstaged = unstaged.out.trim().length > 0;
+  const hasStaged = staged.out.trim().length > 0;
+  const hasUntracked = status.out.split("\n").some((line) => line.startsWith("??"));
+  const changed = hasCommitted || hasUnstaged || hasStaged || hasUntracked;
+
+  if (changed) return { changed: true };
+
+  // No change detected — but a failed probe (e.g. a missing/invalid base ref)
+  // could be masking real changes, so surface it rather than silently hiding
+  // the repo.
+  if (committed.failed || unstaged.failed || staged.failed || status.failed) {
+    return { changed: false, error: "git status/diff failed" };
+  }
+
+  return { changed: false };
+}
+
 interface RepoPrContext {
   repoPath: string;
   prUrl: string | null;
@@ -252,6 +291,11 @@ function showStatus(orchestrator: Orchestrator, ctx: any): void {
 }
 
 async function abortCurrentWork(orchestrator: Orchestrator, ctx: any): Promise<void> {
+  // Clear pi-pi's own delayed post-error retry (timer + ESC interrupt). Unlike
+  // pause/finish, abortCurrentWork does NOT go through cleanupActive/
+  // resetTaskScopedState, so without this a scheduled retry would survive the
+  // abort and re-nudge seconds later.
+  orchestrator.cancelPendingRetry();
   orchestrator.abortAllSubagents();
   orchestrator.transitionController.abortMainAgent(ctx.abort?.bind(ctx));
   await ctx.waitForIdle?.();
@@ -795,6 +839,9 @@ function collectRoleAssignments(config: Partial<PiPiConfig> | null): string[] {
   add("agents.subagents.simple.explore", config.agents?.subagents?.simple?.explore?.model);
   add("agents.subagents.simple.librarian", config.agents?.subagents?.simple?.librarian?.model);
   add("agents.subagents.simple.task", config.agents?.subagents?.simple?.task?.model);
+  add("agents.subagents.simple.advisor", config.agents?.subagents?.simple?.advisor?.model);
+  add("agents.subagents.simple.deep-debugger", config.agents?.subagents?.simple?.["deep-debugger"]?.model);
+  add("agents.subagents.simple.reviewer", config.agents?.subagents?.simple?.reviewer?.model);
   return out;
 }
 
@@ -814,6 +861,7 @@ function flantStatusText(settings: FlantSettings): string {
     lines.push(
       `Personal subscription: on (${subActive ? `active — pp-flant-anthropic-sub, ${providers.anthropic} models` : "inactive"})`,
     );
+    lines.push(`Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`);
     if (!subActive) {
       if (!hasOAuth) lines.push("  - missing Claude OAuth token (run pi /login for Anthropic)");
       if (!hasGatewayKey) lines.push("  - missing gateway key (set LLM_API_KEY or FLANT_API_KEY)");
@@ -849,15 +897,22 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
   while (true) {
     const settings = loadFlantSettings();
     const enableLabel = `Enable: ${settings.enabled ? "ON" : "OFF"}`;
-    const options: OptionInput[] = [enableLabel];
+    const options: OptionInput[] = [
+      { title: enableLabel, description: "Turn the Flant AI model providers on or off" },
+    ];
     const subscriptionLabel = `Personal Claude subscription: ${settings.subscription ? "ON" : "OFF"}`;
     if (settings.enabled) {
       options.push(
-        `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`,
-        `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`,
-        subscriptionLabel,
-        "Update now",
-        "Current status",
+        { title: subscriptionLabel, description: "Route Claude roles through your personal Claude subscription instead of the gateway" },
+        { title: `Auto-update on startup: ${settings.autoUpdate ? "ON" : "OFF"}`, description: "Refresh the available model list automatically each time pi starts" },
+        { title: `Cache period: ${settings.cacheTTLDays} ${settings.cacheTTLDays === 1 ? "day" : "days"}`, description: "How long the fetched model list is reused before it is refreshed" },
+      );
+      if (settings.subscription) {
+        options.push({ title: `Rate-limit switch-back check: every ${settings.switchBackIntervalMinutes} min`, description: "How often to retry your subscription after it was rate-limited and traffic fell back to the gateway" });
+      }
+      options.push(
+        { title: "Update now", description: "Fetch the latest model list from Flant right away" },
+        { title: "Current status", description: "Show the current Flant configuration, providers, and model counts" },
       );
     }
     options.push({ title: "Back", description: "Return to the previous menu" });
@@ -920,6 +975,22 @@ async function showFlantInfraMenu(orchestrator: Orchestrator, ctx: any): Promise
       continue;
     }
 
+    if (choice.startsWith("Rate-limit switch-back check:")) {
+      const selected = await selectOption(ctx, "Switch-back check interval", [
+        { title: "15 min", description: "Probe the subscription limit every 15 minutes" },
+        { title: "30 min", description: "Default — probe every 30 minutes" },
+        { title: "60 min", description: "Probe hourly" },
+        { title: "120 min", description: "Probe every two hours" },
+        { title: "Back", description: "Return to the previous menu" },
+      ]);
+      if (!selected || selected === "Back") continue;
+      const mins = Number(selected.split(" ")[0]);
+      if (!Number.isFinite(mins) || mins <= 0) continue;
+      saveFlantSettings({ ...settings, switchBackIntervalMinutes: mins });
+      ctx.ui.notify(`Switch-back check interval set to ${mins} min.`, "info");
+      continue;
+    }
+
     if (choice.startsWith("Cache period:")) {
       const selected = await selectOption(ctx, "Cache period", [
         { title: "1 day", description: "Refresh model metadata daily" },
@@ -1199,6 +1270,9 @@ const SUBAGENT_ROLES: Array<{ role: AgentRole; label: string; description: strin
   { role: "explore", label: "Explore", description: "agents.subagents.simple.explore" },
   { role: "librarian", label: "Librarian", description: "agents.subagents.simple.librarian" },
   { role: "task", label: "Task", description: "agents.subagents.simple.task" },
+  { role: "advisor", label: "Advisor", description: "agents.subagents.simple.advisor" },
+  { role: "deep-debugger", label: "Deep debugger", description: "agents.subagents.simple.deep-debugger" },
+  { role: "reviewer", label: "Reviewer", description: "agents.subagents.simple.reviewer" },
 ];
 
 const PRESET_GROUP_ITEMS: Array<{ group: PresetGroup; label: string }> = [
@@ -1924,7 +1998,7 @@ async function showPresetVariantEditor(
       continue;
     }
     if (choice.startsWith("Enabled:")) {
-      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"]);
+      await showBooleanSetting(orchestrator, ctx, "Enabled", [...variantPath, "enabled"], "Make this agent available for use", "Disable this agent so it is not used");
       continue;
     }
     const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -2065,8 +2139,8 @@ async function showPresetEnabledSetting(
   const yesTitle = withTags("Yes", formatSourceTags(true, info));
   const noTitle = withTags("No", formatSourceTags(false, info));
   const choice = await selectOption(ctx, "Enabled", [
-    yesTitle,
-    noTitle,
+    { title: yesTitle, description: "Make this preset available for selection" },
+    { title: noTitle, description: "Hide this preset so it can no longer be selected" },
     opt("Back", "Return to the previous menu"),
   ]);
   if (!choice || choice === "Back") return;
@@ -2247,7 +2321,7 @@ async function showAfterEditCommands(orchestrator: Orchestrator, ctx: any): Prom
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       if (commandChoice === "Triggers") {
@@ -2364,7 +2438,7 @@ async function showAfterImplementCommands(orchestrator: Orchestrator, ctx: any):
         continue;
       }
       if (commandChoice.startsWith("Enabled:")) {
-        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"]);
+        await showBooleanSetting(orchestrator, ctx, "Enabled", [...commandPath, "enabled"], "Run this command when its triggers fire", "Keep this command configured but stop running it");
         continue;
       }
       const confirm = await selectOption(ctx, "Confirm delete?", [
@@ -2487,14 +2561,16 @@ async function showBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(true, info));
     const noTitle = withTags("No", formatSourceTags(false, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2516,14 +2592,16 @@ async function showInvertedBooleanSetting(
   ctx: any,
   title: string,
   keyPath: string[],
+  yesDescription = "Turn this setting on",
+  noDescription = "Turn this setting off",
 ): Promise<void> {
   while (true) {
     const info = getConfigSourceInfo(orchestrator, keyPath);
     const yesTitle = withTags("Yes", formatSourceTags(false, info));
     const noTitle = withTags("No", formatSourceTags(true, info));
     const choice = await selectOption(ctx, title, [
-      yesTitle,
-      noTitle,
+      { title: yesTitle, description: yesDescription },
+      { title: noTitle, description: noDescription },
       ...buildResetOptions(orchestrator, keyPath),
       opt("Back", "Return to the previous menu"),
     ]);
@@ -2541,15 +2619,15 @@ async function showInvertedBooleanSetting(
 }
 
 async function showLogLevelSetting(orchestrator: Orchestrator, ctx: any): Promise<void> {
-  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string }> = [
-    { value: "debug", label: "Debug" },
-    { value: "info", label: "Info" },
-    { value: "warn", label: "Warning" },
-    { value: "error", label: "Error" },
+  const levels: Array<{ value: PiPiConfig["general"]["logLevel"]; label: string; description: string }> = [
+    { value: "debug", label: "Debug", description: "Log everything, including detailed diagnostics for troubleshooting" },
+    { value: "info", label: "Info", description: "Log normal activity plus warnings and errors" },
+    { value: "warn", label: "Warning", description: "Log only warnings and errors" },
+    { value: "error", label: "Error", description: "Log only errors" },
   ];
   while (true) {
     const info = getConfigSourceInfo(orchestrator, ["general", "logLevel"]);
-    const options: OptionInput[] = levels.map((entry) => withTags(entry.label, formatSourceTags(entry.value, info)));
+    const options: OptionInput[] = levels.map((entry) => ({ title: withTags(entry.label, formatSourceTags(entry.value, info)), description: entry.description }));
     options.push(...buildResetOptions(orchestrator, ["general", "logLevel"]));
     options.push(opt("Back", "Return to the previous menu"));
     const choice = await selectOption(ctx, "Log level", options);
@@ -2579,11 +2657,11 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
     ]);
     if (!choice || choice === "Back") return BACK;
     if (choice.startsWith("Commit automatically:")) {
-      await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"]);
+      await showBooleanSetting(orchestrator, ctx, "Commit automatically", ["general", "autoCommit"], "Commit changes automatically as work progresses", "Leave committing to you");
       continue;
     }
     if (choice.startsWith("Ignore configs from other repos:")) {
-      await showInvertedBooleanSetting(orchestrator, ctx, "Ignore configs from other repos", ["general", "loadExtraRepoConfigs"]);
+      await showInvertedBooleanSetting(orchestrator, ctx, "Ignore configs from other repos", ["general", "loadExtraRepoConfigs"], "Use only the root repo config and ignore configs from other registered repos", "Also load configs from the other registered repos");
       continue;
     }
     if (choice.startsWith("Log level:")) {
@@ -2591,7 +2669,7 @@ async function showGeneralSettings(orchestrator: Orchestrator, ctx: any): Promis
       continue;
     }
     if (choice.startsWith("Tracing:")) {
-      await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"]);
+      await showBooleanSetting(orchestrator, ctx, "Tracing", ["general", "tracing"], "Capture full session traces to .pp/logs/traces/", "Do not record session traces");
       continue;
     }
     await showFlantInfraMenu(orchestrator, ctx);
@@ -3056,30 +3134,24 @@ async function openCodeReviewInPlannotator(
   if (payload.diffType) requestPayload.diffType = payload.diffType;
   if (payload.defaultBranch) requestPayload.defaultBranch = payload.defaultBranch;
 
-  return await new Promise((resolve) => {
-    let handled = false;
-    const timer = setTimeout(() => {
-      if (!handled) resolve({ status: "error", error: "Plannotator is not available." });
-    }, 30000);
-    orchestrator.pi.events.emit("plannotator:request", {
-      requestId: crypto.randomUUID(),
-      action: "code-review",
-      payload: requestPayload,
-      respond: (response: any) => {
-        handled = true;
-        clearTimeout(timer);
-        if (response?.status !== "handled") {
-          resolve({ status: "error", error: response?.error || "Plannotator is not available." });
-          return;
-        }
-        const approved = !!response?.result?.approved;
-        const feedback = typeof response?.result?.feedback === "string" && response.result.feedback.trim().length > 0
-          ? response.result.feedback
-          : undefined;
-        resolve({ status: approved ? "approved" : "needs_changes", feedback });
-      },
-    });
-  });
+  const { opened, reviewId } = await openPlannotator(orchestrator.pi, "code-review", requestPayload);
+  if (!opened) {
+    return { status: "error", error: "Plannotator is not available." };
+  }
+
+  let result: { approved: boolean; feedback?: string; error?: string };
+  try {
+    result = await waitForPlannotatorResult(orchestrator, reviewId, null);
+  } catch (err) {
+    return { status: "error", error: err instanceof Error ? err.message : "Plannotator review failed." };
+  }
+  if (result.error) {
+    return { status: "error", error: result.error };
+  }
+  const feedback = typeof result.feedback === "string" && result.feedback.trim().length > 0
+    ? result.feedback
+    : undefined;
+  return { status: result.approved ? "approved" : "needs_changes", feedback };
 }
 
 async function startReviewTask(
@@ -3435,7 +3507,7 @@ export async function showActiveTaskMenu(
   summary: string,
   mode: MenuMode = "command",
 ): Promise<string> {
-  const continueMessage = "User wants to continue. Run /pp when ready to advance.";
+  const continueMessage = advanceBanner("[PI-PI] User wants to continue. Run /pp when ready to advance.");
 
   while (true) {
     if (!orchestrator.active) return "No active task.";
@@ -3575,7 +3647,9 @@ export async function showActiveTaskMenu(
       if (hasPlannotator) {
         reviewOptions.push(opt("Review in Plannotator", phase === "plan" ? "Open plan review in browser" : "Open code diff review in browser"));
       }
-      reviewOptions.push(opt("Review on my own", "Review manually, then continue"));
+      reviewOptions.push(opt("Review on my own", phase === "implement"
+        ? "Review in your editor: mark spots with AI_REVIEW: comments, then have the agent address them"
+        : "Review manually, then continue"));
       reviewOptions.push(opt("Back", "Return to the previous menu"));
 
       const reviewChoice = await selectOption(ctx, "Review", reviewOptions);
@@ -3591,8 +3665,23 @@ export async function showActiveTaskMenu(
           if (handled.continueLoop) continue;
           return handled.text ?? text;
         }
-        const repos = getRegisteredRepos(orchestrator);
+        const allRepos = getRegisteredRepos(orchestrator);
         const summaries: string[] = [];
+        const repos: RepoInfo[] = [];
+        for (const repo of allRepos) {
+          const base = await detectDefaultBranch(orchestrator, allRepos, repo.path);
+          const { changed, error } = await repoHasReviewableChanges(orchestrator, repo, base);
+          if (error) {
+            summaries.push(`${formatRepoLabel(repo)}: ERROR — ${error}`);
+            repos.push(repo);
+          } else if (changed) {
+            repos.push(repo);
+          }
+        }
+        if (repos.length === 0) {
+          ctx.ui.notify("No registered repositories have changes to review.", "info");
+          continue;
+        }
         let stopReviewing = false;
 
         for (const repo of repos) {
@@ -3661,10 +3750,35 @@ export async function showActiveTaskMenu(
       if (reviewChoice === "Review on my own") {
         if (phase === "plan") {
           setStep(orchestrator, "synthesize");
-        } else {
+          return continueMessage;
+        }
+        if (phase !== "implement") {
           setStep(orchestrator, "llm_work");
+          return continueMessage;
         }
-        return continueMessage;
+
+        const gate = await selectOption(ctx, "Editor review", [
+          opt("Done", "I've added AI_REVIEW: markers and saved my files"),
+          opt("Skip markers", "Continue without the marker workflow"),
+          opt("Back", "Return to the review menu"),
+        ]);
+        if (!gate || gate === "Back") continue;
+        setStep(orchestrator, "llm_work");
+        if (gate === "Skip markers") {
+          return continueMessage;
+        }
+        return advanceBanner(
+          "[PI-PI] The user reviewed the changes in their editor and left inline `AI_REVIEW:` markers " +
+          "(inside each file's native comment syntax, e.g. `// AI_REVIEW: ...`, `# AI_REVIEW: ...`, " +
+          "`<!-- AI_REVIEW: ... -->`).\n\n" +
+          "For each registered repo, enumerate the CHANGED files only — union of `git diff --name-only <base>...HEAD`, " +
+          "`git diff --name-only`, `git diff --cached --name-only`, and untracked-non-ignored files from `git status --porcelain` " +
+          "(base = each repo's configured base branch) — and search WITHIN those files for `AI_REVIEW:`. Do NOT grep the whole " +
+          "worktree (avoid vendored/generated/node_modules and historical markers).\n\n" +
+          "For each marker: address the request, then remove that marker in the SAME edit. After a pass, re-scan the changed " +
+          "files and repeat until no `AI_REVIEW:` markers remain. Then verify your work and report what you changed per marker. " +
+          "When complete, call pp_phase_complete.",
+        );
       }
 
       const reviewPreset = await pickPreset(ctx, orchestrator, getReviewPresetGroup(phase), "Review preset");

package/extensions/orchestrator/pp-state-tools.test.ts

@@ -0,0 +1,192 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./log.js", () => ({
+  getLogger: () => ({ debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() }),
+}));
+
+import { registerStateFileTools } from "./pp-state-tools.js";
+
+const tempDirs: string[] = [];
+
+function makeTempCwd(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-state-tools-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+interface RegisteredTool {
+  name: string;
+  execute: (id: string, params: any) => Promise<any>;
+}
+
+function setup() {
+  const cwd = makeTempCwd();
+  const taskDir = join(cwd, ".pp", "state", "brainstorm", "abc_brainstorm");
+  mkdirSync(join(taskDir, "artifacts"), { recursive: true });
+  mkdirSync(join(taskDir, "plans"), { recursive: true });
+
+  const tools = new Map<string, RegisteredTool>();
+  const orchestrator: any = {
+    cwd,
+    active: { dir: taskDir },
+    pi: { registerTool: (t: RegisteredTool) => tools.set(t.name, t) },
+  };
+  registerStateFileTools(orchestrator);
+  return { cwd, taskDir, orchestrator, tools };
+}
+
+function textOf(result: any): string {
+  return (result.content ?? []).map((c: any) => c.text).join("\n");
+}
+
+const VALID_RESEARCH = [
+  "## Affected Code",
+  "- foo.ts:bar — does a thing",
+  "## Architecture Context",
+  "- how it connects",
+  "## Constraints & Edge Cases",
+  "- MUST: keep it working",
+].join("\n");
+
+describe("pp_write_state_file", () => {
+  it("creates a valid RESEARCH.md and returns compact output (no diff)", async () => {
+    const { taskDir, tools } = setup();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "RESEARCH.md", content: VALID_RESEARCH });
+    expect(res.isError).toBeFalsy();
+    expect(res.details).toEqual({});
+    expect(textOf(res)).toMatch(/^Created RESEARCH\.md \(\+\d+\/-\d+ lines\)$/);
+    expect(textOf(res)).not.toContain("Affected Code");
+    expect(readFileSync(join(taskDir, "RESEARCH.md"), "utf-8")).toBe(VALID_RESEARCH);
+  });
+
+  it("reports 'Updated' on overwrite", async () => {
+    const { tools } = setup();
+    await tools.get("pp_write_state_file")!.execute("1", { path: "RESEARCH.md", content: VALID_RESEARCH });
+    const res = await tools.get("pp_write_state_file")!.execute("2", { path: "RESEARCH.md", content: VALID_RESEARCH + "\n- more" });
+    expect(textOf(res)).toMatch(/^Updated RESEARCH\.md/);
+  });
+
+  it("rejects invalid RESEARCH.md structure without writing", async () => {
+    const { taskDir, tools } = setup();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "RESEARCH.md", content: "## Wrong Section\nx" });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain("RESEARCH.md structure is invalid");
+    expect(() => readFileSync(join(taskDir, "RESEARCH.md"), "utf-8")).toThrow();
+  });
+
+  it("accepts an artifact starting with a top-level heading", async () => {
+    const { tools } = setup();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "artifacts/design.md", content: "# Design\n\nbody" });
+    expect(res.isError).toBeFalsy();
+    expect(textOf(res)).toMatch(/artifacts\/design\.md/);
+  });
+
+  it("rejects a path escaping the task dir", async () => {
+    const { tools } = setup();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "../../../evil.md", content: "# x" });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toMatch(/escapes the active task directory/);
+  });
+
+  it("rejects a non-.md file", async () => {
+    const { tools } = setup();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "notes.txt", content: "x" });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toMatch(/Only \.md/);
+  });
+
+  it("rejects managed review outputs and non-synthesized plans", async () => {
+    const { tools } = setup();
+    for (const p of [
+      "code-reviews/1_gpt.md",
+      "brainstorm-reviews/1_gemini.md",
+      "plan-reviews/1_opus.md",
+      "plans/1_gpt.md",
+      "scratch.md",
+      "artifacts/nested/deep.md",
+    ]) {
+      const res = await tools.get("pp_write_state_file")!.execute("1", { path: p, content: "# x" });
+      expect(res.isError, `expected ${p} to be rejected`).toBe(true);
+      expect(textOf(res)).toMatch(/Not an editable state file/);
+    }
+  });
+
+  it("allows the synthesized plan", async () => {
+    const { tools } = setup();
+    const plan = [
+      "# Plan",
+      "## Scope",
+      "Do the thing.",
+      "## Checklist",
+      "- [ ] item — Done when: it works",
+    ].join("\n");
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "plans/123_synthesized.md", content: plan });
+    expect(res.isError).toBeFalsy();
+    expect(textOf(res)).toMatch(/plans\/123_synthesized\.md/);
+  });
+});
+
+describe("pp_edit_state_file", () => {
+  beforeEach(() => {});
+
+  it("replaces a unique span and returns compact output", async () => {
+    const { taskDir, tools } = setup();
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    const res = await tools.get("pp_edit_state_file")!.execute("1", {
+      path: "RESEARCH.md",
+      oldText: "does a thing",
+      newText: "does a different thing",
+    });
+    expect(res.isError).toBeFalsy();
+    expect(textOf(res)).toMatch(/^Updated RESEARCH\.md \(\+\d+\/-\d+ lines\)$/);
+    expect(readFileSync(join(taskDir, "RESEARCH.md"), "utf-8")).toContain("does a different thing");
+  });
+
+  it("errors when oldText is not found", async () => {
+    const { taskDir, tools } = setup();
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    const res = await tools.get("pp_edit_state_file")!.execute("1", { path: "RESEARCH.md", oldText: "nope", newText: "x" });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toMatch(/not found/);
+  });
+
+  it("errors on ambiguous oldText unless replaceAll", async () => {
+    const { taskDir, tools } = setup();
+    // Use an artifact (an allowed, unstructured-body state file) with duplicate spans.
+    writeFileSync(join(taskDir, "artifacts", "dup.md"), "# Dup\nx\nx\n", "utf-8");
+    const ambiguous = await tools.get("pp_edit_state_file")!.execute("1", { path: "artifacts/dup.md", oldText: "x", newText: "y" });
+    expect(ambiguous.isError).toBe(true);
+    expect(textOf(ambiguous)).toMatch(/matches 2 locations/);
+
+    const all = await tools.get("pp_edit_state_file")!.execute("2", { path: "artifacts/dup.md", oldText: "x", newText: "y", replaceAll: true });
+    expect(all.isError).toBeFalsy();
+    expect(readFileSync(join(taskDir, "artifacts", "dup.md"), "utf-8")).toBe("# Dup\ny\ny\n");
+  });
+
+  it("errors when the file does not exist", async () => {
+    const { tools } = setup();
+    const res = await tools.get("pp_edit_state_file")!.execute("1", { path: "RESEARCH.md", oldText: "a", newText: "b" });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toMatch(/does not exist/);
+  });
+
+  it("rejects an edit that breaks structure without writing", async () => {
+    const { taskDir, tools } = setup();
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    const res = await tools.get("pp_edit_state_file")!.execute("1", {
+      path: "RESEARCH.md",
+      oldText: "## Affected Code",
+      newText: "## Renamed Section",
+    });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain("RESEARCH.md structure is invalid");
+    expect(readFileSync(join(taskDir, "RESEARCH.md"), "utf-8")).toContain("## Affected Code");
+  });
+});