@underactive/pi-topping-web-tools 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.2] - 2026-09-02
+
+### Added
+
+- `web_browser`: fail-closed browser-context egress enforcement for HTTP(S) requests and WebSocket connections, with live preapproved/session/durable permission checks and blocked-request reporting in network logs. Service workers are disabled so they cannot bypass routing.
+
+### Changed
+
+- `web_browser`: inspects redirect targets before contact, follows approved top-level redirects one gated hop at a time, blocks redirected subresources, closes unapproved popups before activation, and restores the prior page after blocked client-side navigation.
+- `web_browser`: retains an Allow once navigation decision as a browser-session grant so the approved document and its later same-origin requests can pass request-level enforcement.
+
+### Fixed
+
+- `web_browser`: treat an empty optional selector as the default `body` selector for `get_text` and `get_accessibility_snapshot`, avoiding invalid empty CSS-selector errors.
+- `web_browser`: treats bare and `www.` variants of a remote hostname as equivalent for session and durable egress grants, allowing redirects such as `apple.com` → `www.apple.com` without a second approval while keeping other subdomains gated.
+
+## [0.2.1] - 2026-08-31
+
+### Added
+
+- `web_browser`: publishes browser state through the `pi-topping-web-tools/browser` custom session feed for statusline consumers. Truthy `PI_SUPPRESS_NOTIFICATIONS` values hide the native browser footer without suppressing feed entries.
+
+### Changed
+
+- `fetch_markdown`, `pdf_extract`: send browser-like HTTP headers (Accept, Accept-Language, User-Agent, Sec-Fetch-*, etc.) to reduce blocking by User-Agent-based filters; `PI_FETCH_USER_AGENT` overrides the default User-Agent.
+
 ## [0.2.0] - 2026-08-18
 
 ### Added

package/README.md

@@ -22,7 +22,7 @@ Web work has two distinct needs: clean context from public sources and browser-l
 - **Reach PDF-only sources.** `pdf_extract` reads the text layer of specifications, datasheets, and papers that markdown fetchers treat as undisplayable binary content, and that pi's `read` tool cannot parse.
 - **Validate the rendered product.** `web_browser` runs a fresh headless Chromium context for client-rendered pages, local development servers, and user journeys that static HTML cannot represent. It can inspect the accessibility tree, interact with controls, and surface console and failed-network diagnostics.
 - **Use the appropriate tool, not the heavier tool by default.** Fetch static public material first; move to browser automation when JavaScript, visual state, or user input is part of the question.
-- **Keep control over access.** The tools share a host allowlist and confirmation workflow; fetched page text is explicitly marked as untrusted, and browser sessions do not reuse the system browser profile.
+- **Keep control over access.** The tools share a host allowlist and confirmation workflow; `web_browser` also enforces approved URLs on HTTP(S) requests and WebSocket connections inside its isolated browser context. Fetched page text is explicitly marked as untrusted, and browser sessions do not reuse the system browser profile.
 
 ## Examples
 
@@ -114,7 +114,7 @@ Single tool with an `action` parameter:
 | `wait_for` | `selector?`, `state?`, `networkidle?` | Wait for selector state and/or network idle |
 | `get_accessibility_snapshot` | `selector?` | Return ARIA accessibility tree (YAML) |
 | `get_console_logs` | — | Drain captured console/page errors |
-| `get_network_logs` | — | Drain captured failed requests and 4xx/5xx responses |
+| `get_network_logs` | — | Drain captured egress blocks, failed requests, and 4xx/5xx responses |
 | `get_cookies` | — | Return cookie metadata as JSON (name, domain, path, flags; values are redacted) |
 | `set_cookies` | `cookies` | Set cookies (each needs `url` or `domain`+`path`) |
 | `go_back` / `go_forward` / `reload` | — | Browser history navigation / reload |
@@ -129,9 +129,24 @@ Single tool with an `action` parameter:
 
 Optional `timeout` (ms, default 30000) applies to navigation and to selector-based actions (click, type, hover, select_option, screenshot, get_text, get_markdown, wait_for, get_accessibility_snapshot, scroll, drag, upload_file). Other actions use Playwright defaults.
 
+### Browser network egress
+
+`web_browser` enforces its permissions inside every fresh browser context:
+
+- Every HTTP(S) document, script, image, XHR/fetch, beacon, and other routed request is checked against the live preapproved, session, and durable permissions before the request is sent. Path-scoped preapprovals remain path-scoped; session and durable grants remain exact-origin grants except that bare and `www.` host variants are treated as equivalent.
+- Redirect responses are inspected before Chromium receives them. Approved top-level redirects, including simple bare-domain ↔ `www.` redirects, are followed one gated hop at a time. During `navigate`, a redirect to an unapproved URL returns `Blocked: redirect to <origin> requires approval`; redirects triggered by later page interactions are blocked and reported in network logs. Redirected subresources are blocked rather than followed and also appear in network logs.
+- WebSocket handshakes use the same live permission check. Service workers are disabled so they cannot bypass request routing.
+- Client-side navigation and popup destinations are gated. A blocked popup is closed without becoming active, and a blocked same-tab navigation returns to the prior approved page.
+- `data:` and `blob:` subresources are allowed because they do not create network egress, while top-level `data:`/`blob:` documents are denied. `file:` documents require approval for the target path; local-file subresources are allowed only from an approved local-file page.
+- Decision errors fail closed. Route handlers never prompt; call `navigate` on a blocked target to use the normal approval prompt. Blocks are reported by `get_network_logs` as `blocked by egress policy`.
+
+A navigation approved with **Allow once** is retained as a browser-session origin grant so the document and its later same-origin requests can continue to load under request-level enforcement. Choosing a durable duration still controls whether that origin is available in later sessions.
+
+Strict egress can make an approved page incomplete when it depends on an unapproved CDN, API, font, or analytics origin. Navigate directly to that origin to approve it, then return to the page and reload.
+
 Selectors are CSS selectors, or Playwright's `role=` and `text=` selector engines (e.g. `role=button[name='Submit']`, `text=Sign in`). Pass `frame` (a CSS selector for the containing `<iframe>`) to scope click/type/hover/select_option/screenshot/get_text/wait_for/get_accessibility_snapshot/scroll/upload_file/drag into that frame.
 
-Opening a link with `target=_blank` or `window.open` creates a popup that automatically becomes the active tab — subsequent actions target it until you `switch_tab` back. Use `list_tabs` to see all open tabs.
+Opening a link with `target=_blank` or `window.open` opens a new tab whose destination is checked against live permissions. An approved popup becomes the active tab; a popup to an unapproved URL is closed without becoming active and the current tab stays active. Use `list_tabs` to see all open tabs.
 
 JS dialogs (`alert`/`confirm`/`prompt`) are dismissed by default so they never block automation; call `set_dialog_behavior` before the action that triggers one if you need `accept` instead (and, for `prompt`, a `promptText` value).
 
