@narumitw/pi-webui 0.31.0 → 0.33.0

package/README.md

@@ -2,6 +2,9 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-webui)](https://www.npmjs.com/package/@narumitw/pi-webui) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
+> [!WARNING]
+> This extension is experimental. Its browser workflow and package API may change between releases.
+
 `@narumitw/pi-webui` adds a private, focused browser companion to the current terminal-owned [Pi Coding Agent](https://pi.dev) session. It displays Pi's semantic conversation and tool activity as they happen and can send text or sanitized images back into that same session.
 
 This package is intentionally different from the broader, separately maintained `@narumitw/pi-web` application. WebUI has one current-session chat page and no session manager, shell, file browser, git UI, control room, or task board.
@@ -27,7 +30,7 @@ pi install npm:@narumitw/pi-webui
 Try the working tree without installing:
 
 ```bash
-pi -e ./extensions/pi-webui
+pi -e ./experimental/pi-webui
 # or
 just try webui
 ```
@@ -36,11 +39,12 @@ The package targets the latest Pi release.
 
 ## 🚀 Usage
 
-1. Start Pi in a terminal and run `/webui`.
-2. Open the one-time `http://127.0.0.1:<port>/bootstrap?...` link shown by Pi. The extension does not open a browser itself.
-3. Continue typing in either the terminal or browser. Accepted messages from both surfaces appear in the browser transcript.
-4. While Pi is idle, **Send** starts a turn immediately. While Pi is working, **Queue next** queues a follow-up. Use **Steer** only when the new instruction should reach Pi after the current tool batch.
-5. Refreshing or opening the link in another tab takes the editing lease. Older tabs remain readable and clearly become read-only.
+1. Start Pi in a terminal and run `/webui` to open the current-state menu.
+2. Select **Open WebUI**. If the server is already running, select **Get a fresh link** instead; this invalidates any earlier unused bootstrap link.
+3. Open the one-time `http://127.0.0.1:<port>/bootstrap?...` link shown by Pi. The extension does not open a browser itself. Use `/webui open` when you intentionally want to skip the menu.
+4. Continue typing in either the terminal or browser. Accepted messages from both surfaces appear in the browser transcript.
+5. While Pi is idle, **Send** starts a turn immediately. While Pi is working, **Queue next** queues a follow-up. Use **Steer** only when the new instruction should reach Pi after the current tool batch.
+6. Refreshing or opening the link in another tab takes the editing lease. Older tabs remain readable and clearly become read-only.
 
 If another installed extension also registers `/webui`, Pi assigns numeric command suffixes according to extension load order. Check Pi's command provenance and invoke the WebUI entry.
 
@@ -48,13 +52,16 @@ If another installed extension also registers `/webui`, Pi assigns numeric comma
 
 | Command | Behavior |
 | --- | --- |
-| `/webui` | Start or reuse the current session server and display a fresh one-time link. |
+| `/webui` | Open the current-state menu in TUI or an interactive RPC client. Opening or cancelling the menu has no side effects. |
+| `/webui open` | Start or reuse the current session server and display a fresh one-time link without opening the menu. Unsupported print/JSON modes remain side-effect free because they cannot expose the link. |
 | `/webui settings` | Open the interactive settings screen in TUI mode. Other modes report the manual settings path when notifications are available. |
 | `/webui status` | Show the effective startup preference and source, settings path, and whether the current session server is running. It never issues a bootstrap link. |
 | `/webui help` | Show command and manual-settings help. |
 | `/webui init` | Create the defaults file without overwriting existing content, then open settings in TUI mode. |
 
-Argument completion is available for all subcommands. Bare `/webui` remains the direct browser-link action.
+Argument completion is available for all subcommands. Bare `/webui` is menu-first; scripts and users migrating from the earlier direct behavior should use `/webui open`.
+
+The menu keeps the consequential current state beside each decision: whether the session server is running, whether startup is **Manual** or **Every session**, and whether values come from defaults or the settings file. **Open WebUI** previews that it starts a private session server. **Get a fresh link** previews that it keeps the server but invalidates any earlier unused bootstrap link. Escape closes the main menu without starting a server, issuing a link, or saving settings. Settings, Status & diagnostics, and Help are one level deep and return to the menu.
 
 ## ⚙️ Settings
 
@@ -90,7 +97,9 @@ The normal default path is `~/.pi/agent/pi-webui.json`. Pi installations that us
 | `maxBatchBytes` | `41943040` (40 MiB) | Combined source/processed draft bytes; hard ceiling 209715200 (200 MiB). |
 | `maxImagePixels` | `50000000` | Decoded pixels per image; hard ceiling 100000000. Animated-image frame area participates in this limit. |
 
-A missing file uses defaults. The file must contain a top-level JSON object; recognized booleans and positive integer limits must have the documented types and remain within their hard ceilings. Malformed JSON or an invalid recognized value causes the file to be ignored with a warning and leaves it untouched. Unknown fields are accepted and preserved by the settings screen for forward compatibility. The settings screen exposes only the frequent startup toggle; there is not yet user-testing evidence that `maxImages` is adjusted often enough to justify another routine row. Retention and image-limit fields remain in Advanced JSON at the reported path.
+A missing file uses defaults. The file must contain a top-level JSON object; recognized booleans and positive integer limits must have the documented types and remain within their hard ceilings. Malformed JSON or an invalid recognized value causes the file to be ignored with a warning and leaves it untouched. Unknown fields are accepted and preserved by the settings screen for forward compatibility. The settings screen exposes only **Start WebUI automatically**, with the user-facing values **Manual** and **Every session**. Changes save immediately; Escape closes or returns and does not roll back changes that already succeeded. The startup behavior applies on the next session initialization or `/reload` and does not start or stop the current server. There is not yet user-testing evidence that `maxImages` is adjusted often enough to justify another routine row. Retention and image-limit fields remain in Advanced JSON at the reported path.
+
+If the settings file is malformed or contains an invalid recognized value, the menu presents a read-only **Repair settings file** flow. Safe defaults remain active, the original bytes stay untouched, and settings writes remain paused until the file is repaired and Pi is reloaded.
 
 ### Advanced image limits
 
@@ -98,7 +107,7 @@ Omitting all four image-limit fields exactly reproduces the original 8 image / 1
 
 Settings are reloaded on every `session_start`. Changes made in `/webui settings` are saved atomically and update the in-memory preference immediately, but they intentionally do not start or stop the server in the current session; they take effect at the next session initialization or `/reload`. `/webui init` creates formatted defaults once and refuses to overwrite valid or invalid existing content.
 
-In print, JSON, and RPC modes, `/webui settings` does not open custom TUI or write protocol-breaking output. Use `/webui status`, `/webui help`, or edit the reported path manually.
+In RPC mode, `/webui` uses the client's observable selection dialogs without opening custom TUI. In print and JSON modes, bare `/webui` and `/webui open` remain side-effect free because those modes cannot safely expose an interactive menu or bootstrap link. `/webui settings` does not open custom TUI or write protocol-breaking output outside TUI mode. Use an interactive TUI/RPC client for the menu and link, or use `/webui status`, `/webui help`, and the reported path where notifications are available.
 
 ## 🔄 What synchronization means
 
@@ -143,7 +152,9 @@ A loopback page is local to the operating-system network namespace. WebUI does n
 
 ## ♿ Accessibility and browsers
 
-The page uses semantic headings, native disclosure/dialog controls, concise status/alert live regions, accessible labels, visible keyboard focus, at least 44 px controls, keyboard image preview/removal/reordering, `Ctrl/Command+Enter` submission, reduced-motion handling, dark mode, and responsive reflow. It targets current stable desktop Chrome, Edge, Firefox, and Safari.
+The terminal menu uses Pi's configured selection keybindings, textual state that does not depend on color, stable focus when returning from a secondary screen, and responsive wrapping without hiding consequential previews. Pi's terminal accessibility remains subject to terminal and screen-reader capabilities.
+
+The browser page uses semantic headings, native disclosure/dialog controls, concise status/alert live regions, accessible labels, visible keyboard focus, at least 44 px controls, keyboard image preview/removal/reordering, `Ctrl/Command+Enter` submission, reduced-motion handling, dark mode, and responsive reflow. It targets current stable desktop Chrome, Edge, Firefox, and Safari.
 
 ## 🚧 Limitations
 
@@ -158,7 +169,8 @@ The page uses semantic headings, native disclosure/dialog controls, concise stat
 ```text
 src/index.ts         Pi package entrypoint
 src/webui.ts         extension registration and command orchestration
-src/runtime.ts       Pi lifecycle, commands, event projection, and browser message routing
+src/runtime.ts       Pi lifecycle, commands, menu orchestration, event projection, and browser routing
+src/menu.ts          responsive current-state menu and read-only detail presentation
 src/settings.ts      global WebUI settings validation and atomic persistence
 src/conversation.ts  bounded transcript snapshot and ordered event replay
 src/drafts.ts        authoritative in-memory text and attachment-reference revisions

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@narumitw/pi-webui",
-	"version": "0.31.0",
-	"description": "Local Radix UI web companion for the current Pi terminal session.",
+	"version": "0.33.0",
+	"description": "Experimental Radix UI web companion for the current Pi terminal session.",
 	"type": "module",
 	"license": "MIT",
 	"private": false,
@@ -57,6 +57,6 @@
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/narumiruna/pi-extensions",
-		"directory": "extensions/pi-webui"
+		"directory": "experimental/pi-webui"
 	}
 }

package/src/menu.ts

@@ -0,0 +1,194 @@
+import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type KeybindingsManager,
+	type SelectItem,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+
+export type WebUIMenuAction = "open" | "settings" | "repair" | "status" | "help";
+
+export interface WebUIMenuState {
+	serverRunning: boolean;
+	startupAutomatic: boolean;
+	settingsSource: string;
+	settingsPath: string;
+	settingsInvalid: boolean;
+}
+
+export interface WebUIMenuItem extends SelectItem {
+	value: WebUIMenuAction;
+}
+
+interface TuiRenderHost {
+	requestRender(): void;
+}
+
+export function webUIMenuItems(state: WebUIMenuState): WebUIMenuItem[] {
+	const primary: WebUIMenuItem = state.serverRunning
+		? {
+				value: "open",
+				label: "Get a fresh link",
+				description: "Keep the current server and invalidate any unused earlier bootstrap link.",
+			}
+		: {
+				value: "open",
+				label: "Open WebUI",
+				description:
+					"Start a private browser companion for this Pi session and create a one-time link.",
+			};
+	const settings: WebUIMenuItem = state.settingsInvalid
+		? {
+				value: "repair",
+				label: "Repair settings file",
+				description:
+					"Safe defaults are active; inspect the preserved invalid JSON before reloading.",
+			}
+		: {
+				value: "settings",
+				label: "Settings",
+				description: `Startup: ${startupLabel(state)}. Changes save immediately and apply on the next session initialization.`,
+			};
+	return [
+		primary,
+		settings,
+		{
+			value: "status",
+			label: "Status & diagnostics",
+			description: "Review effective startup, settings source, image limits, and server state.",
+		},
+		{
+			value: "help",
+			label: "Help",
+			description: "Review the browser workflow, direct commands, and advanced settings path.",
+		},
+	];
+}
+
+export function webUIMenuTitle(state: WebUIMenuState): string {
+	const lines = [
+		"Pi WebUI",
+		`Server: ${state.serverRunning ? "Running" : "Stopped"} · Startup: ${startupLabel(state)} · Source: ${safeTerminalText(state.settingsSource)}`,
+	];
+	if (state.settingsInvalid) {
+		lines.push(
+			"Settings need repair · Safe defaults are active",
+			`File: ${safeTerminalText(state.settingsPath)}`,
+		);
+	}
+	return lines.join("\n");
+}
+
+export function createWebUIMenuComponent(
+	state: WebUIMenuState,
+	tui: TuiRenderHost,
+	theme: Theme,
+	done: (action: WebUIMenuAction | undefined) => void,
+	selectedAction?: WebUIMenuAction,
+) {
+	const items = webUIMenuItems(state);
+	const container = new Container();
+	const title = new Text(theme.fg("accent", theme.bold("Pi WebUI")), 1, 1);
+	container.addChild(title);
+	container.addChild(
+		new Text(
+			[
+				`Server: ${state.serverRunning ? "Running" : "Stopped"}`,
+				`Startup: ${startupLabel(state)} · Source: ${safeTerminalText(state.settingsSource)}`,
+				...(state.settingsInvalid
+					? [
+							"Settings need repair · Safe defaults are active",
+							`File: ${safeTerminalText(state.settingsPath)}`,
+						]
+					: []),
+			].join("\n"),
+			1,
+			0,
+		),
+	);
+	const preview = new Text("", 1, 1);
+	const list = new SelectList(items, items.length, {
+		selectedPrefix: (text) => theme.fg("accent", text),
+		selectedText: (text) => theme.fg("accent", text),
+		description: (text) => theme.fg("muted", text),
+		scrollInfo: (text) => theme.fg("dim", text),
+		noMatch: (text) => theme.fg("warning", text),
+	});
+	const updatePreview = (item: SelectItem) => {
+		preview.setText(`Effect: ${safeTerminalText(item.description ?? item.label)}`);
+	};
+	const selectedIndex = Math.max(
+		0,
+		items.findIndex((item) => item.value === selectedAction),
+	);
+	list.setSelectedIndex(selectedIndex);
+	updatePreview(items[selectedIndex]);
+	list.onSelectionChange = updatePreview;
+	list.onSelect = (item) => done(item.value as WebUIMenuAction);
+	list.onCancel = () => done(undefined);
+	container.addChild(list);
+	container.addChild(preview);
+	const hintText = () =>
+		theme.fg(
+			"dim",
+			`${keyHint("tui.select.confirm", "select")} · ${keyHint("tui.select.cancel", "close")}`,
+		);
+	const hint = new Text(hintText(), 1, 0);
+	container.addChild(hint);
+	return {
+		render: (width: number) => container.render(width),
+		invalidate: () => {
+			title.setText(theme.fg("accent", theme.bold("Pi WebUI")));
+			hint.setText(hintText());
+			container.invalidate();
+		},
+		handleInput(data: string) {
+			list.handleInput(data);
+			tui.requestRender();
+		},
+	};
+}
+
+export function createWebUIDetailComponent(
+	title: string,
+	lines: readonly string[],
+	tui: TuiRenderHost,
+	theme: Theme,
+	keybindings: KeybindingsManager,
+	done: () => void,
+) {
+	const container = new Container();
+	const heading = new Text(theme.fg("accent", theme.bold(safeTerminalText(title))), 1, 1);
+	const hint = new Text(theme.fg("dim", keyHint("tui.select.cancel", "back")), 1, 1);
+	container.addChild(heading);
+	container.addChild(new Text(lines.map((line) => safeTerminalText(line)).join("\n"), 1, 0));
+	container.addChild(hint);
+	return {
+		render: (width: number) => container.render(width),
+		invalidate: () => {
+			heading.setText(theme.fg("accent", theme.bold(safeTerminalText(title))));
+			hint.setText(theme.fg("dim", keyHint("tui.select.cancel", "back")));
+			container.invalidate();
+		},
+		handleInput(data: string) {
+			if (keybindings.matches(data, "tui.select.cancel")) done();
+			tui.requestRender();
+		},
+	};
+}
+
+export function safeTerminalText(value: unknown): string {
+	return [...String(value)]
+		.map((character) => {
+			const code = character.charCodeAt(0);
+			return code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? " " : character;
+		})
+		.join("")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function startupLabel(state: WebUIMenuState): string {
+	return state.startupAutomatic ? "Every session" : "Manual";
+}

package/src/runtime.ts

@@ -19,6 +19,15 @@ import {
 	processStagedImage,
 	validateStagedBrowserImages,
 } from "./images.js";
+import {
+	createWebUIDetailComponent,
+	createWebUIMenuComponent,
+	safeTerminalText,
+	type WebUIMenuAction,
+	type WebUIMenuState,
+	webUIMenuItems,
+	webUIMenuTitle,
+} from "./menu.js";
 import { type EffectivePiImageSettings, readEffectivePiImageSettings } from "./pi-settings.js";
 import {
 	type WebSendRequest,
@@ -36,10 +45,14 @@ import {
 } from "./settings.js";
 
 const WIDGET_KEY = "webui";
+const ACTIVITY_STATUS_KEY = "webui:activity";
+const EXPERIMENTAL_WARNING =
+	"pi-webui is experimental; its browser workflow and package API may change.";
 const INPUT_HEADER = /^<pi-webui-input nonce="([0-9a-f-]+)">\n/;
 const INPUT_FOOTER = "\n</pi-webui-input>";
-const COMMAND_USAGE = "Usage: /webui [settings|status|help|init]";
+const COMMAND_USAGE = "Usage: /webui [open|settings|status|help|init]";
 const COMMAND_COMPLETIONS = [
+	{ value: "open", label: "open", description: "Open WebUI and display a fresh link" },
 	{ value: "settings", label: "settings", description: "Open WebUI settings" },
 	{ value: "status", label: "status", description: "Show effective WebUI settings and state" },
 	{ value: "help", label: "help", description: "Show WebUI command help" },
@@ -111,6 +124,7 @@ export class WebUIRuntime {
 	private settingsPath = "pi-webui.json";
 	private settingsSource: SettingsLoadResult["source"] = "defaults";
 	private settingsSaveQueue: Promise<void> = Promise.resolve();
+	private activityId = 0;
 
 	constructor(
 		private readonly pi: ExtensionAPI,
@@ -121,7 +135,7 @@ export class WebUIRuntime {
 
 	register(): void {
 		this.pi.registerCommand("webui", {
-			description: "Open or configure the local web companion for this Pi session",
+			description: "Manage the local web companion for this Pi session",
 			getArgumentCompletions: (prefix) => {
 				const normalized = prefix.trimStart().toLowerCase();
 				if (/\s/.test(normalized)) return null;
@@ -133,7 +147,11 @@ export class WebUIRuntime {
 				const action = args.trim().toLowerCase();
 				try {
 					if (!action) {
-						await this.presentLink(ctx);
+						await this.showMenu(ctx);
+						return;
+					}
+					if (action === "open") {
+						await this.openWebUI(ctx);
 						return;
 					}
 					if (action === "settings") {
@@ -154,10 +172,12 @@ export class WebUIRuntime {
 					}
 					if (ctx.hasUI) ctx.ui.notify(COMMAND_USAGE, "warning");
 				} catch (error) {
-					if (!action) {
-						ctx.ui.notify(`Pi WebUI could not start: ${formatError(error)}`, "error");
-					} else if (ctx.hasUI) {
-						ctx.ui.notify(`Pi WebUI command failed: ${formatError(error)}`, "error");
+					if (ctx.hasUI) {
+						const message = `Pi WebUI command failed: ${formatError(error)}`;
+						ctx.ui.notify(
+							action === "open" || !action ? `${message}. Retry with /webui open.` : message,
+							"error",
+						);
 					}
 				}
 			},
@@ -243,6 +263,8 @@ export class WebUIRuntime {
 		previousConversation?.close();
 		await this.releaseServer();
 		if (generation !== this.generation) return;
+		await this.settingsSaveQueue;
+		if (generation !== this.generation) return;
 		const settingsResult = await this.dependencies.loadSettings();
 		if (generation !== this.generation) return;
 		this.applySettingsResult(settingsResult);
@@ -262,6 +284,9 @@ export class WebUIRuntime {
 		this.closed = false;
 		this.lastSettingsWarning = "";
 		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		this.activityId += 1;
+		ctx.ui.setStatus(ACTIVITY_STATUS_KEY, undefined);
+		if (ctx.hasUI) ctx.ui.notify(EXPERIMENTAL_WARNING, "warning");
 		if (settingsResult.warning) ctx.ui.notify(settingsResult.warning, "warning");
 		if (!this.settings.startOnSessionStart) return;
 		try {
@@ -285,6 +310,8 @@ export class WebUIRuntime {
 		this.context = undefined;
 		this.conversation = undefined;
 		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		this.activityId += 1;
+		ctx.ui.setStatus(ACTIVITY_STATUS_KEY, undefined);
 	}
 
 	private captureContext(ctx: ExtensionContext): void {
@@ -363,7 +390,105 @@ export class WebUIRuntime {
 		ctx.ui.notify(`Pi WebUI: ${link}`, "info");
 	}
 
+	private async openWebUI(ctx: ExtensionCommandContext): Promise<void> {
+		if (ctx.mode === "print" || ctx.mode === "json") return;
+		const activityId = ++this.activityId;
+		ctx.ui.setStatus(
+			ACTIVITY_STATUS_KEY,
+			this.server ? "Creating fresh WebUI link…" : "Starting WebUI…",
+		);
+		try {
+			await this.presentLink(ctx);
+		} finally {
+			if (activityId === this.activityId) {
+				ctx.ui.setStatus(ACTIVITY_STATUS_KEY, undefined);
+			}
+		}
+	}
+
+	private menuState(): WebUIMenuState {
+		return {
+			serverRunning: this.server !== undefined,
+			startupAutomatic: this.settings.startOnSessionStart,
+			settingsSource:
+				this.settingsDocument === undefined
+					? "Defaults (invalid file ignored)"
+					: this.settingsSource === "settings file"
+						? "Settings file"
+						: "Defaults",
+			settingsPath: this.settingsPath,
+			settingsInvalid: this.settingsDocument === undefined,
+		};
+	}
+
+	private async showMenu(ctx: ExtensionCommandContext): Promise<void> {
+		if (!ctx.hasUI) return;
+		const generation = this.generation;
+		let selectedAction: WebUIMenuAction | undefined;
+		while (generation === this.generation) {
+			const state = this.menuState();
+			let action: WebUIMenuAction | undefined;
+			if (ctx.mode === "tui") {
+				action = await ctx.ui.custom<WebUIMenuAction | undefined>(
+					(tui, theme, _keybindings, done) =>
+						createWebUIMenuComponent(state, tui, theme, done, selectedAction),
+				);
+			} else {
+				const items = webUIMenuItems(state);
+				const options = items.map((item) => `${item.label} — ${item.description ?? ""}`);
+				const selected = await ctx.ui.select(webUIMenuTitle(state), options);
+				const selectedIndex = selected === undefined ? -1 : options.indexOf(selected);
+				action = items[selectedIndex]?.value;
+			}
+			if (generation !== this.generation || !action) return;
+			selectedAction = action;
+			if (action === "open") {
+				await this.openWebUI(ctx);
+				return;
+			}
+			if (action === "settings") {
+				await this.showSettings(ctx);
+				if (generation !== this.generation) return;
+				continue;
+			}
+			if (action === "repair") {
+				await this.showDetail(ctx, "Repair WebUI settings", this.repairLines());
+				if (generation !== this.generation) return;
+				continue;
+			}
+			if (action === "status") {
+				await this.showDetail(ctx, "Pi WebUI status", this.statusLines());
+				if (generation !== this.generation) return;
+				continue;
+			}
+			await this.showDetail(ctx, "Pi WebUI help", this.helpLines());
+			if (generation !== this.generation) return;
+		}
+	}
+
+	private async showDetail(
+		ctx: ExtensionCommandContext,
+		title: string,
+		lines: readonly string[],
+	): Promise<void> {
+		if (ctx.mode === "tui") {
+			await ctx.ui.custom<void>((tui, theme, keybindings, done) =>
+				createWebUIDetailComponent(title, lines, tui, theme, keybindings, done),
+			);
+			return;
+		}
+		await ctx.ui.select([title, "", ...lines].join("\n"), ["Back"]);
+	}
+
 	private async showSettings(ctx: ExtensionCommandContext): Promise<void> {
+		if (this.settingsDocument === undefined) {
+			if (ctx.mode === "tui") {
+				await this.showDetail(ctx, "Repair WebUI settings", this.repairLines());
+			} else if (ctx.hasUI) {
+				ctx.ui.notify(this.repairLines().join("\n"), "warning");
+			}
+			return;
+		}
 		if (ctx.mode !== "tui") {
 			if (ctx.hasUI) {
 				ctx.ui.notify(`Edit WebUI settings manually: ${this.settingsPath}`, "info");
@@ -371,26 +496,35 @@ export class WebUIRuntime {
 			return;
 		}
 
+		const settingsGeneration = this.generation;
 		const items: SettingItem[] = [
 			{
 				id: "startOnSessionStart",
-				label: "Start on session start",
-				description: "Start WebUI and display a link for each newly initialized Pi session",
-				currentValue: String(this.settings.startOnSessionStart),
-				values: ["true", "false"],
+				label: "Start WebUI automatically",
+				description: "Choose whether future Pi session initializations display a WebUI link",
+				currentValue: this.settings.startOnSessionStart ? "Every session" : "Manual",
+				values: ["Manual", "Every session"],
 			},
 		];
 
 		await ctx.ui.custom((tui, theme, _keybindings, done) => {
 			const container = new Container();
-			container.addChild(new Text(theme.fg("accent", theme.bold("Pi WebUI Settings")), 1, 1));
+			const title = new Text(theme.fg("accent", theme.bold("Pi WebUI Settings")), 1, 1);
+			container.addChild(title);
+			container.addChild(
+				new Text(
+					`Changes save immediately. Startup changes apply on the next session initialization or reload.\nAdvanced settings: ${safeTerminalText(this.settingsPath)}`,
+					1,
+					0,
+				),
+			);
 			const list = new SettingsList(
 				items,
 				Math.min(items.length + 2, 15),
 				getSettingsListTheme(),
 				(id, value) => {
 					if (id !== "startOnSessionStart") return;
-					const requested = value === "true";
+					const requested = value === "Every session";
 					const operation = this.settingsSaveQueue.then(async () => {
 						const previous = this.settings.startOnSessionStart;
 						try {
@@ -407,60 +541,77 @@ export class WebUIRuntime {
 							this.settingsDocument = document;
 							this.settingsSource = "settings file";
 						} catch (error) {
-							list.updateValue(id, String(previous));
-							ctx.ui.notify(`WebUI settings save failed: ${formatError(error)}`, "error");
-							tui.requestRender();
+							if (settingsGeneration === this.generation) {
+								list.updateValue(id, previous ? "Every session" : "Manual");
+								ctx.ui.notify(`WebUI settings save failed: ${formatError(error)}`, "error");
+								tui.requestRender();
+							}
 						}
 					});
 					this.settingsSaveQueue = operation.catch(() => undefined);
 				},
 				() => done(undefined),
-				{ enableSearch: true },
+				{ enableSearch: false },
 			);
 			container.addChild(list);
 			return {
 				render: (width: number) => container.render(width),
-				invalidate: () => container.invalidate(),
+				invalidate: () => {
+					title.setText(theme.fg("accent", theme.bold("Pi WebUI Settings")));
+					container.invalidate();
+				},
 				handleInput(data: string) {
 					list.handleInput?.(data);
 					tui.requestRender();
 				},
 			};
 		});
+		await this.settingsSaveQueue;
+	}
+
+	private statusLines(): string[] {
+		const source =
+			this.settingsDocument === undefined ? "Defaults (invalid file ignored)" : this.settingsSource;
+		return [
+			`Server: ${this.server ? "Running" : "Stopped"}`,
+			`Startup: ${this.settings.startOnSessionStart ? "Every session" : "Manual"} (${source})`,
+			`Image limits (${source}): ${this.effectiveImageLimits.maxImages} images, ${formatMib(this.effectiveImageLimits.maxImageBytes)}/image, ${formatMib(this.effectiveImageLimits.maxBatchBytes)}/batch, ${this.effectiveImageLimits.maxImagePixels.toLocaleString("en-US")} pixels/image`,
+			`Settings: ${safeTerminalText(this.settingsPath)}`,
+		];
 	}
 
 	private showStatus(ctx: ExtensionCommandContext): void {
 		if (!ctx.hasUI) return;
-		const source =
-			this.settingsDocument === undefined ? "defaults (invalid file ignored)" : this.settingsSource;
-		ctx.ui.notify(
-			[
-				"Pi WebUI status",
-				`startOnSessionStart: ${this.settings.startOnSessionStart} (${source})`,
-				`Image limits (${source}): ${this.effectiveImageLimits.maxImages} images, ${formatMib(this.effectiveImageLimits.maxImageBytes)}/image, ${formatMib(this.effectiveImageLimits.maxBatchBytes)}/batch, ${this.effectiveImageLimits.maxImagePixels.toLocaleString("en-US")} pixels/image`,
-				`Settings: ${this.settingsPath}`,
-				`Server: ${this.server ? "running" : "stopped"}`,
-			].join("\n"),
-			"info",
-		);
+		ctx.ui.notify(["Pi WebUI status", ...this.statusLines()].join("\n"), "info");
+	}
+
+	private helpLines(): string[] {
+		return [
+			COMMAND_USAGE,
+			"/webui: open the current-state menu",
+			"open: start or reuse the current session server and display a fresh one-time link",
+			"settings: edit WebUI settings in TUI mode",
+			"status: show effective settings, source, path, and current server state",
+			"init: create the defaults file without overwriting existing content",
+			'Accepted JSON starts with { "startOnSessionStart": false } and may include advanced maxImages, maxImageBytes, maxBatchBytes, and maxImagePixels fields.',
+			`Settings path: ${safeTerminalText(this.settingsPath)}`,
+			"Image byte/pixel limits stay in Advanced JSON; Pi provider-ready dimension/Base64 limits are fixed.",
+			"Settings changes save immediately; startup changes apply on the next session initialization or reload.",
+		];
+	}
+
+	private repairLines(): string[] {
+		return [
+			"The settings file is invalid and was preserved without changes.",
+			"Safe defaults remain active; settings writes are paused.",
+			`File: ${safeTerminalText(this.settingsPath)}`,
+			"Repair the JSON file, then run /reload before editing settings again.",
+		];
 	}
 
 	private showHelp(ctx: ExtensionCommandContext): void {
 		if (!ctx.hasUI) return;
-		ctx.ui.notify(
-			[
-				COMMAND_USAGE,
-				"/webui: start or reuse the current session server and display a fresh one-time link",
-				"settings: edit WebUI settings in TUI mode",
-				"status: show effective settings, source, path, and current server state",
-				"init: create the defaults file without overwriting existing content",
-				'Accepted JSON starts with { "startOnSessionStart": false } and may include advanced maxImages, maxImageBytes, maxBatchBytes, and maxImagePixels fields.',
-				`Settings path: ${this.settingsPath}`,
-				"Image byte/pixel limits stay in Advanced JSON; Pi provider-ready dimension/Base64 limits are fixed.",
-				"Changes apply on the next session initialization or reload.",
-			].join("\n"),
-			"info",
-		);
+		ctx.ui.notify(this.helpLines().join("\n"), "info");
 	}
 
 	private async initializeSettings(ctx: ExtensionCommandContext): Promise<void> {