dsh-browser-playwright-codex 0.7.2 → 0.7.5

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+## 0.7.5 — 2026-10-26
+
+一句话摘要：**两条安全洞补上，同时唤醒不再多开浏览器** —— 白名单从"门口打一次勾"变成"装在浏览器的请求上"，`allowEvaluate` / `allowCdp` 从工具层下沉到会话层（绕过工具直接拿服务也拒），两个任务同时要浏览器时共用一次启动，默认持久化模式下「最多几个会话」也真的算数了。
+
+### Fixed
+
+- **白名单可被绕过（安全）**：入口检查只覆盖 `navigate` / 带 `href` 的点击 / 切标签 / 开标签，页面自己 `location.href='外站'`、meta refresh、`<form action="外站">` 提交、网页自开的弹窗全都绕得过去。实测把名单设成 `127.0.0.1` 后，页面脚本一跳就落在了 `localhost` 上。现在新增 `src/navigation-guard.ts`，把名单**装在这个浏览器 context 的请求上**：发往名单外主机的**导航**当场掐断并报 `URL_NOT_ALLOWED`，**数据请求**（`fetch` / `xhr` / `EventSource`）同样掐断；`script` / 图片 / CSS / 字体 / 媒体这类渲染资源放行，否则页面只会看起来是坏的。空名单（默认）完全不接管路由，所以默认行为一个字没变。
+- **302 跳转是请求拦截看不见的那一跳**：Chromium 在它自己的网络栈里跟随重定向，`context.route()` 根本不会为那一跳触发（实测）。所以每个动作收尾时还会核对页面**最终落在哪个主机**——落在名单外就报 `URL_NOT_ALLOWED`，并把标签页重置成 `about:blank`，绝不留一个可以继续驱动的越界页面。
+- **evaluate / CDP 的开关只在工具层挡（安全）**：此前只有 `tool.ts` 检查 `allowEvaluate` / `allowCdp`，任何拿到浏览器服务的代码（兄弟插件、脚本）都能直接调 `session.evaluate` 跑任意页面 JS，或用 `session.cdp` 发白名单外的 `Runtime.evaluate`（两条都实测跑通）。现在 `session.evaluate` / `session.cdp` 自己就拒（`EVALUATE_DISABLED` / `CDP_DISABLED`），CDP 还要再过一道白名单（`CDP_DENIED`）。**没发布过的门禁算关闭**——部署没说「可以」就是「不可以」。
+- **两个任务同时唤醒会多开浏览器**：`ensureContext` / `ensureBrowser` 没有在途合并，两个会话同时醒来都看到"还没有 context"，于是各自 `launchPersistentContext` 同一个 profile。实测后果比"多开"更难看：第二个死在 Chrome 的单例锁上，恢复流程**把正在运行的那个浏览器的锁文件删了**，而调用方收到的错误是「你没装浏览器」——锁被删正是之后关不干净、残留进程的来路。现在并发调用共享同一次启动，并且在途启动结束就清空；恢复路径也不再动活浏览器的锁文件。
+- **`maxSessions` 在默认（持久化）模式不生效**：这个上限只写在非持久化分支里，而默认就是持久化模式，所以形同虚设。现在它按**会话句柄**生效：最久没用、且当前没有操作在跑的句柄会被回收，共用窗口一动不动，那个 owner 下次拿到一个新句柄（同一批标签页，索引回到 0）。顺便修掉 `browser-lifecycle.ts` 一处复制粘贴多出来的重复赋值。
+- **设置卡可能把关闭的门禁显示成开着**：`publishGates` 原来上报的是「工具是否注册」，而 `registerDisabledTools: true` 会故意把关着的工具也注册（好让模型能发现它并读到说明），于是卡片把关闭的能力显示为开启。现在上报的是能力值本身。
+
+### Added
+
+- **`src/navigation-guard.ts`**：名单的请求层实现，含"文档请求 / 数据请求 / 渲染资源"三分类与拒绝记录。
+- **公开导出（只增不减）**：`isHostAllowed`、`installHostGuard`、`BlockedRequest`、`evaluateDisabled`、`cdpDisabled`。
+- **`tests/host-guard.test.ts`（4 条，真浏览器）**：空名单不插手（默认行为不变）、302 越界被拒并报出主机名、页面自己跳转永远到不了名单外、`fetch` 到名单外**服务器一个请求都没收到**。
+- **`tests/gates-enforcement.test.ts`（5 条，不需要浏览器）**：没发布门禁时 `evaluate` / `cdp` 都拒、开了 CDP 门禁 `Runtime.evaluate` 仍被白名单拒、门禁开关对会话层依旧权威、`getGates()` 报的是能力值。
+- **`tests/concurrency.test.ts`（3 条，真浏览器）**：三个会话同时唤醒共用一个窗口、两个会话同时唤醒共用一个浏览器、持久化模式下 `maxSessions` 按 LRU 回收句柄且窗口不动。
+- **随包验收新增 `[0]` 段（3 条）**：不经工具层直接调 `session.evaluate` / `session.cdp` 必须被拒；开了门禁后 `Runtime.evaluate` 仍报 `CDP_DENIED`。
+
+### Changed
+
+- **行为变化**：代码层调用 `evaluate` / `cdp` 现在也要过门禁，且未发布门禁 = 关闭。走工具层的老路径行为不变（工具层先给出同样口径的错误）。
+- **`allowedDomains` 的语义收紧**：填了名单，就不再只是"插件不去"，而是"这个浏览器不去"。
+- 三个测试文件（`provider` / `regressions` / `scenarios`，另加 `live-smoke`）显式发布门禁——它们本来就直接调 `session.evaluate`，等于把自己声明成"开了开关的部署"。
+
+### Tests
+
+- 全套 243 → **255 条**（+12）：通过 252、跳过 3、失败 0。
+- `npm run verify` 57 → **60 项**：`[0]` 段三条是新增的门禁回归闸。
+
+## 0.7.4 — 2026-10-23
+
+一句话摘要：**设置卡可以切换有头 / 无头** —— 运行时开关，不用改 YAML、不用重启 DSH；切换在**下一次操作**时生效（先导出登录态，再按新模式重开窗口）。默认仍是有头。
+
+### Added
+
+- **「浏览器窗口」开关**：设置卡新增单选「显示浏览器窗口（有头）」/「后台运行（无头）」，选择存进 `~/.dsh/dsh-browser-playwright.state.json`（与页面识别方式同一套 runtime-state），重启后仍记住。改完在**下一次浏览器操作**时重开窗口生效——不会打断正在进行的调用；代价是标签页和未提交的表单会丢，登录状态会先导出、不会丢。
+- **`POST /api/browser-playwright/window { headless }`**：校验布尔值，返回生效值与 `changed`；`GET /state` 同时返回 `headless` / `headlessUserChosen` / `headlessConfigured`，卡片据此显示「当前 / 你选的」。
+- **界面明确写清无头的代价**：无头模式下「看得见、能随时接手」的前提不成立——验证码/二次验证只剩提示，没人能在窗口里替你点；只在无人值守且接受这个代价时用。
+
+### Changed
+
+- **provider 按「期望模式 vs 实际启动模式」懒重开**：`desiredHeadless()` 读运行时选择（无选择时回退 `launch.headless`）；每次 acquire 前比较 `launchedHeadless`，不一致就先 `dispose()`（导出登录态、关窗）再按新模式启动。已经在用的 owner 切换模式也会被重建，而不是「下次重启才生效」。
+- **`launch.headless` 仍是配置默认**：配置里写什么就是没在卡片上选过时的默认值；两处启动路径（持久 context / legacy browser）都改为读解析后的值。
+
+### Fixed
+
+- **挑战页提示语随窗口模式变化**：无头模式下原提示仍说「浏览器窗口就在你桌面上，等人去点」——那个窗口不存在。现在无头时改为明确说「HEADLESS、没有窗口可完成验证；要么把窗口模式切回『显示浏览器窗口』让人处理，要么换一种方式」，并保留「不要盲目重试」的纪律。有头模式的措辞不变。
+
+### Tests
+
+- 运行时状态：窗口模式持久化、configured 默认只在没有用户选择时生效（2 条）。
+- provider：`desiredHeadless()` 用户选择优先于 `launch.headless`（1 条，无浏览器启动）。
+- 真机验收：有头启动 → 切无头（重开、会话句柄替换）→ 切回有头，状态文件落盘。
+
+## 0.7.3 — 2026-10-20
+
+一句话摘要：**设置卡新增「缓存与磁盘」** —— 把浏览器 profile 的纯缓存、%TEMP% 里的 dsh-* 残留、更新器残留、请求图缓存做成可预览、可逐项清理的面板；顺手修掉三处测试把临时目录泄进 %TEMP% 的根因。运行时代码零改动。
+
+### Added
+
+- **设置卡「缓存与磁盘」区块**：四类目标（浏览器缓存 / 临时残留 / 更新器残留 / 图片变体缓存）显示各自字节数与文件数，勾选后先「预演」看能释放多少，再「确认清理」；结果逐项报告释放量与跳过原因（占用中 / 权限 / 其它版本）。
+- **`src/cache-clean.ts`**：纯 `node:fs` 模块，两个入口 `scan()` / `clean()`。安全边界写在代码里而不是提示词里：目标是**枚举 id**（`browser-cache` / `temp-residue` / `updater-residue` / `attachment-cache`），路径一律由 DSH_HOME 与已知系统位置推导，请求体里的字符串永远不拼进路径；浏览器 profile 只删 Chromium 的纯缓存目录（Cache / Code Cache / GPUCache / ShaderCache / GrShaderCache / DawnCache / DawnGraphiteCache / ScriptCache / `*_crx_cache`），Cookies、Local Storage、Service Worker、IndexedDB、Network、Preferences 一律不碰。
+- **`GET /api/browser-playwright/disk/stat`** 与 **`POST /api/browser-playwright/disk/clean`**：沿用已有的 `x-dsh-plugin: browser-toggle` 防伪头（GET 与 POST 都验）、JSON 校验、枚举校验；失败逐条返回 `{ path, reason }`，不折成一个笼统错误。`~/.dsh/cache/attachments` 可清，`~/.dsh/attachments/v1/objects`（会话引用的原图）永不在清理范围内，只在统计里报大小。
+- **`tests/cache-clean.test.ts`**：9 条 fixture 用例——白名单内删干净、Cookies 与 Local Storage 一个不动、`dryRun` 不落盘、新临时目录预演时标 `in-use`、只清当前版本的更新器文件、附件缓存清空而会话原图保留、目标 id 拒绝任意路径、路径推导、字节格式化。
+
+### Fixed
+
+- **三处测试泄漏 %TEMP%**：`runtime-state.test.ts`、`provider.test.ts`、`login-state.test.ts` 用 `mkdtempSync` 创建的 `dsh-browser-state-*` / `dsh-provider-state-*` / `dsh-login-state-*` 目录从来没删，跑一次测试就在临时目录里留一堆空壳；现在各自登记并在 `after()` 里删掉。
+- **Windows 只读文件**：清理时先尝试普通删除，失败再 `chmod` 去掉只读位重试；**删成功之后才计入释放量**，不再出现"报了删除但一个没删"的假账。
+
 ## 0.7.2 — 2026-10-19
 
 一句话摘要：**设置卡推倒重做** —— 用户要求按 DSH 设置页规范重新设计：首屏只留「主开关 + 三个分区摘要」，所有长说明收进折叠。0.7.1 因卡在 npm staged 状态作废（版本号让给这一版）。

