@gavin-hu/my-pi-agent 0.20.0 → 0.21.0

package/extensions/goal/tui.ts

@@ -10,6 +10,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { RenderCache } from "../../lib/tui/render-cache.ts";
 import { goalHeader, goalLine } from "./format.ts";
 import type { AchievedStyle, Goal } from "./types.ts";
 
@@ -47,6 +48,7 @@ export class GoalWidget implements Component {
 export class GoalHeader implements Component {
 	private goal: Goal;
 	private theme: Theme;
+	private readonly cache = new RenderCache();
 
 	constructor(goal: Goal, theme: Theme) {
 		this.goal = goal;
@@ -57,13 +59,21 @@ export class GoalHeader implements Component {
 	update(goal: Goal, theme: Theme): void {
 		this.goal = goal;
 		this.theme = theme;
+		this.cache.invalidate();
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		this.cache.invalidate();
+	}
 
 	render(width: number): string[] {
+		const w = Math.max(1, width);
+		return this.cache.lines(w, undefined, () => this.build(w));
+	}
+
+	private build(w: number): string[] {
 		// The leading blank line separates the header from the call line, matching
 		// the built-ins' header/output gap.
-		return ["", truncateToWidth(goalHeader(this.goal, this.theme), Math.max(1, width), "…")];
+		return ["", truncateToWidth(goalHeader(this.goal, this.theme), w, "…")];
 	}
 }

package/extensions/job/tools.ts

@@ -11,7 +11,15 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { errorResult, textResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { callLine, detailsOrLine, elapsedSuffix, rejectionLine, syncElapsedTimer } from "../../lib/tui/tool.ts";
+import {
+	callLine,
+	detailsOrLine,
+	elapsedSuffix,
+	isTailResult,
+	rejectionLine,
+	syncElapsedTimer,
+	TailResult,
+} from "../../lib/tui/tool.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
@@ -26,8 +34,8 @@ import {
 import type { JobsRuntime } from "./runtime.ts";
 import { JobParams, normalizeCall, type JobArgs, type JobCall } from "./schema.ts";
 import { toRecord } from "./store.ts";
-import { JobResult, type JobResultInput } from "./tui.ts";
-import type { JobDetails } from "./types.ts";
+import { jobTail, type JobResultInput } from "./tui.ts";
+import type { JobDetails, JobRecord } from "./types.ts";
 
 export const TOOL_NAME = "job";
 
@@ -224,8 +232,10 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 				}
 				const shown = options.expanded ? all : all.slice(Math.max(0, all.length - RESULT_ROWS));
 				const input: JobResultInput = { kind: "logs", lines: shown, earlier: all.length - shown.length };
-				const view = context.lastComponent instanceof JobResult ? context.lastComponent : new JobResult(input, theme);
-				view.setInput(input, theme);
+				const previous = context.lastComponent;
+				const tail = jobTail(input);
+				const view = isTailResult<JobRecord>(previous) ? previous : new TailResult<JobRecord>(tail, theme);
+				view.setInput(tail, theme);
 				return view;
 			}
 
@@ -242,8 +252,10 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 					more: ordered.length - shown.length,
 					sessionId: details.sessionId,
 				};
-				const view = context.lastComponent instanceof JobResult ? context.lastComponent : new JobResult(input, theme);
-				view.setInput(input, theme);
+				const previous = context.lastComponent;
+				const tail = jobTail(input);
+				const view = isTailResult<JobRecord>(previous) ? previous : new TailResult<JobRecord>(tail, theme);
+				view.setInput(tail, theme);
 				return view;
 			}
 

package/extensions/job/tui.ts

@@ -15,13 +15,12 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { Component } from "@earendil-works/pi-tui";
 import { formatDuration, sanitizeUntrustedLine } from "../../lib/format.ts";
 import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
 import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { statusRow, type StatusRow } from "../../lib/tui/rows.ts";
-import { TailResult, type TailResultInput } from "../../lib/tui/tool.ts";
+import type { TailResultInput } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
 	compareJobs,
@@ -62,7 +61,7 @@ export type JobResultInput =
 	| { kind: "logs"; lines: string[]; earlier: number };
 
 /** Map the job vocabulary onto the shared transcript tail block. */
-function jobTail(input: JobResultInput): TailResultInput<JobRecord> {
+export function jobTail(input: JobResultInput): TailResultInput<JobRecord> {
 	if (input.kind === "logs") {
 		return { kind: "lines", lines: input.lines, earlier: input.earlier, earlierLabel: "lines" };
 	}
@@ -77,31 +76,6 @@ function jobTail(input: JobResultInput): TailResultInput<JobRecord> {
 	};
 }
 
-/**
- * Transcript result block for the `job` tool: the shared tail block over the
- * `/jobs`-style row rail or the themed log tail. Reused across renders.
- */
-export class JobResult implements Component {
-	private readonly view: TailResult<JobRecord>;
-
-	constructor(input: JobResultInput, theme: Theme) {
-		this.view = new TailResult(jobTail(input), theme);
-	}
-
-	/** Update in place so the transcript can reuse this component across renders. */
-	setInput(input: JobResultInput, theme: Theme): void {
-		this.view.setInput(jobTail(input), theme);
-	}
-
-	invalidate(): void {
-		this.view.invalidate();
-	}
-
-	render(width: number): string[] {
-		return this.view.render(width);
-	}
-}
-
 export interface JobListCallbacks {
 	/** This session's id: a record with another id belongs to a peer session. */
 	sessionId(): string;

package/extensions/plan/commands.ts

@@ -19,7 +19,7 @@ import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
 import { runBrowserReview } from "./review.ts";
 import type { PlanRuntime } from "./runtime.ts";
 import type { PlanSummary } from "./plans.ts";
-import { createPlanWebReview, type PlanWebReview } from "./web.ts";
+import { createPlanWebReview, NO_SERVER_DEPS, type PlanWebReview } from "./web.ts";
 
 const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
@@ -219,7 +219,7 @@ async function openPlanIndex(
 export function registerCommands(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
-	web: PlanWebReview = createPlanWebReview(runtime.plans),
+	web: PlanWebReview = createPlanWebReview(runtime.plans, NO_SERVER_DEPS),
 ): void {
 	pi.registerCommand("plan", {
 		description:

package/extensions/plan/feedback.ts

@@ -43,6 +43,13 @@ export interface PlanAnnotation {
 	 * guess, and the page says so instead of presenting a guess as her own anchor.
 	 */
 	moved?: true;
+	/**
+	 * Set when the note is settled: its writer, or the owner, decided it needs no action, or
+	 * the revision answered it. The comment stays in the file — it is the record of the
+	 * question — and a review sends it flagged, so the model reads what is closed without
+	 * treating it as new.
+	 */
+	resolved?: true;
 }
 
 /** Most annotations one save may carry. */
@@ -59,10 +66,10 @@ export type AuthorClaim = { name: string } | { status: number; message: string }
 
 /**
  * A stored feedback line, capturing whether a refinement moved it, its author, and its
- * comment. The flag is inside the marker tag rather than the comment, so the text a
+ * comment. The flags are inside the marker tag rather than the comment, so the text a
  * reviewer wrote stays exactly what she typed.
  */
-const MARKER_LINE = /^\s*>\s*\[!REVIEW(\s+moved)?\]\s?(.*)$/;
+const MARKER_LINE = /^\s*>\s*\[!REVIEW((?:\s+(?:moved|resolved))*)\]\s?(.*)$/;
 /** The author prefix inside a marker body (`@alice: note`). */
 const AUTHOR_PREFIX = /^@([^:]{1,40}):\s?(.*)$/;
 
@@ -133,6 +140,8 @@ interface StoredMarker {
 	author: string;
 	/** Whether a refinement carried this comment off the text it was written on. */
 	moved: boolean;
+	/** Whether the note is settled: it stays in the file, and is no longer an open question. */
+	resolved: boolean;
 }
 
 /** The plan body without markers, plus the markers that were removed from it. */
@@ -151,17 +160,28 @@ function scanMarkers(plan: string): { clean: string; markers: StoredMarker[] } {
 		const authored = AUTHOR_PREFIX.exec(body);
 		const author = authored ? normalizeAuthor(authored[1]) : "";
 		const comment = (authored ? authored[2] : body).trim();
-		if (comment) markers.push({ at: clean.length - 1, comment, author, moved: match[1] !== undefined });
+		// The tag carries a set of flags, not one keyword: a note can be carried off its text
+		// and settled in the same write, and an older build reading it still finds the comment.
+		const flags = new Set((match[1] ?? "").trim().split(/\s+/).filter(Boolean));
+		if (comment) {
+			markers.push({
+				at: clean.length - 1,
+				comment,
+				author,
+				moved: flags.has("moved"),
+				resolved: flags.has("resolved"),
+			});
+		}
 	});
 	return { clean: clean.join("\n"), markers };
 }
 
 /** One marker line in its stored form. */
-function markerLine(author: string, comment: string, moved = false): string {
+function markerLine(author: string, comment: string, moved = false, resolved = false): string {
 	const body = sanitizeLine(comment);
-	// The flag rides inside the tag, where it cannot be confused with the comment: after
-	// the closing bracket, a comment that begins "moved …" would read as the flag.
-	const tag = moved ? "[!REVIEW moved]" : REVIEW_MARKER;
+	// The flags ride inside the tag, in a fixed order, where they cannot be confused with the
+	// comment: after the closing bracket, a comment that begins "moved …" would read as one.
+	const tag = moved || resolved ? `[!REVIEW${moved ? " moved" : ""}${resolved ? " resolved" : ""}]` : REVIEW_MARKER;
 	return author ? `> ${tag} @${author}: ${body}` : `> ${tag} ${body}`;
 }
 
@@ -236,6 +256,7 @@ export function readFeedback(plan: string): FeedbackRead {
 		};
 		if (marker.author) annotation.author = marker.author;
 		if (marker.moved) annotation.moved = true;
+		if (marker.resolved) annotation.resolved = true;
 		return annotation;
 	});
 	return { body: clean, blocks, annotations };
@@ -249,15 +270,21 @@ export function parseFeedback(plan: string): PlanAnnotation[] {
 /** Sanitized, non-empty comments with the anchor they land on. */
 function storableComments(
 	annotations: readonly PlanAnnotation[],
-): Array<{ anchor: number; comment: string; moved: boolean }> {
-	const items: Array<{ anchor: number; comment: string; moved: boolean }> = [];
+): Array<{ anchor: number; comment: string; moved: boolean; resolved: boolean }> {
+	const items: Array<{ anchor: number; comment: string; moved: boolean; resolved: boolean }> = [];
 	for (const annotation of annotations) {
 		const comment = sanitizeLine(annotation.comment);
 		if (comment.length === 0 || comment.length > MAX_COMMENT_LENGTH) continue;
 		// Editing a moved note's text does not put it back on its old block, so the fact
 		// that a refinement placed it where it sits survives the save: the page posts back
-		// the annotation it was handed, flag included, and this keeps it.
-		items.push({ anchor: annotation.anchor, comment, moved: annotation.moved === true });
+		// the annotation it was handed, flags included, and this keeps them. Settling is the
+		// writer's own decision of the same kind.
+		items.push({
+			anchor: annotation.anchor,
+			comment,
+			moved: annotation.moved === true,
+			resolved: annotation.resolved === true,
+		});
 	}
 	return items;
 }
@@ -272,13 +299,16 @@ export function formatFeedback(plan: string, annotations: PlanAnnotation[], opti
 	const { clean, markers } = scanMarkers(plan);
 	const kept = markers
 		.filter((marker) => marker.author !== author)
-		.map((marker) => ({ at: marker.at, line: markerLine(marker.author, marker.comment, marker.moved) }));
+		.map((marker) => ({
+			at: marker.at,
+			line: markerLine(marker.author, marker.comment, marker.moved, marker.resolved),
+		}));
 	const blocks = planBlocks(clean);
 	const added = storableComments(annotations).map((item) => ({
 		// A marker beside a block, never after a blank line: an anchor that names
 		// blank space is written where the page can read it back as a thread.
 		at: contentBlockAt(blocks, item.anchor)?.end ?? -1,
-		line: markerLine(author, item.comment, item.moved),
+		line: markerLine(author, item.comment, item.moved, item.resolved),
 	}));
 	return compose(clean, [...kept, ...added]);
 }
@@ -452,7 +482,9 @@ export function carryFeedback(previous: string, next: string): string {
 		// The flag means "this note is no longer on the text it was written about", so it
 		// is decided by the carry in hand: a block whose text survived proves the anchor,
 		// and anything after that is a guess the page has to admit to.
-		const keep = (moved: boolean): string => markerLine(marker.author, marker.comment, moved);
+		// Settling is the note's own history, not the carry's decision: a moved note that was
+		// resolved stays settled, and one whose text survived stays as it was.
+		const keep = (moved: boolean): string => markerLine(marker.author, marker.comment, moved, marker.resolved);
 		if (block === undefined) return { at: tail, line: keep(true) };
 		if (block.kind !== "blank") {
 			const match = queues.get(blockKey(block))?.shift();
@@ -503,13 +535,17 @@ export function feedbackSummary(annotations: PlanAnnotation[]): string {
 			// the plan owner chose, so it is normalized like every other author.
 			author: normalizeAuthor(annotation.author),
 			comment: sanitizeLine(annotation.comment),
+			resolved: annotation.resolved === true,
 		}))
 		.filter((item) => item.comment.length > 0);
 	return items
 		.map((item, index) => {
 			const who = item.author ? `@${item.author}: ` : "";
 			const where = item.quote ? `On "${item.quote}": ` : "";
-			return `${index + 1}. ${who}${where}${item.comment}`;
+			// A settled note is still sent — it is the record of the question — but saying so
+			// is what stops the model from answering it a second time.
+			const settled = item.resolved ? " (resolved)" : "";
+			return `${index + 1}. ${who}${where}${item.comment}${settled}`;
 		})
 		.join("\n");
 }
@@ -531,12 +567,22 @@ export function coerceAnnotations(value: unknown): PlanAnnotation[] | undefined
 		if (typeof record.comment !== "string") return undefined;
 		if (record.quote !== undefined && typeof record.quote !== "string") return undefined;
 		if (record.author !== undefined && typeof record.author !== "string") return undefined;
+		if (record.resolved !== undefined && typeof record.resolved !== "boolean") return undefined;
 		const comment = sanitizeLine(record.comment);
 		if (comment.length > MAX_COMMENT_LENGTH) return undefined;
 		if (comment.length === 0) continue;
 		const quote = typeof record.quote === "string" ? sanitizeLine(record.quote).slice(0, MAX_QUOTE_LENGTH) : undefined;
 		const author = normalizeAuthor(record.author);
-		annotations.push({ anchor, comment, ...(quote ? { quote } : {}), ...(author ? { author } : {}) });
+		// A note a refinement carried onto another block keeps saying so when the page posts
+		// it back, and a settled note keeps saying that too: only this body knows either.
+		annotations.push({
+			anchor,
+			comment,
+			...(quote ? { quote } : {}),
+			...(author ? { author } : {}),
+			...(record.moved === true ? { moved: true } : {}),
+			...(record.resolved === true ? { resolved: true } : {}),
+		});
 	}
 	return annotations;
 }

package/extensions/plan/index.ts

@@ -21,6 +21,7 @@ import { Key } from "@earendil-works/pi-tui";
 import { fileURLToPath } from "node:url";
 import { hasPathInput } from "./path-guard.ts";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { requestMount } from "../../lib/http/index.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { lastGoal, isPursuedGoal, type PublishedGoal } from "../../lib/goal-state.ts";
 import { READ_ONLY_SUMMARY, PLAN_ENTER_REQUEST, type PlanEnterRequest } from "../../lib/plan-entry.ts";
@@ -91,7 +92,12 @@ export default function planMode(pi: ExtensionAPI): void {
 	if (!isExtensionEnabled("plan")) return;
 	const policy = createPlanPolicy(pi);
 	const runtime = createPlanRuntime(pi, policy, { entryPath: extensionEntryPath() });
-	const web = createPlanWebReview(runtime.plans);
+	/** The session this review serves as; its prefix lands on that session's one server. */
+	let sessionId = "";
+	const web = createPlanWebReview(runtime.plans, {
+		mount: (spec) => requestMount(pi, spec),
+		session: () => sessionId,
+	});
 
 	registerTools(pi, runtime, web);
 	registerCommands(pi, runtime, web);

package/extensions/plan/plan-text.ts

@@ -17,6 +17,7 @@ import { createHash } from "node:crypto";
 import { stripControlChars } from "../../lib/format.ts";
 import { displayFeedback, stripFeedback } from "./feedback.ts";
 import { extractSections, sectionKeys, type PlanSection } from "./sections.ts";
+import { planBlocks } from "./blocks.ts";
 
 /** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
 const TAB_WIDTH = 4;
@@ -27,6 +28,14 @@ export interface SectionDigest {
 	title: string;
 	/** SHA-256 of the section's normalized text, heading included. */
 	digest: string;
+	/**
+	 * Short digests of this section's content blocks, in order.
+	 *
+	 * Absent in a baseline a build before block marks wrote, which is why every reader
+	 * treats it as optional: a section with no block digests marks nothing, and the page
+	 * says it cannot compare at that depth rather than reading as "nothing changed".
+	 */
+	blocks?: string[];
 }
 
 /**
@@ -60,6 +69,17 @@ function digestOf(text: string): string {
 	return createHash("sha256").update(text.trim()).digest("hex");
 }
 
+/**
+ * A short, stable digest of one block's lines.
+ *
+ * Short because it is persisted once per content block in a session entry: eight hex
+ * characters tell two blocks apart for the length of one review, which is all a change
+ * mark needs, and keep a long plan's baseline small enough to sit in the branch.
+ */
+export function blockDigest(lines: readonly string[]): string {
+	return digestOf(lines.join("\n")).slice(0, 8);
+}
+
 /**
  * A short, stable id for one plan text. The review page keys this tab's unsaved
  * draft on it, so a draft is restored for the plan it was written against and
@@ -74,9 +94,103 @@ export function sectionDigests(content: string): SectionDigest[] {
 	return extractSections(reviewText(content)).map((section) => ({
 		title: section.title,
 		digest: digestOf(section.text),
+		// Blank blocks are separators, not content: a plan that gained a blank line has not
+		// changed, and a digest per separator would say it had.
+		blocks: planBlocks(section.text)
+			.filter((block) => block.kind !== "blank")
+			.map((block) => blockDigest(block.lines)),
 	}));
 }
 
+/** Where the blocks changed, in the document the page is about to render. */
+export interface BlockChangeMarks {
+	/** Absolute 0-based start lines of the blocks that are new or edited. */
+	starts: number[];
+	/** Content blocks each section no longer holds, keyed by the section's heading line. */
+	removed: Record<number, number>;
+	/**
+	 * Whether the baseline carried block digests at all.
+	 *
+	 * False for a baseline a build before block marks wrote: section marks still mean
+	 * something, block marks cannot, and the page says which instead of drawing nothing.
+	 */
+	compared: boolean;
+}
+
+/**
+ * Where the blocks changed since the baseline, as the rendered document numbers them.
+ *
+ * The pages marks what it draws, so every line here is a line of `current`: a section's
+ * blocks are numbered from its own heading, which is why the section's line is added
+ * back. Sections are paired the way {@link changedSections} pairs them — by occurrence,
+ * so a second `## Notes` is never compared with the first — and a section the baseline
+ * never held is all new: every block in it marks, because adding or renaming a heading is
+ * a refinement rather than a reason to refuse the comparison. Only a baseline section
+ * written before block digests is beyond comparing at that depth, and it alone clears
+ * `compared`.
+ */
+export function blockChangeMarks(baseline: readonly SectionDigest[] | undefined, current: string): BlockChangeMarks {
+	const sections = extractSections(reviewText(current));
+	if (baseline === undefined) return { starts: [], removed: {}, compared: false };
+	const before = new Map<string, SectionDigest>();
+	sectionKeys(baseline).forEach((key, at) => {
+		const section = baseline[at];
+		if (section !== undefined) before.set(key, section);
+	});
+	const starts: number[] = [];
+	const removed: Record<number, number> = {};
+	let compared = true;
+	sectionKeys(sections).forEach((key, at) => {
+		const section = sections[at];
+		if (section === undefined) return;
+		const prior = before.get(key);
+		if (prior !== undefined && prior.blocks === undefined) {
+			compared = false;
+			return;
+		}
+		const mine = planBlocks(section.text).filter((block) => block.kind !== "blank");
+		// An unheld section pairs with no blocks, so every block in it is new.
+		const priorBlocks = new Set(prior?.blocks ?? []);
+		for (const block of mine) {
+			if (!priorBlocks.has(blockDigest(block.lines))) starts.push(section.line + block.start);
+		}
+		const shrunk = Math.max(0, (prior?.blocks?.length ?? 0) - mine.length);
+		if (shrunk > 0) removed[section.line] = shrunk;
+	});
+	return { starts, removed, compared };
+}
+
+/** What one section's blocks look like against the baseline's. */
+export interface BlockMarks {
+	/** Indexes, among the section's content blocks, of the blocks that are new or edited. */
+	changed: number[];
+	/** How many content blocks the section no longer holds: the part it shrank by. */
+	removed: number;
+}
+
+/**
+ * Mark the blocks a section gained or edited since the baseline.
+ *
+ * Membership rather than position: a block is changed when its digest is not among the
+ * baseline's, so an inserted step marks itself and leaves every block after it alone —
+ * the index-by-index pairing a diff would use would mark the whole rest of the section.
+ * A block that left cannot be drawn in place, so the section reports how much shorter it
+ * has become instead — the shrinkage, not the set difference, so an edited block reads
+ * as one change rather than as one removal beside one addition.
+ *
+ * An absent or blockless baseline marks nothing: a build before block marks wrote no
+ * block digests, and claiming every block changed would be a worse lie than saying the
+ * comparison cannot be made at that depth.
+ */
+export function changedBlocks(prior: readonly string[] | undefined, current: readonly string[]): BlockMarks {
+	if (prior === undefined) return { changed: [], removed: 0 };
+	const before = new Set(prior);
+	return {
+		changed: current.flatMap((digest, index) => (before.has(digest) ? [] : [index])),
+		removed: Math.max(0, prior.length - current.length),
+	};
+}
+
 /** 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;

package/extensions/plan/runtime.ts

@@ -100,9 +100,19 @@ 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;
+		const section = raw as { title?: unknown; digest?: unknown; blocks?: unknown } | null | undefined;
 		if (typeof section?.title !== "string" || typeof section.digest !== "string") return undefined;
-		sections.push({ title: section.title, digest: section.digest });
+		// Branch data is untrusted, so the block digests are kept only when they are a list
+		// of strings: a baseline written before block marks simply has none, and one that
+		// holds something else is read at section depth rather than repaired.
+		const blocks = Array.isArray(section.blocks)
+			? section.blocks.filter((entry): entry is string => typeof entry === "string")
+			: undefined;
+		sections.push(
+			blocks === undefined
+				? { title: section.title, digest: section.digest }
+				: { title: section.title, digest: section.digest, blocks },
+		);
 	}
 	return sections;
 }

package/extensions/plan/tools.ts

@@ -28,12 +28,12 @@ import { registerEnterTool } from "./tools/enter.ts";
 import { registerExitTool } from "./tools/exit.ts";
 import { registerSetPlanStepsTool } from "./tools/steps.ts";
 import { registerWriteTool } from "./tools/write.ts";
-import { createPlanWebReview, type PlanWebReview } from "./web.ts";
+import { createPlanWebReview, NO_SERVER_DEPS, type PlanWebReview } from "./web.ts";
 
 export function registerTools(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
-	web: PlanWebReview = createPlanWebReview(runtime.plans),
+	web: PlanWebReview = createPlanWebReview(runtime.plans, NO_SERVER_DEPS),
 ): void {
 	registerEnterTool(pi, runtime);
 	registerCancelTool(pi, runtime);

package/extensions/plan/web-blocks.ts

@@ -59,13 +59,20 @@ export function setActive(planEl: ClientNode | null, index: number): number | nu
  * The index one step from `activeIndex`, or `null` when there is nothing to walk.
  *
  * With nothing active yet, `j` starts at the top and `k` at the bottom, which is what a
- * reader pressing either key on a fresh page expects.
+ * reader pressing either key on a fresh page expects. A view can hide blocks, and a
+ * hidden block is not a place the reader can be sent: the step lands on the next block
+ * they can actually see, or nowhere when the filter left none.
  */
 export function moveActive(planEl: ClientNode | null, activeIndex: number, delta: number): number | null {
 	const blocks = blockElements(planEl);
 	if (blocks.length === 0) return null;
-	const next = activeIndex < 0 ? (delta < 0 ? blocks.length - 1 : 0) : activeIndex + delta;
-	return setActive(planEl, next);
+	const step = delta < 0 ? -1 : 1;
+	const first =
+		activeIndex < 0 ? (step < 0 ? blocks.length - 1 : 0) : Math.min(Math.max(activeIndex + step, 0), blocks.length - 1);
+	for (let index = first; index >= 0 && index < blocks.length; index += step) {
+		if (blocks[index]?.hidden !== true) return setActive(planEl, index);
+	}
+	return null;
 }
 
 /**
@@ -85,5 +92,69 @@ export function blockAtLine(
 	return wrap && block ? { wrap, block } : null;
 }
 
-/** The block rules as source, for the client bundle. */
-export const WEB_BLOCKS_JS = [blockElements, setActive, moveActive, blockAtLine].map(String).join("\n\n");
+/** What the reader asked the plan to show. */
+export type ReviewView = "all" | "changed" | "comments";
+
+/** How much of the plan a view kept, so the page can say what it is hiding. */
+export interface ViewCounts {
+	shown: number;
+	hidden: number;
+}
+
+/**
+ * Keep the blocks a view asks for, and hide the rest.
+ *
+ * A view is a filter over what is drawn, not a second document: `All` restores every
+ * block, so the reader is one click from the whole plan, and the page's status line says
+ * how many were hidden so a filtered document never reads as a short one. Headings stay
+ * in every view — a paragraph without its section is a sentence without a subject — and a
+ * view with nothing to show keeps the document whole rather than blanking it.
+ */
+/**
+ * Keep the blocks a view asks for, and hide the rest.
+ *
+ * A view is a filter over what is drawn, not a second document: `All` restores every
+ * block, so the reader is one click from the whole plan, and the page's status line says
+ * how many were hidden so a filtered document never reads as a short one. Headings stay
+ * in every view — a paragraph without its section is a sentence without a subject — and a
+ * view with nothing to show keeps the document whole rather than blanking it. A comment
+ * thread is hidden with the block it hangs under: a note with no text it refers to reads
+ * as a comment on whatever happens to be above it.
+ */
+export function applyView(planEl: ClientNode | null, view: ReviewView): ViewCounts {
+	if (!planEl) return { shown: 0, hidden: 0 };
+	const blocks = blockElements(planEl);
+	const keep = (block: ClientNode): boolean =>
+		view === "all" ||
+		block.getAttribute("data-kind") === "heading" ||
+		(view === "changed"
+			? block.getAttribute("data-changed") === "1"
+			: (block.className || "").split(" ").indexOf("bf-block--commented") >= 0);
+	// A filter that matches nothing but the headings is not a view of the plan: showing an
+	// empty page is worse than showing the whole document beside the count.
+	const matched = blocks.filter((block) => block.getAttribute("data-kind") !== "heading" && keep(block)).length;
+	const whole = view !== "all" && blocks.length > 0 && matched === 0;
+	const visible: Record<string, boolean> = {};
+	for (const block of blocks) {
+		block.hidden = !whole && !keep(block);
+		if (!block.hidden) visible[block.getAttribute("data-line") ?? ""] = true;
+	}
+	const threads = planEl.querySelectorAll(".bf-comments");
+	for (let i = 0; i < threads.length; i++) {
+		const thread = threads[i];
+		if (!thread) continue;
+		const line = thread.getAttribute("data-line");
+		if (line !== null) thread.hidden = visible[line] !== true;
+	}
+	const shown = whole ? blocks.length : blocks.filter(keep).length;
+	return { shown, hidden: blocks.length - shown };
+}
+
+/**
+ * The block rules as source, for the client bundle.
+ *
+ * `applyView` travels with them because the page's view control calls it on every render:
+ * a name the bundle does not carry is a `ReferenceError` at the first repaint, which
+ * aborts the boot before the composer and the progress bar are wired.
+ */
+export const WEB_BLOCKS_JS = [blockElements, setActive, moveActive, blockAtLine, applyView].map(String).join("\n\n");

package/extensions/plan/web-chrome.ts

@@ -76,6 +76,10 @@ export const WEB_CHROME_JS = String.raw`  function setStatus(text, kind) {
     if (saveButton) saveButton.disabled = true;
     if (postButton) postButton.disabled = true;
     if (cancelButton) cancelButton.disabled = true;
+    // The rail's comment controls go with them: a settled review takes no new comment, and
+    // the frame renderer is the one rule that decides that, so this asks for a repaint
+    // rather than removing the buttons itself.
+    renderAll();
   }
 
   // A conflict means the file moved under the page; only a reload can re-anchor.