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

package/extensions/plan/web-page.ts

@@ -39,7 +39,7 @@ export interface ReviewOutlineItem {
 
 /** Everything the browser needs to render one plan review. */
 export interface ReviewPageData {
-	/** Plan title, derived from the file name. */
+	/** Plan title: the document's H1, or the file-name slug when it has none. */
 	title: string;
 	/** Source-line blocks of the feedback-stripped plan. */
 	blocks: PlanBlock[];
@@ -49,6 +49,8 @@ export interface ReviewPageData {
 	outline: ReviewOutlineItem[];
 	/** Highlighted HTML per line, keyed by the code block's 0-based start line. */
 	code: Record<string, string[]>;
+	/** Whether the review may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove: boolean;
 	/** Per-session secret the client echoes on every request. */
 	token: string;
 }
@@ -58,59 +60,106 @@ export const REVIEW_CSS = `${WEB_BASE_CSS}
 ${WEB_THEME_CSS}
 ${WEB_LAYOUT_CSS}
 ${WEB_COMPONENTS_CSS}
-.bf-review{display:flex;flex-direction:column;padding:var(--space-5) var(--space-6) 96px}
+.bf-review{--review-measure:1012px;--review-rail:26px;--review-gutter:34px;flex:1 1 auto;padding:var(--space-5) var(--space-6) 120px}
+/* The document is one content column at GitHub's Markdown body width, with the
+   comment rail inside it, so a plan reads the way the same file does on GitHub. */
+/* Sticky header: identity, the connection/save chip, the actions, and a
+   hairline reading-progress bar pinned to the header's bottom edge. */
 .review-bar{align-items:center;gap:var(--space-2) var(--space-4)}
 .review-bar .bf-brand{flex:0 0 auto}
 .review-heading{display:flex;align-items:center;flex:1 1 160px;min-width:0;overflow:hidden;border-left:1px solid var(--border);padding-left:var(--space-4)}
 .review-title{display:block;flex:1 1 auto;min-width:0;font-size:var(--fs-lg);font-weight:var(--fw-semibold);line-height:var(--lh-tight);color:var(--text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.review-state{flex:0 0 auto;white-space:nowrap}
 .review-status{flex:0 0 auto;max-width:42ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .review-status:empty{display:none}
 .review-controls{display:inline-flex;align-items:center;gap:var(--space-2);flex:0 0 auto}
+.review-progress{position:absolute;left:0;right:0;bottom:-1px;height:2px;overflow:hidden}
+.review-progress__fill{display:block;height:100%;width:0;background:var(--accent);transition:width var(--motion-fast) linear}
+/* Review panel: the plan's review facts, the section outline, then the keys. */
 .bf-app__body--single{grid-template-columns:minmax(0,1fr)}
-.bf-app__sidebar .bf-panel{flex:1 1 auto;min-height:0}
+.bf-app__sidebar .bf-panel{flex:1 1 auto;min-height:0;min-width:0}
+.review-panel{display:flex;flex-direction:column;gap:var(--space-3);padding:var(--space-4) var(--space-4) var(--space-2)}
+.review-facts{display:flex;flex-direction:column;gap:var(--space-2);padding-bottom:var(--space-3);border-bottom:1px solid var(--border)}
+.review-fact{display:flex;align-items:center;justify-content:space-between;gap:var(--space-3);font-size:var(--fs-sm);color:var(--muted)}
+.review-fact .bf-progress{color:var(--text)}
+.review-fact .bf-progress__track{width:96px}
+.review-fact__value{color:var(--text);font-family:var(--font-mono);font-variant-numeric:tabular-nums}
 .review-nav{min-width:0}
-.review-nav__title{margin:0;padding:var(--space-3) var(--space-4) var(--space-2);font:var(--fw-semibold) var(--fs-sm) var(--font-mono);color:var(--muted);text-transform:uppercase;letter-spacing:.04em}
+.review-nav__title{margin:0;font:var(--fw-semibold) var(--fs-xs) var(--font-mono);color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
 .review-nav ul{list-style:none;margin:0;padding:0}
-.review-nav a{display:block;padding:4px 8px;border-radius:var(--radius-sm);color:var(--muted);font-size:var(--fs-sm);line-height:var(--lh-snug);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.review-nav a{display:flex;align-items:baseline;gap:var(--space-2);padding:4px 8px;border-radius:var(--radius-sm);color:var(--muted);font-size:var(--fs-sm);line-height:var(--lh-snug)}
 .review-nav a:hover{background:var(--accent-soft);color:var(--accent);text-decoration:none}
 .review-nav a[aria-current="true"]{background:var(--accent-soft);color:var(--accent);font-weight:var(--fw-semibold)}
+.review-nav__link{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.review-nav__count{flex:0 0 auto;min-width:18px;padding:0 5px;border-radius:var(--radius-pill);background:var(--accent-soft);color:var(--accent);font:var(--fs-xs)/18px var(--font-mono);text-align:center}
 .review-nav .lvl-2 a{padding-left:18px}
 .review-nav .lvl-3 a{padding-left:30px}
 .review-nav .lvl-4 a,.review-nav .lvl-5 a,.review-nav .lvl-6 a{padding-left:42px}
-.bf-review>.bf-block{position:relative;padding:2px 96px 2px 0;border-radius:var(--radius-md);overflow-wrap:break-word}
-.bf-block[id]{scroll-margin-top:76px}
-.bf-block:hover{background:var(--surface)}
-.bf-block h1,.bf-block h2,.bf-block h3,.bf-block h4,.bf-block h5,.bf-block h6{margin:20px 0 8px;line-height:var(--lh-tight)}
-.bf-block h1{font-size:24px;padding-bottom:6px;border-bottom:1px solid var(--border)}
-.bf-block h2{font-size:19px;padding-bottom:4px;border-bottom:1px solid var(--border)}
-.bf-block h3{font-size:16px}
-.bf-block p{margin:10px 0}
-.bf-block blockquote{margin:10px 0;padding:2px 14px;border-left:3px solid var(--border);color:var(--muted)}
-.bf-block__li{display:flex;gap:8px;margin:3px 0}
+.review-hints{margin:auto 0 0;padding-top:var(--space-3);color:var(--muted);font-size:var(--fs-xs);line-height:var(--lh-relaxed)}
+.review-hints .review-kbd{margin:0 1px}
+/* The document: one measure, centred, with a comment rail in its left margin. */
+.bf-review>.bf-block{position:relative;width:100%;max-width:var(--review-measure);margin:0 auto;padding:3px 8px 3px var(--review-gutter);border-radius:var(--radius-md);overflow-wrap:break-word}
+.bf-block[id]{scroll-margin-top:88px}
+.bf-block__rail{position:absolute;left:0;top:6px;display:flex;flex-direction:column;align-items:center;gap:6px;width:var(--review-rail)}
+.bf-block__add{appearance:none;width:22px;height:22px;min-width:22px;padding:0;border:1px solid var(--border);border-radius:var(--radius-pill);background:var(--surface);color:var(--muted);font:var(--fs-md)/1 var(--font-ui);cursor:pointer;opacity:0;transition:opacity var(--motion-fast) var(--motion-ease)}
+.bf-block__add:hover{border-color:var(--accent);color:var(--accent)}
+.bf-block:hover .bf-block__add,.bf-block:focus-within .bf-block__add,.bf-block--active .bf-block__add,.bf-block--commented .bf-block__add{opacity:1}
+.bf-block__count{display:inline-flex;align-items:center;justify-content:center;min-width:20px;height:20px;padding:0 5px;border-radius:var(--radius-pill);background:var(--accent-soft);color:var(--accent);font:var(--fw-semibold) var(--fs-xs)/1 var(--font-mono)}
+.bf-block:hover,.bf-block--active{background:var(--surface)}
+.bf-block--active{box-shadow:inset 0 0 0 1px var(--border)}
+.bf-block h1,.bf-block h2,.bf-block h3,.bf-block h4,.bf-block h5,.bf-block h6{margin:24px 0 8px;line-height:var(--lh-tight)}
+.bf-block h1{font-size:var(--fs-xl);padding-bottom:6px;border-bottom:1px solid var(--border)}
+.bf-block h2{font-size:var(--fs-lg);padding-bottom:4px;border-bottom:1px solid var(--border)}
+.bf-block h3{font-size:17px}
+.bf-block h4,.bf-block h5,.bf-block h6{font-size:var(--fs-base)}
+.bf-block p{margin:11px 0;line-height:var(--lh-relaxed)}
+.bf-block blockquote{margin:11px 0;padding:2px 14px;border-left:3px solid var(--border);color:var(--muted)}
+.bf-block hr{border:0;border-top:1px solid var(--border);margin:22px 0}
+.bf-block__li{display:flex;gap:8px;margin:4px 0;line-height:var(--lh-relaxed)}
 .bf-block__marker{flex:0 0 auto;min-width:1.4em;color:var(--muted)}
 .bf-block__marker--done{color:var(--success)}
-.bf-block code{font-family:var(--font-mono);font-size:.9em;background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-sm);padding:.1em .35em}
-.bf-block pre.bf-code{margin:10px 0;padding:var(--space-3) 0;overflow:auto;background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-md);font:var(--fs-code)/1.55 var(--font-mono);tab-size:4;flex:none}
+.bf-block code{font-family:var(--font-mono);font-size:.9em;background:var(--surface);border-radius:var(--radius-sm);padding:.1em .35em}
+.bf-block pre.bf-code{margin:11px 0;padding:var(--space-3) 0;overflow:auto;background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-md);font:var(--fs-code)/1.55 var(--font-mono);tab-size:4;flex:none}
 .bf-block pre.bf-code code{background:none;border:0;padding:0;font-size:inherit}
 .bf-block pre.bf-code .bf-code__line{display:block;padding:0 14px;white-space:pre;min-height:1.55em}
-.bf-block__add{position:absolute;top:4px;right:4px;display:inline-flex;align-items:center;gap:6px;opacity:0;font-size:var(--fs-xs);padding:2px 8px}
-.bf-block:hover .bf-block__add,.bf-block__add:focus-visible{opacity:1}
-.bf-block--composing .bf-block__add{opacity:0}
-.bf-comments{display:flex;flex-direction:column;gap:8px;margin:4px 0 14px;padding-left:var(--space-5)}
+.review-table-wrap{margin:11px 0;overflow-x:auto}
+.review-table{width:100%;border-collapse:collapse;font-size:var(--fs-sm)}
+.review-table th,.review-table td{padding:6px 10px;border:1px solid var(--border);text-align:left;vertical-align:top}
+.review-table th{background:var(--surface);color:var(--muted);font-weight:var(--fw-medium)}
+/* Comment threads sit in the document flow, aligned with the block's text. */
+.bf-comments{display:flex;flex-direction:column;gap:8px;width:100%;max-width:var(--review-measure);margin:0 auto 14px;padding-left:var(--review-gutter)}
 .bf-comments:empty{display:none}
-.bf-comments--orphans{margin-top:26px;padding:var(--space-3) 0 0;border-top:1px dashed var(--border)}
-.bf-comments--orphans p{margin:0 0 8px;color:var(--muted);font-size:var(--fs-sm)}
+.bf-comments--orphans{margin-top:26px;padding:var(--space-3) 0 0 var(--review-gutter);border-top:1px dashed var(--border)}
+.bf-comments--orphans>p{margin:0 0 8px;color:var(--muted);font-size:var(--fs-sm)}
+.bf-comment{padding:var(--space-3) var(--space-4)}
+.bf-comment__head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:6px}
+.bf-comment__label{font:var(--fw-semibold) var(--fs-xs) var(--font-mono);color:var(--warn);text-transform:uppercase;letter-spacing:.06em}
+.bf-comment__spacer{flex:1 1 auto}
+.bf-comment__actions{display:flex;gap:4px}
+.bf-comment__actions .bf-btn{padding:1px 8px;font-size:var(--fs-xs)}
+.bf-comment__quote{margin-bottom:6px;padding-left:8px;border-left:2px solid var(--border);color:var(--muted);font-size:var(--fs-sm);overflow-wrap:anywhere}
+.bf-comment__body{white-space:pre-wrap;overflow-wrap:anywhere;line-height:var(--lh-snug)}
+.bf-composer{margin:0}
+.bf-block--composing .bf-block__add{opacity:0}
+/* The keyboard sheet, reusing the shared dialog shell. */
+.bf-dialog__head{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);border-bottom:1px solid var(--border)}
+.bf-dialog__head h2{margin:0;font-size:var(--fs-lg)}
+.review-keys{display:grid;grid-template-columns:auto 1fr;gap:8px var(--space-4);margin:0;padding:var(--space-4)}
+.review-keys dt{white-space:nowrap}
+.review-keys dd{margin:0;color:var(--muted);font-size:var(--fs-sm)}
+.review-kbd{display:inline-block;min-width:20px;padding:1px 6px;border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);background:var(--surface);color:var(--text);font:var(--fs-xs) var(--font-mono);text-align:center}
 @media (max-width:1180px){
 .bf-app__body{grid-template-columns:1fr;align-content:start}
 .bf-app__sidebar{position:static;max-height:none;border-right:0;border-bottom:1px solid var(--border)}
-.review-nav{padding:4px 16px 12px}
+.review-panel{padding:var(--space-2) var(--space-4) var(--space-3)}
+.review-facts{flex-direction:row;flex-wrap:wrap;gap:var(--space-3) var(--space-5);border-bottom:0;padding-bottom:0}
+.review-nav__title{padding:0}
+.review-nav ul{display:flex;flex-wrap:wrap;gap:2px}
+.review-nav .lvl-2 a,.review-nav .lvl-3 a,.review-nav .lvl-4 a,.review-nav .lvl-5 a,.review-nav .lvl-6 a{padding-left:8px}
+.review-hints{display:none}
 }
 @media (max-width:860px){
 .bf-review{padding:var(--space-4) 18px 80px}
-.bf-review>.bf-block{padding-right:36px}
-.bf-block__add-label{display:none}
-}
-@media (max-width:860px){
 .review-nav__title{display:none}
 }
 @media (max-width:820px){
@@ -119,10 +168,41 @@ ${WEB_COMPONENTS_CSS}
 .review-controls{order:2;margin-left:auto}
 .review-status{order:4;flex:1 1 100%;max-width:none;white-space:normal}
 }
-@media (prefers-reduced-motion:no-preference){.bf-block{transition:background .08s ease}}
+@media (prefers-reduced-motion:no-preference){.bf-block{transition:background var(--motion-fast) var(--motion-ease)}}
 @media (hover:none){.bf-block__add{opacity:1}}
 `.trim();
 
+/**
+ * The sidebar's one-line keyboard reminder. It names the keys a reviewer reaches
+ * for first and defers to the shortcut sheet (`?`) for the rest, so the line does
+ * not have to grow every time a binding is added.
+ */
+function reviewHints(canApprove: boolean): string {
+	const approve = canApprove ? `, <kbd class="review-kbd">a</kbd> to approve` : "";
+	return `<p class="review-hints">Press <kbd class="review-kbd">j</kbd>/<kbd class="review-kbd">k</kbd> to move, <kbd class="review-kbd">c</kbd> to comment${approve}, <kbd class="review-kbd">s</kbd> to save, <kbd class="review-kbd">?</kbd> for all shortcuts.</p>`;
+}
+
+/** The keyboard sheet, hidden until the client opens it. */
+function keysDialog(canApprove: boolean): string {
+	const approveRow = canApprove
+		? `<div><dt><kbd class="review-kbd">a</kbd></dt><dd>Approve and run the plan</dd></div>
+`
+		: "";
+	return `<div class="bf-dialog" id="keys-dialog" hidden>
+<div class="bf-dialog__panel" role="dialog" aria-modal="true" aria-labelledby="keys-title">
+<div class="bf-dialog__head"><h2 id="keys-title">Keyboard shortcuts</h2><span class="bf-spacer"></span><button type="button" class="bf-btn" id="keys-close">Close</button></div>
+<dl class="review-keys">
+${approveRow}<div><dt><kbd class="review-kbd">j</kbd> <kbd class="review-kbd">k</kbd></dt><dd>Next and previous block</dd></div>
+<div><dt><kbd class="review-kbd">c</kbd></dt><dd>Comment on the current block</dd></div>
+<div><dt><kbd class="review-kbd">Enter</kbd></dt><dd>Add the comment you are writing</dd></div>
+<div><dt><kbd class="review-kbd">s</kbd></dt><dd>Save feedback and return to Pi</dd></div>
+<div><dt><kbd class="review-kbd">Esc</kbd></dt><dd>Close the composer, the sheet, or the review</dd></div>
+<div><dt><kbd class="review-kbd">?</kbd></dt><dd>Toggle this sheet</dd></div>
+</dl>
+</div>
+</div>`;
+}
+
 /**
  * Render the review page for `data`. The markup is a fixed shell; the client
  * fills every dynamic field, so this function is the only place that needs the
@@ -135,10 +215,21 @@ export function renderReviewPage(data: ReviewPageData): string {
 	const outlinePanel = hasOutline
 		? `<details class="bf-app__sidebar review-outline" open>
 <summary class="bf-panel__summary">Sections</summary>
-<nav class="bf-panel review-nav" aria-labelledby="outline-title"><p class="review-nav__title" id="outline-title">Sections</p><ul id="outline-list"></ul></nav>
+<div class="bf-panel review-panel">
+${reviewFacts()}
+<nav class="review-nav" aria-labelledby="outline-title"><p class="review-nav__title" id="outline-title">Sections</p><ul id="outline-list"></ul></nav>
+${reviewHints(data.canApprove)}
+</div>
 </details>
 `
 		: "";
+	// Approve is the decisive action, so it takes the primary button and Save is
+	// demoted; a comment-only review has no approve button and keeps Save primary.
+	const approveButton = data.canApprove
+		? `
+<button type="button" class="bf-btn bf-btn--primary" id="approve">Approve &amp; run</button>`
+		: "";
+	const saveButton = `<button type="button" class="${data.canApprove ? "bf-btn" : "bf-btn bf-btn--primary"}" id="save">Save feedback</button>`;
 	return `<!doctype html>
 <html lang="en">
 <head>
@@ -150,20 +241,34 @@ ${docHead({ title: "Plan review", css: REVIEW_CSS })}
 ${brandLockup("plan review")}
 <div class="review-heading">
 <span class="review-title" id="plan-title">Plan review</span>
+<span class="bf-chip bf-chip--accent review-state" id="review-state">Connecting&#8230;</span>
 </div>
 <span class="bf-status review-status" id="status" role="status" aria-live="polite"></span>
 <div class="review-controls">
 ${themeToggle()}
-<button type="button" class="bf-btn bf-btn--primary" id="save">Save feedback</button>
-<button type="button" class="bf-btn" id="cancel">Close</button>
+<button type="button" class="bf-btn bf-btn--icon" id="shortcuts" aria-label="Keyboard shortcuts" title="Keyboard shortcuts">?</button>${approveButton}
+${saveButton}
+<button type="button" class="bf-btn" id="cancel">Back to Pi</button>
 </div>
-</div></header>
+</div><div class="review-progress" aria-hidden="true"><span class="review-progress__fill" id="progress-fill"></span></div></header>
 <div class="${bodyClass}">
 ${outlinePanel}<main class="bf-app__main bf-review" id="plan" aria-label="Plan"></main>
 </div>
+${keysDialog(data.canApprove)}
 <script type="application/json" id="review-data">${island}</script>
 <script src="/client.js" defer></script>
 </body>
 </html>
 `;
 }
+
+/**
+ * The review facts panel: the plan's step progress and total comment count.
+ * Static placeholders; the client fills them from the blocks it rendered.
+ */
+function reviewFacts(): string {
+	return `<div class="review-facts" id="review-facts">
+<div class="review-fact"><span>Steps</span><span class="bf-progress"><span class="bf-progress__track"><span class="bf-progress__fill" id="step-fill"></span></span><span class="review-fact__value" id="step-count">0/0</span></span></div>
+<div class="review-fact"><span>Comments</span><span class="review-fact__value" id="comment-total">0</span></div>
+</div>`;
+}

package/extensions/plan/web-router.ts

@@ -12,9 +12,9 @@
  * local page from driving the session.
  */
 
-import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { THEME_JS } from "../../lib/web/index.ts";
 import { coerceAnnotations, type PlanAnnotation } from "./feedback.ts";
+import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { renderReviewPage, type ReviewPageData } from "./web-page.ts";
 
 /** What a save callback reports back. */
@@ -24,13 +24,17 @@ export type SaveResult = { ok: true } | { ok: false; status: number; message: st
 export interface ReviewContext {
 	/** Per-session secret required on the page, event stream, and API routes. */
 	token: string;
+	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove: boolean;
 	/** Build the page data (recomputed per request from the current plan). */
 	page: () => Promise<ReviewPageData>;
 	/** Persist the annotations and report the outcome. */
 	save: (annotations: PlanAnnotation[]) => Promise<SaveResult>;
-	/** Called after a successful save, to resolve the session. */
+	/** Called after a successful save; the server resolves the session once the response has flushed. */
 	onSaved: (annotations: PlanAnnotation[]) => void;
-	/** Called when the user cancels, to resolve the session. */
+	/** Called after a successful approve; the server resolves the session once the response has flushed. */
+	onApprove: (annotations: PlanAnnotation[]) => void;
+	/** Called when the user cancels; the server resolves the session once the response has flushed. */
 	onCancel: () => void;
 }
 
@@ -80,6 +84,27 @@ function errorResponse(status: number, message: string): ServeResponse {
 	return jsonResponse(status, { error: message });
 }
 
+/**
+ * Parse and validate an `{ annotations }` request body. Returns the annotations,
+ * or an error response to send instead.
+ */
+function parseAnnotations(body: string): PlanAnnotation[] | ServeResponse {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return errorResponse(400, "The request body must be JSON.");
+	}
+	const annotations = coerceAnnotations((parsed as { annotations?: unknown } | null)?.annotations);
+	if (!annotations) return errorResponse(400, "The annotations are malformed.");
+	return annotations;
+}
+
+/** A parsed body is either the annotations or the error response to send. */
+function isResponse(value: PlanAnnotation[] | ServeResponse): value is ServeResponse {
+	return !Array.isArray(value);
+}
+
 /** Validate method and `Host`; returns an error response to send instead. */
 function checkEnvelope(
 	method: string,
@@ -89,8 +114,10 @@ function checkEnvelope(
 	if (upper !== "GET" && upper !== "HEAD" && upper !== "POST") {
 		return { ...errorResponse(405, "Only GET and POST are served."), headers: { ...JSON_HEADERS, Allow: "GET, POST" } };
 	}
+	// Fail closed: a missing or non-string Host is rejected too, not just a
+	// foreign one, so the DNS-rebinding guard cannot be skipped.
 	const host = headers.host;
-	if (typeof host === "string" && host && !HOST_PATTERN.test(host)) {
+	if (typeof host !== "string" || !HOST_PATTERN.test(host)) {
 		return errorResponse(403, "Unexpected Host header.");
 	}
 	return undefined;
@@ -120,7 +147,7 @@ export async function handleReviewRequest(
 		return errorResponse(400, "Malformed request URL.");
 	}
 
-	if (pathname === "/favicon.ico") return { status: 204, headers: { ...SCRIPT_HEADERS } };
+	if (pathname === "/favicon.ico") return { status: 204, headers: { "Cache-Control": "no-store" } };
 	if (pathname === "/theme.js") return { status: 200, headers: { ...SCRIPT_HEADERS }, body: THEME_JS };
 	if (pathname === "/client.js") return { status: 200, headers: { ...SCRIPT_HEADERS }, body: REVIEW_CLIENT_JS };
 
@@ -137,19 +164,25 @@ export async function handleReviewRequest(
 	}
 	if (pathname === "/api/feedback") {
 		if (method.toUpperCase() !== "POST") return errorResponse(405, "Use POST to save feedback.");
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(body);
-		} catch {
-			return errorResponse(400, "The request body must be JSON.");
-		}
-		const annotations = coerceAnnotations((parsed as { annotations?: unknown } | null)?.annotations);
-		if (!annotations) return errorResponse(400, "The annotations are malformed.");
+		const annotations = parseAnnotations(body);
+		if (isResponse(annotations)) return annotations;
 		const result = await ctx.save(annotations);
 		if (!result.ok) return errorResponse(result.status, result.message);
 		ctx.onSaved(annotations);
 		return jsonResponse(200, { ok: true });
 	}
+	if (pathname === "/api/approve") {
+		if (method.toUpperCase() !== "POST") return errorResponse(405, "Use POST to approve.");
+		// Only the exit_plan_mode flow owns the approval side effects, so a comment-only
+		// review refuses this even if a client posts it directly.
+		if (!ctx.canApprove) return errorResponse(403, "This review cannot be approved from the browser.");
+		const annotations = parseAnnotations(body);
+		if (isResponse(annotations)) return annotations;
+		const result = await ctx.save(annotations);
+		if (!result.ok) return errorResponse(result.status, result.message);
+		ctx.onApprove(annotations);
+		return jsonResponse(200, { ok: true });
+	}
 
 	return errorResponse(404, "That page does not exist.");
 }

package/extensions/plan/web.ts

@@ -24,6 +24,7 @@ import type { ReviewPageData } from "./web-page.ts";
 /** How a browser review ended. */
 export type PlanReviewResult =
 	| { status: "saved"; plan: StoredPlan; annotations: PlanAnnotation[] }
+	| { status: "approved"; plan: StoredPlan; annotations: PlanAnnotation[] }
 	| { status: "cancelled" };
 
 /** A running review the caller awaits and then closes. */
@@ -38,9 +39,17 @@ export interface PlanReviewSession {
 	close(): Promise<void>;
 }
 
+/** Per-session options for {@link PlanWebReview.start}. */
+export interface PlanReviewOptions {
+	/** Abort signal; aborting closes the session as cancelled. */
+	signal?: AbortSignal;
+	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove?: boolean;
+}
+
 /** Starts and tracks review sessions. */
 export interface PlanWebReview {
-	start(cwd: string, plan: StoredPlan, signal?: AbortSignal): Promise<PlanReviewSession | undefined>;
+	start(cwd: string, plan: StoredPlan, options?: PlanReviewOptions): Promise<PlanReviewSession | undefined>;
 	/** Stop every running session (session shutdown). */
 	closeAll(): Promise<void>;
 }
@@ -92,8 +101,17 @@ async function listen(server: Server, port: number): Promise<number> {
 
 export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps = {}): PlanWebReview {
 	const sessions = new Set<PlanReviewSession>();
+	// Last bound port per plan path, so the same plan keeps one origin across
+	// review turns (and its saved browser theme with it).
+	const ports = new Map<string, number>();
 
-	const start = async (cwd: string, plan: StoredPlan, signal?: AbortSignal): Promise<PlanReviewSession | undefined> => {
+	const start = async (
+		cwd: string,
+		plan: StoredPlan,
+		options: PlanReviewOptions = {},
+	): Promise<PlanReviewSession | undefined> => {
+		const { signal } = options;
+		const canApprove = options.canApprove === true;
 		const token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
@@ -113,11 +131,15 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		// that still matches it, or the comments land beside the wrong text.
 		let baseline = stripFeedback(plan.content);
 		let savedPlan: StoredPlan | undefined;
+		// Set by `onSaved`/`onCancel`; resolved once the HTTP response has flushed,
+		// so the caller cannot close the socket before the browser sees the reply.
+		let pendingResult: PlanReviewResult | undefined;
 
 		const page = async (): Promise<ReviewPageData> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
 			baseline = stripFeedback(current.content);
 			const blocks = planBlocks(baseline);
+			const headings = planHeadings(blocks);
 			// Highlight code blocks once, at the boundary: the client copies only the
 			// tok-* spans out of the server-escaped HTML.
 			const code: Record<string, string[]> = {};
@@ -127,10 +149,12 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				if (language) code[String(block.start)] = highlightLines(codeBody(block), language);
 			}
 			return {
-				title: planTitle(basename(current.path)),
+				// The document's own H1 reads better than the file-name slug, and the
+				// slug is still the fallback for a plan that starts with something else.
+				title: headings.find((heading) => heading.level === 1)?.text || planTitle(basename(current.path)),
 				blocks,
 				annotations: parseFeedback(current.content),
-				outline: planHeadings(blocks).map((heading) => ({
+				outline: headings.map((heading) => ({
 					id: `s-${heading.line}`,
 					line: heading.line,
 					level: heading.level,
@@ -138,6 +162,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				})),
 				code,
 				token,
+				canApprove,
 			};
 		};
 
@@ -157,13 +182,18 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 
 		const context: ReviewContext = {
 			token,
+			canApprove,
 			page,
 			save,
 			onSaved: (annotations) => {
-				if (savedPlan) finish({ status: "saved", plan: savedPlan, annotations });
-				else finish({ status: "cancelled" });
+				pendingResult = savedPlan ? { status: "saved", plan: savedPlan, annotations } : { status: "cancelled" };
+			},
+			onApprove: (annotations) => {
+				pendingResult = savedPlan ? { status: "approved", plan: savedPlan, annotations } : { status: "cancelled" };
+			},
+			onCancel: () => {
+				pendingResult = { status: "cancelled" };
 			},
-			onCancel: () => finish({ status: "cancelled" }),
 		};
 
 		// Live event streams, used only to notice a closed tab. The explicit Cancel
@@ -218,23 +248,44 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 					response.end();
 					return;
 				}
-				response.end(result.body ?? "");
+				// A save or cancel only resolves the session after its response is on the
+				// wire; otherwise `close()` would force-close the socket mid-reply.
+				response.end(result.body ?? "", () => {
+					if (!pendingResult) return;
+					const terminal = pendingResult;
+					pendingResult = undefined;
+					finish(terminal);
+				});
 			})();
 		});
 
-		let port: number;
+		const preferred = deps.port ?? ports.get(plan.path) ?? 0;
+		let port: number | undefined;
 		try {
-			port = await listen(server, deps.port ?? 0);
+			port = await listen(server, preferred);
 		} catch {
+			// The remembered port may have been taken between turns; fall back once.
+			if (preferred !== 0) {
+				try {
+					port = await listen(server, 0);
+				} catch {
+					port = undefined;
+				}
+			}
+		}
+		if (port === undefined) {
 			server.close();
 			return undefined;
 		}
+		ports.set(plan.path, port);
 
 		const url = `http://127.0.0.1:${port}/?token=${token}`;
 		let closed = false;
+		let abortHandler: (() => void) | undefined;
 		const close = async (): Promise<void> => {
 			if (closed) return;
 			closed = true;
+			if (signal && abortHandler) signal.removeEventListener("abort", abortHandler);
 			sessions.delete(session);
 			for (const client of clients) client.end();
 			clients.clear();
@@ -249,9 +300,9 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		sessions.add(session);
 
 		if (signal) {
-			const onAbort = (): void => void close();
+			abortHandler = (): void => void close();
 			if (signal.aborted) void close();
-			else signal.addEventListener("abort", onAbort, { once: true });
+			else signal.addEventListener("abort", abortHandler, { once: true });
 		}
 
 		(deps.open ?? openInBrowser)(url);

package/extensions/question/README.md

@@ -4,12 +4,20 @@ A single model-facing tool, `ask_user_question`, that lets the model ask the
 human one or more structured questions mid-turn and wait for typed answers.
 Modelled on Claude Code's `AskUserQuestion`.
 
+<img src="../../assets/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%">
+
 ```
 pi --extension ./extensions/question   # load just this extension
 pi -e .                                # load the whole @gavin-hu/my-pi-agent package
 pi install ./                          # install the package
 ```
 
+## Tool rendering
+
+How the `ask_user_question` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/ask_user_question.png" alt="The ask_user_question tool's call and result: the call line and an indented body with the question headers, the options, and the answers" width="100%">
+
 ## What it does
 
 The model calls `ask_user_question` with 1–4 questions. Each question offers up
@@ -162,7 +170,11 @@ None in v1 — the tool is either available (a UI exists) or not.
 - **Transcript rendering is driven by `details`.** `renderCall` summarises the
   question count and headers and lists one option line per question;
   `renderResult` renders `✓ Auth: 1. OAuth` per answer, `(wrote)` for custom
-  text, warning-colored `Cancelled`, and dim `No UI` when unavailable.
+  text, warning-colored `Cancelled`, and dim `No UI` when unavailable. The call
+  summary reads the call's *streaming* args, so a field that has not arrived yet
+  — a question `header`, an option `label` — reads as absent instead of
+  throwing; a throwing renderer makes Pi fall back to its own call line, a
+  column to the left of the framed one.
 
 ## Files
 
@@ -173,7 +185,7 @@ None in v1 — the tool is either available (a UI exists) or not.
 | `types.ts` | Shared raw/normalized types |
 | `answers.ts` | Answer normalization and model-facing formatting (pure) |
 | `tui-state.ts` | Pure keyboard/navigation state machine |
-| `tui.ts` | Custom terminal component (render + input) |
+| `tui.ts` | Custom terminal component (render + input), drawn from the `lib/tui/` kit (`titleRule`/`plainRule`, `checkbox`, `flowCells`, `screenHint`, `editorTheme`). |
 | `dialogs.ts` | `select`/`input`/`editor` fallback driver |
 | `tools.ts` | Tool registration and transcript renderers |
 

package/extensions/question/answers.ts

@@ -80,37 +80,44 @@ export function formatAnswerText(result: AskResult): string {
 	return lines.join("\n");
 }
 
-/** Minimal shape needed to summarize a call, before or after normalization. */
+/**
+ * Minimal shape needed to summarize a call, before or after normalization.
+ *
+ * The transcript renderer reads this from a call's *streaming* args, where a
+ * field can be missing or still be a fragment: a partial parse can hand back an
+ * option before its label has arrived. Every field is therefore `unknown`, and
+ * the helpers below read a non-string as absent rather than throw.
+ */
 export interface CallQuestion {
-	header?: string;
-	options?: { label: string }[];
+	header?: unknown;
+	options?: unknown;
+}
+
+/** A partial value read as a single line; anything but a string reads empty. */
+function asLine(value: unknown): string {
+	return typeof value === "string" ? sanitizeLine(value) : "";
 }
 
 /** Display headers with positional defaults (`Q1`, `Q2`, …). */
 export function questionHeaders(questions: CallQuestion[]): string[] {
-	return questions.map((question, i) => sanitizeLine(question?.header?.trim() || `Q${i + 1}`));
+	return questions.map((question, i) => asLine(question?.header) || `Q${i + 1}`);
 }
 
 /** One `Header: a, b, Other` summary per question that offers options. */
 export function optionSummary(questions: CallQuestion[]): string[] {
 	return questions
-		.map((question, i) => ({ question, header: question?.header?.trim() || `Q${i + 1}` }))
-		.filter(({ question }) => (question?.options?.length ?? 0) > 0)
-		.map(({ question, header }) => {
-			const labels = question.options?.map((option) => sanitizeLine(option.label)).join(", ");
-			return `${sanitizeLine(header)}: ${labels}, Other`;
+		.map((question, i) => ({ header: asLine(question?.header) || `Q${i + 1}`, options: question?.options }))
+		.filter(({ options }) => Array.isArray(options) && options.length > 0)
+		.map(({ header, options }) => {
+			// A partial option has no label yet; list the ones that have arrived.
+			const labels = (options as unknown[])
+				.map((option) => (option as { label?: unknown } | undefined)?.label)
+				.filter((label): label is string => typeof label === "string")
+				.map((label) => sanitizeLine(label));
+			return `${header}: ${labels.length > 0 ? `${labels.join(", ")}, Other` : "Other"}`;
 		});
 }
 
-/** One-line summary of the questions, used by the transcript call renderer. */
-export function formatCallText(questions: CallQuestion[]): string {
-	const noun = questions.length === 1 ? "question" : "questions";
-	const lines = [`ask_user_question ${questions.length} ${noun} (${questionHeaders(questions).join(", ")})`];
-	const options = optionSummary(questions);
-	if (options.length > 0) lines.push(`  Options: ${options.join(" · ")}`);
-	return lines.join("\n");
-}
-
 /** Human-readable summary of a selection, used in the Submit tab. */
 export function describeSelection(selection: Selection | undefined): string {
 	if (!selection) return "(unanswered)";