dsh-browser-playwright-codex 0.6.5 → 0.7.0

package/SECURITY.md

@@ -6,7 +6,7 @@ the thing worth being careful about. This file answers the two questions a reade
 1. **What can it do to me?**
 2. **Why does dsh.so's scanner report a Critical finding?**
 
-If you only read one line: **the two findings are the implementation of `browser_evaluate`, a tool
+If you only read one line: **the Critical finding is the implementation of `browser_evaluate`, a tool
 this package ships switched off** — it is not registered at all until a deployment turns it on.
 
 ---
@@ -15,18 +15,21 @@ this package ships switched off** — it is not registered at all until a deploy
 
 **It drives your browser, as you.** The provider opens a visible, profile-backed Chromium-family
 window (`~/.dsh/browser-profiles/playwright` by default) and reuses the logins already in it. It does
-not have your passwords, and it never types them: when a login, a 2FA prompt or a captcha appears,
-the agent is supposed to stop and hand the page back to you.
-
+window (`~/.dsh/browser-profiles/playwright` by default) and reuses the logins already in it. It does
+not have your passwords, and `browser_fill` **refuses** credential fields (`type=password`,
+`autocomplete=current-password` / `new-password` / `one-time-code` / `cc-*`) — typing one is a
+mechanism-level no, not a promise. Challenge pages are detected and reported as a note; there is
+**no sign-in detector**, so a sign-in page is handled by the agent's discipline and you complete it in
+the visible window.
 **It is visible and interruptible.** The window lives on your desktop. You can watch every action,
 minimise it (the provider detects a minimised window and keeps working without raising it — see
-[FOCUS-STEALING.md](FOCUS-STEALING.md)), or close it: login state is exported first and restored on
+[FOCUS-STEALING.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/FOCUS-STEALING.md)), or close it: login state is exported first and restored on
 the next launch.
 
 **Native dialogs are never auto-accepted.** `alert` / `confirm` / `prompt` / `beforeunload` are
 parked as a pending state, reported to the model, and answered only by an explicit `browser_dialog`
 call — a click that raises `confirm()` returns the parked dialog instead of accepting it. See
