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

package/extensions/memory/store.ts

@@ -74,17 +74,24 @@ export function readMemoryFile(path: string): string {
 	return readFileSync(path, "utf-8");
 }
 
-/** Coarse identity of a store file, for cheap change detection. */
+/**
+ * Identity of a store file, for cheap change detection.
+ *
+ * The stamp is nanoseconds, not milliseconds: an edit that keeps the file's size
+ * is otherwise invisible for a whole millisecond, which is long enough for an
+ * editor that writes in place. `size` stays a number so the doctor's byte counts
+ * read the same.
+ */
 export interface MemoryFileStamp {
-	mtimeMs: number;
+	mtimeNs: bigint;
 	size: number;
 }
 
 /** Freshness stamp for a store file; `undefined` when it is missing or unstattable. */
 export function memoryFileStamp(path: string): MemoryFileStamp | undefined {
 	try {
-		const info = statSync(path);
-		return { mtimeMs: info.mtimeMs, size: info.size };
+		const info = statSync(path, { bigint: true });
+		return { mtimeNs: info.mtimeNs, size: Number(info.size) };
 	} catch {
 		return undefined;
 	}
@@ -93,7 +100,7 @@ export function memoryFileStamp(path: string): MemoryFileStamp | undefined {
 /** Whether two stamps describe the same file state. */
 export function sameStamp(a: MemoryFileStamp | undefined, b: MemoryFileStamp | undefined): boolean {
 	if (a === undefined || b === undefined) return a === b;
-	return a.mtimeMs === b.mtimeMs && a.size === b.size;
+	return a.mtimeNs === b.mtimeNs && a.size === b.size;
 }
 
 /** Note text of every bullet line, sanitized to one terminal-safe line. */

package/extensions/plan/blocks.ts

@@ -14,7 +14,7 @@
  * step.
  */
 
-import { FENCE, HEADING } from "./steps.ts";
+import { FENCE, HEADING } from "./sections.ts";
 
 /** How a block is rendered and grouped. */
 export type PlanBlockKind = "heading" | "paragraph" | "list" | "code" | "quote" | "table" | "hr" | "blank";
@@ -176,7 +176,7 @@ export function planBlocks(plan: string): PlanBlock[] {
 }
 
 /** The block containing source line `line`, or the nearest block before it. */
-export function blockAt(blocks: PlanBlock[], line: number): PlanBlock | undefined {
+export function blockAt(blocks: readonly PlanBlock[], line: number): PlanBlock | undefined {
 	let candidate: PlanBlock | undefined;
 	for (const block of blocks) {
 		if (block.start <= line && line <= block.end) return block;
@@ -186,6 +186,27 @@ export function blockAt(blocks: PlanBlock[], line: number): PlanBlock | undefine
 	return candidate;
 }
 
+/**
+ * The nearest block with content at or before `line`, else the first one after
+ * it: what a comment in blank space belongs to.
+ *
+ * A blank line is a block, so {@link blockAt} may name one, but a comment cannot
+ * hang on nothing: the review page renders no line for a blank block, so an
+ * anchor there is one it can never attach a thread to.
+ */
+export function contentBlockAt(blocks: readonly PlanBlock[], line: number): PlanBlock | undefined {
+	let before: PlanBlock | undefined;
+	for (const block of blocks) {
+		const content = block.kind !== "blank";
+		if (block.start <= line) {
+			if (content) before = block;
+			continue;
+		}
+		if (content) return before ?? block;
+	}
+	return before;
+}
+
 /** 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

@@ -13,6 +13,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { isRemoteTurn } from "../../lib/interaction.ts";
 import { READ_ONLY_SUMMARY } from "../../lib/plan-entry.ts";
 import { qrLines } from "../../lib/qr.ts";
+import { withRailsSuppressed } from "../../lib/rails.ts";
 import { feedbackSummary } from "./feedback.ts";
 import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
 import { runBrowserReview } from "./review.ts";
@@ -192,22 +193,26 @@ async function openPlanIndex(
 
 	// The review runs after the screen closes, so the input focus is free again.
 	let selected: (PlanSummary | undefined) | undefined;
-	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
-		const component = new PlanIndexComponent({
-			summaries,
-			dir,
-			theme,
-			onSelect: (summary) => {
-				selected = summary;
-				done();
-			},
-			onClose: () => done(),
-			reload: summarise,
-			requestRender: () => tui.requestRender(),
-			viewportRows: () => tui.terminal?.rows,
-		});
-		return component;
-	});
+	// A dock list shares the editor slot with the goal and todo rails, so it takes
+	// the dock to itself for as long as it is open, like the other list screens.
+	await withRailsSuppressed(pi, () =>
+		ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+			const component = new PlanIndexComponent({
+				summaries,
+				dir,
+				theme,
+				onSelect: (summary) => {
+					selected = summary;
+					done();
+				},
+				onClose: () => done(),
+				reload: summarise,
+				requestRender: () => tui.requestRender(),
+				viewportRows: () => tui.terminal?.rows,
+			});
+			return component;
+		}),
+	);
 	if (selected) await reviewInBrowser(pi, runtime, web, selected.path, ctx);
 }
 

package/extensions/plan/feedback.ts

@@ -21,8 +21,8 @@
  */
 
 import { sanitizeLine } from "../../lib/format.ts";
-import { blockAt, planBlocks, type PlanBlock } from "./blocks.ts";
-import { extractPlanSections } from "./steps.ts";
+import { blockAt, contentBlockAt, planBlocks, type PlanBlock } from "./blocks.ts";
+import { extractSections, sectionKeys } from "./sections.ts";
 
 /** Marker that opens every stored feedback line. */
 export const REVIEW_MARKER = "[!REVIEW]";
@@ -37,6 +37,12 @@ export interface PlanAnnotation {
 	comment: string;
 	/** Who wrote it; `""`/absent is the plan owner, the only writer before sharing. */
 	author?: string;
+	/**
+	 * Set when a refinement carried this comment onto a block other than the text it was
+	 * written on: the note is still the reviewer's, but where it sits is this build's best
+	 * guess, and the page says so instead of presenting a guess as her own anchor.
+	 */
+	moved?: true;
 }
 
 /** Most annotations one save may carry. */
@@ -51,8 +57,12 @@ export const MAX_AUTHOR_LENGTH = 40;
 /** The name a reviewer write is stored under, or why it cannot be decided. */
 export type AuthorClaim = { name: string } | { status: number; message: string };
 
-/** A stored feedback line, capturing its author and comment. */
-const MARKER_LINE = /^\s*>\s*\[!REVIEW\]\s?(.*)$/;
+/**
+ * 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
+ * reviewer wrote stays exactly what she typed.
+ */
+const MARKER_LINE = /^\s*>\s*\[!REVIEW(\s+moved)?\]\s?(.*)$/;
 /** The author prefix inside a marker body (`@alice: note`). */
 const AUTHOR_PREFIX = /^@([^:]{1,40}):\s?(.*)$/;
 
@@ -121,6 +131,8 @@ interface StoredMarker {
 	at: number;
 	comment: string;
 	author: string;
+	/** Whether a refinement carried this comment off the text it was written on. */
+	moved: boolean;
 }
 
 /** The plan body without markers, plus the markers that were removed from it. */
@@ -134,20 +146,23 @@ function scanMarkers(plan: string): { clean: string; markers: StoredMarker[] } {
 			clean.push(line);
 			return;
 		}
-		const body = match[1].trim();
+		const body = (match[2] ?? "").trim();
 		if (body === "") return;
 		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 });
+		if (comment) markers.push({ at: clean.length - 1, comment, author, moved: match[1] !== undefined });
 	});
 	return { clean: clean.join("\n"), markers };
 }
 
 /** One marker line in its stored form. */
