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

package/extensions/plan/runtime.ts

@@ -6,7 +6,9 @@
  * (present the plan for approval) and `write_plan` (save the plan artifact under
  * `.pi/plans`). Disabling restores exactly what it hid. The enabled flag is
  * persisted as a custom session entry so `/resume` and `/tree` follow the
- * branch, and it is also mirrored into the footer status.
+ * branch, and it is also mirrored into the footer status. The review baseline
+ * travels the same way, as one digest per heading section, so the changed-section
+ * markers survive a resume too.
  *
  * `write_plan` is the one sanctioned write while planning. The read-only guard
  * in `index.ts` permits a control tool only when the registered tool is this
@@ -23,7 +25,8 @@ import type { ReadOnlyPolicy } from "../../lib/policy.ts";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { createPlanStore, type PlanStore } from "./plans.ts";
-import type { PlanModeEntry } from "./types.ts";
+import { sameSections, sectionDigests, type SectionDigest } from "./plan-text.ts";
+import type { PlanModeEntry, ReviewBaselineEntry } from "./types.ts";
 
 /** Tool the model calls to leave plan mode after approval. */
 export const EXIT_TOOL = "exit_plan_mode";
@@ -33,8 +36,10 @@ export const ENTER_TOOL = "enter_plan_mode";
 export const WRITE_PLAN_TOOL = "write_plan";
 /** Tool the model calls to keep an approved plan's steps current. */
 export const SET_PLAN_STEPS_TOOL = "set_plan_steps";
-/** Custom-entry type used for persistence. */
+/** Custom-entry type used for plan-mode state. */
 export const STATE_TYPE = "plan-mode";
+/** Custom-entry type used for a plan's review baseline. */
+export const BASELINE_TYPE = "plan-baseline";
 
 /** Longest plan-file basename shown in the footer chip. */
 const STATUS_NAME_LENGTH = 28;
@@ -58,27 +63,60 @@ export interface PlanRuntime {
 	lastPlanPath(): string | undefined;
 	/** Remember a written plan and repaint the footer. */
 	setLastPlan(ctx: ExtensionContext, path: string): void;
-	/** The content a review last presented for `path`, for the changed markers. */
-	reviewed(path: string): string | undefined;
-	/** Remember what a review just presented; memory only, keyed by resolved path. */
+	/** The sections the last review of `path` showed, restored with the branch. */
+	reviewed(path: string): SectionDigest[] | undefined;
+	/** Remember what a review just showed, as a session entry on this branch. */
 	markReviewed(path: string, content: string): void;
 }
 