@@ -143,12 +158,33 @@ Commands:
 
 Status line: a footer segment (`browser: example.com`) appears while the browser is open.
 
+### Statusline feed
+
+`web_browser` also publishes its current state as a pi custom session entry, so [pi-topping-statusline](https://github.com/underactive/pi-topping-statusline) can render it without depending on this package:
+
+- Type: `pi-topping-web-tools/browser`
+- `label` (`text`): current hostname, `local file`, `ready`, or an empty string when closed
+- `open` (`number`): `1` when open, `0` when closed
+
+For example, subscribe to `label` with prefix `browser: ` and `text` format:
+
+```json
+{
+  "type": "pi-topping-web-tools/browser",
+  "field": "label",
+  "prefix": "browser: ",
+  "format": "text"
+}
+```
+
+Entries are published only when the state changes, except that the current state is republished immediately at session start and once after the first turn. Closing the browser publishes `{ "label": "", "open": 0 }` so consumers can clear stale labels. Set `PI_SUPPRESS_NOTIFICATIONS` to `1`, `true`, or `yes` (case-insensitive) to hide the native footer; feed publication continues.
+
 ## Saved permissions
 
 When the host confirmation prompt offers a durable option ("Allow for 1 day", "Allow for 1 week", "Allow for 30 days"), the grant is persisted to `~/.pi/agent/web-permissions.json` (mode `0600`) and applies across all sessions and projects.
 
 - **Per-tool scope.** A `fetch_markdown` grant does not authorize `web_browser`, which executes JavaScript and drives interaction. Each tool scopes its grants independently.
-- **Exact origin.** Grants match `scheme://host[:port]` exactly — no subdomain wildcards, no cross-port or cross-scheme reuse.
+- **Exact origin.** Grants are stored as `scheme://host[:port]` and do not cross ports or schemes. For `web_browser` egress, only the bare and `www.` variants of the same remote hostname are equivalent; no other subdomains inherit the grant.
 - **Max 30 days.** All grants expire; there is no indefinite option. Expired entries are pruned automatically.
 - **Local files excluded.** `file://` prompts never offer durable options; local-file access needs a path-scope design that is out of scope here.
 - **Headless behavior.** Active durable grants apply when there is no interactive UI (e.g. RPC or print mode). Without a grant, non-preapproved hosts remain blocked.
@@ -160,10 +196,10 @@ Commands:
 ## Security model (shared)
 
 - **Preapproved hosts**: common documentation and dev sites are allowed without prompting. The allowlist lives in `src/permissions.ts` and is shared by both tools.
-- **User confirmation**: other hosts prompt Allow once / Allow for this session / Allow for 1 day / Allow for 1 week / Allow for 30 days / Deny.
+- **User confirmation**: other hosts prompt Allow once / Allow for this session / Allow for 1 day / Allow for 1 week / Allow for 30 days / Deny. For `web_browser` navigation, Allow once becomes a browser-session grant because request-level enforcement must authorize the loaded document's later requests.
 - **URL validation**: all tools reject embedded credentials and overlong URLs. `fetch_markdown` and `pdf_extract` additionally reject loopback, private, and link-local hosts and any non-HTTP(S) scheme on a `url`. `web_browser` accepts `localhost`, private IPs, and `file://` paths so it can drive local dev servers and local HTML — each still prompts for confirmation unless session-approved or covered by a saved durable grant.
 - **Local file resolution**: `pdf_extract` resolves a `path` through `realpath` before any check, so a symlink pointing outside the working directory is treated as outside and prompts. Directories, FIFOs, and devices are rejected, and the size limit is enforced from `stat` before any bytes are read. `web_browser` `upload_file` follows the same rule: files outside the working directory prompt for confirmation (session-scoped) before they are read.
-- **Isolated browser context**: each session uses a fresh Chromium context (no shared profile/cookies with your system browser).
+- **Isolated browser context and routed egress**: each session uses a fresh Chromium context (no shared profile/cookies with your system browser). HTTP(S) requests, redirect targets, client navigations, popups, and WebSocket connections are checked against live `web_browser` permissions; service workers are disabled.
 - **Untrusted content boundary**: `fetch_markdown` results are wrapped in `<untrusted-content url="…">` tags, and `pdf_extract` results in `<untrusted-content source="…">`, so the model treats fetched page and document text as data, not instructions.
 - **PDF resource limits**: extraction is bounded by download size, page count, and a timeout. Because the bundled PDF.js runs on the event loop rather than a worker, the timeout bounds extraction across its await points but cannot interrupt a fully synchronous parse — the size and page caps are the primary defence.
 
@@ -171,12 +207,14 @@ Commands:
 
 - `web_browser` requires the Chromium download.
 - Screenshots consume significant context on vision models — prefer `get_text`, `get_markdown`, or `get_accessibility_snapshot`.
-- Network logs capture only failed requests and 4xx/5xx responses (not all traffic).
+- Network logs capture blocked/failed requests and 4xx/5xx responses, not successful traffic.
+- Request routing buffers HTTP(S) responses and blocks redirected subresources, so streaming endpoints and resources that rely on redirects may not behave like an unrestricted browser.
+- Playwright routing covers HTTP(S) and WebSockets, not browser transports such as WebRTC; OS-level egress sandboxing remains outside this extension's scope.
 - `pdf_extract` reads only an existing text layer; scanned documents need OCR, which is out of scope.
 
 ### Popups and navigation
 
-Popups inherit the same security model as same-tab link clicks: opening a `target=_blank` link or calling `window.open` is not gated by the host allowlist, since it's JS-initiated navigation rather than a tool-driven `navigate` call. `evaluate` remains gated per active page URL — the permission check follows the active-tab cursor automatically, so switching to a popup and calling `evaluate` re-checks permission for that popup's URL.
+Same-tab client navigation and popups are checked against the live `web_browser` permissions. Unapproved document requests are aborted before reaching the target; blocked popups are closed without becoming active, while a blocked same-tab navigation returns to the prior approved page. Approved popups become active only after their main-frame navigation commits.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Pi extensions for the web: fetch_markdown (URL to markdown, cached, keyless), pdf_extract (PDF text extraction) and web_browser (headless Playwright automation), sharing a preapproved-host allowlist.",
 	"keywords": ["pi-package", "pi-extension"],
 	"license": "MIT",

package/src/browser-headers.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser-like HTTP headers shared by fetch_markdown and pdf_extract.
+ *
+ * Sending these instead of bare-minimum tool-identified headers reduces
+ * the chance of being blocked by WAFs and CDNs that filter non-browser
+ * User-Agents or missing auxiliary headers.
+ *
+ * The header set mimics Chrome ~122 on macOS, omitting Sec-Ch-Ua* (which
+ * would need to stay in sync with the Chrome version) and Accept-Encoding
+ * (Node's native fetch() adds its own).
+ */
+
+const DEFAULT_HEADERS: Record<string, string> = {
+	Accept:
+		"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+	"Accept-Language": "en-US,en;q=0.9",
+	"Upgrade-Insecure-Requests": "1",
+	"User-Agent":
+		"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+	"Sec-Fetch-Dest": "document",
+	"Sec-Fetch-Mode": "navigate",
+	"Sec-Fetch-Site": "none",
+	"Sec-Fetch-User": "?1",
+	DNT: "1",
+	Priority: "u=0, i",
+};
+
+const USER_AGENT_OVERRIDE: string | undefined = process.env.PI_FETCH_USER_AGENT || undefined;
+
+/**
+ * Return a set of browser-like HTTP headers.
+ *
+ * When `PI_FETCH_USER_AGENT` is set in the environment, its value replaces
+ * the default Chrome User-Agent while all other headers remain unchanged.
+ *
+ * @param userAgentOverride - optional explicit User-Agent to use instead of
+ * the default Chrome macOS UA. Takes precedence over the env var when both
+ * are present.
+ */
+export function getBrowserHeaders(userAgentOverride?: string): Record<string, string> {
+	const ua = userAgentOverride ?? USER_AGENT_OVERRIDE;
+	if (!ua) return DEFAULT_HEADERS;
+	return { ...DEFAULT_HEADERS, "User-Agent": ua };
+}

package/src/env.ts

@@ -0,0 +1,10 @@
+// Same truthiness rules as pi core's isTruthyEnvFlag.
+export function isTruthyEnvFlag(value: string | undefined): boolean {
+	if (!value) return false;
+	return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+/** Set when pi suppresses non-essential notifications. */
+export function suppressNotifications(env: NodeJS.ProcessEnv = process.env): boolean {
+	return isTruthyEnvFlag(env.PI_SUPPRESS_NOTIFICATIONS);
+}

package/src/fetch-markdown.ts

@@ -9,6 +9,7 @@ import { Readability } from "@mozilla/readability";
 import { parseHTML } from "linkedom";
 import { STATUS_CODES } from "node:http";
 import { combineSignals } from "./abort-utils.ts";
+import { getBrowserHeaders } from "./browser-headers.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
@@ -207,8 +208,7 @@ export async function getWithPermittedRedirects(
 		signal,
 		redirect: "manual",
 		headers: {
-			Accept: "text/markdown, text/html, */*",
-			"User-Agent": "pi-fetch-markdown/1.0",
+			...getBrowserHeaders(),
 			...extraHeaders,
 		},
 	});

package/src/permission-store.ts

@@ -99,10 +99,31 @@ export function listGrants(): Grant[] {
 	return valid;
 }
 
+let grantCache: Map<string, number> | undefined;
+let grantCacheStorePath: string | undefined;
+
+function grantCacheKey(scope: PermissionScope, origin: string): string {
+	return `${scope}\0${origin}`;
+}
+
+function setGrantCache(grants: Grant[]): void {
+	grantCacheStorePath = storePath();
+	grantCache = new Map(grants.map((g) => [grantCacheKey(g.scope, g.origin), g.expiresAt]));
+}
+
+function ensureGrantCache(): Map<string, number> {
+	const currentPath = storePath();
+	if (!grantCache || grantCacheStorePath !== currentPath) {
+		setGrantCache(listGrants());
+	}
+	return grantCache!;
+}
+
 /** Check whether a specific scope+origin has an active durable grant. */
 export function isGranted(scope: PermissionScope, origin: string): boolean {
 	const key = normalizeOrigin(origin);
-	return listGrants().some((g) => g.scope === scope && g.origin === key);
+	const expiresAt = ensureGrantCache().get(grantCacheKey(scope, key));
+	return expiresAt !== undefined && expiresAt > Date.now();
 }
 
 /** Prune expired entries from a grant list. */
@@ -180,6 +201,7 @@ export async function addGrant(scope: PermissionScope, origin: string, ttlMs: nu
 		// Cap at MAX_GRANTS.
 		const capped = filtered.length > MAX_GRANTS ? filtered.slice(-MAX_GRANTS) : filtered;
 		await writeStore(capped);
+		setGrantCache(capped);
 		return true;
 	} finally {
 		await releaseLock();
@@ -196,6 +218,7 @@ export async function removeGrant(scope: PermissionScope, origin: string): Promi
 		const grants = pruneExpired(listGrants());
 		const filtered = grants.filter((g) => !(g.scope === scope && g.origin === normalized));
 		await writeStore(filtered);
+		setGrantCache(filtered);
 		return true;
 	} finally {
 		await releaseLock();

package/src/web-browser/browser-manager.ts

@@ -3,19 +3,33 @@
  *
  * Lazily launches a single headless Chromium instance. `context.pages()` is
  * the source of truth for open tabs; `this.page` is only an "active tab"
- * cursor that new pages (including popups) claim automatically. Page
- * interactions are serialized via an async mutex.
+ * cursor. Popups claim it only after an approved main-frame navigation.
+ * Page interactions are serialized via an async mutex.
  */
 
-import type { Browser, BrowserContext, Cookie, Locator, Page } from "playwright";
+import type {
+	APIResponse,
+	Browser,
+	BrowserContext,
+	Cookie,
+	Locator,
+	Page,
+	Response,
+	Route,
+	WebSocketRoute,
+} from "playwright";
 import { chromium } from "playwright";
 import { getTurndownService } from "../fetch-markdown.ts";
+import { permissionKey } from "../permissions.ts";
+import { decideRequest, type UrlPermissionChecker } from "./egress-policy.ts";
 
 export const DEFAULT_VIEWPORT_WIDTH = 1280;
 export const DEFAULT_VIEWPORT_HEIGHT = 720;
 export const MAX_FULL_PAGE_WIDTH = 1920;
 export const MAX_BUFFER_ENTRIES = 500;
 export const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000;
+const MAX_REDIRECT_HOPS = 20;
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
 
 type AbortableOpts = { timeout?: number; signal?: AbortSignal };
 type FrameOpts = { frame?: string };
@@ -133,6 +147,11 @@ export class BrowserManager {
 	private networkBuffer: NetworkEntry[] = [];
 	private dialogBuffer: DialogEntry[] = [];
 	private dialogBehavior: DialogBehavior = { action: "dismiss" };
+	private originChecker: UrlPermissionChecker = () => false;
+	private lastBlockedDocumentUrl: string | undefined;
+	private navigationPage: Page | undefined;
+	private navigationSignal: AbortSignal | undefined;
+	private readonly pendingRedirects = new WeakMap<Page, string>();
 	private readonly mutex = new AsyncMutex();
 	private closed = false; // true only after explicit close(), not on initial/normal state
 
@@ -185,19 +204,56 @@ export class BrowserManager {
 			await this.ensureLaunched();
 			const page = this.page!;
 			const timeout = opts?.timeout ?? DEFAULT_NAVIGATION_TIMEOUT_MS;
+			this.lastBlockedDocumentUrl = undefined;
+			this.navigationPage = page;
+			this.navigationSignal = opts?.signal;
 
-			const response = await this.withAbort(opts?.signal, async () =>
-				page.goto(url, {
-					timeout,
-					waitUntil: "domcontentloaded",
-				}),
-			);
+			let currentUrl = url;
+			try {
+				for (let redirects = 0; redirects <= MAX_REDIRECT_HOPS; redirects++) {
+					this.pendingRedirects.delete(page);
+					let response: Response | null;
+					try {
+						response = await this.withAbort(opts?.signal, async () =>
+							page.goto(currentUrl, {
+								timeout,
+								waitUntil: "domcontentloaded",
+							}),
+						);
+					} catch (err) {
+						if (opts?.signal?.aborted) throw err;
+						const redirectTarget = this.pendingRedirects.get(page);
+						if (redirectTarget) {
+							currentUrl = redirectTarget;
+							continue;
+						}
+						const blockedError = this.blockedNavigationError(url);
+						if (blockedError) throw blockedError;
+						throw err;
+					}
 
-			return {
-				url: page.url(),
-				title: await page.title(),
-				statusCode: response?.status(),
-			};
+					const redirectTarget = this.pendingRedirects.get(page);
+					if (redirectTarget) {
+						currentUrl = redirectTarget;
+						continue;
+					}
+
+					const blockedError = this.blockedNavigationError(url);
+					if (blockedError) throw blockedError;
+					return {
+						url: page.url(),
+						title: await page.title(),
+						statusCode: response?.status(),
+					};
+				}
+				throw new Error(`Blocked: more than ${MAX_REDIRECT_HOPS} redirects`);
+			} finally {
+				if (this.navigationPage === page) {
+					this.navigationPage = undefined;
+					this.navigationSignal = undefined;
+				}
+				this.pendingRedirects.delete(page);
+			}
 		});
 	}
 
@@ -389,7 +445,7 @@ export class BrowserManager {
 			await this.ensureLaunched();
 			const page = this.page!;
 			const timeout = opts?.timeout ?? DEFAULT_NAVIGATION_TIMEOUT_MS;
-			const locator = this.resolveLocator(page, selector ?? "body", opts?.frame).first();
+			const locator = this.resolveLocator(page, selector || "body", opts?.frame).first();
 			return this.withAbort(opts?.signal, async () => locator.innerText({ timeout }));
 		});
 	}