-[DIALOG-POLICY.md](DIALOG-POLICY.md).
+[DIALOG-POLICY.md](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/DIALOG-POLICY.md).
 
 **Which hosts it may touch is policy, not goodwill.** `allowedDomains` is enforced on every path that
 can navigate: `browser_navigate`, `browser_open_tab`, every click variant (ref, text, geometric,
@@ -55,7 +58,8 @@ While a gate is off the tool is **not registered at all**, so it does not exist
 costs no prompt tokens. But this file travels inside the package, so if it enabled them, every
 installer would get a backdoor they never asked for; the opt-in belongs to the deployment, and it
 lives in that deployment's own patch layer (the bundled Settings card writes it, or edit your
-profile patch — see the configuration section of the [README](README.md)).
+profile patch — see the configuration section of the
+[README](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/README.md#configuration)).
 
 **No telemetry.** The plugin does not phone home and does not upload page content anywhere. The only
 outbound traffic is what the page itself requests — plus one exception you control: `browser_extract`
@@ -71,8 +75,10 @@ Nothing else.
 ## 2. What the scanner reports, and which gate contains it
 
 dsh.so runs `dsh-plugin-vet` over the whole repository. Their scan of **0.6.0 (2026-10-16)** reports
-**1 Critical, 3 Warning, 25 Info** across 80 files — and it is **right about the capability**. Here is
-each one, with the gate that decides whether it is reachable at all.
+**1 Critical, 3 Warning, 25 Info** across 80 files — and it is **right about the capability**. Below is what
+each reported item actually is, and what decides whether it is reachable. Not every item sits behind a
+capability gate: the login-state write happens whenever login persistence works, and the acceptance script's
+local server exists only while that script runs.
 
 > For the record: their v0.4.9 scan — before this plugin was split into responsibility-scoped modules —
 > reported 2 Critical, 5 Warning, 26 Info across 57 files. Counts move as the scanner and the code
@@ -85,6 +91,9 @@ each one, with the gate that decides whether it is reachable at all.
 | Warning | HTTP request to a bare IP (`scripts/dsh-browser-verify.mjs`) | The acceptance suite starts a **local** `http.server` on `127.0.0.1` with a fixture page, so `npm run verify` needs no DSH and no internet. | Only when you run that script. |
 | Info ×25 | `localStorage` reads, `process.env` reads, hardcoded `127.0.0.1`, dev-only probe scripts | Restoring login state; test hooks (`DSH_BROWSER_STATE_FILE`, `PLAYWRIGHT_DOWNLOAD_HOST`); and scripts under `scripts/analysis/` that the scanner itself marks *"Dev-only file — not executed at install/runtime"*. | — |
 
+The scanner counts the two `fs.writeFileSync` call sites (the login-state export and the small runtime-state
+file) as **two separate Warning findings**; they share one row above because they are one persistence path.
+
 Two honest notes:
 
 - These numbers **will not go to zero**, because `browser_evaluate` exists in the code whether or not
@@ -92,22 +101,23 @@ Two honest notes:
 - We did **not** try to hide the finding (moving the call, obfuscating it, or suppressing the rule).
   That would be deceiving the tool that is trying to protect users, and it would make this file a lie.
 - Module names, not line numbers: this file used to cite a line number in `src/playwright.ts`, which the
-  0.5.x split made meaningless (the code lives in `src/session.ts` now, and that file is a 55-line
-  entry point). File names survive refactors; line numbers do not.
+  0.5.x split made meaningless (the code lives in `src/session.ts` now, and its entry point
+  `src/playwright.ts` is 56 lines). File names survive refactors; line numbers do not.
 
 ## 3. How to check all of this yourself
 
 ```sh
-npm test          # 100+ unit, scenario and guard tests: contracts, tool schemas, scenarios,
+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: no DSH, no network, local fixture server
+npm run verify    # 57 self-contained acceptance checks in a checkout (56 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
 ```
 
 - CI runs the whole suite on **ubuntu-latest and windows-latest** for every push
-  ([workflow](.github/workflows/ci.yml)).
+  ([workflow](https://github.com/miqian-nomad/dsh-browser-playwright-codex/blob/main/.github/workflows/ci.yml)).
 - The gates really are off in the package:
   `git show v0.4.7:cordis.patch.yml` (0.4.7 is where that changed).
 - Sandbox evidence, produced by someone else: [dsh.so's L4/L5 records](https://www.dsh.so/zh/artifact/dsh-browser-playwright-codex/)

package/cordis.patch.yml

@@ -1,72 +1,80 @@
-# dsh-browser-playwright-codex bundle layer: the browser seam, the Playwright
-# provider, and the model-facing tool family. Applied as one insert over the
-# profile's entry list; rows are patchable by id like every other plugin.
+# dsh-browser-playwright-codex bundle layer — ONE row for the whole capability.
 #
-# The `name:` values are package specifiers resolved from the profile, so they
-# must track package.json#name — a rename that misses this file fails at load
-# with MODULE_NOT_FOUND (2026-09-30: the 0.4.0 rename to *-codex did exactly
-# that; verified `require.resolve('dsh-browser-playwright/service')` fails in
-# both profiles while the *-codex specifier resolves).
+# History worth keeping: this file used to insert three rows (`browser` service,
+# `browser-playwright` provider, `browser-tool` tools) because the capability has
+# three configurable concerns. `dsh-client-modules` rejects distinct active Loader
+# sources that resolve to one package name, so a Settings card (which needs a
+# client module) could not live in such a package — it shipped as a second plugin,
+# dsh-browser-toggle. 2026-10-19: one row, three nested config sections, one plugin.
+#
+# The `name:` value is a package specifier resolved from the profile, so it must
+# track package.json#name — a rename that misses this file fails at load with
+# MODULE_NOT_FOUND (the 0.4.0 rename to *-codex did exactly that).
 - insert:
     - id: browser
-      name: 'dsh-browser-playwright-codex/service'
-      config:
-        provider: playwright
-    - id: browser-playwright
-      name: 'dsh-browser-playwright-codex/playwright'
-      config:
-        launch:
-          # Visible profile-backed window (persistent mode): the agent drives a
-          # browser the user can watch and rescue. Set true for headless
-          # servers. profileDir defaults to ~/.dsh/browser-profiles/playwright.
-          headless: false
-          persistent: true
-          viewport:
-            width: 1280
-            height: 800
-          navigationTimeoutMs: 30000
-          ignoreHTTPSErrors: false
-        # Idle auto-close: ms of no agent activity before the window closes
-        # itself (login state is saved first, so it reopens logged-in). 0 =
-        # never auto-close; the window stays until the user closes it or DSH
-        # exits. User choice: never auto-close (2026-09-04).
-        idleTimeoutMs: 0
-        maxSessions: 8
-        # Response-size lever (off by default): return "+/-/~" ref diffs between
-        # snapshots instead of the whole tree. Smaller returns on pages that
-        # re-render often; the model then has to hold the previous tree itself.
-        snapshot:
-          diff: false
-    - id: browser-tool
-      name: 'dsh-browser-playwright-codex/tool'
+      name: 'dsh-browser-playwright-codex'
       config:
-        # This file ships INSIDE the package, so it must not turn anything on for
-        # the people who install it. It used to: an earlier revision carried the
-        # author's own `allowEvaluate: true` / `allowCdp: true` (2026-09-04) into
-        # every download, which is how a package ends up handing each installer a
-        # backdoor they never asked for — and it is what a third-party scanner
-        # reads as "dynamic code execution, critical".
-        #
-        # Both are OFF here (matching the code defaults in src/tool.ts, and the
-        # README's own configuration example). Opt in per deployment, in YOUR
-        # profile patch — never in the package:
-        #
-        #   # ~/.dsh/profiles/<name>/cordis.patch.yml
-        #   # NOTE: dsh replaces an entry's config object wholesale, so list every
-        #   # key you rely on, not just the one you are changing.
-        #   - id: browser-tool
-        #     config:
-        #       toolPrefix: 'browser_'
-        #       allowEvaluate: true    # registers browser_evaluate
-        #       allowCdp: true         # registers browser_cdp (needs a DSH restart)
-        #       registerDisabledTools: false
-        #       interactiveOnlyDefault: false   # true = snapshot returns actionable elements only
-        #       maxWaitMs: 60000
-        #
-        # browser_evaluate runs arbitrary page JavaScript: it can read anything in
-        # the page and act on the user's logged-in sites. browser_cdp is CDP with
-        # an allow-list — only inspection and input simulation pass
-        # (lib/cdp-policy.js); network/storage/cookie/security commands never do.
-        # Neither tool is registered at all while its gate is false.
-        allowEvaluate: false
-        allowCdp: false
+        # Browser seam: which registered provider to drive.
+        service:
+          provider: playwright
+        # Provider: window, launch, snapshot and session settings.
+        playwright:
+          launch:
+            # Visible profile-backed window (persistent mode): the agent drives a
+            # browser the user can watch and rescue. Set true for headless servers.
+            # profileDir defaults to ~/.dsh/browser-profiles/playwright.
+            headless: false
+            persistent: true
+            viewport:
+              width: 1280
+              height: 800
+            navigationTimeoutMs: 30000
+            ignoreHTTPSErrors: false
+          # Idle auto-close: ms of no agent activity before the window closes
+          # itself (login state is saved first, so it reopens logged-in). 0 =
+          # never auto-close. User choice: never auto-close (2026-09-04).
+          idleTimeoutMs: 0
+          maxSessions: 8
+          # Response-size lever (off by default): return "+/-/~" ref diffs between
+          # snapshots instead of the whole tree.
+          snapshot:
+            diff: false
+        # Model-facing tools: prefix, capability gates and wait caps.
+        tool:
+          # This file ships INSIDE the package, so it must not turn anything on for
+          # the people who install it. It used to: an earlier revision carried the
+          # author's own allowEvaluate/allowCdp true (2026-09-04) into every
+          # download — a backdoor each installer never asked for, and what a
+          # third-party scanner reads as "dynamic code execution, critical".
+          #
+          # Both are OFF here (matching the code defaults in src/tool.ts). Opt in
+          # per deployment, in YOUR profile or home patch — never in the package:
+          #
+          #   - id: browser
+          #     name: 'dsh-browser-playwright-codex'
+          #     config:
+          #       service: { provider: playwright }
+          #       playwright: { launch: { headless: false, persistent: true }, idleTimeoutMs: 0, maxSessions: 8, snapshot: { diff: false } }
+          #       tool:
+          #         toolPrefix: 'browser_'
+          #         allowEvaluate: true    # registers browser_evaluate
+          #         diagnostics: true      # registers browser_console_messages / browser_network_requests
+          #         allowCdp: true         # registers browser_cdp
+          #         registerDisabledTools: false
+          #         interactiveOnlyDefault: false   # true = snapshot returns actionable elements only
+          #         maxWaitMs: 60000
+          #
+          # The loader replaces an entry's config object WHOLESALE, so a partial
+          # block resets every key you leave out. List all three sections.
+          #
+          # browser_evaluate runs arbitrary page JavaScript: it can read anything
+          # in the page and act on the user's logged-in sites. browser_cdp is CDP
+          # with an allow-list — only inspection and input simulation pass
+          # (lib/cdp-policy.js); network/storage/cookie/security commands never do.
+          # Neither tool is registered at all while its gate is false.
+          allowEvaluate: false
+          allowCdp: false
+          # Diagnostics tools (console messages, network requests) are OFF here:
+          # they debug a failed run; their schemas would otherwise sit in the
+          # system prompt every turn. Turn them on per deployment.
+          diagnostics: false

package/lib/challenge-signatures.d.ts

@@ -47,6 +47,15 @@ export interface ChallengeSignature {
     readonly headers?: readonly HeaderRule[];
     /** Case-insensitive header-name prefixes (e.g. DataDome's `x-datadome*`). */
     readonly headerPrefixes?: readonly string[];
+    /**
+     * Status codes this signature must be corroborated by. Needed for vendors whose
+     * header is *not* challenge-specific: DataDome adds `x-datadome*` to every
+     * response (their docs say so, and they return `NA` when detection is off), and
+     * Imperva adds `x-iinfo` to everything it fronts. Measured 2026-10-17: a normal
+     * DataDome-fronted page answered 200 with `x-datadome: protected`, which an
+     * ungated rule would have reported as a wall.
+     */
+    readonly statuses?: readonly number[];
     /**
      * Accessible-name tokens only this vendor's widget carries. On a non-iframe
      * node a token must ALSO be corroborated by {@link WIDGET_CORROBORATION}.

package/lib/challenge-signatures.js

@@ -53,16 +53,19 @@ export const CHALLENGE_SIGNATURES = Object.freeze([
     {
         id: 'imperva-incapsula',
         engine: 'Imperva',
-        hint: 'Imperva (Incapsula) served this response from its edge, which is where its bot challenges live',
-        // Presence only: X-IInfo is an opaque per-response trace that Imperva adds
-        // to everything it fronts, so its value carries no comparable state.
+        hint: 'Imperva (Incapsula) blocked this request from its edge',
+        // Presence only: X-IInfo is an opaque per-response trace that Imperva adds to
+        // everything it fronts, so the header alone says nothing about a block — the
+        // status code has to agree.
         headers: [{ name: 'x-iinfo' }],
+        statuses: [403, 429, 503],
     },
     {
         id: 'datadome',
         engine: 'DataDome',
-        hint: 'DataDome attached its own metadata to this response',
+        hint: 'DataDome blocked this request',
         headerPrefixes: ['x-datadome'],
+        statuses: [403, 429, 503],
     },
     {
         id: 'recaptcha',

package/lib/challenge.d.ts

@@ -58,3 +58,23 @@ export declare function detectNoProgress(input: {
     readonly unchangedStreak: number;
     readonly refs: number;
 }): string | null;
+/**
+ * Appended when a page has nothing to click and almost nothing to read. This is
+ * the blind spot the no-progress backstop cannot cover: that tier needs an action
+ * to compare before and after, and on a page with zero actionable elements the
+ * agent has no action to take — so the emptiest, most wall-like pages used to
+ * produce no message at all. Measured 2026-10-17 on 微博's visitor gate: the model
+ * received 364 characters, all of them "URL / Title / Refs: 0 / (no visible
+ * elements)", and nothing said the page was a gate rather than an empty document.
+ */
+export declare const SILENT_PAGE_NOTE = "[nothing here] this page has no clickable elements and almost no text: it may be a gate or visitor check that resolves by itself, a page that is still loading, or a page that needs a person. Wait a moment and take one more browser_snapshot; if it still looks like this, tell the user what you were trying to open and ask them to look at the open window, instead of re-sending the same navigation.";
+/**
+ * Whether the page is a silent one: nothing to click and (almost) nothing to read.
+ * @param input - the action ref count and the accessible tree.
+ * @returns the advisory note, or null when the page has content worth reading.
+ */
+export declare function detectSilentPage(input: {
+    readonly refs: number;
+    readonly nodes?: readonly ChallengeNode[] | undefined;
+    readonly title?: string | undefined;
+}): string | null;

package/lib/challenge.js

@@ -1,10 +1,27 @@
-import { CAPTCHA_ROLES, CAPTCHA_WORD, CHALLENGE_SIGNATURES, WIDGET_CORROBORATION, WORDING_COMMAND, WORDING_EXCLUDE, WORDING_TITLE, } from "./challenge-signatures.js";
+import { CAPTCHA_ROLES, CAPTCHA_WORD, CHALLENGE_SIGNATURES, WORDING_COMMAND, WORDING_EXCLUDE, WORDING_TITLE, } from "./challenge-signatures.js";
 /** How many accessible names the wording tiers may look at. */
 const MAX_NAMES = 60;
-/** Cap on the joined text handed to the wording tiers. */
-const MAX_TEXT = 900;
+/**
+ * The widget tier reads deeper than the wording tiers. Measured 2026-10-17 on
+ * nopecha.com/demo/hcaptcha: a real hCaptcha iframe named
+ * "包含 hCaptcha 安全挑战复选框的小部件" sits below depth 2, so a three-level scan
+ * never saw it and the real widget was reported as NO MATCH. Vendor widgets are
+ * usually mounted inside a wrapper stack; control labels are not.
+ */
+const WIDGET_DEPTH = 8;
+/** Cap on names the widget tier walks (deeper scan, so a larger budget). */
+const MAX_WIDGET_NAMES = 150;
 /** A control label is short; a sentence that merely mentions captchas is not. */
 const MAX_CONTROL_LABEL = 32;
+/**
+ * A title that mentions verification only counts on a page with (almost) nothing
+ * to click. Measured on real pages 2026-10-17: 百度's actual 安全验证 page has
+ * **0** actionable elements, while a Baidu *search result* page titled
+ * "安全验证_百度搜索" has 57 and "滑块验证_百度搜索" has 81. Without this gate the
+ * title tier fires on any search for those words — which is exactly the query a
+ * person investigating captchas types.
+ */
+const TITLE_WORDING_MAX_REFS = 5;
 /** Cap on names folded into one page-state fingerprint. */
 const MAX_FINGERPRINT_NAMES = 200;
 /**
@@ -70,11 +87,25 @@ export function detectChallenge(snapshot) {
     const url = snapshot.url ?? '';
     const names = [];
     scan(snapshot.nodes, 0, 2, names, MAX_NAMES);
+    // The widget tier gets its own, deeper scan (see WIDGET_DEPTH).
+    const widgetNames = [];
+    scan(snapshot.nodes, 0, WIDGET_DEPTH, widgetNames, MAX_WIDGET_NAMES);
     const headers = snapshot.response?.headers;
+    const status = snapshot.response?.status;
+    const refs = snapshot.refs;
+    /**
+     * Some vendors put their header on every response, so the header alone is not a
+     * block: DataDome attaches `x-datadome*` to everything (their docs) and Imperva
+     * attaches `x-iinfo` to everything. A signature that lists `statuses` must have
+     * the status agree, or a perfectly good page is reported as a wall.
+     */
+    const statusAgrees = (required) => required === undefined || (status !== undefined && required.includes(status));
     // Tier 1 — the vendor's own response metadata. This is their published API:
     // Cloudflare documents cf-mitigated: challenge as the supported way to detect
     // a challenge page, so a rename breaks every customer integration, not just us.
     for (const signature of CHALLENGE_SIGNATURES) {
+        if (!statusAgrees(signature.statuses))
+            continue;
         for (const rule of signature.headers ?? []) {
             const evidence = headerEvidence(rule, headers);
             if (evidence !== null) {
@@ -98,18 +129,23 @@ export function detectChallenge(snapshot) {
         const tokens = signature.widgetTokens;
         if (tokens === undefined)
             continue;
-        for (const node of names) {
+        // No ref-count gate here on purpose. An earlier version required the page to be
+        // nearly unusable before a vendor iframe counted, which suppressed a genuine
+        // reCAPTCHA / hCaptcha / Turnstile simply because the login page around it had
+        // links (measured: a busy login page stopped being recognised at all). Login
+        // pages are the main case for this check, so the frame wins: a v3 badge on an
+        // ordinary page is reported as "a captcha is embedded here", which is true.
+        for (const node of widgetNames) {
+            // Frames only. The vendor's own widget is a frame in every real sample measured
+            // (reCAPTCHA, hCaptcha, Turnstile, Arkose): the deep scan exists to reach it.
+            // Accepting a token on an ordinary node was a regression — an article titled
+            // "How hCaptcha works" has h2/p nodes with the vendor word in them, and the
+            // wording elsewhere on the page ("verification", "challenge") then corroborated
+            // it, so a perfectly ordinary blog post rendered as a captcha wall.
+            if (node.role !== 'iframe' && node.role !== 'frame')
+                continue;
             if (!tokens.some((token) => token.test(node.name)))
                 continue;
-            const onFrame = node.role === 'iframe' || node.role === 'frame';
-            if (!onFrame) {
-                const others = [title, url, ...names.filter((other) => other !== node).map((other) => other.name)]
-                    .join(' | ')
-                    .slice(0, MAX_TEXT);
-                const corroborated = WIDGET_CORROBORATION.some((token) => token.test(others));
-                if (!corroborated)
-                    continue;
-            }
             return {
                 engine: signature.engine,
                 hint: signature.hint,
@@ -119,32 +155,41 @@ export function detectChallenge(snapshot) {
         }
     }
     // Tier 3 — wording, weakest of the three. A title is short and written by the
-    // interceptor, so it stands alone; on a node we require a command form (or a
-    // captcha control), which is the difference between a challenge and a help
-    // page about captchas.
+    // interceptor, so it stands almost alone: the one extra condition is that the
+    // page must also be unusable (see TITLE_WORDING_MAX_REFS). A caller that does
+    // not report a ref count is treated as "nothing to click", because the
+    // alternative is silently switching this tier off.
+    // Fail closed: a caller that does not report a ref count gets no title tier at all.
+    // Leaving the gate open when refs was missing is how the false positive came back
+    // (the tests themselves passed a BrowserSnapshot, which has totalRefs but no refs).
+    const unusablePage = refs !== undefined && refs <= TITLE_WORDING_MAX_REFS;
     const head = title + ' ' + url;
-    for (const signature of CHALLENGE_SIGNATURES) {
-        for (const pattern of signature.titleWording ?? []) {
+    if (unusablePage) {
+        for (const signature of CHALLENGE_SIGNATURES) {
+            for (const pattern of signature.titleWording ?? []) {
+                if (!pattern.test(head))
+                    continue;
+                return {
+                    engine: signature.engine,
+                    hint: signature.hint,
+                    tier: 'wording',
+                    evidence: 'title: ' + title.slice(0, 60),
+                };
+            }
+        }
+        for (const pattern of WORDING_TITLE) {
             if (!pattern.test(head))
                 continue;
             return {
-                engine: signature.engine,
-                hint: signature.hint,
+                engine: 'human-verification',
+                hint: 'the page is asking to verify a human visitor',
                 tier: 'wording',
                 evidence: 'title: ' + title.slice(0, 60),
             };
         }
     }
-    for (const pattern of WORDING_TITLE) {
-        if (!pattern.test(head))
-            continue;
-        return {
-            engine: 'human-verification',
-            hint: 'the page is asking to verify a human visitor',
-            tier: 'wording',
-            evidence: 'title: ' + title.slice(0, 60),
-        };
-    }
+    // Control-level wording is not gated the same way: it needs a short label on a
+    // control role, which an ordinary results page does not carry.
     for (const node of names) {
         if (node.name.length > MAX_CONTROL_LABEL)
             continue;
@@ -223,3 +268,34 @@ export function detectNoProgress(input) {
         return null;
     return NO_PROGRESS_NOTE;
 }
+/**
+ * Appended when a page has nothing to click and almost nothing to read. This is
+ * the blind spot the no-progress backstop cannot cover: that tier needs an action
+ * to compare before and after, and on a page with zero actionable elements the
+ * agent has no action to take — so the emptiest, most wall-like pages used to
+ * produce no message at all. Measured 2026-10-17 on 微博's visitor gate: the model
+ * received 364 characters, all of them "URL / Title / Refs: 0 / (no visible
+ * elements)", and nothing said the page was a gate rather than an empty document.
+ */
+export const SILENT_PAGE_NOTE = '[nothing here] this page has no clickable elements and almost no text: it may be a gate or visitor check that resolves by itself, a page that is still loading, or a page that needs a person. Wait a moment and take one more browser_snapshot; if it still looks like this, tell the user what you were trying to open and ask them to look at the open window, instead of re-sending the same navigation.';
+/** A page with no named node at all counts as "almost no text". Strict on purpose:
+ * one heading plus one paragraph is a normal page, not a silent one. */
+const SILENT_PAGE_MAX_NAMES = 0;
+/**
+ * Whether the page is a silent one: nothing to click and (almost) nothing to read.
+ * @param input - the action ref count and the accessible tree.
+ * @returns the advisory note, or null when the page has content worth reading.
+ */
+export function detectSilentPage(input) {
+    if (input.refs > 0)
+        return null;
+    // A page with no title at all is a bare document (about:blank, a raw image):
+    // calling that "maybe a gate" is noise, not a warning.
+    if (input.title !== undefined && input.title.trim() === '')
+        return null;
+    const names = [];
+    // Read as deep as the widget scan: a page whose only text sits six levels down is
+    // a normal page, and a depth-4 scan called it "almost no text" (review, P1-3).
+    scan(input.nodes, 0, WIDGET_DEPTH, names, SILENT_PAGE_MAX_NAMES + 1);
+    return names.length <= SILENT_PAGE_MAX_NAMES ? SILENT_PAGE_NOTE : null;
+}