@zhushanwen/pi-plan 0.2.0

package/src/__tests__/tool.test.ts

@@ -0,0 +1,181 @@
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+// Mock typebox before importing tool
+vi.mock("typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    String: (opts?: Record<string, unknown>) => ({ type: "string", ...opts }),
+    Optional: (schema: unknown) => schema,
+  },
+  Static: class {},
+}));
+
+vi.mock("@mariozechner/pi-ai", () => ({
+  StringEnum: (values: readonly string[]) => ({ type: "string", enum: [...values] }),
+}));
+
+// Mock compact.js (dynamically imported by complete action)
+vi.mock("../compact.js", () => ({
+  handlePlanComplete: vi.fn(),
+  detectGoalCapability: vi.fn(() => false),
+}));
+
+// Mock widget (imported by abort)
+vi.mock("../widget.js", () => ({
+  updatePlanWidget: vi.fn(),
+}));
+
+// Mock node:fs — ESM namespace isn't configurable, so we use vi.mock
+vi.mock("node:fs", async () => {
+  const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
+  return { ...actual, mkdirSync: vi.fn(), writeFileSync: vi.fn() };
+});
+
+import * as fs from "node:fs";
+
+import { handlePlanComplete } from "../compact.js";
+import { PLAN_ACTIONS, registerPlanTool, validateAction } from "../tool.js";
+import { updatePlanWidget } from "../widget.js";
+
+/** Build a fake pi + ctx and capture the execute callback from registerTool. */
+const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
+
+function setup() {
+  const sessions = new Map();
+  let executeFn: (id: string, p: Record<string, unknown>, sig?: AbortSignal, upd?: unknown, ctx?: unknown) => Promise<unknown>;
+  const pi = {
+    registerTool: vi.fn((tool) => { executeFn = tool.execute; }),
+    appendEntry: vi.fn(),
+    setActiveTools: vi.fn(),
+    getAllTools: vi.fn(() => ALL_TOOL_NAMES.map((n) => ({ name: n }))),
+  } as unknown as Parameters<typeof registerPlanTool>[0];
+  registerPlanTool(pi, sessions);
+
+  const ctx = {
+    sessionId: "test-session",
+    cwd: "/tmp/test-project",
+    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] },
+    ui: { select: vi.fn(), notify: vi.fn() },
+  };
+
+  const exec = (params: Record<string, unknown>) => executeFn!("tc0", params, undefined, undefined, ctx);
+  return { pi, sessions, ctx, exec };
+}
+
+describe("registerPlanTool", () => {
+  it("registers a tool named 'plan'", () => {
+    const { pi } = setup();
+    expect(pi.registerTool).toHaveBeenCalledOnce();
+    expect((pi.registerTool as ReturnType<typeof vi.fn>).mock.calls[0][0].name).toBe("plan");
+  });
+
+  // --- list-template ---
+  describe("list-template", () => {
+    it("returns template list", async () => {
+      const { exec } = setup();
+      const res = await exec({ action: "list-template" });
+      expect(res.content[0].type).toBe("text");
+      expect(res.details.action).toBe("list-template");
+      expect(Array.isArray(res.details.templates)).toBe(true);
+    });
+  });
+
+  // --- select-template ---
+  describe("select-template", () => {
+    it("throws when templateName is missing", async () => {
+      const { exec } = setup();
+      await expect(exec({ action: "select-template" })).rejects.toThrow("templateName is required");
+    });
+
+    it("throws when template does not exist", async () => {
+      const { exec } = setup();
+      await expect(exec({ action: "select-template", templateName: "nonexistent" })).rejects.toThrow("Template not found");
+    });
+
+    it("sets phase to writing and persists", async () => {
+      const { exec, pi, sessions } = setup();
+      // Use a builtin template name — find one first
+      const listRes = await exec({ action: "list-template" });
+      const templates = listRes.details.templates as { name: string }[];
+      if (templates.length === 0) return; // no builtin templates available
+
+      const name = templates[0].name;
+      const res = await exec({ action: "select-template", templateName: name });
+      expect(res.details.templateName).toBe(name);
+      expect(res.details.action).toBe("select-template");
+      expect(pi.appendEntry).toHaveBeenCalled();
+      const state = sessions.get("test-session");
+      expect(state?.phase).toBe("writing");
+      expect(state?.templateName).toBe(name);
+    });
+  });
+
+  // --- create-template ---
+  describe("create-template", () => {
+    beforeEach(() => { (fs.mkdirSync as ReturnType<typeof vi.fn>).mockClear(); (fs.writeFileSync as ReturnType<typeof vi.fn>).mockClear(); });
+
+    it("throws when parameters are missing", async () => {
+      const { exec } = setup();
+      await expect(exec({ action: "create-template" })).rejects.toThrow("templateName and templateContent are required");
+    });
+
+    it("throws when name sanitizes to empty", async () => {
+      const { exec } = setup();
+      await expect(exec({ action: "create-template", templateName: "!!!", templateContent: "x" }))
+        .rejects.toThrow("Invalid template name");
+    });
+
+    it("writes file with sanitized name", async () => {
+      const { exec } = setup();
+      const res = await exec({ action: "create-template", templateName: "My Plan v2!", templateContent: "# hello" });
+      expect(res.details.templateName).toBe("MyPlanv2");
+      expect(fs.mkdirSync).toHaveBeenCalledWith("/tmp/test-project/.pi/plan-templates", { recursive: true });
+      expect(fs.writeFileSync).toHaveBeenCalledWith("/tmp/test-project/.pi/plan-templates/MyPlanv2.md", "# hello");
+    });
+  });
+
+  // --- complete ---
+  describe("complete", () => {
+    it("does not advance when user cancels", async () => {
+      const { exec, ctx, pi } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Modify the plan first");
+      const res = await exec({ action: "complete" });
+      expect(res.details.action).toBe("complete-cancelled");
+      expect(pi.setActiveTools).not.toHaveBeenCalled();
+    });
+
+    it("resets state and restores tools on execute", async () => {
+      const { exec, ctx, pi } = setup();
+      (ctx.ui.select as ReturnType<typeof vi.fn>).mockResolvedValue("Subagent-driven execution");
+      const res = await exec({ action: "complete" });
+      expect(res.details.action).toBe("complete");
+      expect(res.details.execMode).toBe("subagent");
+      expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
+      expect(handlePlanComplete).toHaveBeenCalled();
+      expect(res.details.planFilePath).toBeDefined();
+    });
+  });
+
+  // --- abort ---
+  describe("abort", () => {
+    it("resets state and cleans up session", async () => {
+      const { exec, pi, sessions } = setup();
+      // Pre-populate a session
+      sessions.set("test-session", { isActive: true, phase: "writing", planFilePath: "/tmp/plan.md", requirement: "test", templateName: "t" });
+      const res = await exec({ action: "abort" });
+      expect(res.details.action).toBe("abort");
+      expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
+      expect(sessions.has("test-session")).toBe(false);
+      expect(updatePlanWidget).toHaveBeenCalled();
+    });
+  });
+});
+
+describe("validateAction", () => {
+  it("accepts valid actions", () => {
+    for (const a of PLAN_ACTIONS) expect(validateAction(a)).toBe(true);
+  });
+  it("rejects invalid", () => {
+    expect(validateAction("bogus")).toBe(false);
+  });
+});

