@narumitw/pi-chrome-devtools 0.50.1 → 0.52.0

package/README.md

@@ -26,10 +26,12 @@ This package is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDev
   explicit endpoint overrides.
 - Retries briefly while Chrome is starting and reports actionable endpoint errors.
 - Shows statusline activity only while Chrome DevTools tools are running.
-- Provides a state-first `/chrome-devtools` menu for tool access, browser status, setup, and help.
-- Stages menu-based tool changes for exact review before one confirmed apply.
+- Keeps one loader tool active and exposes matching browser capabilities only when the agent needs them.
+- Provides a state-first `/chrome-devtools` menu for tool availability, editable browser settings,
+  browser status, setup, and help.
+- Stages menu-based availability changes for exact review before one confirmed apply.
 - Uses `@narumitw/pi-tui-kit` for width-safe TUI menus and equivalent RPC dialogs.
-- Persists the selected Chrome DevTools tools across Pi restarts.
+- Persists the Chrome DevTools lazy-load catalog across Pi restarts.
 
 ## 📦 Install
 
@@ -51,15 +53,33 @@ pi -e ./packages/pi-chrome-devtools
 
 ## 🚀 Browser startup
 
-Without unpacked extensions, the extension first tries the configured endpoint, defaulting to
-`127.0.0.1:9222`. If that local endpoint is unavailable, it lazily launches an extension-owned
-Chromium-family browser with an isolated temp profile and retries the CDP request. Existing endpoints
-are reused and are never terminated by the extension.
+Without unpacked extensions, the extension first tries `browser.endpoint`, defaulting to
+`http://127.0.0.1:9222`. If that local endpoint is unavailable and `browser.autoLaunch` is `true`, it
+lazily launches an extension-owned Chromium-family browser with an isolated temp profile and retries
+the CDP request. Existing endpoints are reused and are never terminated by the extension.
 
-When `PI_CHROME_DEVTOOLS_PORT` is not set, auto-launch uses Chrome's dynamic DevTools port mode
-(`--remote-debugging-port=0`) and reads `DevToolsActivePort` from the temp profile. If you set a valid
-`PI_CHROME_DEVTOOLS_PORT` (`1`-`65535`), the extension uses that explicit port. Empty or invalid values
-fall back to the default attach-first behavior.
+Configure the canonical user file at
+`${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json`:
+
+```json
+{
+  "browser": {
+    "endpoint": "http://127.0.0.1:9222",
+    "autoLaunch": true,
+    "executablePath": "/absolute/path/to/chromium"
+  }
+}
+```
+
+`browser.endpoint` must be an HTTP origin with an explicit port and no credentials, path, query, or
+fragment. Omitting it keeps attach-first behavior on `127.0.0.1:9222` and lets a managed launch use
+Chrome's dynamic DevTools port mode (`--remote-debugging-port=0`). Explicitly saving an endpoint pins
+managed launches to that port. `browser.autoLaunch` defaults to `true`. `browser.executablePath` is
+optional and must be an absolute path; when absent, normal browser discovery applies.
+
+The configured endpoint must expose the standard CDP HTTP discovery routes such as `/json/version`
+and `/json/list`. Chrome's newer built-in permission flow can listen on port `9222` while returning
+`404` from those routes; setting the same HTTP origin does not by itself make that flow compatible.
 
 ### Unpacked extensions
 
@@ -67,8 +87,7 @@ fall back to the default attach-first behavior.
 > An unpacked extension executes privileged browser code. Load only code you trust. Project settings
 > are honored only when Pi reports the project as trusted.
 
-Configure the canonical user file at
-`${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json`:
+Add trusted unpacked-extension paths to the same canonical user file:
 
 ```json
 {
@@ -100,9 +119,10 @@ A trusted project can replace the user extension list in
 ```
 
 Project `extensionPaths` replace, rather than append to, the user array. A project file cannot
