@ilya-lesikov/pi-pi 0.9.0 → 0.10.0

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

@@ -24,8 +24,13 @@ afterEach(() => {
 interface RegisteredTool {
   name: string;
   execute: (id: string, params: any) => Promise<any>;
+  renderShell?: string;
+  renderCall?: (args: any, theme: any, context: any) => any;
+  renderResult?: (result: any, options: any, theme: any, context: any) => any;
 }
 
+const theme = { fg: (_c: string, t: string) => t } as any;
+
 function setup() {
   const cwd = makeTempCwd();
   const taskDir = join(cwd, ".pp", "state", "brainstorm", "abc_brainstorm");
@@ -190,3 +195,78 @@ describe("pp_edit_state_file", () => {
     expect(readFileSync(join(taskDir, "RESEARCH.md"), "utf-8")).toContain("## Affected Code");
   });
 });
+
+describe("state-file tool rendering (hidden on success, visible on failure/hang)", () => {
+  for (const name of ["pp_write_state_file", "pp_edit_state_file"]) {
+    it(`${name} owns its shell and renders nothing on a settled (non-partial) call`, () => {
+      const { tools } = setup();
+      const tool = tools.get(name)!;
+      expect(tool.renderShell).toBe("self");
+      const callComp = tool.renderCall!({}, theme, { isPartial: false });
+      expect(callComp.render(80)).toEqual([]);
+    });
+
+    it(`${name} renders a visible line for an in-flight (partial) call — hang visibility`, () => {
+      const { tools } = setup();
+      const tool = tools.get(name)!;
+      const callComp = tool.renderCall!({}, theme, { isPartial: true });
+      expect(callComp.render(80).length).toBe(1);
+    });
+
+    it(`${name} renders nothing on a successful result`, () => {
+      const { tools } = setup();
+      const tool = tools.get(name)!;
+      const comp = tool.renderResult!({ content: [{ type: "text", text: "Created X" }] }, { isPartial: false }, theme, { isError: false });
+      expect(comp.render(80)).toEqual([]);
+    });
+
+    it(`${name} renders a visible line while partial (hang)`, () => {
+      const { tools } = setup();
+      const tool = tools.get(name)!;
+      const comp = tool.renderResult!({ content: [] }, { isPartial: true }, theme, { isError: false });
+      expect(comp.render(80).length).toBe(1);
+    });
+
+    it(`${name} renders a visible line on error`, () => {
+      const { tools } = setup();
+      const tool = tools.get(name)!;
+      const comp = tool.renderResult!({ content: [{ type: "text", text: "boom" }], isError: true }, { isPartial: false }, theme, { isError: true });
+      const rows = comp.render(80);
+      expect(rows.length).toBe(1);
+      expect(rows[0]).toContain("boom");
+    });
+  }
+});
+
+describe("state-file writes invalidate a clean review (review pass 3)", () => {
+  function setupWithState() {
+    const cwd = makeTempCwd();
+    const taskDir = join(cwd, ".pp", "state", "brainstorm", "abc_brainstorm");
+    mkdirSync(join(taskDir, "artifacts"), { recursive: true });
+    const tools = new Map<string, RegisteredTool>();
+    const state: any = { reviewApprovedClean: true };
+    const orchestrator: any = {
+      cwd,
+      active: { dir: taskDir, state },
+      pi: { registerTool: (t: RegisteredTool) => tools.set(t.name, t) },
+    };
+    registerStateFileTools(orchestrator);
+    return { taskDir, tools, state };
+  }
+
+  it("pp_write_state_file clears reviewApprovedClean", async () => {
+    const { tools, state } = setupWithState();
+    const res = await tools.get("pp_write_state_file")!.execute("1", { path: "RESEARCH.md", content: VALID_RESEARCH });
+    expect(res.isError).toBeFalsy();
+    expect(state.reviewApprovedClean).toBe(false);
+  });
+
+  it("pp_edit_state_file clears reviewApprovedClean", async () => {
+    const { taskDir, tools, state } = setupWithState();
+    writeFileSync(join(taskDir, "RESEARCH.md"), VALID_RESEARCH, "utf-8");
+    state.reviewApprovedClean = true;
+    const res = await tools.get("pp_edit_state_file")!.execute("1", { path: "RESEARCH.md", oldText: "does a thing", newText: "does another thing" });
+    expect(res.isError).toBeFalsy();
+    expect(state.reviewApprovedClean).toBe(false);
+  });
+});

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

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
 import { Type } from "@sinclair/typebox";
+import { Container, Text, type Component } from "@earendil-works/pi-tui";
 import type { Orchestrator } from "./orchestrator.js";
+import { saveTask } from "./state.js";
 import { getLogger } from "./log.js";
 import {
   validateArtifact,
@@ -147,12 +149,67 @@ function validationError(label: string, errors: string[], hint: string): ToolRes
   );
 }
 