package/README.md

@@ -232,7 +232,7 @@ All tunables are patchable through the profile's `cordis.patch.yml` (later layer
         ignoreHTTPSErrors: false
       allowedDomains: []                  # e.g. ['github.com'] restricts navigation
       idleTimeoutMs: 0                    # shipped value: never auto-close (schema default 600000 = 10 min)
-      maxSessions: 8                      # LRU eviction (persistent mode: one window)
+      maxSessions: 8                      # live-session cap; persistent mode caps handles, still one window
       snapshot:
         engine: legacy                    # 'legacy' (default) or 'aria' (Playwright ariaSnapshot, refs aligned back)
         maxNodes: 500                     # token budget per snapshot tree
@@ -281,6 +281,16 @@ Both are honest trades, not free wins: a diff is smaller but requires the model
 tree, and an interactive-only snapshot hides the prose the model may want to read. Measure before
 turning them on in a deployment that shares prompts across many users.
 
+### Window mode (headful / headless)
+
+The Settings card has a **浏览器窗口** choice: show the window (headful, the default) or run it in the background (headless). The pick is stored in `~/.dsh/dsh-browser-playwright.state.json` and survives restarts; `launch.headless` stays the configured default for anyone who never picks.
+
+Switching takes effect on the **next browser operation**: the provider compares the mode it launched with against the desired one and relaunches (login state is exported first, so the login survives; tabs and unsaved page state do not). Headless is honest about its cost — with no visible window, the “watch it and take over” guarantee for sign-ins and CAPTCHAs no longer holds, so use it only for unattended work where you accept that.
+
+### Cache and disk
+
+The Settings card also carries a **缓存与磁盘** section: Chromium's pure caches inside the plugin's profile, `dsh-*` residue in `%TEMP%`, updater installers of the installed version, and the request-image cache are listed with their sizes; you preview first (“先预演”) and only then confirm. Cookies, Local Storage, Service Worker, IndexedDB, Network, Preferences and `~/.dsh/attachments` are never in scope — the target list is a closed enum in `src/cache-clean.ts`, and no path is ever taken from the request.
+
 ### Prefer a switch to editing config?
 
 The Settings card ships **inside this package** (it moved out of the companion package `dsh-browser-toggle`, which is retired) and puts