-/** The last plan-mode entry on the branch, with the tools it hid. */
-function readPersistedState(ctx: ExtensionContext): PlanModeEntry | undefined {
-	let state: PlanModeEntry | undefined;
+/** What the branch carries: the last plan-mode state, and a baseline per plan. */
+interface BranchState {
+	mode: PlanModeEntry | undefined;
+	baselines: Map<string, SectionDigest[]>;
+}
+
+/** Well-formed `{ title, digest }` pairs from untrusted branch data, or undefined. */
+function readSections(value: unknown): SectionDigest[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const sections: SectionDigest[] = [];
+	for (const raw of value) {
+		const section = raw as { title?: unknown; digest?: unknown } | null | undefined;
+		if (typeof section?.title !== "string" || typeof section.digest !== "string") return undefined;
+		sections.push({ title: section.title, digest: section.digest });
+	}
+	return sections;
+}
+
+/**
+ * The last plan-mode state and the last review baseline per plan on the branch.
+ * One pass, because reading the branch walks the whole session.
+ */
+function readBranchState(ctx: ExtensionContext): BranchState {
+	let mode: PlanModeEntry | undefined;
+	const baselines = new Map<string, SectionDigest[]>();
 	for (const raw of ctx.sessionManager.getBranch()) {
 		const entry = raw as { type?: string; customType?: string; data?: unknown };
-		if (entry.type !== "custom" || entry.customType !== STATE_TYPE) continue;
-		const data = entry.data as { enabled?: unknown; removed?: unknown } | null | undefined;
-		if (typeof data?.enabled !== "boolean") continue;
-		// Branch data is untrusted; keep only string tool names.
-		const removed = Array.isArray(data.removed)
-			? data.removed.filter((name): name is string => typeof name === "string")
-			: undefined;
-		state = removed ? { enabled: data.enabled, removed } : { enabled: data.enabled };
+		if (entry.type !== "custom") continue;
+		if (entry.customType === STATE_TYPE) {
+			const data = entry.data as { enabled?: unknown; removed?: unknown } | null | undefined;
+			if (typeof data?.enabled !== "boolean") continue;
+			// Branch data is untrusted; keep only string tool names.
+			const removed = Array.isArray(data.removed)
+				? data.removed.filter((name): name is string => typeof name === "string")
+				: undefined;
+			mode = removed ? { enabled: data.enabled, removed } : { enabled: data.enabled };
+			continue;
+		}
+		if (entry.customType !== BASELINE_TYPE) continue;
+		const data = entry.data as { path?: unknown; sections?: unknown } | null | undefined;
+		if (typeof data?.path !== "string") continue;
+		const sections = readSections(data.sections);
+		// Last entry per path wins, the same rule the mode entry follows. The key is
+		// canonical, so a path recorded on another platform or relative to another cwd
+		// still answers a lookup for the plan it names.
+		if (sections) baselines.set(resolve(data.path), sections);
 	}
-	return state;
+	return { mode, baselines };
 }
 
 /** Compare two paths, resolving symlinks when possible so `/tmp` and `/private/tmp` match. */
@@ -107,10 +145,10 @@ export function createPlanRuntime(
 ): PlanRuntime {
 	let enabled = false;
 	let lastPlanPath: string | undefined;
-	// The content each plan path last showed in a review, so the next review can
-	// mark what changed. Memory only: a resumed session has no baseline and shows
-	// no markers, which is better than claiming everything changed.
-	const reviewedPlans = new Map<string, string>();
+	// The section digests each plan path last showed in a review, so the next review
+	// can mark what changed. Persisted with the branch, so `/resume` and `/tree`
+	// compare against the review this branch actually showed.
+	const reviewedPlans = new Map<string, SectionDigest[]>();
 	// Tools plan mode deactivated, so disabling restores exactly those and does
 	// not re-activate a tool another extension intentionally hid.
 	let removedForPlan: string[] = [];
@@ -177,11 +215,12 @@ 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.
+			const branch = readBranchState(ctx);
+			// The baseline belongs to the branch that was reviewed: a plan this branch
+			// never showed has no digest here, so nothing looks changed until it does.
 			reviewedPlans.clear();
-			const persisted = readPersistedState(ctx);
+			for (const [path, sections] of branch.baselines) reviewedPlans.set(path, sections);
+			const persisted = branch.mode;
 			// `--plan` starts a fresh session in plan mode; an explicit persisted
 			// choice (including a later disable) wins over the launch flag.
 			const fromFlag = persisted === undefined && pi.getFlag("plan") === true;
@@ -206,7 +245,13 @@ export function createPlanRuntime(
 		},
 		reviewed: (path) => reviewedPlans.get(resolve(path)),
 		markReviewed: (path, content) => {
-			reviewedPlans.set(resolve(path), content);
+			const key = resolve(path);
+			const sections = sectionDigests(content);
+			const previous = reviewedPlans.get(key);
+			// A screen shown again over the same content must not grow the branch.
+			if (previous && sameSections(previous, sections)) return;
+			reviewedPlans.set(key, sections);
+			pi.appendEntry(BASELINE_TYPE, { path: key, sections } satisfies ReviewBaselineEntry);
 		},
 	};
 }

package/extensions/plan/steps.ts

@@ -5,7 +5,9 @@
  * guided to write, the top-level steps that seed `todo` and drive the review
  * gauge, the heading sections the review screen navigates, and the in-place
  * checkbox edit that keeps the file current after approval. All of it is pure so
- * the tools, the store, and the renderer agree on one parser.
+ * the tools, the store, and the renderer agree on one parser. The review's
+ * section comparison lives in `plan-text.ts`, which owns the text normalization
+ * the digest is computed over.
  *
  * Only top-level list items become steps: nested sub-bullets are notes, and the
  * shallowest list level is treated as the plan. When the plan has a `Steps`