+// Minimal-on-success rendering for the state-file tools. With renderShell:"self"
+// the tool owns its inner framing: renderCall shows a line only while the call is
+// in flight (isPartial) so a HANG is visible, and renders nothing once settled;
+// renderResult renders nothing on success and a visible line on failure/hang.
+// Net on success: no tool title, no args echo, no diff, no result text.
+// NOTE: the host ToolExecutionComponent still prepends one unconditional
+// Spacer(1) and treats any returned renderer as "content" (so its full
+// hideComponent collapse path is not taken), meaning a successful write leaves at
+// most a single blank line rather than truly zero rows. That is the intended
+// fallback: it eliminates the full-file/diff "state-file spam" while keeping a
+// hang (isPartial) or failure (isError) visible with an explicit line. Fully
+// removing the residual blank line would require an upstream host change (the
+// Spacer is host-owned).
+function emptyComponent(): Component {
+  return new Container();
+}
+
+function lineComponent(text: string): Component {
+  const c = new Container();
+  c.addChild(new Text(text, 0, 0));
+  return c;
+}
+
+function renderStateCall(_args: unknown, theme: any, context: any): Component {
+  // The host re-runs BOTH renderCall and renderResult every cycle and stacks
+  // their output, so renderCall must stay empty once a result exists — otherwise
+  // a "Saving state…" line would persist onto a successful (silent) write. While
+  // the call is still in flight (isPartial, no final result yet) we DO show the
+  // line, so a genuine HANG before any result is visible. context.isPartial is
+  // true during execution and set false when the final result arrives.
+  if (context?.isPartial) return lineComponent(theme.fg("warning", "◆ [PI-PI] Saving state…"));
+  return emptyComponent();
+}
+
+function renderStateResult(result: ToolResult, options: { isPartial?: boolean }, theme: any, context: any): Component {
+  if (options?.isPartial) return lineComponent(theme.fg("warning", "◆ [PI-PI] Saving state…"));
+  if (result?.isError || context?.isError) {
+    const text = result?.content?.[0]?.type === "text" ? result.content[0].text.split("\n")[0] : "State write failed";
+    return lineComponent(theme.fg("error", text));
+  }
+  return emptyComponent();
+}
+
 // Dedicated compact-output tools for editing .pp state files. Unlike the generic
 // write/edit tools (which render the full file content / a unified diff into the
 // UI on every update — the "state-file spam"), these return only a one-line
 // summary and no details.diff, so the TUI shows nothing large. Structure is
 // validated inline (rejecting bad writes up front) instead of via an appended
 // <validation-error> round-trip on the generic tools.
