pi-jar 0.1.0

package/src/plan-view.ts

@@ -0,0 +1,149 @@
+import { getMarkdownTheme, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, Markdown, matchesKey, truncateToWidth, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { parsePlanSections, type PlanSection } from "./plan-utils.ts";
+import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
+
+export type PlanViewAction = "implement" | "compact" | "refine" | "edit" | "stop";
+export interface PlanViewResult { action: PlanViewAction; role?: string }
+export interface PlanViewInput { title: string; text: string; path?: string; roles?: readonly string[]; role?: string }
+
+const ACTIONS: { action: PlanViewAction; label: string }[] = [
+  { action: "implement", label: "▶ Approve & execute" },
+  { action: "compact", label: "◇ Approve, compact & execute" },
+  { action: "refine", label: "✎ Refine" },
+  { action: "stop", label: "■ Stop" }
+];
+type Focus = "toc" | "body" | "actions";
+
+export interface PlanEntry { title: string; level: number; start: number; end: number }
+
+/** Table of contents: a lone H1 becomes the title; H2/H3 become entries; preamble becomes "Overview". */
+export function planEntries(text: string): { title?: string; entries: PlanEntry[] } {
+  const lines = text.replace(/\r/g, "").split("\n");
+  const sections = parsePlanSections(text);
+  const h1 = sections.filter((section) => section.level === 1);
+  const title = h1.length === 1 ? h1[0]!.title : undefined;
+  const visible = sections.filter((section) => section.level <= 3 && !(title && section.level === 1));
+  const entries: PlanEntry[] = visible.map((section) => ({ title: section.title, level: section.level, start: section.start, end: subtreeEnd(sections, section, lines.length) }));
+  const firstStart = visible[0]?.start ?? lines.length;
+  const preambleStart = title ? h1[0]!.start + 1 : 0;
+  if (visible.length && lines.slice(preambleStart, firstStart).some((line) => line.trim())) {
+    entries.unshift({ title: "Overview", level: 2, start: preambleStart - (title ? 1 : 0), end: firstStart });
+  }
+  if (!entries.length) entries.push({ title: title ?? "Plan", level: 2, start: 0, end: lines.length });
+  return { ...(title ? { title } : {}), entries };
+}
+
+function subtreeEnd(sections: readonly PlanSection[], section: PlanSection, total: number): number {
+  const next = sections.find((candidate) => candidate.start > section.start && candidate.level <= section.level);
+  return next?.start ?? total;
+}
+
+/** Full-screen plan review: headings on the left, the selected section on the right, actions below. */
+export async function openPlanView(ctx: ExtensionContext, input: PlanViewInput): Promise<PlanViewResult | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+  const lines = input.text.replace(/\r/g, "").split("\n");
+  const { title, entries } = planEntries(input.text);
+  const roleChoices = ["current", ...(input.roles ?? [])];
+  return ctx.ui.custom<PlanViewResult | undefined>((tui, theme, _keys, done) => {
+    let selected = 0;
+    let focus: Focus = "toc";
+    let action = 0;
+    let role = Math.max(0, roleChoices.indexOf(input.role ?? "current"));
+    let scroll = 0;
+    let tocScroll = 0;
+    let width = 80;
+    let bodyRows = 0;
+    let rendered: { key: string; lines: string[] } | undefined;
+    let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
+    const finish = (value: PlanViewAction) => done({ action: value, ...(roleChoices[role] !== "current" ? { role: roleChoices[role] } : {}) });
+    const body = (bodyWidth: number) => {
+      const entry = entries[selected]!;
+      const key = `${selected}:${bodyWidth}`;
+      if (rendered?.key !== key) {
+        const markdown = new Markdown(lines.slice(entry.start, entry.end).join("\n"), 0, 0, getMarkdownTheme());
+        rendered = { key, lines: markdown.render(Math.max(1, bodyWidth)) };
+      }
+      return rendered.lines;
+    };
+    const selectEntry = (index: number) => { selected = Math.max(0, Math.min(entries.length - 1, index)); scroll = 0; };
+    const scrollBody = (delta: number) => { scroll = Math.max(0, Math.min(Math.max(0, (rendered?.lines.length ?? 0) - bodyRows), scroll + delta)); };
+    return {
+      invalidate() { rendered = undefined; },
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape) || data === "q") return finish("stop");
+        if (/^[1-4]$/.test(data)) return finish(ACTIONS[Number(data) - 1]!.action);
+        if (data === "e") return finish("edit");
+        if (data === "r") role = (role + 1) % roleChoices.length;
+        else if (matchesKey(data, Key.tab)) focus = focus === "toc" ? "body" : focus === "body" ? "actions" : "toc";
+        else if (matchesKey(data, Key.shift("tab"))) focus = focus === "toc" ? "actions" : focus === "body" ? "toc" : "body";
+        else if (matchesKey(data, Key.pageDown) || data === " ") scrollBody(Math.max(1, bodyRows - 2));
+        else if (matchesKey(data, Key.pageUp)) scrollBody(-Math.max(1, bodyRows - 2));
+        else if (data === "g") focus === "toc" ? selectEntry(0) : scrollBody(-Infinity);
+        else if (data === "G") focus === "toc" ? selectEntry(entries.length - 1) : scrollBody(Infinity);
+        else if (matchesKey(data, Key.enter)) {
+          if (focus === "actions") return finish(ACTIONS[action]!.action);
+          focus = focus === "toc" ? "body" : "actions";
+        } else if (matchesKey(data, Key.up) || data === "k") {
+          if (focus === "toc") selectEntry(selected - 1); else if (focus === "body") scrollBody(-1); else action = (action + ACTIONS.length - 1) % ACTIONS.length;
+        } else if (matchesKey(data, Key.down) || data === "j") {
+          if (focus === "toc") selectEntry(selected + 1); else if (focus === "body") scrollBody(1); else action = (action + 1) % ACTIONS.length;
+        } else if (matchesKey(data, Key.left) || data === "h") {
+          if (focus === "actions") action = (action + ACTIONS.length - 1) % ACTIONS.length; else focus = "toc";
+        } else if (matchesKey(data, Key.right) || data === "l") {
+          if (focus === "actions") action = (action + 1) % ACTIONS.length; else focus = "body";
+        }
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        const row = event.y - layout.top;
+        const inContent = row >= 0 && row < layout.rows;
+        const inToc = layout.leftWidth > 0 && event.x < layout.leftWidth + 3;
+        if (event.type === "wheel" && event.wheelDelta) {
+          if (inContent && inToc) selectEntry(selected + Math.sign(event.wheelDelta));
+          else scrollBody(Math.sign(event.wheelDelta) * 3);
+          tui.requestRender(); return { handled: true };
+        }
+        // Leave press/drag/release to Pi so text selection (and copy-on-select) keeps working.
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === 0 && event.x >= width - 3) { finish("stop"); return { handled: true }; }
+        if (inContent && inToc) {
+          const index = tocScroll + row;
+          if (index < entries.length) { selectEntry(index); focus = "toc"; tui.requestRender(); return { handled: true, focus: true }; }
+        }
+        if (inContent) { focus = "body"; tui.requestRender(); return { handled: true, focus: true }; }
+        // Footer: one row per action, then the role row.
+        const footerRow = event.y - layout.footerTop;
+        if (footerRow >= 0 && footerRow < ACTIONS.length) { action = footerRow; finish(ACTIONS[footerRow]!.action); return { handled: true }; }
+        if (footerRow === ACTIONS.length) { role = (role + 1) % roleChoices.length; tui.requestRender(); return { handled: true, focus: true }; }
+      },
+      render(available: number): string[] {
+        width = Math.max(24, available);
+        bodyRows = contentRows(6 + ACTIONS.length, 6);
+        const tocWidth = sidebarWidth(width);
+        const bodyWidth = tocWidth ? width - tocWidth - 6 : width - 4;
+        const narrowHeader = tocWidth ? [] : [theme.fg("accent", `‹ ${selected + 1}/${entries.length} ${entries[selected]!.title} ›`), ""];
+        const content = [...narrowHeader, ...body(bodyWidth)];
+        const rows = bodyRows;
+        scroll = Math.max(0, Math.min(scroll, Math.max(0, content.length - rows)));
+        if (selected < tocScroll) tocScroll = selected;
+        if (selected >= tocScroll + rows) tocScroll = selected - rows + 1;
+        const toc = entries.slice(tocScroll, tocScroll + rows).map((entry, index) => {
+          const current = tocScroll + index === selected;
+          const indent = "  ".repeat(Math.max(0, entry.level - 2));
+          const text = (current ? "▌" : " ") + indent + entry.title;
+          return theme.fg(current ? (focus === "toc" ? "accent" : "warning") : entry.level > 2 ? "dim" : "muted", truncateToWidth(text, tocWidth));
+        });
+        const window = content.slice(scroll, scroll + rows);
+        const position = content.length > rows ? ` ${scroll + 1}–${Math.min(content.length, scroll + rows)}/${content.length}` : "";
+        const actionRows = optionList(theme, ACTIONS.map((item) => item.label), focus === "actions" ? action : -1);
+        const roleText = `⟳ continue with: ${roleChoices[role]}`;
+        const hints = theme.fg("dim", "   Tab focus · ↑↓ move · 1–4 choose · r role · e edit · Esc stop" + (input.path ? " · " + input.path : ""));
+        const split = splitFrame(theme, width, "◆ PLAN" + (title ? " · " + title : "") + " · read-only" + position, toc, window,
+          [...actionRows, theme.fg("accent", roleText) + hints], rows, tocWidth);
+        layout = split.layout;
+        return split.lines;
+      }
+    };
+  }, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%" } });
+}

