dsh-browser-playwright-codex 0.6.0 → 0.6.5

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 Bilingual by intent: the version headings and the summary of each release are given in both
 languages, the individual entries follow the language the surrounding code and docs use.
 
+## 0.6.5 — 2026-10-16
+
+一句话摘要：**挑战页识别不再靠一份关键词表** —— 判定改成「厂商自有的机器信号优先，认不出来就问一句『页面变了吗』」，所以新出现的验证方式也能被接住；顺带清掉漏网的 4 处本机路径，并把 npm 包里 12 个用不上的开发脚本收成 2 个。
+
+### Changed
+
+- **挑战页识别重做成分层判定**（新增 `src/challenge-signatures.ts`，重写 `src/challenge.ts`）。原来只有一份中英混杂的词表，而且词表里**根本没有「验证码」「安全验证」「拖动滑块」这些中文说法** —— 也就是说 README 承诺的「遇到验证码会停下来」，在中文站点上大半不成立：百度系的「安全验证」、滑块页的「拖动滑块完成拼图」一个都识别不到，插件会当作普通页面继续点。现在按**稳定性**排序，而不是按覆盖率：
+  1. **主文档响应头** —— 厂商对外的公开 API：`cf-mitigated: challenge`（Cloudflare 官方文档就是教用户读这个头）、`x-amzn-waf-action: challenge`（AWS WAF）、`x-iinfo`（Imperva）、`x-datadome*`（DataDome）。为此在 `src/page-diagnostics.ts` 已有的 `page.on('response')` 里认出**主文档导航响应**，把 status 与头透传进快照（`BrowserSnapshot.response`）。只认**产生当前文档的那次响应**：单页应用改了 URL 却没有文档加载时，旧响应不再复用 —— 否则会在一个好好的页面上报出墙；退回低层是安全的失败方向。
+  2. **厂商控件自己的无障碍名** —— reCAPTCHA / hCaptcha / Turnstile / Arkose / PerimeterX 的 iframe 标题就是他们自己的产品名；非 iframe 节点上的同名 token 必须**另有**「请你验证」字样才算数，而且那份旁证语汇**排除了它自己**（`reCAPTCHA` 里就含 `captcha`，不排除的话这条守卫是空的 —— 第一版就是这样，被测试当场抓出来）。
+  3. **文案（最后手段）** —— 标题里的 `安全验证` / `Just a moment...`，或控件上的命令式文案（`请输入验证码`、`拖动滑块完成拼图`）；按「动词族」组合匹配而不是逐句枚举。**只有控件角色**（输入框 / 按钮 / 图片 / 滑块…）能凭「验证码」二字触发，`验证码说明` 这种帮助页链接不触发；`获取验证码` / `发送验证码` 这类正常登录控件也排除（另一个被测试抓出来的误判）。
+  4. **行为兜底（不认识任何厂商）** —— 动作之后 URL、标题、元素集合完全没变、且页面上几乎没有别的可点，就在这次结果里附一句「没有可见变化」，并**明说这是猜测**。这一层覆盖所有没有签名的厂商：新出现的验证方式靠它接住，代价只是多问用户一句，而不是拿账号去撞墙。
+- **`interactiveOnly` 不再把 iframe 剪掉**（`src/injected.ts` 与 `src/snapshot-aria.ts` 两个引擎都改）：iframe 的无障碍名就是内嵌控件自己的标题，是第 2 层唯一的证据。原来这个省 token 的开关一开，等于把验证码识别关掉 —— 一个**静默失效**。
+- **已经认出是拦截面时，不再叠那句兜底提示**：「这是墙、原因是什么」才是可执行的信息，再叠一句更含糊的警告只是多花 prompt。
+- **清掉仓库里漏网的 4 处本机绝对路径**（`README.md`、`PLUGIN-README.md`、`SNAPSHOT-RULES.md`、`scripts/autocommit.ps1`）。0.6.1 声称清干净了，实际漏了这四处；而它正是外部评审用来判断「这个项目离开作者的电脑就转不动」的证据。**这次改成脚本守**：`tests/doc-reality.test.ts` 新增守卫，扫全仓手写文本文件里「盘符 + 至少一段目录」的路径（已用探针验证：三条真实路径全部抓到，仓库里唯一命中是给读者的 `D:\path\to\…` 占位符，由白名单排除）。
+- **npm 包从 85 个文件收到 75 个**：`files` 里那一整个 `scripts/` 收成逐个文件的白名单，只留 `doctor.mjs` 与 `dsh-browser-verify.mjs`（这两个只依赖 `lib/` 与 harness，装到 npm 的用户**能直接跑**）。顺带修掉一处假承诺：README 原来说 `measure-prompt-cost.mjs` 也随包可跑，但它依赖 `src/` 与 `shipped-gates.mjs`，在装好的包里**从来跑不起来**。`scripts/preflight.mjs` 的 `SHOULD_SHIP` 现在钉住这两个脚本，防止以后再被顺手丢掉。
+- **新增上手一节「第一个任务」**（`README.md` / `PLUGIN-README.md` / `中文说明.md`）：三条可以直接复制的话 + 你会看到什么 + 第一天两个习惯（先看再点、不可逆的那步说停）。四家外部评审独立提到「装完不知道第一步干什么、文档过载」，而 `examples/` 目录一直不存在。
+
+### Added
+
+- `tests/challenge.test.ts`：**35 条**用例，正例与**必须不触发**的反例各占一半 —— 讲 reCAPTCHA 的文章、`验证码说明` 帮助链接、`获取验证码` 按钮、只是提到「请输入验证码」的长段落、普通搜索页、只有「安全」二字的标题。另有一条守卫：旁证语汇不得被任何厂商自己的名字满足。
+- `tests/scenarios.test.ts`：**4 条真浏览器端到端**。①真实 `cf-mitigated: challenge` 响应头一路走到渲染结果（钉住「监听 → 快照 → 判定 → 模型读到的文字」这条链，单测盖不住）；②一个**完全没有任何签名**的拦截面（标题「请稍等」、一个点不动的按钮）由第 4 层兜底抓住，测试**先断言 `detectChallenge` 返回 null**，证明它不是靠签名抓到的；③`interactiveOnly` 下 iframe 名字仍在；④单页应用改 URL 后旧响应头不复用。
+- `tests/snapshot-aria.test.ts`：`interactiveOnly` 保留 iframe 的用例。
+- `tests/doc-reality.test.ts`：本机路径守卫（见上）。
+
+### Fixed
+
+- **`PlaywrightSession.blockedSnapshot` 从未声明返回类型**，于是 `navigate()` 的推断返回类型变成一个联合类型，新加的字段在类型上根本不存在。类型检查抓出来的，不是运行期 —— 这正是把 `typecheck` 扩到 `tests/` 的价值。
+- **兜底指纹原来只读两层**：深层文字变化会被误判成「页面没变」，于是在一个正常页面上报出「没有可见变化」的假警告。现在读到 4 层。
+
+## 0.6.1 — 2026-10-16
+### Changed
+
+- **清掉仓库里的本机绝对路径**：`DIALOG-POLICY.md` 里那条 `D:\dsh-plugins\…` 与 `codex-rules.md` 里那条 `C:\Users\…\.codex\…` 换成通用说法；`ci.yml` 里写死的验收计数（"(52 checks)"，实际 57 项）改成由脚本自己打印，从此不会再漂移。三处都是外部模型评审当场读出来的。
+- **SECURITY.md 的扫描数字更新为 2026-10-16 对 0.6.0 的实测**：dsh.so 的 `dsh-plugin-vet` 扫出
+  **1 Critical / 3 Warning / 25 Info**（80 个文件），此前记的是 v0.5.3 的 1 / 3 / 22（75 个文件）。
+  Critical 与 Warning 的**条目**没变（Critical 仍是 `browser_evaluate` 的 `new Function`），只有 Info 随代码增长增加。
+  （旧数字来自我们的上一次扫描；新数字来自 dsh.so 的独立扫描，用于核对。）
+
 ## 0.6.0 — 2026-10-16
 一句话摘要：**`browser_fill` 现在也接受 `value` 这个参数名**（模型按语义猜也能一次成功），缺值时给的是指路错误，而不是"缺少属性 text"。
 

