@gavin-hu/my-pi-agent 0.9.0 → 0.10.0

package/extensions/goal/tui.ts

@@ -1,20 +1,16 @@
 /**
  * Terminal rendering for the goal.
  *
- * Two surfaces share one vocabulary. `goalWidgetLines` renders the persistent
- * above-editor widget as a single label-first rail line (`Goal · active ·
- * <objective>`, dimmed once achieved), matching the `todo` and `jobs` widgets.
- * `goalRailLines` renders the transcript result as a header (`Goal · active`)
- * plus the objective wrapped and led by the status glyph, with continuation rows
- * aligned under the text; it matches the todo transcript result's indent + glyph
- * grammar so the two read as a pair.
- * `GoalResult` wraps `goalRailLines` uncapped for the transcript.
+ * Two surfaces share one vocabulary. The persistent above-editor widget is a
+ * single label-first rail line (`Goal · active · <objective>`, dimmed once
+ * achieved), matching the `todo` and `jobs` widgets. The transcript result is
+ * the status header alone (`Goal · active`): the call line already names the
+ * objective, so the result only states the new status.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
-import { BODY_INDENT, GLYPH_GAP } from "../../lib/tui/glyphs.ts";
-import { goalGlyph, goalHeader, goalLine } from "./format.ts";
+import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { goalHeader, goalLine } from "./format.ts";
 import type { AchievedStyle, Goal } from "./types.ts";
 
 /** Widget key used with `ctx.ui.setWidget()`. */
@@ -25,27 +21,6 @@ export interface GoalWidgetOptions {
 	achieved?: AchievedStyle;
 }
 
-/**
- * Rows for the transcript goal rail: the themed header plus `body` wrapped and
- * led by the status glyph. Continuation rows are padded to the text column.
- */
-export function goalRailLines(goal: Goal, body: string, theme: Theme, width: number): string[] {
-	const w = Math.max(1, width);
-	const glyph = goalGlyph(goal, theme);
-	const glyphWidth = visibleWidth(glyph);
-	const textColumn = BODY_INDENT + glyphWidth + GLYPH_GAP;
-	const inner = Math.max(1, w - textColumn);
-
-	const wrapped = wrapTextWithAnsi(body, inner);
-	const pad = " ".repeat(BODY_INDENT);
-	const continuation = " ".repeat(textColumn);
-	const lines = [goalHeader(goal, theme)];
-	wrapped.forEach((line, index) => {
-		lines.push(index === 0 ? `${pad}${glyph}${" ".repeat(GLYPH_GAP)}${line}` : `${continuation}${line}`);
-	});
-	return lines.map((line) => truncateToWidth(line, w, "…"));
-}
-
 /** Rows for the goal widget: a single rail line, or nothing when hidden. */
 export function goalWidgetLines(goal: Goal, theme: Theme, width: number, options: GoalWidgetOptions = {}): string[] {
 	const w = Math.max(1, width);
@@ -68,30 +43,27 @@ export class GoalWidget implements Component {
 	}
 }
 