+// These tools only ever write the reviewed artifact set (USER_REQUEST.md,
+// RESEARCH.md, artifacts/*.md, plans/*_synthesized.md), so a successful write
+// invalidates any prior clean review for the phase — otherwise "Auto review,
+// then continue" would skip re-review over content changed through the preferred
+// state-file tools (the generic edit/write hook does not see these writes).
+function invalidateCleanReview(orchestrator: Orchestrator): void {
+  const active = orchestrator.active;
+  if (!active?.state?.reviewApprovedClean) return;
+  active.state.reviewApprovedClean = false;
+  try { saveTask(active.dir, active.state); } catch { /* best-effort */ }
+}
+
 export function registerStateFileTools(orchestrator: Orchestrator): void {
   const pi = orchestrator.pi;
   const log = getLogger();
@@ -160,6 +217,9 @@ export function registerStateFileTools(orchestrator: Orchestrator): void {
   pi.registerTool({
     name: "pp_write_state_file",
     label: "pi-pi",
+    renderShell: "self",
+    renderCall: renderStateCall,
+    renderResult: renderStateResult as any,
     description:
       "Create or overwrite a pi-pi state file (USER_REQUEST.md, RESEARCH.md, artifacts/*.md, " +
       "or plans/*_synthesized.md) under the active task directory. PREFER this over the generic " +
@@ -188,6 +248,7 @@ export function registerStateFileTools(orchestrator: Orchestrator): void {
         return err(`Failed to write ${resolved.label}: ${e?.message ?? String(e)}`);
       }
       const { added, removed } = lineDelta(before, content);
+      invalidateCleanReview(orchestrator);
       log.debug({ s: "tool", tool: "pp_write_state_file", path: resolved.label, added, removed }, "state file written");
       const verb = existed ? "Updated" : "Created";
       return ok(`${verb} ${resolved.label} (+${added}/-${removed} lines)`);
@@ -197,6 +258,9 @@ export function registerStateFileTools(orchestrator: Orchestrator): void {
   pi.registerTool({
     name: "pp_edit_state_file",
     label: "pi-pi",
+    renderShell: "self",
+    renderCall: renderStateCall,
+    renderResult: renderStateResult as any,
     description:
       "Edit a pi-pi state file in place by replacing an exact text span. PREFER this over the " +
       "generic edit tool for .pp state files (USER_REQUEST.md, RESEARCH.md, artifacts/*.md, " +
@@ -238,6 +302,7 @@ export function registerStateFileTools(orchestrator: Orchestrator): void {
         return err(`Failed to write ${resolved.label}: ${e?.message ?? String(e)}`);
       }
       const { added, removed } = lineDelta(before, after);
+      invalidateCleanReview(orchestrator);
       log.debug(
         { s: "tool", tool: "pp_edit_state_file", path: resolved.label, occurrences, replaceAll, added, removed },
         "state file edited",

package/extensions/orchestrator/rate-limit-fallback.more.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  isSubscriptionRouted: vi.fn(),
+  setSubscriptionFallbackActive: vi.fn(),
+  toNonSubSpec: vi.fn((id: string) => `nonsub:${id}`),
+  loadFlantSettings: vi.fn(() => ({ switchBackIntervalMinutes: 30 })),
+  probeSubscriptionCleared: vi.fn(),
+  askUser: vi.fn(),
+  isCancel: vi.fn(() => false),
+}));
+
+vi.mock("./usage-tracker.js", () => ({
+  isSubscriptionRouted: mocks.isSubscriptionRouted,
+}));
+vi.mock("./model-registry.js", () => ({
+  setSubscriptionFallbackActive: mocks.setSubscriptionFallbackActive,
+  toNonSubSpec: mocks.toNonSubSpec,
+}));
+vi.mock("./flant-infra.js", () => ({
+  loadFlantSettings: mocks.loadFlantSettings,
+  probeSubscriptionCleared: mocks.probeSubscriptionCleared,
+}));
+vi.mock("../../3p/pi-ask-user/index.js", () => ({
+  askUser: mocks.askUser,
+  isCancel: mocks.isCancel,
+}));
+vi.mock("./log.js", () => ({
+  getLogger: () => ({ debug: vi.fn(), warn: vi.fn(), info: vi.fn() }),
+}));
+
+import {
+  isRateLimitError,
+  isSdkRetryableError,
+  handleMainRateLimit,
+  handleSubagentRateLimit,
+  armSwitchBackProbe,
+} from "./rate-limit-fallback.js";
+
+function makeOrchestrator(overrides: Record<string, unknown> = {}): any {
+  return {
+    subFallbackActive: false,
+    subFallbackModelId: null,
+    subFallbackDialogPending: false,
+    subFallbackPendingDecision: false,
+    activeTaskToken: 1,
+    active: { state: { phase: "implement" } },
+    subSwitchBackTimer: null,
+    lastCtx: null,
+    config: { agents: { orchestrators: { implement: { thinking: "high" } } } },
+    cancelPendingRetry: vi.fn(),
+    switchModel: vi.fn(async () => true),
+    sendUserMessageWhenIdle: vi.fn(),
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Record<string, unknown> = {}): any {
+  return {
+    hasUI: true,
+    abort: vi.fn(),
+    ui: { notify: vi.fn() },
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  mocks.isSubscriptionRouted.mockReturnValue(true);
+  mocks.isCancel.mockReturnValue(false);
+  mocks.loadFlantSettings.mockReturnValue({ switchBackIntervalMinutes: 30 } as any);
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+  vi.useRealTimers();
+});
+
+describe("isRateLimitError extra shapes", () => {
+  it("matches dotted/spaced rate-limit variants", () => {
+    expect(isRateLimitError("rate-limit hit")).toBe(true);
+    expect(isRateLimitError("RATELIMIT")).toBe(true);
+    expect(isRateLimitError("HTTP 429 returned")).toBe(true);
+  });
+  it("does not match numbers that merely contain 429", () => {
+    expect(isRateLimitError("error code 4290")).toBe(false);
+    expect(isRateLimitError("connection reset")).toBe(false);
+    expect(isRateLimitError(42 as any)).toBe(false);
+  });
+});
+
+describe("isSdkRetryableError extra shapes", () => {
+  it("matches a broad set of transient network/server errors", () => {
+    for (const m of [
+      "provider returned error",
+      "502 bad gateway",
+      "504",
+      "service unavailable",
+      "internal error",
+      "connection refused",
+      "websocket closed",
+      "other side closed",
+      "upstream connect error",
+      "reset before headers",
+      "socket hang up",
+      "http2 request did not get a response",
+      "terminated",
+      "retry delay exceeded",
+    ]) {
+      expect(isSdkRetryableError(m)).toBe(true);
+    }
+  });
+  it("rejects plain application errors and non-strings", () => {
+    expect(isSdkRetryableError("permission denied")).toBe(false);
+    expect(isSdkRetryableError(null as any)).toBe(false);
+    expect(isSdkRetryableError(123 as any)).toBe(false);
+  });
+});
+
+describe("handleMainRateLimit", () => {
+  it("returns early without aborting when not subscription-routed", async () => {
+    mocks.isSubscriptionRouted.mockReturnValue(false);
+    const orch = makeOrchestrator();
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "claude", "provider");
+    expect(ctx.abort).not.toHaveBeenCalled();
+    expect(orch.cancelPendingRetry).not.toHaveBeenCalled();
+  });
+
+  it("aborts and cancels retries, then stops when already on non-sub", async () => {
+    const orch = makeOrchestrator({ subFallbackActive: true });
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "sub/claude", "sub");
+    expect(ctx.abort).toHaveBeenCalled();
+    expect(orch.cancelPendingRetry).toHaveBeenCalled();
+    expect(mocks.askUser).not.toHaveBeenCalled();
+  });
+
+  it("skips the dialog when no UI is available", async () => {
+    const orch = makeOrchestrator();
+    const ctx = makeCtx({ hasUI: false });
+    await handleMainRateLimit(orch, ctx, "sub/claude", "sub");
+    expect(mocks.askUser).not.toHaveBeenCalled();
+    expect(orch.switchModel).not.toHaveBeenCalled();
+  });
+
+  it("activates fallback and switches the main model on confirm", async () => {
+    mocks.askUser.mockResolvedValue({ kind: "selection", selections: ["Switch to non-sub Claude"] });
+    vi.useFakeTimers();
+    const orch = makeOrchestrator();
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "sub/claude-opus", "sub");
+    expect(orch.subFallbackActive).toBe(true);
+    expect(mocks.setSubscriptionFallbackActive).toHaveBeenCalledWith(true);
+    expect(mocks.toNonSubSpec).toHaveBeenCalledWith("sub/claude-opus");
+    expect(orch.switchModel).toHaveBeenCalled();
+    expect(orch.sendUserMessageWhenIdle).toHaveBeenCalled();
+    expect(orch.subSwitchBackTimer).not.toBeNull();
+  });
+
+  it("stays on subscription and notifies when the user declines", async () => {
+    mocks.askUser.mockResolvedValue({ kind: "selection", selections: ["Stay on subscription"] });
+    const orch = makeOrchestrator();
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "sub/claude", "sub");
+    expect(orch.subFallbackActive).toBe(false);
+    expect(ctx.ui.notify).toHaveBeenCalled();
+    expect(orch.switchModel).not.toHaveBeenCalled();
+  });
+
+  it("does not open a second dialog while one is pending", async () => {
+    const orch = makeOrchestrator({ subFallbackDialogPending: true });
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "sub/claude", "sub");
+    expect(mocks.askUser).not.toHaveBeenCalled();
+  });
+
+  it("aborts activation when the task token changes mid-dialog", async () => {
+    const orch = makeOrchestrator();
+    mocks.askUser.mockImplementation(async () => {
+      orch.activeTaskToken = 999;
+      return { kind: "selection", selections: ["Switch to non-sub Claude"] };
+    });
+    const ctx = makeCtx();
+    await handleMainRateLimit(orch, ctx, "sub/claude", "sub");
+    expect(orch.subFallbackActive).toBe(false);
+    expect(orch.switchModel).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleSubagentRateLimit", () => {
+  it("returns early when not subscription-routed", async () => {
+    mocks.isSubscriptionRouted.mockReturnValue(false);
+    const orch = makeOrchestrator();
+    await handleSubagentRateLimit(orch, makeCtx(), "claude");
+    expect(mocks.askUser).not.toHaveBeenCalled();
+  });
+
+  it("returns early when already on non-sub", async () => {
+    const orch = makeOrchestrator({ subFallbackActive: true });
+    await handleSubagentRateLimit(orch, makeCtx(), "sub/claude");
+    expect(mocks.askUser).not.toHaveBeenCalled();
+  });
+
+  it("activates fallback WITHOUT switching the main model for a subagent 429", async () => {
+    mocks.askUser.mockResolvedValue({ kind: "selection", selections: ["Switch to non-sub Claude"] });
+    vi.useFakeTimers();
+    const orch = makeOrchestrator();
+    await handleSubagentRateLimit(orch, makeCtx(), "sub/claude-haiku");
+    expect(mocks.setSubscriptionFallbackActive).toHaveBeenCalledWith(true);
+    expect(orch.switchModel).not.toHaveBeenCalled();
+    expect(orch.subFallbackActive).toBe(true);
+  });
+});
+
+describe("armSwitchBackProbe", () => {
+  it("schedules a timer using the configured interval and clears any prior timer", () => {
+    vi.useFakeTimers();
+    const prior = setTimeout(() => {}, 100000) as any;
+    const orch = makeOrchestrator({ subSwitchBackTimer: prior });
+    armSwitchBackProbe(orch);
+    expect(orch.subSwitchBackTimer).not.toBeNull();
+    expect(orch.subSwitchBackTimer).not.toBe(prior);
+  });
+
+  it("floors the interval to at least one minute", () => {
+    vi.useFakeTimers();
+    mocks.loadFlantSettings.mockReturnValue({ switchBackIntervalMinutes: 0 } as any);
+    const orch = makeOrchestrator();
+    armSwitchBackProbe(orch);
+    expect(orch.subSwitchBackTimer).not.toBeNull();
+  });
+
+  it("runs the probe when the timer fires and stays on non-sub while still limited", async () => {
+    vi.useFakeTimers();
+    mocks.probeSubscriptionCleared.mockResolvedValue("rate_limited");
+    const orch = makeOrchestrator({ subFallbackActive: true, subFallbackModelId: "sub/claude" });
+    armSwitchBackProbe(orch);
+    await vi.runOnlyPendingTimersAsync();
+    expect(mocks.probeSubscriptionCleared).toHaveBeenCalledWith("sub/claude");
+  });
+});

package/extensions/orchestrator/rate-limit-fallback.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isRateLimitError, isSdkRetryableError } from "./rate-limit-fallback.js";
+import { isRateLimitError, isExtraUsageError, isSdkRetryableError } from "./rate-limit-fallback.js";
 import { isSubscriptionRouted } from "./usage-tracker.js";
 import { SUB_MODEL_PREFIX, SUB_PROVIDER, subProbeModelId } from "./flant-infra.js";
 
@@ -18,6 +18,25 @@ describe("isRateLimitError", () => {
     expect(isRateLimitError("")).toBe(false);
     expect(isRateLimitError(undefined)).toBe(false);
   });
+
+  it("does not match the 400 extra-usage message (kept separate from 429)", () => {
+    expect(isRateLimitError("Third-party apps now draw from extra usage, not plan limits")).toBe(false);
+  });
+});
+
+describe("isExtraUsageError", () => {
+  it("matches the subscription 400 extra-usage phrasing", () => {
+    expect(isExtraUsageError("400 Third-party apps now draw from extra usage, not plan limits")).toBe(true);
+    expect(isExtraUsageError("you are out of extra usage")).toBe(true);
+    expect(isExtraUsageError("requests now draw from your extra usage balance")).toBe(true);
+  });
+
+  it("does not match 429 or unrelated errors (no over-match)", () => {
+    expect(isExtraUsageError("Error 429: too many requests")).toBe(false);
+    expect(isExtraUsageError("500 internal server error")).toBe(false);
+    expect(isExtraUsageError("")).toBe(false);
+    expect(isExtraUsageError(undefined)).toBe(false);
+  });
 });
 
 describe("isSdkRetryableError", () => {

package/extensions/orchestrator/rate-limit-fallback.ts

@@ -11,6 +11,18 @@ export function isRateLimitError(message?: string): boolean {
   return /\b429\b|rate.?limit|too many requests|exceed your account/i.test(message);
 }
 
+// Recognise the subscription-routing-specific 400 "extra usage" error, e.g.
+// "Third-party apps now draw from extra usage, not plan limits". This is a
+// DISTINCT failure class from 429 (not retryable, not a plan rate-limit) but is
+// funneled into the SAME sub→non-sub fallback. Kept separate from
+// isRateLimitError so the 429 regex stays clean. Anchored on the specific
+// phrasing to avoid over-matching other 400s; the CALLER additionally requires
+// isSubscriptionRouted.
+export function isExtraUsageError(message?: string): boolean {
+  if (typeof message !== "string" || !message) return false;
+  return /extra usage|draw from[\s\S]{0,40}plan limits/i.test(message);
+}
+
 // Mirror of the SDK's AgentSession._isRetryableError classifier
 // (agent-session.js: overloaded/rate-limit/5xx/network/stream-ended/timeout/...).
 // When true, the SDK auto-retries the SAME turn itself (abortable backoff bound

package/extensions/orchestrator/review-files.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { isReviewFileForRound } from "./review-files.js";
+
+describe("isReviewFileForRound", () => {
+  it("matches the exact round suffix", () => {
+    expect(isReviewFileForRound("001_alpha_round-1.md", 1)).toBe(true);
+    expect(isReviewFileForRound("42_gemini_round-3.md", 3)).toBe(true);
+  });
+
+  it("does not let round-1 match round-10 through round-19", () => {
+    expect(isReviewFileForRound("001_alpha_round-10.md", 1)).toBe(false);
+    expect(isReviewFileForRound("001_alpha_round-11.md", 1)).toBe(false);
+    expect(isReviewFileForRound("001_alpha_round-19.md", 1)).toBe(false);
+    expect(isReviewFileForRound("001_alpha_round-10.md", 10)).toBe(true);
+  });
+
+  it("excludes synthesized final-pass files", () => {
+    expect(isReviewFileForRound("001_final_pass-1.md", 1)).toBe(false);
+    expect(isReviewFileForRound("001_final_pass-10.md", 1)).toBe(false);
+  });
+
+  it("requires the .md extension", () => {
+    expect(isReviewFileForRound("001_alpha_round-1.txt", 1)).toBe(false);
+    expect(isReviewFileForRound("001_alpha_round-1", 1)).toBe(false);
+  });
+});

package/extensions/orchestrator/review-files.ts

@@ -0,0 +1,3 @@
+export function isReviewFileForRound(filename: string, pass: number): boolean {
+  return new RegExp(`_round-${pass}\\.md$`).test(filename);
+}

package/extensions/orchestrator/state.test.ts

@@ -1,12 +1,13 @@
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
-import { join, resolve } from "path";
+import { join, resolve, relative } from "path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import lockfile from "proper-lockfile";
 import {
   createTask,
   formatModeIndicator,
   getActiveTask,
+  getActiveTaskStatus,
   getEffectiveMode,
   getFirstPhase,
   listTasks,
@@ -152,6 +153,23 @@ describe("listTasks", () => {
     expect(brainstormOnly[0].type).toBe("brainstorm");
   });
 
+  it("includes done tasks when includeDone is set", () => {
+    const cwd = makeCwd();
+    const active = createTask(cwd, "implement", "Active feature");
+    const doneTask = createTask(cwd, "implement", "Finished feature");
+    const doneState = loadTask(doneTask);
+    doneState.phase = "done";
+    saveTask(doneTask, doneState);
+
+    const activeOnly = listTasks(cwd, { type: "implement" }).map((t) => t.dir);
+    expect(activeOnly).toContain(active);
+    expect(activeOnly).not.toContain(doneTask);
+
+    const withDone = listTasks(cwd, { type: "implement", includeDone: true }).map((t) => t.dir);
+    expect(withDone).toContain(active);
+    expect(withDone).toContain(doneTask);
+  });
+
   it("skips corrupt task entries", () => {
     const cwd = makeCwd();
     createTask(cwd, "implement", "Healthy task");
@@ -219,6 +237,17 @@ describe("validateFromPath", () => {
       reason: "No state.json found at . — not a valid task directory",
     });
   });
+
+  it("accepts the stateDir-relative form the From fork derives from an absolute dir", () => {
+    // startTask receives an absolute fromTaskDir and feeds validateFromPath the
+    // stateDir-relative form (the same shape stored in state.from). This mirrors
+    // that conversion and confirms the guard accepts it and returns the absolute dir.
+    const cwd = makeCwd();
+    const absoluteTaskDir = createTask(cwd, "brainstorm", "Source");
+    const rel = relative(join(cwd, ".pp", "state"), absoluteTaskDir);
+
+    expect(validateFromPath(cwd, rel)).toEqual({ ok: true, dir: absoluteTaskDir });
+  });
 });
 
 describe("taskName", () => {
@@ -235,6 +264,21 @@ describe("taskName", () => {
 
     expect(taskName(taskDir)).toBe("my fallback name");
   });
+
+  it("falls back to RESEARCH.md when description is generic and no USER_REQUEST.md", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "review", "review");
+    writeFileSync(join(taskDir, "RESEARCH.md"), "## Affected Code\nReview the payment refactor\n", "utf-8");
+    expect(taskName(taskDir)).toBe("Review the payment refactor");
+  });
+
+  it("prefers USER_REQUEST.md over RESEARCH.md for a generic description", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "brainstorm", "brainstorm");
+    writeFileSync(join(taskDir, "USER_REQUEST.md"), "# User Request\nAdd dark mode\n", "utf-8");
+    writeFileSync(join(taskDir, "RESEARCH.md"), "## Affected Code\nsomething else\n", "utf-8");
+    expect(taskName(taskDir)).toBe("Add dark mode");
+  });
 });
 
 describe("taskAge", () => {
@@ -371,6 +415,34 @@ describe("getActiveTask", () => {
   });
 });
 