package/src/command.ts

@@ -0,0 +1,177 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import type { PlanSessionMap } from "./state.js";
+import { getPlanState, persistPlanState, resetPlanState } from "./state.js";
+import { updatePlanWidget } from "./widget.js";
+
+const MAX_SLUG_LENGTH = 30;
+
+export function registerPlanCommand(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+): void {
+  pi.registerCommand("plan", {
+    description:
+      "Enter plan mode: /plan [description]. " +
+      "Subcommands: /plan abort, /plan status. " +
+      "With no args, show status or detect existing plan.",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const trimmed = args.trim();
+      const sessionId = ctx.sessionManager.getSessionId();
+      const state = getPlanState(sessions, sessionId, ctx);
+
+      // Subcommand: abort
+      if (trimmed === "abort") {
+        await handleAbort(pi, sessions, sessionId, ctx, state);
+        return;
+      }
+
+      // Subcommand: status
+      if (trimmed === "status") {
+        handleStatus(ctx, state);
+        return;
+      }
+
+      // If already in plan mode with no args, show status
+      if (state.isActive && !trimmed) {
+        handleStatus(ctx, state);
+        return;
+      }
+
+      // If already in plan mode with args, warn
+      if (state.isActive && trimmed) {
+        ctx.ui.notify("Plan mode is already active. Use /plan abort to cancel first.", "warning");
+        return;
+      }
+
+      // Reentry: check for existing plan files in .xyz-harness/
+      if (!state.isActive && !trimmed) {
+        const projectDir = ctx.cwd;
+        const harnessDir = path.join(projectDir, ".xyz-harness");
+        const existingPlans = findExistingPlans(harnessDir);
+        if (existingPlans.length > 0) {
+          pi.sendUserMessage(
+            `[PLAN MODE] Found existing plan files:\n${existingPlans.map((p, i) => `  ${i + 1}. ${p}`).join("\n")}\n\n` +
+            `Choose an option:\n` +
+            `  a) Continue existing plan\n` +
+            `  b) Implement existing plan\n` +
+            `  c) Create new plan\n` +
+            `  d) Cancel`,
+          );
+          return;
+        }
+      }
+
+      // Enter plan mode
+      handleEnterPlanMode(pi, sessions, sessionId, ctx, state, trimmed);
+    },
+  });
+}
+
+/** Handle /plan abort subcommand */
+async function handleAbort(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+): Promise<void> {
+  if (!state.isActive) {
+    ctx.ui.notify("No active plan mode.", "info");
+    return;
+  }
+  const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
+  updatePlanWidget(ctx, updatedState);
+  // Restore full tool set (SDK does NOT support undefined)
+  pi.setActiveTools(pi.getAllTools().map((t: { name: string }) => t.name));
+  ctx.ui.notify("Plan mode aborted.", "info");
+}
+
+/** Handle /plan status subcommand */
+function handleStatus(
+  ctx: ExtensionContext,
+  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+): void {
+  if (!state.isActive) {
+    ctx.ui.notify("No active plan mode.", "info");
+    return;
+  }
+  ctx.ui.notify(
+    `Plan Mode: ${state.phase}\nPlan: ${state.planFilePath}\nTemplate: ${state.templateName || "(not selected)"}`,
+    "info",
+  );
+}
+
+/** Find existing plan.md files in .xyz-harness/ subdirectories */
+function findExistingPlans(harnessDir: string): string[] {
+  try {
+    return fs.readdirSync(harnessDir)
+      .filter((f) => {
+        const subDir = path.join(harnessDir, f);
+        return fs.statSync(subDir).isDirectory() && fs.existsSync(path.join(subDir, "plan.md"));
+      })
+      .map((f) => path.join(harnessDir, f, "plan.md"));
+  } catch {
+    return [];
+  }
+}
+
+/** Handle entering plan mode */
+function handleEnterPlanMode(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+  requirement: string,
+): void {
+  const slug = requirement
+        ? requirement.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, MAX_SLUG_LENGTH)
+    : "untitled";
+
+  const projectDir = ctx.cwd;
+  const planDir = path.join(projectDir, ".xyz-harness", slug);
+  fs.mkdirSync(planDir, { recursive: true });
+  const planFilePath = path.join(planDir, "plan.md");
+
+  state.isActive = true;
+  state.phase = "brainstorming";
+  state.planFilePath = planFilePath;
+  state.requirement = requirement;
+  state.templateName = "";
+
+  persistPlanState(pi, state);
+  updatePlanWidget(ctx, state);
+
+  // Restrict tools to read-only set during plan mode
+  pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
+
+  // Inject plan mode system prompt inline
+  pi.sendUserMessage(
+    `[PLAN MODE] Entered plan mode.\n\n` +
+    `Requirement: ${requirement || "(from conversation context)"}\n` +
+    `Plan file: ${planFilePath}\n\n` +
+    `## Constraints\n` +
+    `- READ-ONLY: Do NOT edit any files except the plan file (${planFilePath}).\n` +
+    `- Do NOT run write commands (mkdir, echo, sed, etc.) on non-plan files.\n` +
+    `- All plan content goes to the plan file only.\n\n` +
+    `## Phase B: Brainstorming\n` +
+    `1. **Quick Overview**: ls project root, read README, package.json — build context (< 30s).\n` +
+    `2. **Explore before asking**: grep/read code first. Only ask user for preferences, not code-fact questions.\n` +
+    `3. **Progressive questioning**: Ask 2-3 questions at a time. Use ask_user tool if available.\n` +
+    `4. **Propose 2-3 approaches** with trade-offs + recommendation.\n` +
+    `5. **Assumption audit**: Grep-verify interfaces/types exist. Mark [UNVERIFIED] what can't be verified.\n\n` +
+    `## Phase C: Writing\n` +
+    `1. Call plan tool (list-template) to show available templates.\n` +
+    `2. After user selects template, call plan tool (select-template).\n` +
+    `3. Write chapters in template order — do NOT skip unwritten chapters.\n` +
+    `4. Write all chapters in one turn, then ask user to review.\n\n` +
+    `## Phase D: Completion\n` +
+    `1. Ask user to review the complete plan.\n` +
+    `2. Call plan tool (complete) with isolation method (compact/tree/direct).\n` +
+    `3. After plan complete: check subagent capability → suggest goal + wave or single-agent execution.`,
+  );
+}

