@gavin-hu/my-pi-agent 0.11.3 → 0.12.0

package/extensions/goal/format.ts

@@ -51,10 +51,18 @@ export function goalObjective(goal: Goal, theme: Theme): string {
 	return goal.status === "achieved" ? paint(theme, "faint", goal.objective) : paint(theme, "label", goal.objective);
 }
 
-/** Model-facing result text. */
-export function formatGoalText(goal: Goal | null): string {
+/**
+ * Model-facing result text. `openTodos` counts the todo items the branch still
+ * has open, so marking a goal achieved can point at work the list still holds.
+ */
+export function formatGoalText(goal: Goal | null, openTodos = 0): string {
 	if (goal === null) return "Goal cleared.";
-	if (goal.status === "achieved") return `Goal achieved: ${goal.objective}`;
+	if (goal.status === "achieved") {
+		const text = `Goal achieved: ${goal.objective}`;
+		if (openTodos <= 0) return text;
+		const items = openTodos === 1 ? "1 todo item is" : `${openTodos} todo items are`;
+		return `${text}\n${items} still open; close or clear the list if that work is done.`;
+	}
 	return `Goal: ${goal.objective}\nKeep this objective in mind as you work, and mark it achieved with the goal tool when it is done.`;
 }
 
@@ -72,7 +80,7 @@ export const GOAL_HELP = [
 	"Set a goal with /goal <what you want to accomplish> and start working on it.",
 	"/goal raw <prompt> records your words verbatim, without confirming them first.",
 	"/goal set <prompt> records the goal without starting work; /goal edit [<prompt>] changes it.",
-	"/goal done  ·  /goal clear  ·  /goal help",
+	"/goal done (or achieved)  ·  /goal clear  ·  /goal help (or -h / --help)",
 ].join("\n");
 
 /** Truncate an objective to `max` display columns, appending `…` when cut. */

package/extensions/goal/tools.ts

@@ -11,6 +11,7 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { GOAL_TOOL } from "../../lib/tool-names.ts";
+import { lastTodos } from "../../lib/todo-state.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
@@ -18,7 +19,7 @@ import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { formatCallText, formatGoalText } from "./format.ts";
 import type { GoalRuntime } from "./runtime.ts";
 import { GoalParams, GoalResult, normalizeGoal, type GoalArgs } from "./schema.ts";
-import { GoalResult as GoalResultView } from "./tui.ts";
+import { GoalHeader } from "./tui.ts";
 import type { GoalAction, GoalDetails } from "./types.ts";
 
 export const TOOL_NAME = GOAL_TOOL;
@@ -45,13 +46,30 @@ function toStructuredContent(details: GoalDetails): Record<string, JsonValue> {
 	return content;
 }
 
+/**
+ * How many items the branch's todo list still has open.
+ *
+ * `todo` is the *how* to the goal's *what*, so completing one while the other
+ * still holds work is worth saying out loud. The list is read from the branch
+ * (`lib/todo-state.ts`), so no todo module is imported.
+ */
+function openTodoCount(entries: Iterable<unknown>): number {
+	return lastTodos(entries).filter((todo) => todo.status !== "completed").length;
+}
+
 /**
  * Build the tool result for one call. A rejected call (`error` set) carries the
  * unchanged goal so the model can retry, and is marked `isError`.
  */
-function goalResult(details: GoalDetails, error?: string) {
+function goalResult(details: GoalDetails, options: { error?: string; openTodos?: number } = {}) {
+	const { error, openTodos = 0 } = options;
 	return {
-		content: [{ type: "text" as const, text: error === undefined ? formatGoalText(details.goal) : `Error: ${error}` }],
+		content: [
+			{
+				type: "text" as const,
+				text: error === undefined ? formatGoalText(details.goal, openTodos) : `Error: ${error}`,
+			},
+		],
 		details,
 		structuredContent: toStructuredContent(details),
 		...(error === undefined ? {} : { isError: true as const }),
@@ -82,10 +100,14 @@ export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {
 				const goal = normalizeGoal(args);
 				const action = goal === null ? "clear" : goal.status === "achieved" ? "achieve" : "set";
 				runtime.setGoal(goal, ctx);
-				return goalResult({ goal, action });
+				const openTodos = action === "achieve" ? openTodoCount(ctx.sessionManager.getBranch()) : 0;
+				return goalResult({ goal, action }, { openTodos });
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return goalResult({ goal: runtime.getGoal(), action: attemptedAction(args), error: message }, message);
+				return goalResult(
+					{ goal: runtime.getGoal(), action: attemptedAction(args), error: message },
+					{ error: message },
+				);
 			}
 		},
 
@@ -115,9 +137,7 @@ export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {
 				return text;
 			}
 			const view =
-				context.lastComponent instanceof GoalResultView
-					? context.lastComponent
-					: new GoalResultView(details.goal, theme);
+				context.lastComponent instanceof GoalHeader ? context.lastComponent : new GoalHeader(details.goal, theme);
 			view.update(details.goal, theme);
 			return view;
 		},

package/extensions/goal/tui.ts

@@ -44,7 +44,7 @@ export class GoalWidget implements Component {
 }
 
 /** Transcript result block: the status header, separated from the call line. */
-export class GoalResult implements Component {
+export class GoalHeader implements Component {
 	private goal: Goal;
 	private theme: Theme;
 

package/extensions/memory/README.md

@@ -173,7 +173,7 @@ when consolidating.
 |---|---|
 | Registration | The default export registers the `memory` tool, the `/memory` command, and four event listeners; nothing long-lived. |
 | Events | `session_start` loads config and both stores; `before_agent_start` injects the `[MEMORY]` message; `context` keeps only the newest injection; `session_shutdown` clears the cache. The runtime refreshes both stores from their file stamps whenever the notes are read. |
-| Tool | `exposure: "direct"`, `executionMode: "sequential"`, `annotations` and `outputSchema` as above. |
+| Tool | direct exposure (the default), `executionMode: "sequential"`, `annotations` and `outputSchema` as above. |
 | State | External markdown, **not** branch state: the tool result's `details`/`structuredContent` mirror the call but the notes are read from disk and survive independently of `/resume` and `/tree`. |
 | UI | `ctx.ui.notify`, `editor`, and `confirm`, guarded by `ctx.hasUI`, plus the `/memory` picker (`ctx.ui.custom`) in the TUI. |
 | Plan mode | Blocked — `plan`'s read-only policy allows only `readOnlyHint` tools, so memory cannot be mutated while planning; recall still works. |

package/extensions/plan/README.md

@@ -174,6 +174,10 @@ instead of opening a server nobody can use. The browser's **Approve & run** is
 offered only for the review `exit_plan_mode` opens, since only that flow owns
 leaving plan mode; `/plan review` stays comment-only.
 
+Aborting the turn closes a browser review. `exit_plan_mode` forwards the call's
+abort signal to the review server, so an aborted turn returns "not approved"
+and stops listening instead of waiting on a page nobody is watching.
+
 ### Transcript
 
 The three tool rows reuse the transcript component, and `exit_plan_mode`
@@ -227,8 +231,11 @@ command. The read-only guarantee is layered:
   transcript and in non-TUI notices; a plan file cannot drive the terminal.
 - **Loopback browser review.** The review server binds `127.0.0.1` and requires a
   random per-session token in the URL, rejects a missing or foreign `Host`
-  header, serves only `GET`/`POST`, and caps the request body; the page renders plan and comment text
-  with DOM text nodes, never `innerHTML`, so a plan cannot script the reviewer.
+  header, serves only `GET`, `HEAD`, and `POST`, and caps the request body; the
+  page renders plan and comment text with DOM text nodes, never `innerHTML`, so a
+  plan cannot script the reviewer. The page also refuses to be framed
+  (`frame-ancestors 'none'` and `X-Frame-Options: DENY`), so a local page cannot
+  clickjack **Approve & run**.
 
 ## Read-only git shell
 
@@ -356,12 +363,13 @@ file and returns them to the model.
   update, depending on the mode).
 - **Loopback and tokenized.** The server binds `127.0.0.1`, carries a random
   per-session token in the URL, rejects a missing or foreign `Host` header,
-  serves only `GET` and `POST`, and caps the request body. A save or cancel
+  serves only `GET`, `HEAD`, and `POST`, and caps the request body. A save or cancel
   resolves the session only after its HTTP response is delivered, so the browser
   never sees a false "Failed to fetch". The last bound port is remembered per
   plan, so reviewing the same plan again reuses the origin (and the browser's
-  saved theme with it). It is closed on save, cancel, tab close, or
-  `session_shutdown`.
+  saved theme with it). It is closed on save, cancel, a dropped event stream, or
+  `session_shutdown`; a reload reconnects inside that grace, so refreshing or
+  reloading a conflicted page does not end the review.
 
 | Route | Result |
 |---|---|
@@ -406,7 +414,7 @@ file and returns them to the model.
 
 | Integration point | How |
 |---|---|
-| Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`); no `outputSchema`/`structuredContent`. |
+| Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
 | Commands and flags | `/plan` (toggle, or enter and send a task), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
 | State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })` and rebuilt from `ctx.sessionManager.getBranch()`; the last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. The content each review showed is kept in runtime memory (keyed by resolved path) for the changed markers. |
 | Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
@@ -414,6 +422,13 @@ file and returns them to the model.
 
 ## Design notes
 
+- **One review loop owns the human gate.** `review.ts` asks however the session
+  is attached — TUI screen, dialog plus editor, remote file plus digest, or
+  browser — and returns one `ReviewDecision`, so `exit_plan_mode` and
+  `/plan review` no longer carry two copies of the browser lifecycle and the
+  tool's own `for(;;)` with a `continue` per outcome. The loop also owns the
+  baseline rule (mark what the screen showed, after it showed it) and forwards
+  the call's abort signal, which is what closes a review on an aborted turn.
 - **Two tools, not one.** `EnterPlanMode`/`ExitPlanMode` are a pair: entering is
   consent to explore read-only, exiting is consent to act. A single toggle tool
   cannot express "the model wants to plan but the user declines".
@@ -500,8 +515,9 @@ file and returns them to the model.
 | `plans.ts` | Plan-file store: slug/stamp naming, directory resolution, containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
 | `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the section diff, and the checkbox edit. |
-| `runtime.ts` | Enabled state, tool gating, persistence, control-tool identity, footer status. |
-| `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`. |
+| `runtime.ts` | Enabled state, tool gating, persistence, control-tool identity, footer status, the review baseline. |
+| `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`: schemas, results, transcripts, and the approval-time todo seed. |
+| `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
 | `commands.ts` | `/plan` (enter, optional task) and the `/plan review [path]` browser subcommand. |
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, approve/refine/browser/keep). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks). |