package/README.md

@@ -25,7 +25,11 @@ dsh plugin --profile <name> add github:miqian-nomad/dsh-browser-playwright-codex
   keeps working while it is minimised ([FOCUS-STEALING.md](FOCUS-STEALING.md)).
 - **遇事停下来叫人** — `alert` / `confirm` / `prompt` are parked and reported, answered only by an
   explicit `browser_dialog` call; a login, 2FA or captcha is handed back to you
-  ([DIALOG-POLICY.md](DIALOG-POLICY.md)).
+  ([DIALOG-POLICY.md](DIALOG-POLICY.md)). A challenge page is recognised from the interceptor's own
+  response headers first (`cf-mitigated: challenge` and friends), then from its widget, and only then
+  from wording; if none of those match, a page that stops changing after an action is reported as a
+  possible wall instead of being retried
+  ([docs/articles/dialogs-and-captcha.md](docs/articles/dialogs-and-captcha.md)).
 - **ref 失效会明说** — per-document nonce refs; a stale ref fails fast with an explanation instead of
   silently clicking a different element.
 - **强力工具默认关闭** — `browser_evaluate` / `browser_cdp` are **not registered at all** unless your
@@ -64,6 +68,28 @@ without a build step — `npm run build` is only needed after editing `src/`.
 
 The bundle mounts three rows: the `ctx.browser` seam (`service`), the Playwright provider (`playwright`), and the model-facing tool family (`tool`).
 