-override `browser.executablePath`; browser selection remains machine-owned user configuration.
-Effective precedence is defaults, user settings, trusted project override, then existing explicit
-runtime environment overrides. No new environment variable is required.
+override `browser.endpoint`, `browser.autoLaunch`, or `browser.executablePath`; browser connection
+settings remain machine-owned user configuration. Effective precedence is defaults, user settings,
+trusted project extension paths, then deprecated environment overrides. No new environment variable
+is required.
 
 When `extensionPaths` is non-empty, the extension skips attach-first behavior and starts an isolated,
 extension-owned managed browser with `--disable-extensions-except` and `--load-extension`. It fails
@@ -115,24 +135,17 @@ old managed browser is closed before the new configuration is applied. Missing f
 existing no-extension behavior. Invalid JSON, invalid browser values, and missing manifests are left
 unchanged and ignored with an actionable warning.
 
-### Environment overrides and manual endpoints
-
-`PI_CHROME_DEVTOOLS_BROWSER` remains the explicit runtime executable override. Without unpacked
-extensions, browser discovery still checks platform-specific Chrome, Chromium, Brave, and Microsoft
-Edge candidates. Disable auto-launch to keep the manual flow:
+### Deprecated environment overrides and manual endpoints
 
-```bash
-PI_CHROME_DEVTOOLS_AUTO_LAUNCH=0 pi -e ./packages/pi-chrome-devtools
-```
+The existing `PI_CHROME_DEVTOOLS_HOST`, `PI_CHROME_DEVTOOLS_PORT`,
+`PI_CHROME_DEVTOOLS_AUTO_LAUNCH`, and `PI_CHROME_DEVTOOLS_BROWSER` variables remain temporary
+compatibility overrides. They still take precedence over JSON, but every session that sees one emits
+a deprecation warning. Move their values to `browser.endpoint`, `browser.autoLaunch`, and
+`browser.executablePath`; the variables will be removed in a future version.
 
-Force an executable or endpoint if needed:
-
-```bash
-PI_CHROME_DEVTOOLS_BROWSER=/usr/bin/chromium pi -e ./packages/pi-chrome-devtools
-PI_CHROME_DEVTOOLS_HOST=127.0.0.1 PI_CHROME_DEVTOOLS_PORT=9223 pi -e ./packages/pi-chrome-devtools
-```
-
-Manual launch remains available when no unpacked extensions are configured:
+Without unpacked extensions, browser discovery still checks platform-specific Chrome, Chromium,
+Brave, and Microsoft Edge candidates. Manual launch remains available when no unpacked extensions are
+configured:
 
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pi-chrome-devtools
@@ -143,12 +156,31 @@ removes their temporary profiles. It never closes user-started browsers or remot
 
 ## 🛠️ Pi tools
 
+- `chrome_devtools_load` — find and load browser capabilities relevant to a task.
 - `chrome_devtools_list_pages` — list inspectable Chrome tabs/pages.
 - `chrome_devtools_select_page` — select the active page for later tool calls.
 - `chrome_devtools_navigate` — navigate a page to a URL; if no page exists, create one first.
 - `chrome_devtools_evaluate` — evaluate JavaScript in the selected page.
 - `chrome_devtools_screenshot` — capture a PNG screenshot and save it as a PNG file.
 
+### Lazy tool loading
+
+All six tools are registered, but only `chrome_devtools_load` starts active for this extension.
+
+The loader accepts a task-oriented `query`, matches it against the five capability tools, and adds matching available tools without removing any active Pi tool.
+
+Loaded capability tools remain active for the rest of the session unless the user makes them unavailable through `/chrome-devtools`.
+
+Pi uses native deferred tool references on compatible Anthropic and OpenAI models.
+
+Other models receive Pi's safe fallback: the newly active definitions appear in the normal tool list on the next model request.
+
+The capability tools omit active-only prompt snippets so a lazy load does not rebuild the system prompt prefix.
+
+The saved `tools` array controls which capabilities the loader may expose.
+
+An empty array leaves the loader active but makes every browser capability unavailable.
+
 ### Screenshot files
 
 `chrome_devtools_screenshot` always saves the captured PNG to disk. If `savePath` is omitted,
