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

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
@@ -174,6 +193,10 @@ instead of opening a server nobody can use. The browser's **Approve & run** is
 offered only for the review `exit_plan_mode` opens, since only that flow owns
 leaving plan mode; `/plan review` stays comment-only.
 
+Aborting the turn closes a browser review. `exit_plan_mode` forwards the call's
+abort signal to the review server, so an aborted turn returns "not approved"
+and stops listening instead of waiting on a page nobody is watching.
+
 ### Transcript
 
 The three tool rows reuse the transcript component, and `exit_plan_mode`
@@ -227,8 +250,11 @@ command. The read-only guarantee is layered:
   transcript and in non-TUI notices; a plan file cannot drive the terminal.
 - **Loopback browser review.** The review server binds `127.0.0.1` and requires a
   random per-session token in the URL, rejects a missing or foreign `Host`
-  header, serves only `GET`/`POST`, and caps the request body; the page renders plan and comment text
-  with DOM text nodes, never `innerHTML`, so a plan cannot script the reviewer.
+  header, serves only `GET`, `HEAD`, and `POST`, and caps the request body; the
+  page renders plan and comment text with DOM text nodes, never `innerHTML`, so a
+  plan cannot script the reviewer. The page also refuses to be framed
+  (`frame-ancestors 'none'` and `X-Frame-Options: DENY`), so a local page cannot
+  clickjack **Approve & run**.
 
 ## Read-only git shell
 
@@ -314,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
@@ -356,12 +382,13 @@ file and returns them to the model.
   update, depending on the mode).
 - **Loopback and tokenized.** The server binds `127.0.0.1`, carries a random
   per-session token in the URL, rejects a missing or foreign `Host` header,
-  serves only `GET` and `POST`, and caps the request body. A save or cancel
+  serves only `GET`, `HEAD`, and `POST`, and caps the request body. A save or cancel
   resolves the session only after its HTTP response is delivered, so the browser
   never sees a false "Failed to fetch". The last bound port is remembered per
   plan, so reviewing the same plan again reuses the origin (and the browser's
-  saved theme with it). It is closed on save, cancel, tab close, or
-  `session_shutdown`.
+  saved theme with it). It is closed on save, cancel, a dropped event stream, or
+  `session_shutdown`; a reload reconnects inside that grace, so refreshing or
+  reloading a conflicted page does not end the review.
 
 | Route | Result |
 |---|---|
@@ -378,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
@@ -406,14 +434,21 @@ 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`); 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. |
+| 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 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
 
+- **One review loop owns the human gate.** `review.ts` asks however the session
+  is attached — TUI screen, dialog plus editor, remote file plus digest, or
+  browser — and returns one `ReviewDecision`, so `exit_plan_mode` and
+  `/plan review` no longer carry two copies of the browser lifecycle and the
+  tool's own `for(;;)` with a `continue` per outcome. The loop also owns the
+  baseline rule (mark what the screen showed, after it showed it) and forwards
+  the call's abort signal, which is what closes a review on an aborted turn.
 - **Two tools, not one.** `EnterPlanMode`/`ExitPlanMode` are a pair: entering is
   consent to explore read-only, exiting is consent to act. A single toggle tool
   cannot express "the model wants to plan but the user declines".
@@ -441,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
@@ -499,11 +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. |
-| `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`. |
+| `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/blocks.ts

@@ -14,7 +14,7 @@
  * step.
  */
 
-import { normalizeHeadingText } from "./steps.ts";
+import { FENCE, HEADING } from "./steps.ts";
 
 /** How a block is rendered and grouped. */
 export type PlanBlockKind = "heading" | "paragraph" | "list" | "code" | "quote" | "table" | "hr" | "blank";
@@ -30,10 +30,6 @@ export interface PlanBlock {
 	lines: string[];
 }
 
-/** ATX heading outside a fence. */
-const HEADING = /^ {0,3}#{1,6}(?:\s|$)/;
-/** Code-fence opener or closer (backticks or tildes). */
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 /** A list marker with its leading indentation and trailing gap. */
 const LIST_ITEM = /^( *)([-*+]|\d+[.)])(\s+)/;
 /** A blockquote line. */
@@ -190,36 +186,6 @@ export function blockAt(blocks: PlanBlock[], line: number): PlanBlock | undefine
 	return candidate;
 }
 
-/** A heading in a plan, for the review page's section outline. */
-export interface PlanHeading {
-	/** 0-based source line of the heading. */
-	line: number;
-	/** Heading level, 1-6. */
-	level: number;
-	/** Heading text with inline markdown removed. */
-	text: string;
-}
-
-/** ATX heading with its captured level and raw text. */
-const HEADING_PARTS = /^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
-
-/** Strip the inline markdown an outline label should not show. */
-function headingText(raw: string): string {
-	return normalizeHeadingText(raw);
-}
-
-/** The plan's headings in order, for the outline. */
-export function planHeadings(blocks: PlanBlock[]): PlanHeading[] {
-	const headings: PlanHeading[] = [];
-	for (const block of blocks) {
-		if (block.kind !== "heading") continue;
-		const match = block.lines[0]?.match(HEADING_PARTS);
-		if (!match) continue;
-		headings.push({ line: block.start, level: match[1].length, text: headingText(match[2]) });
-	}
-	return headings;
-}
-
 /** 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();