@@ -224,6 +226,38 @@ function elide(content: string): string {
 	return content.length > MAX_STEP_LENGTH ? `${content.slice(0, MAX_STEP_LENGTH - 1).trimEnd()}…` : content;
 }
 
+/** A list marker with an optional checkbox, at any indent. */
+const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
+
+/**
+ * The plan's `Verification` section as one trailing checklist item, or
+ * `undefined` when the plan has none.
+ *
+ * The section is prose ("commands and checks"), and a todo item is one line, so
+ * the lines are stripped of list markers and inline emphasis and joined with
+ * `; `, prefixed with `Verify:` and elided like a long step. The item is
+ * deliberately *not* a plan step: it is not in the `Steps` section, so it must
+ * not count against the step cap or appear in `set_plan_steps` numbering.
+ *
+ * A plan with no `Steps` heading feeds its shallowest list as steps (the older
+ * rule), so that list already covers the verification bullets; appending a
+ * summary of them would duplicate them, and there is nothing to carry.
+ */
+export function verificationItem(plan: string): PlanStep | undefined {
+	if (stepsSection(plan) === undefined) return undefined;
+	const section = extractPlanSections(plan).find(
+		(candidate) => candidate.level > 0 && candidate.title.toLowerCase() === "verification",
+	);
+	if (!section) return undefined;
+	const items = section.text
+		.split("\n")
+		.slice(1)
+		.map((line) => plainText(line.replace(LIST_PREFIX, "")))
+		.filter(Boolean);
+	if (items.length === 0) return undefined;
+	return { content: elide(`Verify: ${items.join("; ")}`), status: "pending" };
+}
+
 /** Top-level steps from a plan, in order. */
 export function extractPlanSteps(plan: string): PlanStep[] {
 	return topLevelItems(plan).map((item) => ({ content: elide(item.step.content), status: item.step.status }));
@@ -294,30 +328,6 @@ export function setStepStatuses(plan: string, updates: StepUpdate[]): string | u
 	return lines.join("\n");
 }
 
-/**
- * Per-section change flags for a second review: `boolean[]` aligned with
- * `extractPlanSections(current)`, so duplicate headings are flagged by
- * occurrence rather than by title. Revision snapshots are the caller's to
- * provide; strip stored feedback first so a review comment does not look like
- * an edit.
- */
-export function changedSections(previous: string, current: string): boolean[] {
-	const before = new Map<string, string[]>();
-	for (const section of extractPlanSections(previous)) {
-		const texts = before.get(section.title);
-		if (texts) texts.push(section.text.trim());
-		else before.set(section.title, [section.text.trim()]);
-	}
-
-	const seen = new Map<string, number>();
-	return extractPlanSections(current).map((section) => {
-		const index = seen.get(section.title) ?? 0;
-		seen.set(section.title, index + 1);
-		const prior = before.get(section.title)?.[index];
-		return prior === undefined || prior !== section.text.trim();
-	});
-}
-
 /**
  * Sections of a plan, split at heading lines outside code fences. The content
  * before the first heading is a section titled `""`. Pi's `Markdown` renderer

package/extensions/plan/todos.ts

@@ -23,6 +23,11 @@ export interface TodoMerge {
 	kept: number;
 	/** Plan steps left out because the list reached its cap. */
 	deferred: number;
+	/**
+	 * What happened to the trailing checklist item (the plan's verification
+	 * summary): appended after the steps, already present, or left out by the cap.
+	 */
+	trailing?: "added" | "skipped" | "deferred";
 }
 
 /** Fallback list cap when the registered todo tool does not advertise one. */