package/src/compact.ts

@@ -0,0 +1,196 @@
+import * as fs from "node:fs";
+
+import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent, SessionBeforeTreeEvent } from "@mariozechner/pi-coding-agent";
+
+import type { PlanSessionMap, PlanState } from "./state.js";
+import { getPlanState } from "./state.js";
+
+export function registerPlanEventHandlers(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+): void {
+  pi.on("session_before_compact", async (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const state = getPlanState(sessions, sessionId, ctx);
+    if (!state.isActive) return {};
+
+    const prep = event.preparation;
+
+    // Read plan file content for recovery after compact
+    const planContent = readPlanFileSafe(state.planFilePath);
+
+    // Include phase info for non-complete phases
+    const phaseNote = state.phase !== "complete"
+      ? `\nPhase: ${state.phase}. Plan was in progress — review and continue.`
+      : "\nAwaiting user decision on execution. Do NOT auto-proceed.";
+
+    return {
+      compaction: {
+        summary:
+          `Plan mode active (${state.phase}). Plan file: ${state.planFilePath}\n\n` +
+          `## Plan Content\n${planContent}\n\n` +
+          `Requirement: ${state.requirement}` +
+          phaseNote,
+        firstKeptEntryId: prep?.firstKeptEntryId,
+        tokensBefore: prep?.tokensBefore,
+      },
+    };
+  });
+
+  pi.on("session_before_tree", async (_event: SessionBeforeTreeEvent, ctx: ExtensionContext) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const state = getPlanState(sessions, sessionId, ctx);
+    if (!state.isActive) return {};
+
+    const planContent = readPlanFileSafe(state.planFilePath);
+
+    return {
+      summary: {
+        summary:
+          `Plan mode active (${state.phase}). Plan file: ${state.planFilePath}\n\n` +
+          `## Plan Content\n${planContent}\n\n` +
+          `Read the plan file and execute the implementation.`,
+      },
+    };
+  });
+}
+
+/** Read plan file, return content or error message */
+function readPlanFileSafe(planFilePath: string): string {
+  try {
+    return fs.readFileSync(planFilePath, "utf-8");
+  } catch {
+    return "(plan file could not be read)";
+  }
+}
+
+/** Detect whether goal extension is available via its programming interface */
+export function detectGoalCapability(pi: ExtensionAPI): boolean {
+  try {
+    const api = pi as unknown as Record<string, unknown>;
+    return typeof api.__goalInit === "function";
+  } catch {
+    return false;
+  }
+}
+
+/** Try to initialize goal via programming interface */
+function tryGoalInit(pi: ExtensionAPI, planFilePath: string, ctx: ExtensionContext): boolean {
+  type GoalInitFn = (
+    objective: string,
+    tasks: string[],
+    budget?: { tokenBudget?: number; timeBudgetMinutes?: number; maxTurns?: number },
+    ctx?: ExtensionContext,
+  ) => boolean;
+
+  try {
+    const api = pi as unknown as Record<string, unknown>;
+    const goalInit = api.__goalInit as GoalInitFn | undefined;
+    if (typeof goalInit !== "function") return false;
+
+    const planContent = readPlanFileSafe(planFilePath);
+    if (planContent.startsWith("(")) return false; // read failed
+
+    const objective = `Execute plan: ${planFilePath}`;
+    const tasks = extractPlanSteps(planContent);
+    if (tasks.length === 0) return false;
+
+    return goalInit(objective, tasks, undefined, ctx);
+  } catch {
+    return false;
+  }
+}
+
+/** Extract numbered steps from plan markdown */
+export function extractPlanSteps(planContent: string): string[] {
+  const steps: string[] = [];
+  let inStepsSection = false;
+
+  for (const line of planContent.split("\n")) {
+    // Detect steps section headers
+    if (/^##\s*(实现步骤|实施步骤|Implementation|Steps)/i.test(line)) {
+      inStepsSection = true;
+      continue;
+    }
+    // Exit on next ## header
+    if (inStepsSection && /^##\s/.test(line)) {
+      break;
+    }
+    // Collect numbered list items or checkbox items
+    if (inStepsSection) {
+      const match = line.match(/^\s*(?:\d+\.|- \[[ x]\])\s+(.+)/);
+      if (match && match[1].trim()) {
+        steps.push(match[1].trim());
+      }
+    }
+  }
+
+  // Fallback: if no steps section found, look for any numbered items (limit MAX_FALLBACK_STEPS)
+  const MAX_FALLBACK_STEPS = 10;
+  if (steps.length === 0) {
+    for (const line of planContent.split("\n")) {
+      const match = line.match(/^\s*\d+\.\s+(.+)/);
+      if (match && match[1].trim()) {
+        steps.push(match[1].trim());
+        if (steps.length >= MAX_FALLBACK_STEPS) break;
+      }
+    }
+  }
+
+  return steps;
+}
+
+
+export function handlePlanComplete(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  state: PlanState,
+  isolation: string,
+  execMode: string,
+): void {
+  const planFilePath = state.planFilePath;
+
+  // Build mode-specific steer
+  const modeMessages: Record<string, string> = {
+    subagent: "Execute via subagent-driven development: delegate each task to an independent subagent for parallel execution.",
+    goal: "Execute via /goal: set up tracked task decomposition with budget control using the goal extension.",
+    "single-agent": "Execute step by step in the current session.",
+  };
+  const modeHint = modeMessages[execMode] ?? modeMessages["single-agent"];
+
+  const executeMessage =
+    `Plan approved by user. Plan file: ${planFilePath}\n\n` +
+    `Execution mode: ${execMode}\n` +
+    `${modeHint}\n\n` +
+    `Read the plan file and start implementing.`;
+
+  switch (isolation) {
+    case "compact": {
+      ctx.compact({
+        customInstructions: `Plan file: ${planFilePath}. Read plan and execute implementation.`,
+        onComplete: () => {
+          pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+          tryGoalInit(pi, planFilePath, ctx);
+        },
+        onError: (_error: Error) => {
+          ctx.ui.notify("Compact failed, continuing without isolation.", "warning");
+          pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+          tryGoalInit(pi, planFilePath, ctx);
+        },
+      });
+      break;
+    }
+
+    case "tree": {
+      ctx.ui.notify("Use /tree to manually navigate back. Plan file: " + planFilePath, "info");
+      break;
+    }
+
+    case "direct":
+    default: {
+      pi.sendUserMessage(executeMessage, { deliverAs: "steer" });
+      tryGoalInit(pi, planFilePath, ctx);
+      break;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { registerPlanCommand } from "./command.js";
+import { type PlanSessionMap, reconstructPlanState } from "./state.js";
+import { registerPlanTool } from "./tool.js";
+import { updatePlanWidget } from "./widget.js";
+
+export default function planExtension(pi: ExtensionAPI) {
+  // Per-session state cache — keyed by sessionId
+  const sessions: PlanSessionMap = new Map();
+
+  // Register tool and command
+  registerPlanTool(pi, sessions);
+  registerPlanCommand(pi, sessions);
+
+  // Dynamic import compact handlers — avoids cross-group static import
+  import("./compact.js").then(({ registerPlanEventHandlers }) => {
+    registerPlanEventHandlers(pi, sessions);
+  }).catch((_e: unknown) => {
+    console.warn("[pi-plan] compact handlers load failed:", _e);
+  });
+
+  // Reconstruct state on session start
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const state = reconstructPlanState(ctx);
+    sessions.set(sessionId, state);
+    updatePlanWidget(ctx, state);
+    // If plan mode was active, re-restrict tools to read-only set
+    if (state.isActive) {
+      pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
+    }
+  });
+
+  // Clean up on session end
+  pi.on("session_shutdown", async (_event: unknown, ctx: ExtensionContext) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    sessions.delete(sessionId);
+  });
+}

