@gavin-hu/my-pi-agent 0.8.0 → 0.9.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[];
@@ -58,59 +58,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 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 +166,25 @@ ${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 keyboard sheet, hidden until the client opens it. */
+const KEYS_DIALOG = `<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">
+<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 or this sheet</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,7 +197,11 @@ 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>
+<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, <kbd class="review-kbd">s</kbd> to save.</p>
+</div>
 </details>
 `
 		: "";
@@ -150,20 +216,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--icon" id="shortcuts" aria-label="Keyboard shortcuts" title="Keyboard shortcuts">?</button>
 <button type="button" class="bf-btn bf-btn--primary" id="save">Save feedback</button>
 <button type="button" class="bf-btn" id="cancel">Close</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>
+${KEYS_DIALOG}
 <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

@@ -28,9 +28,9 @@ export interface ReviewContext {
 	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 when the user cancels; the server resolves the session once the response has flushed. */
 	onCancel: () => void;
 }
 
@@ -89,8 +89,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 +122,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 };
 

package/extensions/plan/web.ts

@@ -92,6 +92,9 @@ 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 token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
@@ -113,11 +116,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 +134,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,
@@ -160,10 +169,11 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			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" };
+			},
+			onCancel: () => {
+				pendingResult = { status: "cancelled" };
 			},
-			onCancel: () => finish({ status: "cancelled" }),
 		};
 
 		// Live event streams, used only to notice a closed tab. The explicit Cancel
@@ -218,23 +228,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 +280,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

@@ -173,7 +173,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/tools.ts

@@ -6,8 +6,9 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { askHuman } from "../../lib/interaction.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
-import { reuseText, toolDetails } from "../../lib/tui.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { ASK_USER_QUESTION_TOOL } from "../../lib/tool-names.ts";
 import { UNAVAILABLE_TEXT, formatAnswerText, optionSummary, questionHeaders, unavailableResult } from "./answers.ts";
 import { askViaDialogs, type QuestionUI } from "./dialogs.ts";
@@ -73,12 +74,12 @@ export function registerTools(pi: ExtensionAPI): void {
 			const count = raw.length;
 			const noun = count === 1 ? "question" : "questions";
 			const headers = questionHeaders(raw);
-			let text = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("muted", `${count} ${noun}`);
-			if (headers.length > 0) text += theme.fg("dim", ` (${headers.join(", ")})`);
+			let text = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "meta", `${count} ${noun}`);
+			if (headers.length > 0) text += paint(theme, "faint", ` (${headers.join(", ")})`);
 
 			// One indented line per question that offers options, so a long option list
 			// stays mapped to its question instead of wrapping on a single row.
-			for (const line of optionSummary(raw)) text += `\n${theme.fg("dim", `  ${line}`)}`;
+			for (const line of optionSummary(raw)) text += `\n${paint(theme, "faint", `  ${line}`)}`;
 
 			const component = reuseText(context?.lastComponent);
 			component.setText(text);
@@ -94,26 +95,26 @@ export function registerTools(pi: ExtensionAPI): void {
 				return component;
 			}
 			if (details.unavailable) {
-				component.setText(theme.fg("dim", UNAVAILABLE_TEXT));
+				component.setText(paint(theme, "faint", UNAVAILABLE_TEXT));
 				return component;
 			}
 			if (details.answers.length === 0) {
-				component.setText(theme.fg("warning", "Cancelled"));
+				component.setText(paint(theme, "warn", "Cancelled"));
 				return component;
 			}
 
 			const lines = details.answers.map((answer) => {
-				const header = theme.fg("accent", sanitizeLine(answer.header));
+				const header = paint(theme, "accent", sanitizeLine(answer.header));
 				if (answer.wasCustom) {
 					const values = answer.values.map((value) => sanitizeLine(value)).join("; ");
-					return `${theme.fg("success", `${GLYPHS.check} `)}${header}: ${theme.fg("muted", "(wrote) ")}${values}`;
+					return `${paint(theme, "ok", `${GLYPHS.check} `)}${header}: ${paint(theme, "meta", "(wrote) ")}${values}`;
 				}
 				const numbered = answer.labels
 					.map((label, i) => `${answer.indices?.[i] ?? "?"}. ${sanitizeLine(label)}`)
 					.join(", ");
-				return `${theme.fg("success", `${GLYPHS.check} `)}${header}: ${numbered}`;
+				return `${paint(theme, "ok", `${GLYPHS.check} `)}${header}: ${numbered}`;
 			});
-			if (details.cancelled) lines.push(theme.fg("warning", "(cancelled)"));
+			if (details.cancelled) lines.push(paint(theme, "warn", "(cancelled)"));
 			// A blank line separates the call header from a multi-line answer body.
 			component.setText(lines.length > 1 ? `\n${lines.join("\n")}` : lines.join("\n"));
 			return component;