@@ -38,8 +43,12 @@ function contentKey(content: string): string {
  * keep their status, a legacy in-progress item without an `activeForm` gets its
  * content as one so the todo tool accepts it, and the appended steps stop at
  * `max` items — the rest are counted as deferred, never dropped.
+ *
+ * `trailing` is the plan's verification summary: it is appended after every step
+ * (still subject to the same duplicate and cap rules) but is not counted as a
+ * step, because it is not one.
  */
-export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: number): TodoMerge {
+export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: number, trailing?: PlanStep): TodoMerge {
 	const limit = Number.isInteger(max) && max > 0 ? max : DEFAULT_TODO_MAX;
 	const todos: ExistingTodo[] = existing.map((todo) =>
 		todo.status === "in_progress" && !todo.activeForm ? { ...todo, activeForm: todo.content } : todo,
@@ -63,5 +72,18 @@ export function mergeTodos(existing: ExistingTodo[], steps: PlanStep[], max: num
 		todos.push({ content: step.content, status: step.status });
 		added += 1;
 	}
-	return { todos, added, skipped, kept: existing.length, deferred };
+
+	let trailingOutcome: TodoMerge["trailing"];
+	if (trailing) {
+		const key = contentKey(trailing.content);
+		if (!key) trailingOutcome = undefined;
+		else if (seen.has(key)) trailingOutcome = "skipped";
+		else if (todos.length >= limit) trailingOutcome = "deferred";
+		else {
+			todos.push({ content: trailing.content, status: trailing.status });
+			trailingOutcome = "added";
+		}
+	}
+
+	return { todos, added, skipped, kept: existing.length, deferred, trailing: trailingOutcome };
 }

package/extensions/plan/tools.ts

@@ -19,7 +19,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
-import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { lastGoal } from "../../lib/goal-state.ts";
+import { GOAL_TOOL, TODO_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";
@@ -34,13 +35,15 @@ import {
 	PLAN_OUTLINE,
 	extractPlanSteps,
 	planStepSummary,
+	verificationItem,
 	type PlanStep,
-	type PlanStepSummary,
 	type StepUpdate,
 } from "./steps.ts";
+import { basename } from "node:path";
+import { planTitle, type StoredPlan } from "./plans.ts";
 import { DEFAULT_TODO_MAX, mergeTodos, type TodoMerge } from "./todos.ts";
 import { reviewPlan } from "./review.ts";
-import { sanitizePlanText } from "./tui.ts";
+import { sanitizePlanText } from "./plan-text.ts";
 import type { EnterPlanModeDetails, ExitPlanModeDetails, SetPlanStepsDetails, WritePlanDetails } from "./types.ts";
 import { createPlanWebReview, type PlanWebReview } from "./web.ts";
 
@@ -116,20 +119,21 @@ function preview(plan: string): { body: string; more: number } {
 }
 
 /**
- * One sentence for `write_plan` when the step list is larger than approval can
- * track, so the model can shorten it instead of discovering the cap later.
+ * One sentence when a step is longer than the display cap. The text stays in the
+ * plan file either way; only the todo list and the approval listing shorten it.
  */
-function stepCapNote({ total, elided }: PlanStepSummary): string {
-	const notes: string[] = [];
-	if (total > MAX_STEPS) {
-		notes.push(`the plan has ${total} steps and only the first ${MAX_STEPS} can be seeded or ticked`);
-	}
-	if (elided > 0) {
-		notes.push(
-			`${elided} step${elided === 1 ? " is" : "s are"} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list`,
-		);
-	}
-	return notes.length > 0 ? ` Note: ${notes.join("; ")}.` : "";
+function stepElisionNote(elided: number): string {
+	if (elided === 0) return "";
+	const plural = elided === 1 ? " is" : "s are";
+	return ` Note: ${elided} step${plural} longer than ${MAX_STEP_LENGTH} characters and will be shortened in the todo list.`;
+}
+
+/**
+ * The diagnosis both cap refusals share: a step list longer than approval can
+ * track. Each caller appends the fix that is available from where it stands.
+ */
+function overCap(total: number): string {
+	return `The plan has ${total} top-level steps but approval tracks at most ${MAX_STEPS}.`;
 }
 
 /** "Step 2" or "Steps 1, 2" for a set of step numbers. */
@@ -171,11 +175,12 @@ async function seedTodos(
 	plan: string,
 ): Promise<{ steps: PlanStep[]; merged?: TodoMerge; error?: string }> {
 	const steps = extractPlanSteps(plan);
-	if (steps.length === 0) return { steps };
-	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi));
-	// Nothing new to write: every step is already in the list (or the list is
-	// full), so a whole-list rewrite would only churn the todo widget.
-	if (merged.added === 0) return { steps, merged };
+	const verification = verificationItem(plan);
+	if (steps.length === 0 && !verification) return { steps };
+	const merged = mergeTodos(lastTodos(ctx.sessionManager.getBranch()), steps, todoMaxItems(pi), verification);
+	// Nothing new to write: every step (and the verification item) is already in
+	// the list, or the list is full, so a rewrite would only churn the widget.
+	if (merged.added === 0 && merged.trailing !== "added") return { steps, merged };
 	const outcome = await ctx.executeTool(TODO_TOOL, { todos: merged.todos });
 	if (!outcome.isError) return { steps, merged };
 	// The nested call fails both when the tool is unavailable and when it rejects
@@ -185,6 +190,56 @@ async function seedTodos(
 	return { steps, merged, error: firstLine ? sanitizeLine(firstLine) : undefined };
 }
 
+/** What the goal offer did: `recorded` undefined when there was nothing to offer. */
+interface GoalOffer {
+	objective: string;
+	recorded?: boolean;
+	error?: string;
+}
+
+/**
+ * Offer to record the approved plan as the session goal — only when the session
+ * has no goal at all (an active or achieved one is the user's, never replaced) and
+ * the session can ask. The objective is the plan's own `# title`, or the file-name
+ * slug; recording runs through the goal tool, so validation and the widget stay
+ * goal's, and no model turn is spent.
+ */
+async function offerSessionGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOffer> {
+	const objective = planObjective(plan);
+	if (!ctx.hasUI) return { objective };
+	// The branch already carries a goal: leave it alone, and say nothing.
+	if (lastGoal(ctx.sessionManager.getBranch()) !== null) return { objective };
+	const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
+	if (!approved) return { objective };
+	const outcome = await ctx.executeTool(GOAL_TOOL, { objective });
+	if (!outcome.isError) return { objective, recorded: true };
+	const part = outcome.result?.content?.find((entry) => entry.type === "text");
+	const firstLine = part?.type === "text" ? part.text.split("\n", 1)[0] : undefined;
+	return { objective, recorded: false, error: firstLine ? sanitizeLine(firstLine) : undefined };
+}
+
+/** The plan's own title: its first `# heading`, else the file-name slug. */
+function planObjective(plan: StoredPlan): string {
+	const heading = /^ {0,3}#\s+(.+)$/m.exec(plan.content)?.[1];
+	const title = heading === undefined ? "" : sanitizeLine(heading).trim();
+	return title || planTitle(basename(plan.path));
+}
+
+/**
+ * One sentence about the plan's verification item, or "" when the plan has none
+ * (or it was already in the list). The item is a todo, not a plan step, so it is
+ * ticked in the list rather than in the file.
+ */
+function verificationNote(merged: TodoMerge | undefined): string {
+	if (merged?.trailing === "added") {
+		return "\nThe plan's verification section is the last todo item; tick it in the todo list, not in the file.";
+	}
+	if (merged?.trailing === "deferred") {
+		return "\nThe plan's verification section did not fit in the full todo list; keep it in mind.";
+	}
+	return "";
+}
+
 /** What the merge did, for the approval message; `steps` is the plan's step count. */
 function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 	const total = steps.length;
@@ -287,7 +342,8 @@ export function registerTools(
 			"Save the plan you designed as a markdown file under .pi/plans (project root, or the agent directory outside a " +
 			"repository). Write the complete plan, not a summary, in this outline so it is consistent and scannable:\n\n" +
 			`${PLAN_OUTLINE}\n\n` +
-			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining.",
+			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining. " +
+			`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it cannot track.`,
 		promptSnippet: "Save the designed plan as a markdown file under .pi/plans.",
 		promptGuidelines: [
 			"While plan mode is active, write the full plan with write_plan, then call exit_plan_mode with the returned path.",
@@ -308,6 +364,21 @@ export function registerTools(
 				};
 			}
 			const args = params as WritePlanArgs;
+			const summary = planStepSummary(args.content);
+			if (summary.total > MAX_STEPS) {
+				// Refuse before writing: a note after the fact arrives once the file exists and
+				// the review has listed every step, so the overflow is already lost.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(summary.total)} Nothing was written; group the steps (one outcome each, sub-bullets for detail) and call write_plan again.`,
+						},
+					],
+					details: undefined,
+					isError: true,
+				};
+			}
 			try {
 				const file = await runtime.plans.write(ctx.cwd, {
 					title: args.title,
@@ -319,7 +390,7 @@ export function registerTools(
 					content: [
 						{
 							type: "text",
-							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepCapNote(planStepSummary(args.content))}`,
+							text: `Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
 						},
 					],
 					details: { path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,
@@ -394,6 +465,27 @@ export function registerTools(
 				};
 			}
 
+			const total = planStepSummary(file.content).total;
+			if (total > MAX_STEPS) {
+				// A hand-edited or older plan file can still be over the cap; refuse it here
+				// too, so approval never seeds a list it cannot hold in full.
+				return {
+					content: [
+						{
+							type: "text",
+							text: `${overCap(total)} It was not presented for approval; call write_plan with plan_path to group the steps, then exit_plan_mode again.`,
+						},
+					],
+					details: {
+						approved: false,
+						plan: file.content,
+						planPath: file.path,
+						relativePath: file.relativePath,
+					} satisfies ExitPlanModeDetails,
+					isError: true,
+				};
+			}
+
 			if (!ctx.hasUI) {
 				return {
 					content: [
@@ -464,6 +556,7 @@ export function registerTools(
 
 			runtime.disable(ctx);
 			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
+			const goal = await offerSessionGoal(ctx, decision.plan);
 			const listing =
 				steps.length > 0
 					? `\n\n${steps
@@ -478,6 +571,13 @@ export function registerTools(
 						: merged
 							? mergeSummary(merged, steps)
 							: ` Could not read the todo list. Record these steps with the todo tool before you start, and tick them off with ${SET_PLAN_STEPS_TOOL}.`;
+			const verification = verificationNote(merged);
+			const goalNote =
+				goal.recorded === undefined
+					? ""
+					: goal.recorded
+						? ` Recorded the session goal: ${goal.objective}.`
+						: ` Could not record the session goal: ${goal.error ?? "unknown error"}. Use the goal tool to set it.`;
 			const browserNote = decision.comments.length
 				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(decision.comments)}`
 				: "";
@@ -485,7 +585,7 @@ export function registerTools(
 				content: [
 					{
 						type: "text",
-						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${listing}`,
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${decision.plan.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${verification}${goalNote}${listing}`,
 					},
 				],
 				details: {

package/extensions/plan/tui.ts

@@ -1,10 +1,6 @@
 /**
  * Terminal rendering for the plan review screen.
  *
- * `sanitizePlanText` is exported so the transcript renderer (`tools.ts`) can
- * strip control characters from plan text with the same rules the review screen
- * uses.
- *
  * `PlanViewComponent` is the scrollable review screen `exit_plan_mode` opens
  * for approval. The plan body is rendered by Pi's own `Markdown` component with
  * the active Markdown theme, so headings, lists, code, links, and quotes match
@@ -30,7 +26,7 @@ import {
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
-import { sanitizeLine, stripControlChars } from "../../lib/format.ts";
+import { sanitizeLine } from "../../lib/format.ts";
 import {
 	editorTheme,
 	screenHint,
@@ -45,8 +41,8 @@ import { titleRule } from "../../lib/tui/rules.ts";
 import { emptyState, checkbox } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { planTitle, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSections } from "./steps.ts";
-import { stripFeedback } from "./feedback.ts";
+import { changedSections, sanitizePlanText, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSections } from "./steps.ts";
 
 /** What the user chose from the read/review screen. */
 export type PlanViewAction = "approve" | "refine" | "keep" | "browser";
@@ -71,10 +67,10 @@ interface BodyCache {
 export interface PlanViewOptions {
 	plan: StoredPlan;
 	/**
-	 * The content the previous review of this plan showed, when there was one.
-	 * Used only to mark the sections that changed since then.
+	 * The section digests the previous review of this plan showed, when there was
+	 * one. Used only to mark the sections that changed since then.
 	 */
-	previous?: string;
+	baseline?: SectionDigest[];
 	theme: Theme;
 	/**
 	 * Called once when the screen closes. `refinement` carries the typed text
@@ -110,17 +106,6 @@ const PRIMARY_HINTS: ScreenHint[] = [
 const SCROLL_HINTS: ScreenHint[] = ["↑/↓ or k/j scroll", "space/b page", "g/G ends"];
 /** Section-jump hint, shown when the plan has more than one heading section. */
 const SECTION_HINTS: ScreenHint[] = ["n/p section"];
-/** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
-const TAB_WIDTH = 4;
-
-/**
- * Replace control characters (including ESC and the C1 block) and expand tabs
- * so model-authored plan text cannot drive the terminal. Newlines are kept, so
- * callers can still render or split the text line by line.
- */
-export function sanitizePlanText(text: string): string {
-	return stripControlChars(text.replace(/\t/g, " ".repeat(TAB_WIDTH)));
-}
 
 /** A task checkbox in a list marker: `- [x] `, `1. [ ] `. */
 const TASK_MARKER = /^([-*+]|\d+[.)])(\s+)(\[([ xX])\])(\s*)$/;
@@ -210,13 +195,7 @@ export class PlanViewComponent implements Component {
 		const base = this.options.markdownTheme ?? getMarkdownTheme();
 		const theme = planMarkdownTheme(this.theme, base);
 		const current = sanitizePlanText(this.options.plan.content);
-		// Both sides of the diff get the same normalization: the baseline is stored
-		// raw, so sanitizing only `current` would report a tab as a change on every
-		// review.
-		const changed =
-			this.options.previous === undefined
-				? []
-				: changedSections(stripFeedback(sanitizePlanText(this.options.previous)), stripFeedback(current));
+		const changed = changedSections(this.options.baseline, current);
 		const chunks = extractPlanSections(current);
 		const lines: string[] = [];
 		const sections: SectionOffset[] = [];

package/extensions/plan/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { PlanAnnotation } from "./feedback.ts";
+import type { SectionDigest } from "./plan-text.ts";
 import type { StepUpdate } from "./steps.ts";
 
 /** Persisted (custom entry) plan-mode state. */
@@ -15,6 +16,14 @@ export interface PlanModeEntry {
 	removed?: string[];
 }
 
+/** Persisted (custom entry) review baseline for one plan. */
+export interface ReviewBaselineEntry {
+	/** Resolved path of the plan file the review showed. */
+	path: string;
+	/** One digest per heading section, in document order. */
+	sections: SectionDigest[];
+}
+
 /** Structured result carried in `enter_plan_mode`'s `details`. */
 export interface EnterPlanModeDetails {
 	/** Whether the user agreed to enter plan mode. */

package/extensions/plan/web-page.ts

@@ -16,6 +16,7 @@
 import {
 	brandLockup,
 	docHead,
+	SIDEBAR_COLLAPSE_MAX,
 	themeToggle,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
@@ -90,7 +91,6 @@ ${WEB_COMPONENTS_CSS}
 .review-progress__fill{display:block;height:100%;width:0;background:var(--accent);transition:width var(--motion-fast) linear}
 /* Review panel: the plan's review facts, the section outline, then the keys. */
 .bf-app__body--single{grid-template-columns:minmax(0,1fr)}
-.bf-app__sidebar .bf-panel{flex:1 1 auto;min-height:0;min-width:0}
 .review-panel{display:flex;flex-direction:column;gap:var(--space-3);padding:var(--space-4) var(--space-4) var(--space-2)}
 .review-facts{display:flex;flex-direction:column;gap:var(--space-2);padding-bottom:var(--space-3);border-bottom:1px solid var(--border)}
 .review-fact{display:flex;align-items:center;justify-content:space-between;gap:var(--space-3);font-size:var(--fs-sm);color:var(--muted)}
@@ -172,7 +172,7 @@ ${WEB_COMPONENTS_CSS}
 .review-nav .lvl-2 a,.review-nav .lvl-3 a,.review-nav .lvl-4 a,.review-nav .lvl-5 a,.review-nav .lvl-6 a{padding-left:8px}
 .review-hints{display:none}
 }
-@media (max-width:860px){
+@media (max-width:${SIDEBAR_COLLAPSE_MAX}px){
 .bf-review{padding:var(--space-4) 18px 80px}
 .review-nav__title{display:none}
 }