@@ -320,7 +330,7 @@ npm install
 npm test           # full suite: engine/action integration on real Chrome, policy, rendering,
                    # schema assembly, plus the realistic scenario suites below
 npm run verify     # naming/folding + click/hover/dialog acceptance; self-contained, prints its own count
-                   # (57 in a checkout; from an npm install it prints 56 + "1 skipped", because the
+                   # (60 in a checkout; from an npm install it prints 59 + "1 skipped", because the
                    #  `lib/`-vs-`src/` check has no `src/` to compare against)
 npm run verify:live  # same, plus a live sample of a real page (needs network)
 npm run doctor     # does the installed harness still export everything this plugin imports?
@@ -416,7 +426,7 @@ links below go to GitHub rather than to files inside the package:
 - **Headless servers must opt in** — the bundle defaults to `headless: false`; on a headless/remote host set `launch.headless: true`.
 - **Selector-free, not vision-free** — interaction is a11y-tree based; purely visual widgets (canvas, WebGL, custom-drawn controls) may expose no refs. `browser_screenshot` + an image-capable model is the fallback.
 - **Cross-origin iframes** appear as leaf `(frame)` nodes without refs; same-origin frames are walked up to two levels deep.
-- **Evaluate gate is config, not approval** — enabling `allowEvaluate` trusts the model with arbitrary page JavaScript; compose it with the harness approval/permission policy for stricter control.
+- **Evaluate gate is config, not approval** — enabling `allowEvaluate` trusts the model with arbitrary page JavaScript; compose it with the harness approval/permission policy for stricter control. The gate is enforced in **two** places: `tool.ts` refuses before a browser is even launched, and the session itself refuses too (`EVALUATE_DISABLED` / `CDP_DISABLED`), so a sibling plugin or a script holding the browser service cannot go around it. A gate that was never published counts as **off**. `browser_cdp` additionally passes the CDP allow-list at the session layer, so `Runtime.evaluate` is rejected even with the switch on.
 - **The package ships both power gates OFF, and that is deliberate** — `cordis.patch.yml` is part of the package, so anything it enables is enabled for *everyone who installs this*. It therefore sets `allowEvaluate: false` and `allowCdp: false` (the code defaults), and each deployment opts in through its **own profile patch** (`~/.dsh/profiles/<name>/cordis.patch.yml`). A package that shipped them on would be handing every installer a backdoor they never asked for. Snippet:
   ```yaml
   # dsh replaces an entry's config object wholesale — list every key you rely on.
@@ -434,7 +444,7 @@ links below go to GitHub rather than to files inside the package:
 - **`launch.viewport` only applies headless** — the visible window is a real window: it tracks the desktop size (`browser-lifecycle.ts` passes `viewport: null` in headful), so setting 1280×800 there changes nothing. Pin the size by running `headless: true`, or resize the window itself.
 - **Chromium family only** — Firefox/WebKit channels are not probed; providers are swappable if another engine is needed.
 - **Extract needs a dedicated model route** — it does not reuse the main request's route; misconfiguration fails loudly at call time.
-- **JS-driven navigations are not statically checkable** — `allowedDomains` covers `browser_navigate`, `browser_open_tab`, every navigating click (`browser_click`: `ref`, `text`, `precise` and raw-coordinate modes) and `browser_switch_tab`; `mode: "hover"` reveals content without activating anything, so it is not checked against the URL policy. A button whose handler runs `location.href = …` can still leave the allowed hosts, and so can a `<form>` whose `action` points at another host (pressing its submit button is a navigation this check does not statically see), and a tab that is already sitting on a disallowed host stays open (the agent simply refuses to drive it); deploy an external network guard for hard isolation.
+- **`allowedDomains` is enforced on the wire, not just at the entry points** — the host list is installed on the browser context itself (`navigation-guard.ts`), so a navigation nobody vetted is refused by the browser: `location.href = …`, `meta refresh`, a `<form>` posting to another host and a page-opened popup all stop at the request. Data requests (`fetch` / `xhr` / `EventSource`) to a host outside the list are refused too, so page script cannot move data off-site; rendering assets (script / image / CSS / font / media) are left alone, because blocking them only makes a page look broken. `browser_navigate`, `browser_open_tab`, every navigating click and `browser_switch_tab` still check first — that is what produces the friendly error before anything happens. One case needs a second look, because Chromium follows a redirect inside its own network stack where request interception never sees the hop: after every action the page's final URL is checked, and a landing outside the list is refused with `URL_NOT_ALLOWED` and the tab is reset to `about:blank`. Entry-point checks remain as the second layer for a tab that already existed on a disallowed host (a profile from an older version): the agent simply refuses to drive it. For hard isolation from the whole host stack, still deploy an external network guard.
 - **Stability waits are bounded by design** — a perpetually animating element falls back to a forced click on its current rect rather than stalling; a page that never settles is snapshotted after the cap. This is intentional: the agent must never hang.
 - **Challenge detection reads the responses it has actually seen** — the response-header tier applies to a document response this session observed after it attached to the tab. A tab that was already sitting on a challenge page when the session took it over falls through to the widget and wording tiers and, failing those, to the no-progress backstop: it reports a *possible* wall instead of guessing the vendor. A page that is not recognised still never goes silent: a non-2xx document carries an `[http NNN]` note, and a page with no clickable elements and almost no text carries a `[nothing here]` note.
 
@@ -444,7 +454,7 @@ The scenario suites originally surfaced four hazards, now fixed and regression-t
 
 - **Stale refs fail fast** — refs carry a per-snapshot nonce, so after a client-side re-render a stale ref matches nothing and `browser_click` fails with `REF_NOT_FOUND` instead of silently acting on a different element.
 - **Link clicks respect `allowedDomains`** — every click path is checked before any input is delivered: `browser_click` — ref mode (the element's `href`), `precise` ref mode, and raw-coordinate mode (the enclosing link found at the point). A disallowed host is rejected with `URL_NOT_ALLOWED`. `javascript:` links are exempt because they run in-page and navigate nowhere; other non-http(s) schemes stay refused.
-- **A page-opened tab outside `allowedDomains` cannot be driven** — a page can open a tab itself (`target="_blank"`, `window.open`) and the plugin never sees that navigation, so the policy is applied where it can be: `browser_switch_tab` refuses to enter such a tab (the current tab is kept, the tab itself stays open for the user).
+- **A page-opened tab outside `allowedDomains` cannot be driven** — two layers: the request-level guard refuses the popup's document (so it never loads the disallowed host), and `browser_switch_tab` still refuses to enter a tab that already sits on one (the current tab is kept).
 - **Idle disposal defers during operations** — a navigation slower than `idleTimeoutMs` completes normally; disposal only fires when the session is truly idle.
 - **Mid-navigation snapshots settle** — a `browser_snapshot` racing a JS navigation waits for the new document and retries instead of surfacing a raw "Execution context was destroyed" error.
 
@@ -496,3 +506,5 @@ MIT
 - **新增两只诊断工具**：`browser_console_messages`（控制台报错）与 `browser_network_requests`（网络请求），用于"点了没反应"时快速定位原因。
 - **接口与实现同步**：`BrowserSession` 补齐 9 个实现里已有的方法；`errors.ts` 补齐 12 个实际在用的错误码；`BrowserSnapshot` 补 `dialogNote` / `landingNote`；`TabInfo` 补 `active`；`runtime-state` / `cdp-policy` 新增类型声明。
 - **依赖范围修正**：`devDependencies` 与 `peerDependencies` 对齐，可在当前 DSH 版本下安装。
+
+**有问题直接去[讨论区](https://github.com/miqian-nomad/dsh-browser-playwright-codex/discussions)开个帖说，用得顺手也可以来吭一声——就我一个人维护，回得慢，但每条都看。**

package/SECURITY.md

@@ -11,6 +11,10 @@ this package ships switched off** — it is not registered at all until a deploy
 
 ---
 
+## 0. Window mode
+
+Headful is the default and the safety story depends on it: the window is visible, you can watch it and take over for sign-ins and CAPTCHAs. **Headless removes that**: the agent still parks native dialogs and reports challenge pages as notes, but nobody can act in a window that does not exist. Treat headless as an unattended mode, not as a quieter headful one.
+
 ## 1. What it can and cannot do
 
 **It drives your browser, as you.** The provider opens a visible, profile-backed Chromium-family
@@ -110,7 +114,7 @@ Two honest notes:
 npm test          # 219 tests: contracts, tool schemas, scenarios,
                   # aria engine, CDP policy, diff, click/tab allow-lists, snapshot rendering,
                   # prompt budget, docs-vs-reality consistency
-npm run verify    # 57 self-contained acceptance checks in a checkout (56 checks + 1 skipped
+npm run verify    # 60 self-contained acceptance checks in a checkout (59 checks + 1 skipped
                   # from an npm install, where there is no src/): no DSH, no network, local fixture server
 npm run doctor    # the host packages this plugin imports are still exporting what it uses
 npm run cost      # resident prompt cost of the registered tool surface

package/lib/browser-lifecycle.d.ts

@@ -4,9 +4,21 @@ import type { PlaywrightProvider } from './provider.ts';
  * profile-backed window is launched once and reused until closed by the
  * last owner, idle disposal, or an external close; login state lives in
  * the profile plus the exported state file, so reopening is seamless.
+ *
+ * Concurrent callers share ONE launch. Without this, two sessions waking up at
+ * the same moment both saw "no context" and both called launchPersistentContext
+ * on the same profile directory: the loser died on Chrome's profile singleton,
+ * the recovery path deleted the running browser's lock files, and the caller was
+ * told "install a Chromium-family browser" (measured 2026-10-26).
  */
 export declare function ensureContext(provider: PlaywrightProvider): Promise<import("playwright-core").BrowserContext>;
 /** Remove stale Chrome singleton lock files inside the profile directory. */
 export declare function clearChromeLocks(provider: PlaywrightProvider): Promise<void>;
-/** Launch the browser once, probing the configured or auto-detected channel. */
+/**
+ * Launch the browser once, probing the configured or auto-detected channel.
+ *
+ * Concurrent callers share one launch, for the same reason ensureContext does:
+ * otherwise two sessions wake up, both see `browser === undefined`, and two
+ * browsers are launched (the reported "两个任务同时唤醒会多开浏览器").
+ */
 export declare function ensureBrowser(provider: PlaywrightProvider): Promise<import("playwright-core").Browser>;

package/lib/browser-lifecycle.js

@@ -14,8 +14,26 @@ import { BrowserError, launchFailed } from "./errors.js";
  * profile-backed window is launched once and reused until closed by the
  * last owner, idle disposal, or an external close; login state lives in
  * the profile plus the exported state file, so reopening is seamless.
+ *
+ * Concurrent callers share ONE launch. Without this, two sessions waking up at
+ * the same moment both saw "no context" and both called launchPersistentContext
+ * on the same profile directory: the loser died on Chrome's profile singleton,
+ * the recovery path deleted the running browser's lock files, and the caller was
+ * told "install a Chromium-family browser" (measured 2026-10-26).
  */
 export async function ensureContext(provider) {
+    const inFlight = provider.contextLaunch;
+    if (inFlight !== undefined)
+        return await inFlight;
+    const launch = launchContext(provider).finally(() => {
+        if (provider.contextLaunch === launch)
+            provider.contextLaunch = undefined;
+    });
+    provider.contextLaunch = launch;
+    return await launch;
+}
+/** The actual launch, shared by every concurrent {@link ensureContext} caller. */
+async function launchContext(provider) {
     if (provider.context !== undefined) {
         try {
             const browser = provider.context.browser();
@@ -28,7 +46,8 @@ export async function ensureContext(provider) {
         provider.context = undefined;
     }
     fs.mkdirSync(provider.profileDir, { recursive: true });
-    const { executablePath, channel, headless } = provider.config.launch;
+    const { executablePath, channel } = provider.config.launch;
+    const headless = provider.desiredHeadless();
     const headful = !headless;
     const attempts = [];
     const baseOptions = {
@@ -56,14 +75,22 @@ export async function ensureContext(provider) {
     const start = async (extra) => {
         try {
             provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+            provider.launchedHeadless = headless;
         }
         catch (error) {
-            // A stale Chrome singleton lock from a dirty shutdown breaks a
-            // relaunch into the same profile; clear the lock files and
-            // retry once before surfacing the failure.
+            // Another launch may have won while this one was starting (an explicit
+            // `dispose()` racing a fresh acquire, a second provider on the same
+            // profile). Hand back that window: clearing the lock files it is running
+            // on would let a later launch start a SECOND browser on this profile.
+            if (provider.context !== undefined)
+                return provider.context;
+            // A stale Chrome singleton lock from a dirty shutdown breaks a relaunch
+            // into the same profile; clear the lock files and retry once before
+            // surfacing the failure.
             if (error instanceof Error && /user data directory|SingletonLock|ProcessSingleton/i.test(error.message)) {
                 await provider.clearChromeLocks();
                 provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+                provider.launchedHeadless = headless;
             }
             else {
                 throw error;
@@ -91,6 +118,9 @@ export async function ensureContext(provider) {
         catch {
             /* malformed state file must not block startup */
         }
+        // Allow-list on the wire: registered before the first navigation, so a
+        // page cannot leave the list by itself (navigation-guard.ts).
+        await provider.installHostGuard(ctx);
         await ctx.addInitScript(SNAPSHOT_SCRIPT);
         // The initial blank page predates addInitScript: reload so the
         // snapshot engine and restored localStorage apply on first use.
@@ -143,15 +173,35 @@ export async function clearChromeLocks(provider) {
         }
     }
 }
-/** Launch the browser once, probing the configured or auto-detected channel. */
+/**
+ * Launch the browser once, probing the configured or auto-detected channel.
+ *
+ * Concurrent callers share one launch, for the same reason ensureContext does:
+ * otherwise two sessions wake up, both see `browser === undefined`, and two
+ * browsers are launched (the reported "两个任务同时唤醒会多开浏览器").
+ */
 export async function ensureBrowser(provider) {
+    const inFlight = provider.browserLaunch;
+    if (inFlight !== undefined)
+        return await inFlight;
+    const launch = launchBrowser(provider).finally(() => {
+        if (provider.browserLaunch === launch)
+            provider.browserLaunch = undefined;
+    });
+    provider.browserLaunch = launch;
+    return await launch;
+}
+/** The actual launch, shared by every concurrent {@link ensureBrowser} caller. */
+async function launchBrowser(provider) {
     if (provider.browser !== undefined)
         return provider.browser;
-    const { executablePath, channel, headless } = provider.config.launch;
+    const { executablePath, channel } = provider.config.launch;
+    const headless = provider.desiredHeadless();
     const attempts = [];
     if (executablePath !== undefined) {
         try {
             provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            provider.launchedHeadless = headless;
             return provider.browser;
         }
         catch (error) {
@@ -164,6 +214,7 @@ export async function ensureBrowser(provider) {
         for (const candidate of channels) {
             try {
                 provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                provider.launchedHeadless = headless;
                 return provider.browser;
             }
             catch (error) {

package/lib/cache-clean.d.ts

@@ -0,0 +1,90 @@
+/** The four buckets the card can report and clean. */
+export type TargetId = 'browser-cache' | 'temp-residue' | 'updater-residue' | 'attachment-cache';
+/** Display order and labels for every target. */
+export declare const TARGETS: readonly {
+    id: TargetId;
+    label: string;
+}[];
+/** Is this value one of the enum ids? Unknown strings are rejected, never joined into a path. */
+export declare function isTargetId(value: unknown): value is TargetId;
+/** Absolute locations this module may inspect. */
+export interface CachePaths {
+    /** DSH home (`~/.dsh` unless DSH_HOME overrides it). */
+    dshHome: string;
+    /** Persistent Chromium profile directory of the browser capability. */
+    browserProfileDir: string;
+    /** OS temp directory. */
+    tmpDir: string;
+    /** Electron updater residue directory for the DSH desktop app. */
+    updaterDir: string;
+    /** Version currently installed — used to refuse other versions' installers. */
+    installedVersion: string;
+}
+/** Resolve the default paths from the environment (no path ever comes from the request). */
+export declare function resolvePaths(env: NodeJS.ProcessEnv | undefined, version: string, platform?: NodeJS.Platform): CachePaths;
+/** One row of the disk panel. */
+export interface DiskItem {
+    id: TargetId;
+    label: string;
+    bytes: number;
+    files: number;
+    /** Optional human note (e.g. "浏览器正在运行，整段跳过"). */
+    note?: string;
+}
+/** What `scan()` reports. */
+export interface ScanReport {
+    items: DiskItem[];
+    totalBytes: number;
+    attachments: {
+        objectsBytes: number;
+        requestImagesBytes: number;
+    };
+    skipped: {
+        id: TargetId;
+        reason: string;
+    }[];
+}
+/** One skipped entry inside a target. */
+export interface SkippedEntry {
+    path: string;
+    reason: 'in-use' | 'permission' | 'other-version' | 'unknown-version' | 'missing';
+}
+/** Per-target outcome of a clean pass. */
+export interface CleanTargetReport {
+    id: TargetId;
+    freedBytes: number;
+    skipped: SkippedEntry[];
+}
+/** What `clean()` reports. */
+export interface CleanReport {
+    dryRun: boolean;
+    freedBytes: number;
+    perTarget: CleanTargetReport[];
+}
+/** Options for one clean pass. */
+export interface CleanOptions extends CachePaths {
+    targets: readonly TargetId[];
+    dryRun: boolean;
+    /** True when the capability is enabled — reported, not used to skip silently. */
+    browserActive?: boolean;
+    /** Clock override for tests. */
+    now?: number;
+}
+/**
+ * Inspect every bucket without touching anything.
+ * @param paths - resolved locations
+ * @returns per-target sizes plus the attachment totals kept apart from the cache
+ */
+export declare function scan(paths: CachePaths): Promise<ScanReport>;
+/**
+ * Clean the requested buckets. With `dryRun` the same walk happens but nothing
+ * is renamed or removed, so the preview shows real numbers.
+ *
+ * @param options - resolved paths, enum targets and dry-run flag
+ * @returns per-target freed bytes and every skipped entry with a reason
+ */
+export declare function clean(options: CleanOptions): Promise<CleanReport>;
+/** Human-readable size for the card and the CLI. */
+export declare function formatBytes(bytes: number): string;
+/** Basename helper re-exported for the route's skipped-entry display. */
+export declare function displayName(path: string): string;