package/extensions/plan/blocks.ts

@@ -14,7 +14,7 @@
  * step.
  */
 
-import { normalizeHeadingText } from "./steps.ts";
+import { FENCE, HEADING } from "./steps.ts";
 
 /** How a block is rendered and grouped. */
 export type PlanBlockKind = "heading" | "paragraph" | "list" | "code" | "quote" | "table" | "hr" | "blank";
@@ -30,10 +30,6 @@ export interface PlanBlock {
 	lines: string[];
 }
 
-/** ATX heading outside a fence. */
-const HEADING = /^ {0,3}#{1,6}(?:\s|$)/;
-/** Code-fence opener or closer (backticks or tildes). */
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 /** A list marker with its leading indentation and trailing gap. */
 const LIST_ITEM = /^( *)([-*+]|\d+[.)])(\s+)/;
 /** A blockquote line. */
@@ -190,36 +186,6 @@ export function blockAt(blocks: PlanBlock[], line: number): PlanBlock | undefine
 	return candidate;
 }
 
-/** A heading in a plan, for the review page's section outline. */
-export interface PlanHeading {
-	/** 0-based source line of the heading. */
-	line: number;
-	/** Heading level, 1-6. */
-	level: number;
-	/** Heading text with inline markdown removed. */
-	text: string;
-}
-
-/** ATX heading with its captured level and raw text. */
-const HEADING_PARTS = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
-
-/** Strip the inline markdown an outline label should not show. */
-function headingText(raw: string): string {
-	return normalizeHeadingText(raw);
-}
-
-/** The plan's headings in order, for the outline. */
-export function planHeadings(blocks: PlanBlock[]): PlanHeading[] {
-	const headings: PlanHeading[] = [];
-	for (const block of blocks) {
-		if (block.kind !== "heading") continue;
-		const match = block.lines[0]?.match(HEADING_PARTS);
-		if (!match) continue;
-		headings.push({ line: block.start, level: match[1].length, text: headingText(match[2]) });
-	}
-	return headings;
-}
-
 /** The source inside a fenced code block, without its opening and closing fence lines. */
 export function codeBody(block: PlanBlock): string[] {
 	if (block.kind !== "code") return block.lines.slice();

package/extensions/plan/commands.ts

@@ -11,6 +11,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { isRemoteTurn } from "../../lib/interaction.ts";
 import { feedbackSummary } from "./feedback.ts";
 import { READ_ONLY_SUMMARY } from "./policy.ts";
+import { runBrowserReview } from "./review.ts";
 import type { PlanRuntime } from "./runtime.ts";
 import { createPlanWebReview, type PlanWebReview } from "./web.ts";
 
@@ -57,34 +58,39 @@ async function reviewInBrowser(
 	// to the newest plan file in the plans directory.
 	const file = path ? await runtime.plans.read(ctx.cwd, path) : await runtime.plans.latest(ctx.cwd);
 	if (!file) {
-		if (path) ctx.ui.notify(`plan review: no plan file at ${path}`, "error");
-		else ctx.ui.notify("plan review: no plan to review; write one with write_plan or pass a path.", "warning");
+		if (path) ctx.ui.notify(`Plan review: no plan file at ${path}`, "error");
+		else ctx.ui.notify("Plan review: no plan to review; write one with write_plan or pass a path.", "warning");
 		return;
 	}
 	// The server is loopback-only, so a remote turn cannot drive it.
 	if (isRemoteTurn(ctx)) {
-		ctx.ui.notify("plan review: browser review needs the local machine.", "warning");
+		ctx.ui.notify("Plan review: browser review needs the local machine.", "warning");
 		return;
 	}
 
 	const previous = runtime.reviewed(file.path);
-	runtime.markReviewed(file.path, file.content);
-	const session = await web.start(ctx.cwd, file, { previous }).catch(() => undefined);
-	if (!session) {
-		ctx.ui.notify("plan review: could not start the browser review server.", "error");
+	const result = await runBrowserReview(web, ctx.cwd, file, {
+		canApprove: false,
+		previous,
+		// Mark only once the page is actually open: a failed start must not consume
+		// the baseline for a plan nobody saw.
+		onOpened: (session) => {
+			runtime.markReviewed(file.path, file.content);
+			ctx.ui.notify(`Plan review: opened ${session.url}`, "info");
+		},
+	});
+	if (!result) {
+		ctx.ui.notify("Plan review: could not start the browser review server.", "error");
 		return;
 	}
-	ctx.ui.notify(`plan review: opened ${session.url}`, "info");
-	const result = await session.done;
-	await session.close();
 
 	if (result.status === "cancelled") {
-		ctx.ui.notify("plan review: closed without saving.", "info");
+		ctx.ui.notify("Plan review: closed without saving.", "info");
 		return;
 	}
 	const summary = feedbackSummary(result.annotations);
 	if (!summary) {
-		ctx.ui.notify("plan review: saved with no comments.", "info");
+		ctx.ui.notify("Plan review: saved with no comments.", "info");
 		return;
 	}
 	const message = runtime.isEnabled()

package/extensions/plan/plans.ts

@@ -295,7 +295,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	/**
 	 * Write the browser review comments into an existing plan, replacing any
 	 * feedback already stored there. The file must already be a contained plan,
-	 * so this is the same path-safe write as `setStep`.
+	 * so this is the same path-safe write as `setSteps`.
 	 */
 	const saveFeedback = async (cwd: string, planPath: string, annotations: PlanAnnotation[]): Promise<StoredPlan> => {
 		const plan = await read(cwd, planPath);

package/extensions/plan/policy.ts

@@ -7,9 +7,10 @@
  * from `index.ts` so tests and future read-only modes can build the policy
  * without loading the extension wiring.
  *
- * Plan mode keeps raw shell on a short leash: `bash` and `powershell` stay
- * active only so the model can run read-only git commands, and the `tool_call`
- * guard in `index.ts` refuses anything that is not one (see `git-bash.ts`).
+ * Plan mode keeps raw shell on a short leash: `bash` stays active only so the
+ * model can run read-only git commands (the `tool_call` guard in `index.ts`
+ * refuses anything that is not one, see `git-bash.ts`), and `powershell` is
+ * blocked outright so plan mode has one shell to reason about.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/extensions/plan/review.ts

@@ -0,0 +1,243 @@
+/**
+ * The plan review gate: ask the human about a plan file and return one decision.
+ *
+ * A review has three presentations — the scrollable TUI screen, a select plus
+ * editor for dialog-only modes, and a remote turn's plan file plus digest — and
+ * one optional browser server. This module owns the loop that switches between
+ * them, so `exit_plan_mode` and `/plan review` share one lifecycle and only map
+ * the returned {@link ReviewDecision} to their own result.
+ *
+ * It also owns the review baseline: a review marks the content the human was
+ * actually shown, never content that was only about to be shown, and the abort
+ * signal reaches the browser server so an aborted turn closes it.
+ */
+
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import { askHuman } from "../../lib/interaction.ts";
+import { FULL_SCREEN_OVERLAY } from "../../lib/tui/chrome.ts";
+import { feedbackSummary, type PlanAnnotation } from "./feedback.ts";
+import type { PlanStore, StoredPlan } from "./plans.ts";
+import { extractPlanSteps } from "./steps.ts";
+import { PlanViewComponent, type PlanViewAction } from "./tui.ts";
+import type { PlanReviewResult, PlanReviewSession, PlanWebReview } from "./web.ts";
+
+/** A choice from the review screen, with the refinement the screen carried, if any. */
+interface PlanReviewChoice {
+	action: PlanViewAction;
+	refinement?: string;
+}
+
+/** A dialog-only choice: post the full plan text, then ask again. Never returned. */
+type ReviewChoice = PlanReviewChoice | { action: "send" };
+
+/** What a review decided, and the plan state it decided on. */
+export type ReviewDecision =
+	| { action: "approve"; plan: StoredPlan; comments: PlanAnnotation[] }
+	| {
+			action: "refine";
+			plan: StoredPlan;
+			/** The refinement request: the saved comments, or what the user typed. */
+			refinement: string;
+			comments: PlanAnnotation[];
+			/** True when the request came from the browser, which is reported differently. */
+			fromBrowser: boolean;
+	  }
+	| { action: "keep"; plan: StoredPlan };
+
+/** What the previous review showed, so this one can mark what changed. */
+export interface ReviewBaselines {
+	reviewed(path: string): string | undefined;
+	markReviewed(path: string, content: string): void;
+}
+
+/** Everything one review needs: whom to ask, where to ask, and what to compare against. */
+export interface ReviewPlanOptions {
+	ctx: ExtensionToolContext;
+	web: PlanWebReview;
+	/** Re-read the plan after a browser review that may have changed it. */
+	plans: Pick<PlanStore, "read">;
+	baselines: ReviewBaselines;
+	plan: StoredPlan;
+	/** Aborting the turn closes a browser review and returns the plan unapproved. */
+	signal?: AbortSignal;
+}
+
+/** Prompt shown by the dialog-based refine editor in non-TUI modes. */
+const REFINE_PROMPT = "Refine the plan — what should change? (Enter to save, Esc to cancel)";
+
+/** How much of one step the remote digest shows. */
+const DIGEST_STEP_CHARS = 90;
+
+/** The refinement request used when a browser save carried no comments. */
+const NO_BROWSER_COMMENTS = "See the review comments in the plan file.";
+
+/**
+ * A one-message digest of the plan for a remote review.
+ *
+ * The file is the primary artifact, but a phone client may never render or open
+ * it, and the peer still has to choose approve / refine. The digest carries the
+ * title, the step count, and the first few steps; the full text follows as a
+ * file or as the fallback message.
+ */
+function planReviewDigest(content: string): string {
+	const title = /^#\s+(.+)$/m.exec(content)?.[1]?.trim();
+	const steps = extractPlanSteps(content);
+	const count = steps.length;
+	const head = `Plan${title ? `: ${title}` : ""}${count > 0 ? ` (${count} step${count === 1 ? "" : "s"})` : ""}`;
+	const preview = steps.slice(0, 3).map((step, index) => {
+		const text = step.content.replace(/\s+/g, " ").trim();
+		const shown = text.length > DIGEST_STEP_CHARS ? `${text.slice(0, DIGEST_STEP_CHARS - 1)}…` : text;
+		return `${index + 1}. ${shown}`;
+	});
+	const more = count > preview.length ? `… (${count - preview.length} more)` : "";
+	return [head, ...preview, more, "The full plan is attached above, or sent as text if the file failed."]
+		.filter((line) => line !== "")
+		.join("\n");
+}
+
+/**
+ * Ask the user to review the plan file. The TUI opens the scrollable review
+ * screen (with an inline refine editor); dialog-capable modes (RPC) fall back to
+ * a select plus the refine editor; a remote turn gets the plan file and a digest
+ * first. Asking for the full plan re-enters with the text only, then shows the
+ * choices again.
+ */
+async function askPlanReview(
+	ctx: ExtensionToolContext,
+	plan: StoredPlan,
+	previous: string | undefined,
+): Promise<PlanReviewChoice> {
+	let sentFullText = false;
+	for (;;) {
+		const outcome = await askHuman<ReviewChoice>(ctx, {
+			custom: async () => {
+				const choice = await ctx.ui.custom<PlanReviewChoice | undefined>(
+					(tui, theme, _keybindings, done) =>
+						new PlanViewComponent({
+							plan,
+							previous,
+							theme,
+							onClose: (action, refinement) => done({ action, refinement }),
+							requestRender: () => tui.requestRender(),
+							viewportRows: () => tui.terminal?.rows,
+							tui,
+						}),
+					FULL_SCREEN_OVERLAY,
+				);
+				return choice ?? { action: "keep" };
+			},
+			dialogs: async () => {
+				const choice = await ctx.ui.select("Plan mode — what next?", [
+					"Approve and execute",
+					"Send the full plan",
+					"Refine the plan",
+					"Keep planning",
+				]);
+				if (choice === "Approve and execute") return { action: "approve" };
+				if (choice === "Send the full plan") return { action: "send" };
+				if (choice === "Refine the plan") return { action: "refine" };
+				return { action: "keep" };
+			},
+			// A remote turn gets the plan file up front, falling back to the full text;
+			// a local TUI turn ignores both and renders the component. The digest goes
+			// out either way so the choices stay answerable when a phone client does not
+			// render the file bubble.
+			file: sentFullText ? undefined : { path: plan.path, name: basename(plan.relativePath) },
+			body: plan.content,
+			note: sentFullText ? undefined : planReviewDigest(plan.content),
+		});
+		if (outcome.action !== "send") return outcome;
+		sentFullText = true;
+	}
+}
+
+/** How a browser review may decide, and what to report when it opens. */
+export interface BrowserReviewOptions {
+	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove: boolean;
+	/** The content the previous review showed, so the page can mark changed sections. */
+	previous?: string;
+	/** Aborting the turn closes the session as cancelled. */
+	signal?: AbortSignal;
+	/** Called once the server is listening and the browser was opened. */
+	onOpened?: (session: PlanReviewSession) => void;
+}
+
+/**
+ * Open a browser review and wait for its outcome. `undefined` means the server
+ * could not start, so the caller can fall back to the screen it came from.
+ */
+export async function runBrowserReview(
+	web: PlanWebReview,
+	cwd: string,
+	plan: StoredPlan,
+	options: BrowserReviewOptions,
+): Promise<PlanReviewResult | undefined> {
+	if (options.signal?.aborted) return { status: "cancelled" };
+	const session = await web
+		.start(cwd, plan, { canApprove: options.canApprove, previous: options.previous, signal: options.signal })
+		.catch(() => undefined);
+	if (!session) return undefined;
+	options.onOpened?.(session);
+	try {
+		return await session.done;
+	} finally {
+		await session.close();
+	}
+}
+
+/**
+ * Ask the user about `plan` and return the decision. Approve and keep end the
+ * review; a refinement is handed back to the model; a browser review that is
+ * cancelled returns to the screen it was opened from.
+ */
+export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDecision> {
+	const { ctx, web, plans, baselines, signal } = options;
+	let plan = options.plan;
+	for (;;) {
+		// An aborted turn has nobody left to answer the screen.
+		if (signal?.aborted) return { action: "keep", plan };
+		// Read the baseline before the screen and mark it after, so what the next
+		// review compares against is the content this one actually showed.
+		const previous = baselines.reviewed(plan.path);
+		const choice = await askPlanReview(ctx, plan, previous);
+		baselines.markReviewed(plan.path, plan.content);
+
+		if (choice.action === "approve") return { action: "approve", plan, comments: [] };
+		if (choice.action === "keep") return { action: "keep", plan };
+		if (choice.action === "refine") {
+			const refinement = choice.refinement ?? (await ctx.ui.editor(REFINE_PROMPT, ""))?.trim();
+			// An empty or cancelled editor returns to the review screen instead of
+			// being reported as "not approved".
+			if (!refinement) continue;
+			return { action: "refine", plan, refinement, comments: [], fromBrowser: false };
+		}
+		// An unrecognized action keeps planning rather than opening a server.
+		if (choice.action !== "browser") return { action: "keep", plan };
+
+		const result = await runBrowserReview(web, ctx.cwd, plan, {
+			canApprove: true,
+			previous,
+			signal,
+			onOpened: (session) => ctx.ui.notify(`Plan review: opened ${session.url}`, "info"),
+		});
+		if (!result) {
+			ctx.ui.notify("Plan review: could not start the browser review server.", "error");
+			continue;
+		}
+		if (result.status === "approved") return { action: "approve", plan: result.plan, comments: result.annotations };
+		if (result.status === "saved") {
+			return {
+				action: "refine",
+				plan: result.plan,
+				refinement: feedbackSummary(result.annotations) || NO_BROWSER_COMMENTS,
+				comments: result.annotations,
+				fromBrowser: true,
+			};
+		}
+		// Cancelled or the tab closed: the file may have been rewritten underneath,
+		// so re-read it before showing the screen again.
+		plan = (await plans.read(ctx.cwd, plan.path)) ?? plan;
+	}
+}

package/extensions/plan/runtime.ts

@@ -177,6 +177,10 @@ export function createPlanRuntime(
 		toggle: (ctx) => setEnabled(!enabled, ctx, true),
 		restore: (ctx) => {
 			lastPlanPath = undefined;
+			// The baseline belongs to the branch that was reviewed: a resumed or
+			// tree-restored session starts without one rather than marking every section
+			// changed against a review this branch never showed.
+			reviewedPlans.clear();
 			const persisted = readPersistedState(ctx);
 			// `--plan` starts a fresh session in plan mode; an explicit persisted
 			// choice (including a later disable) wins over the launch flag.