+describe("getActiveTaskStatus", () => {
+  it("reports none when no tasks exist", () => {
+    const cwd = makeCwd();
+    expect(getActiveTaskStatus(cwd).kind).toBe("none");
+  });
+
+  it("reports single for exactly one unlocked task", () => {
+    const cwd = makeCwd();
+    const taskDir = createTask(cwd, "implement", "Only one");
+    vi.spyOn(lockfile, "checkSync").mockReturnValue(false);
+
+    const status = getActiveTaskStatus(cwd);
+    expect(status.kind).toBe("single");
+    if (status.kind === "single") expect(status.task.dir).toBe(taskDir);
+  });
+
+  it("reports ambiguous with all tasks when multiple are unlocked", () => {
+    const cwd = makeCwd();
+    createTask(cwd, "implement", "First");
+    createTask(cwd, "debug", "Second");
+    vi.spyOn(lockfile, "checkSync").mockReturnValue(false);
+
+    const status = getActiveTaskStatus(cwd);
+    expect(status.kind).toBe("ambiguous");
+    if (status.kind === "ambiguous") expect(status.tasks).toHaveLength(2);
+  });
+});
+
 describe("getFirstPhase", () => {
   it("returns expected first phase for each task type", () => {
     expect(getFirstPhase("implement")).toBe("brainstorm");