dsh-browser-playwright-codex 0.7.4 → 0.7.6

package/lib/legacy-config.js

@@ -0,0 +1,238 @@
+/**
+ * Legacy loader-row detection (2026-10-19 merge follow-up).
+ *
+ * 0.7.0 collapsed three loader rows (`browser-playwright`, `browser-tool`, and
+ * the `/service` entry) into one `- id: browser` row with nested
+ * `service` / `playwright` / `tool` config. The loader simply stops reading the
+ * old rows, so an upgraded deployment whose patch layer still lists them starts
+ * with the package defaults — and the package ships both power gates OFF.
+ *
+ * That failure is silent: nothing errors, the tools that the old row would have
+ * published are simply absent, and the user believes a capability is still on.
+ * A real 0.7.4 deployment was found in exactly this state (16 tools, no
+ * `evaluate` / `cdp`, `allowEvaluate: true` sitting in a row nobody reads).
+ *
+ * This module reads the patch layers (read-only, never writes) and reports the
+ * stale rows once per DSH home so the operator can fix the config instead of
+ * discovering the downgrade through a missing tool.
+ *
+ * @module dsh-browser-playwright-codex/legacy-config
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Row ids that 0.7.0 stopped reading. */
+export const LEGACY_ROW_IDS = ['browser-playwright', 'browser-tool', 'browser-playwright-service'];
+/**
+ * Subpath entries that 0.7.0 stopped mounting. Rows naming one of these are
+ * stale even when the user gave them some other id.
+ */
+export const LEGACY_ENTRY_NAMES = [
+    'dsh-browser-playwright-codex/tool',
+    'dsh-browser-playwright-codex/playwright',
+    'dsh-browser-playwright-codex/service',
+];
+/**
+ * Retired package names this project owns on npm. A row mounting one of them
+ * keeps a second, older settings card alive — and that card rewrites the patch
+ * layer in the pre-0.7.0 shape, so the fix keeps reverting.
+ *
+ * Matching is by package NAME, never by row id: `- id:` is a local label the
+ * user picks, so another plugin may legitimately call its row `browser-tool`.
+ * Only a row whose `name:` is one of ours is reported.
+ */
+export const RETIRED_PACKAGES = ['dsh-browser-playwright', 'dsh-browser-toggle'];
+/** A `- id:` at column 0 starts a loader row. */
+const ROW_ID = /^- id:\s*['"]?([A-Za-z0-9._-]+)['"]?\s*$/;
+/** `name:` at exactly two spaces belongs to the row, not to a nested config block. */
+const ROW_NAME = /^ {2}name:\s*['"]?([^'"\s#]+)['"]?\s*$/;
+/**
+ * Find loader rows in one patch file's text that 0.7.0 stopped reading.
+ *
+ * The evidence is always the row's `name:` — never its `- id:`, which is just a
+ * local label. A patch layer that happens to call some unrelated plugin's row
+ * `browser-tool` is not reported.
+ *
+ * Pure and text-only so the rule can be tested without touching a real patch
+ * layer. Comments are ignored naturally: a commented row fails the anchored
+ * `- id:` / `  name:` patterns.
+ *
+ * @param text - contents of a cordis.patch.yml layer
+ * @returns every stale row, in file order
+ */
+export function findLegacyRowsIn(text) {
+    const rows = [];
+    const lines = text.split(/\r?\n/);
+    let current;
+    const finish = () => {
+        const name = current?.name;
+        if (name !== undefined && LEGACY_ENTRY_NAMES.includes(name)) {
+            rows.push({
+                id: current?.id ?? '(no id)',
+                name,
+                line: current?.line ?? 0,
+                target: 'entry',
+            });
+        }
+        else if (name !== undefined && RETIRED_PACKAGES.includes(name)) {
+            rows.push({
+                id: current?.id ?? '(no id)',
+                name,
+                line: current?.line ?? 0,
+                target: 'package',
+            });
+        }
+        current = undefined;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        const id = ROW_ID.exec(line);
+        if (id !== null) {
+            finish();
+            const value = id[1];
+            if (value !== undefined)
+                current = { id: value, line: index + 1 };
+            continue;
+        }
+        if (current === undefined)
+            continue;
+        const name = ROW_NAME.exec(line);
+        const label = name?.[1];
+        if (label !== undefined && current.name === undefined)
+            current.name = label;
+    }
+    finish();
+    return rows;
+}
+/**
+ * The operator-facing warning for one patch file.
+ *
+ * Written as one self-contained paragraph pair on purpose: it lands in a log
+ * line, so it has to name the file, the rows, and the fix without the reader
+ * opening documentation first.
+ *
+ * @param file - absolute path of the patch layer
+ * @param rows - stale rows found in it
+ * @returns the warning text
+ */
+export function legacyRowWarning(file, rows) {
+    const listed = rows
+        .map((row) => `  - 第 ${String(row.line)} 行: - id: ${row.id} (name: ${row.name ?? '?'})` +
+        (row.target === 'package' ? '  ← 退役包' : '  ← 本插件 0.7.0 之前的入口'))
+        .join('\n');
+    const retired = rows.some((row) => row.target === 'package');
+    return [
+        'browser 插件发现 0.7.0 之前的旧加载行，当前版本不再读取它们 —— 那几行里的 config 全部不生效，',
+        '插件按包内默认值运行（allowEvaluate / allowCdp 默认关闭，等于你以为开着其实关着）。',
+        `文件: ${file}`,
+        listed,
+        ...(retired
+            ? [
+                '标了「退役包」的行挂的是本项目的旧包（dsh-browser-toggle / dsh-browser-playwright）：它们自带一张旧设置卡，',
+                '还会按旧写法改写这个文件，所以只改下面这几行会反复被改回去 —— 先把那一行去掉或禁用。',
+            ]
+            : []),
+        '改法：按 name 删掉这些旧行，然后打开一次设置页的「浏览器」卡片（它会整块重写成一行），',
+        "或手写一行 `- id: browser` + `name: 'dsh-browser-playwright-codex'`，并把 service / playwright / tool 三节写全。",
+        '判断依据是每行的 name（包名），不是 id —— id 只是本地标签，别人的插件也可能叫 browser-tool。',
+        '如果你确认某个 name 不是本插件的包，那它跟这条提示无关，忽略即可。',
+    ].join('\n');
+}
+/**
+ * Patch layers that can hold a browser row: the home layer plus every profile
+ * layer. Missing files and unreadable directories are skipped silently — this
+ * check must never be the reason a plugin fails to load.
+ *
+ * @param env - environment (`DSH_HOME` override, as the rest of the package uses)
+ * @returns candidate file paths, home layer first
+ */
+export async function patchLayers(env = process.env) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    const files = [join(home, 'cordis.patch.yml')];
+    const profiles = join(home, 'profiles');
+    let entries = [];
+    try {
+        entries = await readdir(profiles);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries.sort())
+        files.push(join(profiles, entry, 'cordis.patch.yml'));
+    return files;
+}
+/**
+ * Scan every patch layer for stale rows.
+ *
+ * @param env - environment (`DSH_HOME` override)
+ * @returns one entry per file that still lists a retired row; empty when clean
+ */
+export async function scanLegacyRows(env = process.env) {
+    const hits = [];
+    for (const file of await patchLayers(env)) {
+        let text = '';
+        try {
+            text = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rows = findLegacyRowsIn(text);
+        if (rows.length > 0)
+            hits.push({ file, rows });
+    }
+    return hits;
+}
+/** DSH homes already scanned in this process, so one load logs once. */
+const scannedHomes = new Set();
+/**
+ * Warn about stale loader rows, once per DSH home, never throwing.
+ *
+ * Call it from the plugin entry: it is advisory only, so a failure here must
+ * never affect mounting the capability.
+ *
+ * @param ctx - plugin context (its logger carries the message to the host log)
+ * @param env - environment (`DSH_HOME` override, as tests use)
+ * @param report - sink for the text (defaults to the context logger, then console)
+ */
+export async function warnLegacyRows(ctx, env = process.env, report) {
+    if (env.DSH_BROWSER_SKIP_LEGACY_SCAN === '1')
+        return;
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    if (scannedHomes.has(home))
+        return;
+    scannedHomes.add(home);
+    let hits = [];
+    try {
+        hits = await scanLegacyRows(env);
+    }
+    catch {
+        return;
+    }
+    if (hits.length === 0)
+        return;
+    const warn = report ?? loggerWarn(ctx);
+    for (const hit of hits) {
+        try {
+            warn(legacyRowWarning(hit.file, hit.rows));
+        }
+        catch {
+            // A logger that is not mounted yet must not break the load.
+        }
+    }
+}
+/** Best-effort warn sink: the context logger when it exists, otherwise console. */
+function loggerWarn(ctx) {
+    return (text) => {
+        try {
+            if (ctx.logger !== undefined) {
+                ctx.logger.warn(text);
+                return;
+            }
+        }
+        catch {
+            // fall through to console
+        }
+        console.warn(text);
+    };
+}

package/lib/navigation-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 白名单的网络层守卫：把「只能访问这些站点」变成**路上的一道闸**，而不是只在调用入口
+ * 打一次勾。
+ *
+ * 起因（2026-10-26 实测）：入口检查只覆盖 navigate / 点击带 href 的链接 / 切标签 / 开标签。
+ * 页面自己 `location.href = 'http://别的站点'`、meta refresh、302 跳转、表单提交，全都
+ * 绕过白名单——实测把名单设成 `127.0.0.1` 后，页面脚本一跳就落在了 `localhost` 上。
+ * 入口检查在这里永远追不上：那些导航不是插件发起的。
+ *
+ * 做法：接管这个 context 的每一条请求（context.route），按主机名判定。
+ *   - **文档请求**（导航、iframe）：不在名单里 → 掐断，并记下来。调用方在动作收尾时
+ *     用它把「我点了但页面没动」变成一条明确的 URL_NOT_ALLOWED，而不是一次静默。
+ *   - **数据请求**（xhr / fetch / eventsource）：不在名单里 → 掐断。页面脚本不该拿着
+ *     这个浏览器的身份去白名单外的站点取数据。
+ *   - 其余子资源（script / img / css / font / media）：放行。它们几乎是页面渲染的刚需
+ *     （CDN、头像、字体），且不带目标站点的凭据；拦掉只会让页面看起来是坏的。
+ *
+ * 只在配置了名单时才接管：空名单的语义是「任意站点」，此时接管路由纯属拖慢每一页
+ * （Playwright 的路由会关掉 HTTP 缓存）。
+ *
+ * @module dsh-browser-playwright-codex/navigation-guard
+ */
+import type { BrowserContext } from 'playwright-core';
+/** One request the guard refused, in the shape callers report it. */
+export interface BlockedRequest {
+    /** Full requested URL. */
+    url: string;
+    /** Hostname that was not in the allow-list. */
+    host: string;
+    /** Playwright resourceType: document, xhr, script, … */
+    resourceType: string;
+    /** True for a navigation-level block (a document request). */
+    document: boolean;
+    /** Epoch milliseconds. */
+    at: number;
+}
+/**
+ * Refuse every request to a host outside the allow-list for one context.
+ *
+ * Installed once per context, before the first navigation. When the configured
+ * list is empty nothing is installed: "any host" must not pay the routing cost.
+ * @param context - the context to guard.
+ * @param allowedDomains - reads the live allow-list.
+ * @param onBlocked - called for each refused request; the caller keeps the last
+ *   document-level block and turns it into an error for the action that caused it.
+ * @returns true when a guard was installed, false when the list is empty.
+ */
+export declare function installHostGuard(context: BrowserContext, allowedDomains: () => readonly string[], onBlocked: (blocked: BlockedRequest) => void): Promise<boolean>;

package/lib/navigation-guard.js

@@ -0,0 +1,48 @@
+import { isHostAllowed } from "./url-policy.js";
+/** Resource types that carry data off the page and are refused outside the allow-list. */
+const DATA_RESOURCE_TYPES = new Set(['xhr', 'fetch', 'eventsource']);
+/**
+ * Refuse every request to a host outside the allow-list for one context.
+ *
+ * Installed once per context, before the first navigation. When the configured
+ * list is empty nothing is installed: "any host" must not pay the routing cost.
+ * @param context - the context to guard.
+ * @param allowedDomains - reads the live allow-list.
+ * @param onBlocked - called for each refused request; the caller keeps the last
+ *   document-level block and turns it into an error for the action that caused it.
+ * @returns true when a guard was installed, false when the list is empty.
+ */
+export async function installHostGuard(context, allowedDomains, onBlocked) {
+    const domains = allowedDomains();
+    if (domains.length === 0)
+        return false;
+    await context.route('**/*', async (route) => {
+        const request = route.request();
+        let host;
+        try {
+            host = new URL(request.url()).hostname;
+        }
+        catch {
+            // Not a URL we can judge (data:, blob:, about:, chrome-extension: …).
+            // Neither a host nor a site the policy talks about: let the browser decide.
+            await route.continue().catch(() => { });
+            return;
+        }
+        if (isHostAllowed(host, allowedDomains())) {
+            await route.continue().catch(() => { });
+            return;
+        }
+        const resourceType = request.resourceType();
+        const document = resourceType === 'document';
+        // Sub-resources the page needs in order to render are left alone; only the
+        // request classes that move the user or move data are refused.
+        if (!document && !DATA_RESOURCE_TYPES.has(resourceType)) {
+            await route.continue().catch(() => { });
+            return;
+        }
+        if (document)
+            onBlocked({ url: request.url(), host, resourceType, document, at: Date.now() });
+        await route.abort('blockedbyclient').catch(() => { });
+    });
+    return true;
+}

package/lib/page-actions.js

@@ -121,6 +121,9 @@ export async function navigate(session, url, waitUntil, signal) {
         catch (error) {
             if (isAbortError(error) || signal?.aborted === true)
                 throw error;
+            // A redirect chain can leave the allow-list: the guard refuses the hop and
+            // Playwright reports a plain navigation failure. Name the real cause.
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -716,6 +719,7 @@ export async function back(session, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -730,6 +734,7 @@ export async function forward(session, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);
@@ -776,6 +781,7 @@ export async function openTab(session, url, waitUntil, signal) {
         catch (error) {
             if (isAbortError(error))
                 throw error;
+            session.throwIfNavigationBlocked();
             throw asTimeoutError('navigation', error);
         }
         return session.settleAndSnapshot(page, true);

package/lib/page-snapshot.js

@@ -77,6 +77,11 @@ export async function settleAndSnapshot(session, page, navChanged) {
     });
     if (raced.blocked)
         return session.blockedSnapshot(page, raced.pending);
+    // A page can leave the allow-list without any entry-point check seeing it: the
+    // request-level guard catches self-started navigations, and this catches the
+    // redirect the browser followed on its own.
+    session.throwIfNavigationBlocked();
+    await session.assertCurrentUrlAllowed(page);
     return raced.value;
 }
 /**

package/lib/playwright.d.ts

@@ -11,6 +11,6 @@ export declare const inject: string[];
  */
 export { Config, type PageData, type PlaywrightConfig } from './config.ts';
 export { PlaywrightProvider } from './provider.ts';
-export { assertAllowedUrl } from './url-policy.ts';
+export { assertAllowedUrl, isHostAllowed } from './url-policy.ts';
 export { resolveSnapshotEngine } from './page-snapshot.ts';
 export declare function apply(ctx: Context, config: PlaywrightConfig): void;

package/lib/playwright.js

@@ -11,6 +11,8 @@
  *   page-snapshot.ts       capture, ref signatures, ref lookup
  *   page-diagnostics.ts    console messages, page errors, network records
  *   browser-lifecycle.ts   launching/reusing the persistent context, window state
+ *   window-focus.ts        is the window minimized / create a tab without raising it
+ *   navigation-guard.ts    the allow-list on the wire (refuses off-list requests)
  *   login-state.ts         exporting and restoring login state
  * @module dsh-browser-playwright-codex/playwright
  */
@@ -33,7 +35,7 @@ export const inject = ['browser'];
 // subpath stopped re-exporting it). The other names keep the pre-split public surface intact.
 export { Config } from "./config.js";
 export { PlaywrightProvider } from "./provider.js";
-export { assertAllowedUrl } from "./url-policy.js";
+export { assertAllowedUrl, isHostAllowed } from "./url-policy.js";
 export { resolveSnapshotEngine } from "./page-snapshot.js";
 export function apply(ctx, config) {
     const provider = new PlaywrightProvider(config);

package/lib/plugin.js

@@ -5,6 +5,7 @@ import * as tool from "./tool.js";
 import * as settingsCard from "./settings-card.js";
 import { Config as PlaywrightConfigSchema } from "./config.js";
 import { Config as ToolConfigSchema } from "./tool.js";
+import { warnLegacyRows } from "./legacy-config.js";
 /** Schemastery validation for {@link BrowserPluginConfig}. */
 export const Config = z.object({
     service: ServiceConfig,
@@ -21,6 +22,10 @@ export const name = 'browser';
  * @param config - nested config for each concern; the loader fills defaults
  */
 export function apply(ctx, config) {
+    // 0.7.0 stopped reading the three legacy rows, and a stale row downgrades the
+    // deployment to package defaults (both power gates off) without an error.
+    // Advisory only: it reads the patch layers and never blocks the mount.
+    void warnLegacyRows(ctx).catch(() => { });
     ctx.plugin(BrowserRuntime, config.service ?? {});
     ctx.plugin(playwright, config.playwright);
     ctx.plugin(tool, config.tool);

package/lib/provider.d.ts

@@ -1,6 +1,7 @@
 import { type Browser, type BrowserContext, type Dialog, type Page } from 'playwright-core';
 import { PlaywrightSession } from './session.ts';
 import type { PlaywrightConfig } from './config.ts';
+import { type BlockedRequest } from './navigation-guard.ts';
 /**
  * Playwright-backed {@link BrowserProvider}: one shared browser, one context
  * per owner key, LRU eviction, idle disposal, ref-based snapshot interaction.
@@ -50,6 +51,26 @@ export declare class PlaywrightProvider {
     /** Owner that raised the dialog currently parked on a page. */
     lastActor: string | undefined;
     lastStatePersist: number;
+    /**
+     * Launch in flight, so two sessions waking up at the same time share ONE
+     * launch instead of racing for the same profile directory.
+     *
+     * Measured 2026-10-26: two concurrent acquires both saw "no context yet" and
+     * both called launchPersistentContext. The second died on Chrome's profile
+     * singleton, the recovery path deleted the RUNNING browser's lock files, and
+     * the caller got "install a Chromium-family browser". The lock files being
+     * gone is what let a later launch start a second browser on the same profile
+     * and leave processes behind.
+     */
+    contextLaunch: Promise<BrowserContext> | undefined;
+    /** Same for the legacy shared-browser launch. */
+    browserLaunch: Promise<Browser> | undefined;
+    /**
+     * The last navigation the host guard refused. Read (and cleared) once by the
+     * action that caused it, so "I clicked and nothing happened" becomes a named
+     * URL_NOT_ALLOWED instead of a silent no-op.
+     */
+    blockedNavigation: BlockedRequest | undefined;
     constructor(config: PlaywrightConfig);
     available(): boolean;
     /** Pages already carrying the dialog guard (WeakSet: pages stay collectable). */
@@ -98,6 +119,14 @@ export declare class PlaywrightProvider {
      */
     private relaunchIfModeChanged;
     acquire(owner: string): Promise<PlaywrightSession>;
+    /**
+     * Keep the number of tracked owner handles inside maxSessions in persistent
+     * mode. Handles share one window, so dropping the least recently used idle
+     * handle costs nothing the user can see; the owner gets a fresh handle on the
+     * same window next time. An owner with an operation in flight is never dropped.
+     * @param keep - the owner being acquired right now.
+     */
+    private evictIdleHandles;
     disposeOwner(owner: string): Promise<void>;
     dispose(): Promise<void>;
     /** Touch the entry's last-used clock and re-arm its idle timer. */
@@ -120,6 +149,19 @@ export declare class PlaywrightProvider {
     ensureContext(): Promise<BrowserContext>;
     /** Remove stale Chrome singleton lock files inside the profile directory. */
     clearChromeLocks(): Promise<void>;
+    /**
+     * Put the allow-list on the wire for one context: every navigation and every
+     * data request outside the list is refused from then on, whoever started it.
+     * See navigation-guard.ts for why the entry-point checks alone were not enough.
+     * @param context - freshly created context, before its first navigation.
+     */
+    installHostGuard(context: BrowserContext): Promise<void>;
+    /**
+     * Take the pending "a navigation was refused" record, if any. Consumed once:
+     * the next action must not inherit the previous action's refusal.
+     * @returns the refused navigation, or undefined.
+     */
+    takeBlockedNavigation(): BlockedRequest | undefined;
     /**
      * Collect the login-state fallback WITHOUT ever opening a page while the
      * window is put away.

package/lib/provider.js

@@ -10,10 +10,11 @@ import {} from 'playwright-core';
 import os from 'node:os';
 import path from 'node:path';
 import { PlaywrightSession } from "./session.js";
-import { getEffectiveHeadless, getEnabled, publishConfiguredEngine, publishLoginSites, } from "./runtime-state.js";
+import { getEffectiveHeadless, getEnabled, publishConfiguredEngine, publishLoginSites } from "./runtime-state.js";
 import { BrowserError } from "./errors.js";
 import { SNAPSHOT_SCRIPT } from "./injected.js";
 import { isWindowMinimized } from "./window-focus.js";
+import { installHostGuard } from "./navigation-guard.js";
 export class PlaywrightProvider {
     config;
     id = 'playwright';
@@ -37,6 +38,26 @@ export class PlaywrightProvider {
     /** Owner that raised the dialog currently parked on a page. */
     lastActor;
     lastStatePersist = 0;
+    /**
+     * Launch in flight, so two sessions waking up at the same time share ONE
+     * launch instead of racing for the same profile directory.
+     *
+     * Measured 2026-10-26: two concurrent acquires both saw "no context yet" and
+     * both called launchPersistentContext. The second died on Chrome's profile
+     * singleton, the recovery path deleted the RUNNING browser's lock files, and
+     * the caller got "install a Chromium-family browser". The lock files being
+     * gone is what let a later launch start a second browser on the same profile
+     * and leave processes behind.
+     */
+    contextLaunch = undefined;
+    /** Same for the legacy shared-browser launch. */
+    browserLaunch = undefined;
+    /**
+     * The last navigation the host guard refused. Read (and cleared) once by the
+     * action that caused it, so "I clicked and nothing happened" becomes a named
+     * URL_NOT_ALLOWED instead of a silent no-op.
+     */
+    blockedNavigation = undefined;
     constructor(config) {
         this.config = config;
         // Tell the settings card which page-reading mode this deployment was
@@ -215,6 +236,11 @@ export class PlaywrightProvider {
             // window (Codex-style). Entries are lightweight session handles on
             // the shared context; the last owner to leave closes the window.
             const context = await this.ensureContext();
+            // maxSessions applies here too, but as a cap on HANDLES: all of them
+            // drive the same window, so evicting one costs nothing visible and the
+            // owner simply gets a fresh handle (same page set, index back to 0) next
+            // time. Before this, the setting was inert in the default mode.
+            this.evictIdleHandles(owner);
             const session = new PlaywrightSession(this, owner, context);
             const entry = { context, session, lastUsed: Date.now(), pending: 0, timer: undefined };
             this.entries.set(owner, entry);
@@ -238,6 +264,8 @@ export class PlaywrightProvider {
             ignoreHTTPSErrors: this.config.launch.ignoreHTTPSErrors,
         });
         context.on('page', (page) => this.armDialogGuard(page));
+        // Allow-list on the wire, not just at the entry points (navigation-guard.ts).
+        await this.installHostGuard(context);
         await context.addInitScript(SNAPSHOT_SCRIPT);
         const session = new PlaywrightSession(this, owner, context);
         const entry = { context, session, lastUsed: Date.now(), pending: 0, timer: undefined };
@@ -252,6 +280,30 @@ export class PlaywrightProvider {
         });
         return session;
     }
+    /**
+     * Keep the number of tracked owner handles inside maxSessions in persistent
+     * mode. Handles share one window, so dropping the least recently used idle
+     * handle costs nothing the user can see; the owner gets a fresh handle on the
+     * same window next time. An owner with an operation in flight is never dropped.
+     * @param keep - the owner being acquired right now.
+     */
+    evictIdleHandles(keep) {
+        const limit = this.config.maxSessions;
+        if (!Number.isFinite(limit) || limit <= 0)
+            return;
+        while (this.entries.size >= limit) {
+            const candidates = [...this.entries.entries()]
+                .filter(([key, entry]) => key !== keep && entry.pending === 0)
+                .sort((left, right) => left[1].lastUsed - right[1].lastUsed);
+            const oldest = candidates[0];
+            if (oldest === undefined)
+                return;
+            const [key, entry] = oldest;
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            this.entries.delete(key);
+        }
+    }
     async disposeOwner(owner) {
         const entry = this.entries.get(owner);
         if (entry === undefined)
@@ -275,6 +327,10 @@ export class PlaywrightProvider {
     }
     async dispose() {
         this.launchedHeadless = undefined;
+        // A launch still in flight must not re-create a context after disposal.
+        this.contextLaunch = undefined;
+        this.browserLaunch = undefined;
+        this.blockedNavigation = undefined;
         const owners = [...this.entries.keys()];
         for (const owner of owners)
             await this.disposeOwner(owner);
@@ -364,6 +420,29 @@ export class PlaywrightProvider {
     async clearChromeLocks() {
         return clearChromeLocks(this);
     }
+    /**
+     * Put the allow-list on the wire for one context: every navigation and every
+     * data request outside the list is refused from then on, whoever started it.
+     * See navigation-guard.ts for why the entry-point checks alone were not enough.
+     * @param context - freshly created context, before its first navigation.
+     */
+    async installHostGuard(context) {
+        this.blockedNavigation = undefined;
+        await installHostGuard(context, () => this.config.allowedDomains ?? [], (blocked) => {
+            if (blocked.document)
+                this.blockedNavigation = blocked;
+        });
+    }
+    /**
+     * Take the pending "a navigation was refused" record, if any. Consumed once:
+     * the next action must not inherit the previous action's refusal.
+     * @returns the refused navigation, or undefined.
+     */
+    takeBlockedNavigation() {
+        const blocked = this.blockedNavigation;
+        this.blockedNavigation = undefined;
+        return blocked;
+    }
     /**
      * Collect the login-state fallback WITHOUT ever opening a page while the
      * window is put away.