@ilya-lesikov/pi-pi 0.7.0 → 0.9.0

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");
+  });
+});

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

@@ -0,0 +1,249 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import { Type } from "@sinclair/typebox";
+import type { Orchestrator } from "./orchestrator.js";
+import { getLogger } from "./log.js";
+import {
+  validateArtifact,
+  validatePlan,
+  validateResearch,
+  validateUserRequest,
+} from "./validate-artifacts.js";
+
+type ToolResult = {
+  content: { type: "text"; text: string }[];
+  isError?: true;
+  details: Record<string, never>;
+};
+
+function ok(text: string): ToolResult {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function err(text: string): ToolResult {
+  return { content: [{ type: "text" as const, text }], isError: true as const, details: {} };
+}
+
+function isPathInside(basePath: string, targetPath: string): boolean {
+  const rel = relative(basePath, targetPath);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+// Approximate added/removed line counts via an LCS of the line arrays. Good
+// enough for a compact "(+N/-M lines)" summary without pulling in a diff lib.
+function lineDelta(oldContent: string, newContent: string): { added: number; removed: number } {
+  const a = oldContent.length ? oldContent.split(/\r?\n/) : [];
+  const b = newContent.length ? newContent.split(/\r?\n/) : [];
+  const n = a.length;
+  const m = b.length;
+  // DP LCS length (rolling rows to keep memory O(m)).
+  let prev = new Array<number>(m + 1).fill(0);
+  for (let i = 1; i <= n; i += 1) {
+    const curr = new Array<number>(m + 1).fill(0);
+    for (let j = 1; j <= m; j += 1) {
+      curr[j] = a[i - 1] === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], curr[j - 1]);
+    }
+    prev = curr;
+  }
+  const lcs = prev[m];
+  return { added: m - lcs, removed: n - lcs };
+}
+
+// The exact set of state files these compact tools may edit. Anything else
+// under the task dir — especially orchestrator-MANAGED outputs like
+// brainstorm-reviews/, plan-reviews/, code-reviews/, and non-synthesized
+// plans/ files — is REJECTED so the agent cannot corrupt managed artifacts.
+function isAllowedStateFile(rel: string): boolean {
+  if (rel === "USER_REQUEST.md" || rel === "RESEARCH.md") return true;
+  const parts = rel.split(sep);
+  const base = parts[parts.length - 1];
+  if (parts.length === 2 && parts[0] === "artifacts" && base.endsWith(".md")) return true;
+  if (parts.length === 2 && parts[0] === "plans" && base.endsWith("_synthesized.md")) return true;
+  return false;
+}
+
+// Resolve a caller-supplied path (relative to the active task dir, or absolute)
+// and enforce it stays within the active task dir under .pp/state/, is a .md
+// file, AND is one of the allowed state files. Returns the absolute path or an
+// error result.
+function resolveStatePath(
+  orchestrator: Orchestrator,
+  rawPath: string,
+): { ok: true; absolute: string; label: string } | { ok: false; result: ToolResult } {
+  const active = orchestrator.active;
+  if (!active) return { ok: false, result: err("No active task.") };
+  const taskDir = resolve(active.dir);
+  const input = typeof rawPath === "string" ? rawPath.trim() : "";
+  if (!input) return { ok: false, result: err("Missing path.") };
+
+  const absolute = isAbsolute(input) ? resolve(input) : resolve(taskDir, input);
+
+  if (!isPathInside(taskDir, absolute)) {
+    return { ok: false, result: err(`Path escapes the active task directory: ${rawPath}`) };
+  }
+  const ppStateDir = resolve(orchestrator.cwd, ".pp", "state");
+  if (!isPathInside(ppStateDir, absolute)) {
+    return { ok: false, result: err("State files must live under .pp/state/.") };
+  }
+  if (!absolute.endsWith(".md")) {
+    return { ok: false, result: err("Only .md state files can be edited with this tool.") };
+  }
+  const rel = relative(taskDir, absolute);
+  if (!isAllowedStateFile(rel)) {
+    return {
+      ok: false,
+      result: err(
+        `Not an editable state file: ${rel}. These tools only edit USER_REQUEST.md, RESEARCH.md, artifacts/*.md, and plans/*_synthesized.md. ` +
+          `Managed outputs (brainstorm-reviews/, plan-reviews/, code-reviews/, non-synthesized plans) are off-limits.`,
+      ),
+    };
+  }
+  const label = rel || relative(orchestrator.cwd, absolute);
+  return { ok: true, absolute, label };
+}
+
+// Validate structured state files by their role. resolveStatePath has already
+// restricted callers to the allowed set (USER_REQUEST/RESEARCH/artifacts/
+// plans-synthesized), so every path reaching here maps to a known validator.
+function validateStateContent(taskDir: string, absolute: string, content: string):
+  | { ok: true }
+  | { ok: false; errors: string[]; hint: string } {
+  const rel = relative(taskDir, absolute);
+  const parts = rel.split(sep);
+  const base = parts[parts.length - 1];
+
+  if (rel === "USER_REQUEST.md") {
+    const res = validateUserRequest(content);
+    return res.ok
+      ? { ok: true }
+      : { ok: false, errors: res.errors, hint: "Keep exactly: # User Request, ## Problem, ## Constraints. No other sections." };
+  }
+  if (rel === "RESEARCH.md") {
+    const res = validateResearch(content);
+    return res.ok
+      ? { ok: true }
+      : {
+          ok: false,
+          errors: res.errors,
+          hint: "Keep exactly: ## Affected Code, ## Architecture Context, ## Constraints & Edge Cases, ## Open Questions (optional). No other sections.",
+        };
+  }
+  if (parts[0] === "artifacts" && base.endsWith(".md")) {
+    const res = validateArtifact(content);
+    return res.ok ? { ok: true } : { ok: false, errors: res.errors, hint: "Artifact files must start with # <Title>." };
+  }
+  if (parts[0] === "plans" && base.endsWith("_synthesized.md")) {
+    const res = validatePlan(content);
+    return res.ok
+      ? { ok: true }
+      : { ok: false, errors: res.errors, hint: "Keep exactly: # Plan, ## Scope, ## Checklist (items need 'Done when:'), ## Blockers (optional)." };
+  }
+  return { ok: true };
+}
+
+function validationError(label: string, errors: string[], hint: string): ToolResult {
+  return err(
+    `${label} structure is invalid:\n${errors.map((e) => `- ${e}`).join("\n")}\n\n${hint}`,
+  );
+}
+
+// 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.
+export function registerStateFileTools(orchestrator: Orchestrator): void {
+  const pi = orchestrator.pi;
+  const log = getLogger();
+
+  pi.registerTool({
+    name: "pp_write_state_file",
+    label: "pi-pi",
+    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 " +
+      "write tool for .pp state files: it emits compact output (no full-file echo) and validates " +
+      "structure before writing. `path` is relative to the task directory (e.g. \"RESEARCH.md\", " +
+      "\"artifacts/design.md\").",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path relative to the active task dir (e.g. RESEARCH.md, artifacts/foo.md)" }),
+      content: Type.String({ description: "Full new file content" }),
+    }),
+    async execute(_toolCallId, params: any): Promise<ToolResult> {
+      const resolved = resolveStatePath(orchestrator, params?.path);
+      if (!resolved.ok) return resolved.result;
+      const content = typeof params?.content === "string" ? params.content : "";
+
+      const taskDir = resolve(orchestrator.active!.dir);
+      const check = validateStateContent(taskDir, resolved.absolute, content);
+      if (!check.ok) return validationError(resolved.label, check.errors, check.hint);
+
+      const existed = existsSync(resolved.absolute);
+      const before = existed ? readFileSync(resolved.absolute, "utf-8") : "";
+      try {
+        mkdirSync(dirname(resolved.absolute), { recursive: true });
+        writeFileSync(resolved.absolute, content, "utf-8");
+      } catch (e: any) {
+        return err(`Failed to write ${resolved.label}: ${e?.message ?? String(e)}`);
+      }
+      const { added, removed } = lineDelta(before, content);
+      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)`);
+    },
+  });
+
+  pi.registerTool({
+    name: "pp_edit_state_file",
+    label: "pi-pi",
+    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, " +
+      "plans/*_synthesized.md): it emits compact output (no diff) and validates structure before " +
+      "writing. `path` is relative to the active task dir. `oldText` must match exactly and be " +
+      "unique unless replaceAll is set.",
+    parameters: Type.Object({
+      path: Type.String({ description: "Path relative to the active task dir (e.g. RESEARCH.md)" }),
+      oldText: Type.String({ description: "Exact text to replace" }),
+      newText: Type.String({ description: "Replacement text" }),
+      replaceAll: Type.Optional(Type.Boolean({ description: "Replace all occurrences (default: false — oldText must be unique)" })),
+    }),
+    async execute(_toolCallId, params: any): Promise<ToolResult> {
+      const resolved = resolveStatePath(orchestrator, params?.path);
+      if (!resolved.ok) return resolved.result;
+      if (!existsSync(resolved.absolute)) {
+        return err(`File does not exist: ${resolved.label}. Use pp_write_state_file to create it.`);
+      }
+      const oldText = typeof params?.oldText === "string" ? params.oldText : "";
+      const newText = typeof params?.newText === "string" ? params.newText : "";
+      const replaceAll = params?.replaceAll === true;
+      if (!oldText) return err("oldText must be a non-empty string.");
+
+      const before = readFileSync(resolved.absolute, "utf-8");
+      const occurrences = before.split(oldText).length - 1;
+      if (occurrences === 0) return err(`oldText not found in ${resolved.label}.`);
+      if (occurrences > 1 && !replaceAll) {
+        return err(`oldText matches ${occurrences} locations in ${resolved.label}. Make it unique or set replaceAll.`);
+      }
+      const after = replaceAll ? before.split(oldText).join(newText) : before.replace(oldText, newText);
+
+      const taskDir = resolve(orchestrator.active!.dir);
+      const check = validateStateContent(taskDir, resolved.absolute, after);
+      if (!check.ok) return validationError(resolved.label, check.errors, check.hint);
+
+      try {
+        writeFileSync(resolved.absolute, after, "utf-8");
+      } catch (e: any) {
+        return err(`Failed to write ${resolved.label}: ${e?.message ?? String(e)}`);
+      }
+      const { added, removed } = lineDelta(before, after);
+      log.debug(
+        { s: "tool", tool: "pp_edit_state_file", path: resolved.label, occurrences, replaceAll, added, removed },
+        "state file edited",
+      );
+      const scope = replaceAll ? ` (${occurrences}x)` : "";
+      return ok(`Updated ${resolved.label}${scope} (+${added}/-${removed} lines)`);
+    },
+  });
+}

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

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Mock collaborators so the flow test exercises only the fallback orchestration
+// (dialog gating, main-vs-subagent switch gating, override activation).
+vi.mock("./log.js", () => ({
+  getLogger: () => ({ debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() }),
+}));
+
+const askUserMock = vi.fn();
+vi.mock("../../3p/pi-ask-user/index.js", () => ({
+  askUser: (...args: any[]) => askUserMock(...args),
+  isCancel: (v: any) => !!v && v.__cancel === true,
+}));
+
+vi.mock("./flant-infra.js", () => ({
+  loadFlantSettings: () => ({ switchBackIntervalMinutes: 30 }),
+  probeSubscriptionCleared: vi.fn(),
+  SUB_PROVIDER: "pp-flant-anthropic-sub",
+  SUB_MODEL_PREFIX: "sub/",
+}));
+
+const setSubscriptionFallbackActiveMock = vi.fn();
+vi.mock("./model-registry.js", () => ({
+  setSubscriptionFallbackActive: (v: boolean) => setSubscriptionFallbackActiveMock(v),
+  toNonSubSpec: (spec: string) =>
+    spec.replace(/^pp-flant-anthropic-sub\/sub\//, "pp-flant-anthropic/").replace(/^sub\//, "pp-flant-anthropic/"),
+}));
+
+import { handleMainRateLimit, handleSubagentRateLimit } from "./rate-limit-fallback.js";
+
+function makeOrchestrator() {
+  return {
+    active: { state: { phase: "debug" } },
+    activeTaskToken: 1,
+    subFallbackActive: false,
+    subFallbackDialogPending: false,
+    subFallbackPendingDecision: false,
+    subFallbackModelId: null as string | null,
+    subSwitchBackTimer: null as any,
+    config: { agents: { orchestrators: { debug: { thinking: "high" }, implement: { thinking: "high" } } } },
+    switchModel: vi.fn().mockResolvedValue(true),
+    sendUserMessageWhenIdle: vi.fn(),
+    cancelPendingRetry: vi.fn(),
+    safeSendUserMessage: vi.fn(),
+  } as any;
+}
+
+function makeCtx() {
+  return { hasUI: true, abort: vi.fn(), ui: { notify: vi.fn() } };
+}
+
+beforeEach(() => {
+  askUserMock.mockReset();
+  setSubscriptionFallbackActiveMock.mockReset();
+});
+afterEach(() => {
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
+describe("handleSubagentRateLimit (M1: does not switch the main model)", () => {
+  it("activates the session override + nudges but does NOT switch the main model", async () => {
+    vi.useFakeTimers();
+    askUserMock.mockResolvedValue({ kind: "selection", selections: ["Switch to non-sub Claude"] });
+    const orch = makeOrchestrator();
+
+    await handleSubagentRateLimit(orch, makeCtx(), "pp-flant-anthropic-sub/sub/claude-opus-4-8");
+
+    expect(setSubscriptionFallbackActiveMock).toHaveBeenCalledWith(true);
+    expect(orch.subFallbackActive).toBe(true);
+    // Main model must NOT change for a subagent-origin 429.
+    expect(orch.switchModel).not.toHaveBeenCalled();
+    // Continuation nudge is idle-gated (not a bare safeSendUserMessage).
+    expect(orch.sendUserMessageWhenIdle).toHaveBeenCalledTimes(1);
+    expect(orch.safeSendUserMessage).not.toHaveBeenCalled();
+  });
+
+  it("does nothing for a non-subscription subagent model", async () => {
+    const orch = makeOrchestrator();
+    await handleSubagentRateLimit(orch, makeCtx(), "pp-flant-anthropic/claude-opus-4-8");
+    expect(askUserMock).not.toHaveBeenCalled();
+    expect(orch.subFallbackActive).toBe(false);
+  });
+
+  it("clears the pending-decision flag after the dialog resolves", async () => {
+    vi.useFakeTimers();
+    askUserMock.mockResolvedValue({ kind: "selection", selections: ["Switch to non-sub Claude"] });
+    const orch = makeOrchestrator();
+    orch.subFallbackPendingDecision = true; // set synchronously by the detection site
+    await handleSubagentRateLimit(orch, makeCtx(), "pp-flant-anthropic-sub/sub/claude-opus-4-8");
+    expect(orch.subFallbackPendingDecision).toBe(false);
+  });
+});
+
+describe("handleMainRateLimit (main-origin switches the main model)", () => {
+  it("switches the main model to the non-sub equivalent on confirm", async () => {
+    vi.useFakeTimers();
+    askUserMock.mockResolvedValue({ kind: "selection", selections: ["Switch to non-sub Claude"] });
+    const orch = makeOrchestrator();
+    const ctx = makeCtx();
+
+    await handleMainRateLimit(orch, ctx, "pp-flant-anthropic-sub/sub/claude-opus-4-8", "pp-flant-anthropic-sub");
+
+    // Futile retry stopped.
+    expect(ctx.abort).toHaveBeenCalled();
+    expect(orch.cancelPendingRetry).toHaveBeenCalled();
+    // Session override on + main model switched to non-sub.
+    expect(setSubscriptionFallbackActiveMock).toHaveBeenCalledWith(true);
+    expect(orch.switchModel).toHaveBeenCalledWith(ctx, "pp-flant-anthropic/claude-opus-4-8", "high");
+    expect(orch.sendUserMessageWhenIdle).toHaveBeenCalledTimes(1);
+  });
+
+  it("declining does not switch or activate the override", async () => {
+    askUserMock.mockResolvedValue({ kind: "selection", selections: ["Stay on subscription"] });
+    const orch = makeOrchestrator();
+    await handleMainRateLimit(orch, makeCtx(), "pp-flant-anthropic-sub/sub/claude-opus-4-8", "pp-flant-anthropic-sub");
+    expect(orch.switchModel).not.toHaveBeenCalled();
+    expect(setSubscriptionFallbackActiveMock).not.toHaveBeenCalledWith(true);
+    expect(orch.subFallbackActive).toBe(false);
+  });
+
+  it("is sticky: no dialog when already on fallback", async () => {
+    const orch = makeOrchestrator();
+    orch.subFallbackActive = true;
+    await handleMainRateLimit(orch, makeCtx(), "pp-flant-anthropic-sub/sub/claude-opus-4-8", "pp-flant-anthropic-sub");
+    expect(askUserMock).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { isRateLimitError, isSdkRetryableError } from "./rate-limit-fallback.js";
+import { isSubscriptionRouted } from "./usage-tracker.js";
+import { SUB_MODEL_PREFIX, SUB_PROVIDER, subProbeModelId } from "./flant-infra.js";
+
+describe("isRateLimitError", () => {
+  it("matches 429 and rate-limit phrasings", () => {
+    expect(isRateLimitError("Error 429: too many requests")).toBe(true);
+    expect(isRateLimitError("rate_limit_error")).toBe(true);
+    expect(isRateLimitError("This request would exceed your account's rate limit")).toBe(true);
+    expect(isRateLimitError("Rate Limit reached")).toBe(true);
+    expect(isRateLimitError("Too Many Requests")).toBe(true);
+  });
+
+  it("does not match unrelated errors", () => {
+    expect(isRateLimitError("Anthropic stream ended before message_stop")).toBe(false);
+    expect(isRateLimitError("500 internal server error")).toBe(false);
+    expect(isRateLimitError("")).toBe(false);
+    expect(isRateLimitError(undefined)).toBe(false);
+  });
+});
+
+describe("isSdkRetryableError", () => {
+  it("matches the same error classes the SDK auto-retries", () => {
+    // These are exactly the errors the user hit; the SDK retries them itself,
+    // so pi-pi must NOT double-retry.
+    expect(isSdkRetryableError("Anthropic stream ended before message_stop")).toBe(true);
+    expect(isSdkRetryableError("429 rate_limit_error")).toBe(true);
+    expect(isSdkRetryableError("overloaded_error")).toBe(true);
+    expect(isSdkRetryableError("503 service unavailable")).toBe(true);
+    expect(isSdkRetryableError("fetch failed")).toBe(true);
+    expect(isSdkRetryableError("request timed out")).toBe(true);
+  });
+
+  it("does not match non-retryable errors", () => {
+    expect(isSdkRetryableError("invalid request: bad tool arguments")).toBe(false);
+    expect(isSdkRetryableError("")).toBe(false);
+    expect(isSdkRetryableError(undefined)).toBe(false);
+  });
+
+  it("the common rate-limit phrasings are both rate-limit AND SDK-retryable", () => {
+    // The sub-429 interception (isRateLimitError) runs BEFORE the SDK-defer
+    // branch (isSdkRetryableError); the phrasings the gateway actually emits
+    // must be recognised by both so a sub-429 is intercepted and any other
+    // rate-limit is deferred to the SDK rather than double-retried by pi-pi.
+    for (const m of ["429", "rate limit", "rate_limit_error", "too many requests"]) {
+      expect(isRateLimitError(m)).toBe(true);
+      expect(isSdkRetryableError(m)).toBe(true);
+    }
+    // The gateway's account-limit phrasing is a rate limit; the SDK regex does
+    // not include that exact phrase, so pi-pi's sub-429 interception (which runs
+    // first) is what handles it — by design.
+    expect(isRateLimitError("exceed your account")).toBe(true);
+  });
+});
+
+describe("isSubscriptionRouted", () => {
+  it("detects the subscription provider", () => {
+    expect(isSubscriptionRouted("claude-opus-4-8", SUB_PROVIDER)).toBe(true);
+  });
+
+  it("detects the sub/ model prefix", () => {
+    expect(isSubscriptionRouted(`${SUB_MODEL_PREFIX}claude-opus-4-8`)).toBe(true);
+  });
+
+  it("detects a full provider-prefixed spec passed as a single id", () => {
+    expect(isSubscriptionRouted(`${SUB_PROVIDER}/${SUB_MODEL_PREFIX}claude-opus-4-8`)).toBe(true);
+  });
+
+  it("returns false for regular flant Claude", () => {
+    expect(isSubscriptionRouted("claude-opus-4-8", "pp-flant-anthropic")).toBe(false);
+    expect(isSubscriptionRouted("pp-flant-anthropic/claude-opus-4-8")).toBe(false);
+  });
+
+  it("returns false with no signal", () => {
+    expect(isSubscriptionRouted(undefined, undefined)).toBe(false);
+  });
+});
+
+describe("subProbeModelId", () => {
+  it("derives sub/<m> from a provider-prefixed spec", () => {
+    expect(subProbeModelId(`${SUB_PROVIDER}/${SUB_MODEL_PREFIX}claude-opus-4-8`)).toBe(`${SUB_MODEL_PREFIX}claude-opus-4-8`);
+  });
+
+  it("keeps a bare sub/<m> spec", () => {
+    expect(subProbeModelId(`${SUB_MODEL_PREFIX}claude-haiku-4-5`)).toBe(`${SUB_MODEL_PREFIX}claude-haiku-4-5`);
+  });
+
+  it("adds sub/ to a plain claude id", () => {
+    expect(subProbeModelId("claude-opus-4-8")).toBe(`${SUB_MODEL_PREFIX}claude-opus-4-8`);
+  });
+
+  it("never double-prefixes the provider", () => {
+    const out = subProbeModelId(`${SUB_PROVIDER}/${SUB_MODEL_PREFIX}claude-opus-4-8`);
+    expect(out).not.toContain(SUB_PROVIDER);
+    expect(out.startsWith(`${SUB_MODEL_PREFIX}${SUB_MODEL_PREFIX}`)).toBe(false);
+  });
+});