-function markerLine(author: string, comment: string): string {
+function markerLine(author: string, comment: string, moved = false): string {
 	const body = sanitizeLine(comment);
-	return author ? `> ${REVIEW_MARKER} @${author}: ${body}` : `> ${REVIEW_MARKER} ${body}`;
+	// 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;
+	return author ? `> ${tag} @${author}: ${body}` : `> ${tag} ${body}`;
 }
 
 /** A marker waiting to be placed after clean-plan line `at`. */
@@ -191,28 +206,58 @@ export function stripFeedback(plan: string): string {
 }
 
 /**
- * Read stored feedback back. The anchor is the block ending just before each
- * marker in the stripped plan, so a comment keeps its place across reloads.
+ * A plan read the way the review reads it: its body, its blocks, and its
+ * comments, out of one parse.
  */
-export function parseFeedback(plan: string): PlanAnnotation[] {
+export interface FeedbackRead {
+	/** The plan body with every stored marker removed. */
+	body: string;
+	/** The body split into source-line blocks: the shape an anchor names. */
+	blocks: PlanBlock[];
+	/** The comments the markers carried, each anchored to a content block's start. */
+	annotations: PlanAnnotation[];
+}
+
+/**
+ * Read a plan once. An anchor is the start of the block the marker follows, so a
+ * comment keeps its place across reloads — and it is always a block with
+ * content, because the page renders no line for a blank one and so can never
+ * attach a thread to it. A plan whose every line is blank has no such block: its
+ * comments keep anchor `0` and the page lists them as unattached, which is the
+ * truth there.
+ */
+export function readFeedback(plan: string): FeedbackRead {
 	const { clean, markers } = scanMarkers(plan);
-	if (markers.length === 0) return [];
 	const blocks = planBlocks(clean);
-	return markers.map((marker) => {
-		const block = blockAt(blocks, marker.at);
-		const annotation: PlanAnnotation = { anchor: block ? block.start : 0, comment: marker.comment };
+	const annotations = markers.map((marker) => {
+		const annotation: PlanAnnotation = {
+			anchor: contentBlockAt(blocks, marker.at)?.start ?? 0,
+			comment: marker.comment,
+		};
 		if (marker.author) annotation.author = marker.author;
+		if (marker.moved) annotation.moved = true;
 		return annotation;
 	});
+	return { body: clean, blocks, annotations };
+}
+
+/** The comments a plan carries, in the order they were written. */
+export function parseFeedback(plan: string): PlanAnnotation[] {
+	return readFeedback(plan).annotations;
 }
 
 /** Sanitized, non-empty comments with the anchor they land on. */
-function storableComments(annotations: readonly PlanAnnotation[]): Array<{ anchor: number; comment: string }> {
-	const items: Array<{ anchor: number; comment: string }> = [];
+function storableComments(
+	annotations: readonly PlanAnnotation[],
+): Array<{ anchor: number; comment: string; moved: boolean }> {
+	const items: Array<{ anchor: number; comment: string; moved: boolean }> = [];
 	for (const annotation of annotations) {
 		const comment = sanitizeLine(annotation.comment);
 		if (comment.length === 0 || comment.length > MAX_COMMENT_LENGTH) continue;
-		items.push({ anchor: annotation.anchor, comment });
+		// 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 });
 	}
 	return items;
 }
@@ -227,11 +272,13 @@ 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) }));
+		.map((marker) => ({ at: marker.at, line: markerLine(marker.author, marker.comment, marker.moved) }));
 	const blocks = planBlocks(clean);
 	const added = storableComments(annotations).map((item) => ({
-		at: blockAt(blocks, item.anchor)?.end ?? -1,
-		line: markerLine(author, item.comment),
+		// 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),
 	}));
 	return compose(clean, [...kept, ...added]);
 }