+### Your first task
+
+Install it and ask for something that leaves a visible result — there is nothing else to configure:
+
+> Open `https://news.ycombinator.com` and list the titles of the first five stories with their links.
+
+> Go to my orders page on `<site>` and tell me the delivery address on the most recent order.
+
+> Fill in this contact form, but stop and show me the filled form before you submit it.
+
+What you should see: a real browser window on your desktop doing the clicking, and the page coming back to
+the model as a `ref`-numbered list. The first time it meets a sign-in, a 2FA prompt or a verification page
+it **stops and tells you** — take the window over by hand and it continues from where it left off. The
+logins already in that profile are what make the rest work.
+
+Two habits worth having on day one:
+
+- **Let it look before it clicks.** Start from `browser_snapshot`; a `ref` is only valid in the result that
+  produced it (a stale one fails fast instead of clicking something else).
+- **Say "stop" for the irreversible step.** Submitting, paying, deleting and sending are the points where
+  you want to read the form first.
+
 ### Browser binary
 
 The provider probes `chromium` → `chrome` → `msedge` → `edge` channels automatically; any installed Chromium-family browser works with **zero download**. To use Playwright-managed Chromium instead:
@@ -204,6 +230,9 @@ whose snapshots are long, and both are off by default because both change what t
   anchor. Turn it on when a page re-renders often and you resent paying for the same tree twice.
 - **`interactiveOnlyDefault`** (tool row) — makes `browser_snapshot` default to actionable elements
   only; the model can still pass `interactiveOnly: false` per call when it needs the text around them.
+  Frames are kept either way: an iframe's accessible name is the embedded widget's own title, which is
+  how a challenge widget identifies itself, so pruning it would hide the wall the snapshot is meant to
+  reveal.
 
 Both are honest trades, not free wins: a diff is smaller but requires the model to hold the previous
 tree, and an interactive-only snapshot hides the prose the model may want to read. Measure before
