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

package/extensions/plan/plan-text.ts

@@ -0,0 +1,95 @@
+/**
+ * The plan text as a review shows and compares it (pure).
+ *
+ * Two needs pull in the same direction. A plan is model-authored text, so it is
+ * neutralized before it reaches a terminal or a page; and a review has to compare
+ * what it shows against what the previous review showed. Both start from the same
+ * normalization — control characters stripped, tabs expanded, stored feedback
+ * removed — so the digest a review writes and the digest a later review compares
+ * cannot disagree about a plan that did not change.
+ *
+ * The baseline is one digest per heading section rather than the previous plan
+ * text, so it can live in a session entry without copying the plan file into the
+ * branch on every review.
+ */
+
+import { createHash } from "node:crypto";
+import { stripControlChars } from "../../lib/format.ts";
+import { stripFeedback } from "./feedback.ts";
+import { extractPlanSections } from "./steps.ts";
+
+/** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
+const TAB_WIDTH = 4;
+
+/** One heading section's identity and content digest. */
+export interface SectionDigest {
+	/** Plain heading text, or `""` for the content before the first heading. */
+	title: string;
+	/** SHA-256 of the section's normalized text, heading included. */
+	digest: string;
+}
+
+/**
+ * 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)));
+}
+
+/**
+ * The text a review compares: terminal-safe, with tabs expanded and stored
+ * feedback removed. A review comment a browser wrote into the file is a note to
+ * the model, not an edit, so it never reads as a changed section.
+ */
+export function reviewText(content: string): string {
+	return stripFeedback(sanitizePlanText(content));
+}
+
+/** Digest one section's text; the heading line is part of it. */
+function digestOf(text: string): string {
+	return createHash("sha256").update(text.trim()).digest("hex");
+}
+
+/** One digest per heading section, in document order, for a persisted baseline. */
+export function sectionDigests(content: string): SectionDigest[] {
+	return extractPlanSections(reviewText(content)).map((section) => ({
+		title: section.title,
+		digest: digestOf(section.text),
+	}));
+}
+
+/** Whether two baselines describe the same content, section for section. */
+export function sameSections(a: readonly SectionDigest[], b: readonly SectionDigest[]): boolean {
+	if (a.length !== b.length) return false;
+	return a.every((section, index) => section.title === b[index].title && section.digest === b[index].digest);
+}
+
+/**
+ * Per-section change flags for a second review: `boolean[]` aligned with
+ * `extractPlanSections(reviewText(current))`, so duplicate headings are flagged
+ * by occurrence rather than by title. An absent baseline flags nothing, which is
+ * what a first review of a plan looks like; `stripFeedback` only ever drops
+ * quote-marker lines, so the flags stay aligned with the sections a screen
+ * renders from the same content.
+ */
+export function changedSections(baseline: readonly SectionDigest[] | undefined, current: string): boolean[] {
+	const sections = extractPlanSections(reviewText(current));
+	if (baseline === undefined) return sections.map(() => false);
+
+	const before = new Map<string, string[]>();
+	for (const section of baseline) {
+		const digests = before.get(section.title);
+		if (digests) digests.push(section.digest);
+		else before.set(section.title, [section.digest]);
+	}
+
+	const seen = new Map<string, number>();
+	return sections.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 !== digestOf(section.text);
+	});
+}

package/extensions/plan/plans.ts