package/src/state.ts

@@ -0,0 +1,91 @@
+import type { CustomEntry, ExtensionAPI, ExtensionContext, SessionEntry } from "@mariozechner/pi-coding-agent";
+
+export type PlanPhase = "idle" | "brainstorming" | "writing" | "complete";
+
+export interface PlanState {
+  isActive: boolean;
+  phase: PlanPhase;
+  planFilePath: string;
+  requirement: string;
+  templateName: string;
+}
+
+export const DEFAULT_PLAN_STATE: PlanState = {
+  isActive: false,
+  phase: "idle",
+  planFilePath: "",
+  requirement: "",
+  templateName: "",
+};
+
+/** Per-session state cache. Keyed by sessionId. */
+export type PlanSessionMap = Map<string, PlanState>;
+
+/**
+ * Get plan state for a session. Returns cached state if available,
+ * otherwise reconstructs from sessionManager and caches it.
+ */
+export function getPlanState(
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+): PlanState {
+  const cached = sessions.get(sessionId);
+  if (cached) return cached;
+
+  const reconstructed = reconstructPlanState(ctx);
+  sessions.set(sessionId, reconstructed);
+  return reconstructed;
+}
+
+export function persistPlanState(pi: ExtensionAPI, state: PlanState): void {
+  pi.appendEntry("plan-state", {
+    isActive: state.isActive,
+    phase: state.phase,
+    planFilePath: state.planFilePath,
+    requirement: state.requirement,
+    templateName: state.templateName,
+  });
+}
+
+/** Reset plan state to idle, persist, and clean up session cache. */
+export function resetPlanState(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+): PlanState {
+  const state = getPlanState(sessions, sessionId, ctx);
+  state.isActive = false;
+  state.phase = "idle";
+  state.planFilePath = "";
+  state.requirement = "";
+  state.templateName = "";
+  persistPlanState(pi, state);
+  sessions.delete(sessionId);
+  return state;
+}
+
+function isPlanStateEntry(entry: SessionEntry): entry is CustomEntry<Partial<PlanState>> & { customType: "plan-state" } {
+  const e = entry as unknown as Record<string, unknown>;
+  return e.type === "custom" && e.customType === "plan-state" && typeof e.data === "object" && e.data !== null;
+}
+
+export function reconstructPlanState(ctx: ExtensionContext): PlanState {
+  const state = { ...DEFAULT_PLAN_STATE };
+  const entries = ctx.sessionManager.getEntries();
+
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (isPlanStateEntry(entries[i])) {
+      const data = (entries[i] as unknown as { data: Partial<PlanState> }).data;
+      state.isActive = data.isActive ?? false;
+      state.phase = data.phase ?? "idle";
+      state.planFilePath = data.planFilePath ?? "";
+      state.requirement = data.requirement ?? "";
+      state.templateName = data.templateName ?? "";
+      break;
+    }
+  }
+
+  return state;
+}