@@ -254,7 +283,10 @@ npm run cost       # resident prompt cost of the tool schemas, per surface
 npm run build      # tsc → lib/
 ```
 
-`scripts/` is self-contained: `dsh-browser-verify.mjs`, `doctor.mjs` and `measure-prompt-cost.mjs` live inside the package and resolve their imports relatively, so copying this directory elsewhere keeps every check runnable. A thin forwarder at `D:\dsh-plugins\_deps\scripts\dsh-browser-verify.mjs` keeps the old command (and the toolbox panel entry) working.
+Two of those scripts ship with the package and work against an installed copy, because they need nothing
+but `lib/` and the harness: `node scripts/dsh-browser-verify.mjs` (the acceptance suite) and
+`node scripts/doctor.mjs` (re-checks the harness exports after an upgrade). The rest are repository-only
+and run from a checkout — `measure-prompt-cost.mjs` reads `src/`, so it cannot work from a tarball.
 
 ### Test suites
 
@@ -336,6 +368,7 @@ Written for people deciding whether to hand an agent their browser:
 - **Extract needs a dedicated model route** — it does not reuse the main request's route; misconfiguration fails loudly at call time.
 - **JS-driven navigations are not statically checkable** — `allowedDomains` covers `browser_navigate`, `browser_open_tab`, every click path (`browser_click`: ref, `precise`, raw-coordinate and `mode:"hover"` modes) and `browser_switch_tab`, but a button whose handler runs `location.href = …` can still leave the allowed hosts, and a tab that is already sitting on a disallowed host stays open (the agent simply refuses to drive it); deploy an external network guard for hard isolation.
 - **Stability waits are bounded by design** — a perpetually animating element falls back to a forced click on its current rect rather than stalling; a page that never settles is snapshotted after the cap. This is intentional: the agent must never hang.
+- **Challenge detection reads the responses it has actually seen** — the response-header tier applies to a document response this session observed after it attached to the tab. A tab that was already sitting on a challenge page when the session took it over falls through to the widget and wording tiers and, failing those, to the no-progress backstop: it reports a *possible* wall instead of guessing the vendor.
 
 ### Ref and lifecycle safety (fixed)
 

package/SECURITY.md

@@ -70,8 +70,8 @@ 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 **v0.5.3 (2026-10-11)** reports
-**1 Critical, 3 Warning, 22 Info** across 75 files — and it is **right about the capability**. Here is
+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.
 
 > For the record: their v0.4.9 scan — before this plugin was split into responsibility-scoped modules —
@@ -83,7 +83,7 @@ each one, with the gate that decides whether it is reachable at all.
 | Critical | `new Function('return (' + expression + ')')` — reported in `lib/session.js` (source: `src/session.ts`) | The body of **`browser_evaluate`**: it wraps your expression and runs it in the page. This is what "run JavaScript in the page" means; there is no way to implement it without dynamic evaluation. | Only when `allowEvaluate: true`. **The package ships `false`, so the tool is not registered.** |
 | Warning | `fs.writeFileSync` of a JSON blob (`lib/login-state.js`, `lib/runtime-state.js`) | Exporting the login state (`cookies` + `localStorage`) so a closed window can be reopened still logged in, and the small runtime state file behind the Settings switches. | Always — it is how login persistence works. The files live under your DSH home. |
 | 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 ×22 | `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"*. | — |
+| 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"*. | — |
 
 Two honest notes:
 