@@ -415,7 +471,7 @@ export class BrowserManager {
 			await this.ensureLaunched();
 			const page = this.page!;
 			const timeout = opts?.timeout ?? DEFAULT_NAVIGATION_TIMEOUT_MS;
-			const selector = opts?.selector ?? "body";
+			const selector = opts?.selector || "body";
 			const locator = this.resolveLocator(page, selector, opts?.frame);
 			try {
 				const snapshot = await this.withAbort(opts?.signal, async () =>
@@ -593,6 +649,10 @@ export class BrowserManager {
 		});
 	}
 
+	setOriginChecker(checker: UrlPermissionChecker): void {
+		this.originChecker = checker;
+	}
+
 	setDialogBehavior(action: "accept" | "dismiss", promptText?: string): void {
 		this.dialogBehavior = { action, promptText };
 	}
@@ -685,15 +745,8 @@ export class BrowserManager {
 	 *                    (default 5000). Set to 0 for unbounded.
 	 */
 	async close(timeoutMs = 5_000): Promise<void> {
-		// Mark closed immediately so ensureLaunched() bails out.
 		this.closed = true;
 
-		// Drain the mutex chain (wait for any in-flight operation to finish),
-		// then call cleanup directly — bypassing the mutex so no new
-		// operation can re-trigger ensureLaunched() mid-shutdown.
-		await this.mutex.drain();
-
-		// Force-close with optional timeout.
 		await this.forceClose(timeoutMs);
 	}
 
@@ -705,17 +758,23 @@ export class BrowserManager {
 	 * than blocking indefinitely.
 	 */
 	private async forceClose(timeoutMs: number): Promise<void> {
+		if (timeoutMs <= 0) {
+			try {
+				await this.cleanup();
+			} catch {
+				// Cleanup error — best effort; resources are cleaned up by OS.
+			}
+			return;
+		}
+
 		let timerId: ReturnType<typeof setTimeout> | undefined;
-		const timer =
-			timeoutMs > 0
-				? new Promise<never>((_, reject) => {
-						timerId = setTimeout(
-							() => reject(new Error("Close timed out")),
-							timeoutMs,
-						);
-						if (typeof timerId.unref === "function") timerId.unref();
-				  })
-				: Promise.resolve();
+		const timer = new Promise<never>((_, reject) => {
+			timerId = setTimeout(
+				() => reject(new Error("Close timed out")),
+				timeoutMs,
+			);
+			if (typeof timerId.unref === "function") timerId.unref();
+		});
 
 		try {
 			await Promise.race([this.cleanup(), timer]);
@@ -841,7 +900,12 @@ export class BrowserManager {
 					height: DEFAULT_VIEWPORT_HEIGHT,
 				},
 				acceptDownloads: false,
+				serviceWorkers: "block",
 			});
+			await this.context.route("**/*", (route) => this.enforceEgress(route));
+			await this.context.routeWebSocket("**/*", (webSocket) =>
+				this.enforceWebSocketEgress(webSocket),
+			);
 			this.context.on("page", (page) => this.registerPage(page));
 			this.page = await this.context.newPage();
 			this.closed = false;
@@ -858,16 +922,291 @@ export class BrowserManager {
 	}
 
 	/**
-	 * Attaches console/network/dialog listeners to every page in the context
-	 * (including the initial page and popups) and claims it as the active
-	 * tab. This is the single attachment point — `context.on("page")` also
-	 * fires for `context.newPage()`, so listeners must not be attached
-	 * anywhere else or they would be registered twice.
+	 * Attaches listeners to every page in the context. The initial page is
+	 * active immediately; popups become active only after an approved main-
+	 * frame navigation commits.
 	 */
 	private registerPage(page: Page): void {
 		this.attachConsoleListeners(page);
 		this.attachDialogListener(page);
-		this.page = page;
+
+		let pendingActivation = this.page !== undefined && !this.page.isClosed();
+		if (!pendingActivation) {
+			this.page = page;
+		}
+
+		page.on("framenavigated", (frame) => {
+			if (frame !== page.mainFrame()) return;
+			this.handleMainFrameNavigation(page, frame.url(), pendingActivation)
+				.then((activate) => {
+					if (activate && pendingActivation && !page.isClosed()) {
+						this.page = page;
+						pendingActivation = false;
+					}
+				})
+				.catch(() => {
+					this.closeBlockedPage(page).catch(() => {});
+				});
+		});
+
+		// The context-level page event can arrive after the first navigation has
+		// committed, in which case no later framenavigated event will activate it.
+		const currentUrl = page.url();
+		if (
+			pendingActivation &&
+			currentUrl !== "about:blank" &&
+			decideRequest(currentUrl, "document", currentUrl, this.originChecker).allow
+		) {
+			this.page = page;
+			pendingActivation = false;
+		}
+	}
+
+	private async enforceEgress(route: Route): Promise<void> {
+		const request = route.request();
+		let requestPage: Page | undefined;
+		let pageUrl = "";
+		let isMainFrameRequest = false;
+		try {
+			const frame = request.frame();
+			requestPage = frame.page();
+			pageUrl = requestPage.url();
+			isMainFrameRequest = frame === requestPage.mainFrame();
+		} catch {
+			// Requests without an issuing page are evaluated with an empty page URL.
+		}
+
+		const decision = decideRequest(
+			request.url(),
+			request.resourceType(),
+			pageUrl,
+			this.originChecker,
+		);
+		if (decision.allow) {
+			const protocol = new URL(request.url()).protocol;
+			if (protocol !== "http:" && protocol !== "https:") {
+				await route.continue();
+				return;
+			}
+
+			// route.continue() follows redirect hops without routing them again.
+			// Fetch one response without redirects so Location can be approved
+			// before Chromium receives a response that would contact the target.
+			let response: APIResponse;
+			try {
+				response = await route.fetch({
+					maxRedirects: 0,
+					signal: requestPage === this.navigationPage ? this.navigationSignal : undefined,
+				});
+			} catch {
+				try {
+					await route.abort(this.navigationSignal?.aborted ? "aborted" : "failed");
+				} catch {
+					// The request may already be gone after a page or context closes.
+				}
+				return;
+			}
+			const location = REDIRECT_STATUS_CODES.has(response.status())
+				? response.headers().location
+				: undefined;
+			if (!location) {
+				try {
+					await route.fulfill({ response });
+				} finally {
+					await response.dispose();
+				}
+				return;
+			}
+
+			let redirectUrl: string;
+			try {
+				redirectUrl = new URL(location, request.url()).toString();
+			} catch {
+				await response.dispose();
+				this.pushNetwork({
+					type: "failed",
+					url: request.url(),
+					method: request.method(),
+					status: 0,
+					statusText: "",
+					failure: "blocked by egress policy: Invalid redirect URL",
+					timestamp: Date.now(),
+				});
+				await route.abort("blockedbyclient");
+				return;
+			}
+
+			const redirectDecision = decideRequest(
+				redirectUrl,
+				request.resourceType(),
+				pageUrl,
+				this.originChecker,
+			);
+			await response.dispose();
+
+			if (!redirectDecision.allow) {
+				if (isMainFrameRequest && requestPage === this.navigationPage) {
+					this.lastBlockedDocumentUrl = redirectUrl;
+				}
+				this.pushNetwork({
+					type: "failed",
+					url: redirectUrl,
+					method: request.method(),
+					status: 0,
+					statusText: "",
+					failure: `blocked by egress policy: ${redirectDecision.reason}`,
+					timestamp: Date.now(),
+				});
+				await route.abort("blockedbyclient");
+				if (isMainFrameRequest && requestPage && requestPage !== this.page) {
+					await this.closeBlockedPage(requestPage);
+				}
+				return;
+			}
+
+			if (request.resourceType() !== "document" || !isMainFrameRequest || !requestPage) {
+				this.pushNetwork({
+					type: "failed",
+					url: redirectUrl,
+					method: request.method(),
+					status: 0,
+					statusText: "",
+					failure: "blocked by egress policy: Redirected subrequests are not followed",
+					timestamp: Date.now(),
+				});
+				await route.abort("blockedbyclient");
+				return;
+			}
+
+			this.pendingRedirects.set(requestPage, redirectUrl);
+			await route.fulfill({
+				status: 200,
+				contentType: "text/html",
+				body: "<!doctype html><meta charset=\"utf-8\"><title>Redirecting</title>",
+			});
+			if (requestPage !== this.navigationPage) {
+				setTimeout(() => {
+					if (requestPage.isClosed()) return;
+					this.pendingRedirects.delete(requestPage);
+					requestPage.goto(redirectUrl, { waitUntil: "domcontentloaded" }).catch(() => {
+						if (requestPage !== this.page) this.closeBlockedPage(requestPage).catch(() => {});
+					});
+				}, 0);
+			}
+			return;
+		}
+
+		if (
+			request.resourceType() === "document" &&
+			isMainFrameRequest &&
+			requestPage === this.page
+		) {
+			this.lastBlockedDocumentUrl = request.url();
+		}
+		this.pushNetwork({
+			type: "failed",
+			url: request.url(),
+			method: request.method(),
+			status: 0,
+			statusText: "",
+			failure: `blocked by egress policy: ${decision.reason}`,
+			timestamp: Date.now(),
+		});
+
+		await route.abort("blockedbyclient");
+		if (request.resourceType() === "document" && requestPage && requestPage !== this.page) {
+			await this.closeBlockedPage(requestPage);
+		}
+	}
+
+	private blockedNavigationError(requestedUrl: string): Error | undefined {
+		if (!this.lastBlockedDocumentUrl) return undefined;
+		const blockedTarget = permissionKey(this.lastBlockedDocumentUrl);
+		const navigationType = blockedTarget === permissionKey(requestedUrl) ? "navigation" : "redirect";
+		return new Error(`Blocked: ${navigationType} to ${blockedTarget} requires approval`);
+	}
+
+	private async enforceWebSocketEgress(webSocket: WebSocketRoute): Promise<void> {
+		const url = webSocket.url();
+		let permitted = false;
+		try {
+			permitted = this.originChecker(url);
+		} catch {
+			// Fail closed when the live permission source cannot be read.
+		}
+
+		if (permitted) {
+			webSocket.connectToServer();
+			return;
+		}
+
+		this.pushNetwork({
+			type: "failed",
+			url,
+			method: "GET",
+			status: 0,
+			statusText: "",
+			failure: "blocked by egress policy: WebSocket URL is not approved",
+			timestamp: Date.now(),
+		});
+		await webSocket.close({ code: 1008, reason: "blocked by egress policy" });
+	}
+
+	private async handleMainFrameNavigation(
+		page: Page,
+		url: string,
+		pendingActivation: boolean,
+	): Promise<boolean> {
+		if (pendingActivation && url === "about:blank") return false;
+		if (
+			url === "chrome-error://chromewebdata/" &&
+			(page === this.navigationPage || this.pendingRedirects.has(page))
+		) {
+			return false;
+		}
+
+		const decision = decideRequest(url, "document", url, this.originChecker);
+		if (decision.allow) return pendingActivation;
+
+		this.pushNetwork({
+			type: "failed",
+			url,
+			method: "GET",
+			status: 0,
+			statusText: "",
+			failure: `blocked by egress policy: ${decision.reason}`,
+			timestamp: Date.now(),
+		});
+
+		if (pendingActivation) {
+			await this.closeBlockedPage(page);
+			return false;
+		}
+
+		try {
+			await page.goBack({ waitUntil: "commit" });
+		} catch {
+			// Fall through and close a page that cannot return to an approved URL.
+		}
+
+		if (!page.isClosed()) {
+			const current = decideRequest(page.url(), "document", page.url(), this.originChecker);
+			if (!current.allow) await this.closeBlockedPage(page);
+		}
+		return false;
+	}
+
+	private async closeBlockedPage(page: Page): Promise<void> {
+		try {
+			await page.close({ runBeforeUnload: false });
+		} catch {
+			// The page may already have closed while its request was being aborted.
+		}
+
+		if (this.page === page) {
+			const fallback = this.context?.pages().filter((candidate) => !candidate.isClosed()).at(-1);
+			this.page = fallback;
+		}
 	}
 
 	private attachConsoleListeners(page: Page): void {
@@ -878,13 +1217,15 @@ export class BrowserManager {
 			this.pushConsole({ type: "pageerror", text: err.message, timestamp: Date.now() });
 		});
 		page.on("requestfailed", (req) => {
+			const failure = req.failure()?.errorText ?? "unknown";
+			if (failure.includes("ERR_BLOCKED_BY_CLIENT")) return;
 			this.pushNetwork({
 				type: "failed",
 				url: req.url(),
 				method: req.method(),
 				status: 0,
 				statusText: "",
-				failure: req.failure()?.errorText ?? "unknown",
+				failure,
 				timestamp: Date.now(),
 			});
 		});
@@ -953,7 +1294,13 @@ export class BrowserManager {
 		this.consoleBuffer = [];
 		this.networkBuffer = [];
 		this.dialogBuffer = [];
+		this.lastBlockedDocumentUrl = undefined;
 
+		try {
+			await this.context?.unrouteAll({ behavior: "ignoreErrors" });
+		} catch {
+			// ignore
+		}
 		try {
 			await this.page?.close({ runBeforeUnload: false });
 		} catch {

package/src/web-browser/egress-policy.ts

@@ -0,0 +1,145 @@
+import { isIP } from "node:net";
+import { isGranted } from "../permission-store.ts";
+import { isPreapprovedHost, permissionKey } from "../permissions.ts";
+
+export type EgressDecision = { allow: true } | { allow: false; reason: string };
+
+export type UrlPermissionChecker = (url: string) => boolean;
+
+function denied(reason: string): EgressDecision {
+	return { allow: false, reason };
+}
+
+function alternateWwwHostname(hostname: string): string | undefined {
+	const bareHostname = hostname.startsWith("www.") ? hostname.slice(4) : hostname;
+	const unbracketed = bareHostname.startsWith("[") && bareHostname.endsWith("]")
+		? bareHostname.slice(1, -1)
+		: bareHostname;
+	if (
+		!bareHostname.includes(".") ||
+		bareHostname === "localhost" ||
+		bareHostname.endsWith(".local") ||
+		isIP(unbracketed) !== 0
+	) {
+		return undefined;
+	}
+	return hostname.startsWith("www.") ? bareHostname : `www.${hostname}`;
+}
+
+/**
+ * Decide whether a browser request may leave the page.
+ *
+ * HTTP(S) requests require a live URL permission. The network-free internal
+ * about:blank page and data/blob subresources are allowed, but top-level
+ * data/blob documents are denied. Every file: request checks the approved
+ * target path. Local-file subresources additionally require a local-file page.
+ */
+export function decideRequest(
+	requestUrl: string,
+	requestResourceType: string,
+	pageUrl: string,
+	isPermittedUrl: UrlPermissionChecker,
+): EgressDecision {
+	let request: URL;
+	try {
+		request = new URL(requestUrl);
+	} catch {
+		return denied("Invalid request URL");
+	}
+
+	if (request.protocol === "http:" || request.protocol === "https:") {
+		try {
+			return isPermittedUrl(requestUrl)
+				? { allow: true }
+				: denied(`URL is not approved: ${permissionKey(requestUrl)}`);
+		} catch {
+			return denied("Permission check failed");
+		}
+	}
+
+	if (request.href === "about:blank") {
+		return { allow: true };
+	}
+
+	if (request.protocol === "data:" || request.protocol === "blob:") {
+		return requestResourceType === "document"
+			? denied(`${request.protocol} document navigation is not allowed`)
+			: { allow: true };
+	}
+
+	if (request.protocol !== "file:") {
+		return denied(`Unsupported request protocol: ${request.protocol}`);
+	}
+
+	try {
+		if (requestResourceType === "document") {
+			return isPermittedUrl(requestUrl)
+				? { allow: true }
+				: denied(`Local file is not approved: ${permissionKey(requestUrl)}`);
+		}
+
+		const page = new URL(pageUrl);
+		if (page.protocol !== "file:") {
+			return denied("Local-file subrequests require a local-file page");
+		}
+
+		return isPermittedUrl(requestUrl)
+			? { allow: true }
+			: denied(`Local file is not approved: ${permissionKey(requestUrl)}`);
+	} catch {
+		return denied("Permission check failed");
+	}
+}
+
+/** Build a live checker over preapproved URLs plus session and durable grants. */
+export function buildOriginChecker(
+	sessionPermissions: Map<string, "allow" | "deny">,
+): UrlPermissionChecker {
+	return (candidateUrl: string): boolean => {
+		let parsed: URL;
+		try {
+			parsed = new URL(candidateUrl);
+		} catch {
+			return false;
+		}
+
+		if (parsed.username || parsed.password) {
+			return false;
+		}
+
+		if (parsed.protocol === "ws:") parsed.protocol = "http:";
+		else if (parsed.protocol === "wss:") parsed.protocol = "https:";
+
+		if (
+			(parsed.protocol === "http:" || parsed.protocol === "https:") &&
+			isPreapprovedHost(parsed.hostname, parsed.pathname)
+		) {
+			return true;
+		}
+
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && parsed.protocol !== "file:") {
+			return false;
+		}
+
+		const key = permissionKey(parsed.toString());
+		const sessionDecision = sessionPermissions.get(key);
+		if (sessionDecision === "deny") return false;
+		if (sessionDecision === "allow") return true;
+		if (parsed.protocol !== "file:" && isGranted("web_browser", key)) return true;
+
+		if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+			const alternateHostname = alternateWwwHostname(parsed.hostname);
+			if (alternateHostname) {
+				const alternateUrl = new URL(parsed.toString());
+				alternateUrl.hostname = alternateHostname;
+				const alternateKey = permissionKey(alternateUrl.toString());
+				const alternateDecision = sessionPermissions.get(alternateKey);
+				if (alternateDecision === "deny") return false;
+				if (alternateDecision === "allow") return true;
+				if (isGranted("web_browser", alternateKey)) return true;
+			}
+		}
+
+		return false;
+	};
+}

package/src/web-browser/feeds.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const BROWSER_FEED_TYPE = "pi-topping-web-tools/browser";
+
+export interface BrowserFeedPayload {
+	label: string;
+	open: 0 | 1;
+}
+
+let extension: ExtensionAPI | undefined;
+let latestPayload: BrowserFeedPayload | undefined;
+let emittedPayload: BrowserFeedPayload | undefined;
+let publishAfterFirstTurn = false;
+
+function samePayload(left: BrowserFeedPayload | undefined, right: BrowserFeedPayload): boolean {
+	return left?.label === right.label && left.open === right.open;
+}
+
+function emitBrowserState(force = false): void {
+	if (!extension || !latestPayload || (!force && samePayload(emittedPayload, latestPayload))) return;
+	try {
+		extension.appendEntry(BROWSER_FEED_TYPE, latestPayload);
+		emittedPayload = latestPayload;
+	} catch {
+		// Feed publication is best effort; leave emitted state unchanged for retry.
+	}
+}
+
+export function registerBrowserFeeds(pi: ExtensionAPI): void {
+	extension = pi;
+	pi.on("session_start", () => {
+		emittedPayload = undefined;
+		publishAfterFirstTurn = true;
+	});
+	pi.on("turn_end", () => {
+		if (!publishAfterFirstTurn) return;
+		publishAfterFirstTurn = false;
+		emitBrowserState(true);
+	});
+}
+
+export function publishBrowserState(label: string, open: boolean | number): void {
+	latestPayload = { label, open: open ? 1 : 0 };
+	emitBrowserState();
+}
+
+export function resetBrowserFeedState(): void {
+	extension = undefined;
+	latestPayload = undefined;
+	emittedPayload = undefined;
+	publishAfterFirstTurn = false;
+}

package/src/web-browser/index.ts

@@ -28,10 +28,14 @@ import {
 	type SetCookieParam,
 	type TabInfo,
 } from "./browser-manager.ts";
+import { buildOriginChecker } from "./egress-policy.ts";
 import { checkUrlPermission, upgradeHttpToHttps, validateURL } from "./permissions.ts";
 import { requestHostPermission } from "../permission-prompt.ts";
 import { listGrants } from "../permission-store.ts";
+import { permissionKey } from "../permissions.ts";
 import { isInsideCwd } from "../pdf-extract.ts";
+import { suppressNotifications } from "../env.ts";
+import { publishBrowserState, registerBrowserFeeds } from "./feeds.ts";
 
 const ACTIONS = [
 	"navigate",
@@ -132,7 +136,8 @@ function formatTabs(tabs: TabInfo[]): string {
 
 function wrapUntrustedContent(url: string, text: string): string {
 	const safeUrl = url.replaceAll('"', "%22");
-	return `<untrusted-content url="${safeUrl}">\n${text}\n</untrusted-content>`;
+	const safeText = text.replaceAll(/<\/untrusted-content/gi, "");
+	return `<untrusted-content url="${safeUrl}">\n${safeText}\n</untrusted-content>`;
 }
 
 function isAbortError(err: unknown): boolean {
@@ -198,21 +203,47 @@ function browserStatus(ctx: ExtensionContext, text: string, tone: "success" | "m
 	return ctx.ui.theme.fg(tone, `browser: ${text}`);
 }
 
-function updateBrowserStatus(ctx: ExtensionContext, info: { url: string; title?: string }): void {
+export function browserLabel(url: string): string {
 	try {
-		const parsed = new URL(info.url);
-		const label = parsed.protocol === "file:" ? "local file" : parsed.hostname;
-		ctx.ui.setStatus("browser", browserStatus(ctx, label, "success"));
+		const parsed = new URL(url);
+		return parsed.protocol === "file:" ? "local file" : parsed.hostname || "ready";
 	} catch {
-		ctx.ui.setStatus("browser", browserStatus(ctx, "ready", "muted"));
+		return "ready";
+	}
+}
+
+function syncBrowserOpen(ctx: ExtensionContext, url: string): void {
+	const label = browserLabel(url);
+	publishBrowserState(label, 1);
+	if (!suppressNotifications()) {
+		ctx.ui.setStatus("browser", browserStatus(ctx, label, label === "ready" ? "muted" : "success"));
+	}
+}
+
+function syncBrowserClosed(ctx: ExtensionContext): void {
+	publishBrowserState("", 0);
+	if (!suppressNotifications()) {
+		ctx.ui.setStatus("browser", undefined);
 	}
 }
 
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
+	const originChecker = buildOriginChecker(sessionPermissions);
+	const getConfiguredBrowserManager = () => {
+		const manager = getBrowserManager();
+		manager.setOriginChecker(originChecker);
+		return manager;
+	};
+	registerBrowserFeeds(pi);
 
 	pi.on("session_start", async (_event, ctx) => {
-		ctx.ui.setStatus("browser", undefined);
+		const info = await getConfiguredBrowserManager().getPageInfoAsync();
+		if (info.isOpen) {
+			syncBrowserOpen(ctx, info.url);
+		} else {
+			syncBrowserClosed(ctx);
+		}
 	});
 
 	pi.on("session_shutdown", async () => {
@@ -226,16 +257,22 @@ export default function (pi: ExtensionAPI) {
 		const input = event.input as { action?: string; url?: string };
 
 		if (input.action === "navigate" && input.url) {
-			const permission = await checkUrlPermission(input.url, ctx, sessionPermissions);
+			const upgraded = upgradeHttpToHttps(input.url);
+			const permission = await checkUrlPermission(upgraded, ctx, sessionPermissions);
 			if (permission !== "allow") {
 				return { block: true, reason: blockReason(permission) };
 			}
 
+			// A browser navigation must keep its approved origin available to
+			// request-level enforcement after the tool-call hook returns.
+			if (!originChecker(upgraded)) {
+				sessionPermissions.set(permissionKey(upgraded), "allow");
+			}
 			return undefined;
 		}
 
 		if (input.action === "evaluate") {
-			const info = await getBrowserManager().getPageInfoAsync();
+			const info = await getConfiguredBrowserManager().getPageInfoAsync();
 			const permission = await checkUrlPermission(info.url, ctx, sessionPermissions);
 			if (permission !== "allow") {
 				return { block: true, reason: blockReason(permission) };
@@ -249,7 +286,7 @@ export default function (pi: ExtensionAPI) {
 		description:
 			"Show headless browser status (open/closed, URL, title, console and network counts, session-approved hosts)",
 		handler: async (_args, ctx) => {
-			const browser = getBrowserManager();
+			const browser = getConfiguredBrowserManager();
 			const info = await browser.getPageInfoAsync();
 			const lines = [
 				"Web Browser:",
@@ -271,7 +308,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Force close the headless browser",
 		handler: async (_args, ctx) => {
 			await closeBrowserManager();
-			ctx.ui.setStatus("browser", undefined);
+			syncBrowserClosed(ctx);
 			ctx.ui.notify("Browser closed", "info");
 		},
 	});
@@ -279,7 +316,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerCommand("browser-screenshot", {
 		description: "Save a full-page screenshot to a temp PNG file",
 		handler: async (_args, ctx) => {
-			const browser = getBrowserManager();
+			const browser = getConfiguredBrowserManager();
 			const info = await browser.getPageInfoAsync();
 			if (!info.isOpen) {
 				ctx.ui.notify("Browser is closed — navigate to a page first.", "warning");
@@ -306,13 +343,13 @@ export default function (pi: ExtensionAPI) {
 			"On SPA sites, use wait_for after navigate (selector/state or networkidle) before click/type.",
 			"Use screenshot for visual verification (requires a vision-capable model); use toFile=true to save PNG to disk instead of base64.",
 			"Use get_console_logs when JavaScript errors or console output may explain page behavior.",
-			"Use get_network_logs when failed requests or 4xx/5xx responses may explain page behavior.",
+			"Use get_network_logs when failed, egress-blocked, or 4xx/5xx requests may explain page behavior. Navigate directly to a blocked origin to request approval.",
 			"Use set_cookies to inject cookies for authenticated flows after manual login.",
 			"Use hover to trigger tooltips/hover-menus before click; press for keyboard key events (Enter, Escape, Tab) — distinct from type mode:press which types characters; select_option to choose <select> dropdown values; set_viewport to resize the page for responsive/mobile checks.",
 			"Selectors are CSS selectors, or Playwright's role= and text= selector engines (e.g. role=button[name='Submit'], text=Sign in). If click/type fails, read the returned diagnostics and page snippet and adjust the selector.",
 			"Use frame to target an element inside an iframe: pass a CSS selector for the iframe itself, separate from the element selector.",
 			"Call set_dialog_behavior before the action that triggers a JS dialog (alert/confirm/prompt) — dialogs are dismissed by default, which would silently cancel a confirm(). Use get_dialog_logs to see captured dialogs.",
-			"Opening a link with target=_blank or window.open creates a popup that automatically becomes the active tab. Use list_tabs and switch_tab to manage multiple open tabs.",
+			"An approved target=_blank or window.open popup becomes the active tab; an unapproved popup is blocked and closed. Use list_tabs and switch_tab to manage open tabs.",
 			"Use scroll to bring an off-screen element into view (selector) or to scroll the page/container by pixel deltas; use drag for drag-and-drop between two selectors; use upload_file to set files on an <input type=file>.",
 		],
 		description:
@@ -442,14 +479,14 @@ export default function (pi: ExtensionAPI) {
 			try {
 				if (action === "close") {
 					await closeBrowserManager();
-					ctx.ui.setStatus("browser", undefined);
+					syncBrowserClosed(ctx);
 					return {
 						content: [{ type: "text", text: "Browser closed." }],
 						details: { action } satisfies WebBrowserDetails,
 					};
 				}
 
-				const mgr = getBrowserManager();
+				const mgr = getConfiguredBrowserManager();
 
 				switch (action) {
 					case "navigate": {
@@ -470,7 +507,7 @@ export default function (pi: ExtensionAPI) {
 
 						const upgraded = upgradeHttpToHttps(params.url);
 						const result: NavigateResult = await mgr.navigate(upgraded, { timeout, signal });
-						updateBrowserStatus(ctx, result);
+						syncBrowserOpen(ctx, result.url);
 
 						const text = `Navigated to ${result.url}\nTitle: ${result.title}${result.statusCode ? `\nStatus: ${result.statusCode}` : ""}`;
 						return {
@@ -494,7 +531,7 @@ export default function (pi: ExtensionAPI) {
 							signal,
 						});
 						const info = await mgr.getPageInfoAsync();
-						updateBrowserStatus(ctx, info);
+						syncBrowserOpen(ctx, info.url);
 						const dims = `${shot.width}×${shot.height}`;
 						const dimsNote = `${dims}${shot.fullPage ? " (full page)" : ""}`;
 
@@ -940,7 +977,7 @@ export default function (pi: ExtensionAPI) {
 						}
 						const msg = await mgr.switchTab(params.index);
 						const info = await mgr.getPageInfoAsync();
-						updateBrowserStatus(ctx, info);
+						syncBrowserOpen(ctx, info.url);
 						return {
 							content: [{ type: "text", text: msg }],
 							details: { action, bytes: Buffer.byteLength(msg) } satisfies WebBrowserDetails,
@@ -966,7 +1003,9 @@ export default function (pi: ExtensionAPI) {
 				}
 				const message = err instanceof Error ? err.message : String(err);
 				return {
-					content: [{ type: "text", text: `Browser error: ${message}` }],
+					content: [
+						{ type: "text", text: message.startsWith("Blocked:") ? message : `Browser error: ${message}` },
+					],
 					details: { action, error: message } satisfies WebBrowserDetails,
 					isError: true,
 				};