@@ -247,30 +294,92 @@ function blockKey(block: PlanBlock): string {
 }
 
 /**
- * A plan's heading sections, keyed by title and occurrence, each with the blocks
- * inside it and its last source line. Two `## Notes` sections are told apart by
- * which one they are, the way `changedSections` does it, so a duplicate heading
- * never collects both sections' blocks.
+ * Words a block is compared by when it may merely have been reworded: lowercased,
+ * with the list marker and task checkbox dropped. Every step of a `## Steps`
+ * section would otherwise match every other one through its `- [ ]` alone.
+ */
+function blockWords(block: PlanBlock): Set<string> {
+	const text = block.lines
+		.join(" ")
+		.toLowerCase()
+		.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, " ")
+		.replace(/\[[ x]\]/g, " ");
+	return new Set(text.split(/[^\p{L}\p{N}]+/u).filter((word) => word !== ""));
+}
+
+/** Share of the longer block's words that both blocks have. */
+function sharedShare(a: ReadonlySet<string>, b: ReadonlySet<string>): number {
+	if (a.size === 0 || b.size === 0) return 0;
+	let shared = 0;
+	for (const word of a) if (b.has(word)) shared += 1;
+	return shared / Math.max(a.size, b.size);
+}
+
+/** Share of its words a block keeps, at or above which it is the same block reworded. */
+const MATCH_SHARE = 0.5;
+
+/**
+ * Which block of `next` each block of `old` became, keeping both lists in
+ * document order: the longest set of pairs whose wording overlaps enough to be one
+ * block reworded. A block left without a pair is `-1` — deleted, or replaced by
+ * text that shares nothing — which is the gap its comment belongs in.
+ */
+function alignBlocks(old: readonly PlanBlock[], next: readonly PlanBlock[]): number[] {
+	const before = old.map(blockWords);
+	const after = next.map(blockWords);
+	const matches = before.map((words) => after.map((other) => (sharedShare(words, other) >= MATCH_SHARE ? 1 : 0)));
+	// A longest common subsequence over the match grid, so a block that moved keeps
+	// its own pairing instead of pulling the blocks around it along.
+	const width = next.length + 1;
+	const counts = new Array<number>((old.length + 1) * width).fill(0);
+	for (let row = old.length - 1; row >= 0; row--) {
+		for (let column = next.length - 1; column >= 0; column--) {
+			const paired = matches[row][column] === 1 ? 1 + counts[(row + 1) * width + column + 1] : 0;
+			counts[row * width + column] = Math.max(
+				paired,
+				counts[(row + 1) * width + column],
+				counts[row * width + column + 1],
+			);
+		}
+	}
+	const aligned = new Array<number>(old.length).fill(-1);
+	let row = 0;
+	let column = 0;
+	while (row < old.length && column < next.length) {
+		if (matches[row][column] === 1 && counts[row * width + column] === 1 + counts[(row + 1) * width + column + 1]) {
+			aligned[row] = column;
+			row += 1;
+			column += 1;
+			continue;
+		}
+		if (counts[(row + 1) * width + column] >= counts[row * width + column + 1]) row += 1;
+		else column += 1;
+	}
+	return aligned;
+}
+
+/**
+ * A plan's heading sections, keyed by `sectionKeys`, each with the blocks a
+ * comment can hang on and the last line of that content. Blank lines are left out
+ * on purpose: a position among them would move when one is added or removed
+ * above, and a reworded step would lose its comment to the next block. A section
+ * with no content block ends at its own heading, which the page renders.
  */
 function sectionIndex(plan: string, blocks: readonly PlanBlock[]): Map<string, { blocks: PlanBlock[]; end: number }> {
-	const sections = extractPlanSections(plan);
-	const lineCount = plan === "" ? 0 : plan.split("\n").length;
-	const seen = new Map<string, number>();
+	const sections = extractSections(plan);
 	const index = new Map<string, { blocks: PlanBlock[]; end: number }>();
-	const keys = sections.map((section, position) => {
-		const occurrence = seen.get(section.title) ?? 0;
-		seen.set(section.title, occurrence + 1);
-		const key = `${occurrence}\u0000${section.title}`;
-		index.set(key, { blocks: [], end: (sections[position + 1]?.line ?? lineCount) - 1 });
-		return key;
-	});
+	const keys = sectionKeys(sections);
+	keys.forEach((key, at) => index.set(key, { blocks: [], end: sections[at]?.line ?? 0 }));
 
 	let position = 0;
 	for (const block of blocks) {
 		while (position + 1 < sections.length && (sections[position + 1]?.line ?? 0) <= block.start) position += 1;
 		const key = keys[position];
 		if (key === undefined) continue;
-		index.get(key)?.blocks.push(block);
+		const entry = index.get(key);
+		if (!entry || block.kind === "blank") continue;
+		entry.blocks.push(block);
+		entry.end = block.end;
 	}
 	return index;
 }