@@ -182,17 +214,19 @@ to read the saved path, for example `read({ path: "artifacts/homepage.png" })`.
 /chrome-devtools
 ```
 
-Opens a menu that shows the current browser-tool count, whether that selection is saved, the
-configured endpoint, the observed managed-browser state, and any settings or launch warning before
-you choose an action. The five actions stay on one level:
+Opens a menu that shows the lazy catalog size, whether that catalog is saved, the configured
+endpoint, the observed managed-browser state, and any settings or launch warning before you choose
+an action. The five actions stay on one level:
 
-- **Choose browser tools…** — stage any combination of the five capabilities, then review the exact
-  enabled/disabled result before selecting **Apply tool changes**.
-- **Enable all browser tools…** or **Disable all browser tools…** — preview the context-appropriate
-  bulk change before applying it.
+- **Choose available browser tools…** — stage any combination of the five capabilities, then review
+  the exact available/unavailable result before selecting **Apply tool changes**.
+- **Make all browser tools available…** or **Make all browser tools unavailable…** — preview the
+  context-appropriate bulk change before applying it.
 - **Browser status** — inspect runtime, endpoint, launch mode, and the last launch attempt without
   probing the endpoint or starting Chrome.
-- **Settings & setup** — inspect effective files, sources, trust, reload steps, and recovery guidance.
+- **Browser settings** — immediately save the endpoint, auto-launch policy, or browser executable;
+  inspect unpacked-extension paths and effective sources. A deprecated environment override remains
+  effective until removed even when its underlying JSON value changes.
 - **Help** — view command usage and return to the menu.
 
 In the tool screen, **Select all** and **Select none** are unambiguous shortcuts; individual rows use
@@ -200,8 +234,8 @@ friendly task labels while retaining their raw `chrome_devtools_*` identity in t
 Toggles remain a command-local draft. **Review changes** previews the exact effect, **Apply tool
 changes** saves it, and Cancel, Escape, Ctrl+C, disposal, or session replacement discards an
 unconfirmed draft without changing runtime tools or settings. A failed apply restores the previous
-active-tool state, preserves the settings file, retains the draft for retry, and reports how to
-recover.
+availability and loaded-tool state, preserves the settings file, retains the draft for retry, and
+reports how to recover.
 
 Direct subcommands are also available:
 
@@ -209,6 +243,7 @@ Direct subcommands are also available:
 /chrome-devtools help
 /chrome-devtools quickstart
 /chrome-devtools status
+/chrome-devtools settings
 /chrome-devtools tools
 /chrome-devtools toggle
 /chrome-devtools enable
@@ -221,34 +256,44 @@ Compatibility aliases remain available: `toggle` and `select` mean `tools`, `on`
 - `help` shows command usage.
 - `quickstart` shows the configured CDP endpoint, endpoint source, auto-launch mode, browser
   candidates, last launch attempt, and launch hints.
-- `status` shows runtime tool state, persisted selection, settings file path, endpoint source,
-  launch mode, last launch attempt, and active non-Chrome tool count.
-- `tools` opens the same staged, width-safe selection and review flow used by the menu.
+- `status` shows available and loaded capability counts, loader state, the persisted catalog,
+  settings file path, endpoint source, launch mode, last launch attempt, and active non-Chrome tool
+  count.
+- `settings` opens the same immediate-save browser settings flow used by the menu.
+- `tools` opens the same staged, width-safe availability and review flow used by the menu.
 - `toggle` and `select` are compatibility aliases for `tools`.
-- `enable` immediately enables and saves all `chrome_devtools_*` tools for future turns; `on` is a
+- `enable` makes all five capability tools available to the loader and saves that catalog; `on` is a
   compatibility alias.
-- `disable` immediately disables and saves all `chrome_devtools_*` tools for future turns; `off` is a
-  compatibility alias. The slash command remains available.
+- `disable` makes all five capability tools unavailable and saves the empty catalog; `off` is a
+  compatibility alias. The slash command and `chrome_devtools_load` remain available.
+
+The menu, `settings`, `tools`, `help`, `quickstart`, and `status` require TUI or RPC mode so their
+result is observable. TUI uses keyboard navigation and injected Pi keybindings; RPC receives
+equivalent standard dialogs. In print and JSON modes, interactive and informational routes reject
+explicitly instead of silently opening unavailable UI. The immediate `enable`/`disable` routes remain
+available for deterministic non-interactive use.
 
-The menu, `tools`, `help`, `quickstart`, and `status` require TUI or RPC mode so their result is
-observable. TUI uses keyboard navigation and injected Pi keybindings; RPC receives equivalent
-standard dialogs. In print and JSON modes, interactive and informational routes reject explicitly
-instead of silently opening unavailable UI. The immediate `enable`/`disable` routes remain available
-for deterministic non-interactive use.
+## ⚙️ Settings
 
-The selected tool names are saved to:
+The available capability names are saved to:
 
 ```text
 ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json
 ```
 
-When the file is missing or invalid, the extension preserves Pi's current active-tool policy
-instead of enabling tools by itself. A valid saved selection is restored on Pi startup and
-`/reload`. A missing file is created by the first confirmed menu apply or successful direct
-selection change. Within one Pi process, selection saves run in invocation order, reread the latest
-valid document, and preserve unknown fields. Malformed JSON or invalid recognized fields make menu
-mutation unavailable and block direct saves without replacement; a failed save restores the prior
-Chrome DevTools tool selection while preserving other extensions' current tools.
+The same file owns `browser.endpoint`, `browser.autoLaunch`, `browser.executablePath`, and
+`browser.extensionPaths`. Browser connection fields are machine-owned user settings; trusted project
+files may replace only `browser.extensionPaths`. Confirmed menu changes apply before the next browser
+connection and close only an extension-owned managed browser. Manual JSON edits and unpacked-extension
+changes apply after `/reload` or session replacement.
+
+When the file is missing or invalid, the extension preserves Pi's current Chrome DevTools
+availability policy instead of replacing it. A valid saved catalog is restored on Pi startup and
+`/reload`, while its capability definitions remain deferred. A missing file is created by the first
+confirmed browser or tool setting. Within one Pi process, all browser and tool saves run in invocation
+order, reread the latest valid document, publish by temporary-file rename, and preserve unknown
+fields. Malformed JSON or invalid recognized fields make menu mutation unavailable and block direct
+saves without replacement; a failed save restores the prior displayed and effective state.
 
 Compatibility: older versions used `pi-chrome-devtools-settings.json`. A legacy-only file remains
 readable with a warning and is never modified automatically; rename it to
@@ -271,6 +316,7 @@ packages/pi-chrome-devtools/
 ├── src/
 │   ├── index.ts            # Pi package entrypoint
 │   ├── chrome-devtools.ts  # Extension registration and command orchestration
+│   ├── lazy-tools.ts       # Deferred capability catalog and loader tool
 │   └── *.ts                # Package-local browser, CDP, tool, and storage modules
 ├── README.md
 ├── LICENSE

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-chrome-devtools",
-	"version": "0.50.1",
+	"version": "0.52.0",
 	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
 	"type": "module",
 	"license": "MIT",

package/src/browser-manager.ts

@@ -143,7 +143,7 @@ async function prepareManagedBrowserLaunch(
 		throwIfBrowserLaunchCancelled(generation, signal);
 		if (!available) {
 			throw new DevToolsEndpointError(
-				`Cannot launch the extension-owned browser because explicit port ${state.port} is already in use. Choose a free PI_CHROME_DEVTOOLS_PORT or remove the override for a dynamic port.`,
+				`Cannot launch the extension-owned browser because explicit port ${state.port} is already in use. Choose a free browser.endpoint port or reset the endpoint to use a dynamic managed port.`,
 			);
 		}
 	}
@@ -609,9 +609,7 @@ export function formatHostForUrl(host: string) {
 }
 
 export function endpointSourceLabel() {
-	const hostSource = state.hostConfigured ? "PI_CHROME_DEVTOOLS_HOST" : "default host";
-	const portSource = state.portConfigured ? "PI_CHROME_DEVTOOLS_PORT" : "default/dynamic port";
-	return `${hostSource}; ${portSource}`;
+	return state.endpointSource;
 }
 
 export type BrowserLifecycleState = "starting" | "running" | "exited" | "failed" | "unobserved";
@@ -710,7 +708,7 @@ export function quoteCommandPart(value: string) {
 }
 
 export function endpointConfigHint() {
-	return "Set PI_CHROME_DEVTOOLS_HOST and PI_CHROME_DEVTOOLS_PORT for a manual endpoint, PI_CHROME_DEVTOOLS_BROWSER to choose an executable, or PI_CHROME_DEVTOOLS_AUTO_LAUNCH=0 to disable auto-launch.";
+	return "Configure browser.endpoint, browser.executablePath, and browser.autoLaunch in pi-chrome-devtools.json or the /chrome-devtools Settings flow.";
 }
 
 export function isLocalDevToolsHost(host: string) {

package/src/browser-settings-menu.ts

@@ -0,0 +1,311 @@
+import { isAbsolute } from "node:path";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { shutdownManagedBrowser } from "./browser-manager.js";
+import { applyRuntimeBrowserSettings, state } from "./runtime.js";
+import {
+	type BrowserSettingsPatch,
+	type BrowserSettingsSource,
+	loadSettings,
+	parseBrowserEndpoint,
+	type SettingsLoadResult,
+	saveBrowserSettings,
+} from "./settings.js";
+import { sanitizeChromeDevtoolsDisplay } from "./tool-selector.js";
+
+type BrowserSettingsScreen = "settings" | "endpoint" | "executable" | "extensions";
+type BrowserSettingsAction =
+	| "open-endpoint"
+	| "save-endpoint"
+	| "set-auto-launch"
+	| "open-executable"
+	| "save-executable"
+	| "show-extensions";
+
+interface BrowserSettingsMenuState {
+	load: SettingsLoadResult;
+}
+
+type CommandContext = ExtensionCommandContext;
+
+export async function showChromeDevtoolsBrowserSettings(
+	ctx: CommandContext,
+	generation: number,
+): Promise<{ closeParent: boolean }> {
+	const ownerSignal = state.sessionController.signal;
+	const isCurrent = () => generation === state.sessionGeneration && !ownerSignal.aborted;
+	const projectTrusted = ctx.isProjectTrusted();
+	const menu = defineMenu<BrowserSettingsMenuState, BrowserSettingsScreen, BrowserSettingsAction>({
+		start: "settings",
+		screens: {
+			settings: ({ state: current }) => {
+				if (current.load.userFile.kind === "invalid") return invalidSettingsScreen(current.load);
+				const browser = current.load.effectiveBrowser;
+				return {
+					kind: "settings",
+					title: "Chrome DevTools Browser settings",
+					lines: settingsContextLines(current.load),
+					items: [
+						{
+							id: "endpoint",
+							label: "DevTools endpoint",
+							description:
+								'HTTP origin with an explicit port; enter "default" to restore 127.0.0.1:9222.',
+							currentValue: sanitizeChromeDevtoolsDisplay(browser.endpoint),
+							action: "open-endpoint",
+						},
+						{
+							id: "auto-launch",
+							label: "Auto-launch",
+							description:
+								"Launch an isolated managed browser when a local endpoint is unavailable.",
+							currentValue: browser.autoLaunchEnabled ? "On" : "Off",
+							values: ["On", "Off"],
+							action: "set-auto-launch",
+						},
+						{
+							id: "executable",
+							label: "Browser executable",
+							description:
+								'Absolute executable path; enter "automatic" to restore browser discovery.',
+							currentValue: sanitizeChromeDevtoolsDisplay(browser.executablePath ?? "Automatic"),
+							action: "open-executable",
+						},
+						{
+							id: "extensions",
+							label: "Unpacked extensions",
+							description: "Inspect trusted extension paths configured in user or project JSON.",
+							currentValue: `${browser.extensionPaths.length} configured`,
+							action: "show-extensions",
+						},
+					],
+				};
+			},
+			endpoint: ({ state: current }) => ({
+				kind: "input",
+				title: "DevTools endpoint",
+				lines: [
+					sanitizeChromeDevtoolsDisplay(
+						`Current effective endpoint: ${current.load.effectiveBrowser.endpoint}`,
+					),
+					'Enter an HTTP origin with an explicit port, or "default".',
+				],
+				placeholder: "http://127.0.0.1:9222",
+				action: "save-endpoint",
+				hint: "back",
+			}),
+			executable: ({ state: current }) => ({
+				kind: "input",
+				title: "Browser executable",
+				lines: [
+					sanitizeChromeDevtoolsDisplay(
+						`Current effective executable: ${current.load.effectiveBrowser.executablePath ?? "automatic discovery"}`,
+					),
+					'Enter an absolute path, or "automatic".',
+				],
+				placeholder: "absolute browser executable path",
+				action: "save-executable",
+				hint: "back",
+			}),
+			extensions: ({ state: current }) => ({
+				kind: "detail",
+				title: "Unpacked extensions",
+				lines: extensionDetailLines(current.load),
+				hint: "back",
+			}),
+		},
+		actions: {
+			"open-endpoint": () => ({ kind: "to", screen: "endpoint" }),
+			"save-endpoint": async ({ value, signal }) => {
+				if (value === undefined) return { kind: "rejected" };
+				let endpoint: string | null;
+				try {
+					const trimmed = value.trim();
+					endpoint =
+						trimmed.toLowerCase() === "default" ? null : parseBrowserEndpoint(trimmed).endpoint;
+				} catch (error) {
+					notifySaveFailure(ctx, error);
+					return { kind: "rejected" };
+				}
+				const saved = await saveAndApplyBrowserPatch(
+					ctx,
+					generation,
+					ownerSignal,
+					signal,
+					projectTrusted,
+					{ endpoint },
+				);
+				if (!saved) return { kind: "rejected" };
+				notifyEffectiveSave(
+					ctx,
+					"endpoint",
+					saved.effectiveBrowser.endpoint,
+					saved.effectiveBrowser.endpointSource,
+				);
+				return { kind: "back" };
+			},
+			"set-auto-launch": async ({ value, signal }) => {
+				if (value !== "On" && value !== "Off") return { kind: "rejected" };
+				const saved = await saveAndApplyBrowserPatch(
+					ctx,
+					generation,
+					ownerSignal,
+					signal,
+					projectTrusted,
+					{ autoLaunch: value === "On" },
+				);
+				if (!saved) return { kind: "rejected" };
+				notifyEffectiveSave(
+					ctx,
+					"auto-launch",
+					saved.effectiveBrowser.autoLaunchEnabled ? "On" : "Off",
+					saved.effectiveBrowser.autoLaunchSource,
+				);
+				return { kind: "stay" };
+			},
+			"open-executable": () => ({ kind: "to", screen: "executable" }),
+			"save-executable": async ({ value, signal }) => {
+				if (value === undefined) return { kind: "rejected" };
+				const trimmed = value.trim();
+				const reset = ["automatic", "default", "none"].includes(trimmed.toLowerCase());
+				if (!reset && (!trimmed || !isAbsolute(trimmed))) {
+					notifySaveFailure(ctx, new Error('Enter an absolute path or "automatic".'));
+					return { kind: "rejected" };
+				}
+				const executablePath = reset ? null : trimmed;
+				const saved = await saveAndApplyBrowserPatch(
+					ctx,
+					generation,
+					ownerSignal,
+					signal,
+					projectTrusted,
+					{ executablePath },
+				);
+				if (!saved) return { kind: "rejected" };
+				notifyEffectiveSave(
+					ctx,
+					"browser executable",
+					saved.effectiveBrowser.executablePath ?? "automatic discovery",
+					saved.effectiveBrowser.executablePathSource,
+				);
+				return { kind: "back" };
+			},
+			"show-extensions": () => ({ kind: "to", screen: "extensions" }),
+		},
+	});
+	const result = await runMenu(ctx, menu, {
+		getState: async ({ signal }) => {
+			signal.throwIfAborted();
+			const load = await loadSettings({ cwd: ctx.cwd, projectTrusted });
+			signal.throwIfAborted();
+			return { load };
+		},
+		signal: ownerSignal,
+		isCurrent,
+		onError: (currentCtx, error) =>
+			currentCtx.ui.notify(
+				sanitizeChromeDevtoolsDisplay(
+					`Chrome DevTools browser settings failed: ${formatError(error)}`,
+				),
+				"error",
+			),
+	});
+	return { closeParent: result.kind === "closed" && result.reason === "close" };
+}
+
+async function saveAndApplyBrowserPatch(
+	ctx: CommandContext,
+	generation: number,
+	ownerSignal: AbortSignal,
+	actionSignal: AbortSignal,
+	projectTrusted: boolean,
+	patch: BrowserSettingsPatch,
+) {
+	try {
+		await ctx.waitForIdle();
+		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
+		await saveBrowserSettings(patch);
+		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
+		await shutdownManagedBrowser();
+		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
+		const loaded = await loadSettings({ cwd: ctx.cwd, projectTrusted });
+		if (!isCurrent(generation, ownerSignal, actionSignal)) return false;
+		applyRuntimeBrowserSettings(loaded.effectiveBrowser, loaded.paths, projectTrusted);
+		state.settingsNotice = loaded.notice;
+		return loaded;
+	} catch (error) {
+		if (isCurrent(generation, ownerSignal, actionSignal)) notifySaveFailure(ctx, error);
+		return false;
+	}
+}
+
+function isCurrent(generation: number, ownerSignal: AbortSignal, actionSignal: AbortSignal) {
+	return generation === state.sessionGeneration && !ownerSignal.aborted && !actionSignal.aborted;
+}
+
+function invalidSettingsScreen(load: SettingsLoadResult) {
+	const reason =
+		load.userFile.kind === "invalid"
+			? load.userFile.reason
+			: "The user settings file is unavailable.";
+	return {
+		kind: "detail" as const,
+		title: "Chrome DevTools Browser settings · Read only",
+		lines: [
+			sanitizeChromeDevtoolsDisplay(
+				`Fix the active user settings before saving; the file will not be overwritten. ${reason}`,
+			),
+		],
+		hint: "back" as const,
+	};
+}
+
+function settingsContextLines(load: SettingsLoadResult) {
+	const browser = load.effectiveBrowser;
+	return [
+		`User settings · ${load.paths.user}`,
+		`Effective sources: endpoint ${browser.endpointSource} · auto-launch ${browser.autoLaunchSource} · executable ${browser.executablePathSource}`,
+		...(load.notice ? [`Warning: ${load.notice}`] : []),
+	].map((line) => sanitizeChromeDevtoolsDisplay(line));
+}
+
+function extensionDetailLines(load: SettingsLoadResult) {
+	const browser = load.effectiveBrowser;
+	return [
+		`Effective source: ${browser.extensionPathsSource}`,
+		...(browser.extensionPaths.length > 0
+			? browser.extensionPaths.map((extensionPath) => `- ${extensionPath}`)
+			: ["No unpacked extensions are configured."]),
+		"Edit browser.extensionPaths in the user JSON or a trusted project JSON, then run /reload.",
+		"Unpacked extensions execute privileged browser code; load only paths you trust.",
+	].map((line) => sanitizeChromeDevtoolsDisplay(line));
+}
+
+function notifyEffectiveSave(
+	ctx: CommandContext,
+	setting: string,
+	effectiveValue: string,
+	source: BrowserSettingsSource,
+) {
+	const overrideNotice =
+		source === "environment" ? " The deprecated environment override remains effective." : "";
+	ctx.ui.notify(
+		sanitizeChromeDevtoolsDisplay(
+			`Chrome DevTools ${setting} saved. Effective ${setting}: ${effectiveValue} (${source}).${overrideNotice}`,
+		),
+		"info",
+	);
+}
+
+function notifySaveFailure(ctx: CommandContext, error: unknown) {
+	ctx.ui.notify(
+		sanitizeChromeDevtoolsDisplay(
+			`Chrome DevTools browser settings save failed; previous settings remain active: ${formatError(error)}`,
+		),
+		"warning",
+	);
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}