@@ -23,12 +23,14 @@ import {
 	readFileSync,
 	readdirSync,
 	renameSync,
+	statSync,
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { repoRootFor } from "../../lib/git/index.ts";
+import { sanitizeLine } from "../../lib/format.ts";
 import { isInside, isInsideReal } from "../../lib/path.ts";
 import { formatFeedback, type PlanAnnotation } from "./feedback.ts";
 import { extractPlanSteps, matchesStepText, setStepStatuses, type StepUpdate } from "./steps.ts";
@@ -53,6 +55,23 @@ export interface WrittenPlan extends StoredPlan {
 	title: string;
 }
 
+/** One row of the plan index: enough to choose a plan without opening it. */
+export interface PlanSummary {
+	/** Absolute path. */
+	path: string;
+	/** Path relative to the working directory, when it is inside it. */
+	relativePath: string;
+	/** The plan's `# title`, or a title derived from the file name. */
+	title: string;
+	/** File modification time, ms since the epoch. */
+	modified: number;
+	bytes: number;
+	/** Steps done and total, or undefined for a file the store would not have written. */
+	steps?: { done: number; total: number };
+	/** True when the file is over {@link MAX_PLAN_BYTES} and was listed without a read. */
+	oversize?: boolean;
+}
+
 export interface WritePlanInput {
 	/** Short title; drives the file-name slug. */
 	title: string;
@@ -70,6 +89,11 @@ export interface PlanStore {
 	read(cwd: string, planPath: string): Promise<StoredPlan | undefined>;
 	/** The newest plan file in the plans directory, or undefined when there is none. */
 	latest(cwd: string): Promise<StoredPlan | undefined>;
+	/**
+	 * Every plan in the directory, newest first. The directory is the index, so
+	 * this is one `readdir`, one `stat` per file, and one bounded read per plan.
+	 */
+	index(cwd: string): Promise<PlanSummary[]>;
 	/** Set the given top-level steps' checkboxes in an existing plan. Throws when the file or any step is invalid. */
 	setSteps(cwd: string, planPath: string, updates: StepUpdate[]): Promise<StoredPlan>;
 	/** Replace the plan's stored browser feedback. Throws when the file is missing or outside the plans directory. */
@@ -342,5 +366,70 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		return newest ? read(cwd, newest.path) : undefined;
 	};
 
-	return { dirFor, write, read, latest, setSteps, saveFeedback };
+	/**
+	 * Every plan in the directory, newest first: the directory is the index.
+	 *
+	 * One `readdir`, one `lstat`/`stat` per entry, and one `readFileSync` per plan
+	 * that fits {@link MAX_PLAN_BYTES}. A larger file is listed as `oversize`
+	 * without being read — the store would never have written it, and pulling it
+	 * into memory to print one row is not worth the risk. A symlinked entry, a
+	 * dotfile, or a file that vanishes mid-walk is simply not a plan.
+	 */
+	const index = async (cwd: string): Promise<PlanSummary[]> => {
+		const dir = await dirFor(cwd);
+		let names: string[];
+		try {
+			names = readdirSync(dir);
+		} catch {
+			return [];
+		}
+
+		const summaries: PlanSummary[] = [];
+		for (const name of names) {
+			const path = join(dir, name);
+			if (!isPlanFileName(path)) continue;
+			let info: ReturnType<typeof statSync>;
+			try {
+				// lstat, not stat: a symlink is never a plan.
+				info = lstatSync(path);
+			} catch {
+				continue;
+			}
+			if (!info.isFile()) continue;
+			if (!isContainedPlan(dir, path)) continue;
+
+			const summary: PlanSummary = {
+				path,
+				relativePath: relativeTo(cwd, path),
+				title: planTitle(name),
+				modified: info.mtimeMs,
+				bytes: info.size,
+			};
+			if (info.size > MAX_PLAN_BYTES) {
+				summaries.push({ ...summary, oversize: true });
+				continue;
+			}
+			try {
+				const content = readFileSync(path, "utf-8");
+				const heading = /^ {0,3}#\s+(.+)$/m.exec(content)?.[1];
+				const title = heading === undefined ? "" : sanitizeLine(heading).trim();
+				const steps = extractPlanSteps(content);
+				summaries.push({
+					...summary,
+					...(title ? { title } : {}),
+					steps: { done: steps.filter((step) => step.status === "completed").length, total: steps.length },
+				});
+			} catch {
+				// An unreadable plan is still a file the user may want to see; list the
+				// row from its name and leave the content-derived fields out.
+				summaries.push(summary);
+			}
+		}
+		// Newest first, with the name (which carries the stamp) as the tie break —
+		// the same order `latest` picks from.
+		summaries.sort((a, b) => b.modified - a.modified || (a.path < b.path ? 1 : a.path > b.path ? -1 : 0));
+		return summaries;
+	};
+
+	return { dirFor, write, read, latest, index, setSteps, saveFeedback };
 }

package/extensions/plan/review.ts

@@ -18,6 +18,7 @@ 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 type { SectionDigest } from "./plan-text.ts";
 import { extractPlanSteps } from "./steps.ts";
 import { PlanViewComponent, type PlanViewAction } from "./tui.ts";
 import type { PlanReviewResult, PlanReviewSession, PlanWebReview } from "./web.ts";
@@ -47,7 +48,9 @@ export type ReviewDecision =
 
 /** What the previous review showed, so this one can mark what changed. */
 export interface ReviewBaselines {
-	reviewed(path: string): string | undefined;
+	/** The sections the last review of `path` showed, when this branch has one. */
+	reviewed(path: string): SectionDigest[] | undefined;
+	/** Remember what a review just showed, as a session entry on this branch. */
 	markReviewed(path: string, content: string): void;
 }
 
@@ -106,7 +109,7 @@ function planReviewDigest(content: string): string {
 async function askPlanReview(
 	ctx: ExtensionToolContext,
 	plan: StoredPlan,
-	previous: string | undefined,
+	baseline: SectionDigest[] | undefined,
 ): Promise<PlanReviewChoice> {
 	let sentFullText = false;
 	for (;;) {
@@ -116,7 +119,7 @@ async function askPlanReview(
 					(tui, theme, _keybindings, done) =>
 						new PlanViewComponent({
 							plan,
-							previous,
+							baseline,
 							theme,
 							onClose: (action, refinement) => done({ action, refinement }),
 							requestRender: () => tui.requestRender(),
@@ -156,8 +159,8 @@ async function askPlanReview(
 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;
+	/** The section digests the previous review showed, for the changed markers. */
+	baseline?: SectionDigest[];
 	/** Aborting the turn closes the session as cancelled. */
 	signal?: AbortSignal;
 	/** Called once the server is listening and the browser was opened. */
@@ -176,7 +179,7 @@ export async function runBrowserReview(
 ): 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 })
+		.start(cwd, plan, { canApprove: options.canApprove, baseline: options.baseline, signal: options.signal })
 		.catch(() => undefined);
 	if (!session) return undefined;
 	options.onOpened?.(session);
@@ -200,8 +203,8 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 		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);
+		const baseline = baselines.reviewed(plan.path);
+		const choice = await askPlanReview(ctx, plan, baseline);
 		baselines.markReviewed(plan.path, plan.content);
 
 		if (choice.action === "approve") return { action: "approve", plan, comments: [] };
@@ -218,7 +221,7 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 
 		const result = await runBrowserReview(web, ctx.cwd, plan, {
 			canApprove: true,
-			previous,
+			baseline,
 			signal,
 			onOpened: (session) => ctx.ui.notify(`Plan review: opened ${session.url}`, "info"),
 		});

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 };
 }