@te-river/opencode-team-mode 1.5.11 → 1.5.13

package/dist/tm/browser.js

@@ -1,56 +1,113 @@
 /**
  * tm_browser — governed interactive browser (Plan C: the user's own
- * Chromium-family browser driven headful over the CDP pipe protocol).
+ * Chromium-family browser, headful by default on desktops).
  *
- * Feasibility proven by smoke (Edge + --remote-debugging-pipe + JSON/NUL
- * framing over fds 3/4 — zero deps, no WebSocket implementation).  Qoder's
- * hardening ideas are ported where the plugin can reach them:
- *   - isolated temp user-data-dir (never the user's real profile);
- *   - per-navigation allowlist enforced at the NETWORK layer via CDP
- *     Fetch.requestPaused (non-allowlisted hosts get BlockedByClient —
- *     the per-hop re-check analog);
- *   - hardened webPreferences are the spawn's own flags (no-first-run,
- *     no-extensions, mute);
- *   - hard per-command timeout + explicit close; dispose kills the child.
+ * T5 engine split (design board ② "TM_BROWSER_ENGINE" + R2 verdict):
+ *   - PRIMARY engine: playwright-core — dynamic import ONLY (the package is
+ *     declared in dependencies but NOT installed at build time; a static
+ *     import would break tsc).  A failed import or node < 20 degrades the
+ *     session to the cdp-legacy engine automatically, per plugin instance.
+ *   - cdp-legacy engine: the original hand-rolled CDP pipe transport
+ *     (JSON + NUL framing over fds 3/4, zero deps — smoke-proven) kept
+ *     verbatim as the fallback.  On cdp-legacy only the core subset works
+ *     (open/navigate/read/screenshot/close + navigate_page/take_screenshot/
+ *     list_pages/evaluate_script aliases); the snapshot-first actions
+ *     (take_snapshot + uid addressing, 16-verb chrome-devtools-mcp surface)
+ *     require the playwright engine.
+ *
+ * Action surface aligns with chrome-devtools-mcp's 16 verbs (R2 mapping):
+ *   navigate_page · take_snapshot · click · fill · hover · drag ·
+ *   press_key · select_page · upload_file · wait_for · evaluate_script ·
+ *   list_console_messages · list_network_requests · list_pages ·
+ *   take_screenshot · handle_dialog
+ * plus the legacy compatibility verbs open / navigate / read /
+ * screenshot / close.  Snapshot-first discipline: take_snapshot returns
+ * the ariaSnapshot YAML with an INJECTED [uid=eN] per node (playwright has
+ * no uid concept — SnapshotIndex below is our own snapshot→locator
+ * registry); follow-up actions address nodes by that uid (or an explicit
+ * selector escape hatch) instead of guessed locators.
+ *
+ * Hardening (unchanged from the CDP era, ported to both engines):
+ *   - isolated temp profile (never the user's real browser profile);
+ *     persistent login is ONLY via an explicit TM_BROWSER_USER_DATA_DIR;
+ *   - domain allowlist enforced at the NETWORK layer on the NAVIGATION
+ *     (playwright context.route / CDP Fetch interception), re-checked on
+ *     every redirect hop; SUBRESOURCES then follow TM_BROWSER_SUBRESOURCE
+ *     (default same-site: passive types load, an executable resource loads
+ *     when it belongs to a site this session opened).  Gating every request
+ *     by the content allowlist is what made pages render picture-less — the
+ *     21 seeded hosts contain no CDN, so img/css/js died silently;
+ *   - out-of-allowlist open/navigate routes through the OFFICIAL dialog
+ *     BEFORE any spawn; approved hosts also pass the network layer;
+ *   - hardened context: real-Chrome UA + zh-CN Accept-Language,
+ *     no-first-run / no-extensions / mute launch flags, 3 s default action
+ *     timeout (the prompt's "3000 ms budget" is the tool's default, not an
+ *     aspiration), no networkidle waits anywhere;
+ *   - dispose AWAITS the close, and an idle session reaps itself
+ *     (TM_BROWSER_IDLE_MS) — an orphaned visible window is a user-facing bug.
  *
  * Environment adaptivity (different OpenCode hosts):
  *   - headful by default (Plan C); display-less Linux (no DISPLAY/
  *     WAYLAND_DISPLAY) automatically falls back to headless; TM_BROWSER_
  *     HEADLESS=1|0 forces either way;
- *   - browser discovery: TM_BROWSER_PATH override, then the USER'S DEFAULT
- *     browser (Windows registry / Linux xdg-settings) when it is
- *     Chromium-family — CDP's pipe protocol is Chromium-only, so Firefox as
- *     default falls through — then per-OS candidate paths (Edge first on
- *     Windows; Chrome/Chromium elsewhere).  No browser → structured error,
- *     the agent falls back to tm_webfetch / user MCP tools.
+ *   - browser discovery (SHARED by both engines): TM_BROWSER_PATH
+ *     override, then the USER'S DEFAULT browser (Windows registry / Linux
+ *     xdg-settings) when it is Chromium-family — CDP is Chromium-proprietary
+ *     and playwright channels only speak Chromium too, so a Firefox default
+ *     falls through — then per-OS candidate paths (Edge first on Windows;
+ *     Chrome/Chromium elsewhere).  No browser → structured error, the agent
+ *     falls back to tm_webfetch / user MCP tools.
  *
- * Role access mirrors tm_webfetch: network roles (team + researcher) only.
+ * Role access mirrors tm_webfetch: network roles (team + researcher) only,
+ * tester browser-only (UI verification).
  */
 import { execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { checkWebUrl } from "./webfetch.js";
+import { checkWebUrl, seedWebfetchDomains } from "./webfetch.js";
 import { askUserForTarget } from "./perm-ask.js";
+import { assertReadablePath } from "./guard.js";
+import { isEnvFilePath } from "../envprotect.js";
 import { tmError, toToolResult } from "./result.js";
+import { estimateTokens } from "./config.js";
 import { rmForceSafe } from "../fs-safe.js";
-/** Per-OS browser candidates, in preference order (first hit wins). */
+/** Per-OS browser candidates, in preference order (first hit wins).  ONLY a
+ *  fallback: on Windows the registry probe below is what actually honours the
+ *  user's chosen channel.  Edge/Chrome ship each channel in its OWN install
+ *  directory (`Microsoft\EdgeBeta`, `EdgeDev`, `EdgeCanary`), so the stable
+ *  path alone let a Beta-default host fall back to stable Edge (observed on
+ *  Windows 11, 2026-09-18). */
 const BROWSER_CANDIDATES = {
     win32: [
         "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
         "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge Beta\\Application\\msedge.exe",
+        "C:\\Program Files\\Microsoft\\Edge Beta\\Application\\msedge.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge Dev\\Application\\msedge.exe",
+        "C:\\Program Files\\Microsoft\\Edge Dev\\Application\\msedge.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge Canary\\Application\\msedge.exe",
+        "C:\\Program Files\\Microsoft\\Edge Canary\\Application\\msedge.exe",
         "%LOCALAPPDATA%\\Google\\Chrome\\Application\\chrome.exe",
         "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
         "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        "%LOCALAPPDATA%\\Google\\Chrome Beta\\Application\\chrome.exe",
+        "%LOCALAPPDATA%\\Google\\Chrome Dev\\Application\\chrome.exe",
+        "%LOCALAPPDATA%\\Google\\Chrome SxS\\Application\\chrome.exe",
     ],
     darwin: [
         "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
         "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Microsoft Edge Beta.app/Contents/MacOS/Microsoft Edge Beta",
+        "/Applications/Microsoft Edge Dev.app/Contents/MacOS/Microsoft Edge Dev",
+        "/Applications/Microsoft Edge Canary.app/Contents/MacOS/Microsoft Edge Canary",
         "/Applications/Chromium.app/Contents/MacOS/Chromium",
     ],
     linux: [
         "/usr/bin/google-chrome",
         "/usr/bin/google-chrome-stable",
+        "/usr/bin/google-chrome-beta",
+        "/usr/bin/google-chrome-unstable",
         "/usr/bin/chromium-browser",
         "/usr/bin/chromium",
         "/snap/bin/chromium",
@@ -68,7 +125,9 @@ export function parseProgId(stdout) {
     const m = /ProgId\s+REG_SZ\s+(\S+)/i.exec(String(stdout ?? ""));
     return m ? m[1] : null;
 }
-/** Parse `reg query "...\shell\open\command" /ve` output → exe path. */
+/** Parse `reg query "...\shell\open\command" /ve` output → exe path.
+ *  The quoted capture stops at the closing quote, so the `" -- %1"` style
+ *  URL-template tail never leaks into the returned path. */
 export function parseRegCommand(stdout) {
     const m = /REG_SZ\s+(?:"([^"]+)"|(\S+))/i.exec(String(stdout ?? ""));
     return m ? (m[1] ?? m[2]) : null;
@@ -78,24 +137,84 @@ export function parseDesktopExec(text) {
     const m = /^Exec\s*=\s*(?:"([^"]+)"|(\S+))/m.exec(String(text ?? ""));
     return m ? (m[1] ?? m[2]) : null;
 }
+/** Registry roots that can carry a ProgId's `shell\open\command`.  Edge is
+ *  installed machine-wide (HKLM\SOFTWARE\Classes) while a per-user Chrome
+ *  install registers HKCU\Software\Classes — probing HKCU only is what made
+ *  a Beta-default host come back empty and fall through to the stable
+ *  candidate path. */
+const REG_CLASSES_ROOTS = ["HKCU\\Software\\Classes", "HKLM\\SOFTWARE\\Classes"];
+/** Both URL schemes the shell association is recorded under.  A user can
+ *  set the two differently, so `http` alone is not "the default browser". */
+const REG_URL_SCHEMES = ["http", "https"];
+/** Channel install dirs keyed off the ProgId name (`MSEdgeBetaHTM`,
+ *  `ChromeHTML`, …) — the last-resort probe when the launch command itself is
+ *  unreadable but the ProgId still names the channel.  NOTE the real Windows
+ *  Edge dirs carry a SPACE ("Microsoft\Edge Beta"), which is what an
+ *  `EdgeBeta` guess silently misses; and Chrome installs per-user under
+ *  %LOCALAPPDATA% with a different exe name. */
+const CHANNEL_INSTALL_BY_PROGID = [
+    [/edgebeta/i, "C:\\Program Files (x86)\\Microsoft\\Edge Beta\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge Beta\\Application\\msedge.exe"],
+    [/edgedev/i, "C:\\Program Files (x86)\\Microsoft\\Edge Dev\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge Dev\\Application\\msedge.exe"],
+    [/edgecanary|edgeappcanary/i, "C:\\Program Files (x86)\\Microsoft\\Edge Canary\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge Canary\\Application\\msedge.exe"],
+    [/msedge|edgehtm/i, "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe"],
+    [/chromebeta/i, "%LOCALAPPDATA%\\Google\\Chrome Beta\\Application\\chrome.exe", "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe"],
+    [/chromedev|chromejsx/i, "%LOCALAPPDATA%\\Google\\Chrome Dev\\Application\\chrome.exe", "C:\\Program Files\\Google\\Chrome Dev\\Application\\chrome.exe"],
+    [/chromehtml|chromechtml/i, "%LOCALAPPDATA%\\Google\\Chrome\\Application\\chrome.exe", "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"],
+];
+/** Resolve a ProgId to its executable via every classes root.  `reg query`
+ *  exits non-zero (throws) for a missing key, so each probe is wrapped. */
+function progIdToExecutable(progId, run) {
+    for (const root of REG_CLASSES_ROOTS) {
+        try {
+            const exe = parseRegCommand(run("reg", ["query", `${root}\\${progId}\\shell\\open\\command`, "/ve"]));
+            if (exe)
+                return exe;
+        }
+        catch {
+            /* next root */
+        }
+    }
+    return null;
+}
 /** The user's DEFAULT browser, when it is Chromium-family and present.
  *  null → the caller falls back to the per-OS probe list (detection is
  *  best-effort and must never throw into tool discovery). */
 export function defaultBrowserExecutable(env = process.env, run = defaultRunner) {
     try {
         if (process.platform === "win32") {
-            const choice = run("reg", [
-                "query",
-                "HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\http\\UserChoice",
-                "/v",
-                "ProgId",
-            ]);
-            const progId = parseProgId(choice);
-            if (!progId)
-                return null;
-            const cmd = run("reg", ["query", `HKCU\\Software\\Classes\\${progId}\\shell\\open\\command`, "/ve"]);
-            const exe = parseRegCommand(cmd);
-            return exe && isChromiumFamily(exe) && fs.existsSync(exe) ? exe : null;
+            const accept = (exe) => exe && isChromiumFamily(exe) && fs.existsSync(exe) ? exe : null;
+            for (const scheme of REG_URL_SCHEMES) {
+                let progId = null;
+                try {
+                    progId = parseProgId(run("reg", [
+                        "query",
+                        `HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\${scheme}\\UserChoice`,
+                        "/v",
+                        "ProgId",
+                    ]));
+                }
+                catch {
+                    progId = null;
+                }
+                if (!progId)
+                    continue;
+                const direct = accept(progIdToExecutable(progId, run));
+                if (direct)
+                    return direct;
+                // launch command unreadable (or points at a Firefox shim) — the
+                // ProgId itself still names the channel, so probe that channel's
+                // standard install dir before giving up on the user's default.
+                for (const [re, ...cands] of CHANNEL_INSTALL_BY_PROGID) {
+                    if (!re.test(progId))
+                        continue;
+                    for (const cand of cands) {
+                        const hit = accept(cand.replace(/%LOCALAPPDATA%/gi, String(env.LOCALAPPDATA ?? "").trim()));
+                        if (hit)
+                            return hit;
+                    }
+                }
+            }
+            return null;
         }
         if (process.platform === "linux") {
             const desk = run("xdg-settings", ["get", "default-web-browser"]).trim();
@@ -122,6 +241,23 @@ export function defaultBrowserExecutable(env = process.env, run = defaultRunner)
     }
     return null;
 }
+/** Playwright's `channel` launch IGNORES the executable we discovered —
+ *  `channel:"msedge"` resolves whatever playwright thinks the stable Edge is,
+ *  so a correct Edge-Beta discovery still opened stable (the decisive half of
+ *  the 2026-09-18 report).  The channel spelling is therefore only correct
+ *  for the exact stable-channel install dir; everything else (Beta/Dev/
+ *  Canary, portable, an explicit TM_BROWSER_PATH) rides on executablePath. */
+export function playwrightLaunchTarget(executable, opts = {}) {
+    const exe = String(executable ?? "");
+    const p = exe.replace(/\//g, "\\").toLowerCase();
+    if (!opts.explicitOverride) {
+        if (/\\microsoft\\edge\\application\\msedge\.exe$/.test(p))
+            return { executablePath: exe, channel: "msedge" };
+        if (/\\google\\chrome\\application\\chrome\.exe$/.test(p))
+            return { executablePath: exe, channel: "chrome" };
+    }
+    return { executablePath: exe };
+}
 /** Resolve the browser executable: TM_BROWSER_PATH override → the user's
  *  DEFAULT browser (Chromium-family only) → per-OS candidate paths.
  *  %LOCALAPPDATA% style vars are expanded on win32. */
@@ -165,13 +301,90 @@ export function resolveHeadless(env = process.env) {
         return !env.DISPLAY && !env.WAYLAND_DISPLAY;
     return false;
 }
+// ---------- subresource gate (the "pages render without images" fix) --------
+/** A resource the page cannot execute code with — it can only paint. */
+const PASSIVE_RESOURCE_TYPES = new Set(["image", "media", "font", "stylesheet"]);
+/** Public suffixes that make the last TWO labels insufficient for a site
+ *  comparison.  Deliberately a small spelled-out list (no PSL dependency):
+ *  an unlisted multi-label suffix yields a LONGER site key, which auto-passes
+ *  FEWER hosts — the conservative direction for a network gate. */
+const TWO_LABEL_SUFFIXES = new Set([
+    "com.cn", "net.cn", "org.cn", "gov.cn", "edu.cn", "ac.cn", "co.cn", "com.hk", "org.hk", "co.jp", "ne.jp",
+    "co.kr", "co.uk", "org.uk", "ac.uk", "com.au", "net.au", "org.au", "co.in", "com.br", "com.mx", "com.tr",
+    "com.ua", "com.sg", "com.my", "com.tw", "co.za", "com.pl", "com.ru", "com.vn", "com.id", "com.ar", "com.co",
+]);
+/** Approximate registrable site (eTLD+1) of a hostname. */
+export function siteOf(host) {
+    const h = String(host ?? "").toLowerCase().replace(/\.$/, "");
+    if (!h || /^\d{1,3}(?:\.\d{1,3}){3}$/.test(h))
+        return h;
+    const labels = h.split(".").filter(Boolean);
+    if (labels.length <= 2)
+        return labels.join(".");
+    const lastTwo = labels.slice(-2).join(".");
+    if (TWO_LABEL_SUFFIXES.has(lastTwo))
+        return labels.slice(-3).join(".");
+    return lastTwo;
+}
+/** playwright and CDP spell resource types differently (`Image` vs `image`,
+ *  `Stylesheet` vs `stylesheet`) — one normalizer keeps both engines on the
+ *  same verdict table. */
+export function normalizeResourceType(raw) {
+    const t = String(raw ?? "").trim().toLowerCase();
+    return t === "" ? "other" : t;
+}
+export function isPassiveResource(raw) {
+    return PASSIVE_RESOURCE_TYPES.has(normalizeResourceType(raw));
+}
+/**
+ * One subresource verdict, shared VERBATIM by both engines so playwright and
+ * cdp-legacy can never drift.  `allowedSites` holds the registrable sites of
+ * every host this session actually navigated to (allowlist hit or dialog
+ * approval), which is what makes a page's own JS/CSS work without opening
+ * the whole internet: the governance boundary moves from "21 content domains"
+ * to "the site you approved", and an off-site SCRIPT still needs a dialog.
+ */
+export function subresourcePass(opts) {
+    if (opts.allowlistHit)
+        return { pass: true, via: "allowlist" };
+    if (opts.approvedHost)
+        return { pass: true, via: "approved" };
+    if (opts.policy === "off")
+        return { pass: false, via: "blocked" };
+    let host;
+    try {
+        host = new URL(opts.url).hostname;
+    }
+    catch {
+        return { pass: false, via: "blocked" };
+    }
+    const type = normalizeResourceType(opts.resourceType);
+    if (PASSIVE_RESOURCE_TYPES.has(type))
+        return { pass: true, via: `passive:${type}` };
+    if (opts.policy === "passive")
+        return { pass: false, via: `blocked:${type}` };
+    return opts.allowedSites.has(siteOf(host)) ? { pass: true, via: `same-site:${type}` } : { pass: false, via: `blocked:${type}` };
+}
+/** A navigation (or a host the dialog approved) widens the subresource
+ *  footprint to its own site.  Called for EVERY top-level/document request
+ *  that passed the allowlist side. */
+export function rememberSite(allowedSites, url) {
+    try {
+        const host = new URL(url).hostname;
+        if (host)
+            allowedSites.add(siteOf(host));
+    }
+    catch {
+        /* unparseable — nothing to remember */
+    }
+}
 class PipeCdp {
     child;
     nextId = 1;
     pending = new Map();
     buf = Buffer.alloc(0);
     events = [];
-    onEvent = (handler) => this.eventHandler = handler;
+    onEvent = (handler) => (this.eventHandler = handler);
     eventHandler = () => { };
     constructor(child) {
         this.child = child;
@@ -230,28 +443,374 @@ class PipeCdp {
         }
     }
 }
+/** playwright-core 1.63 targets node >= 20; on anything older we refuse the
+ *  engine up-front and stay on the zero-dependency CDP pipe (the node>=18
+ *  package floor keeps the plugin itself loadable — only the playwright
+ *  PRIMARY is gated here, cdp-legacy carries node 18/19 hosts). */
+export const PLAYWRIGHT_MIN_NODE_MAJOR = 20;
+/** "v22.3.1" / "20" -> major number; unparseable -> 0 (fail toward the
+ *  always-available cdp-legacy engine). */
+export function nodeMajorOf(version) {
+    const m = /^v?(\d+)/.exec(String(version ?? "").trim());
+    return m ? Number(m[1]) : 0;
+}
+/** The REAL loader — a VARIABLE specifier so tsc never tries to resolve
+ *  "playwright-core" at build time (types ship inside the package, which may
+ *  be absent from node_modules).  Under ESM, import(variable) yields the
+ *  module namespace typed as any. */
+export async function defaultImportPlaywright() {
+    const specifier = "playwright-core";
+    return await import(specifier);
+}
+/** Pure engine-selection seam (exported for test-browser.mjs):
+ *  cdp-legacy preference → legacy WITHOUT ever importing; node < 20 →
+ *  legacy without importing; playwright preference → import, verify the
+ *  chromium.launch shape, degrade to legacy on ANY failure. */
+export async function selectBrowserEngine(opts) {
+    const preference = opts.preference === "cdp-legacy" ? "cdp-legacy" : "playwright";
+    if (preference === "cdp-legacy") {
+        return { kind: "cdp-legacy", reason: "TM_BROWSER_ENGINE=cdp-legacy 偏好" };
+    }
+    if (opts.nodeMajor < PLAYWRIGHT_MIN_NODE_MAJOR) {
+        return {
+            kind: "cdp-legacy",
+            reason: `node ${opts.nodeMajor || "?"} < ${PLAYWRIGHT_MIN_NODE_MAJOR} — playwright-core 不受支持，自动降级 cdp-legacy`,
+        };
+    }
+    try {
+        const mod = (await opts.importPlaywright());
+        if (!mod || typeof mod.chromium?.launch !== "function") {
+            throw new Error("playwright-core 模块形状异常（缺 chromium.launch）");
+        }
+        return { kind: "playwright", pw: mod };
+    }
+    catch (e) {
+        return {
+            kind: "cdp-legacy",
+            reason: `playwright-core 加载失败：${e?.message ?? String(e)} — 自动降级 cdp-legacy（快照类动作不可用）`,
+        };
+    }
+}
+/** ariaSnapshot yields plain YAML with NO addressable id, while the
+ *  chrome-devtools-mcp muscle memory this tool aligns to is uid-addressed.
+ *  The missing layer is built here: each take_snapshot re-indexes every YAML
+ *  node (`- <role> "<name>" …`), injects `[uid=eN]` inline, and remembers
+ *  (role, name, nth-of-kind); later actions resolve uid →
+ *  `page.getByRole(role, { name, exact: true }).nth(nth)`.  Uids are
+ *  renumbered on every snapshot (one action, one observation); an
+ *  unknown/stale uid errors back to take_snapshot instead of falling back
+ *  to guessed locators. */
+export class SnapshotIndex {
+    entries = new Map();
+    next = 0;
+    get size() {
+        return this.entries.size;
+    }
+    /** Reset + parse + annotate the ariaSnapshot YAML in one pass. */
+    annotate(yaml) {
+        this.entries.clear();
+        this.next = 0;
+        const counters = new Map();
+        const out = [];
+        for (const line of String(yaml ?? "").split(/\r?\n/)) {
+            // `- role`, `- role "name"`, `- role:`, `- role "name" [attrs]` …
+            // the `text` pseudo-role carries no interactive semantics: skip it.
+            const m = /^(\s*-\s+)([A-Za-z][\w-]*)((?:"[^"]*"|.)*?)$/.exec(line);
+            if (!m || m[2] === "text") {
+                out.push(line);
+                continue;
+            }
+            const role = m[2];
+            const rest = m[3];
+            const uid = `e${++this.next}`;
+            const rawName = /"((?:[^"\\]|\\.)*)"/.exec(rest)?.[1];
+            const name = rawName === undefined ? undefined : unescapeAriaName(rawName);
+            const key = `${role}\u0000${name ?? ""}`;
+            const nth = counters.get(key) ?? 0;
+            counters.set(key, nth + 1);
+            this.entries.set(uid, { role, name, nth });
+            // container lines (`- list:`) get the uid BEFORE the colon so the
+            // YAML `key:` child-anchor semantics stay intact; names may contain
+            // colons, hence the startsWith check instead of a split.
+            out.push(rest.startsWith(":") ? `${m[1]}${role} [uid=${uid}]${rest}` : `${line} [uid=${uid}]`);
+        }
+        return out.join("\n");
+    }
+    get(uid) {
+        return this.entries.get(String(uid ?? "").trim());
+    }
+    /** uid → playwright locator; null = unknown uid / role the engine cannot
+     *  address (the caller renders the take_snapshot-first guidance). */
+    locatorFor(page, uid) {
+        const entry = this.get(uid);
+        if (!entry)
+            return null;
+        try {
+            const base = entry.name !== undefined ? page.getByRole(entry.role, { name: entry.name, exact: true }) : page.getByRole(entry.role);
+            return base.nth(entry.nth);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** ariaSnapshot escapes whitespace/quotes inside names (\s \n \t \" \\). */
+export function unescapeAriaName(raw) {
+    return String(raw).replace(/\\(.)/g, (_, c) => (c === "s" ? " " : c === "n" ? "\n" : c === "t" ? "\t" : c));
+}
+// ---------- action surface (R2: chrome-devtools-mcp 16-verb alignment) --------
+/** The 16 canonical verbs, named byte-identical to chrome-devtools-mcp. */
+export const BROWSER_PLAYWRIGHT_ACTIONS = [
+    "navigate_page",
+    "take_snapshot",
+    "click",
+    "fill",
+    "hover",
+    "drag",
+    "press_key",
+    "select_page",
+    "upload_file",
+    "wait_for",
+    "evaluate_script",
+    "list_console_messages",
+    "list_network_requests",
+    "list_pages",
+    "take_screenshot",
+    "handle_dialog",
+];
+/** Legacy compat verbs that ride on top of the 16 (both engines). */
+export const BROWSER_COMPAT_ACTIONS = ["open", "navigate", "read", "screenshot", "close"];
+/** What the cdp-legacy fallback can still do (R2: degradation must keep the
+ *  §6o behavior; everything snapshot-shaped is playwright-only). */
+export const BROWSER_LEGACY_ACTIONS = [
+    "open",
+    "navigate",
+    "navigate_page",
+    "read",
+    "screenshot",
+    "take_screenshot",
+    "list_pages",
+    "evaluate_script",
+    "close",
+];
+/** Default action/wait budget — the prompt's "3000 ms" discipline is the
+ *  ENGINE default, so agents that forget a timeout still fail fast. */
+const PW_DEFAULT_TIMEOUT_MS = 3000;
+const OBSERVE_BUFFER_CAP = 200;
+const HARDENED_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
 const SPAWN_TIMEOUT_MS = 15_000;
 const NAVIGATE_EVENT_TIMEOUT_MS = 15_000;
-// ---------- tool ----------------------------------------------------------------
 export function buildTmBrowserTool(deps) {
     const { pipelines } = deps;
     const env = deps.env ?? process.env;
+    const notify = typeof deps.notify === "function" ? deps.notify : undefined;
     const tool = "tm_browser";
     const traj = (e) => pipelines.store.appendTrajectory({ tool, ...e });
     let session = null;
-    const allowlist = deps.cfg.webfetchAllowedDomains
-        ?? ["*"];
+    // m2 (fix round): SAME seed policy as tm_webfetch / tm_search — the
+    // built-in default list gains the T4 engine home hosts (api.stackexchange
+    // .com, hn.algolia.com) so jump-reading a search hit stops re-popping the
+    // dialog; a narrowed TM_WEBFETCH_ALLOWED_DOMAINS is never widened.
+    const allowlist = seedWebfetchDomains(deps.cfg.webfetchAllowedDomains ?? ["*"]);
     // hosts approved through the OFFICIAL dialog this plugin lifetime — the
-    // CDP network-layer block consults this in addition to the static allowlist
+    // network layer (both engines) consults this in addition to the static allowlist
     const approvedHosts = new Set();
-    async function ensureSession(headless) {
-        if (session)
-            return session;
-        const executable = findBrowserExecutable(env);
-        if (!executable) {
-            throw new Error("本机未找到可用的浏览器（按 Edge/Chrome/Chromium 顺序探测失败）。" +
-                "设置 TM_BROWSER_PATH 指向浏览器可执行文件，或改用 tm_webfetch / 用户 MCP 工具。");
+    const snapshotBudget = Math.max(10, Number(deps.cfg?.browserSnapshotMaxTokens) || 1200);
+    const subPolicy = deps.cfg?.browserSubresource ?? "same-site";
+    const discover = deps.findExecutable ?? findBrowserExecutable;
+    const imageMaxBytes = Math.max(1000, Number(deps.cfg?.browserImageMaxBytes) || 400_000);
+    const idleCloseMs = Number(deps.cfg?.browserIdleCloseMs ?? 180_000);
+    // ---------- engine selection (cached per plugin instance) ----------
+    let selPromise = null;
+    let lastSel = null;
+    const preference = String(deps.cfg?.browserEngine ?? "playwright");
+    const selection = () => {
+        if (!selPromise) {
+            selPromise = selectBrowserEngine({
+                preference,
+                nodeMajor: deps.nodeMajor ?? nodeMajorOf(process.versions.node),
+                importPlaywright: deps.importPlaywright ?? defaultImportPlaywright,
+            }).then((sel) => {
+                lastSel = sel;
+                traj({ step_id: "browser", event: "engine", kind: sel.kind, reason: (sel.reason ?? "").slice(0, 200) });
+                return sel;
+            });
+        }
+        return selPromise;
+    };
+    /** Observe-payload cap shared by snapshot / console / network / eval. */
+    function capTokens(text, note) {
+        if (estimateTokens(text) <= snapshotBudget)
+            return text;
+        const lines = text.split("\n");
+        let acc = 0;
+        let i = 0;
+        for (; i < lines.length; i++) {
+            const cost = estimateTokens(lines[i]) + 1;
+            if (acc + cost > snapshotBudget)
+                break;
+            acc += cost;
+        }
+        return `${lines.slice(0, i).join("\n")}\n${note}`;
+    }
+    function saveShotPng(bytes, stepId) {
+        const png = Buffer.from(bytes);
+        const dir = path.join(pipelines.store.stepsRoot(), stepId);
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, "screenshot.png");
+        fs.writeFileSync(file, png);
+        traj({ step_id: stepId, event: "result", bytes: png.length });
+        return { file, png };
+    }
+    /** LLM args are booleans most of the time, but `"false"` / `"0"` strings
+     *  are common — a bare `Boolean()` read both as TRUE, which is exactly how
+     *  a model used to force tm_browser into headless (and get anti-bot
+     *  blocked) on a desktop that defaults to headful. */
+    function isTrueArg(raw) {
+        if (raw === true)
+            return true;
+        if (typeof raw === "number")
+            return raw === 1;
+        if (typeof raw === "string")
+            return /^(1|true|yes|on)$/i.test(raw.trim());
+        return false;
+    }
+    /** Screenshot line + the OPT-IN pixels.
+     *  The PNG always lands in the run store (it is the evidence artifact);
+     *  what rides back to the MODEL is a quality-70 JPEG — a real page with
+     *  images loaded is ~1.5 MB as PNG, which no token budget should ever
+     *  inline, and ~150-300 KB as JPEG.  Pixels stay opt-in so a UI sweep
+     *  cannot spend context the agent never asked for. */
+    async function shotOutput(sess, file, png, args, captureJpeg) {
+        const head = `截图已保存（PNG ${png.length} bytes）：${file}`;
+        if (!isTrueArg(args.image)) {
+            return `${head}\n（上下文只携带路径，不携带像素——需要真正看到画面时带 image:true 再截一次。）`;
+        }
+        let img = null;
+        if (captureJpeg) {
+            try {
+                img = await captureJpeg();
+            }
+            catch {
+                img = null;
+            }
+        }
+        let kind = "jpeg";
+        if (!img) {
+            img = png;
+            kind = "png";
+        }
+        if (img.length > imageMaxBytes) {
+            return `${head}\n（未附带像素：${kind.toUpperCase()} ${img.length} bytes 超过 TM_BROWSER_IMAGE_MAX_BYTES=${imageMaxBytes}。改用视口截图（去掉 fullPage）或提高该上限。）`;
+        }
+        sess.attachments.push({
+            type: "file",
+            mime: `image/${kind}`,
+            url: `data:image/${kind};base64,${img.toString("base64")}`,
+            filename: path.basename(file).replace(/\.png$/, `.${kind === "jpeg" ? "jpg" : "png"}`),
+        });
+        return `${head}\n（像素以 ${kind.toUpperCase()} ${img.length} bytes 随本条结果附带。）`;
+    }
+    /** One line telling the agent that the page is NOT actually empty — the
+     *  subresource gate dropped N requests.  Without this the model reads a
+     *  blank-looking page and reports "该网站没有图片". */
+    function blockedNote(sess) {
+        if (!sess.blocked.count)
+            return "";
+        const n = sess.blocked.count;
+        const hosts = [...sess.blocked.hosts];
+        // RESET IN PLACE — the engine's route handler holds this very object, so
+        // swapping in a new one would silently stop counting after the first
+        // drain (and the note would never appear again for the session).
+        sess.blocked.count = 0;
+        sess.blocked.hosts.clear();
+        traj({ step_id: "browser", event: "blocked", count: n, hosts: hosts.slice(0, 20).join(",") });
+        return (`\n注意：本页有 ${n} 个子资源请求被治理白名单拦截（${hosts.slice(0, 6).join(", ")}${hosts.length > 6 ? ` …+${hosts.length - 6}` : ""}）——不是站点没有内容。` +
+            `当前策略 TM_BROWSER_SUBRESOURCE=${subPolicy}；同域资源已自动放行，跨域脚本仍需白名单或弹窗批准。`);
+    }
+    function pageTextOutput(url, text) {
+        return `页面文本（${url}）：\n${text.slice(0, 20000)}${text.length > 20000 ? "\n…(截断)" : ""}`;
+    }
+    function discoveryError() {
+        return new Error("本机未找到可用的浏览器（按 Edge/Chrome/Chromium 顺序探测失败）。" +
+            "设置 TM_BROWSER_PATH 指向浏览器可执行文件，或改用 tm_webfetch / 用户 MCP 工具。");
+    }
+    /**
+     * M1 (upload_file exfil): the domain allowlist constrains the network
+     * DESTINATION but never the local SOURCE — an unguarded filePath could
+     * upload .env / key files to a whitelisted host's form. Reuses the read
+     * pipeline's P2 containment verbatim (workspace root + blackboard +
+     * trajectory; realpath-verified, fail-closed on unresolvable paths) and
+     * then applies the R6 env-file classifier, so *.env / shell-rc files are
+     * refused INSIDE the root too. The env refusal echoes no path (R6 privacy
+     * line); the scope verdict keeps the tm_read/tm_grep message shape.
+     */
+    function uploadExfilGuard(args, ctx) {
+        const raw = (args.filePath ?? args.files);
+        const files = (Array.isArray(raw) ? raw : [raw]).map((f) => String(f ?? "").trim()).filter(Boolean);
+        if (!files.length)
+            return null; // "缺少 filePath" stays act()'s own args error
+        const d = ctx?.directory;
+        const root = typeof d === "string" && d ? d : process.cwd();
+        const extra = [pipelines.store.blackboardRoot, pipelines.store.trajectoryRoot].filter((p) => typeof p === "string" && p.length > 0);
+        for (const f of files) {
+            if (isEnvFilePath(f))
+                return "拒绝上传（R6 红线：.env / shell rc 家族文件永不离开本机）";
+            const scope = assertReadablePath(root, f, extra);
+            if (!scope.ok)
+                return scope.message;
+        }
+        return null;
+    }
+    // ================= cdp-legacy engine (原手写 CDP 管道，保留不删) =============
+    /**
+     * Shared network verdict for BOTH engines — one implementation, so the
+     * playwright and cdp-legacy legs can never disagree about what passes.
+     * The hard red lines (non-http scheme, remote env-file spelling) stay hard
+     * under EVERY subresource policy: they are not consentable, so a passive
+     * image or a same-site script can never relax them.
+     */
+    function gateDecide(st, url, resourceType) {
+        const verdict = checkWebUrl(url, allowlist);
+        if (!verdict.ok && !verdict.askable)
+            return { pass: false, via: "red-line" };
+        let approved = false;
+        try {
+            approved = approvedHosts.has(new URL(url).hostname);
+        }
+        catch {
+            approved = false;
+        }
+        const v = subresourcePass({
+            url,
+            resourceType,
+            policy: subPolicy,
+            allowlistHit: verdict.ok,
+            approvedHost: approved,
+            allowedSites: st.allowedSites,
+        });
+        if (v.pass) {
+            if (normalizeResourceType(resourceType) === "document")
+                rememberSite(st.allowedSites, url);
+        }
+        else {
+            st.blocked.count++;
+            try {
+                st.blocked.hosts.add(new URL(url).hostname);
+            }
+            catch {
+                /* no host to name */
+            }
         }
+        // NO per-request trajectory: a real page is hundreds of requests and the
+        // log would be pure noise.  Blocked verdicts aggregate into st.blocked
+        // and flush as ONE line (blockedNote / close).
+        return v;
+    }
+    async function openLegacySession(headless) {
+        const executable = discover(env);
+        if (!executable)
+            throw discoveryError();
         const profileDir = fs.mkdtempSync(path.join(os.tmpdir(), "tm-browser-"));
         const child = spawn(executable, [
             headless ? "--headless=new" : "--start-maximized",
@@ -259,7 +818,7 @@ export function buildTmBrowserTool(deps) {
             `--user-data-dir=${profileDir}`,
             // real-Chrome UA even under --headless=new (which some sites detect
             // via the "HeadlessChrome" token otherwise) + zh-CN Accept-Language
-            "--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+            `--user-agent=${HARDENED_UA}`,
             "--accept-lang=zh-CN,zh;q=0.9,en;q=0.8",
             "--no-first-run", "--no-default-browser-check", "--disable-extensions",
             "--disable-background-networking", "--mute-audio",
@@ -286,36 +845,115 @@ export function buildTmBrowserTool(deps) {
         const page = targets.targetInfos.find((t) => t.type === "page");
         if (!page)
             throw new Error("浏览器启动后未找到 page target");
-        const { sessionId } = await cdp.call("Target.attachToTarget", { targetId: page.targetId, flatten: true });
+        const { sessionId } = (await cdp.call("Target.attachToTarget", { targetId: page.targetId, flatten: true }));
         await cdp.call("Page.enable", {}, sessionId);
-        // network-layer allowlist enforcement (Qoder's per-hop re-check analog)
+        // network-layer enforcement — the SAME gateDecide the playwright leg uses
+        // (subresource policy + per-hop redirect re-check + dialog-approved hosts)
+        const allowedSites = new Set();
+        const blocked = { count: 0, hosts: new Set() };
         await cdp.call("Fetch.enable", { patterns: [{ urlPattern: "*" }] }, sessionId);
         cdp.onEvent((m) => {
             if (m.method !== "Fetch.requestPaused" || m.sessionId !== sessionId)
                 return;
             const requestId = String(m.params.requestId ?? "");
-            const url = String(m.params.request?.url ?? "");
-            const verdict = checkWebUrl(url, allowlist);
-            let pass = verdict.ok;
-            if (!pass) {
-                // an approved-via-dialog host passes the network layer too
-                try {
-                    pass = approvedHosts.has(new URL(url).hostname);
-                }
-                catch {
-                    pass = false;
-                }
-            }
+            const p = m.params.request ?? {};
+            const url = String(p.url ?? "");
+            const { pass } = gateDecide({ allowedSites, blocked }, url, p.resourceType);
             if (pass) {
                 void cdp.call("Fetch.continueRequest", { requestId }, sessionId, 5000).catch(() => { });
             }
             else {
-                traj({ step_id: "browser", event: "blocked", url: url.slice(0, 200) });
                 void cdp.call("Fetch.failRequest", { requestId, errorReason: "BlockedByClient" }, sessionId, 5000).catch(() => { });
             }
         });
-        child.on("exit", () => {
-            session = null;
+        const sess = {
+            kind: "cdp-legacy",
+            currentUrl: "about:blank",
+            headless,
+            label: `cdp-legacy · ${path.basename(executable)} · pid ${child.pid ?? "?"}`,
+            attachments: [],
+            blocked,
+            allowedSites,
+            async act(action, args, stepId) {
+                if (action === "navigate" || action === "navigate_page") {
+                    const url = String(args.url ?? "").trim();
+                    rememberSite(allowedSites, url);
+                    await cdp.call("Page.navigate", { url }, sessionId);
+                    await cdp.waitEvent("Page.loadEventFired", sessionId, NAVIGATE_EVENT_TIMEOUT_MS).catch(() => { });
+                    sess.currentUrl = url;
+                    return `已导航：${url}${blockedNote(sess)}`;
+                }
+                if (action === "read") {
+                    traj({ step_id: stepId, event: "call", url: sess.currentUrl.slice(0, 200) });
+                    const ev = await cdp.call("Runtime.evaluate", { expression: "document.body ? document.body.innerText : ''", returnByValue: true }, sessionId);
+                    const text = String(ev.result?.value ?? "");
+                    traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
+                    return `${pageTextOutput(sess.currentUrl, text)}${blockedNote(sess)}`;
+                }
+                if (action === "screenshot" || action === "take_screenshot") {
+                    traj({ step_id: stepId, event: "call", kind: "screenshot", url: sess.currentUrl.slice(0, 200) });
+                    const shot = await cdp.call("Page.captureScreenshot", { format: "png" }, sessionId);
+                    const png = Buffer.from(String(shot.data ?? ""), "base64");
+                    const { file } = saveShotPng(new Uint8Array(png), stepId);
+                    return shotOutput(sess, file, png, args, async () => {
+                        const j = await cdp.call("Page.captureScreenshot", { format: "jpeg", quality: 70 }, sessionId);
+                        return Buffer.from(String(j.data ?? ""), "base64");
+                    });
+                }
+                if (action === "list_pages") {
+                    const t = await cdp.call("Target.getTargets");
+                    const pages = t.targetInfos.filter((x) => x.type === "page");
+                    const lines = pages.map((p, i) => `${i}: ${String(p.url ?? "")} ${String(p.title ?? "")}`.trimEnd());
+                    return `标签页（${pages.length}）：\n${lines.join("\n") || "（无）"}`;
+                }
+                if (action === "evaluate_script") {
+                    const src = String(args.function ?? args.expression ?? "").trim();
+                    if (!src)
+                        throw new Error('缺少 expression/function 参数（evaluate_script 需要一个 JS 表达式）');
+                    traj({ step_id: stepId, event: "call", kind: "evaluate" });
+                    const ev = await cdp.call("Runtime.evaluate", { expression: src, returnByValue: true }, sessionId);
+                    const value = ev.result?.value;
+                    return capTokens(`执行结果：${JSON.stringify(value ?? null)}`, "…(结果超长已截断)");
+                }
+                throw new Error(`action "${action}" 需要 playwright 引擎（当前为 cdp-legacy 降级：playwright-core 未安装或 node<20）。` +
+                    `cdp-legacy 可用: ${BROWSER_LEGACY_ACTIONS.filter((a) => a !== "open" && a !== "close").join(" | ")}`);
+            },
+            async close() {
+                child.off?.("exit", onExit);
+                await cdp.call("Browser.close", {}, undefined, 3000).catch(() => { });
+                if (child.exitCode === null) {
+                    child.kill();
+                }
+                // wait briefly for the process to release the profile (Windows file
+                // locks linger while the browser is still shutting down)
+                await new Promise((res) => {
+                    if (child.exitCode !== null)
+                        return res();
+                    const t = setTimeout(res, 3000);
+                    child.once("exit", () => {
+                        clearTimeout(t);
+                        res();
+                    });
+                });
+                const dead = child.exitCode !== null;
+                try {
+                    rmForceSafe(profileDir, { recursive: true });
+                }
+                catch {
+                    /* a locked leftover temp dir is reclaimed by the OS — never fail close */
+                }
+                return dead
+                    ? { closed: true, text: "浏览器进程已退出（cdp-legacy），临时配置目录已清理。" }
+                    : {
+                        closed: false,
+                        text: `警告：cdp-legacy 子进程 pid ${child.pid ?? "?"} 未在 3s 内退出，窗口可能仍在前台——` +
+                            `请手动关闭该浏览器窗口（临时目录 ${profileDir}）。`,
+                    };
+            },
+        };
+        const onExit = () => {
+            if (session === sess)
+                session = null;
             // best-effort: the profile may still be file-locked during shutdown —
             // a leftover temp dir is reclaimed by the OS, never an error for the task
             try {
@@ -324,38 +962,422 @@ export function buildTmBrowserTool(deps) {
             catch {
                 /* ignore */
             }
-        });
-        session = { child, cdp, sessionId, profileDir, currentUrl: "about:blank" };
-        return session;
+        };
+        child.on("exit", onExit);
+        return sess;
     }
-    async function closeSession() {
-        if (!session)
-            return "没有打开的浏览器会话。";
-        const { child, cdp, profileDir } = session;
-        session = null;
-        await cdp.call("Browser.close", {}, undefined, 3000).catch(() => { });
-        if (child.exitCode === null) {
-            child.kill();
+    // ================= playwright engine (primary) ==============================
+    async function openPlaywrightSession(pw, headless) {
+        const executable = discover(env);
+        if (!executable)
+            throw discoveryError();
+        const launchArgs = [
+            "--no-first-run", "--no-default-browser-check", "--disable-extensions",
+            "--disable-background-networking", "--mute-audio",
+            ...(headless ? [] : ["--start-maximized"]),
+        ];
+        const contextOpts = {
+            userAgent: HARDENED_UA,
+            locale: "zh-CN",
+            extraHTTPHeaders: { "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8" },
+            // the 3000 ms observation budget is the engine default (see header)
+            timeout: PW_DEFAULT_TIMEOUT_MS,
+            // headful: honor --start-maximized (null viewport = the OS window size)
+            viewport: headless ? undefined : null,
+        };
+        const persistentDir = String(env.TM_BROWSER_USER_DATA_DIR ?? "").trim();
+        // R2 (revised 2026-09-18): playwright's `channel` resolves the executable
+        // ITSELF, which silently overrode our discovery (a Beta-default Windows
+        // host opened STABLE Edge).  executablePath is now the primary launch and
+        // the channel spelling only a fallback — the opposite of the old order.
+        const target = playwrightLaunchTarget(executable, {
+            explicitOverride: String(env.TM_BROWSER_PATH ?? "").trim() !== "",
+        });
+        let browser = null;
+        let context;
+        let via = "executablePath";
+        if (persistentDir) {
+            context = await pw.chromium.launchPersistentContext(persistentDir, {
+                ...contextOpts,
+                executablePath: target.executablePath,
+                headless,
+                args: launchArgs,
+            });
+            via = `persistent(executablePath)`;
+        }
+        else {
+            try {
+                browser = await pw.chromium.launch({ executablePath: target.executablePath, headless, args: launchArgs });
+                via = "executablePath";
+            }
+            catch (e1) {
+                if (!target.channel)
+                    throw e1;
+                browser = await pw.chromium.launch({ channel: target.channel, headless, args: launchArgs });
+                via = `channel(${target.channel})`;
+            }
+            context = await browser.newContext(contextOpts);
         }
-        // wait briefly for the process to release the profile (Windows file
-        // locks linger while the browser is still shutting down)
-        await new Promise((res) => {
-            if (child.exitCode !== null)
-                return res();
-            const t = setTimeout(res, 3000);
-            child.once("exit", () => {
-                clearTimeout(t);
-                res();
+        const snapIndex = new SnapshotIndex();
+        const state = {
+            page: context.pages()[0] ?? (await context.newPage()),
+            dialogs: [],
+            consoleBuf: [],
+            netBuf: [],
+            allowedSites: new Set(),
+            blocked: { count: 0, hosts: new Set() },
+        };
+        const attached = new WeakSet();
+        const attach = (p) => {
+            if (attached.has(p))
+                return; // select_page may bounce back to an already-hooked tab
+            attached.add(p);
+            p.on("console", (msg) => {
+                state.consoleBuf.push({ type: String(msg?.type?.() ?? "log"), text: String(msg?.text?.() ?? "") });
+                if (state.consoleBuf.length > OBSERVE_BUFFER_CAP)
+                    state.consoleBuf.shift();
             });
-        });
+            p.on("pageerror", (err) => {
+                state.consoleBuf.push({ type: "pageerror", text: String(err?.message ?? err) });
+                if (state.consoleBuf.length > OBSERVE_BUFFER_CAP)
+                    state.consoleBuf.shift();
+            });
+            p.on("request", (req) => {
+                state.netBuf.push({ method: req?.method?.() ?? "?", url: String(req?.url?.() ?? "").slice(0, 300) });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            p.on("response", (res) => {
+                state.netBuf.push({
+                    method: res?.request?.()?.method?.() ?? "?",
+                    url: String(res?.url?.() ?? "").slice(0, 300),
+                    status: Number(res?.status?.() ?? 0) || undefined,
+                });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            p.on("requestfailed", (req) => {
+                state.netBuf.push({ method: req?.method?.() ?? "?", url: String(req?.url?.() ?? "").slice(0, 300), failure: "requestfailed" });
+                if (state.netBuf.length > OBSERVE_BUFFER_CAP)
+                    state.netBuf.shift();
+            });
+            // dialogs are HELD for handle_dialog (registering the handler opts us
+            // out of playwright's implicit auto-dismiss)
+            p.on("dialog", (d) => {
+                state.dialogs.push(d);
+                if (state.dialogs.length > 8)
+                    state.dialogs.shift();
+            });
+        };
+        attach(state.page);
+        // ---- network-layer allowlist: context.route() (CDP Fetch 的迁移面) ----
+        const routeHandler = async (route, request) => {
+            const u = String(request.url?.() ?? "");
+            // data:/blob:/about: never reach playwright's route anyway; keep the
+            // non-http hard-reject semantics identical to the CDP-era behavior
+            if (/^(about|data|blob):/i.test(u)) {
+                await route.continue().catch(() => { });
+                return;
+            }
+            const { pass } = gateDecide(state, u, request.resourceType?.());
+            if (pass) {
+                await route.continue().catch(() => { });
+            }
+            else {
+                // per-hop re-check lands here for every redirect hop too
+                state.netBuf.push({ method: request.method?.() ?? "?", url: u.slice(0, 300), blocked: true });
+                await route.abort().catch(() => { });
+            }
+        };
+        // M2 (fix round) fail-closed: the route gate is playwright's analog of
+        // the CDP leg's AWAITED Fetch.enable — if registration fails the session
+        // would browse with NO network whitelist. Close the context (persistent:
+        // the only handle; launched: plus the browser) and surface an execute
+        // error; a swallowed .catch(()=>{}) was a fail-open hole.
         try {
-            rmForceSafe(profileDir, { recursive: true });
+            await Promise.resolve(context.route("**/*", routeHandler));
         }
-        catch {
-            /* a locked leftover temp dir is reclaimed by the OS — never fail close */
+        catch (e) {
+            await Promise.resolve(context.close()).catch(() => { });
+            if (browser)
+                await Promise.resolve(browser.close()).catch(() => { });
+            traj({ step_id: "browser", event: "gate_register_failed", reason: String(e?.message ?? e).slice(0, 200) });
+            throw new Error(`网络白名单闸注册失败（context.route）——已 fail-closed 关闭浏览器会话，不会留下无白名单的窗口。` +
+                `原因：${String(e?.message ?? e)}`);
         }
-        return "浏览器会话已关闭，临时配置目录已清理。";
+        /** uid → locator with the snapshot-first guidance errors (R2: 禁猜
+         *  locator — only uid addressing or an explicit selector escape). */
+        const targetOf = (uidKey, selKey, args) => {
+            const uid = String(args[uidKey] ?? "").trim();
+            if (uid) {
+                const loc = snapIndex.locatorFor(state.page, uid);
+                if (!loc) {
+                    throw new Error(`uid "${uid}" 不在当前快照中（快照会重新编号）——先 action:"take_snapshot" 再用返回的 [uid=...] 寻址`);
+                }
+                return loc;
+            }
+            const sel = String(args[selKey] ?? "").trim();
+            if (sel)
+                return state.page.locator(sel);
+            throw new Error(`缺少 ${uidKey}/selector——tm_browser 快照优先：先 action:"take_snapshot"，动作只按快照里的 [uid=...] 寻址（或显式 selector 逃生舱），禁止猜 locator`);
+        };
+        /** Human-readable addressing echo for action results (no full locators
+         *  into context — uid tokens only). */
+        const describeTarget = (args, uidKey = "uid") => {
+            const uid = String(args[uidKey] ?? "").trim();
+            if (uid)
+                return `uid "${uid}"`;
+            const sel = String(args[uidKey === "uid" ? "selector" : "targetSelector"] ?? "").trim();
+            return sel ? `selector "${sel.slice(0, 60)}"` : "目标";
+        };
+        const sess = {
+            kind: "playwright",
+            currentUrl: "about:blank",
+            headless,
+            label: `playwright/${via} · ${path.basename(executable)} · ${headless ? "headless" : "headful"}`,
+            attachments: [],
+            blocked: state.blocked,
+            allowedSites: state.allowedSites,
+            async act(action, args, stepId) {
+                if (action === "navigate" || action === "navigate_page") {
+                    const url = String(args.url ?? "").trim();
+                    // the navigation itself already cleared the allowlist (execute()
+                    // asked the user otherwise) — its SITE may now load subresources
+                    rememberSite(state.allowedSites, url);
+                    // domcontentloaded ONLY — networkidle is banned (prompt discipline)
+                    await state.page.goto(url, { waitUntil: "domcontentloaded", timeout: 20_000 });
+                    sess.currentUrl = state.page.url?.() || url;
+                    rememberSite(state.allowedSites, sess.currentUrl);
+                    return `已导航：${url}${blockedNote(sess)}`;
+                }
+                if (action === "read") {
+                    traj({ step_id: stepId, event: "call", url: sess.currentUrl.slice(0, 200) });
+                    const text = String((await state.page.evaluate("document.body ? document.body.innerText : ''")) ?? "");
+                    traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
+                    return `${pageTextOutput(sess.currentUrl, text)}${blockedNote(sess)}`;
+                }
+                if (action === "screenshot" || action === "take_screenshot") {
+                    traj({ step_id: stepId, event: "call", kind: "screenshot", url: sess.currentUrl.slice(0, 200) });
+                    const bytes = await state.page.screenshot({ type: "png", fullPage: Boolean(args.fullPage) });
+                    const { file, png } = saveShotPng(bytes, stepId);
+                    return shotOutput(sess, file, png, args, async () => Buffer.from(await state.page.screenshot({ type: "jpeg", quality: 70, fullPage: Boolean(args.fullPage) })));
+                }
+                if (action === "take_snapshot") {
+                    traj({ step_id: stepId, event: "call", kind: "snapshot", url: sess.currentUrl.slice(0, 200) });
+                    let yaml;
+                    try {
+                        yaml = await state.page.locator("body").ariaSnapshot();
+                    }
+                    catch (e) {
+                        throw new Error(`ariaSnapshot 不可用：${e.message} —— locator.ariaSnapshot 需要 playwright-core ≥1.49（本包 optionalDependencies 锁 1.63）；未安装或过旧会走 cdp-legacy 降级，那边没有快照动作。`);
+                    }
+                    const annotated = snapIndex.annotate(yaml);
+                    traj({ step_id: stepId, event: "result", tokens: estimateTokens(annotated), nodes: snapIndex.size });
+                    const body = capTokens(annotated, `…(快照超过 browserSnapshotMaxTokens=${snapshotBudget}，后续行已截断——用 read 拿原文或先滚动再快照)`);
+                    const hint = state.dialogs.length ? `\n注意：有 ${state.dialogs.length} 个未处理对话框——先 handle_dialog` : "";
+                    return `ARIA 快照（${sess.currentUrl} · ${snapIndex.size} 个可寻址节点）——后续动作按行内 [uid=eN] 寻址：\n${body}${hint}${blockedNote(sess)}`;
+                }
+                if (action === "click") {
+                    const loc = targetOf("uid", "selector", args);
+                    await loc.click();
+                    return `已点击 ${describeTarget(args)}${state.dialogs.length ? "；有未处理对话框——handle_dialog（同轮观察，勿另起动作）" : ""}`;
+                }
+                if (action === "fill") {
+                    const loc = targetOf("uid", "selector", args);
+                    const text = String(args.text ?? "");
+                    await loc.fill(text);
+                    return `已填充 ${describeTarget(args)}（${text.length} 字符）`;
+                }
+                if (action === "hover") {
+                    const loc = targetOf("uid", "selector", args);
+                    await loc.hover();
+                    return `已悬停 ${describeTarget(args)}`;
+                }
+                if (action === "drag") {
+                    const from = targetOf("uid", "selector", args);
+                    const to = targetOf("targetUid", "targetSelector", args);
+                    await from.dragTo(to);
+                    return `已拖拽 ${describeTarget(args, "uid")} → ${describeTarget(args, "targetUid")}`;
+                }
+                if (action === "press_key") {
+                    const key = String(args.key ?? "").trim();
+                    if (!key)
+                        throw new Error('缺少 key 参数（如 "Enter"、"Control+A"）');
+                    await state.page.keyboard.press(key);
+                    return `已按键：${key}`;
+                }
+                if (action === "upload_file") {
+                    const loc = targetOf("uid", "selector", args);
+                    const raw = args.filePath ?? args.files;
+                    const files = (Array.isArray(raw) ? raw : [raw]).map((f) => String(f ?? "").trim()).filter(Boolean);
+                    if (!files.length)
+                        throw new Error("缺少 filePath 参数（文件或文件数组，本机路径）");
+                    for (const f of files) {
+                        if (!fs.existsSync(f))
+                            throw new Error(`上传文件不存在：${f.slice(0, 200)}`);
+                    }
+                    await loc.setInputFiles(files);
+                    return `已上传 ${files.length} 个文件到 ${describeTarget(args)}`;
+                }
+                if (action === "wait_for") {
+                    const uid = String(args.uid ?? "").trim();
+                    const text = String(args.text ?? "").trim();
+                    const timeout = Math.min(30_000, Math.max(100, Number(args.timeoutMs) || PW_DEFAULT_TIMEOUT_MS));
+                    const what = uid ? `uid "${uid}"` : text ? `文本 "${text.slice(0, 80)}"` : "";
+                    if (!uid && !text)
+                        throw new Error('wait_for 需要 text 或 uid');
+                    const loc = uid ? targetOf("uid", "selector", { uid }) : state.page.getByText(text);
+                    await loc.waitFor({ state: "visible", timeout });
+                    return `等待命中：${what}（≤${timeout}ms 内可见）`;
+                }
+                if (action === "evaluate_script") {
+                    const src = String(args.function ?? args.expression ?? "").trim();
+                    if (!src)
+                        throw new Error('缺少 expression/function 参数（JS 函数源或表达式）');
+                    traj({ step_id: stepId, event: "call", kind: "evaluate" });
+                    const value = await state.page.evaluate(src);
+                    return capTokens(`执行结果：${JSON.stringify(value ?? null)}`, "…(结果超长已截断)");
+                }
+                if (action === "list_pages") {
+                    const pages = context.pages();
+                    const lines = [];
+                    for (let i = 0; i < pages.length; i++) {
+                        const p = pages[i];
+                        const title = await Promise.resolve(p.title?.()).catch(() => "");
+                        lines.push(`${i}${p === state.page ? "（当前）" : ""}: ${String(p.url?.() ?? "")} ${String(title ?? "")}`.trimEnd());
+                    }
+                    return `标签页（${pages.length}）：\n${lines.join("\n") || "（无）"}\n用 select_page { index } 切换。`;
+                }
+                if (action === "select_page") {
+                    const idx = Number(args.index);
+                    const pages = context.pages();
+                    if (!Number.isInteger(idx) || idx < 0 || idx >= pages.length) {
+                        throw new Error(`index 越界（0..${pages.length - 1}）——先 list_pages`);
+                    }
+                    state.page = pages[idx];
+                    attach(state.page);
+                    await Promise.resolve(state.page.bringToFront?.()).catch(() => { });
+                    sess.currentUrl = String(state.page.url?.() ?? "");
+                    return `已切换到标签页 ${idx}：${sess.currentUrl}`;
+                }
+                if (action === "list_console_messages") {
+                    const lines = state.consoleBuf.map((m, i) => `${i + 1}. [${m.type}] ${m.text.slice(0, 300)}`);
+                    if (args.clear)
+                        state.consoleBuf.length = 0;
+                    return capTokens(`控制台消息（缓冲 ${lines.length}/${OBSERVE_BUFFER_CAP}）：\n${lines.join("\n") || "（无）"}`, "…(消息超长已截断)");
+                }
+                if (action === "list_network_requests") {
+                    const lines = state.netBuf.map((r, i) => `${i + 1}. ${r.method} ${r.url}${r.status !== undefined ? ` → ${r.status}` : ""}${r.blocked ? " [被白名单拦截]" : r.failure ? ` [${r.failure}]` : ""}`);
+                    return capTokens(`网络请求（缓冲 ${lines.length}/${OBSERVE_BUFFER_CAP}）：\n${lines.join("\n") || "（无）"}`, "…(列表超长已截断)");
+                }
+                if (action === "handle_dialog") {
+                    const d = state.dialogs.shift();
+                    if (!d)
+                        return "没有待处理的对话框（弹窗会在 click/submit 后出现——出现时 take_snapshot 的头部会提示，再 handle_dialog）。";
+                    const verdict = String(args.dialogAction ?? "accept").trim().toLowerCase();
+                    if (verdict === "dismiss") {
+                        await d.dismiss();
+                    }
+                    else {
+                        await d.accept(typeof args.promptText === "string" ? args.promptText : undefined);
+                    }
+                    return `已处理对话框（${d.type()}：「${d.message().slice(0, 120)}」→ ${verdict === "dismiss" ? "dismiss" : "accept"}）`;
+                }
+                throw new Error(`playwright 引擎未知 action "${action}"`);
+            },
+            async close() {
+                state.dialogs.length = 0;
+                const errs = [];
+                const fail = (label2) => (e) => {
+                    errs.push(`${label2}: ${String(e?.message ?? e)}`);
+                };
+                await Promise.resolve(context.close()).catch(fail("context"));
+                if (browser)
+                    await Promise.resolve(browser.close()).catch(fail("browser"));
+                // VERIFY before claiming — an agent quotes this line to the user as
+                // "浏览器已关闭", so a swallowed failure must not read like success.
+                let alivePages = 0;
+                try {
+                    alivePages = context.pages().length;
+                }
+                catch {
+                    alivePages = 0;
+                }
+                const connected = browser ? Boolean(browser.isConnected?.()) : false;
+                const closed = errs.length === 0 && alivePages === 0 && !connected;
+                const profile = persistentDir
+                    ? `持久配置目录已保留（下次 open 复用登录态）：${persistentDir}`
+                    : "临时配置目录由 playwright 自行回收";
+                if (closed)
+                    return { closed: true, text: `浏览器会话已确认关闭（${sess.label}）；${profile}。` };
+                return {
+                    closed: false,
+                    text: `警告：关闭未完全成功（${sess.label}${errs.length ? `：${errs.join("; ")}` : ""}）——` +
+                        `残留标签页 ${alivePages} 个${connected ? "，浏览器进程仍处于连接状态" : ""}。` +
+                        `窗口可能仍在前台，需要用户手动关闭。${profile}。`,
+                };
+            },
+        };
+        return sess;
+    }
+    // ---------- engine-neutral session lifecycle ----------
+    /** Idle reaper.  The pre-v1.5.13 layer had NO cleanup path other than the
+     *  agent remembering to call `close` — and an agent that believes it
+     *  closed the window (issue #3) leaves the user staring at a Chromium
+     *  window nobody owns.  An untouched session now closes itself and tells
+     *  the user it did. */
+    let idleTimer = null;
+    const armIdle = () => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = null;
+        if (!idleCloseMs || !session)
+            return;
+        idleTimer = setTimeout(() => {
+            idleTimer = null;
+            if (!session)
+                return;
+            traj({ step_id: "browser", event: "idle_close", idle_ms: idleCloseMs });
+            void closeActive()
+                .then((r) => notify?.(`tm_browser 空闲 ${Math.round(idleCloseMs / 1000)}s，会话已自动关闭${r.closed ? "（窗口应已消失）" : "——但窗口可能仍需手动关闭"}`))
+                .catch(() => { });
+        }, idleCloseMs);
+        idleTimer.unref?.();
+    };
+    async function ensureSession(headless) {
+        if (session)
+            return session;
+        const sel = await selection();
+        session =
+            sel.kind === "playwright" && sel.pw
+                ? await openPlaywrightSession(sel.pw, headless)
+                : await openLegacySession(headless);
+        return session;
     }
+    async function closeActive() {
+        const s = session;
+        if (!s)
+            return { text: "没有打开的浏览器会话。", closed: true };
+        session = null;
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+        return s.close();
+    }
+    /** Move any screenshot pixels act() produced out of the session and onto
+     *  the ToolResult.  Drained per call so a stale attachment can never ride
+     *  along on the next action. */
+    function withAttachments(res, sess) {
+        const atts = sess?.attachments ?? [];
+        if (sess)
+            sess.attachments = [];
+        if (!atts.length)
+            return res;
+        const base = typeof res === "string" ? { output: res } : res;
+        return { ...base, attachments: atts };
+    }
+    const ALL_ACTIONS = new Set([...BROWSER_PLAYWRIGHT_ACTIONS, ...BROWSER_COMPAT_ACTIONS, "navigate_page"]);
     const execute = async (rawArgs, ctx) => {
         try {
             const args = rawArgs ?? {};
@@ -363,8 +1385,10 @@ export function buildTmBrowserTool(deps) {
             const url = String(args.url ?? "").trim();
             // allowlist FIRST — an out-of-allowlist URL only proceeds after the
             // OFFICIAL dialog approves it (then the host passes the network layer
-            // too); hard red lines (scheme / env-file) reject with no dialog
-            if ((action === "open" || action === "navigate") && url) {
+            // too); hard red lines (scheme / env-file) reject with no dialog.
+            // NOTE: this gate runs BEFORE engine selection — a blocked target
+            // never touches playwright nor spawns anything (§6o invariant).
+            if ((action === "open" || action === "navigate" || action === "navigate_page") && url) {
                 const verdict = checkWebUrl(url, allowlist);
                 if (!verdict.ok) {
                     if (!verdict.askable || !verdict.url) {
@@ -386,81 +1410,114 @@ export function buildTmBrowserTool(deps) {
                 if (!url)
                     return toToolResult(tmError(tool, "args", "缺少 url 参数"));
                 if (session) {
-                    // already open: navigate instead of spawning a second browser
-                    return toToolResult(await navigateTo(url));
+                    // already open: navigate instead of spawning a second browser.
+                    // Report the mode the RUNNING instance is actually in — the old
+                    // code echoed the REQUESTED mode, so a sticky session could be
+                    // described as headful while it was a headless leftover.
+                    const out = await session.act("navigate", { url }, "browser");
+                    armIdle();
+                    return withAttachments(toToolResult(`复用已运行的会话（${session.headless ? "无头" : "有头窗口"} · ${session.label}）。${out}`), session);
                 }
-                const headless = args.headless != null ? Boolean(args.headless) : resolveHeadless(env);
+                // Mode is an OPERATOR decision (TM_BROWSER_HEADLESS), never a model
+                // arg: a model that once passed headless:"false" (string → truthy
+                // under Boolean()) pinned the whole process to headless and every
+                // anti-bot gate in the run failed.
+                const headless = resolveHeadless(env);
                 const s = await ensureSession(headless);
-                const out = await navigateTo(url);
-                traj({ step_id: "browser", event: "open", headless });
-                return toToolResult(`浏览器已启动（${headless ? "无头" : "有头窗口"}，隔离临时配置）。${out}`);
+                const out = await s.act("navigate", { url }, "browser");
+                traj({ step_id: "browser", event: "open", headless, label: s.label });
+                const mode = s.headless ? "无头" : "有头窗口";
+                const profile = String(env.TM_BROWSER_USER_DATA_DIR ?? "").trim() ? "持久登录配置" : "隔离临时配置";
+                const note = lastSel && preference !== "cdp-legacy" && lastSel.kind === "cdp-legacy"
+                    ? `\n（引擎：cdp-legacy 降级——${lastSel.reason ?? ""}；完整 16 动作需 npm install playwright-core + node≥20）`
+                    : "";
+                const guard = subPolicy === "off"
+                    ? `\n（子资源策略=off：跨域图片/脚本一律拦截，页面可能显示不全——TM_BROWSER_SUBRESOURCE=same-site 可恢复）`
+                    : "";
+                armIdle();
+                return withAttachments(toToolResult(`浏览器已启动（${mode}，${profile} · ${s.label}）。${out}${note}${guard}`), s);
             }
-            if (action === "navigate") {
+            if (action === "navigate" || action === "navigate_page") {
                 if (!url)
                     return toToolResult(tmError(tool, "args", "缺少 url 参数"));
                 if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                return toToolResult(await navigateTo(url));
-            }
-            if (action === "read") {
-                if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                const stepId = pipelines.nextStepId();
-                traj({ step_id: stepId, event: "call", url: session.currentUrl.slice(0, 200) });
-                const ev = await session.cdp.call("Runtime.evaluate", { expression: "document.body ? document.body.innerText : ''", returnByValue: true }, session.sessionId);
-                const text = String(ev.result?.value ?? "");
-                traj({ step_id: stepId, event: "result", tokens: Math.ceil(text.length / 4) });
-                return toToolResult(`页面文本（${session.currentUrl}）：\n${text.slice(0, 20000)}${text.length > 20000 ? "\n…(截断)" : ""}`);
-            }
-            if (action === "screenshot") {
-                if (!session)
-                    return toToolResult(tmError(tool, "args", "没有打开的浏览器会话——先用 action:\"open\""));
-                const stepId = pipelines.nextStepId();
-                traj({ step_id: stepId, event: "call", kind: "screenshot", url: session.currentUrl.slice(0, 200) });
-                const shot = await session.cdp.call("Page.captureScreenshot", { format: "png" }, session.sessionId);
-                const data = String(shot.data ?? "");
-                const png = Buffer.from(data, "base64");
-                const dir = path.join(pipelines.store.stepsRoot(), stepId);
-                fs.mkdirSync(dir, { recursive: true });
-                const file = path.join(dir, "screenshot.png");
-                fs.writeFileSync(file, png);
-                traj({ step_id: stepId, event: "result", bytes: png.length });
-                return toToolResult(`截图已保存（${png.length} bytes）：${file}\n（PNG 已落 run store；上下文只携带路径，不携带像素。）`);
+                    return toToolResult(tmError(tool, "args", '没有打开的浏览器会话——先用 action:"open"'));
+                const out = await session.act(action, { url }, "browser");
+                armIdle();
+                return withAttachments(toToolResult(out), session);
             }
             if (action === "close") {
                 traj({ step_id: "browser", event: "close" });
-                return toToolResult(await closeSession());
+                const r = await closeActive();
+                return toToolResult(r.text);
             }
-            return toToolResult(tmError(tool, "args", `未知 action "${String(action).slice(0, 30)}"——可用: open | navigate | read | screenshot | close`));
+            if (!ALL_ACTIONS.has(action)) {
+                return toToolResult(tmError(tool, "args", `未知 action "${String(action).slice(0, 30)}"——可用: open | navigate | take_snapshot | click | fill | hover | drag | press_key | select_page | upload_file | wait_for | evaluate_script | list_console_messages | list_network_requests | list_pages | take_screenshot | handle_dialog | read | screenshot | close（快照优先：先 take_snapshot，按 [uid=…] 寻址）`));
+            }
+            if (!session)
+                return toToolResult(tmError(tool, "args", '没有打开的浏览器会话——先用 action:"open"'));
+            // M1: upload_file SOURCE containment runs at the execute layer — the
+            // engine act() has no host ctx. Out-of-P2 paths and R6 env files are
+            // refused before setInputFiles can move any bytes.
+            if (action === "upload_file") {
+                const refusal = uploadExfilGuard(args, ctx);
+                if (refusal) {
+                    traj({ step_id: "browser", event: "upload_refused", reason: refusal.slice(0, 200) });
+                    return toToolResult(tmError(tool, "permission", refusal));
+                }
+            }
+            const stepId = pipelines.nextStepId();
+            const out = await session.act(action, args, stepId);
+            armIdle();
+            return withAttachments(toToolResult(out), session);
         }
         catch (err) {
             const e = err;
             return toToolResult(tmError(tool, "execute", String(e?.message ?? err ?? "browser 操作失败")));
         }
     };
-    async function navigateTo(url) {
-        const s = session;
-        await s.cdp.call("Page.navigate", { url }, s.sessionId);
-        await s.cdp.waitEvent("Page.loadEventFired", s.sessionId, NAVIGATE_EVENT_TIMEOUT_MS).catch(() => { });
-        s.currentUrl = url;
-        return `已导航：${url}`;
-    }
-    const DESCRIPTION = `Interactive browser (governed, Plan C): drives the user's own Chromium-family browser HEADFUL via CDP pipe — a visible window opens on desktops; display-less Linux hosts automatically run headless (TM_BROWSER_HEADLESS=1|0 forces either way).  Actions:
-- open: { url } — launch (or reuse) the session and navigate.  Uses your DEFAULT browser (Chromium-family; TM_BROWSER_PATH overrides; falls back to Edge/Chrome probes when the default is Firefox — CDP is Chromium-only).  Isolated temp profile (never your real profile); per-request DOMAIN ALLOWLIST enforced at the network layer (seeded = tm_webfetch's hosts; extend via TM_WEBFETCH_ALLOWED_DOMAINS).
-- navigate: { url } · read: extract page text (threshold-governed like tm_read) · screenshot: save PNG into the run store, only the path enters context · close: kill + cleanup.
-- Fixed priority ladder: ① tm_* governed tools → ② user MCP/plugin tools → ③ reasoning (never fabricate).  If no browser is installed (TM_BROWSER_PATH override exists), a structured error tells you to fall back to tm_webfetch / MCP.
-- Network roles: team + researcher full grant, tester browser-only (UI verification).  Out-of-allowlist open/navigate routes through the OFFICIAL confirmation dialog (approved hosts pass the network layer for the session); env-file URLs and non-http(s) schemes hard-reject.`;
+    const DESCRIPTION = `Interactive browser (governed, Plan C): drives the user's own Chromium-family browser HEADFUL — playwright-core engine primary (npm install + node>=20; auto-degrades to the zero-dep CDP pipe when absent, snapshot actions then unavailable). Snapshot-first flow: open → take_snapshot → act by [uid] → observe again.
+- 16 actions (chrome-devtools-mcp aligned): navigate_page { url } · take_snapshot { } → ariaSnapshot YAML with injected [uid=eN] · click/fill{text}/hover { uid|selector } · drag { uid, targetUid } · press_key { key } · select_page { index } · upload_file { uid, filePath } (filePath must live INSIDE the workspace/blackboard scope — .env & shell-rc files are refused) · wait_for { text|uid, timeoutMs<=3000 default } · evaluate_script { function } · list_console_messages · list_network_requests · list_pages · take_screenshot { fullPage?, image? } → the PNG always lands in the run store (path in the reply); with image:true a quality-70 JPEG of the same view is attached to THIS result so a vision model can actually see it (opt-in: pixels cost context, so ask only when the screenshot is the evidence) · handle_dialog { dialogAction: accept|dismiss, promptText }.
+- Compat actions: open { url } — launch/reuse + navigate (TM_BROWSER_PATH override → DEFAULT browser, Chromium-family only; the registry ProgId decides the CHANNEL, so an Edge Beta default opens Edge Beta, not stable). Isolated temp profile by default; persistent login ONLY via TM_BROWSER_USER_DATA_DIR (the real profile is never touched). navigate / read (page text) / screenshot / close also work.
+- Lifecycle (the user SEES this window): headful by default — headless is an operator setting (TM_BROWSER_HEADLESS), not a parameter you can pass. An idle session closes itself (TM_BROWSER_IDLE_MS, default 180s) and the user is told. ALWAYS action:"close" when your browser work is done, and quote the tool's own close line — "已确认关闭" vs "警告：关闭未完全成功" — instead of asserting the window is gone.
+- Discipline (enforced by defaults): act ONLY on uids from the latest take_snapshot — no guessed locators; one action then one observation; fold dialogs into the same round (snapshot header warns while a dialog is held); 3000 ms action budget; networkidle is never waited on; screenshots are the visual-last-resort, not the primary read.
+- Network: the top-level navigation must clear the domain allowlist (seeded = tm_webfetch's hosts; out-of-allowlist open/navigate asks the user through the OFFICIAL confirmation dialog BEFORE any spawn). SUBRESOURCES then follow TM_BROWSER_SUBRESOURCE (default same-site): images/media/fonts/stylesheets load, a script/XHR loads when it belongs to a site this session actually opened, anything else is blocked and reported as a "N 个子资源被拦截" note on the next snapshot — that note means the gate trimmed the page, NOT that the site has no images. env-file URLs and non-http(s) schemes hard-reject under every policy.
+- Fixed priority ladder: ① tm_* governed tools → ② user MCP/plugin tools → ③ reasoning (never fabricate).  No browser installed → structured error, fall back to tm_webfetch / MCP.  Role grant: team + researcher full, tester browser-only (UI verification).`;
     return {
         description: DESCRIPTION,
         args: deps.args ?? {
-            action: { descriptor: "action: open|navigate|read|screenshot|close (required)" },
-            url: { descriptor: "url: string (open/navigate, allowlisted https)" },
-            headless: { descriptor: "headless: boolean (open, optional — default auto)" },
+            action: { descriptor: "action: take_snapshot|click|fill|navigate_page|... (16 playwright verbs + open/navigate/read/screenshot/close)" },
+            url: { descriptor: "url: string (open/navigate/navigate_page, allowlisted https)" },
+            image: { descriptor: "image: true (take_screenshot only — attach the PNG pixels to this result; default is path-only)" },
+            uid: { descriptor: "uid: snapshot [uid=eN] token (click/fill/hover/drag/upload_file/wait_for)" },
+            selector: { descriptor: "selector: CSS/text locator escape hatch (only when a snapshot cannot express the node)" },
+            targetUid: { descriptor: "targetUid: drag destination uid" },
+            targetSelector: { descriptor: "targetSelector: drag destination selector" },
+            text: { descriptor: "text: fill value / wait_for visible text" },
+            key: { descriptor: "key: press_key chord, e.g. Enter|Control+A" },
+            function: { descriptor: "function: JS function source for evaluate_script" },
+            filePath: { descriptor: "filePath: local file path(s) for upload_file" },
+            index: { descriptor: "index: select_page target from list_pages" },
+            timeoutMs: { descriptor: "timeoutMs: wait_for budget (default 3000)" },
+            fullPage: { descriptor: "fullPage: take_screenshot full page (default viewport only)" },
+            dialogAction: { descriptor: "dialogAction: accept|dismiss for handle_dialog (default accept)" },
+            promptText: { descriptor: "promptText: prompt-dialog reply for handle_dialog accept" },
+            clear: { descriptor: "clear: drain the console buffer after list_console_messages" },
         },
         execute,
-        dispose: () => {
-            void closeSession().catch(() => { });
+        dispose: async () => {
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+            // AWAITED: the host's dispose hook is Promise-returning, and tearing
+            // down while a close was still in flight left the window on screen.
+            await closeActive().catch(() => { });
         },
+        engineInfo: () => ({
+            kind: lastSel?.kind ?? null,
+            reason: lastSel?.reason ?? null,
+        }),
     };
 }
 //# sourceMappingURL=browser.js.map