package/lib/challenge-signatures.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 挑战页签名表：把「这页是不是拦截页」的判据放在厂商自有信号上，而不是页面文案上。
+ *
+ * 为什么分层，以及为什么是这个顺序（稳定性递减）：
+ *
+ * 1. 响应头是厂商对外的 API。Cloudflare 专门发文教用户读 `cf-mitigated: challenge`
+ *    来识别挑战页，AWS WAF 同理（`x-amzn-waf-action: challenge`）。厂商改一个字的代价
+ *    是打断所有客户的集成，不是打断我们一个插件。
+ * 2. 厂商控件的无障碍名是次稳的：reCAPTCHA / hCaptcha / Turnstile 的 iframe 标题就是
+ *    他们自己的产品名，出现在每一张用了他们的页面上。
+ * 3. 文案最脆。FlareSolverr 就是死在依赖页面 title 和元素 class 上（上游 issue #1734：
+ *    「元素的 class 和 id 被改过，所以现有的检测规则失效」）。
+ *
+ * 因此新增一家厂商 = 在这张表里加一条签名 + 在 tests/challenge.test.ts 加一条用例，
+ * 判定逻辑本身不用改。
+ * @module dsh-browser-playwright-codex/challenge-signatures
+ */
+/**
+ * How a signature was proven. `response-header` is the vendor's own API,
+ * `widget` is the vendor's own widget, `wording` is the fallback we trust least.
+ */
+export type ChallengeTier = 'response-header' | 'widget' | 'wording';
+/**
+ * One response-header rule. Matching is case-insensitive; a rule with neither
+ * `equals` nor `contains` fires on the header's presence alone.
+ */
+export interface HeaderRule {
+    /** Exact header name. Ignored when `namePrefix` is set. */
+    readonly name: string;
+    /** Exact value the header must carry. */
+    readonly equals?: string;
+    /** Substring the value must contain. */
+    readonly contains?: string;
+}
+/** One vendor's interception signature. */
+export interface ChallengeSignature {
+    /** Stable id, used in tests and diagnostics. */
+    readonly id: string;
+    /** Engine label shown to the model. */
+    readonly engine: string;
+    /** One-clause explanation of what is happening. */
+    readonly hint: string;
+    /**
+     * Header rules proven against the MAIN document response. These are the
+     * vendor's published detection contract, so they are checked first.
+     */
+    readonly headers?: readonly HeaderRule[];
+    /** Case-insensitive header-name prefixes (e.g. DataDome's `x-datadome*`). */
+    readonly headerPrefixes?: readonly string[];
+    /**
+     * Accessible-name tokens only this vendor's widget carries. On a non-iframe
+     * node a token must ALSO be corroborated by {@link WIDGET_CORROBORATION}.
+     */
+    readonly widgetTokens?: readonly RegExp[];
+    /**
+     * Wording this vendor puts in the TITLE of its own interstitial. Vendor
+     * wording is stronger than generic wording, so it is checked first and keeps
+     * the vendor's name on the result.
+     */
+    readonly titleWording?: readonly RegExp[];
+}
+/**
+ * Wording that corroborates a widget token found on a non-iframe node.
+ *
+ * Shared by every vendor on purpose, and it contains no vendor token: three of
+ * the tokens below ("reCAPTCHA", "FunCaptcha", "px-captcha") literally contain
+ * the word "captcha", so a list that accepted "captcha" would let the token
+ * corroborate itself and the guard would be vacuous.
+ */
+export declare const WIDGET_CORROBORATION: readonly RegExp[];
+/**
+ * Every vendor we can prove from machine signals. Adding a vendor here is the
+ * whole change: the detector walks the table, it does not know any of these names.
+ */
+export declare const CHALLENGE_SIGNATURES: readonly ChallengeSignature[];
+/**
+ * Wording a challenge page puts in its TITLE, with no vendor to attribute it to.
+ * A title is short and authored by the interceptor, so a match here is safe on
+ * its own. Kept combinatorial ("verification" + "human/safety/…") rather than
+ * one phrase per language, so a reworded page still matches without a new
+ * signature.
+ */
+export declare const WORDING_TITLE: readonly RegExp[];
+/**
+ * Wording a challenge page puts on a CONTROL (a button, a link, an input).
+ * Command forms only: a help page that explains captchas says "验证码说明",
+ * a challenge says "请输入验证码". The bare word for captcha is deliberately NOT
+ * here — it is gated on a control role in {@link CAPTCHA_ROLES} instead, so a
+ * link to the documentation cannot fire this tier.
+ */
+export declare const WORDING_COMMAND: readonly RegExp[];
+/**
+ * Controls that mention verification but are NOT a bot wall: sending yourself a
+ * code is an ordinary sign-in step, and labelling it an anti-bot challenge
+ * would send the user looking for a wall that is not there.
+ */
+export declare const WORDING_EXCLUDE: readonly RegExp[];
+/** The word for "captcha" itself; only counts on a {@link CAPTCHA_ROLES} node. */
+export declare const CAPTCHA_WORD: RegExp;
+/**
+ * Roles that make {@link CAPTCHA_WORD} count. A captcha input, image or button
+ * is a challenge; a link or heading named "验证码说明" is documentation, and
+ * firing on it would send the user chasing a wall that is not there.
+ */
+export declare const CAPTCHA_ROLES: ReadonlySet<string>;

