@openlines/opl-pi-sht 0.2.12 → 0.3.0

package/extensions/opl-browser/README.md

@@ -1,15 +1,10 @@
 # opl-browser
 
-Chromium browser automation for pi via [Playwright](https://playwright.dev). One
-LLM-callable dispatcher tool covers navigation, accessibility snapshots, element
-interaction, console/network capture, script evaluation, and screenshots —
-enough to replace the `chrome-devtools` MCP server without running a separate
-process.
+Chromium browser automation for pi via [Playwright](https://playwright.dev). One LLM-callable dispatcher tool covers navigation, accessibility snapshots, element interaction, console/network capture, script evaluation, and screenshots — enough to replace the `chrome-devtools` MCP server without running a separate process.
 
 ## Commands, flags, and shortcuts
 
-No slash commands. The extension registers a single tool, `browser`, chosen by an
-`action` parameter:
+No slash commands. The extension registers a single tool, `browser`, chosen by an `action` parameter:
 
 ```ts
 browser({ action: "navigate", url: "https://example.com" })
@@ -26,46 +21,56 @@ browser({ action: "get", responseId: "br-..." })   // retrieve a stored large re
 browser({ action: "close" })
 ```
 
-Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`,
-`extract`, `screenshot`, `click`, `fill`, `hover`, `press`, `select`, `evaluate`,
-`console`, `network`, `wait_for`, `pages`, `new_page`, `select_page`, `close_page`,
-`resize`, `get`, `close`.
+Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`, `extract`, `screenshot`, `click`, `fill`, `hover`, `press`, `select`, `evaluate`, `console`, `network`, `wait_for`, `pages`, `new_page`, `select_page`, `close_page`, `resize`, `get`, `close`.
 
 ## Extension features
 
-- **Single dispatcher tool.** One compact schema in the system prompt instead of
-  ~29 per-tool schemas. Keeps the cached prefix small.
-- **Handle + preview output.** Large results (snapshots, console/network logs,
-  evaluate output) are kept out of context: the tool returns a truncated preview
-  plus a `responseId`; call `action: "get"` with that id to page through the full
-  text (`getChars` per page, pass `offset` to continue). Screenshots are written to
-  a file, never inlined as base64.
-- **Structured extraction.** `extract` runs Readability + Turndown over the
-  *rendered* (post-JS) DOM — the complement to `opl-webaccess`'s `fetch_content`,
-  which only sees raw HTTP HTML. Static pages: `fetch_content`; rendered or
-  interacted-with pages: `browser:extract`. With a `selector`, the matched element
-  is converted verbatim (no article detection): Readability's candidate scoring is
-  a whole-document heuristic and mispicks inside small subtrees. A selector that
-  matches multiple elements returns a clear error instead of a strict-mode crash,
-  and a selector with no match reports `(no elements match ...)`.
-- **Real Chromium via Playwright.** Navigation with `domcontentloaded` waits,
-  CSS-selector interaction, viewport control, multi-page management.
-- **Scheme + path guards.** `navigate`/`new_page` accept http(s) only; `file:`,
-  `data:`, and `javascript:` are rejected, private-range and link-local hosts are
-  blocked by default, and cloud-metadata endpoints are always blocked (SSRF guard).
-  Loopback (`localhost`/`127.0.0.0/8`/`::1`) is allowed by default for local
-  development; set `allowPrivateNetwork: true` for private ranges. Redirect targets
-  are re-checked on the final URL. Screenshot paths must use `.png`/`.jpg`, stay
-  inside the project directory, and are refused when the file already exists, so a
-  bad action cannot overwrite or plant arbitrary files.
-- **Per-page capture.** Console messages and network requests are buffered per
-  page as they occur; `console` and `network` actions return the active page's
-  buffer, capped at the most recent `200` entries per page so an active
-  long-running page cannot grow the buffer without bound. `navigate: back`/
-  `forward` on a fresh session reports `(no history to go back/forward)` instead of
-  silently returning the unchanged page.
-- **One reused browser per session.** Launched on first use, closed automatically
-  on `session_shutdown`, or on demand via `action: "close"`.
+- **Single dispatcher tool.** One compact schema in the system prompt instead of ~29 per-tool schemas. Keeps the cached prefix small.
+- **Handle + preview output.** Large results (snapshots, console/network logs, evaluate output) are kept out of context: the tool returns a truncated preview plus a `responseId`; call `action: "get"` with that id to page through the full text (`getChars` per page, pass `offset` to continue). Screenshots are written to a file, never inlined as base64.
+- **Structured extraction.** `extract` runs Readability + Turndown over the *rendered* (post-JS) DOM — the complement to `opl-webaccess`'s `fetch_content`, which only sees raw HTTP HTML. Static pages: `fetch_content`; rendered or interacted-with pages: `browser:extract`. With a `selector`, the matched element is converted verbatim (no article detection): Readability's candidate scoring is a whole-document heuristic and mispicks inside small subtrees. A selector that matches multiple elements returns a clear error instead of a strict-mode crash, and a selector with no match reports `(no elements match ...)`.
+- **Real Chromium via Playwright.** Navigation with `domcontentloaded` waits, CSS-selector interaction, viewport control, multi-page management.
+- **Scheme + host guards, applied to the whole page.** `navigate`/`new_page` accept http(s)
+  only; `file:`, `data:`, and `javascript:` are rejected. The policy is judged on **resolved
+  addresses**, not on the URL text, and enforced wherever a page can reach the network:
+  - **Navigation** — the requested URL, plus every live frame URL after the load.
+  - **Page requests** — a context route blocks subresources, script-driven fetches, JS/meta
+    redirects and popups (`net::ERR_BLOCKED_BY_CLIENT`), not only the URL the tool was given.
+  - **Page WebSockets** — `ws://`/`wss://` handshakes are classified as if they were
+    `http://`/`https://` and closed before they reach the target.
+  - **Redirect landings** — Playwright sees only the first URL of a redirect chain, so a page or
+    iframe that a redirect lands on a blocked host is sent back to `about:blank` before any
+    action can read it.
+  - **Service workers** — blocked on new contexts: routing does not see requests a worker has
+    already intercepted.
+  - **Toggles** — `allowPrivateNetwork` (default `false`) governs private/link-local/reserved,
+    `allowLoopback` (default `false`) governs `localhost`, `127.0.0.0/8` and `::1` — set it to `true`
+    when the browser must reach a local dev server. Cloud metadata and unspecified addresses
+    (`0.0.0.0/8`, `::`) are refused whatever they say.
+  - **Fail closed** — if a build cannot install either handler, the tool refuses to browse
+    instead of browsing half-guarded.
+
+  See [Network policy](#network-policy) for what this still cannot cover: DNS rebinding (the
+  `opl-webaccess` fetch path pins its socket; browsing cannot), blind redirect side effects, and
+  `evaluate` returning page-held data.
+- **Screenshots are contained and reserved.** The target must use `.png`/`.jpg` and stay inside
+  the **session directory** (`ExtensionContext.cwd`, never the directory the harness was started
+  in). Containment is checked on the real path: every symlink in the existing part of the path is
+  followed first, so a `shots -> ~/.pi` entry inside the project cannot carry the write out of it,
+  and a symlink standing at the target is refused like any other existing file instead of being
+  followed onto whatever it points at. Then the file is created with `wx`, so "refuse to overwrite"
+  and "hand this path to Playwright" are one atomic operation rather than a check-then-write race.
+  The action returns the resolved absolute path, and a capture that throws leaves no empty file
+  behind.
+- **Pages are addressed, not guessed.** Any page-scoped action accepts `index`; without it the
+  selected page is used. A stale selection is an error that names the page count, never a silent
+  retarget to the last page - so `close_page` cannot make a later `screenshot` or `navigate` act on
+  a different document than the model meant. `new_page` selects the page it actually created, and
+  `close_page` keeps the same page selected when what closed was a different one (stepping to the
+  nearest survivor when the selected page itself closes).
+- **Per-page capture.** Console messages and network requests are buffered per page as they occur; `console` and `network` actions return the target page's buffer, capped at the most recent `200` entries per page so an active long-running page cannot grow the buffer without bound. `navigate: back`/ `forward` on a fresh session reports `(no history to go back/forward)` instead of silently returning the unchanged page.
+- **One reused browser per session.** Launched on first use, closed automatically on `session_shutdown`, or on demand via `action: "close"`.
+
+Selection follows the page object, so closing an earlier tab preserves the selected document. If the selected page closes externally (including `window.close()`), page-scoped actions without `index` fail until `select_page` or `new_page` establishes a selection; an explicit `index` targets the current live list without changing selection. Every action binds one page before validation and cannot switch documents if that page closes mid-action. Deliberate `close_page` keeps another selected page or selects the nearest survivor when closing the selection.
 
 ## Configuration
 
@@ -78,12 +83,35 @@ Optional `~/.pi/agent/configs/opl-browser.json` (see `opl-browser.json.sample`):
 | `navigationTimeoutMs` | `30000` | Default navigation and `wait_for` timeout. |
 | `previewChars` | `4000` | Inline threshold; larger outputs are stored and previewed. |
 | `getChars` | `30000` | Characters returned by one `action: "get"` page. |
-| `allowPrivateNetwork` | `false` | Allow `navigate`/`new_page` to reach private/link-local ranges (loopback is always allowed; cloud metadata is always blocked). |
+| `allowPrivateNetwork` | `false` | Allow `navigate`/`new_page` and page requests to reach private/link-local ranges, literal or resolved (cloud metadata and unspecified addresses are always blocked). |
+| `allowLoopback` | `false` | Allow loopback — `localhost`, `127.0.0.0/8`, `::1`, literal or resolved — for navigations, page requests and page WebSockets. Set `true` when the browser must reach a local dev server; `0.0.0.0/8` and `::` stay blocked either way, because they reach local listeners too. |
+
+### Network policy
+
+The guard runs at three points, and each one answers a different question:
+
+| Point | What it covers | Behaviour on a blocked host |
+|---|---|---|
+| Navigation (`navigate`, `new_page`) | the URL the model asked for, plus every live frame URL after the load | refuses before connecting; clears the page to `about:blank` if a redirect already landed it on a blocked host |
+| Context route | every request the page itself makes: subresources, script fetches, JS/meta redirects, popups | `net::ERR_BLOCKED_BY_CLIENT` |
+| WebSocket route | `ws://` / `wss://` handshakes from page code, classified as if they were `http://` / `https://` | socket closed before it reaches the target |
+
+Hosts are classified after resolution, not from the URL text, so `http://169.254.169.254.nip.io/` is refused the same way the literal is. Cloud-metadata and unspecified addresses (`0.0.0.0/8`, `::`) are refused whatever the toggles say, because reaching them means reaching local listeners or instance credentials. IPv6 literals that carry an IPv4 inside them — NAT64 (`64:ff9b::/96`), 6to4 (`2002::/16`), mapped (`::ffff:`) and the deprecated IPv4-compatible form — are classified by the embedded address, so `[64:ff9b::a9fe:a9fe]` cannot stand in for the metadata endpoint; a DNS64 answer for a real public site still passes. Service workers are blocked: Playwright routing does not see requests a worker has already intercepted, so a worker would be a hole rather than a client.
+
+Compressed and fully expanded IPv6 forms share the same policy, including DNS answers. The entire local-use translation prefix `64:ff9b:1::/48` is always blocked, regardless of `allowPrivateNetwork` or `allowLoopback`; this also blocks translations of public IPv4 addresses within that prefix. Public translations under the well-known `64:ff9b::/96` prefix remain permitted.
+
+What is **not** covered, and the reason:
+
+- **DNS rebinding.** Validation resolves, then Playwright connects with its own lookup. An attacker who runs DNS for the hostname (TTL 0, alternating answers) can still land on an internal address. Closing this needs a filtering proxy the browser connects through: Chromium resolves names internally and no Playwright API exposes a per-connection resolver, so the pin `opl-webaccess` uses for `fetch_content` is not available here. It is a documented residual rather than a bug: the defaults (`allowPrivateNetwork: false`, `allowLoopback: false`) are what narrows what a rebound name can reach.
+- **Blind side effects through redirects.** Playwright hands a route handler only the first URL of a redirect chain, and `<img>` or no-cors `fetch` results are not readable anyway, so those legs are not re-checked. The page-level result *is* cleared by the frame check above.
+- **`ENOTFOUND` for page requests.** A hostname the resolver does not know is let through, because hosts a page references willy-nilly (telemetry that is blocked in the hosts file, ad domains) would otherwise break every page. Navigations and `opl-webaccess` fetches fail closed on the same error; only page-initiated subresources and WebSockets fail open, and only for that one code.
+- **`evaluate` returns whatever the page holds.** That is the feature: a page that can read an internal endpoint from its own origin can also hand it to the model.
+
+Loopback is opt-in. `allowLoopback: true` reopens `localhost`, `127.0.0.0/8` and `::1` for local development; left at the default, a model cannot drive a dev server, a Docker socket proxy or an IDaaS callback on your machine through the browser.
 
 ### Dependencies
 
-Playwright is a real third-party dependency, so install it in the extension
-directory and download the Chromium binary once:
+Playwright is a real third-party dependency, so install it in the extension directory and download the Chromium binary once:
 
 ```bash
 cd extensions/opl-browser
@@ -99,17 +127,15 @@ index.ts     Pi wiring: registers the single `browser` tool, TTL result store,
 browser.ts   Playwright driver: browser/context/page lifecycle, per-page console
              and network buffers, and the action switch. Tool calls are serialized
              on the single shared context.
-validate.ts  URL/path guards: http/https-only navigation, screenshot path confined
-             to the project directory.
+validate.ts  URL/path guards: http/https-only navigation with resolved-address host
+             policy, page-request route decision, screenshot path confined
+             to the project directory. The host guard region is mirrored verbatim from
+             `opl-webaccess/utils.ts` (extensions install per directory, so it cannot be
+             a shared import); `tests/net-guard-parity.test.mjs` fails if the two drift.
 paging.ts    Bounded `get` pagination and continuation metadata.
 extract.ts   Pure rendered-HTML → markdown pipeline (linkedom + Readability +
              turndown), duplicated from opl-webaccess to keep installs independent.
 config.ts    DEFAULT_CONFIG + loadUserConfig (user overrides win via ??).
 ```
 
-Interaction is CSS-selector based. Snapshot-uid interaction (referencing elements
-by ids returned from `snapshot`) is intentionally not implemented; use CSS
-selectors, which are simpler and robust. The in-memory result store expires
-entries after one hour or when the browser is closed; expiry is checked on read,
-not only when another result is stored, so an idle entry past its TTL is never
-served.
+Interaction is CSS-selector based. Snapshot-uid interaction (referencing elements by ids returned from `snapshot`) is intentionally not implemented; use CSS selectors, which are simpler and robust. The in-memory result store expires entries after one hour or when the browser is closed; expiry is checked on read, not only when another result is stored, so an idle entry past its TTL is never served.

package/extensions/opl-browser/browser.ts

@@ -1,13 +1,13 @@
-import { chromium, type Browser, type BrowserContext, type Page, type ConsoleMessage } from "playwright";
+import { chromium, type Browser, type BrowserContext, type Page, type Route, type ConsoleMessage } from "playwright";
 import { extractMarkdown } from "./extract.js";
-import { assertHttpUrl, safeScreenshotPath } from "./validate.js";
+import { assertSafeHttpUrl, decideSubresource, discardEmptyFile, safeScreenshotPath, type HttpUrlOptions } from "./validate.js";
 import type { BrowserConfig } from "./config.js";
 
 // ponytail: single module-level Chromium instance reused across tool calls.
 // One browser per session is enough; add contexts only if parallel isolation matters.
 let browser: Browser | null = null;
 let context: BrowserContext | null = null;
-let activeIndex = 0;
+let selectedPage: Page | null = null;
 
 const consoleBuf = new WeakMap<Page, string[]>();
 const networkBuf = new WeakMap<Page, string[]>();
@@ -48,26 +48,191 @@ function track(page: Page, cfg: BrowserConfig): void {
 async function ensure(cfg: BrowserConfig): Promise<BrowserContext> {
   if (context) return context;
   browser = await chromium.launch({ headless: cfg.headless });
-  context = await browser.newContext({ viewport: { width: cfg.width, height: cfg.height } });
+  const created = await browser.newContext({
+    viewport: { width: cfg.width, height: cfg.height },
+    // Playwright documents that routing does not see requests a service worker already
+    // intercepted, so a worker would be a hole in the guard rather than another client of it.
+    serviceWorkers: "block",
+  });
+  // Install the guards before publishing the module-level context: if registration fails, the tool
+  // must not keep browsing through a context whose host guard is missing or only half installed.
+  try {
+    const wsGuarded = await installGuard(created, guardOf(cfg));
+    if (!wsGuarded) console.warn("[opl-browser] this build cannot intercept page WebSockets, so ws:// and wss:// from the page are unguarded");
+  } catch (err) {
+    await created.close().catch(() => {});
+    await browser.close().catch(() => {});
+    browser = null;
+    context = null;
+    throw new Error(`cannot enforce the network host guard in this browser build: ${err instanceof Error ? err.message : err}`);
+  }
+  context = created;
   const page = await context.newPage();
   track(page, cfg);
-  activeIndex = 0;
+  selectedPage = page;
   return context;
 }
 
-function page(): Page {
+/** Which page an action acts on. A stale or out-of-range selection is an error, never a silent
+ *  retarget: `context.pages()` is creation order, so the index a previous `pages` call showed is
+ *  the page the model means - unless something closed it, which is exactly when guessing the last
+ *  page would navigate or screenshot the wrong document. */
+export function resolvePageIndex(active: number, count: number, requested?: number): number {
+  if (count === 0) throw new Error("no open pages");
+  const i = requested ?? active;
+  if (!Number.isInteger(i) || i < 0 || i >= count) {
+    throw new Error(`no page at index ${i} (${count} page${count === 1 ? "" : "s"} open; use \`pages\` to list them)`);
+  }
+  return i;
+}
+
+/** The selection after closing `closed` from `count` pages: keep the same page when the closed one
+ *  was before it (indices shift down), otherwise fall to the nearest surviving page. */
+export function indexAfterClose(active: number, closed: number, count: number): number {
+  const remaining = count - 1;
+  if (remaining <= 0) return 0;
+  if (closed < active) return active - 1;
+  if (closed === active) return Math.min(active, remaining - 1);
+  return active;
+}
+
+/** The page for the current action: an explicit `index` argument wins, otherwise the selection. */
+function pageAt(requested?: number): Page {
   const pages = context!.pages();
-  if (!pages.length) throw new Error("no open pages");
-  return pages[activeIndex] ?? pages[pages.length - 1];
+  const active = selectedPage ? pages.indexOf(selectedPage) : -1;
+  if (requested === undefined && active < 0 && pages.length > 0) {
+    throw new Error("selected page closed; use `select_page` or `new_page` to select another document");
+  }
+  return pages[resolvePageIndex(active, pages.length, requested)]!;
+}
+
+/** Budget for one DNS round-trip. Playwright has no timeout of its own on a route handler, so a
+ *  stalled getaddrinfo would hold the navigation open; the guard cuts it instead. */
+const DNS_BUDGET_MS = 5000;
+
+/** The host policy applied to every navigation, frame re-check, page request and WebSocket. */
+export function guardOf(cfg: BrowserConfig): HttpUrlOptions {
+  return {
+    allowPrivateNetwork: cfg.allowPrivateNetwork,
+    allowLoopback: cfg.allowLoopback,
+    dnsTimeoutMs: DNS_BUDGET_MS,
+  };
+}
+
+/** Route handler for the shared context: covers subresources, JS-driven redirects and
+ *  popups, i.e. the requests a page makes that no tool argument ever named. Only http(s)
+ *  is consulted — `data:`/`blob:` have no host to classify and cannot be re-issued. */
+export function makeRouteHandler(guard: HttpUrlOptions): (route: Route) => Promise<void> {
+  return async (route) => {
+    const url = route.request().url();
+    if (url.startsWith("data:") || url.startsWith("blob:")) return;
+    const decision = await decideSubresource(url, guard);
+    if (decision === "abort") {
+      await route.abort("blockedbyclient");
+      return;
+    }
+    await route.continue();
+  };
+}
+
+/** Install both halves of the network guard on a context: http(s) requests and WebSocket
+ *  handshakes. Returns false when this Playwright build cannot intercept WebSockets, which is
+ *  reported rather than hidden: `route()` does not see `ws://`/`wss://`, so a page could otherwise
+ *  open a socket straight to an internal service while the tool claims the boundary is enforced. */
+export interface GuardTarget {
+  // `unknown` rather than `void`: Playwright's route registration hands back a Disposable, and a
+  // BrowserContext returns that where a Page returns void, so `void` would exclude contexts.
+  route(url: string, handler: (route: Route) => Promise<void>): Promise<unknown>;
+  routeWebSocket?(match: (url: URL) => boolean, handler: (ws: WebSocketRouteLike) => Promise<void>): Promise<unknown>;
+}
+
+export interface WebSocketRouteLike {
+  url(): string;
+  close(): Promise<void>;
+  connectToServer(): unknown;
 }
 
-/** Navigate with the host validated both before the request and on the final URL, so a
- *  public URL that redirects to a private/link-local host is rejected. */
+/** WebSockets are classified with the http(s) policy: `ws:` counts as `http:`, `wss:` as `https:`.
+ *  Anything the guard refuses, and anything it cannot classify, is closed. */
+export function makeWebSocketGuard(guard: HttpUrlOptions): (ws: WebSocketRouteLike) => Promise<void> {
+  return async (ws) => {
+    const asHttp = ws.url().replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+    let decision: "abort" | "continue";
+    try {
+      decision = await decideSubresource(asHttp, guard);
+    } catch {
+      decision = "abort";
+    }
+    if (decision === "abort") {
+      await ws.close().catch(() => {});
+      return;
+    }
+    ws.connectToServer();
+  };
+}
+
+export async function installGuard(ctx: GuardTarget, guard: HttpUrlOptions): Promise<boolean> {
+  await ctx.route("**/*", makeRouteHandler(guard));
+  if (typeof ctx.routeWebSocket !== "function") return false;
+  await ctx.routeWebSocket(() => true, makeWebSocketGuard(guard));
+  return true;
+}
+
+/** Navigate with the host validated both before the request and on the live frames after it,
+ *  so a public URL that redirects to a private/link-local host, or a hostname that answers
+ *  with an internal address, is rejected and the landed page is cleared. */
 async function gotoAllowed(target: Page, url: string, cfg: BrowserConfig): Promise<void> {
-  await target.goto(assertHttpUrl(url, { allowPrivateNetwork: cfg.allowPrivateNetwork }), { waitUntil: "domcontentloaded" });
-  assertHttpUrl(target.url(), { allowPrivateNetwork: cfg.allowPrivateNetwork });
+  const guard = guardOf(cfg);
+  await target.goto(await assertSafeHttpUrl(url, guard), { waitUntil: "domcontentloaded" });
+  await assertFrameTargetsSafe(target, guard);
+}
+
+/** Anything `pageAt()` can hand back: its live frames plus a way to clear them. */
+export interface FrameSafeTarget {
+  frames(): Array<{ url(): string }>;
+  goto(url: string, options?: { timeout?: number }): Promise<unknown>;
 }
 
+/** Playwright calls a route handler for the FIRST url of a redirect chain only, so a server-side
+ *  redirect can land a page or iframe on a host the guard already rejected and the route never
+ *  sees the second leg. Every read therefore re-checks the live frame URLs and clears the page
+ *  before its content can be returned. */
+export async function assertFrameTargetsSafe(target: FrameSafeTarget, guard: HttpUrlOptions): Promise<void> {
+  let failure: Error | undefined;
+  for (const frame of target.frames()) {
+    const url = frame.url();
+    if (!/^https?:/i.test(url)) continue; // about:blank, data:, blob:, empty: no host to classify
+    try {
+      await assertSafeHttpUrl(url, guard);
+    } catch (err) {
+      failure = err instanceof Error ? err : new Error(String(err));
+      break;
+    }
+  }
+  if (failure) {
+    await target.goto("about:blank", { timeout: 5000 }).catch(() => {});
+    throw new Error(`${failure.message} (page cleared)`);
+  }
+}
+
+/** Actions whose result is derived from, or acts upon, a page that is already open. */
+const PAGE_BOUND_ACTIONS = new Set([
+  "navigate",
+  "snapshot",
+  "extract",
+  "screenshot",
+  "click",
+  "fill",
+  "hover",
+  "press",
+  "select",
+  "evaluate",
+  "console",
+  "network",
+  "wait_for",
+  "resize",
+]);
+
 export interface BrowserActionResult {
   text: string;
   file?: string;
@@ -91,7 +256,7 @@ export interface BrowserParams {
 
 let last: Promise<unknown> = Promise.resolve();
 /** Serialize state-mutating browser work: a single shared context cannot service
- *  concurrent tool calls safely (activeIndex, page(), ensure() all race). Each new
+ *  concurrent tool calls safely (selection, pageAt(), ensure() all race). Each new
  *  action is queued behind the previous one, and failures never break the chain. */
 function serialize<T>(task: () => Promise<T>): Promise<T> {
   const run = last.then(task, task);
@@ -99,17 +264,29 @@ function serialize<T>(task: () => Promise<T>): Promise<T> {
   return run;
 }
 
-export function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
-  return serialize(() => runActionInternal(p, cfg));
+/** `cwd` is the session directory from `ExtensionContext`, never the harness working
+ *  directory: a screenshot
+ *  name that arrives from the model has to be contained against the project the user is in, and
+ *  the harness working directory is not that directory. */
+export function runAction(p: BrowserParams, cfg: BrowserConfig, cwd: string): Promise<BrowserActionResult> {
+  return serialize(() => runActionInternal(p, cfg, cwd));
 }
 
-async function runActionInternal(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+async function runActionInternal(p: BrowserParams, cfg: BrowserConfig, cwd: string): Promise<BrowserActionResult> {
   if (p.action === "close") {
     await closeBrowserInternal();
     return { text: "Browser closed." };
   }
 
   const ctx = await ensure(cfg);
+  const boundPage = PAGE_BOUND_ACTIONS.has(p.action) ? pageAt(p.index) : null;
+  const target = () => {
+    if (!boundPage || boundPage.isClosed()) throw new Error("target page closed; select another document before retrying");
+    return boundPage;
+  };
+  // A page can only have been landed on a blocked host through a path the route handler never
+  // saw (redirect chain, history, script). Re-check before touching or reading it.
+  if (PAGE_BOUND_ACTIONS.has(p.action)) await assertFrameTargetsSafe(target(), guardOf(cfg));
 
   switch (p.action) {
     case "navigate": {
@@ -117,24 +294,24 @@ async function runActionInternal(p: BrowserParams, cfg: BrowserConfig): Promise<
       if (url === "back" || url === "forward") {
         // Playwright returns null (no throw) when history is exhausted; report it
         // clearly instead of silently returning the unchanged page.
-        const moved = url === "back" ? await page().goBack() : await page().goForward();
+        const moved = url === "back" ? await target().goBack() : await target().goForward();
         if (!moved) return { text: `(no history to go ${url})` };
-        return { text: `${page().url()} — ${await page().title()}` };
+        return { text: `${target().url()} — ${await target().title()}` };
       }
-      if (url === "reload") await page().reload();
-      else if (url) await gotoAllowed(page(), url, cfg);
+      if (url === "reload") await target().reload();
+      else if (url) await gotoAllowed(target(), url, cfg);
       else throw new Error("navigate requires url (or back|forward|reload)");
-      return { text: `${page().url()} — ${await page().title()}` };
+      return { text: `${target().url()} — ${await target().title()}` };
     }
     case "snapshot": {
-      const tree = await page().locator("body").ariaSnapshot();
+      const tree = await target().locator("body").ariaSnapshot();
       return { text: tree || "(empty snapshot)" };
     }
     case "extract": {
       const selector = p.selector;
       let html: string;
       if (selector) {
-        const loc = page().locator(selector);
+        const loc = target().locator(selector);
         const count = await loc.count();
         if (count === 0) return { text: `(no elements match "${selector}")` };
         if (count > 1) {
@@ -142,92 +319,109 @@ async function runActionInternal(p: BrowserParams, cfg: BrowserConfig): Promise<
         }
         html = await loc.evaluate((el: Element) => el.outerHTML);
       } else {
-        html = await page().content();
+        html = await target().content();
       }
       const { markdown } = extractMarkdown(html, { raw: Boolean(selector) });
       return { text: markdown || "(empty extraction)" };
     }
     case "screenshot": {
-      const file = safeScreenshotPath(p.path ?? `opl-browser-${Date.now()}.png`);
-      await page().screenshot({ path: file, fullPage: p.fullPage ?? false });
+      const file = safeScreenshotPath(p.path ?? `opl-browser-${Date.now()}.png`, cwd);
+      try {
+        await target().screenshot({ path: file, fullPage: p.fullPage ?? false });
+      } catch (err) {
+        // The reservation above created an empty file; a capture that threw must not leave it.
+        discardEmptyFile(file);
+        throw err;
+      }
       return { text: `Screenshot saved to ${file}`, file };
     }
     case "click": {
       if (!p.selector) throw new Error("click requires selector");
-      await page().click(p.selector);
+      await target().click(p.selector);
       return { text: `Clicked ${p.selector}` };
     }
     case "fill": {
       if (!p.selector || p.text == null) throw new Error("fill requires selector and text");
-      await page().fill(p.selector, p.text);
+      await target().fill(p.selector, p.text);
       return { text: `Filled ${p.selector}` };
     }
     case "hover": {
       if (!p.selector) throw new Error("hover requires selector");
-      await page().hover(p.selector);
+      await target().hover(p.selector);
       return { text: `Hovered ${p.selector}` };
     }
     case "press": {
       if (!p.key) throw new Error("press requires key");
-      await page().keyboard.press(p.key);
+      await target().keyboard.press(p.key);
       return { text: `Pressed ${p.key}` };
     }
     case "select": {
       if (!p.selector || !p.values?.length) throw new Error("select requires selector and values");
-      const picked = await page().selectOption(p.selector, p.values);
+      const picked = await target().selectOption(p.selector, p.values);
       return { text: `Selected ${picked.join(", ")} in ${p.selector}` };
     }
     case "evaluate": {
       if (!p.script) throw new Error("evaluate requires script");
-      const value = await page().evaluate(p.script);
+      const value = await target().evaluate(p.script);
       if (value === undefined) return { text: "(undefined result)" };
       return { text: typeof value === "string" ? value : (JSON.stringify(value, null, 2) ?? "(undefined result)") };
     }
     case "console": {
-      const msgs = consoleBuf.get(page()) ?? [];
+      const msgs = consoleBuf.get(target()) ?? [];
       const suffix = msgs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} entries)` : "";
       return { text: msgs.length ? msgs.join("\n") + suffix : "(no console messages)" };
     }
     case "network": {
-      const reqs = networkBuf.get(page()) ?? [];
+      const reqs = networkBuf.get(target()) ?? [];
       const suffix = reqs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} requests)` : "";
       return { text: reqs.length ? reqs.join("\n") + suffix : "(no network requests)" };
     }
     case "wait_for": {
       const timeout = p.timeoutMs ?? cfg.navigationTimeoutMs;
-      if (p.selector) await page().waitForSelector(p.selector, { timeout });
-      else if (p.text) await page().getByText(p.text).first().waitFor({ timeout });
+      if (p.selector) await target().waitForSelector(p.selector, { timeout });
+      else if (p.text) await target().getByText(p.text).first().waitFor({ timeout });
       else throw new Error("wait_for requires selector or text");
       return { text: `Condition met` };
     }
     case "pages": {
-      const list = ctx.pages().map((pg, i) => `${i === activeIndex ? "*" : " "} [${i}] ${pg.url()}`);
+      const list = ctx.pages().map((pg, i) => `${pg === selectedPage ? "*" : " "} [${i}] ${pg.url()}`);
       return { text: list.join("\n") || "(no pages)" };
     }
     case "new_page": {
       const pg = await ctx.newPage();
       track(pg, cfg);
-      activeIndex = ctx.pages().length - 1;
+      // Select the page that was actually created; `pages()` order is creation order but a popup
+      // from another page can land in the same tick, so ask instead of assuming it is last.
+      const created = ctx.pages().indexOf(pg);
+      selectedPage = pg;
+      if (created < 0 || pg.isClosed()) throw new Error("new page closed before it could be selected");
       if (p.url) await gotoAllowed(pg, p.url, cfg);
-      return { text: `Opened page [${activeIndex}] ${pg.url()}` };
+      if (pg.isClosed()) throw new Error("new page closed during its safety check");
+      return { text: `Opened page [${ctx.pages().indexOf(pg)}] ${pg.url()}` };
     }
     case "select_page": {
-      const i = p.index ?? 0;
-      if (i < 0 || i >= ctx.pages().length) throw new Error(`no page at index ${i}`);
-      activeIndex = i;
-      return { text: `Selected page [${i}] ${page().url()}` };
+      const pg = pageAt(p.index ?? 0);
+      selectedPage = pg;
+      await assertFrameTargetsSafe(pg, guardOf(cfg));
+      if (pg.isClosed()) throw new Error("selected page closed during its safety check");
+      return { text: `Selected page [${ctx.pages().indexOf(pg)}] ${pg.url()}` };
     }
     case "close_page": {
-      const i = p.index ?? activeIndex;
       const pages = ctx.pages();
-      if (i < 0 || i >= pages.length) throw new Error(`no page at index ${i}`);
-      await pages[i].close();
-      activeIndex = Math.max(0, ctx.pages().length - 1);
-      return { text: `Closed page [${i}]` };
+      const doomed = pageAt(p.index);
+      const i = pages.indexOf(doomed);
+      await doomed.close();
+      const remaining = ctx.pages();
+      if (doomed === selectedPage) {
+        const next = indexAfterClose(i, i, pages.length);
+        selectedPage = remaining[Math.min(next, remaining.length - 1)] ?? null;
+      }
+      const active = selectedPage ? remaining.indexOf(selectedPage) : -1;
+      return { text: `Closed page [${i}]; selection is now ${active >= 0 ? `[${active}]` : "none"}${remaining.length ? "" : " (no pages left)"}` };
     }
     case "resize": {
       if (p.width == null || p.height == null) throw new Error("resize requires width and height");
-      await page().setViewportSize({ width: p.width, height: p.height });
+      await target().setViewportSize({ width: p.width, height: p.height });
       return { text: `Resized to ${p.width}x${p.height}` };
     }
     default:
@@ -248,5 +442,5 @@ async function closeBrowserInternal(): Promise<void> {
   }
   context = null;
   browser = null;
-  activeIndex = 0;
+  selectedPage = null;
 }