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

package/extensions/goal/tools.ts

@@ -10,6 +10,7 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { GOAL_TOOL } from "../../lib/tool-names.ts";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { paint } from "../../lib/tui/tokens.ts";
@@ -52,17 +53,11 @@ function toStructuredContent(details: GoalDetails): Record<string, JsonValue> {
  */
 function goalResult(details: GoalDetails, options: { error?: string; openTodos?: number } = {}) {
 	const { error, openTodos = 0 } = options;
-	return {
-		content: [
-			{
-				type: "text" as const,
-				text: error === undefined ? formatGoalText(details.goal, openTodos) : `Error: ${error}`,
-			},
-		],
-		details,
-		structuredContent: toStructuredContent(details),
-		...(error === undefined ? {} : { isError: true as const }),
-	};
+	const text = error === undefined ? formatGoalText(details.goal, openTodos) : `Error: ${error}`;
+	const structuredContent = toStructuredContent(details);
+	return error === undefined
+		? textResult(text, details, structuredContent)
+		: failedResult(text, details, structuredContent);
 }
 
 export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {

package/extensions/job/index.ts

@@ -14,7 +14,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { JOB_FINISHED_CHANNEL, type JobFinishedEvent } from "../../lib/events.ts";
 import { noticeMessage, type NoticeMessage } from "../../lib/notice.ts";
-import { createPendingReporter } from "../../lib/report.ts";
+import { createPendingReporter, registerPendingChannel } from "../../lib/report.ts";
 import { registerCommands } from "./commands.ts";
 import { formatCompletion, jobOutcome, shortLabel } from "./format.ts";
 import { createJobsRuntime, type JobsRuntime } from "./runtime.ts";
@@ -80,51 +80,26 @@ export default function jobs(pi: ExtensionAPI, deps: JobsDeps = {}): void {
 	registerTools(pi, runtime);
 	registerCommands(pi, runtime);
 
-	pi.on("session_start", (_event, ctx) => {
-		reporter.sessionStart();
-		runtime.load(ctx);
+	registerPendingChannel(pi, {
+		reporter,
+		runtime,
 		// `shutdown` clears these; a reload or session replacement reuses the
 		// runtime, so re-arm them on every session start.
-		runtime.onFinish = () => reporter.report();
-		// Notify-listening extensions follow completions on the shared bus; the
-		// runtime only knows the callback, never the channel.
-		runtime.onComplete = (job) => {
-			try {
-				pi.events.emit(JOB_FINISHED_CHANNEL, toFinishedEvent(job));
-			} catch {
-				// The event bus is optional.
-			}
-		};
-	});
-
-	// Tree navigation does not change the process table; only repaint.
-	pi.on("session_tree", (_event, ctx) => {
-		runtime.setStatus(ctx);
-	});
-
-	pi.on("agent_start", () => {
-		reporter.agentStart();
-	});
-	pi.on("agent_settled", () => {
-		reporter.agentSettled();
-	});
-
-	// Report completions to the model at the start of the next turn.
-	pi.on("before_agent_start", (_event, ctx) => {
-		const reported = reporter.beforeAgentStart();
-		if (!reported) return undefined;
-		runtime.setStatus(ctx);
-		return reported;
-	});
-
-	// Keep stale completion notices out of later turns. Only this extension's
-	// notices are pruned; another source's are left for its own handler.
-	pi.on("context", (event) => reporter.filterContext(event.messages));
-
-	// `shutdown` detaches the UI controller, which clears both chips.
-	pi.on("session_shutdown", async () => {
-		runtime.onFinish = undefined;
-		runtime.onComplete = undefined;
-		await runtime.shutdown();
+		onSessionStart: () => {
+			runtime.onFinish = () => reporter.report();
+			// Notify-listening extensions follow completions on the shared bus; the
+			// runtime only knows the callback, never the channel.
+			runtime.onComplete = (job) => {
+				try {
+					pi.events.emit(JOB_FINISHED_CHANNEL, toFinishedEvent(job));
+				} catch {
+					// The event bus is optional.
+				}
+			};
+		},
+		onSessionShutdown: () => {
+			runtime.onFinish = undefined;
+			runtime.onComplete = undefined;
+		},
 	});
 }

package/extensions/job/tools.ts

@@ -9,7 +9,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { errorResult } from "../../lib/tool-result.ts";
+import { errorResult, textResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { callLine, detailsOrLine, elapsedSuffix, rejectionLine, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { SEPARATORS } from "../../lib/tui/glyphs.ts";
@@ -77,46 +77,40 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 							},
 							ctx,
 						);
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text: `Started ${job.id} (pid ${job.pid ?? "?"}): ${job.command}\nPoll with \`job status ${job.id}\`, or \`job wait ${job.id}\`.`,
-								},
-							],
-							details: { action: "start", job: toRecord(job) } satisfies JobDetails,
-						};
+						return textResult(
+							`Started ${job.id} (pid ${job.pid ?? "?"}): ${job.command}\nPoll with \`job status ${job.id}\`, or \`job wait ${job.id}\`.`,
+							{ action: "start", job: toRecord(job) } satisfies JobDetails,
+						);
 					}
 
 					case "list": {
 						const jobs = runtime.list();
-						return {
-							content: [{ type: "text" as const, text: formatJobList(jobs, Date.now(), runtime.sessionId) }],
-							details: { action: "list", jobs, sessionId: runtime.sessionId } satisfies JobDetails,
-						};
+						return textResult(formatJobList(jobs, Date.now(), runtime.sessionId), {
+							action: "list",
+							jobs,
+							sessionId: runtime.sessionId,
+						} satisfies JobDetails);
 					}
 
 					case "status": {
 						const job = runtime.get(call.id);
 						if (!job) return errorResult("status", `no job "${call.id}".`);
-						return {
-							content: [{ type: "text" as const, text: formatJobStatus(job, Date.now(), runtime.sessionId) }],
-							details: { action: "status", job: toRecord(job), sessionId: runtime.sessionId } satisfies JobDetails,
-						};
+						return textResult(formatJobStatus(job, Date.now(), runtime.sessionId), {
+							action: "status",
+							job: toRecord(job),
+							sessionId: runtime.sessionId,
+						} satisfies JobDetails);
 					}
 
 					case "logs": {
 						const result = runtime.logs(call.id, call.lines);
 						if (!result) return errorResult("logs", `no job "${call.id}".`);
-						return {
-							content: [{ type: "text" as const, text: result.text }],
-							details: {
-								action: "logs",
-								job: toRecord(result.job),
-								logs: result.lines.join("\n"),
-								truncated: result.truncated,
-							} satisfies JobDetails,
-						};
+						return textResult(result.text, {
+							action: "logs",
+							job: toRecord(result.job),
+							logs: result.lines.join("\n"),
+							truncated: result.truncated,
+						} satisfies JobDetails);
 					}
 
 					case "send": {
@@ -132,15 +126,12 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 										result.closed ? " and closed its stdin" : ""
 									}.`
 								: `Closed ${job.id}'s stdin.`;
