@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/plan/plan-index.ts

@@ -16,7 +16,8 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Key, matchesKey, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { sanitizeLine, shortenPath } from "../../lib/format.ts";
 import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
-import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { detailBlockRows, dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { formatSize } from "../../lib/format.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { emptyState, listRow } from "../../lib/tui/rows.ts";
 import { titleRule } from "../../lib/tui/rules.ts";
@@ -25,8 +26,12 @@ import type { PlanSummary } from "./plans.ts";
 
 /** Rows the screen shows when the terminal height is unknown. */
 const DEFAULT_ROWS = 14;
-/** Fixed rows around the list: header, summary, blank, range, detail, hint, closing rule. */
-const CHROME = 7;
+/**
+ * Fixed rows around the list body: header, summary, blank, and the closing footer
+ * (blank, hint, rule). The focused path adds `detailBlockRows` on top, and `fitRows`
+ * adds one more when the range row appears.
+ */
+const CHROME = 6;
 /** Longest title a row draws before the trailing meta wins the column. */
 const TITLE_WIDTH = 56;
 
@@ -56,11 +61,33 @@ function localTime(ms: number): string {
 	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
 }
 
+/**
+ * The store's own footprint for one repository: the bytes its plans hold, and the
+ * oldest of them. Derived from the summary the directory walk already produced, so
+ * reporting a size never becomes a second index that can disagree with the files.
+ */
+function footprint(summaries: readonly PlanSummary[]): { bytes: number; oldest: number } {
+	let bytes = 0;
+	let oldest = summaries[0]?.modified ?? 0;
+	for (const summary of summaries) {
+		bytes += summary.bytes;
+		oldest = Math.min(oldest, summary.modified);
+	}
+	return { bytes, oldest };
+}
+
+/** `2.4 kB — oldest 2d ago`, the store's footprint as the header and the screen say it. */
+function footprintText(summaries: readonly PlanSummary[], nowMs: number): string {
+	const { bytes, oldest } = footprint(summaries);
+	return `${formatSize(bytes)} — oldest ${relativeAge(oldest, nowMs)}`;
+}
+
 /**
  * The non-TUI listing: one line per plan with its title, step progress, modified
- * time, and path, newest first. The directory is named once in the header.
+ * time, and path, newest first. The header names the count, the store's footprint,
+ * and the directory once; `now` is injectable so the age can be asserted.
  */
-export function formatPlanIndex(summaries: readonly PlanSummary[], dir: string): string {
+export function formatPlanIndex(summaries: readonly PlanSummary[], dir: string, now: number = Date.now()): string {
 	const where = sanitizeLine(shortenPath(dir));
 	if (summaries.length === 0) {
 		return `No plans in ${where} yet; write_plan saves one there.`;
@@ -69,7 +96,7 @@ export function formatPlanIndex(summaries: readonly PlanSummary[], dir: string):
 		(summary) =>
 			`  ${sanitizeLine(summary.title)} — ${stepsText(summary)} — ${localTime(summary.modified)} — ${sanitizeLine(summary.relativePath)}`,
 	);
-	return [`Plans (${summaries.length}) — ${where}`, ...lines].join("\n");
+	return [`Plans (${summaries.length}) — ${footprintText(summaries, now)} — ${where}`, ...lines].join("\n");
 }
 
 export interface PlanIndexOptions {
@@ -185,7 +212,8 @@ export class PlanIndexComponent implements Component {
 	private summaryLine(width: number): string {
 		const { theme } = this.options;
 		const count = this.summaries.length;
-		const text = `${paint(theme, "accent", "Plans")} ${paint(theme, "meta", `· ${count} ${count === 1 ? "plan" : "plans"}`)}`;
+		const size = footprintText(this.summaries, (this.options.now ?? Date.now)());
+		const text = `${paint(theme, "accent", "Plans")} ${paint(theme, "meta", `· ${count} ${count === 1 ? "plan" : "plans"} · ${size}`)}`;
 		const where = paint(theme, "faint", ` · ${sanitizeLine(shortenPath(this.options.dir))}`);
 		return clip(`  ${text}${where}`, width);
 	}
@@ -202,12 +230,18 @@ export class PlanIndexComponent implements Component {
 	render(width: number): string[] {
 		const { theme } = this.options;
 		const w = Math.max(1, width);
-		this.cursor.visible = fitRows(this.options.viewportRows, this.summaries.length, CHROME, DEFAULT_ROWS);
 		this.cursor.sync(this.summaries.length);
+		const detail = this.detailLines(w);
+		this.cursor.visible = fitRows(
+			this.options.viewportRows,
+			this.summaries.length,
+			CHROME + detailBlockRows(detail),
+			DEFAULT_ROWS,
+		);
 
 		const body: string[] = [];
 		if (this.summaries.length === 0) {
-			body.push(...emptyState(theme, w, { label: "No plans yet. write_plan saves one under .pi/plans." }));
+			body.push(...emptyState(theme, w, { label: "No plans yet. write_plan saves one in the agent directory." }));
 		} else {
 			const { start, end } = this.cursor.window(this.summaries.length);
 			for (let index = start; index < end; index++) {
@@ -229,7 +263,7 @@ export class PlanIndexComponent implements Component {
 			range: this.cursor.clipped(this.summaries.length)
 				? formatRange(theme, w, { ...this.cursor.window(this.summaries.length), total: this.summaries.length })
 				: undefined,
-			detail: this.detailLines(w),
+			detail,
 			hint,
 		});
 	}

package/extensions/plan/plan-text.ts

@@ -15,8 +15,8 @@
 
 import { createHash } from "node:crypto";
 import { stripControlChars } from "../../lib/format.ts";
-import { stripFeedback } from "./feedback.ts";
-import { extractPlanSections } from "./steps.ts";
+import { displayFeedback, stripFeedback } from "./feedback.ts";
+import { extractSections, sectionKeys, type PlanSection } from "./sections.ts";
 
 /** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
 const TAB_WIDTH = 4;
@@ -38,6 +38,14 @@ export function sanitizePlanText(text: string): string {
 	return stripControlChars(text.replace(/\t/g, " ".repeat(TAB_WIDTH)));
 }
 
+/**
+ * The text a review *shows*: terminal-safe, with stored comments kept in place
+ * as readable quotes, so a reviewer sees what a teammate wrote.
+ */
+export function planDisplayText(content: string): string {
+	return displayFeedback(sanitizePlanText(content));
+}
+
 /**
  * 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
@@ -52,9 +60,18 @@ function digestOf(text: string): string {
 	return createHash("sha256").update(text.trim()).digest("hex");
 }
 
+/**
+ * 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
+ * dropped for a plan that changed underneath it.
+ */
+export function planDigest(text: string): string {
+	return digestOf(text).slice(0, 12);
+}
+
 /** One digest per heading section, in document order, for a persisted baseline. */
 export function sectionDigests(content: string): SectionDigest[] {
-	return extractPlanSections(reviewText(content)).map((section) => ({
+	return extractSections(reviewText(content)).map((section) => ({
 		title: section.title,
 		digest: digestOf(section.text),
 	}));
@@ -66,30 +83,40 @@ export function sameSections(a: readonly SectionDigest[], b: readonly SectionDig
 	return a.every((section, index) => section.title === b[index].title && section.digest === b[index].digest);
 }
 
+/** One section of the text as it reads now, and whether it differs from the baseline. */
+export interface SectionMark {
+	/** The section, in the order the document lists it. */
+	section: PlanSection;
+	/** Whether its content differs from the baseline's section in the same place. */
+	changed: boolean;
+}
+
 /**
- * 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.
+ * Per-section change marks for a second review: every section of `current` with
+ * whether its content differs from the baseline's section in the same place.
+ *
+ * The marks carry their sections, so a caller cannot pair the flags with a list it
+ * parsed separately — the section list and its marks come out of one scan, in
+ * document order. Duplicate headings are told apart by occurrence rather than by
+ * title. An absent baseline marks nothing, which is what a first review of a plan
+ * looks like; `stripFeedback` only ever drops quote-marker lines, so the marks 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);
+export function changedSections(baseline: readonly SectionDigest[] | undefined, current: string): SectionMark[] {
+	const sections = extractSections(reviewText(current));
+	if (baseline === undefined) return sections.map((section) => ({ section, changed: 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]);
-	}
+	// Same section across two reviews: `sectionKeys` tells a second `## Notes` from
+	// the first, so a duplicate heading is never compared with the wrong digest.
+	const before = new Map<string, string>();
+	sectionKeys(baseline).forEach((key, at) => {
+		const digest = baseline[at]?.digest;
+		if (digest !== undefined) before.set(key, 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);
+	const keys = sectionKeys(sections);
+	return sections.map((section, at) => {
+		const prior = before.get(keys[at] ?? "");
+		return { section, changed: prior === undefined || prior !== digestOf(section.text) };
 	});
 }

package/extensions/plan/plans.ts

@@ -4,15 +4,19 @@
  * A plan is written to disk as markdown: one file per plan, named from the
  * title and stamp. A refinement rewrites that file atomically, so the user can
  * read the same artifact the model is working from and the plan survives
- * outside the conversation without a partial write ever being visible. Files
- * live under `<repo-root>/.pi/plans` (the worktree root inside a worktree), or
- * under `<agent-dir>/plans` outside a repository. An extension tool sees the
- * session cwd rather than the worktree the user entered, so the active worktree
- * is applied before any path is resolved.
+ * outside the conversation without a partial write ever being visible.
  *
- * The directory is self-ignoring: the first write drops a `.gitignore` with `*`
- * so plans never show up as untracked files or inside rewind snapshots,
- * without editing the project's own `.gitignore`.
+ * Plans live under `<agent-dir>/plans/<repo-key>`, keyed by the repository's
+ * common git directory, so every worktree and every session of one repository
+ * reads one store — a plan approved in a worktree is the same plan from the main
+ * checkout. Outside a repository they land under `<agent-dir>/plans`. An
+ * extension tool sees the session cwd rather than the worktree the user entered,
+ * so the active worktree is applied before any path is resolved.
+ *
+ * Plans are outside the project, so they are never untracked files and never
+ * appear in a rewind snapshot. A store written by an older version, under
+ * `<repo>/.pi/plans`, is moved in once, and nothing is deleted before its plans
+ * have arrived.
  *
  * This module owns paths and bytes only; tool wiring lives in `tools.ts`.
  */
@@ -25,29 +29,38 @@ import {
 	readFileSync,
 	readdirSync,
 	renameSync,
+	rmdirSync,
 	statSync,
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolveEffectiveCwd } from "../../lib/env.ts";
-import { repoRootFor } from "../../lib/git/index.ts";
-import { sanitizeLine } from "../../lib/format.ts";
+import { sanitizeLine, shortenPath } from "../../lib/format.ts";
 import { isInside, isInsideReal } from "../../lib/path.ts";
-import { formatFeedback, type PlanAnnotation } from "./feedback.ts";
+import { repoKeyFor } from "../../lib/repo-key.ts";
+import { carryFeedback, formatFeedback, normalizeAuthor, type PlanAnnotation } from "./feedback.ts";
 import { extractPlanSteps, matchesStepText, setStepStatuses, type StepUpdate } from "./steps.ts";
 
 /** Largest plan accepted, in UTF-8 bytes. */
 export const MAX_PLAN_BYTES = 256 * 1024;
 /** Longest slug derived from a plan title. */
 const MAX_SLUG_LENGTH = 60;
+/** The agent-directory entry plans are filed under. */
+const PLANS_DIRNAME = "plans";
+
+/** The plan store: `<agent-dir>/plans`, or `<agent-dir>/plans/<key>` inside a repository. */
+function plansDir(agentDir: string, key?: string): string {
+	return key === undefined ? join(agentDir, PLANS_DIRNAME) : join(agentDir, PLANS_DIRNAME, key);
+}
 
 /** A plan read from disk. */
 export interface StoredPlan {
 	/** Absolute path. */
 	path: string;
-	/** Path relative to the working directory, when it is inside it. */
+	/** How the path is shown to the user: `~`-shortened, since plans live outside the project. */
 	relativePath: string;
 	content: string;
 	bytes: number;
@@ -62,7 +75,7 @@ export interface WrittenPlan extends StoredPlan {
 export interface PlanSummary {
 	/** Absolute path. */
 	path: string;
-	/** Path relative to the working directory, when it is inside it. */
+	/** How the path is shown to the user: `~`-shortened, since plans live outside the project. */
 	relativePath: string;
 	/** The plan's `# title`, or a title derived from the file name. */
 	title: string;
@@ -99,8 +112,20 @@ export interface PlanStore {
 	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. */
-	saveFeedback(cwd: string, planPath: string, annotations: PlanAnnotation[]): Promise<StoredPlan>;
+	/** Replace the comments of `options.author` (the owner when absent) and keep every other writer's. */
+	saveFeedback(
+		cwd: string,
+		planPath: string,
+		annotations: PlanAnnotation[],
+		options?: { author?: string },
+	): Promise<StoredPlan>;
+	/**
+	 * The line a one-time migration wants reported, or undefined.
+	 *
+	 * A moved store is the user's business — plans are not where they used to be —
+	 * so the first caller that can show a notice takes it and clears it.
+	 */
+	takeNotice(): string | undefined;
 }
 
 /** Timestamp prefix the plan store adds to file names. */
@@ -155,16 +180,19 @@ function isContainedPlan(dir: string, path: string): boolean {
 	return isInsideReal(dir, dirname(path));
 }
 
-/** Keep plan files out of git (and so out of rewind snapshots) without touching the project. */
-function ensureIgnored(dir: string): void {
-	const ignore = join(dir, ".gitignore");
-	try {
-		// `wx` is race-free: an existing ignore file (ours or a user's) is left alone.
-		writeFileSync(ignore, "*\n", { encoding: "utf-8", flag: "wx" });
-	} catch {
-		// A read-only plans directory will fail on the plan write anyway; the
-		// ignore file is best-effort.
-	}
+/**
+ * Resolve a `plan_path` argument against the store.
+ *
+ * A plan lives outside the project, so a path relative to the working directory
+ * can no longer name one. Absolute paths and the `~/…` form the tools display are
+ * accepted, and a bare name resolves inside the store — which is what a reader of
+ * a tool result has in hand.
+ */
+function resolvePlanArg(dir: string, planPath: string): string {
+	const text = planPath.trim();
+	if (text === "~") return homedir();
+	if (text.startsWith("~/") || text.startsWith(`~${sep}`)) return resolve(homedir(), text.slice(2));
+	return isAbsolute(text) ? resolve(text) : resolve(dir, text);
 }
 
 /**
@@ -188,12 +216,6 @@ function writeAtomic(path: string, content: string): void {
 	}
 }
 
-/** `path` relative to `cwd` when inside it, else `path`. */
-function relativeTo(cwd: string, path: string): string {
-	const rel = relative(cwd, path);
-	return rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel) ? rel : path;
-}
-
 function uniquePath(dir: string, base: string): string {
 	const taken = (candidate: string): boolean => {
 		try {
@@ -214,16 +236,69 @@ function uniquePath(dir: string, base: string): string {
 	return candidate;
 }
 
-/** Repository (or worktree) root of `cwd`, or undefined outside a repository. */
-async function repoRoot(pi: ExtensionAPI, cwd: string): Promise<string | undefined> {
-	// Local `rev-parse` is fast; cap it so a stuck call cannot hang the tool.
-	return repoRootFor(pi, cwd, 5_000);
+/** A repository (or worktree) root is applied before any path here is resolved. */
+
+/** How many legacy plans one migration moves, so a pathological directory cannot stall a tool call. */
+const MAX_MIGRATED_PLANS = 200;
+
+/**
+ * Move a store written by an older version, under `<repo>/.pi/plans`, into `dir`.
+ *
+ * Copy-then-unlink when a rename crosses a filesystem boundary, so a store on a
+ * different volume still arrives. Nothing here deletes before its plan has
+ * landed, a file that cannot move is left where it is, and the old directory
+ * goes only when what remains is the ignore file this package used to write.
+ */
+function migrateLegacyStore(dir: string, legacy: string): number {
+	if (!existsSync(legacy)) return 0;
+	let names: string[];
+	try {
+		names = readdirSync(legacy);
+	} catch {
+		return 0;
+	}
+	const plans = names.filter((name) => isPlanFileName(name)).slice(0, MAX_MIGRATED_PLANS);
+	let moved = 0;
+	for (const name of plans) {
+		const from = join(legacy, name);
+		try {
+			if (!statSync(from).isFile()) continue;
+			mkdirSync(dir, { recursive: true });
+			const to = uniquePath(dir, name.replace(/\.md$/i, ""));
+			try {
+				renameSync(from, to);
+			} catch {
+				writeFileSync(to, readFileSync(from), { flag: "wx" });
+				unlinkSync(from);
+			}
+			moved += 1;
+		} catch {
+			// A plan that cannot move stays where it is, and the directory stays with it.
+		}
+	}
+	try {
+		if (readdirSync(legacy).every((name) => name === ".gitignore")) {
+			const ignore = join(legacy, ".gitignore");
+			if (existsSync(ignore) && readFileSync(ignore, "utf-8") === "*\n") unlinkSync(ignore);
+			rmdirSync(legacy);
+		}
+	} catch {
+		// Leave a directory that still holds something.
+	}
+	return moved;
 }
 
 export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date } = {}): PlanStore {
 	const now = options.now ?? (() => new Date());
 	// One `git rev-parse` per effective root; a worktree switch changes that root.
-	const dirCache = new Map<string, string>();
+	const dirCache = new Map<string, { dir: string; root: string | undefined }>();
+	let notice: string | undefined;
+
+	const takeNotice = (): string | undefined => {
+		const line = notice;
+		notice = undefined;
+		return line;
+	};
 
 	/**
 	 * The root every path here is resolved against.
@@ -231,21 +306,29 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	 * A tool registered by an extension receives the session's cwd, not the
 	 * worktree the user entered: only the built-ins are re-rooted. The worktree
 	 * extension publishes its root in the environment, so this is where the two
-	 * meet, and it is applied before the git lookup, the relative path, and the
-	 * plan path resolution.
+	 * meet, and it is applied before the repository lookup, the migration of an
+	 * older store, and the plan path resolution.
 	 */
 	const baseOf = (cwd: string): string => resolveEffectiveCwd(cwd);
 
-	const dirFor = async (cwd: string): Promise<string> => {
+	const resolve = async (cwd: string): Promise<{ dir: string; root: string | undefined }> => {
 		const base = baseOf(cwd);
 		const cached = dirCache.get(base);
 		if (cached) return cached;
-		const root = await repoRoot(pi, base);
-		const dir = root ? join(root, CONFIG_DIR_NAME, "plans") : join(getAgentDir(), "plans");
-		dirCache.set(base, dir);
-		return dir;
+		const repo = await repoKeyFor(pi, base);
+		const dir = plansDir(getAgentDir(), repo.fromGit ? repo.key : undefined);
+		dirCache.set(base, { dir, root: repo.fromGit ? repo.root : undefined });
+		if (repo.fromGit) {
+			// The keyed directory is the store; a store an older version left in the
+			// checkout moves in once, so an upgrade does not strand its plans.
+			const moved = migrateLegacyStore(dir, join(base, CONFIG_DIR_NAME, "plans"));
+			if (moved > 0) notice = `Moved ${moved} plan${moved === 1 ? "" : "s"} to ${shortenPath(dir)}.`;
+		}
+		return { dir, root: repo.fromGit ? repo.root : undefined };
 	};
 
+	const dirFor = async (cwd: string): Promise<string> => (await resolve(cwd)).dir;
+
 	const write = async (cwd: string, input: WritePlanInput): Promise<WrittenPlan> => {
 		const base = baseOf(cwd);
 		const title = input.title.trim();
@@ -257,11 +340,10 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 		const dir = await dirFor(base);
 		mkdirSync(dir, { recursive: true });
-		ensureIgnored(dir);
 
 		let path: string;
 		if (input.planPath) {
-			const resolved = resolve(base, input.planPath);
+			const resolved = resolvePlanArg(dir, input.planPath);
 			if (!isContainedPlan(dir, resolved)) {
 				throw new Error("plan_path must be a markdown plan file inside the plans directory.");
 			}
@@ -275,20 +357,30 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 			throw new Error("The plan path is not writable inside the plans directory.");
 		}
 
-		writeAtomic(path, input.content);
-		return { path, relativePath: relativeTo(base, path), title, content: input.content, bytes };
+		// A refinement rewrites the body but not the review: every stored comment is
+		// carried onto the block whose text survived, so revising a plan under review
+		// does not silently discard what a teammate wrote.
+		const previous = existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+		const content = previous === undefined ? carryFeedback("", input.content) : carryFeedback(previous, input.content);
+		const nextBytes = Buffer.byteLength(content, "utf-8");
+		if (nextBytes > MAX_PLAN_BYTES) {
+			throw new Error(`The plan is too large with its review comments (${nextBytes} bytes).`);
+		}
+
+		writeAtomic(path, content);
+		return { path, relativePath: shortenPath(path), title, content, bytes: nextBytes };
 	};
 
 	const read = async (cwd: string, planPath: string): Promise<StoredPlan | undefined> => {
 		const base = baseOf(cwd);
 		const dir = await dirFor(base);
-		const resolved = resolve(base, planPath);
+		const resolved = resolvePlanArg(dir, planPath);
 		if (!isContainedPlan(dir, resolved) || !existsSync(resolved)) return undefined;
 		try {
 			const content = readFileSync(resolved, "utf-8");
 			return {
 				path: resolved,
-				relativePath: relativeTo(base, resolved),
+				relativePath: shortenPath(resolved),
 				content,
 				bytes: Buffer.byteLength(content, "utf-8"),
 			};
@@ -333,14 +425,27 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	};
 
 	/**
-	 * Write the browser review comments into an existing plan, replacing any
-	 * feedback already stored there. The file must already be a contained plan,
-	 * so this is the same path-safe write as `setSteps`.
+	 * Write the browser review comments into an existing plan, replacing the
+	 * comments of `options.author` (the owner when absent) and leaving every other
+	 * writer's in place. The file must already be a contained plan, so this is the
+	 * same path-safe write as `setSteps`.
 	 */
-	const saveFeedback = async (cwd: string, planPath: string, annotations: PlanAnnotation[]): Promise<StoredPlan> => {
+	const saveFeedback = async (
+		cwd: string,
+		planPath: string,
+		annotations: PlanAnnotation[],
+		options: { author?: string } = {},
+	): Promise<StoredPlan> => {
 		const plan = await read(cwd, planPath);
 		if (!plan) throw new Error("No plan file there; pass a plan_path written by write_plan.");
-		const content = formatFeedback(plan.content, annotations);
+		const author = normalizeAuthor(options.author);
+		// An untagged entry is the writer's own; one tagged with a different name is
+		// another writer's comment, so it is dropped rather than re-signed.
+		const own = annotations.filter((annotation) => {
+			const who = normalizeAuthor(annotation.author);
+			return who === "" || who === author;
+		});
+		const content = formatFeedback(plan.content, own, { author });
 		writeAtomic(plan.path, content);
 		return {
 			path: plan.path,
@@ -417,7 +522,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 			const summary: PlanSummary = {
 				path,
-				relativePath: relativeTo(base, path),
+				relativePath: shortenPath(path),
 				title: planTitle(name),
 				modified: info.mtimeMs,
 				bytes: info.size,
@@ -448,5 +553,5 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		return summaries;
 	};
 
-	return { dirFor, write, read, latest, index, setSteps, saveFeedback };
+	return { dirFor, write, read, latest, index, setSteps, saveFeedback, takeNotice };
 }

package/extensions/plan/policy.ts

@@ -14,26 +14,30 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createReadOnlyPolicy, type ReadOnlyPolicy } from "../../lib/policy.ts";
-import { ASK_USER_QUESTION_TOOL, GOAL_TOOL, SUBAGENT_TOOL, TODO_TOOL } from "../../lib/tool-names.ts";
+import { createReadOnlyPolicy, WORKSPACE_READERS, type ReadOnlyPolicy } from "../../lib/policy.ts";
+import {
+	ASK_USER_QUESTION_TOOL,
+	GOAL_TOOL,
+	SUBAGENT_TOOL,
+	TODO_TOOL,
+	WEB_FETCH_TOOL,
+	WEB_SEARCH_TOOL,
+} from "../../lib/tool-names.ts";
 import { ENTER_TOOL } from "./runtime.ts";
 
 /**
- * Tools that stay available while planning: structured readers, the trackers,
- * the git-only `bash`, and the known web/question readers. They are also the
- * tools the path backstop does not second-guess.
+ * Tools that stay available while planning: structured readers (documents
+ * included), the trackers, the git-only `bash`, and the known web/question
+ * readers. They are also the tools the path backstop does not second-guess.
  */
 export const PLAN_SAFE_TOOLS = [
-	"read",
-	"grep",
-	"find",
-	"ls",
+	...WORKSPACE_READERS,
 	TODO_TOOL,
 	GOAL_TOOL,
 	"bash",
 	ASK_USER_QUESTION_TOOL,
-	"web_search",
-	"web_fetch",
+	WEB_SEARCH_TOOL,
+	WEB_FETCH_TOOL,
 ];
 
 /**
@@ -43,7 +47,11 @@ export const PLAN_SAFE_TOOLS = [
  * deliberately absent — it is default-denied like any other shell.
  */
 export const PLAN_ALLOWED_TOOLS = [...PLAN_SAFE_TOOLS, SUBAGENT_TOOL];
-/** Tools always blocked while planning, even when annotated read-only. */
+/**
+ * Tools always blocked while planning, even when annotated read-only.
+ * `enter_plan_mode` is denied so it stays hidden while planning; the guard exempts
+ * plan's own registration so a call already in flight can still answer "already".
+ */
 const ALWAYS_BLOCKED_TOOLS = ["write", "edit", ENTER_TOOL];
 
 /** Shown when a tool call is refused while planning. */