package/src/plan.ts

@@ -0,0 +1,460 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { promptText } from "./dialogs.ts";
+import { type ModelRoleManager } from "./model-roles.ts";
+import { openPlanView } from "./plan-view.ts";
+import { extractApproachSteps, isSafePlanCommand, PLAN_TEMPLATE, planTextFromSteps, validatePlanDocument } from "./plan-utils.ts";
+import { cleanText } from "./status.ts";
+import { type TodoStore } from "./tasks.ts";
+
+export const PLAN_ENTRY = "pi-jar.plan";
+export const PLAN_SUBMIT_TOOL = "jar_plan_submit";
+type PlanState = { v: 2; enabled: boolean; steps: string[]; text?: string; path?: string; title?: string };
+
+// Only tools with known read-only semantics are allowed. Name suffixes (for example
+// "remote_get") do not prove that an extension or MCP tool is safe to invoke.
+export const PLAN_SAFE_TOOLS = new Set(["read", "bash", "grep", "find", "ls", "jar_ask", "jar_advisor"]);
+/** Allowed only for markdown files inside the session's plan directory. */
+const PLAN_WRITE_TOOLS = new Set(["write", "edit"]);
+const MAX_PLAN_BYTES = 64 * 1024;
+const MAX_REMINDERS = 2;
+
+export function safePlanText(value: string): string {
+  return value.slice(0, MAX_PLAN_BYTES)
+    .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g, "")
+    .replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, (char) => char === "\t" ? "  " : "")
+    .trim();
+}
+
+/** Global, temporary home for plan documents: `$TMPDIR/pi-jar/plans/<session>`. */
+export function planDirectory(sessionId: string | undefined, root = tmpdir()): string {
+  const safe = (sessionId ?? "").replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64) || "session";
+  return join(root, "pi-jar", "plans", safe);
+}
+
+/**
+ * Resolve a tool path and return its real location only when it is a markdown file inside `root`.
+ * Symlinks are resolved on the nearest existing ancestor (and on the file itself when present).
+ */
+export function resolvePlanPath(root: string, raw: unknown, cwd: string): string | undefined {
+  if (typeof raw !== "string" || !raw.trim()) return undefined;
+  const expanded = raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw.trim();
+  const absolute = resolve(cwd, expanded);
+  if (!absolute.toLowerCase().endsWith(".md")) return undefined;
+  let realRoot: string;
+  try { realRoot = realpathSync(root); } catch { return undefined; }
+  let probe = absolute;
+  const rest: string[] = [];
+  while (!existsSync(probe)) {
+    rest.unshift(basename(probe));
+    const parent = dirname(probe);
+    if (parent === probe) return undefined;
+    probe = parent;
+  }
+  let real: string;
+  try { real = join(realpathSync(probe), ...rest); } catch { return undefined; }
+  const inside = relative(realRoot, real);
+  if (!inside || inside.startsWith("..") || isAbsolute(inside)) return undefined;
+  return real;
+}
+
+export class PlanMode {
+  private enabled = false;
+  private steps: string[] = [];
+  private planText = "";
+  private planPath: string | undefined;
+  private planTitle: string | undefined;
+  private directory: string | undefined;
+  private toolsBefore: string[] | undefined;
+  private pendingReview = false;
+  private reminders = 0;
+  private reviewing = false;
+  private compacting = false;
+  private compactGeneration = 0;
+  private executionRestore: (() => Promise<void>) | undefined;
+  private executionRunning = false;
+  private restoreRole: (() => Promise<void>) | undefined;
+  private onEnter: ((ctx: ExtensionContext) => void) | undefined;
+  private readonly pi: ExtensionAPI;
+  private readonly todos: () => TodoStore | undefined;
+  private readonly roles: ModelRoleManager;
+  private readonly todosChanged: (ctx: ExtensionContext) => void;
+  private readonly root: string | undefined;
+
+  constructor(pi: ExtensionAPI, todos: () => TodoStore | undefined, roles: ModelRoleManager, todosChanged: (ctx: ExtensionContext) => void, root?: string) {
+    this.pi = pi;
+    this.todos = todos;
+    this.roles = roles;
+    this.todosChanged = todosChanged;
+    this.root = root;
+  }
+
+  isEnabled(): boolean { return this.enabled; }
+  latestSteps(): string[] { return [...this.steps]; }
+  hasPlan(): boolean { return !!(this.planText || this.steps.length); }
+  summary(): { enabled: boolean; title?: string; steps: number } {
+    return { enabled: this.enabled, ...(this.planTitle ? { title: this.planTitle } : {}), steps: this.steps.length };
+  }
+  /** Called when plan mode starts, so goal automation can pause. */
+  setOnEnter(handler: (ctx: ExtensionContext) => void): void { this.onEnter = handler; }
+
+  private persist(): void {
+    this.pi.appendEntry(PLAN_ENTRY, { v: 2, enabled: this.enabled, steps: this.steps, text: this.planText,
+      ...(this.planPath ? { path: this.planPath } : {}), ...(this.planTitle ? { title: this.planTitle } : {}) } satisfies PlanState);
+  }
+
+  private updateStatus(ctx: ExtensionContext): void {
+    try { ctx.ui.setStatus("pi-jar.plan", this.enabled ? ctx.ui.theme.fg("warning", "◆ PLAN · read-only") : undefined); }
+    catch { /* decorative */ }
+  }
+
+  private planTools(active: string[]): string[] {
+    const available = new Set(this.pi.getAllTools().map((tool) => tool.name));
+    const allowed = [...active.filter((name) => PLAN_SAFE_TOOLS.has(name)), ...PLAN_WRITE_TOOLS, PLAN_SUBMIT_TOOL];
+    return [...new Set(allowed.filter((name) => available.has(name)))];
+  }
+
+  private ensureDirectory(ctx: ExtensionContext): string {
+    const id = (ctx.sessionManager as { getSessionId?: () => string } | undefined)?.getSessionId?.();
+    const directory = planDirectory(id, this.root);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    // On shared temp dirs, refuse a directory another user planted (or a symlink to elsewhere).
+    const info = lstatSync(directory);
+    const uid = process.getuid?.();
+    if (!info.isDirectory() || (uid !== undefined && info.uid !== uid)) throw new Error(directory + " is not a private directory");
+    this.directory = directory;
+    return directory;
+  }
+
+  private async enter(ctx: ExtensionContext, persist = true): Promise<void> {
+    if (this.enabled) return;
+    try { this.ensureDirectory(ctx); }
+    catch (error) { ctx.ui.notify("Plan mode unavailable: cannot create plan directory: " + (error as Error).message, "error"); return; }
+    this.enabled = true;
+    this.pendingReview = false;
+    this.reminders = 0;
+    this.toolsBefore = this.pi.getActiveTools();
+    this.pi.setActiveTools(this.planTools(this.toolsBefore));
+    this.onEnter?.(ctx);
+    this.restoreRole = await this.roles.activateTemporary("plan", ctx);
+    this.updateStatus(ctx);
+    if (persist) this.persist();
+    ctx.ui.notify("Plan mode · read-only. The agent writes a plan file, then you review it.", "info");
+  }
+
+  private async leave(ctx: ExtensionContext, persist = true): Promise<void> {
+    const wasEnabled = this.enabled;
+    this.enabled = false;
+    this.compacting = false;
+    this.pendingReview = false;
+    this.compactGeneration++;
+    if (this.toolsBefore) this.pi.setActiveTools(this.toolsBefore);
+    this.toolsBefore = undefined;
+    if (this.restoreRole) await this.restoreRole();
+    this.restoreRole = undefined;
+    this.updateStatus(ctx);
+    if (persist && wasEnabled) this.persist();
+  }
+
+  private seedTodos(ctx: ExtensionContext): void {
+    const store = this.todos();
+    if (!store) return;
+    const existing = new Set(store.all().map((item) => item.title.trim().toLowerCase()));
+    let changed = false;
+    for (const step of this.steps) {
+      const key = step.trim().toLowerCase();
+      if (!key || existing.has(key)) continue;
+      if (store.add(step, "Approved plan step")) { existing.add(key); changed = true; }
+    }
+    if (changed) this.todosChanged(ctx);
+  }
+
+  private executeMessage(): string {
+    const text = this.planText || planTextFromSteps(this.steps);
+    return [
+      "Implement the approved plan now.",
+      "Work through it step by step. Keep jar_todo synchronized: mark each step done as it completes and add any newly discovered work.",
+      "Verify each step as described in the plan before moving on. If the plan is wrong, say so and adjust rather than silently diverging.",
+      this.planPath ? "The plan file is " + this.planPath + "; re-read it only if this inline copy is lost to compaction." : "",
+      `<plan${this.planPath ? ` path="${this.planPath}"` : ""}>`,
+      text,
+      "</plan>"
+    ].filter(Boolean).join("\n\n");
+  }
+
+  private async implement(ctx: ExtensionContext, role?: string): Promise<void> {
+    this.seedTodos(ctx);
+    await this.leave(ctx);
+    // A role picked in the plan view sticks; otherwise the run uses `implement` and then returns.
+    if (role) await this.roles.activate(role, ctx, true);
+    else if (this.roles.resolve("implement")) this.executionRestore = await this.roles.activateTemporary("implement", ctx);
+    this.pi.sendUserMessage(this.executeMessage(), { deliverAs: "followUp" });
+  }
+
+  private compactThenImplement(ctx: ExtensionContext, role?: string): void {
+    this.compacting = true;
+    const generation = ++this.compactGeneration;
+    ctx.ui.notify("Compacting context while preserving the approved plan…", "info");
+    ctx.compact({
+      customInstructions: "Preserve this approved implementation plan exactly enough to execute it after compaction:\n" + (this.planText || planTextFromSteps(this.steps)),
+      onComplete: () => {
+        if (!this.enabled || generation !== this.compactGeneration) return;
+        this.compacting = false;
+        ctx.ui.notify("Context compacted · starting approved plan", "info");
+        void this.implement(ctx, role);
+      },
+      onError: (error) => {
+        if (generation !== this.compactGeneration) return;
+        this.compacting = false;
+        ctx.ui.notify("Compaction failed; plan mode is still active: " + error.message, "error");
+      }
+    });
+  }
+
+  private writeBack(text: string): void {
+    if (!this.planPath) return;
+    writeFileSync(this.planPath, text.endsWith("\n") ? text : text + "\n", "utf8");
+  }
+
+  /** Open the plan view and act on the user's choice. */
+  async review(ctx: ExtensionContext): Promise<void> {
+    if (this.reviewing || this.compacting || !this.hasPlan()) return;
+    if (!ctx.hasUI || ctx.mode !== "tui") {
+      ctx.ui.notify("Plan ready for review" + (this.planPath ? ": " + this.planPath : "") + ". Run /plan review in the interactive TUI.", "info");
+      return;
+    }
+    this.reviewing = true;
+    this.pendingReview = false;
+    try {
+      while (true) {
+        const roles = this.roles.cycleOrder().filter((role) => this.roles.resolve(role));
+        const result = await openPlanView(ctx, { title: this.planTitle ?? "Plan", text: this.planText || planTextFromSteps(this.steps),
+          ...(this.planPath ? { path: this.planPath } : {}), roles });
+        const action = result?.action ?? "stop";
+        if (action === "edit") {
+          const edited = await ctx.ui.editor("Edit plan" + (this.planPath ? " · " + this.planPath : ""), this.planText);
+          if (edited != null && edited.trim() && edited !== this.planText) {
+            this.planText = safePlanText(edited);
+            this.planTitle = validatePlanDocument(this.planText).title ?? this.planTitle;
+            this.steps = extractApproachSteps(this.planText);
+            try { this.writeBack(this.planText); } catch (error) { ctx.ui.notify("Plan edited in memory but not saved: " + (error as Error).message, "warning"); }
+            this.persist();
+          }
+          continue;
+        }
+        if (action === "implement") { if (!this.enabled) await this.enter(ctx, false); await this.implement(ctx, result?.role); }
+        else if (action === "compact") { if (!this.enabled) await this.enter(ctx, false); this.compactThenImplement(ctx, result?.role); }
+        else if (action === "refine") {
+          const feedback = await promptText(ctx, "Refine plan", "What should change in the plan?");
+          if (feedback) {
+            if (!this.enabled) await this.enter(ctx);
+            this.pi.sendUserMessage("Revise the plan file with this feedback, then submit it again with " + PLAN_SUBMIT_TOOL + ":\n\n" + feedback, { deliverAs: "followUp" });
+          }
+        } else {
+          if (this.enabled) await this.leave(ctx);
+          ctx.ui.notify("Plan stopped · no implementation started", "info");
+        }
+        return;
+      }
+    } finally {
+      this.reviewing = false;
+    }
+  }
+
+  private submit(raw: unknown, ctx: ExtensionContext): { ok: boolean; message: string } {
+    if (!this.enabled) return { ok: false, message: "Plan mode is not active; there is nothing to submit." };
+    const directory = this.directory ?? this.ensureDirectory(ctx);
+    const path = resolvePlanPath(directory, raw, ctx.cwd);
+    if (!path) return { ok: false, message: `Submit a markdown file inside ${directory}.` };
+    let text: string;
+    try {
+      if (statSync(path).size > MAX_PLAN_BYTES) return { ok: false, message: "Plan file is larger than 64 KB; tighten it." };
+      text = safePlanText(readFileSync(path, "utf8"));
+    } catch (error) {
+      return { ok: false, message: "Could not read the plan file: " + (error as Error).message };
+    }
+    const validation = validatePlanDocument(text);
+    if (!validation.ok) {
+      return { ok: false, message: ["The plan is incomplete. Fix it and submit again:",
+        ...validation.missing.map((name) => `- add a \`## ${name}\` section`), ...validation.problems.map((problem) => "- " + problem),
+        "", "Required structure:", PLAN_TEMPLATE].join("\n") };
+    }
+    this.planText = text;
+    this.planPath = path;
+    this.planTitle = validation.title;
+    this.steps = extractApproachSteps(text);
+    this.pendingReview = true;
+    this.persist();
+    return { ok: true, message: `Plan "${validation.title}" submitted for review (${this.steps.length} steps). Stop now; the user reviews it in the plan view.` };
+  }
+
+  private restoreFrom(branch: readonly unknown[]): PlanState | undefined {
+    let state: PlanState | undefined;
+    for (const raw of branch) {
+      if (!raw || typeof raw !== "object") continue;
+      const entry = raw as Record<string, unknown>;
+      if (entry.type !== "custom" || entry.customType !== PLAN_ENTRY || !entry.data || typeof entry.data !== "object") continue;
+      const data = entry.data as Record<string, unknown>;
+      if ((data.v !== 1 && data.v !== 2) || typeof data.enabled !== "boolean" || !Array.isArray(data.steps)) continue;
+      state = {
+        v: 2, enabled: data.enabled,
+        steps: data.steps.filter((item): item is string => typeof item === "string").map((item) => cleanText(item, 240)).filter(Boolean).slice(0, 50),
+        text: typeof data.text === "string" ? safePlanText(data.text) : "",
+        ...(typeof data.path === "string" ? { path: data.path } : {}),
+        ...(typeof data.title === "string" ? { title: cleanText(data.title, 120) } : {})
+      };
+    }
+    return state;
+  }
+
+  private async restore(branch: readonly unknown[], ctx: ExtensionContext): Promise<void> {
+    const state = this.restoreFrom(branch);
+    if (this.enabled) await this.leave(ctx, false);
+    this.steps = state?.steps ?? [];
+    this.planText = state?.text ?? "";
+    this.planPath = state?.path;
+    this.planTitle = state?.title;
+    if (state?.enabled) await this.enter(ctx, false);
+    else this.updateStatus(ctx);
+  }
+
+  private async toggle(ctx: ExtensionContext): Promise<void> {
+    if (this.enabled) { await this.leave(ctx); ctx.ui.notify("Plan mode off", "info"); }
+    else await this.enter(ctx);
+  }
+
+  private context(): string {
+    return [
+      "[PI-JAR PLAN MODE · READ ONLY]",
+      "You are planning, not implementing. Explore with read-only tools; do not modify the repository, remote services or any external state.",
+      `Write the plan as markdown to ${this.directory ?? planDirectory(undefined, this.root)}/<short-kebab-slug>-plan.md with write/edit (the only place writes are allowed).`,
+      "Make it decision-complete: someone new to the conversation can execute it without making design choices.",
+      "Use jar_ask for structured clarifying questions when a real decision is the user's to make.",
+      `Every turn must end with ${PLAN_SUBMIT_TOOL}({ path }) once the plan is ready. Never ask for approval in chat; the user approves in the plan view.`,
+      "Required structure:",
+      PLAN_TEMPLATE
+    ].join("\n");
+  }
+
+  register(): void {
+    this.pi.registerTool?.({
+      name: PLAN_SUBMIT_TOOL,
+      label: "plan",
+      description: "Submit the finished plan markdown file for user review. Only available in pi-jar plan mode.",
+      promptSnippet: "In plan mode, write the plan file then call jar_plan_submit to request review.",
+      parameters: Type.Object({ path: Type.String({ description: "Path of the plan markdown file inside the plan directory." }) }),
+      execute: async (_id, params, _signal, _update, ctx) => {
+        const result = this.submit(params.path, ctx);
+        return { content: [{ type: "text", text: result.message }], details: { ok: result.ok, title: this.planTitle, steps: this.steps.length }, ...(result.ok ? { terminate: true } : {}) };
+      },
+      renderCall(args, theme) { return new Text(theme.fg("toolTitle", theme.bold("plan")) + " " + theme.fg("accent", "submit") + " " + theme.fg("muted", String(args.path ?? "")), 0, 0); },
+      renderResult(result, _options, theme) {
+        const details = result.details as { ok?: boolean; title?: string; steps?: number } | undefined;
+        return new Text(details?.ok ? theme.fg("success", `◆ ${details.title ?? "Plan"} · ${details.steps ?? 0} steps · awaiting review`) : theme.fg("warning", "Plan needs changes before review"), 0, 0);
+      }
+    });
+
+    this.pi.registerCommand("plan", {
+      description: "Plan mode: /plan [prompt] enters read-only planning, /plan review reopens the plan view, /plan off exits",
+      handler: async (args, ctx) => {
+        const text = args.trim();
+        if (/^(?:off|stop|exit)$/i.test(text)) {
+          await this.leave(ctx);
+          ctx.ui.notify("Plan mode off", "info");
+          return;
+        }
+        if (/^(?:review|view|show)$/i.test(text)) {
+          if (!this.hasPlan()) { ctx.ui.notify("No plan yet. Use /plan <what to plan>.", "info"); return; }
+          await this.review(ctx);
+          return;
+        }
+        const wasEnabled = this.enabled;
+        if (!this.enabled) await this.enter(ctx);
+        if (!this.enabled) return;
+        if (text) {
+          this.pi.sendUserMessage(text, { deliverAs: "followUp" });
+          return;
+        }
+        if (wasEnabled && this.hasPlan()) await this.review(ctx);
+      }
+    });
+
+    this.pi.registerShortcut?.(Key.ctrlAlt("p"), {
+      description: "Toggle pi-jar plan mode",
+      handler: async (ctx) => { await this.toggle(ctx); }
+    });
+
+    this.pi.on("tool_call", async (event, ctx) => {
+      if (!this.enabled) return;
+      const input = event.input && typeof event.input === "object" ? event.input as Record<string, unknown> : {};
+      if (event.toolName === "bash") {
+        if (!this.pi.getActiveTools().includes("bash")) return { block: true, reason: "Plan mode is read-only: bash is not active." };
+        if (typeof input.command !== "string" || !isSafePlanCommand(input.command)) {
+          return { block: true, reason: "Plan mode is read-only: this shell command is not on the read-only allowlist." };
+        }
+        return;
+      }
+      if (PLAN_WRITE_TOOLS.has(event.toolName)) {
+        const directory = this.directory ?? this.ensureDirectory(ctx);
+        if (resolvePlanPath(directory, input.path ?? input.file_path, ctx.cwd)) return;
+        return { block: true, reason: `Plan mode: the working tree is read-only. Write your plan to ${directory}/<slug>-plan.md instead.` };
+      }
+      if (event.toolName === PLAN_SUBMIT_TOOL) return;
+      if (!PLAN_SAFE_TOOLS.has(event.toolName) || !this.pi.getActiveTools().includes(event.toolName)) {
+        return { block: true, reason: "Plan mode is read-only: tool " + event.toolName + " is disabled until the plan is approved." };
+      }
+    });
+
+    this.pi.on("before_agent_start", async () => {
+      if (!this.enabled) return;
+      return { message: { customType: "pi-jar.plan-context", content: this.context(), display: false } };
+    });
+
+    this.pi.on("context", async (event) => {
+      if (this.enabled) return;
+      return { messages: event.messages.filter((raw) => {
+        const message = raw as { customType?: string };
+        return message.customType !== "pi-jar.plan-context" && message.customType !== "pi-jar.plan-reminder";
+      }) };
+    });
+
+    this.pi.on("input", (event) => {
+      if (event.source === "interactive") this.reminders = 0;
+    });
+
+    // The final actionable boundary: nudge the agent to submit instead of ending with a chat-only plan.
+    this.pi.on("agent_before_settle", (event, ctx) => {
+      if (!this.enabled || this.pendingReview || this.reviewing || this.compacting || event.continue || event.outcome !== "completed") return;
+      if (this.reminders >= MAX_REMINDERS) {
+        if (this.reminders++ === MAX_REMINDERS) ctx.ui.notify("Plan mode: the agent has not submitted a plan file. Ask it to, or /plan off.", "warning");
+        return;
+      }
+      this.reminders++;
+      return {
+        entries: [{ type: "custom_message", customType: "pi-jar.plan-reminder", display: false,
+          content: `[PI-JAR PLAN MODE] You ended the turn without ${PLAN_SUBMIT_TOOL}. If the plan is ready, write it to the plan directory and call ${PLAN_SUBMIT_TOOL}. If you need a decision from the user, use jar_ask. Do not ask for approval in chat.` }],
+        continue: true
+      };
+    });
+
+    // The approved plan's run ends: return from the temporary `implement` role.
+    this.pi.on("agent_start", () => { if (this.executionRestore) this.executionRunning = true; });
+    this.pi.on("agent_settled", async (_event, ctx) => {
+      if (this.executionRestore && this.executionRunning) {
+        const restore = this.executionRestore;
+        this.executionRestore = undefined;
+        this.executionRunning = false;
+        await restore();
+      }
+      if (this.enabled && this.pendingReview) await this.review(ctx);
+    });
+
+    this.pi.on("session_start", async (_event, ctx) => { await this.restore(ctx.sessionManager.getBranch(), ctx); });
+    this.pi.on("session_tree", async (_event, ctx) => { await this.restore(ctx.sessionManager.getBranch(), ctx); });
+    this.pi.on("session_shutdown", async (_event, ctx) => { if (this.enabled) await this.leave(ctx, false); });
+  }
+}