-/** Transcript result block: the rail, uncapped, with the themed body. */
+/** Transcript result block: the status header, separated from the call line. */
 export class GoalResult implements Component {
 	private goal: Goal;
-	private body: string;
 	private theme: Theme;
 
-	constructor(goal: Goal, body: string, theme: Theme) {
+	constructor(goal: Goal, theme: Theme) {
 		this.goal = goal;
-		this.body = body;
 		this.theme = theme;
 	}
 
 	/** Update in place so the transcript can reuse this component across renders. */
-	update(goal: Goal, body: string, theme: Theme): void {
+	update(goal: Goal, theme: Theme): void {
 		this.goal = goal;
-		this.body = body;
 		this.theme = theme;
 	}
 
 	invalidate(): void {}
 
 	render(width: number): string[] {
-		// The leading blank line separates the rail from the call header, matching
+		// The leading blank line separates the header from the call line, matching
 		// the built-ins' header/output gap.
-		return ["", ...goalRailLines(this.goal, this.body, this.theme, Math.max(1, width))];
+		return ["", truncateToWidth(goalHeader(this.goal, this.theme), Math.max(1, width), "…")];
 	}
 }

package/extensions/job/README.md

@@ -5,12 +5,20 @@ the background and manage them without blocking the turn. A job starts
 immediately and keeps running across tool calls; poll it, tail its output, wait
 for it, or kill it.
 
+<img src="../../assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%">
+
 ```
 pi --extension ./extensions/job    # load just this extension
 pi -e .                            # load the whole @gavin-hu/my-pi-agent package
 pi install ./                      # install the package
 ```
 
+## Tool rendering
+
+How the `job` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/job.png" alt="The job tool's result: the call line and an indented body with a finished and a failed job row, each with its status glyph and elapsed time" width="100%">
+
 ## What it does
 
 - Registers one model-callable tool, `job`, with actions `start`, `list`,
@@ -81,7 +89,7 @@ JobDetails {
 ### Transcript
 
 The call line names the action and its target. The result is themed and reuses
-the slot's component: `list` draws the same row rail as `/jobs`, `logs` draws a
+the slot's component: `list` draws the same rows as `/jobs`, `logs` draws a
 blank line and the sanitized tail, and a single-job action draws one outcome
 line. A `kill` that sent a signal appends it (`· SIGTERM sent`) instead of
 showing the job's pre-kill running state, a `start` badges `detached` and
@@ -89,7 +97,6 @@ showing the job's pre-kill running state, a `start` badges `detached` and
 
 ```
 job list
-
   ▸ j1  tests                            3.2s
   ✗ j2  build                            0.4s
 ```
@@ -199,8 +206,8 @@ rewritten.
 | Execution mode | `sequential` — actions share the in-memory job table. |
 | Annotations | `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true` — plan mode blocks it. |
 | `outputSchema` / `structuredContent` | None. Results return `JobDetails` in tool-result `details` only. |
-| State storage | One durable registry file per session, `~/.pi/agent/jobs/<projectKey>/registry-<sessionHash>.json` (keyed by the session cwd, so entering a worktree does not move it), merged from every session file on load; a dead session's records are adopted and a legacy shared `registry.json` is migrated once. Ids are reserved with an atomic `O_EXCL` `<id>.lock` before `start`, and a POSIX job's exit code is written to a per-job `.status` file. Tool results carry `JobDetails`; unreported completions arrive as hidden `job-context` messages at `before_agent_start`. |
-| Lifecycle | `session_start` loads and reconciles the registry and arms `onFinish` and `onComplete`; `session_shutdown` kills session-owned jobs and clears both status chips. `session_tree` repaints; `agent_start`/`agent_settled` track busy; `context` prunes stale `job-context` messages. |
+| State storage | One durable registry file per session, `~/.pi/agent/jobs/<projectKey>/registry-<sessionHash>.json` (keyed by the session cwd, so entering a worktree does not move it), merged from every session file on load; a dead session's records are adopted and a legacy shared `registry.json` is migrated once. Ids are reserved with an atomic `O_EXCL` `<id>.lock` before `start`, and a POSIX job's exit code is written to a per-job `.status` file. Tool results carry `JobDetails`; unreported completions arrive as a shared transcript notice (`my-pi-agent/notice`) at `before_agent_start`. |
+| Lifecycle | `session_start` loads and reconciles the registry and arms `onFinish` and `onComplete`; `session_shutdown` kills session-owned jobs and clears both status chips. `session_tree` repaints; `agent_start`/`agent_settled` track busy; `context` prunes stale notices of its own source. |
 | Event bus | Each job that reaches a terminal state is published on `my-pi-agent/job-finished` (`lib/events.ts`) with its id, label, status, exit code, and signal, from the one `settle` path every transition goes through. bytefly's notify capability subscribes there instead of importing this extension. |
 
 ## Design notes
@@ -248,11 +255,11 @@ rewritten.
   settles it (recovering an exit code from the status file, else `unknown`)
   when the pid disappears.
 - **Notify by default, wake opt-in.** A failed job raises one `ctx.ui.notify`
-  (a clean exit is left to the list and chips). Finished jobs are also injected
-  as a hidden `job-context` message at the next `before_agent_start`. A
-  `wake: true` job (or `wakeOnFinish`) additionally triggers one turn when the
-  agent is idle; auto-wake is not the default because it easily loops and burns
-  tokens.
+  (a clean exit is left to the list and chips). Finished jobs are also posted
+  as a shared transcript notice — model-facing text plus the notice block — at the
+  next `before_agent_start`. A `wake: true` job (or `wakeOnFinish`) additionally
+  triggers one turn when the agent is idle; auto-wake is not the default because
+  it easily loops and burns tokens.
 - **Width-1 glyphs and cached latest line.** The running chip is `▸ N` and the
   failure chip `✗ N`, each a two-token badge under its own status key, so the
   status bar compacts each independently (`▸N` / `✗N`) and an unreported
@@ -264,8 +271,10 @@ rewritten.
   spawn/liveness/kill/clock functions, so the whole suite runs without
   launching a process.
 - **The transcript reuses the `/jobs` grammar.** `job list` renders the same
-  `jobRow` rail as the screen (running first, capped, `… N more`), `job logs`
-  draws a themed tail with a `… N earlier lines` note, and single-job actions
+  `jobRow` rows as the screen (running first, capped, `… N more`), minus the
+  selection-marker column (`listRow`'s `marker: false`), which only the
+  interactive screen needs; `job logs` draws a themed tail with a `… N earlier
+  lines` note, and single-job actions
   draw one `formatJobOutcomeLine` (plus a signal note on `kill` and
   `detached`/`wake` badges on `start`). A capped collapsed result ends with the
   `app.tools.expand` hint, and an expanded list shows every job. The renderers
@@ -292,7 +301,7 @@ rewritten.
 | `ui.ts` | Footer status chips, over the shared `lib/tui/status-controller.ts`. |
 | `waiters.ts` | `wait` resolver bookkeeping. |
 | `runtime.ts` | Composition: job table, handles, process events, repaint clock. |
-| `tui.ts` | The `/jobs` screen and the transcript `JobResult` rail, drawn from the `lib/tui/` kit (`titleRule`, `listRow`, `emptyState`, `IdCursor`, `LinePane`). |
+| `tui.ts` | The `/jobs` screen and the transcript `JobResult` rows, drawn from the `lib/tui/` kit (`titleRule`, `listRow`, `emptyState`, `IdCursor`, `LinePane`). |
 | `tools.ts` | The `job` tool and its transcript rendering. |
 | `commands.ts` | The `/jobs` command. |
 | `types.ts` | Shared types. |

package/extensions/job/format.ts

@@ -14,7 +14,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { JobRecord, JobStatus } from "./types.ts";
 
@@ -251,7 +251,7 @@ export function jobOutcome(job: JobRecord): string {
 
 /** One-line outcome for a single job, themed for the transcript result. */
 export function formatJobOutcomeLine(job: JobRecord, theme: Theme, now = Date.now()): string {
-	const sep = paint(theme, "faint", " · ");
+	const sep = paint(theme, "faint", SEPARATORS.item);
 	const outcome =
 		job.status === "failed" ? paint(theme, "bad", jobOutcome(job)) : paint(theme, "faint", jobOutcome(job));
 	return (

package/extensions/job/index.ts

@@ -4,18 +4,19 @@
  * Registers the `job` tool and `/jobs` command. Jobs run as detached shell
  * processes with their output streamed to log files; the status chip shows
  * running and unreported-failure counts, and finished jobs are reported to the
- * model at the next turn (or, for `wake` jobs, by triggering one turn).
+ * model — and shown as a bytefly notice — at the next turn, or by triggering one
+ * turn for a `wake` job.
  *
  * Load with:  pi --extension ./extensions/job
  */
 
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
 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, pruneStaleNotices } from "../../lib/notice.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { registerCommands } from "./commands.ts";
-import { formatCompletion } from "./format.ts";
+import { formatCompletion, jobOutcome, shortLabel } from "./format.ts";
 import { createJobsRuntime, type JobsRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 import type { Job, JobRecord } from "./types.ts";
@@ -23,16 +24,26 @@ import type { Job, JobRecord } from "./types.ts";
 /** Marker embedded in the injected completion context. */
 const JOB_CONTEXT_MARKER = "[BACKGROUND JOBS]";
 
-/** Custom-entry type used for the injected completion message. */
-export const JOB_CONTEXT_TYPE = "job-context";
-
 function buildContext(jobs: JobRecord[]): string {
 	const lines = jobs.map((job) => formatCompletion(job));
 	return `${JOB_CONTEXT_MARKER}\n${jobs.length} background job${jobs.length === 1 ? "" : "s"} finished:\n${lines.join("\n")}\nRun \`job logs <id>\` for output.`;
 }
 
-function isJobContext(message: AgentMessage): boolean {
-	return (message as AgentMessage & { customType?: string }).customType === JOB_CONTEXT_TYPE;
+/** The shared notice for pending completions: model text plus renderer details. */
+function jobNotice(jobs: JobRecord[]): NoticeMessage {
+	const count = jobs.length;
+	return noticeMessage({
+		content: buildContext(jobs),
+		details: {
+			source: "job",
+			title: `${count} background job${count === 1 ? "" : "s"} finished`,
+			items: jobs.map((job) => ({
+				label: `${job.id} ${shortLabel(job)}`,
+				detail: jobOutcome(job),
+				severity: job.status === "failed" ? "bad" : job.status === "exited" ? "ok" : "warn",
+			})),
+		},
+	});
 }
 
 /** Trim a finished record to the fields the event bus carries. */
@@ -67,10 +78,7 @@ export default function jobs(pi: ExtensionAPI, deps: JobsDeps = {}): void {
 		const pending = runtime.pendingCompletions();
 		if (pending.length === 0) return;
 		try {
-			pi.sendMessage(
-				{ customType: JOB_CONTEXT_TYPE, content: buildContext(pending), display: false },
-				{ triggerTurn: true },
-			);
+			pi.sendMessage(jobNotice(pending), { triggerTurn: true });
 			// Mark only once the send succeeded; a throw leaves them for the next turn.
 			runtime.markReported(pending.map((job) => job.id));
 		} catch {
@@ -113,17 +121,14 @@ export default function jobs(pi: ExtensionAPI, deps: JobsDeps = {}): void {
 		if (pending.length === 0) return undefined;
 		runtime.markReported(pending.map((job) => job.id));
 		runtime.setStatus(ctx);
-		return {
-			message: { customType: JOB_CONTEXT_TYPE, content: buildContext(pending), display: false },
-		};
+		return { message: jobNotice(pending) };
 	});
 
-	// Keep stale completion notes out of later turns.
+	// 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) => {
-		const contexts = event.messages.filter(isJobContext);
-		if (contexts.length <= 1) return undefined;
-		const last = contexts[contexts.length - 1];
-		return { messages: event.messages.filter((message) => !isJobContext(message) || message === last) };
+		const pruned = pruneStaleNotices(event.messages, "job");
+		return pruned ? { messages: pruned } : undefined;
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {

package/extensions/job/tools.ts

@@ -10,6 +10,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
 	compareJobs,
@@ -209,8 +210,9 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 			const text = reuseText(context.lastComponent);
 			text.setText(
 				theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) +
-					theme.fg(
-						"muted",
+					paint(
+						theme,
+						"meta",
 						sanitizeLine(formatCallText(action, args as Record<string, unknown>, context.argsComplete)),
 					),
 			);
@@ -282,7 +284,7 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 					const badges: string[] = [];
 					if (details.job.detached) badges.push("detached");
 					if (details.job.wake) badges.push("wake");
-					if (badges.length > 0) line += paint(theme, "faint", ` · ${badges.join(" · ")}`);
+					if (badges.length > 0) line += paint(theme, "faint", `${SEPARATORS.item}${badges.join(SEPARATORS.item)}`);
 				}
 				text.setText(line);
 				return text;

package/extensions/job/tui.ts

@@ -21,7 +21,7 @@ import { clip, fitCells } from "../../lib/tui/columns.ts";
 import { fitRows, formatRange, IdCursor, isCloseKey, navIntent, wheelDelta } from "../../lib/tui/cursor.ts";
 import { expandHint, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { LinePane } from "../../lib/tui/line-pane.ts";
-import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { emptyState, statusRow, type StatusRow } from "../../lib/tui/rows.ts";
 import { titleRule } from "../../lib/tui/rules.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
@@ -51,15 +51,19 @@ const LOG_CHROME_ROWS = 6;
 const jobId = (job: JobRecord): string => job.id;
 
 /** One job row: selection marker, status glyph, id, label, and a right-aligned
- *  elapsed value. `listRow` owns the clipping and the alignment. */
-function jobRow(job: JobRecord, theme: Theme, width: number, selected = false): string {
-	return listRow(theme, width, {
-		selected,
+ *  elapsed value. `statusRow` owns the clipping and the alignment. */
+function jobRow(
+	job: JobRecord,
+	theme: Theme,
+	width: number,
+	options: Pick<StatusRow, "selected" | "marker"> = {},
+): string {
+	return statusRow(theme, width, {
+		...options,
 		glyph: statusGlyphChar(job.status),
 		glyphRole: statusRole(job.status),
 		label: `${job.id}  ${shortLabel(job)}`,
 		trailing: formatDuration(elapsedMs(job, Date.now())),
-		trailingRole: "faint",
 	});
 }
 
@@ -95,7 +99,7 @@ export class JobResult implements Component {
 		// A leading blank line separates the result from the call header.
 		const lines: string[] = [""];
 		if (this.input.kind === "list") {
-			for (const job of this.input.jobs) lines.push(jobRow(job, this.theme, w));
+			for (const job of this.input.jobs) lines.push(jobRow(job, this.theme, w, { marker: false }));
 			if (this.input.more > 0) {
 				const note = `${paint(this.theme, "faint", `… ${this.input.more} more`)} ${expandHint(this.theme)}`;
 				lines.push(clip(`  ${note}`, w));
@@ -350,7 +354,8 @@ export class JobListComponent implements Component {
 			body.push(...emptyState(this.theme, w, { label: "No background jobs." }));
 		} else {
 			const end = Math.min(jobs.length, this.cursor.scroll + this.cursor.visible);
-			for (let i = this.cursor.scroll; i < end; i++) body.push(jobRow(jobs[i], this.theme, w, i === index));
+			for (let i = this.cursor.scroll; i < end; i++)
+				body.push(jobRow(jobs[i], this.theme, w, { selected: i === index }));
 			if (this.cursor.scroll > 0 || end < jobs.length) {
 				range = formatRange(this.theme, w, { start: this.cursor.scroll, end, total: jobs.length });
 			}

package/extensions/memory/README.md

@@ -13,6 +13,12 @@ pi -e .                               # load the whole @gavin-hu/my-pi-agent pac
 pi install ./                         # install the package
 ```
 
+## Tool rendering
+
+How the `memory` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/memory.png" alt="The memory tool's result: the call line and an indented body confirming the write and the new project and global counts" width="100%">
+
 ## What it does
 
 - Registers one model-callable tool, `memory`, with four actions: `add` a note,

package/extensions/memory/format.ts

@@ -78,7 +78,9 @@ export function formatResultText(details: MemoryDetails, expanded = false): stri
 			].join("\n");
 		case "add":
 			if (details.changed) {
-				return `Added to ${scopeLabel(details.scope)} memory: ${details.entry ?? ""}\nNow ${countLine(entries)}.`;
+				// The call line already names the note, so the result confirms the write
+				// and the new counts rather than repeating it.
+				return `Added to ${scopeLabel(details.scope)} memory\nNow ${countLine(entries)}.`;
 			}
 			if (details.existing !== undefined && details.existing !== details.entry) {
 				return `Already in ${scopeLabel(details.scope)} memory (near-duplicate): ${details.existing}`;
@@ -86,10 +88,10 @@ export function formatResultText(details: MemoryDetails, expanded = false): stri
 			return `Already in ${scopeLabel(details.scope)} memory: ${details.existing ?? details.entry ?? ""}`;
 		case "update":
 			return details.changed
-				? `Updated ${scopeLabel(details.scope)} memory: ${details.entry ?? ""} → ${details.to ?? ""}\nNow ${countLine(entries)}.`
+				? `Updated ${scopeLabel(details.scope)} memory\nNow ${countLine(entries)}.`
 				: `Already set in ${scopeLabel(details.scope)} memory: ${details.entry ?? ""}`;
 		case "forget":
-			return `Removed from ${scopeLabel(details.scope)} memory: ${details.entry ?? ""}\nNow ${countLine(entries)}.`;
+			return `Removed from ${scopeLabel(details.scope)} memory\nNow ${countLine(entries)}.`;
 	}
 }
 

package/extensions/plan/README.md

@@ -12,6 +12,14 @@ pi -e .                            # load the whole @gavin-hu/my-pi-agent packag
 pi --plan                          # start in plan mode
 ```
 
+## Tool rendering
+
+How the `write_plan` and `exit_plan_mode` calls and their results look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/write_plan.png" alt="The write_plan tool's call and result: the call line and an indented body with the saved plan path and byte count" width="100%">
+
+<img src="../../assets/tools/exit_plan_mode.png" alt="The exit_plan_mode tool's call and result: the call line and an indented body with the approval line and the approved plan preview" width="100%">
+
 ## What it does
 
 - **Read-only gating, with one exception.** Tools that are not read-only are
@@ -142,7 +150,9 @@ the user.
 
 Browser review is a local-turn feature: the server binds `127.0.0.1`, so a remote
 (WeChat) turn cannot reach it and `/plan review` there refuses with a notice
-instead of opening a server nobody can use.
+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.
 
 ### Transcript
 
@@ -254,15 +264,15 @@ agent file that overrides it.
 
 ## Browser review
 
-<img src="../../assets/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title and Save/Close, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail and an inline review thread" width="100%">
+<img src="../../assets/plan-review.png" alt="The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail and an inline review thread" width="100%">
 
 Press `w` on the review screen — or run `/plan review [path]` — to open the plan
 in the default browser on `127.0.0.1`. The page is a reading-first review
 surface: a sticky header carrying the plan's H1 (falling back to the file-name
 slug), a live status chip (connection, comment count, and unsaved changes), the
-theme toggle, and Save/Close, over a hairline reading-progress bar. A sticky
-side panel shows the plan's step progress and comment count above a **section
-outline**, and the document is GitHub's Markdown content column — one centred
+theme toggle, and the review actions, over a hairline reading-progress bar. A
+sticky side panel shows the plan's step progress and comment count above a
+**section outline**, and the document is GitHub's Markdown content column — one centred
 measure of at most 1012px with a comment rail in its left margin. Every block
 reveals a **+ Comment** action on hover; select
 text first to quote it. **Save feedback** writes the comments into the plan
@@ -284,12 +294,22 @@ file and returns them to the model.
   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.
 - **Keyboard first.** `j`/`k` move to the next or previous block, `c` comments
-  on the current block, `s` saves, `Esc` closes the composer, and `?` opens a
-  shortcut sheet; the header's `?` button opens the same sheet.
+  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.
+- **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.
 - **Markdown that reads.** Headings, lists, task items, blockquotes, fenced
-  code, GFM tables, `---` rules, and bare-URL autolinks render; tables honour the
-  alignment row and
-  scroll horizontally when narrow.
+  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
+  rather than a bordered chip, tables honour the alignment row and scroll
+  horizontally when narrow.
 - **Highlighted code.** Fenced code is tokenized by the shared
   `lib/highlight.ts`; the client copies only text and `tok-*` spans through
   `DOMParser`, so a code line is never parsed as markup.
@@ -439,10 +459,10 @@ file and returns them to the model.
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, section jump, scroll gauge, approve/refine/browser/keep). |
 | `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 and code highlighting, and the save/cancel/abort session. |
+| `web.ts` | `createPlanWebReview`: the loopback server, the section outline and code highlighting, and the save/approve/cancel/abort session. |
 | `web-router.ts` | Pure request handler: token/`Host`/method checks and the review routes. |
 | `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/cancel). |
+| `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). |
 | `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/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer (shared with `file-browse`). |

package/extensions/plan/tools.ts

@@ -26,12 +26,12 @@ import { FULL_SCREEN_OVERLAY, reuseText, toolDetails } from "../../lib/tui/chrom
 import { paint } from "../../lib/tui/tokens.ts";
 import { expandHint } from "../../lib/tui/glyphs.ts";
 import { READ_ONLY_SUMMARY } from "./policy.ts";
-import { feedbackSummary } from "./feedback.ts";
+import { feedbackSummary, type PlanAnnotation } from "./feedback.ts";
 import { ENTER_TOOL, EXIT_TOOL, SET_PLAN_STEPS_TOOL, WRITE_PLAN_TOOL, type PlanRuntime } from "./runtime.ts";
 import { PLAN_OUTLINE, extractPlanSteps, type PlanStep, type StepUpdate } from "./steps.ts";
 import { PlanViewComponent, sanitizePlanText, type PlanViewAction } from "./tui.ts";
 import type { EnterPlanModeDetails, ExitPlanModeDetails, SetPlanStepsDetails, WritePlanDetails } from "./types.ts";
-import { createPlanWebReview, type PlanWebReview } from "./web.ts";
+import { createPlanWebReview, type PlanReviewResult, type PlanReviewSession, type PlanWebReview } from "./web.ts";
 
 const ExitPlanModeParams = Type.Object({
 	plan_path: Type.String({
@@ -394,6 +394,8 @@ export function registerTools(
 			}
 
 			let outcome = await reviewPlan(ctx, file);
+			// Comments carried by a browser approval, reported alongside the approval.
+			let browserComments: PlanAnnotation[] = [];
 			// Review, refine, and browser review all loop back here until the user
 			// approves, keeps planning, or a refinement is handed to the model. The
 			// dialog-based refine editor carries no text from the review screen, so an
@@ -401,15 +403,25 @@ export function registerTools(
 			// as "not approved".
 			for (;;) {
 				if (outcome.action === "browser") {
-					const session = await web.start(ctx.cwd, file).catch(() => undefined);
+					const session: PlanReviewSession | undefined = await web
+						.start(ctx.cwd, file, { canApprove: true })
+						.catch(() => undefined);
 					if (!session) {
 						ctx.ui.notify("Plan review: could not start the browser review server.", "error");
 						outcome = await reviewPlan(ctx, file);
 						continue;
 					}
 					ctx.ui.notify(`Plan review: opened ${session.url}`, "info");
-					const result = await session.done;
+					const result: PlanReviewResult = await session.done;
 					await session.close();
+					if (result.status === "approved") {
+						// Approve from the browser is the TUI's approve: keep the comments it
+						// carried and fall through to the shared approval path below.
+						file = result.plan;
+						browserComments = result.annotations;
+						outcome = { action: "approve" };
+						continue;
+					}
 					if (result.status === "saved") {
 						// The comments are already in the file; hand them back as a refinement so
 						// the model revises the same plan and calls exit_plan_mode again.
@@ -491,11 +503,14 @@ export function registerTools(
 					: steps.length > 0
 						? ` Could not record the steps in the todo list${error ? `: ${error}` : ""}. Keep these steps in mind and tick them off with ${SET_PLAN_STEPS_TOOL} as you go.`
 						: " If the todo tool is available, record the steps with it before you start.";
+			const browserNote = browserComments.length
+				? `\n\nThe user approved from the browser review with these comments:\n${feedbackSummary(browserComments)}`
+				: "";
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${file.relativePath} is the source of truth; follow its steps.${tail}${listing}`,
+						text: `Plan approved. Plan mode is off and write access is restored. The plan file ${file.relativePath} is the source of truth; follow its steps.${browserNote}${tail}${listing}`,
 					},
 				],
 				details: {