-						return {
-							content: [{ type: "text" as const, text }],
-							details: {
-								action: "send",
-								job: toRecord(job),
-								sent: result.sent,
-								stdinClosed: result.closed,
-							} satisfies JobDetails,
-						};
+						return textResult(text, {
+							action: "send",
+							job: toRecord(job),
+							sent: result.sent,
+							stdinClosed: result.closed,
+						} satisfies JobDetails);
 					}
 
 					case "kill": {
@@ -149,30 +140,27 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 						const job = runtime.kill(call.id, call.signal);
 						if (!job) return errorResult("kill", `no job "${call.id}".`);
 						const wasRunning = before.status === "running";
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text: wasRunning
-										? `Sent ${call.signal ?? "SIGTERM"} to ${job.id} (${job.label}).`
-										: `${job.id} already ${job.status}; nothing to kill.`,
-								},
-							],
-							details: {
+						return textResult(
+							wasRunning
+								? `Sent ${call.signal ?? "SIGTERM"} to ${job.id} (${job.label}).`
+								: `${job.id} already ${job.status}; nothing to kill.`,
+							{
 								action: "kill",
 								job: toRecord(job),
 								signalled: wasRunning,
 								signal: call.signal ?? "SIGTERM",
 							} satisfies JobDetails,
-						};
+						);
 					}
 
 					case "wait": {
 						const result = await runtime.wait(call.id, call.timeoutMs, signal, () =>
-							onUpdate?.({
-								content: [{ type: "text" as const, text: `Waiting on ${call.id}…` }],
-								details: { action: "wait", job: runtime.get(call.id) } satisfies JobDetails,
-							}),
+							onUpdate?.(
+								textResult(`Waiting on ${call.id}…`, {
+									action: "wait",
+									job: runtime.get(call.id),
+								} satisfies JobDetails),
+							),
 						);
 						if (!result) return errorResult("wait", `no job "${call.id}".`);
 						const { job, timedOut, cancelled } = result;
@@ -181,37 +169,23 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 							: timedOut
 								? " (still running after the timeout)"
 								: "";
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text: `${formatCompletion(job)}${note}${job.lastLine ? `\nlast: ${job.lastLine}` : ""}`,
-								},
-							],
-							details: {
-								action: "wait",
-								job: toRecord(job),
-								timedOut,
-								cancelled,
-							} satisfies JobDetails,
-						};
+						return textResult(`${formatCompletion(job)}${note}${job.lastLine ? `\nlast: ${job.lastLine}` : ""}`, {
+							action: "wait",
+							job: toRecord(job),
+							timedOut,
+							cancelled,
+						} satisfies JobDetails);
 					}
 
 					case "clear": {
 						const result = runtime.clear(call.id, call.all ?? false);
 						if (result.refused) return errorResult("clear", result.refused);
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text:
-										result.cleared === 0
-											? "Nothing to clear."
-											: `Cleared ${result.cleared} job${result.cleared === 1 ? "" : "s"}.`,
-								},
-							],
-							details: { action: "clear", cleared: result.cleared, jobs: runtime.list() } satisfies JobDetails,
-						};
+						return textResult(
+							result.cleared === 0
+								? "Nothing to clear."
+								: `Cleared ${result.cleared} job${result.cleared === 1 ? "" : "s"}.`,
+							{ action: "clear", cleared: result.cleared, jobs: runtime.list() } satisfies JobDetails,
+						);
 					}
 				}
 			} catch (error) {

package/extensions/memory/tools.ts

@@ -11,6 +11,7 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { messageOf } from "./errors.ts";
 import { formatCallText, formatResultText, scopeLabel } from "./format.ts";
@@ -49,12 +50,9 @@ function toStructuredContent(details: MemoryDetails): Record<string, JsonValue>
  */
 function memoryResult(details: MemoryDetails, error?: string) {
 	const full: MemoryDetails = error === undefined ? details : { ...details, error };
-	return {
-		content: [{ type: "text" as const, text: formatResultText(full) }],
-		details: full,
-		structuredContent: toStructuredContent(full),
-		...(error === undefined ? {} : { isError: true as const }),
-	};
+	const text = formatResultText(full);
+	const structuredContent = toStructuredContent(full);
+	return error === undefined ? textResult(text, full, structuredContent) : failedResult(text, full, structuredContent);
 }
 
 export function registerTools(pi: ExtensionAPI, runtime: MemoryRuntime): void {

package/extensions/memory/tui.ts

@@ -43,7 +43,7 @@ const MAX_NOTE_CHARS = 500;
 /** Rows the screen shows when the terminal height is unknown. */
 const SCREEN_DEFAULT_ROWS = 14;
 
-/** Fixed rows around the list: header, summary, blank, blank, hint, blank. */
+/** Fixed rows around the list: header, summary, blank, blank, hint, closing rule. */
 const CHROME = 6;
 
 /** Which scopes the list shows. */
@@ -482,6 +482,8 @@ export class MemoryPickerComponent implements Component {
 		const body: string[] = [];
 		for (const line of this.editor.render(Math.max(1, width - 2))) body.push(`${pad}${line}`);
 		return dockListFrame({
+			theme: this.theme,
+			width,
 			header: titleRule(this.theme, width, `Memory · ${verb} ${scope}`),
 			summary: clip(`  ${paint(this.theme, "meta", summary)}`, width),
 			body,
@@ -528,6 +530,8 @@ export class MemoryPickerComponent implements Component {
 						]);
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, "Memory"),
 			summary: this.summary(w),
 			body,

package/extensions/plan/README.md

@@ -45,18 +45,35 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   empty repositories, and falls back to evidence with recorded assumptions when
   the interview is unavailable or cancelled; it never invents commands.
 - **Plan files.** The model saves the plan with `write_plan`; the file lands in
-  `<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.
+  `<repo-root>/.pi/plans/<YYYY-MM-DD-HHmm>-<slug>.md` — the entered worktree's
+  root when one is active — 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.
+  `# <Title>`, then `## Goal`, `## Context`, `## Approach`, `## Visual`,
+  `## Steps`, `## Risks`, and `## Verification` — and the model is guided to
+  follow it. Every example in the template is the shape wanted rather than a
+  description of it, and each section has one job: the goal is one sentence, the
+  context is the facts that force the approach, the approach names the
+  alternative it rejected, and verification is a fence of the commands to run.
+  `Visual` carries the end state in an untagged fence, with one line naming what to
+  look at: the same surface before and after when the change alters one that
+  already exists, one frame when the surface is new, because a reviewer judges the
+  result before the steps that build it; a change with no visible surface drops it.
+  The description calls the shape a guide rather than a form: `Context`,
+  `Approach`, `Visual`, and `Risks` are dropped when they have nothing to say,
+  while `Steps` and `Verification` are kept, because the steps are read from that
+  section (without it, the shallowest list anywhere becomes the steps) and
+  Verification becomes the last todo item. Within `Steps` only the shallowest
+  list is tracked, so nested bullets stay notes instead of becoming todos. This
+  is guidance only: any markdown is accepted, stored, and rendered as written,
+  and a refinement is asked to keep its section headings so the review can still
+  mark only what changed.
 - **Trackable steps.** Steps are written as `- [ ]` checkboxes in the `## Steps`
   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
@@ -76,7 +93,9 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   widget and the plan do not drift apart. Pass the step's text as `expected` and
   an update whose step number moved is refused instead of ticking the wrong line.
 - **Reviewable plan.** `exit_plan_mode` reads the plan file back and presents
-  it for approval. The user approves, keeps planning, or asks for a refinement.
+  it for approval. The user approves, keeps planning, asks for a refinement, or
+  exits plan mode without approving; the last keeps the plan file for a later
+  review and records no todo items or goal.
   On a remote turn (WeChat) the plan file is sent first, then a digest of its
   title, step count, and first steps, then the choices, so the review is still
   answerable when the attachment is not opened. The choices include **Send the
@@ -100,9 +119,10 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   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. 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 —
+  todo item, summarized on one line (`Verify: …`) — a fenced block contributes its
+  commands, not its fence lines. 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.
   Each seeded item is matched back to its step by text, so ticking a step with
@@ -113,8 +133,9 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   (`planning`) is finalized from the plan's own `## Goal` section — falling back
   to the title — through the `goal` tool, with no extra dialog, because approving
   the plan *is* the decision. A session with no goal at all gets one confirm to
-  record the same objective, and an `active` or `achieved` goal is never
-  rewritten: a final objective is the user's. No path spends a model turn.
+  record the same objective, unless `plan.goalPrompt` is off, which records it
+  without asking. An `active` or `achieved` goal is never rewritten: a final
+  objective is the user's. No path spends a model turn.
 - **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.
@@ -125,7 +146,8 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 |---|---|---|
 | `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. 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. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. The review also offers **Exit plan mode (discard)**, which leaves plan mode without approving. Refuses a file whose step list is over the cap, before the review screen. |
+| `cancel_plan_mode` | plan mode | Leave plan mode without a plan file or a review. Restores write access; records no todo items or goal; keeps any saved plan. Empty schema. |
 | `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 `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. The todo item approval seeded from a step is ticked with it: the file is written first and is authoritative, a renamed item is left alone, and a failed todo write is reported in the result. |
 
 ### Commands and flags
@@ -137,6 +159,7 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 | `/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 |
+| `/plan cancel` | the user, leaving plan mode without approving | immediate |
 | `/skill:init` | the user, creating or updating `AGENTS.md` | enters plan mode; write waits for plan approval |
 | `Ctrl+Alt+P` | the user | immediate |
 | `--plan` | the user, at launch | immediate |
@@ -204,7 +227,7 @@ package, so load the whole package (`pi -e .`) or install it; loading only
 ## Behaviour by mode
 
 The review screen is TUI-only. `exit_plan_mode` opens `PlanViewComponent`: a
-scrollable, width-safe view of the plan with approve/refine/keep in the footer.
+scrollable, width-safe view of the plan with approve/refine/keep/exit in the footer.
 The body is rendered with Pi's own `Markdown` component and `getMarkdownTheme()`,
 so headings, lists, inline code, code blocks, links, and quotes carry the active
 theme's colors; task items get the shared `◼` (done) or `◻` (pending) marker,
@@ -213,7 +236,11 @@ actions (`a approve & run` in `success`, `r refine` in `accent`).
 `a` ends plan mode, restores write access, and seeds `todo`; `r` keeps the plan
 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
+model the plan was not approved; `x` leaves plan mode without approving and
+keeps the plan file. The dialog path offers the same five outcomes, including
+**Exit plan mode (discard)**. Dismissing the dialog (or a timeout) is also an
+exit, not a silent `keep`; only the explicit **Keep planning** option stays in
+plan mode. When the plan changed since the previous review
 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
@@ -225,12 +252,12 @@ from the design system's `gaugeBar` and stays
 visible while the refine editor is open, since the body above is still clipped.
 Hints are
 dropped whole as the terminal narrows, and each footer leads with its safe exit
-(`Esc keep planning` in the review, `Esc back to plan` in the inline editor) so
+(`Esc keep plan` in the review, `Esc back to plan` in the inline editor) so
 the exit survives even when only one hint fits.
 
-Dialog-capable non-TUI modes (RPC) show the same three choices as a select menu
+Dialog-capable non-TUI modes (RPC) show the same five choices as a select menu
 plus the refine editor; cancelling the editor returns to the select instead of
-being reported as "not approved". A WeChat turn takes the same dialog path and
+being reported as "not approved". Dismissing the plan select is an exit. A WeChat turn takes the same dialog path and
 is answered over WeChat, even though the session is in TUI mode: the choice
 comes from `askHuman(ctx, { custom, dialogs, file, body })` in
 `lib/interaction.ts`, not from `ctx.mode`. A remote turn also receives the plan
@@ -276,6 +303,16 @@ exit_plan_mode submitted a plan
 … 12 more lines (ctrl+o to expand)
 ```
 
+## Configuration
+
+The `plan` section of the shared `bytefly.json` (global then project), or the
+**Offer the session goal** row in `/bytefly settings`. It is read when a plan is
+approved, so a change applies to the next approval without a reload.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `goalPrompt` | `true` | Ask before recording an approved plan's objective as the session goal; `false` records it without asking. |
+
 ## Security
 
 Plan mode is a **guard rail, not a sandbox**: extensions run with Pi's OS
@@ -409,18 +446,28 @@ file and returns them to the model.
 - **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
   measure at every width. There is no separate column to reflow.
+- **Nothing typed is lost.** **Save feedback**, **Approve & run**, and **Back to
+  Pi** refuse while a composer holds text and put the cursor back in it, and a
+  deleted comment is offered back in the header for a few seconds. The page keeps
+  no draft of its own — these are the three ways an open comment could disappear.
+- **Prints as a document.** Printing uses the light palette whatever the screen
+  shows, drops the header, panel, rail, and progress bar, and lets the comments
+  stay with the blocks they belong to.
 - **Keyboard first.** `j`/`k` move to the next or previous block, `c` comments
   on the current block, `a` approves (the approval flow only), `s` saves, `Esc`
   closes the composer or the sheet and then the review, and `?` opens a shortcut
-  sheet; the header's `?` button opens the same sheet.
+  sheet; the header's `?` button opens the same sheet. Either dialog traps
+  `Tab` and hands focus back to whatever opened it.
 - **Decision in place.** A review opened for approval (`w` on the review screen)
   shows **Approve & run** beside Save feedback: it persists the current comments,
   ends plan mode, restores write access, seeds `todo`, and hands control back to
-  the model. **Save feedback** keeps plan mode and returns the comments as a
-  refinement; **Back to Pi** closes the review with no decision. Each action
-  settles the page on a terminal state — `Approved`, `Saved`, or `Closed` — so
-  the tab never falls to Offline. `/plan review` is comment-only: it renders no
-  approve action and the server refuses one.
+  the model. Because that cannot be undone from the page, the button and `a`
+  open a confirmation that says what happens and starts on **Cancel**; only its
+  own **Approve & run** posts. **Save feedback** keeps plan mode and returns the
+  comments as a refinement; **Back to Pi** closes the review with no decision.
+  Each action settles the page on a terminal state — `Approved`, `Saved`, or
+  `Closed` — so the tab never falls to Offline. `/plan review` is comment-only:
+  it renders no approve action and the server refuses one.
 - **Markdown that reads.** Headings, lists, task items, blockquotes, fenced
   code, GFM tables, `---` rules, and bare-URL autolinks render; a list item's
   continuation lines hang under the item's text, inline code is a soft fill
@@ -441,9 +488,10 @@ file and returns them to the model.
   page rendered and answers `409`; the page then offers a **Reload** action,
   because only a reload can re-anchor the comments to the new text.
 - **Back to the model.** A save from the review screen returns `refined: true`
-  with the comments, so the model stays in plan mode and revises the same file.
-  `/plan review` sends them as a user message (a plan-mode revision or a plain
-  update, depending on the mode).
+  with the comments, so the model stays in plan mode and revises the same file. A
+  save that carries no comments asks for nothing, so the review screen comes back
+  instead. `/plan review` sends them as a user message (a plan-mode revision or a
+  plain 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`, `HEAD`, and `POST`, and caps the request body. A save or cancel
@@ -503,7 +551,7 @@ file and returns them to the model.
 |---|---|
 | 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), `/skill:init` (skill-backed `AGENTS.md` bootstrap), `--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 writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is offered one, and an `active`/`achieved` goal is left alone. 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. |
+| 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 writes a goal only at approval, through `ctx.executeTool("goal", { objective })`: a `planning` goal is promoted to the plan's `## Goal`, a session with none is offered one unless `plan.goalPrompt` is off, and an `active`/`achieved` goal is left alone. 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. |
 | Entry requests | `pi.events` channel `PLAN_ENTER_REQUEST` from `lib/plan-entry.ts`: the `goal` workflow asks, with the shared consent sentence, and plan enables the mode on the caller's context without a second dialog. Subscribed on `session_start`, released on `session_shutdown`. |
 | Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with a pursued 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. |
@@ -577,8 +625,12 @@ file and returns them to the model.
   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
-  adapt the document while making the common case consistent and scannable.
+  no section is required and nothing is rewritten. The description names the two
+  headings that do carry behavior — `Steps` is what approval reads as steps, and
+  `Verification` the trailing check — so the model is told the cost of dropping
+  one instead of having the plan refused. The review's baseline is keyed by
+  heading text, so a refinement is asked to keep its headings; a rename reads as
+  an edit, which is the one change the markers cannot tell from a rewrite.
 - **Sections are rendered one at a time.** Pi's `Markdown` exposes no
   source-line map, so `tui.ts` splits the body at its headings and renders each
   section separately. That gives exact offsets for the current-section label and
@@ -623,9 +675,10 @@ file and returns them to the model.
 |---|---|
 | `index.ts` | Wiring: tools, command, flag, shortcut, events, context injection. |
 | `types.ts` | `PlanModeEntry`, `EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`. |
+| `config.ts` | The `plan` section loader: `goalPrompt`, default on. |
 | `policy.ts` | Plan mode's read-only policy, the shared prompt summary, and the bash-refusal guidance. |
 | `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`. |
+| `plans.ts` | Plan-file store: slug/stamp naming, directory resolution (repository, active worktree, or agent directory), 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 plan's own goal (`goalSection`), and the checkbox edit. |
 | `format.ts` | Pure result/approval text: the plan preview, the step-cap diagnosis, step labels, the merge summary, and the verification note. |
@@ -641,8 +694,10 @@ file and returns them to the model.
 | `feedback.ts` | Browser-comment codec: `stripFeedback`, `parseFeedback`, `formatFeedback`, `feedbackSummary`, and payload validation. |
 | `web.ts` | `createPlanWebReview`: the review session (SSE close detection, the body cap, settle-after-flush, abort) over the shared loopback bind, writer, and close. |
 | `web-router.ts` | Pure request handler: token/`Host`/method checks and the review routes, over the shared page and JSON header sets. |
-| `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet), its data island, and inline CSS. |
-| `web-client.ts` | The `/client.js` source (block/thread rendering, the comment rail, outline and facts, inline comments, selection quotes, tables, highlighted code, keyboard nav, save/approve/back). |
+| `web-page.ts` | The review page shell (header, reading progress, review facts, section outline, shortcut sheet, approve confirmation), its data island, and inline CSS. |
+| `web-client.ts` | The `/client.js` source: state and wiring (comment rail, comments, selection quotes, save/approve/back, keyboard nav) over the two fragments below. |
+| `web-markdown.ts` | The client's document half: `safeHref` and the inline/table/code/list rendering (interpolated into `web-client.ts`). |
+| `web-chrome.ts` | The client's chrome half: the state chip, the status line, the header, reading progress, and the stream's lifetime (interpolated into `web-client.ts`). |
 | `path-guard.ts` | Recursive path-argument detection for the read-only backstop. |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform default-browser opener (shared with `file-browse`). |
 | [`../../lib/plan-entry.ts`](../../lib/plan-entry.ts) | Plan-mode entry shared with `goal`: the read-only summary, the consent sentence, and the `pi.events` request `plan` answers by enabling the mode. |