package/lib/challenge-signatures.js

@@ -0,0 +1,154 @@
+/**
+ * 挑战页签名表：把「这页是不是拦截页」的判据放在厂商自有信号上，而不是页面文案上。
+ *
+ * 为什么分层，以及为什么是这个顺序（稳定性递减）：
+ *
+ * 1. 响应头是厂商对外的 API。Cloudflare 专门发文教用户读 `cf-mitigated: challenge`
+ *    来识别挑战页，AWS WAF 同理（`x-amzn-waf-action: challenge`）。厂商改一个字的代价
+ *    是打断所有客户的集成，不是打断我们一个插件。
+ * 2. 厂商控件的无障碍名是次稳的：reCAPTCHA / hCaptcha / Turnstile 的 iframe 标题就是
+ *    他们自己的产品名，出现在每一张用了他们的页面上。
+ * 3. 文案最脆。FlareSolverr 就是死在依赖页面 title 和元素 class 上（上游 issue #1734：
+ *    「元素的 class 和 id 被改过，所以现有的检测规则失效」）。
+ *
+ * 因此新增一家厂商 = 在这张表里加一条签名 + 在 tests/challenge.test.ts 加一条用例，
+ * 判定逻辑本身不用改。
+ * @module dsh-browser-playwright-codex/challenge-signatures
+ */
+/**
+ * Wording that corroborates a widget token found on a non-iframe node.
+ *
+ * Shared by every vendor on purpose, and it contains no vendor token: three of
+ * the tokens below ("reCAPTCHA", "FunCaptcha", "px-captcha") literally contain
+ * the word "captcha", so a list that accepted "captcha" would let the token
+ * corroborate itself and the guard would be vacuous.
+ */
+export const WIDGET_CORROBORATION = Object.freeze([
+    /verify|challenge|robot|human|verification/i,
+    /验证|校验|人机|真人/,
+]);
+/**
+ * Every vendor we can prove from machine signals. Adding a vendor here is the
+ * whole change: the detector walks the table, it does not know any of these names.
+ */
+export const CHALLENGE_SIGNATURES = Object.freeze([
+    {
+        id: 'cloudflare-challenge',
+        engine: 'Cloudflare',
+        hint: 'Cloudflare answered with a challenge page instead of the page itself',
+        headers: [{ name: 'cf-mitigated', equals: 'challenge' }],
+        // The interstitial's own title, in both languages. Only reached when the
+        // header is missing (a cached page, a prefetch, a client-side fetch).
+        titleWording: [
+            /just a moment|attention required|checking (your )?browser|enable javascript and cookies|cf-chl-/i,
+            /请稍候|验证你的浏览器|正在进行安全验证/,
+        ],
+    },
+    {
+        id: 'aws-waf',
+        engine: 'AWS WAF',
+        hint: 'AWS WAF answered with a challenge instead of the page itself',
+        headers: [{ name: 'x-amzn-waf-action', equals: 'challenge' }],
+    },
+    {
+        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.
+        headers: [{ name: 'x-iinfo' }],
+    },
+    {
+        id: 'datadome',
+        engine: 'DataDome',
+        hint: 'DataDome attached its own metadata to this response',
+        headerPrefixes: ['x-datadome'],
+    },
+    {
+        id: 'recaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded a reCAPTCHA widget, which automation must not attempt to solve',
+        widgetTokens: [/recaptcha/i],
+    },
+    {
+        id: 'hcaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded an hCaptcha widget, which automation must not attempt to solve',
+        widgetTokens: [/hcaptcha/i],
+    },
+    {
+        id: 'turnstile',
+        engine: 'Cloudflare',
+        hint: 'Cloudflare Turnstile is asking the visitor to prove they are human',
+        widgetTokens: [/turnstile/i, /widget containing a cloudflare security challenge/i],
+    },
+    {
+        id: 'arkose-funcaptcha',
+        engine: 'captcha',
+        hint: 'the page embedded an Arkose / FunCaptcha challenge, which automation must not attempt to solve',
+        widgetTokens: [/arkoselabs/i, /funcaptcha/i, /arkose/i],
+    },
+    {
+        id: 'perimeterx-human',
+        engine: 'PerimeterX',
+        hint: 'PerimeterX is asking the visitor to press and hold, which automation must not attempt',
+        widgetTokens: [/px-captcha/i, /perimeterx/i, /press (and|&) hold/i],
+    },
+]);
+/**
+ * Wording a challenge page puts in its TITLE, with no vendor to attribute it to.
+ * A title is short and authored by the interceptor, so a match here is safe on
+ * its own. Kept combinatorial ("verification" + "human/safety/…") rather than
+ * one phrase per language, so a reworded page still matches without a new
+ * signature.
+ */
+export const WORDING_TITLE = Object.freeze([
+    /verify (you are|you're|that you are) (a )?human|are you a robot/i,
+    /人机验证|验证您(是|为)人类|真人验证|安全验证|身份验证|访客验证/,
+    /(滑块|拼图)(验证|校验)/,
+]);
+/**
+ * Wording a challenge page puts on a CONTROL (a button, a link, an input).
+ * Command forms only: a help page that explains captchas says "验证码说明",
+ * a challenge says "请输入验证码". The bare word for captcha is deliberately NOT
+ * here — it is gated on a control role in {@link CAPTCHA_ROLES} instead, so a
+ * link to the documentation cannot fire this tier.
+ */
+export const WORDING_COMMAND = Object.freeze([
+    /(请|点击|输入|拖动|按住|滑动|完成|进行|通过)[^。！？]{0,8}(验证|校验|拼图|滑块)/,
+    /(验证|校验)(您|你)(是|为)/,
+    /(是|为)(真人|人类)(吗|？|\?)?$/,
+    /(拖动|按住|滑动)[^。！？]{0,8}(滑块|拼图)/,
+    /(verify|click|press|complete|solve|check|confirm)[^.!?]{0,24}(human|robot|browser|captcha|challenge|you are)/i,
+    /i'?m not a robot|not a robot/i,
+]);
+/**
+ * Controls that mention verification but are NOT a bot wall: sending yourself a
+ * code is an ordinary sign-in step, and labelling it an anti-bot challenge
+ * would send the user looking for a wall that is not there.
+ */
+export const WORDING_EXCLUDE = Object.freeze([
+    /(获取|发送|重新获取|重新发送|接收)[^。！？]{0,4}(验证码|校验码|短信码)/,
+    /send (the )?(code|sms)|resend/i,
+]);
+/** The word for "captcha" itself; only counts on a {@link CAPTCHA_ROLES} node. */
+export const CAPTCHA_WORD = /captcha|验证码/i;
+/**
+ * Roles that make {@link CAPTCHA_WORD} count. A captcha input, image or button
+ * is a challenge; a link or heading named "验证码说明" is documentation, and
+ * firing on it would send the user chasing a wall that is not there.
+ */
+export const CAPTCHA_ROLES = new Set([
+    'textbox',
+    'searchbox',
+    'combobox',
+    'spinbutton',
+    'button',
+    'checkbox',
+    'radio',
+    'slider',
+    'img',
+    'image',
+    'iframe',
+    'figure',
+]);

package/lib/challenge.d.ts

@@ -1,15 +1,19 @@
 /**
- * 人机验证页识别：从快照里判断是否撞上 Cloudflare 之类的挑战页，并给出对应的提示文案。
+ * 挑战页识别与「无进展」兜底。
+ *
+ * 判定顺序 = 稳定性顺序：先读厂商自己的响应头（他们的公开 API），再看厂商控件的无障碍名，
+ * 最后才看文案。三层都不认识的时候不猜厂商，改问一个与厂商无关的问题——「这个动作之后
+ * 页面变了吗」。所以新出的验证方式没有签名也能被接住，代价只是多问用户一句。
  * @module dsh-browser-playwright-codex/challenge
  */
-import type { ChallengeMatch, ChallengeSnapshot } from './tool-types.ts';
+import type { ChallengeMatch, ChallengeNode, ChallengeSnapshot } from './tool-types.ts';
 /**
- * Detect anti-bot / human-verification challenge pages (Cloudflare
- * interstitial, Turnstile, reCAPTCHA-style) from a snapshot's title, url and
- * visible text. We do NOT try to solve them: the correct move for an agent is
- * to hand the challenge to the human who can see the open window. Returns the
- * engine name when matched, else null. Matching is conservative to avoid
- * false positives on ordinary pages.
+ * Detect an anti-bot / human-verification surface from the MAIN document
+ * response metadata, the page's accessible names and, as a last resort, its
+ * wording. We never try to solve one: the correct move for an agent is to hand
+ * it to the human who can see the open window.
+ * @param snapshot - title, url, accessible tree and (when available) the main document response.
+ * @returns the matched engine with its tier and the concrete evidence, else null.
  */
 export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeMatch | null;
 /**
@@ -18,3 +22,39 @@ export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeM
  * should pause and ask the user to complete it by hand, then re-snapshot.
  */
 export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
+/**
+ * Appended after an action that left the page byte-for-byte unchanged on a page
+ * with almost nothing else to interact with. Worded as a guess, because that is
+ * what it is: it is the shape an unrecognised wall has, and the whole point of
+ * this tier is to cover the vendors we have no signature for.
+ */
+export declare const NO_PROGRESS_NOTE = "[no visible change] that action left the page identical \u2014 same URL, same title, same elements \u2014 and the page offers almost nothing else to click. This is a guess, not a diagnosis: it is what an unrecognised anti-bot wall looks like. Take one browser_snapshot to confirm; if the page still looks unchanged, stop and tell the user what you were trying to do and ask them to look at the open window, instead of retrying the same action.";
+/** A page with at most this many actionable elements counts as "nearly empty". */
+export declare const NO_PROGRESS_MAX_REFS = 3;
+/**
+ * Identity of one page state: URL, title, actionable-element count and the
+ * accessible labels. Two captures with the same fingerprint look the same to a
+ * human glancing at the window, which is exactly the question this tier asks.
+ * @param input - the slice of a snapshot the backstop compares.
+ * @returns an opaque fingerprint string.
+ */
+export declare function snapshotFingerprint(input: {
+    readonly url?: string | undefined;
+    readonly title?: string | undefined;
+    readonly refs?: number | undefined;
+    readonly nodes?: readonly ChallengeNode[] | undefined;
+}): string;
+/**
+ * The no-progress backstop: a vendor we have never seen leaves no signature, so
+ * we stop asking "which wall is this" and ask "did anything happen". Deliberately
+ * conservative — it needs an identical page AND (a nearly empty page, or a second
+ * identical result), so an ordinary click that is not meant to change anything
+ * stays quiet.
+ * @param input - whether an action just ran, the identical-capture streak, and the ref count.
+ * @returns the advisory note, or null when the page is still plausibly alive.
+ */
+export declare function detectNoProgress(input: {
+    readonly afterAction: boolean;
+    readonly unchangedStreak: number;
+    readonly refs: number;
+}): string | null;