pi-lean-portal 0.5.0 → 0.7.0

package/README.md

@@ -16,9 +16,10 @@
 
 ```bash
 pi install npm:pi-lean-portal
-npx playwright install chromium firefox
 ```
 
+Then run **`/web install`** inside pi to download browser binaries (these are not installed via npm).
+
 Once loaded, you'll see a notification like:
 
 > 🌐 Browser extension loaded (plugins: chromium, firefox). Try: web-fetch for static pages or browser-navigate for interactive browsing.
@@ -27,10 +28,6 @@ The browser tools are **enabled by default**: `web-fetch` for static pages,
 `browser-navigate` (plus click/type/scroll/screenshots via `@e` refs) for
 interactive browsing.
 
-> **Playwright browser binaries are not downloaded during `npm install`.**
-> Run `npx playwright install chromium firefox` separately. On first
-> `browser-navigate` without them, you'll be prompted with the exact command.
-
 ---
 
 ## `/web` Command — Browser Toggle & Profiles
@@ -51,13 +48,16 @@ toggles guide-saving mode, and manages browser profiles.
 | Command | Effect |
 | ------- | ------ |
 | `/web` | Show current toggle status and available sub-commands. |
-| `/web status` | **Detailed runtime status** including toggle state, plugin health, active sessions, and profiles on disk. |
+| `/web status` | **Detailed runtime status** including toggle state, plugin health, browser-binary presence, active sessions, and profiles on disk. |
+| `/web install` | **Install browser binaries** via the bundled playwright CLI (checkbox dialog in the TUI; prints the manual command elsewhere). |
+| `/web install chromium\|firefox` | Directly download one engine, no dialog. |
 
 ```text
 🌐 Browser tools: ✅ on  |  📖 Learn mode: ❌ off
 ────────────────────────────────────────
 Status: idle
 Plugins: chromium, firefox, chromium-py (disabled), firefox-py (disabled)
+Browsers: chromium ✓ firefox ✓
 Use web-fetch for stateless HTTP fetches.
 Active sessions: 1
   PW [chromium] https://example.com — Example Domain [profile: session]
@@ -225,9 +225,9 @@ and the router dispatches tool calls to the right plugin based on a
 | `chromium-py` | Chromium | Python/Playwright | Disabled |
 | `firefox-py` | Firefox | Python/Playwright | Disabled |
 
-> **Install Firefox:** `npx playwright install firefox` to use the Node
-> `firefox` backend. For the Python parity backends, install Playwright
-> inside `backends/python-base/.venv`.
+> **Install Firefox:** run `/web install firefox` inside pi to download the
+> Firefox binary for the Node `firefox` backend. For the Python parity
+> backends, install Playwright inside `backends/python-base/.venv`.
 
 All four shipped backends support screenshots (viewport-sized, not
 full-page), console capture, JS evaluation, bot detection, and dialog
@@ -331,8 +331,8 @@ the toolset's packaged default:
 - Omit a `toolsetDefaults` key to use the toolset's packaged default (`web`
   and `search` default `true`; `web-learn` defaults `false`).
 - The `search` key only applies when `pi-lean-search` is installed.
-- Pins do not apply in spawned subagent children (see pi-tool-masking
-  1.3.0's `piToolMasking.childPolicy` for the opt-out).
+- Pins do not apply in spawned subagent children (see pi-tool-masking's
+  `piToolMasking.childPolicy` for the opt-out).
 
 ### `browser.maxStorageStateSize`
 

package/backends/chromium/index.ts

@@ -35,7 +35,7 @@ export class ChromiumPlugin extends PlaywrightPluginBase {
 	}
 
 	protected get installHint(): string {
-		return "Browser not installed. Run: npx playwright install chromium firefox";
+		return "Browser not installed. Run /web install to install it.";
 	}
 }
 

package/backends/firefox/index.ts

@@ -54,7 +54,7 @@ export class FirefoxPlugin extends PlaywrightPluginBase {
 	}
 
 	protected get installHint(): string {
-		return "Browser not installed. Run: npx playwright install chromium firefox";
+		return "Browser not installed. Run /web install to install it.";
 	}
 }
 

package/backends/playwright-base/playwright-plugin.ts

@@ -83,7 +83,7 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 
 	/**
 	 * Engine-specific install hint, shown when the browser executable
-	 * is not installed. Example: "Run: npx playwright install firefox".
+	 * is not installed, e.g. "Browser not installed. Run /web install to install it".
 	 */
 	protected abstract get installHint(): string;
 

package/backends/python-base/pi_browser_bridge/playwright_base.py

@@ -38,6 +38,7 @@ contexts across tasks.
 """
 
 import base64
+import contextlib
 import json
 import os
 import re
@@ -299,13 +300,14 @@ class PlaywrightBridge:
     _csp_safe_readonly_via_init_script: bool = False
 
     #: When non-zero, ``_wait_for_navigation_settle`` uses this as the
-    #: settle poll budget (ms) instead of the default 400.  Stealth backends
+    #: settle poll budget (ms) instead of the default.  Stealth backends
     #: whose patched browser fires navigation events with higher latency
     #: (e.g. Camoufox's Juggler) set a larger value to avoid settling before
-    #: the navigation commit is observable.  Default 400 matches the
-    #: historical hard-coded value so shipped chromium-py / firefox-py are
-    #: unchanged.
-    _settle_budget_ms: int = 400
+    #: the navigation commit is observable.  Default reads
+    #: ``navSettle.settleTimeoutMs`` from the shared TS↔Python parity JSON
+    #: (``browser-data.json``) so both runtimes stay in lockstep; shipped
+    #: chromium-py / firefox-py are unchanged.
+    _settle_budget_ms: int = NAV_SETTLE["settleTimeoutMs"]
 
     #: When True, ``_wait_for_navigation_settle`` switches the no-nav
     #: polling branch from a fixed budget to "URL stable for 150 ms **or**
@@ -448,10 +450,8 @@ class PlaywrightBridge:
             self._log("captureUA", success=False, ua="(fallback)")
         finally:
             if page is not None:
-                try:
+                with contextlib.suppress(Exception):
                     page.close()
-                except Exception:
-                    pass
 
     # ── Debug logging ───────────────────────────────────────────
 
@@ -518,15 +518,11 @@ class PlaywrightBridge:
     def _maybe_stop_playwright(self) -> None:
         """Stop the shared Playwright if no sessions remain."""
         if not self.sessions and self._pw is not None:
-            try:
-                if self._browser:
+            if self._browser:
+                with contextlib.suppress(Exception):
                     self._browser.close()
-            except Exception:
-                pass
-            try:
+            with contextlib.suppress(Exception):
                 self._pw.stop()
-            except Exception:
-                pass
             self._pw = None
             self._browser = None
 
@@ -577,7 +573,7 @@ class PlaywrightBridge:
         # Start Playwright trace capture if BROWSER_TRACE_DIR is set.
         _trace_dir = os.environ.get("BROWSER_TRACE_DIR")
         if _trace_dir:
-            try:
+            with contextlib.suppress(Exception):
                 context.tracing.start(
                     screenshots=True,
                     snapshots=True,
@@ -588,9 +584,7 @@ class PlaywrightBridge:
                     taskId=config.get("_task_id", "shared"),
                     action="start",
                     dir=_trace_dir,
-                )
-            except Exception:
-                pass  # Best-effort
+                )  # Best-effort
 
         # CSP-safe read-only eval path (see _csp_safe_readonly_via_init_script).
         # Registers an init script that stashes the EXTRACTOR_SCRIPT result in
@@ -749,12 +743,10 @@ class PlaywrightBridge:
         if session is not None:
             context: Any = session.get("context")
 
-            try:
-                page: Any = session.get("page")
-                if page and not page.is_closed():
+            page: Any = session.get("page")
+            if page and not page.is_closed():
+                with contextlib.suppress(Exception):
                     page.close()
-            except Exception:
-                pass
 
             # Stop and save Playwright trace if BROWSER_TRACE_DIR is set.
             _trace_dir = os.environ.get("BROWSER_TRACE_DIR")
@@ -767,14 +759,15 @@ class PlaywrightBridge:
                     )
                     context.tracing.stop(path=_trace_path)
                     self._log("tracing", taskId=task_id, action="stop", dir=_trace_dir)
-                except Exception:
-                    pass
+                except Exception as exc:
+                    # Best-effort: a failed trace save must not fail cleanup.
+                    self._log(
+                        "tracing", taskId=task_id, action="stop-failed", error=str(exc)
+                    )
 
-            try:
-                if context:
+            if context:
+                with contextlib.suppress(Exception):
                     context.close()
-            except Exception:
-                pass
 
         # Remove session + element cache
         self.sessions.pop(task_id, None)
@@ -926,15 +919,11 @@ class PlaywrightBridge:
                 stealth patched-Firefox binaries don't fire it reliably and
                 loitering for it can deadlock the Juggler driver.
         """
-        try:
+        with contextlib.suppress(Exception):
             page.wait_for_load_state("load", timeout=timeout_ms)
-        except Exception:
-            pass
         if not skip_networkidle:
-            try:
+            with contextlib.suppress(Exception):
                 page.wait_for_load_state("networkidle", timeout=timeout_ms)
-            except Exception:
-                pass
 
     def _wait_for_navigation_settle(
         self,
@@ -974,8 +963,10 @@ class PlaywrightBridge:
         page.on("framenavigated", _on_nav)
 
         try:
-            # Wait for a potential navigation to start (150 ms window)
-            page.wait_for_timeout(150)
+            # Wait for a potential navigation to start (shared race window,
+            # ``navSettle.settleRaceMs`` in browser-data.json — same value
+            # the TS nav-settle races against ``framenavigated``).
+            page.wait_for_timeout(NAV_SETTLE["settleRaceMs"])
 
             waited_for_load = False
             if navigated:
@@ -1099,13 +1090,12 @@ class PlaywrightBridge:
                     break
 
         # ── DOM stabilization wait ──────────────────────────────
-        try:
+        # Stabilization timeout is best-effort — proceed.
+        with contextlib.suppress(Exception):
             page.wait_for_function(
                 _DOM_STABILIZE_JS,
                 timeout=NAV_SETTLE["navTimeoutMs"],
             )
-        except Exception:
-            pass  # Stabilization timed out — proceed
 
         # ── Bot detection ───────────────────────────────────────
         bot_detected = check_bot_detection(page)
@@ -1270,7 +1260,7 @@ class PlaywrightBridge:
 
         try:
             locator.click(timeout=5_000)  # Focus first
-            locator.fill(text)
+            locator.fill(text, timeout=5_000)
 
             result = self._build_interaction_result(task_id, page)
         except Exception as exc:
@@ -1331,11 +1321,9 @@ class PlaywrightBridge:
 
             new_url: str | None = None
             new_title: str | None = None
-            try:
+            with contextlib.suppress(Exception):
                 new_url = page.url
                 new_title = page.title()
-            except Exception:
-                pass
 
             extra: dict[str, Any] = {}
             if new_url is not None:
@@ -1554,20 +1542,18 @@ class PlaywrightBridge:
             # ponytail: single retry, no backoff — challenge pages settle in
             # one load cycle; add exponential backoff if a real challenge
             # needs >1 retry.
-            # Nested ifs (rather than
-            # `self._wrap_mw_eval_in_eval and "Execution context was destroyed" in err_msg`)
-            # keep the no-boolean-in-except lint calm; behavior is identical.
+            retry_destroyed = False
             if self._wrap_mw_eval_in_eval:
-                if "Execution context was destroyed" in err_msg:
-                    try:
-                        page.wait_for_load_state("load")
-                    except Exception:
-                        pass  # Best-effort: proceed to retry even if wait fails
-                    try:
-                        result = page.evaluate(effective_expression)
-                        return {"success": True, "result": result}
-                    except Exception as retry_exc:
-                        return {"success": False, "error": str(retry_exc)}
+                retry_destroyed = "Execution context was destroyed" in err_msg
+            if retry_destroyed:
+                # Best-effort: proceed to retry even if wait fails
+                with contextlib.suppress(Exception):
+                    page.wait_for_load_state("load")
+                try:
+                    result = page.evaluate(effective_expression)
+                    return {"success": True, "result": result}
+                except Exception as retry_exc:
+                    return {"success": False, "error": str(retry_exc)}
             return {
                 "success": False,
                 "error": err_msg,

package/backends/python-base/pi_browser_bridge/transport.py

@@ -21,9 +21,7 @@ Error response::
 
 import json
 import sys
-import traceback
-from typing import Any, Optional
-
+from typing import Any
 
 # ─── Standard JSON-RPC error codes ────────────────────────────────────
 
@@ -31,7 +29,6 @@ PARSE_ERROR = -32700
 INVALID_REQUEST = -32600
 METHOD_NOT_FOUND = -32601
 INVALID_PARAMS = -32602
-INTERNAL_ERROR = -32603
 
 # Custom error codes (application-level)
 APPLICATION_ERROR = -32000
@@ -50,7 +47,8 @@ class InvalidRequestError(ValueError):
 
 # ─── Reading requests ─────────────────────────────────────────────────
 
-def read_request() -> Optional[dict[str, Any]]:
+
+def read_request() -> dict[str, Any] | None:
     """Read one JSON-RPC request from stdin (line-delimited).
 
     Returns the parsed request dict, or None on EOF.
@@ -86,6 +84,7 @@ def read_request() -> Optional[dict[str, Any]]:
 
 # ─── Writing responses ────────────────────────────────────────────────
 
+
 def write_response(response: dict[str, Any]) -> None:
     """Write a JSON-RPC response to stdout as a single JSON line, then flush.
 
@@ -110,7 +109,7 @@ def make_error_response(
     request_id: Any,
     code: int,
     message: str,
-    data: Optional[dict[str, Any]] = None,
+    data: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Build a JSON-RPC error response."""
     error: dict[str, Any] = {
@@ -136,24 +135,10 @@ def make_invalid_request(request_id: Any = None) -> dict[str, Any]:
     return make_error_response(request_id, INVALID_REQUEST, "Invalid Request")
 
 
-def make_internal_error(
-    request_id: Any,
-    exc: Exception,
-) -> dict[str, Any]:
-    """Build an internal error response including Python traceback."""
-    tb = traceback.format_exception(type(exc), exc, exc.__traceback__)
-    return make_error_response(
-        request_id,
-        INTERNAL_ERROR,
-        f"Internal error: {exc}",
-        data={"traceback": "".join(tb)},
-    )
-
-
 def make_application_error(
     request_id: Any,
     message: str,
-    traceback_str: Optional[str] = None,
+    traceback_str: str | None = None,
 ) -> dict[str, Any]:
     """Build an application-level error response."""
     data: dict[str, Any] = {}

package/browser-install.ts

@@ -0,0 +1,454 @@
+/**
+ * Browser Install — `/web install` subcommand.
+ *
+ * The `playwright` npm package ships no browser binaries, and the generic
+ * `npx playwright install` advice can resolve a different playwright copy
+ * than the one the backends import — installing revisions the backends
+ * don't match. This command resolves the *bundled* playwright CLI (the same
+ * copy the backends use) and downloads engines from it, guaranteeing
+ * revision parity.
+ *
+ * Forms:
+ *   /web install            — checkbox dialog (TUI only; other modes print
+ *                             the manual bundled-CLI command)
+ *   /web install chromium   — direct download, no dialog (TUI + RPC spawn;
+ *                             print/JSON modes print the manual command)
+ *
+ * Never throws: resolution, detection, and download failures all fall back
+ * to printing a manual command. Removal is intentionally out of scope —
+ * `playwright uninstall` takes no per-engine arguments and the cache
+ * directory is machine-global; document the real CLI instead.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type SelectItem,
+	SelectList,
+	Text,
+} from "@earendil-works/pi-tui";
+
+// ─── Engines ─────────────────────────────────────────────────────
+
+export const ENGINES = ["chromium", "firefox"] as const;
+export type Engine = (typeof ENGINES)[number];
+
+/** Rough per-engine download sizes, for the dialog rows. */
+const ENGINE_SIZES = {
+	chromium: "~170 MB",
+	firefox: "~90 MB",
+} as const;
+
+// ─── Bundled playwright resolution ───────────────────────────────
+
+export interface BundledPlaywright {
+	/** The playwright module the backends import (same copy, same revisions). */
+	pw: typeof import("playwright");
+	/** Absolute path to the bundled playwright CLI entry. */
+	cliJs: string;
+	/** Node interpreter for spawning the CLI. */
+	nodeExe: string;
+}
+
+/**
+ * Node interpreter for spawning the bundled CLI. `process.execPath` is only
+ * a Node binary under the npm-shim distribution; pi also ships a
+ * bun-compiled standalone binary where `process.execPath` is the pi binary
+ * itself — spawning it with playwright's args re-runs pi, not the CLI. The
+ * `.exe` strip handles Windows (`...\node.exe` there); on POSIX the replace
+ * is a no-op.
+ */
+export function resolveNodeInterpreter(): string {
+	return basename(process.execPath).replace(/\.exe$/i, "") === "node"
+		? process.execPath
+		: "node";
+}
+
+/**
+ * Resolve the bundled playwright module + CLI path. Throws if playwright is
+ * missing entirely (corrupted install) — callers must catch and fall back to
+ * the generic manual command. Must be called lazily (inside the command
+ * handler), never at module top level: this module is imported by the `/web`
+ * dispatcher, and a throwing top-level require would break the entire `/web`
+ * command in exactly the corrupt-install scenario this command exists for.
+ */
+export function resolveBundledPlaywright(): BundledPlaywright {
+	const req = createRequire(import.meta.url);
+	const pw = req("playwright");
+	// `playwright/package.json` is exported; `playwright/cli.js` is not —
+	// resolving the CLI subpath directly throws ERR_PACKAGE_PATH_NOT_EXPORTED.
+	const pkgDir = dirname(req.resolve("playwright/package.json"));
+	return {
+		pw,
+		cliJs: join(pkgDir, "cli.js"),
+		nodeExe: resolveNodeInterpreter(),
+	};
+}
+
+// ─── Installed-browser detection (no launch) ─────────────────────
+
+export interface BrowserDetection {
+	chromium: boolean;
+	firefox: boolean;
+}
+
+/**
+ * Detect installed Node-backend browsers without launching. Unexpected
+ * layouts degrade to `missing` — the safe direction, since re-running
+ * install is harmless.
+ */
+export function detectInstalledBrowsers(
+	pw: typeof import("playwright"),
+): BrowserDetection {
+	return { chromium: detectChromium(pw), firefox: detectFirefox(pw) };
+}
+
+/**
+ * Chromium detection is keyed on the headless-shell binary, not the full
+ * browser: portal launches headless, and headless launches use
+ * `chromium_headless_shell-<rev>`, not the full `chromium-<rev>` binary that
+ * `executablePath()` reports — keying on the full browser would report
+ * "downloaded" in exactly the broken-cache scenario this command fixes
+ * (full chromium present, shell missing).
+ *
+ * ponytail: the directory-name transform is a heuristic on the documented
+ * cache layout (`chromium-<rev>/` ↔ `chromium_headless_shell-<rev>/`, same
+ * parent); the shell revision comes from playwright-core's `browsers.json`,
+ * not the chromium path, so the two may safely diverge. Correctness rests on
+ * the `INSTALLATION_COMPLETE` marker (what `playwright install` writes as
+ * its final step), which is immune to inner-layout renames. If playwright
+ * renames the shell *directory*, detection degrades to "missing" (safe) —
+ * resolve the shell directory through the registry only if that misfires.
+ */
+function detectChromium(pw: typeof import("playwright")): boolean {
+	try {
+		const exec = pw.chromium.executablePath();
+		const revMatch = /([/\\])chromium-(\d+)[/\\]/.exec(exec);
+		if (!revMatch) return false;
+		let shellRev = revMatch[2];
+		try {
+			const req = createRequire(import.meta.url);
+			const coreDir = dirname(req.resolve("playwright-core/package.json"));
+			const browsers = JSON.parse(
+				readFileSync(join(coreDir, "browsers.json"), "utf8"),
+			) as { browsers: Array<{ name: string; revision: number | string }> };
+			const entry = browsers.browsers.find(
+				(b) => b.name === "chromium-headless-shell",
+			);
+			// Independent revision field from chromium's — read the shell's own,
+			// fall back to the chromium revision if the read/entry fails.
+			if (entry) shellRev = String(entry.revision);
+		} catch {
+			/* keep chromium-revision fallback */
+		}
+		const shellDir = exec.replace(
+			/([/\\])chromium-\d+[/\\].*/,
+			`$1chromium_headless_shell-${shellRev}`,
+		);
+		// replace() returning the input means the layout didn't match.
+		return (
+			shellDir !== exec && existsSync(join(shellDir, "INSTALLATION_COMPLETE"))
+		);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Firefox has no headless-shell split — one binary. Same
+ * INSTALLATION_COMPLETE marker as chromium: a partial download that has
+ * extracted the executable but not finished would otherwise false-report
+ * "downloaded".
+ */
+function detectFirefox(pw: typeof import("playwright")): boolean {
+	try {
+		const exec = pw.firefox.executablePath();
+		const dirMatch = /[/\\]firefox-\d+[/\\]/.exec(exec);
+		if (!dirMatch) return false;
+		return existsSync(
+			join(
+				exec.slice(0, dirMatch.index + dirMatch[0].length),
+				"INSTALLATION_COMPLETE",
+			),
+		);
+	} catch {
+		return false;
+	}
+}
+
+// ─── Manual-command fallback ─────────────────────────────────────
+
+function manualCommand(bundled: BundledPlaywright, engines: Engine[]): string {
+	return `Install: ${bundled.nodeExe} ${bundled.cliJs} install ${engines.join(" ")}`;
+}
+
+function genericManualCommand(): string {
+	// Bundled path unresolvable — only the generic advice remains.
+	return "Install: npx playwright install chromium firefox";
+}
+
+/**
+ * Emit a manual-command fallback everywhere a feedback channel exists.
+ * `notify` reaches the TUI and RPC clients but is a no-op in print/JSON
+ * (their UI context is a no-op stub), where stderr is the only channel —
+ * write there too so those modes still print the command.
+ */
+function emitManualCommand(ctx: ExtensionContext, msg: string): void {
+	ctx.ui.notify(msg, "info");
+	if (!ctx.hasUI) process.stderr.write(`${msg}\n`);
+}
+
+// ─── Checklist dialog (copied from pi-lean-host select-picker.ts) ─
+//
+// pi's ctx.ui.select is single-choice and portal must not depend on host,
+// so pickChecklist is copied here. Keep the dialog rendering visually
+// identical to the host copy via the shared pickerTheme shape; the
+// behavioral deltas are intentional: an Install confirm row, pre-checked
+// rows, and an empty-selection guard (host resolves empty as []). UX
+// changes should propagate to
+// packages/pi-lean-host/core/select-picker.ts.
+
+/** Shared SelectList theme callbacks — keep both pickers visually identical. */
+function pickerTheme(theme: { fg(color: string, text: string): string }) {
+	return {
+		selectedPrefix: (text: string) => theme.fg("accent", text),
+		selectedText: (text: string) => theme.fg("accent", text),
+		description: (text: string) => theme.fg("muted", text),
+		scrollInfo: (text: string) => theme.fg("dim", text),
+		noMatch: (text: string) => theme.fg("warning", text),
+	};
+}
+
+const INSTALL_VALUE = "__install__";
+const INSTALL_TITLE = "🌐 Select browsers to install";
+
+/**
+ * Multi-select checklist: Enter toggles ✓/○, Enter on the Install row
+ * resolves the checked values, Esc returns undefined. Confirming with
+ * nothing checked notifies and keeps the dialog open. TUI-only — callers
+ * must guard with `ctx.mode === "tui"`.
+ */
+export async function pickBrowsersToInstall(
+	ctx: ExtensionContext,
+	rows: SelectItem[],
+	preChecked: string[],
+): Promise<string[] | undefined> {
+	const checked = new Set<string>(preChecked);
+	return ctx.ui.custom<string[] | undefined>((tui, theme, _kb, done) => {
+		const container = new Container();
+		let selectedIndex = 0;
+		let list = buildList();
+
+		function buildList(): SelectList {
+			const selectItems: SelectItem[] = rows.map((r) => ({
+				...r,
+				label: `${checked.has(r.value) ? "✓" : "○"} ${r.label}`,
+			}));
+			selectItems.push({
+				value: INSTALL_VALUE,
+				label: "Install — download the checked browsers",
+			});
+			const fresh = new SelectList(
+				selectItems,
+				Math.min(selectItems.length, 12),
+				pickerTheme(theme),
+			);
+			fresh.setSelectedIndex(Math.min(selectedIndex, selectItems.length - 1));
+			fresh.onSelectionChange = (item) => {
+				const at = selectItems.findIndex((s) => s.value === item.value);
+				if (at >= 0) selectedIndex = at;
+			};
+			fresh.onSelect = (item) => {
+				if (item.value === INSTALL_VALUE) {
+					if (checked.size === 0) {
+						ctx.ui.notify(
+							"Nothing selected — toggle a browser row first.",
+							"warning",
+						);
+						return;
+					}
+					done([...checked]);
+					return;
+				}
+				if (checked.has(item.value)) checked.delete(item.value);
+				else checked.add(item.value);
+				// Rebuild so the ✓/○ prefixes re-render; the highlight follows
+				// the tracked index across the swap.
+				container.removeChild(list);
+				list = buildList();
+				container.addChild(list);
+				// addChild appends — keep the footer below the rebuilt list.
+				container.removeChild(footer);
+				container.addChild(footer);
+			};
+			fresh.onCancel = () => done(undefined);
+			return fresh;
+		}
+
+		container.addChild(new Text(theme.fg("accent", theme.bold(INSTALL_TITLE))));
+		container.addChild(list);
+		const footer = new Text(
+			theme.fg("dim", "↑↓ navigate • enter toggle/select • esc cancel"),
+		);
+		container.addChild(footer);
+		return {
+			render(width: number) {
+				return container.render(width);
+			},
+			invalidate() {
+				container.invalidate();
+			},
+			handleInput(data: string) {
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+}
+
+// ─── Spawn & stream ──────────────────────────────────────────────
+
+/**
+ * Run the bundled playwright CLI install for the given engines, streaming
+ * output into a widget above the editor. Never throws — spawn errors and non-zero
+ * exits notify with the manual command instead.
+ */
+async function runInstall(
+	ctx: ExtensionContext,
+	bundled: BundledPlaywright,
+	engines: Engine[],
+): Promise<void> {
+	const manual = manualCommand(bundled, engines);
+	await new Promise<void>((resolve) => {
+		let out = "";
+		const child = spawn(bundled.nodeExe, [bundled.cliJs, "install", ...engines], {
+			stdio: "pipe",
+		});
+		// Bound the accumulated output: a long install must not grow memory
+		// without limit or re-split the whole buffer per chunk. The tail is
+		// enough — the host-validation warning is emitted near the end.
+		const MAX_TAIL = 64 * 1024;
+		// Show the last few download lines in a widget above the editor instead
+		// of the status bar: full progress visibility without crowding the
+		// footer. Piped (non-TTY) playwright prints a newline-terminated 10%-step
+		// progress line, so plain line splitting is enough; \r is handled for
+		// safety in case output shape changes.
+		const WIDGET_LINES = 8;
+		const tail = (chunk: Buffer) => {
+			out = (out + chunk.toString()).slice(-MAX_TAIL);
+			// ponytail: no progress-bar parsing — playwright's output format is
+			// not a stable API; the raw tail lines are enough.
+			const lines = out.trimEnd().split(/\r\n|\r|\n/);
+			ctx.ui.setWidget("install", [
+				`⬇ Installing ${engines.join(", ")}…`,
+				...lines.slice(-WIDGET_LINES).map((l) => `  ${l.trim().slice(0, 120)}`),
+			]);
+		};
+		child.stdout?.on("data", tail);
+		child.stderr?.on("data", tail);
+		// Node can fire both `error` and `close` for one failed spawn — settle
+		// once so the user gets a single notification.
+		let settled = false;
+		const finish = (notifyMsg: string, type: "info" | "warning") => {
+			if (settled) return;
+			settled = true;
+			ctx.ui.setWidget("install", undefined);
+			ctx.ui.notify(notifyMsg, type);
+			resolve();
+		};
+		child.on("error", (err) => {
+			// ENOENT, non-Node runtime with no `node` on PATH, etc.
+			finish(`Browser install failed: ${err.message}\n${manual}`, "warning");
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				let msg = `✅ Installed: ${engines.join(", ")}`;
+				// The multi-line host-validation warning scrolls past in status
+				// text on exactly the fresh-Linux-host case where it matters —
+				// surface it in the completion notify instead. Still no
+				// --with-deps (needs root/apt): the warning names the exact
+				// install-deps command.
+				if (out.includes("Playwright Host validation warning")) {
+					msg +=
+						"\n⚠ Playwright reported missing host dependencies — run the install-deps command it printed (needs root).";
+				}
+				finish(msg, "info");
+			} else {
+				finish(`Browser install failed (exit code ${code}).\n${manual}`, "warning");
+			}
+		});
+	});
+}
+
+// ─── Handler ─────────────────────────────────────────────────────
+
+/**
+ * Handle the `/web install` subcommand.
+ *
+ * @param sub The text after "install" ("" | "chromium" | "firefox")
+ */
+export async function handleInstallSubcommand(
+	sub: string,
+	ctx: ExtensionContext,
+): Promise<void> {
+	const arg = sub.trim().toLowerCase();
+	const direct: Engine[] | null =
+		arg === "chromium" || arg === "firefox" ? [arg] : null;
+	if (arg !== "" && !direct) {
+		ctx.ui.notify(
+			`Unknown install sub-command: "${arg}". Usage: /web install [chromium|firefox]`,
+			"warning",
+		);
+		return;
+	}
+
+	// Lazy resolution — see resolveBundledPlaywright. On failure the bundled
+	// path doesn't exist to print, so only the generic command remains.
+	let bundled: BundledPlaywright;
+	try {
+		bundled = resolveBundledPlaywright();
+	} catch {
+		emitManualCommand(ctx, genericManualCommand());
+		return;
+	}
+
+	if (direct) {
+		// Direct form: spawn wherever a feedback channel exists — TUI and RPC
+		// (notify reaches the RPC client, so at least the completion message is
+		// observable); in print/JSON they're no-ops and the ~170 MB download
+		// would appear to hang, so print the manual command instead.
+		if (ctx.hasUI) {
+			await runInstall(ctx, bundled, direct);
+		} else {
+			emitManualCommand(ctx, manualCommand(bundled, direct));
+		}
+		return;
+	}
+
+	// Bare form: dialog in TUI only; every other mode (RPC included — the
+	// checklist dialog does not exist outside TUI) prints the manual command.
+	if (ctx.mode !== "tui") {
+		emitManualCommand(ctx, manualCommand(bundled, [...ENGINES]));
+		return;
+	}
+
+	// The dialog always opens, even when detection reports both downloaded:
+	// it cannot see a corrupted binary behind a valid-looking cache marker,
+	// so a forced redownload must stay reachable (downloaded rows are
+	// toggleable; missing ones come pre-checked).
+	const detection = detectInstalledBrowsers(bundled.pw);
+	const rows: SelectItem[] = ENGINES.map((engine) => ({
+		value: engine,
+		label: `${engine === "chromium" ? "Chromium" : "Firefox"} (${ENGINE_SIZES[engine]}) — ${detection[engine] ? "downloaded" : "missing"}`,
+	}));
+	const preChecked = ENGINES.filter((e) => !detection[e]);
+
+	const checked = await pickBrowsersToInstall(ctx, rows, preChecked);
+	if (checked === undefined) return; // Esc — user cancelled
+	if (checked.length === 0) return; // guarded in the dialog; defensive no-op
+	await runInstall(ctx, bundled, checked as Engine[]);
+}

package/browser-status.ts

@@ -10,6 +10,11 @@ import { sessionManager } from "./core/shared/session-manager.js";
 import { pluginRegistry } from "./core/plugin-registry.js";
 import { listProfiles } from "./browser-profile.js";
 import { isSessionProfile } from "./core/shared/storage-state.js";
+import {
+	ENGINES,
+	detectInstalledBrowsers,
+	resolveBundledPlaywright,
+} from "./browser-install.js";
 
 /**
  * Show detailed browser runtime status.
@@ -41,6 +46,22 @@ export function handleStatusSubcommand(
 		}
 	}
 	msg += `\nPlugins: ${backendLines.join(", ")}`;
+
+	// Browser-binary presence for the Node backends, via the same detection
+	// /web install uses. Resolution failure (corrupt install) just omits the
+	// line — /web install reports the fallback command in that case.
+	try {
+		const bundled = resolveBundledPlaywright();
+		const detected = detectInstalledBrowsers(bundled.pw);
+		const states = ENGINES.map((e) => `${e} ${detected[e] ? "✓" : "✗"}`).join(
+			" ",
+		);
+		const anyMissing = ENGINES.some((e) => !detected[e]);
+		msg += `\nBrowsers: ${states}${anyMissing ? " (run /web install)" : ""}`;
+	} catch {
+		/* playwright unresolvable — omit */
+	}
+
 	msg += `\nUse web-fetch for stateless HTTP fetches.`;
 
 	if (active.length > 0) {

package/browser-toggle.ts

@@ -2,18 +2,27 @@ import type {
 	ExtensionAPI,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import { updateFooterStatus } from "./tools/utils.js";
-import {
-	defineToolset,
-	TOOLSET_EVENTS,
-	getDefaultResolutionMode,
-} from "pi-tool-masking";
+import { updateFooterStatus, getLastCtx, setLastCtx } from "./tools/utils.js";
+import { defineToolset, TOOLSET_EVENTS } from "pi-tool-masking";
 import type { ToolsetSpec } from "pi-tool-masking";
 
-// Focus-mode guard: refuse actuating subcommands while allowlist focus is
-// holding the line (an upstream pi-tool-masking consumer).
-function isFocusHolding(): boolean {
-	return getDefaultResolutionMode() === "allowlist";
+// Catch AllowlistModeError by name, never `instanceof` — the handle may come
+// from a different library copy via the shared registry. Returns true when
+// the toggle ran, false when it was refused (nothing changed).
+function refuseOnAllowlist(ctx: ExtensionContext, toggle: () => unknown): boolean {
+	try {
+		toggle();
+		return true;
+	} catch (err) {
+		if ((err as { name?: string } | undefined)?.name === "AllowlistModeError") {
+			ctx.ui.notify(
+				"Focus mode (allowlist) is active — this toolset can't be toggled while focus is holding the line. Exit focus there first.",
+				"warning",
+			);
+			return false;
+		}
+		throw err;
+	}
 }
 
 // ---- Toolset specs -----------------------------------------------
@@ -52,9 +61,6 @@ let _lastToggleState = true;
 /** @internal Last known learn state for status bar coloring. */
 let _lastLearnState = false;
 
-/** @internal Last captured ExtensionContext for event-driven status-bar rendering. */
-let _lastCtx: ExtensionContext | null = null;
-
 export function getToggleState(): boolean {
 	return _lastToggleState;
 }
@@ -105,7 +111,6 @@ function restoreProfile(_pi: ExtensionAPI, ctx: ExtensionContext): void {
 export function resetToggleModuleState(): void {
 	_lastToggleState = true;
 	_lastLearnState = false;
-	_lastCtx = null;
 	_conversationDefaultProfile = undefined;
 }
 
@@ -125,8 +130,9 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 	const syncCachedState = () => {
 		_lastToggleState = webToolset.isEnabled(pi);
 		_lastLearnState = learnToolset.isEnabled(pi);
-		if (_lastCtx) {
-			updateFooterStatus(_lastCtx);
+		const ctx = getLastCtx();
+		if (ctx) {
+			updateFooterStatus(ctx);
 		}
 	};
 
@@ -137,40 +143,42 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 	pi.registerCommand("web", {
 		description:
 			"Enable/disable browser automation tools. " +
-			"Usage: /web on | off | learn | status",
+			"Usage: /web on | off | learn | install | status",
 		handler: async (args, ctx) => {
 			const cmd = args.trim().toLowerCase();
 
-			// Focus-mode guard: refuse actuating subcommands while allowlist
-			// focus holds the line (an upstream pi-tool-masking consumer) —
-			// a sibling toggle must not write a focus-indistinguishable
-			// {enabled} entry.
-			// Read-only subcommands (status/profile/cookies/bare /web) stay
-			// unguarded, matching the focus controller's treatment of its own
-			// read-only commands.
-			if (["on", "off", "learn"].includes(cmd) && isFocusHolding()) {
-				ctx.ui.notify(
-					"Focus mode (allowlist) is active — this toolset can't be toggled while focus is holding the line. Exit focus there first.",
-					"warning",
-				);
-				return;
-			}
-
 			if (cmd === "on") {
-				webToolset.enable(pi);
-				learnToolset.disable(pi);
+				if (
+					!refuseOnAllowlist(ctx, () => {
+						webToolset.enable(pi, ctx.sessionManager);
+						learnToolset.disable(pi, ctx.sessionManager);
+					})
+				)
+					return;
 				ctx.ui.notify(
 					"🌐 Browser tools enabled. /web learn to make web-learn available.",
 					"info",
 				);
 			} else if (cmd === "learn") {
-				learnToolset.enable(pi); // cascades web on via requires
+				if (
+					!refuseOnAllowlist(
+						ctx,
+						() => learnToolset.enable(pi, ctx.sessionManager), // cascades web on via requires
+					)
+				)
+					return;
 				ctx.ui.notify(
 					"📖 web-learn tool is now available. Agent will save/update guides when asked.",
 					"info",
 				);
 			} else if (cmd === "off") {
-				webToolset.disable(pi); // cascades learn off via requires
+				if (
+					!refuseOnAllowlist(
+						ctx,
+						() => webToolset.disable(pi, ctx.sessionManager), // cascades learn off via requires
+					)
+				)
+					return;
 				ctx.ui.notify("🌐 Browser tools disabled. /web on to re-enable.", "info");
 			} else if (cmd === "profile" || cmd.startsWith("profile ")) {
 				const sub = cmd.slice("profile".length).trim();
@@ -187,6 +195,10 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 				const sub = cmd.slice("cookies".length).trim();
 				const { handleCookiesSubcommand } = await import("./browser-cookies.js");
 				await handleCookiesSubcommand(sub, ctx);
+			} else if (cmd === "install" || cmd.startsWith("install ")) {
+				const sub = cmd.slice("install".length).trim();
+				const { handleInstallSubcommand } = await import("./browser-install.js");
+				await handleInstallSubcommand(sub, ctx);
 			} else if (cmd === "status") {
 				const { handleStatusSubcommand } = await import("./browser-status.js");
 				handleStatusSubcommand(
@@ -203,6 +215,7 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 						`📖 Learn mode: ${learnOn}\n` +
 						`   /web profile     manage browser profiles\n` +
 						`   /web cookies     inspect or clear session cookies\n` +
+						`   /web install     install browser binaries (bundled playwright CLI)\n` +
 						`   /web off         disable all browser tools\n` +
 						`   /web on          enable browsing only\n` +
 						`   /web learn       enable browsing + guide-saving\n` +
@@ -217,17 +230,17 @@ export default function initBrowserToggle(pi: ExtensionAPI) {
 	// ── Session handlers: restore profile + render status bar ─
 	pi.on("session_start", async (_event, ctx) => {
 		restoreProfile(pi, ctx);
-		_lastCtx = ctx;
+		setLastCtx(ctx);
 		syncCachedState();
 	});
 
 	pi.on("session_tree", async (_event, ctx) => {
 		restoreProfile(pi, ctx);
-		_lastCtx = ctx;
+		setLastCtx(ctx);
 		syncCachedState();
 	});
 
 	pi.on("session_shutdown", async () => {
-		_lastCtx = null;
+		setLastCtx(null);
 	});
 }

package/core/fetch-backend.ts

@@ -111,8 +111,6 @@ async function performFetch(
 			redirect: "follow",
 		});
 
-		clearTimeout(timeoutId);
-
 		if (!response.ok) {
 			throw new Error(`HTTP ${response.status} ${response.statusText ?? ""}`);
 		}
@@ -128,6 +126,8 @@ async function performFetch(
 
 		return { title, needsJavaScript, root };
 	} finally {
+		// Timer stays armed through the body read, so `timeout` bounds the
+		// whole request, not just the response headers.
 		clearTimeout(timeoutId);
 	}
 }

package/core/router.ts

@@ -83,36 +83,6 @@ export interface NavigateOptions {
 	piSessionId?: string;
 }
 
-// ─── Profile Change Callback ───────────────────────────────────────
-
-/**
- * Simple nullable callback for profile changes.
- * Used by index.ts to update the TUI status bar.
- */
-let _onProfileChange:
-	| ((
-			taskId: string,
-			profileName?: string,
-			profileMode?: "none" | "session" | "named",
-	  ) => void)
-	| null = null;
-
-/**
- * Set the profile change callback.
- * Called once at extension startup from index.ts.
- */
-export function setOnProfileChange(
-	handler:
-		| ((
-				taskId: string,
-				profileName?: string,
-				profileMode?: "none" | "session" | "named",
-		  ) => void)
-		| null,
-): void {
-	_onProfileChange = handler;
-}
-
 // ─── Helpers ─────────────────────────────────────────────────────────
 
 /**
@@ -489,8 +459,13 @@ export async function navigate(
 		resolvedProfileName = profileInput;
 	}
 
-	// ── Notify profile change callback ─────────────────────
-	_onProfileChange?.(taskId, resolvedProfileName, profileMode);
+	// ── Notify profile change ─────────────────────
+	if (process.env.BROWSER_DEBUG) {
+		const parts = [`[browser] profile_changed: task=${taskId}`];
+		if (resolvedProfileName) parts.push(`profile=${resolvedProfileName}`);
+		if (profileMode) parts.push(`mode=${profileMode}`);
+		console.error(parts.join(" "));
+	}
 
 	// ── Create session and navigate ───────────────────────────
 	sessionManager.createSession(taskId, plugin.name);

package/core/shared/session-manager.ts

@@ -2,8 +2,6 @@ import { getProfileLabel } from "./storage-state.js";
 
 /**
  * Session manager — tracks browser session lifecycle per task_id.
-
-
  *
  * Design: sessions track metadata; browsers and contexts are managed
  * entirely by the plugin. The session manager is Playwright-agnostic.
@@ -112,7 +110,7 @@ class SessionManager {
 		this.#lastNav.delete(taskId);
 	}
 
-	async removeAll(): Promise<void> {
+	removeAll(): void {
 		this.#sessions.clear();
 		this.#lastNav.clear();
 	}

package/index.ts

@@ -15,7 +15,7 @@ import type { PythonBridgeConfig } from "./backends/python-adapter.js";
 import { sessionManager } from "./core/shared/session-manager.js";
 import { removeAllSnapshotFiles } from "./core/shared/snapshot-cache.js";
 import initBrowserToggle from "./browser-toggle.js";
-import { updateFooterStatus, getLastCtx, setLastCtx } from "./tools/utils.js";
+import { updateFooterStatus, setLastCtx } from "./tools/utils.js";
 import { deleteSessionKey, resetTaskIds } from "./core/shared/task-id.js";
 import { resetToggleModuleState } from "./browser-toggle.js";
 import { registerGuideProvider } from "./core/guides.js";
@@ -214,23 +214,6 @@ export default function (pi: ExtensionAPI) {
 	// --- Register commands ------------------------------------------
 	initBrowserToggle(pi);
 
-	// --- Profile change callback for TUI status updates ------------
-	router.setOnProfileChange((taskId, profileName, profileMode) => {
-		// Update TUI status bar on any profile lifecycle event
-		const lastCtx = getLastCtx();
-		if (lastCtx) {
-			updateFooterStatus(lastCtx);
-		}
-
-		// Debug logging when BROWSER_DEBUG is set
-		if (process.env.BROWSER_DEBUG) {
-			const parts = [`[browser] profile_changed: task=${taskId}`];
-			if (profileName) parts.push(`profile=${profileName}`);
-			if (profileMode) parts.push(`mode=${profileMode}`);
-			console.error(parts.join(" "));
-		}
-	});
-
 	// --- Startup ----------------------------------------------------
 	pi.on("session_start", async (_event, ctx) => {
 		const pluginNames = pluginRegistry.available().join(", ");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lean-portal",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"description": "Interactive Playwright web browsing for Pi. Chromium and Firefox built in; author stealth backends on either engine. Snapshots and screenshots cache to disk, saving context. Configurable profiles/cookies. Agents write site guides, auto-matched by domain.",
 	"keywords": [
 		"pi-package",
@@ -32,6 +32,7 @@
 		"browser-profile.ts",
 		"browser-cookies.ts",
 		"browser-status.ts",
+		"browser-install.ts",
 		"LICENSE",
 		"backends/",
 		"!backends/python-base/.venv/",
@@ -54,7 +55,7 @@
 	},
 	"dependencies": {
 		"node-html-parser": "^6.1.0",
-		"pi-tool-masking": "^1.3.0",
+		"pi-tool-masking": "^2.0.1",
 		"playwright": "^1.60.0",
 		"turndown": "^7.2.0"
 	},

package/tools/browser-navigate.ts

@@ -137,9 +137,13 @@ export const browserNavigateTool = defineTool({
 			// If the browser executable is not installed, notify the user with install instructions.
 			const isInstallError =
 				result.error && result.error.toLowerCase().includes("not installed");
-			if (isInstallError) {
+			// Python backends (chromium-py, firefox-py, stealth -py backends) report a
+			// missing venv Playwright wheel — their error already carries the accurate
+			// pip install hint, and /web install cannot fix that, so stay quiet.
+			const isPythonBackend = result.backendUsed?.endsWith("-py") ?? false;
+			if (isInstallError && !isPythonBackend) {
 				ctx?.ui?.notify(
-					"Browser not installed. Run: npx playwright install chromium firefox",
+					"Browser not installed. Run /web install to install it.",
 					"warning",
 				);
 			}

package/tools/utils.ts

@@ -29,10 +29,9 @@ export function contentText(
 // ─── Status bar ─────────────────────────────────────────────────
 
 /**
- * Retained reference to the most recent extension context for use by
- * the browser.profile event listener (which fires asynchronously from
- * tool execution contexts). Updated on session_start and cleared on
- * session_shutdown.
+ * Retained reference to the most recent extension context, so event
+ * handlers that fire outside a tool/ctx scope (e.g. browser-toggle's
+ * toolset changed/restored listeners) can still repaint the status bar.
  */
 let _lastCtx: {
 	ui: {
@@ -62,12 +61,12 @@ export function updateFooterStatus(ctx: {
 	ctx.ui.setStatus("browser", `${dot} ${body}`);
 }
 
-/** @internal — used by index.ts's profile event listener */
+/** @internal — read by browser-toggle's event-driven status repaint */
 export function getLastCtx(): typeof _lastCtx {
 	return _lastCtx;
 }
 
-/** @internal — set by index.ts on startup/shutdown */
+/** @internal — updated on session_start/session_tree, cleared on shutdown */
 export function setLastCtx(ctx: typeof _lastCtx): void {
 	_lastCtx = ctx;
 }