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

package/extensions/memory/store.ts

@@ -180,6 +180,37 @@ export function applyUpdate(content: string, from: string, to: string): FileChan
 	return changed ? { content: lines.join("\n"), changed: true } : { content, changed: false };
 }
 
+/**
+ * Merge two notes into one: replace `first` in place with `merged` and drop
+ * `second`, so the pair becomes a single bullet where the first one stood. One
+ * transform, so the caller's write is atomic; a missing note or two identical
+ * names changes nothing.
+ */
+export function applyMerge(content: string, first: string, second: string, merged: string): FileChange {
+	if (first === second) return { content, changed: false };
+	const lines = content.split(/\r?\n/);
+	const notes = lines.map((line) => {
+		const match = BULLET_PARTS.exec(line);
+		return match ? sanitizeLine(match[2]) : undefined;
+	});
+	if (!notes.includes(first) || !notes.includes(second)) return { content, changed: false };
+
+	let changed = false;
+	const out: string[] = [];
+	for (const line of lines) {
+		const match = BULLET_PARTS.exec(line);
+		if (match && sanitizeLine(match[2]) === first) {
+			out.push(`${match[1]}${merged}${match[3]}`);
+			changed = true;
+			continue;
+		}
+		if (match && sanitizeLine(match[2]) === second) continue;
+		out.push(line);
+	}
+
+	return changed ? { content: endWithNewline(out.join("\n")), changed: true } : { content, changed: false };
+}
+
 /** Remove every note, keeping the header and any prose. */
 export function applyClear(content: string): FileChange {
 	let changed = false;

package/extensions/memory/tui.ts

@@ -7,6 +7,12 @@
  * without the component owning any authoritative state. Navigation and scroll
  * math come from `lib/tui/cursor.ts` and the screen chrome from `lib/tui/chrome.ts`;
  * the inline note editor is the shared `Editor` from `@earendil-works/pi-tui`.
+ *
+ * `m` marks one note as a merge source and `m` on a second note in the same
+ * scope opens the editor, pre-filled with both notes so the user writes the
+ * merged wording. The merge is one write: the store replaces the first note and
+ * drops the second. `p` moves the focused note to the other scope, which is two
+ * writes ordered target-first so a failure leaves a duplicate, never a loss.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
@@ -53,6 +59,10 @@ export interface MemoryPickerCallbacks {
 	add(scope: MemoryScope, text: string): Promise<{ changed: boolean; existing?: string }>;
 	update(scope: MemoryScope, from: string, to: string): Promise<boolean>;
 	forget(scope: MemoryScope, entry: string): Promise<boolean>;
+	/** Merge two notes in `scope` into one, in a single write. */
+	merge(scope: MemoryScope, first: string, second: string, merged: string): Promise<boolean>;
+	/** Move a note to the other scope: written there first, then removed here. */
+	move(from: MemoryScope, to: MemoryScope, entry: string): Promise<{ moved: boolean; existing?: string }>;
 }
 
 /** One note in the flat, filtered list. */
@@ -72,11 +82,15 @@ export class MemoryPickerComponent implements Component {
 	private readonly editor: Editor;
 
 	private filter: MemoryFilter = "all";
-	private mode: "list" | "edit" | "add" = "list";
+	private mode: "list" | "edit" | "add" | "merge" = "list";
 	/** Scope the inline editor writes to. */
 	private editorScope: MemoryScope = "project";
 	/** Note being edited, or undefined while adding. */
 	private editing: Note | undefined;
+	/** The two notes a merge editor will combine. */
+	private mergePair: { first: Note; second: Note } | undefined;
+	/** The note marked with `m`, awaiting a second `m` to merge into it. */
+	private mergeSource: Note | undefined;
 	/** Note awaiting a y/N forget confirmation. */
 	private confirm: Note | undefined;
 	/** Transient feedback shown in place of the hint. */
@@ -161,15 +175,55 @@ export class MemoryPickerComponent implements Component {
 		}
 		this.mode = "edit";
 		this.editing = note;
+		this.mergePair = undefined;
 		this.editorScope = note.scope;
 		this.editor.setText(note.text);
 		this.syncEditorFocus();
 		this.requestRender();
 	}
 
+	/**
+	 * `m`: mark the focused note, unmark it, or open the merge editor for a marked
+	 * pair. The mark survives navigation so the second note can be found.
+	 */
+	private toggleMerge(note: Note | undefined): void {
+		if (!note) return;
+		const source = this.mergeSource;
+		if (source && noteKey(source) === noteKey(note)) {
+			this.mergeSource = undefined;
+			this.requestRender();
+			return;
+		}
+		if (source) {
+			this.startMerge(source, note);
+			return;
+		}
+		this.mergeSource = note;
+		this.notice = undefined;
+		this.requestRender();
+	}
+
+	/** Open the editor for a marked pair, pre-filled with both notes to rewrite. */
+	private startMerge(first: Note, second: Note): void {
+		if (first.scope !== second.scope) {
+			this.notice = "A merge combines two notes in the same scope.";
+			this.requestRender();
+			return;
+		}
+		this.mode = "merge";
+		this.editing = undefined;
+		this.mergePair = { first, second };
+		this.editorScope = first.scope;
+		// The user writes the merged wording; the seed only saves retyping both notes.
+		this.editor.setText(`${first.text}; ${second.text}`.slice(0, MAX_NOTE_CHARS));
+		this.syncEditorFocus();
+		this.requestRender();
+	}
+
 	private startAdd(): void {
 		this.mode = "add";
 		this.editing = undefined;
+		this.mergePair = undefined;
 		this.editorScope = this.activeScope();
 		this.editor.setText("");
 		this.syncEditorFocus();
@@ -179,6 +233,8 @@ export class MemoryPickerComponent implements Component {
 	private cancelEditor(): void {
 		this.mode = "list";
 		this.editing = undefined;
+		this.mergePair = undefined;
+		this.mergeSource = undefined;
 		this.syncEditorFocus();
 		this.notice = undefined;
 		this.requestRender();
@@ -188,8 +244,11 @@ export class MemoryPickerComponent implements Component {
 		const text = sanitizeLine(value).trim();
 		const editing = this.editing;
 		const scope = this.editorScope;
+		const pair = this.mergePair;
 		this.mode = "list";
 		this.editing = undefined;
+		this.mergePair = undefined;
+		this.mergeSource = undefined;
 		this.syncEditorFocus();
 
 		if (text.length === 0) {
@@ -204,6 +263,12 @@ export class MemoryPickerComponent implements Component {
 		}
 
 		this.run(async () => {
+			if (pair) {
+				await this.callbacks.merge(pair.first.scope, pair.first.text, pair.second.text, text);
+				this.notice = `Merged 2 ${scopeLabel(pair.first.scope)} notes.`;
+				this.selectedKey = noteKey({ scope: pair.first.scope, text });
+				return;
+			}
 			if (editing) {
 				if (text === editing.text) {
 					this.notice = "Unchanged.";
@@ -236,6 +301,30 @@ export class MemoryPickerComponent implements Component {
 		});
 	}
 
+	/** `p`: move the focused note to the other scope, target first. */
+	private moveNote(note: Note | undefined): void {
+		if (!note) return;
+		const to: MemoryScope = note.scope === "project" ? "global" : "project";
+		if (to === "project" && !this.callbacks.trusted()) {
+			this.notice = "Project memory is unavailable for an untrusted project.";
+			this.requestRender();
+			return;
+		}
+		const from = note.scope;
+		const text = note.text;
+		this.run(async () => {
+			const result = await this.callbacks.move(from, to, text);
+			if (!result.moved) {
+				this.notice = `Added to ${scopeLabel(to)}; the ${scopeLabel(from)} note was already gone.`;
+			} else if (result.existing !== undefined) {
+				this.notice = `Moved to ${scopeLabel(to)} (it was already there).`;
+			} else {
+				this.notice = `Moved to ${scopeLabel(to)}.`;
+			}
+			this.selectedKey = noteKey({ scope: to, text });
+		});
+	}
+
 	private reload(): void {
 		this.notice = this.callbacks.refresh() ? "Reloaded memory." : "Memory is already up to date.";
 		this.requestRender();
@@ -248,11 +337,21 @@ export class MemoryPickerComponent implements Component {
 			.catch((error: unknown) => {
 				this.notice = `Memory not saved: ${messageOf(error)}`;
 			})
-			.then(() => this.requestRender());
+			.then(() => {
+				this.dropStaleMergeSource();
+				this.requestRender();
+			});
+	}
+
+	/** A merge source that a mutation removed is no longer a valid target. */
+	private dropStaleMergeSource(): void {
+		const source = this.mergeSource;
+		if (!source) return;
+		if (!this.notes().some((note) => noteKey(note) === noteKey(source))) this.mergeSource = undefined;
 	}
 
 	private syncEditorFocus(): void {
-		this.editor.focused = this.componentFocused && (this.mode === "edit" || this.mode === "add");
+		this.editor.focused = this.componentFocused && this.mode !== "list";
 	}
 
 	private handleConfirm(data: string): void {
@@ -270,7 +369,7 @@ export class MemoryPickerComponent implements Component {
 	}
 
 	handleInput(data: string): void {
-		if (this.mode === "edit" || this.mode === "add") {
+		if (this.mode !== "list") {
 			if (isCloseKey(data) || matchesKey(data, Key.escape)) {
 				this.cancelEditor();
 				return;
@@ -284,6 +383,12 @@ export class MemoryPickerComponent implements Component {
 			return;
 		}
 		if (isCloseKey(data) || data === "q") {
+			// With a mark set, the first Esc cancels the merge instead of closing the screen.
+			if (this.mergeSource) {
+				this.mergeSource = undefined;
+				this.requestRender();
+				return;
+			}
 			this.onClose();
 			return;
 		}
@@ -308,6 +413,8 @@ export class MemoryPickerComponent implements Component {
 		if (matchesKey(data, Key.tab) || data === "s") this.cycleFilter();
 		else if (matchesKey(data, Key.enter) || data === "e") this.startEdit(focused);
 		else if (data === "a") this.startAdd();
+		else if (data === "m") this.toggleMerge(focused);
+		else if (data === "p") this.moveNote(focused);
 		else if (data === "d") {
 			if (!focused) return;
 			this.confirm = focused;
@@ -355,9 +462,11 @@ export class MemoryPickerComponent implements Component {
 	/** One note row: selection marker, scope tag, and the sanitized note text. */
 	private noteRow(note: Note, selected: boolean, width: number): string {
 		const tag = `${paint(this.theme, "meta", scopeLabel(note.scope))} ${paint(this.theme, "faint", "·")}`;
+		const source = this.mergeSource;
+		const marked = source !== undefined && noteKey(source) === noteKey(note);
 		return listRow(this.theme, width, {
 			selected,
-			leading: tag,
+			leading: marked ? `${tag} ${paint(this.theme, "warn", "merge")}` : tag,
 			label: sanitizeLine(note.text),
 			labelRole: selected ? "accent" : "label",
 		});
@@ -372,17 +481,20 @@ export class MemoryPickerComponent implements Component {
 	}
 
 	private renderEditor(width: number): string[] {
-		const verb = this.mode === "edit" ? "Edit" : "Add";
+		const verb = this.mode === "edit" ? "Edit" : this.mode === "merge" ? "Merge" : "Add";
 		const scope = scopeLabel(this.editorScope);
 		const pad = width > 1 ? " " : "";
+		const summary =
+			this.mode === "edit"
+				? "Editing the focused note"
+				: this.mode === "merge"
+					? `Merging 2 ${scope} notes into one`
+					: `New ${scope} note`;
 		const body: string[] = [];
 		for (const line of this.editor.render(Math.max(1, width - 2))) body.push(`${pad}${line}`);
 		return dockListFrame({
 			header: titleRule(this.theme, width, `Memory · ${verb} ${scope}`),
-			summary: clip(
-				`  ${paint(this.theme, "meta", this.mode === "edit" ? "Editing the focused note" : `New ${scope} note`)}`,
-				width,
-			),
+			summary: clip(`  ${paint(this.theme, "meta", summary)}`, width),
 			body,
 			hint: screenHint(this.theme, width, ["Enter save", "Esc cancel"]),
 		});
@@ -391,7 +503,7 @@ export class MemoryPickerComponent implements Component {
 	render(width: number): string[] {
 		const w = Math.max(1, width);
 		this.syncEditorFocus();
-		if (this.mode === "edit" || this.mode === "add") return this.renderEditor(w);
+		if (this.mode !== "list") return this.renderEditor(w);
 
 		const notes = this.notes();
 		this.cursor.visible = fitRows(this.viewportRowsSource, notes.length, CHROME, SCREEN_DEFAULT_ROWS);
@@ -411,7 +523,19 @@ export class MemoryPickerComponent implements Component {
 			? clip(`  ${paint(this.theme, "warn", this.confirmPrompt())}`, w)
 			: this.notice !== undefined
 				? clip(`  ${paint(this.theme, "meta", this.notice)}`, w)
-				: screenHint(this.theme, w, ["Esc close", "Enter/e edit", "a add", "d forget", "s/Tab scope", "↑/↓", "g/G"]);
+				: this.mergeSource
+					? screenHint(this.theme, w, ["m merge into the focused note", "Esc cancel merge", "↑/↓"])
+					: screenHint(this.theme, w, [
+							"Esc close",
+							"Enter/e edit",
+							"a add",
+							"d forget",
+							"m merge",
+							"p move",
+							"s/Tab scope",
+							"↑/↓",
+							"g/G",
+						]);
 
 		return dockListFrame({
 			header: titleRule(this.theme, w, "Memory"),

package/extensions/plan/README.md

@@ -42,19 +42,28 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   `<repo-root>/.pi/plans/<YYYY-MM-DD-HHmm>-<slug>.md` (or `<agent-dir>/plans`
   outside a repository). The plans directory is self-ignoring, so plan files
   never show up as untracked files or in `rewind` snapshots.
+- **A discoverable index.** `/plan list` walks the plans directory and shows
+  every plan with its title, modified time, and step progress, newest first — in
+  the TUI as a docked list where `Enter` opens the plan's review, elsewhere as a
+  notice with each plan's path. The directory stays the index: no registry file,
+  one bounded read per plan.
 - **A shape that reads.** `write_plan` documents a canonical outline — a
   `# <Title>`, then `## Goal`, `## Context`, `## Approach`, `## Steps`,
   `## Risks`, and `## Verification` — and the model is guided to follow it. This
   is guidance only: any markdown is accepted, stored, and rendered as written.
 - **Trackable steps.** Steps are written as `- [ ]` checkboxes in the `## Steps`
-  section; approval seeds them into `todo`.
+  section; approval seeds them into `todo`, with the `## Verification` section as
+  the last item so the definition of done travels with the work. A plan with more
+  than 50 top-level steps is refused rather than truncated, so approval never
+  drops a step you reviewed.
 - **A navigable review.** The review screen splits the body at its headings,
   names the section you are in, and jumps between sections with `n`/`p`.
 - **What changed since the last review.** After a refinement, the review screen
   names how many sections changed, marks the current one in the scroll row, and
   the browser outline dots each changed section, so a re-review does not mean
-  re-reading the whole plan. The baseline is what the previous review in this
-  session showed; a resumed session starts without markers.
+  re-reading the whole plan. The baseline is one digest per heading section of
+  what the previous review showed, kept as a session entry, so a resumed session
+  or a `/tree` restore marks only what changed on its own branch.
 - **Kept current.** After approval, `set_plan_steps` flips the checkboxes of
   the steps you name in the file, so the plan mirrors what has actually been
   done. Pass the step's text as `expected` and an update whose step number moved
@@ -83,19 +92,28 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   nested sub-bullets are treated as notes. The list is a merge, not a
   replacement: existing items keep their place and status, a step whose text is
   already there is skipped, and the tool's item cap defers the rest instead of
-  dropping anything. A plan without a `Steps` heading keeps the older rule — the
-  shallowest list in the document — so prose bullets in a plan that follows the
-  outline never become todos.
-- **Branch-aware.** The enabled flag is a custom session entry, so `/resume` and
-  `/tree` restore the right mode.
+  dropping anything. The plan's `## Verification` section follows as the **last**
+  todo item, summarized on one line (`Verify: …`) — it is not a plan step, so it is
+  ticked in the todo list rather than with `set_plan_steps`, and it never counts
+  against the 50-step cap. A plan without a `Steps` heading keeps the older rule —
+  the shallowest list in the document — so prose bullets in a plan that follows the
+  outline never become todos, and its verification bullets are already covered.
+- **Goal-aware.** While planning, the injected context restates an active
+  session goal as one bullet, so the plan is designed against the objective
+  instead of beside it. On approval, when the session has no goal at all, the user
+  is offered one confirm to record the plan's title as the goal — never replacing
+  an existing goal, and with no extra model call.
+- **Branch-aware.** The enabled flag and the review baseline are custom session
+  entries, so `/resume` and `/tree` restore the right mode and keep the
+  changed-section markers.
 
 ## Tools
 
 | Tool | Active | Purpose |
 |---|---|---|
 | `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
-| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. |
-| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
+| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. A plan with more than 50 top-level steps in its `Steps` section is refused, with the cap and the fix named, and nothing is written. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. Refuses a file whose step list is over the cap, before the review screen. |
 | `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and optionally `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. |
 
 ### Commands and flags
@@ -105,6 +123,7 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 | `enter_plan_mode` tool | the model, before a non-trivial task | `ctx.ui.confirm` |
 | `/plan` | the user | immediate |
 | `/plan <prompt>` | the user, with the task | immediate |
+| `/plan list` | the user, browsing the plans directory | immediate |
 | `/plan review [path]` | the user, reviewing a plan in the browser | immediate |
 | `Ctrl+Alt+P` | the user | immediate |
 | `--plan` | the user, at launch | immediate |
@@ -143,7 +162,7 @@ actions (`a approve & run` in `success`, `r refine` in `accent`).
 mounted and opens an inline editor beneath it (`Enter` submits, an empty buffer
 does nothing, `Esc` returns to the plan); `Esc` keeps planning and tells the
 model the plan was not approved. When the plan changed since the previous review
-in this session, a summary line under the title names how many sections changed
+on this branch, a summary line under the title names how many sections changed
 and the scroll row appends `· changed` to the current section. Scroll with `↑`/`↓` or `j`/`k`, `space`/`b` or
 `PgUp`/`PgDn`, `d`/`u`, `g`/`G`, and the mouse wheel. Press `n`/`p` to jump to
 the next or previous heading; the scroll row names the current section when the
@@ -321,7 +340,7 @@ file and returns them to the model.
   links, an active-section highlight, and a per-section comment count; the panel
   above it reports the `Steps` section's progress (`n/m`, the same list approval
   seeds) and total comments. A
-  section that changed since the previous review in this session carries a dot
+  section that changed since the previous review on this branch carries a dot
   (its `title` and accessible label say so); an unchanged plan shows none.
 - **Inline threads.** A comment renders directly under the block it anchors to,
   labelled and indented as a thread, so it reads in place and the plan keeps one
@@ -386,14 +405,15 @@ file and returns them to the model.
   Git Bash (`bash`), which must be installed for any shell command to run.
 - The read-only guarantee is a guard rail against accidental writes, not a
   security boundary (see [Security](#security)).
-- The plans directory is the only index; there is no registry and no persisted
-  plan metadata.
-- Changed markers need a prior review of the same plan in the same session. A
-  resumed or new session has no baseline, so it shows no markers rather than
-  marking the whole plan as changed.
-- Approval tracks at most 50 steps, and a step longer than 200 characters is
-  shortened in the todo list and the approval listing. `write_plan` reports both
-  cases when they apply; the plan file itself always keeps the full text.
+- The plans directory is the only index. `/plan list` walks it on every open and
+  keeps no registry, so it sees an external edit or a hand-copied plan
+  immediately; it lists a file over the 256 KiB plan limit without reading it,
+  and does not index the agent directory's plans while a worktree is active.
+- Approval tracks at most 50 steps: `write_plan` refuses a larger plan, and
+  `exit_plan_mode` refuses to present one, so no reviewed step is silently
+  dropped. A step longer than 200 characters is shortened in the todo list and
+  the approval listing — a display rule only, because the plan file always keeps
+  the full text.
 - Browser review needs a local browser: the server is loopback-only, so a remote
   turn cannot drive it.
 - A browser that never connects leaves the review waiting until the user
@@ -415,9 +435,9 @@ file and returns them to the model.
 | Integration point | How |
 |---|---|
 | Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
-| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
-| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })` and rebuilt from `ctx.sessionManager.getBranch()`; the last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. The content each review showed is kept in runtime memory (keyed by resolved path) for the changed markers. |
-| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
+| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
+| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan never writes a goal itself: an approval offer records one through `ctx.executeTool("goal", { objective })`. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
+| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with an active session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
 
 ## Design notes
@@ -456,12 +476,21 @@ file and returns them to the model.
   channel; no import from that extension) and the steps are merged into them.
   A rejected seed reports the nested tool's own reason in the approval message
   instead of failing silently.
+- **A cap is enforced where it can still be fixed.** Both refusal points —
+  `write_plan` and `exit_plan_mode` — sit before the write and before the review,
+  because those are the moments the model can still regroup the steps. A note on
+  a successful write would arrive after the file existed and the review had
+  already listed every step, which is exactly when the overflow becomes lost
+  work.
 - **Changed markers compare what was shown, not revisions on disk.** A review
-  result is only meaningful next to the text the reviewer already read, so the
-  runtime keeps the content each review presented (keyed by resolved path) and
-  `changedSections` diffs section title and text against it. Stored feedback is
+  result is only meaningful next to the text the reviewer already read, so every
+  review marks the sections it presented (keyed by resolved path) and
+  `plan-text.ts` compares the next plan against those digests. Stored feedback is
   stripped from both sides, so a review comment never reads as an edit, and the
-  same helper feeds the terminal summary and the browser outline.
+  same helper feeds the terminal summary and the browser outline. The digests are
+  a session entry rather than the previous text, so the markers survive a resume
+  without copying the plan file into the branch, and the reader and the writer
+  share one normalization so a tab cannot read as a change.
 - **The outline guides, it does not enforce.** `write_plan` documents the
   canonical shape in its description and stores whatever markdown it is given;
   no section is required and nothing is rewritten. That keeps the model free to
@@ -514,12 +543,14 @@ file and returns them to the model.
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
 | `plans.ts` | Plan-file store: slug/stamp naming, directory resolution, containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
-| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the section diff, and the checkbox edit. |
-| `runtime.ts` | Enabled state, tool gating, persistence, control-tool identity, footer status, the review baseline. |
+| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, and the checkbox edit. |
+| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`. |
+| `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
 | `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`: schemas, results, transcripts, and the approval-time todo seed. |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
 | `commands.ts` | `/plan` (enter, optional task) and the `/plan review [path]` browser subcommand. |
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, approve/refine/browser/keep). |
+| `plan-index.ts` | `/plan list`: the notice text and the docked index screen (title, step progress, age, focused path; Enter reviews). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks). |
 | `feedback.ts` | Browser-comment codec: `stripFeedback`, `parseFeedback`, `formatFeedback`, `feedbackSummary`, and payload validation. |
 | `web.ts` | `createPlanWebReview`: the loopback server, the section outline (with changed-section flags) and code highlighting, and the save/approve/cancel/abort session. |

package/extensions/plan/commands.ts

@@ -2,22 +2,26 @@
  * Slash command for the plan-mode extension.
  *
  * `/plan` toggles plan mode, or enters it and sends an optional task;
- * `Ctrl+Alt+P` toggles too. `/plan review [path]` is the one reserved
- * subcommand: it opens the plan in the browser, and when the user saves their
- * comments sends them to the model as a refinement request.
+ * `Ctrl+Alt+P` toggles too. Two subcommands are reserved: `/plan review [path]`
+ * opens a plan in the browser (and sends saved comments to the model as a
+ * refinement), and `/plan list` shows the plans directory, newest first, with
+ * Enter opening a review.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isRemoteTurn } from "../../lib/interaction.ts";
 import { feedbackSummary } from "./feedback.ts";
+import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
 import { READ_ONLY_SUMMARY } from "./policy.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";
 
 const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
 const REVIEW_PREFIX = "review";
+const LIST_PREFIX = "list";
 
 /** Notice text for the current mode; shared by `/plan` and the `Ctrl+Alt+P` shortcut. */
 export function planModeNotice(enabled: boolean): string {
@@ -30,6 +34,14 @@ function reviewTarget(args: string): string | undefined {
 	return target === "" ? undefined : target;
 }
 
+/**
+ * Whether a command line is the reserved `list` subcommand. Exact match only, so
+ * `list the untracked files` stays a task instead of silently listing plans.
+ */
+function isListSubcommand(prompt: string): boolean {
+	return prompt.toLowerCase() === LIST_PREFIX;
+}
+
 /**
  * Whether a command line is the reserved `review` subcommand. Bare `review`
  * always is; a path after it is, but `review the auth flow` stays a task, so a
@@ -68,10 +80,10 @@ async function reviewInBrowser(
 		return;
 	}
 
-	const previous = runtime.reviewed(file.path);
+	const baseline = runtime.reviewed(file.path);
 	const result = await runBrowserReview(web, ctx.cwd, file, {
 		canApprove: false,
-		previous,
+		baseline,
 		// Mark only once the page is actually open: a failed start must not consume
 		// the baseline for a plan nobody saw.
 		onOpened: (session) => {
@@ -100,6 +112,47 @@ async function reviewInBrowser(
 	else await pi.sendUserMessage(message, { deliverAs: "followUp" });
 }
 
+/**
+ * `/plan list`: show the plans directory, newest first. The TUI gets a docked
+ * list whose Enter opens the focused plan's review; every other mode gets the
+ * same facts as a notice, with each plan's path.
+ */
+async function openPlanIndex(
+	pi: ExtensionAPI,
+	runtime: PlanRuntime,
+	web: PlanWebReview,
+	ctx: ExtensionContext,
+): Promise<void> {
+	const dir = await runtime.plans.dirFor(ctx.cwd);
+	const summarise = async (): Promise<Awaited<ReturnType<typeof runtime.plans.index>>> => runtime.plans.index(ctx.cwd);
+	const summaries = await summarise();
+
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(formatPlanIndex(summaries, dir), "info");
+		return;
+	}
+
+	// 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;
+	});
+	if (selected) await reviewInBrowser(pi, runtime, web, selected.path, ctx);
+}
+
 export function registerCommands(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
@@ -107,16 +160,22 @@ export function registerCommands(
 ): void {
 	pi.registerCommand("plan", {
 		description:
-			"Toggle plan mode (read-only exploration), enter it with an optional task, or review a plan in the browser",
+			"Toggle plan mode (read-only exploration), enter it with an optional task, list saved plans, or review one in the browser",
 		getArgumentCompletions: (prefix) => {
 			const text = prefix.trimStart();
 			if (text.includes(" ")) return null;
-			return REVIEW_PREFIX.startsWith(text) ? [{ value: REVIEW_PREFIX, label: REVIEW_PREFIX }] : null;
+			const subcommands = [LIST_PREFIX, REVIEW_PREFIX].filter((name) => name.startsWith(text));
+			return subcommands.length > 0 ? subcommands.map((value) => ({ value, label: value })) : null;
 		},
 		handler: async (args, ctx) => {
 			const prompt = args.trim();
 
-			// `/plan review [path]` is a reserved subcommand; everything else is a task.
+			// `/plan list` and `/plan review [path]` are reserved subcommands;
+			// everything else is a task.
+			if (isListSubcommand(prompt)) {
+				await openPlanIndex(pi, runtime, web, ctx);
+				return;
+			}
 			if (isReviewSubcommand(prompt)) {
 				await reviewInBrowser(pi, runtime, web, reviewTarget(prompt), ctx);
 				return;