@@ -280,9 +389,11 @@ function sectionIndex(plan: string, blocks: readonly PlanBlock[]): Map<string, {
  * Comments are not plan content, so `next` is stripped of any marker it carries,
  * and every old one is re-attached by the strongest evidence that survives: the
  * block's text (per occurrence, so two identical steps keep their own comments),
- * then the same section and ordinal, then the end of that section. A comment
- * whose section is gone too is placed at the end rather than dropped, where the
- * review page shows it as unattached.
+ * then the block the alignment says it became when the wording changed, then the
+ * gap it left between the blocks that survived, then the end of that section's
+ * content. A comment whose section is gone too moves to the plan's last content
+ * block, so the page keeps showing it under a block rather than listing it as
+ * unattached; only a plan with no block at all leaves it in that list.
  */
 export function carryFeedback(previous: string, next: string): string {
 	const { clean: oldClean, markers } = scanMarkers(previous);
@@ -303,29 +414,51 @@ export function carryFeedback(previous: string, next: string): string {
 	const oldSections = sectionIndex(oldClean, oldBlocks);
 	const nextSections = sectionIndex(cleanNext, nextBlocks);
 	const lastLine = cleanNext === "" ? -1 : cleanNext.split("\n").length - 1;
+	// Where a comment goes when nothing about it survived: beside the plan's last
+	// block, never after the blank line a trailing newline leaves.
+	const tail = contentBlockAt(nextBlocks, lastLine)?.end ?? lastLine;
+
+	/** One alignment per section, reused by every comment that lands in it. */
+	const alignments = new Map<string, number[]>();
 
-	/** The block at the same ordinal in the same section, else that section's end. */
+	/**
+	 * Where a comment goes when its own block's text is gone: the block the alignment
+	 * says it became, else the gap it left, else its section's end.
+	 */
 	const bySection = (block: PlanBlock): number | undefined => {
-		for (const [key, old] of oldSections) {
-			const ordinal = old.blocks.indexOf(block);
-			if (ordinal < 0) continue;
-			const section = nextSections.get(key);
-			if (section === undefined) return undefined;
-			const same = section.blocks[ordinal];
-			return same ? same.end : section.end;
+		for (const [key, before] of oldSections) {
+			const index = before.blocks.indexOf(block);
+			if (index < 0) continue;
+			const after = nextSections.get(key);
+			if (after === undefined) return undefined;
+			let aligned = alignments.get(key);
+			if (aligned === undefined) {
+				aligned = alignBlocks(before.blocks, after.blocks);
+				alignments.set(key, aligned);
+			}
+			const became = aligned[index];
+			if (became >= 0) return after.blocks[became].end;
+			// The gap it left is right after the block before its nearest surviving
+			// successor: for the first block of a section, that is the heading.
+			const successor = aligned.findIndex((at, from) => from > index && at >= 0);
+			const gap = successor >= 0 ? after.blocks[aligned[successor] - 1] : undefined;
+			return gap?.end ?? after.end;
 		}
 		return undefined;
 	};
 
 	const placed = markers.map((marker) => {
 		const block = blockAt(oldBlocks, marker.at);
-		const line = markerLine(marker.author, marker.comment);
-		if (block === undefined) return { at: lastLine, line };
+		// 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);
+		if (block === undefined) return { at: tail, line: keep(true) };
 		if (block.kind !== "blank") {
 			const match = queues.get(blockKey(block))?.shift();
-			if (match !== undefined) return { at: match.end, line };
+			if (match !== undefined) return { at: match.end, line: keep(false) };
 		}
-		return { at: bySection(block) ?? lastLine, line };
+		return { at: bySection(block) ?? tail, line: keep(true) };
 	});
 	return compose(cleanNext, placed);
 }
@@ -344,7 +477,7 @@ export function displayFeedback(plan: string): string {
 			if (fenced.has(index)) return line;
 			const match = MARKER_LINE.exec(line);
 			if (!match) return line;
-			const body = match[1].trim();
+			const body = (match[2] ?? "").trim();
 			if (body === "") return line;
 			const authored = AUTHOR_PREFIX.exec(body);
 			const author = authored ? normalizeAuthor(authored[1]) : "";

package/extensions/plan/format.ts

@@ -72,16 +72,23 @@ export function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 	const total = steps.length;
 	const counted = `${merged.added + merged.skipped} of ${total} plan step${total === 1 ? "" : "s"}`;
 	const notes = [
+		merged.replaced > 0
+			? `${merged.replaced} stale item${merged.replaced === 1 ? "" : "s"} from the earlier approval replaced`
+			: "",
 		merged.skipped > 0 ? `${merged.skipped} already present` : "",
 		merged.kept > 0 ? `${merged.kept} existing kept` : "",
 		merged.deferred > 0 ? `${merged.deferred} deferred, list full` : "",
 	].filter(Boolean);
 	const suffix = notes.length > 0 ? ` (${notes.join(", ")})` : "";
 	const tick = `Tick each one off in the file with ${SET_PLAN_STEPS_TOOL} as you finish it, passing the step's text as \`expected\`.`;
+	const touched =
+		merged.stale > 0
+			? ` ${merged.stale} older item${merged.stale === 1 ? "" : "s"} no longer match${merged.stale === 1 ? "es" : ""} this plan but ${merged.stale === 1 ? "was" : "were"} left alone: ${merged.stale === 1 ? "it was" : "they were"} started or finished, so check ${merged.stale === 1 ? "it" : "them"} yourself.`
+			: "";
 	if (merged.added === 0 && merged.skipped === 0) {
-		return ` The todo list is full, so no plan steps were added${suffix}. Keep these steps in mind. ${tick}`;
+		return ` The todo list is full, so no plan steps were added${suffix}.${touched} Keep these steps in mind. ${tick}`;
 	}
 	if (merged.added === 0)
-		return ` ${total === 1 ? "The plan's step is" : "Every plan step is"} already in the todo list${suffix}. ${tick}`;
-	return ` Merged ${counted} into the todo list${suffix}. ${tick}`;
+		return ` ${total === 1 ? "The plan's step is" : "Every plan step is"} already in the todo list${suffix}.${touched} ${tick}`;
+	return ` Merged ${counted} into the todo list${suffix}.${touched} ${tick}`;
 }

package/extensions/plan/index.ts

@@ -24,7 +24,14 @@ import { isExtensionEnabled } from "../../lib/env.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";
-import { ASK_USER_QUESTION_TOOL, SUBAGENT_READ_ONLY_PARAM, SUBAGENT_TOOL } from "../../lib/tool-names.ts";
+import { isBoardRead } from "../../lib/policy.ts";
+import {
+	ASK_USER_QUESTION_TOOL,
+	BOARD_READ_ACTION,
+	BOARD_TOOL,
+	SUBAGENT_READ_ONLY_PARAM,
+	SUBAGENT_TOOL,
+} from "../../lib/tool-names.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { planModeNotice, registerCommands } from "./commands.ts";
@@ -149,10 +156,12 @@ export default function planMode(pi: ExtensionAPI): void {
 	 * the path backstop (a hint on a path-carrying tool is only a claim).
 	 */
 	const blockedReason = (toolName: string, input: unknown): string | undefined => {
-		// Plan-owned control tools are the sanctioned exception: `write_plan` saves
-		// the artifact, `exit_plan_mode` presents it. The source-path check keeps a
-		// same-named tool from another extension from borrowing the exemption.
-		if (runtime.isControlTool(toolName)) return undefined;
+		// Plan-owned tools are the sanctioned exception: `write_plan` saves the
+		// artifact, `exit_plan_mode` presents it, `cancel_plan_mode` restores access,
+		// and `enter_plan_mode` answers "already" to a call that was in flight when
+		// plan mode came on. The source-path check keeps a same-named tool from
+		// another extension from borrowing the exemption.
+		if (runtime.isOwnTool(toolName)) return undefined;
 		// `subagent` stays active, but only as read-only delegation. The flag is
 		// forced in place (the child enforces it through `--tools`), so the model
 		// cannot forget it; a `subagent` that does not declare the parameter is
@@ -166,6 +175,15 @@ export default function planMode(pi: ExtensionAPI): void {
 			}
 			return undefined;
 		}
+		// `board` stays active so planning can read the board it is about to add cards
+		// to. The action is the truth here, not the annotation: the same tool writes, so
+		// `readOnlyHint` cannot say it, and every verb but the read is refused by name.
+		if (toolName === BOARD_TOOL) {
+			if (isBoardRead(input)) return undefined;
+			const action = (input as { action?: unknown } | undefined)?.action;
+			const verb = typeof action === "string" && action.trim() !== "" ? action.trim() : "board";
+			return `Plan mode: \`${verb}\` changes the board — only \`${BOARD_READ_ACTION}\` reads it. ${BLOCKED_GUIDANCE}`;
+		}
 		const blocked = policy.check(toolName);
 		if (blocked) return `Plan mode: ${blocked.reason}`;
 		// `bash` is allowed by the policy so read-only git stays possible; this is

package/extensions/plan/plan-files.ts

@@ -0,0 +1,88 @@
+/**
+ * How a plan file reaches the disk, and what it leaves behind (one job).
+ *
+ * Two writes, one subject: the plan itself, atomically so a crash cannot truncate
+ * the artifact a review is reading, and the revision a refinement replaces, kept
+ * beside it so the two can be compared. Keeping them together is deliberate — the
+ * revision has to be written with the same care as the plan, and before the rename
+ * that overwrites it, or the text is gone.
+ *
+ * A revision is a dotfile named for its plan (`.‹plan›-r001.md`): `isPlanFileName`
+ * and every scan that reads the directory as an index skip it, so a revision is
+ * never listed, reviewed, approved, or opened by `plan_path`.
+ *
+ * Value-only, as a store helper must be: the paths and the text are the caller's.
+ */
+
+import { randomBytes } from "node:crypto";
+import { readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * How many replaced revisions a plan keeps, as dotfiles beside it.
+ *
+ * A refinement overwrites the file it replaces, because the reviewed artifact has to
+ * be the executed one — so the text the reviewer read was gone the moment it was
+ * refined: a comment `carryFeedback` mis-anchored could not be checked against what
+ * she actually saw, and two revisions could not be diffed. Five is a chain deep
+ * enough to answer "what changed since I last looked" and short enough that a plan
+ * refined all afternoon does not leave fifty files in the store.
+ */
+const MAX_REVISIONS = 5;
+
+/**
+ * Write a plan atomically: a hidden sibling temp file, then a rename. A crash
+ * or a full disk mid-write leaves the previous file intact instead of a
+ * truncated plan, and the temp name is a dotfile, so neither `latest()` nor a
+ * plan lookup ever mistakes it for a plan.
+ */
+export function writeAtomic(path: string, content: string): void {
+	const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		writeFileSync(temp, content, { encoding: "utf-8", flag: "wx" });
+		renameSync(temp, path);
+	} catch (error) {
+		try {
+			unlinkSync(temp);
+		} catch {
+			// The temp file was never created, or the rename already moved it.
+		}
+		throw error;
+	}
+}
+
+/** The prefix a plan's revisions share, so one chain is one `startsWith`. */
+function revisionPrefix(path: string): string {
+	return `.${basename(path).replace(/\.md$/i, "")}-r`;
+}
+
+/** The number a revision's name carries, so the newest is the highest. */
+function revisionNumber(name: string): number {
+	const digits = /-r(\d+)\.md$/i.exec(name)?.[1];
+	return digits === undefined ? 0 : Number.parseInt(digits, 10);
+}
+
+/** Keep `previous` as `path`'s next revision, and drop all but the newest few. */
+export function keepRevision(path: string, previous: string): string {
+	const dir = dirname(path);
+	const prefix = revisionPrefix(path);
+	let names: string[];
+	try {
+		names = readdirSync(dir).filter((name) => name.startsWith(prefix) && revisionNumber(name) > 0);
+	} catch {
+		names = [];
+	}
+	const next = Math.max(0, ...names.map(revisionNumber)) + 1;
+	const target = join(dir, `${prefix}${String(next).padStart(3, "0")}.md`);
+	writeAtomic(target, previous);
+	// Oldest first, so what stays is the newest chain.
+	const chain = [...names, basename(target)].sort((a, b) => revisionNumber(a) - revisionNumber(b));
+	for (const name of chain.slice(0, Math.max(0, chain.length - MAX_REVISIONS))) {
+		try {
+			unlinkSync(join(dir, name));
+		} catch {
+			// A revision that vanished is one fewer to prune.
+		}
+	}
+	return target;
+}