dsh-browser-playwright-codex 0.6.1 → 0.6.6

package/lib/page-diagnostics.js

@@ -65,11 +65,29 @@ export function trackPage(session, page) {
         });
         page.on('response', (response) => {
             const slot = session.requestEntries.get(response.request());
-            if (slot === undefined)
-                return;
-            slot.entry.status = response.status();
-            slot.entry.ms = Date.now() - slot.startedAt;
-            session.requestEntries.delete(response.request());
+            if (slot !== undefined) {
+                slot.entry.status = response.status();
+                slot.entry.ms = Date.now() - slot.startedAt;
+                session.requestEntries.delete(response.request());
+            }
+            // The main document response carries whatever the interceptor put on the
+            // wire. Challenge detection reads this before it reads a single word of the
+            // page: `cf-mitigated: challenge` is Cloudflare's published detection
+            // contract, and unlike page wording it cannot be reworded by accident.
+            try {
+                if (!response.request().isNavigationRequest())
+                    return;
+                if (response.frame() !== page.mainFrame())
+                    return;
+                session.docResponses.set(page, {
+                    status: response.status(),
+                    url: response.url(),
+                    headers: { ...response.headers() },
+                });
+            }
+            catch {
+                // A response that detached mid-flight must never break capture.
+            }
         });
         page.on('requestfailed', (request) => {
             const slot = session.requestEntries.get(request);
@@ -155,6 +173,11 @@ export function networkRequests(session, args) {
         })),
     };
 }
+/**
+ * Bounded page data for browser_extract. Credential values (password fields and
+ * password-autocomplete fields) are blanked inside the page before the payload
+ * leaves the browser: the extract prompt is sent to an auxiliary model.
+ */
 export async function pageData(session) {
     return session.run(async () => {
         session.assertLive();
@@ -164,7 +187,38 @@ export async function pageData(session) {
             const fn = window.__dshPageData;
             if (typeof fn !== 'function')
                 return { url: location.href, title: document.title, text: '', truncated: false, links: [], inputs: [] };
-            return fn({ maxTextChars: 30000, maxLinks: 300, maxInputs: 200 });
+            const data = fn({ maxTextChars: 30000, maxLinks: 300, maxInputs: 200 });
+            // Credentials never leave the page. __dshPageData reads every field's current
+            // value, and browser_extract pastes that object into an auxiliary model's
+            // prompt, so a login or change-password page put the plaintext password into
+            // that prompt (audit B3). The field itself stays — "there is a password box
+            // here" is useful page structure — but its value is blanked. The collector and
+            // this pass use the same selector over the same document, so the i-th entry is
+            // the i-th field.
+            if (data !== null && Array.isArray(data.inputs)) {
+                const fields = document.querySelectorAll('input, select, textarea');
+                for (let index = 0; index < data.inputs.length; index += 1) {
+                    const entry = data.inputs[index];
+                    const field = fields[index];
+                    if (entry === undefined || field === undefined)
+                        continue;
+                    const type = (field.getAttribute('type') ?? '').toLowerCase();
+                    const autocomplete = (field.getAttribute('autocomplete') ?? '').toLowerCase();
+                    if (type === 'password' ||
+                        autocomplete.includes('current-password') ||
+                        autocomplete.includes('new-password') ||
+                        // One-time codes and card numbers are just as sensitive as passwords: a
+                        // 2FA code in the prompt can be replayed, and a card number is payment
+                        // data (independent review, P2-7). The field stays, its value does not.
+                        autocomplete.includes('one-time-code') ||
+                        autocomplete.includes('cc-number') ||
+                        autocomplete.includes('cc-csc') ||
+                        autocomplete.includes('cc-exp')) {
+                        entry['value'] = '';
+                    }
+                }
+            }
+            return data;
         };
         let data;
         try {

package/lib/page-probes.d.ts

@@ -55,6 +55,18 @@ export declare const pageStabilityProbe: (arg: {
     frames: number;
     timeoutMs: number;
 }) => Promise<boolean>;
+/**
+ * The href a click on this element would follow: the element's own href, or the
+ * nearest ancestor `<a href>` — crossing shadow-root boundaries, the same way the
+ * hit-test walks. Raw-coordinate clicks already check `closest('a[href]')`; ref and
+ * text clicks used to look only at the element itself, so a button/span nested in an
+ * off-domain `<a>` reached the outside host while every check passed. This probe is
+ * that missing layer: locator.evaluate(clickTargetHrefProbe).
+ *
+ * A policy check, not a navigation: `javascript:` hrefs are returned as-is and the
+ * caller's session policy keeps its existing exemption for them.
+ */
+export declare const clickTargetHrefProbe: (el: Element) => string | null;
 /**
  * The click-point hit test, moved out of the session so it lives with the other page-side
  * functions: it is serialized into the page by locator.evaluate(), so the same

package/lib/page-probes.js

@@ -201,6 +201,39 @@ export const pageStabilityProbe = (arg) => new Promise((resolve) => {
     ];
     requestAnimationFrame(tick);
 });
+/**
+ * The href a click on this element would follow: the element's own href, or the
+ * nearest ancestor `<a href>` — crossing shadow-root boundaries, the same way the
+ * hit-test walks. Raw-coordinate clicks already check `closest('a[href]')`; ref and
+ * text clicks used to look only at the element itself, so a button/span nested in an
+ * off-domain `<a>` reached the outside host while every check passed. This probe is
+ * that missing layer: locator.evaluate(clickTargetHrefProbe).
+ *
+ * A policy check, not a navigation: `javascript:` hrefs are returned as-is and the
+ * caller's session policy keeps its existing exemption for them.
+ */
+export const clickTargetHrefProbe = (el) => {
+    const own = el.getAttribute('href');
+    if (own !== null && own !== '')
+        return own;
+    let node = el;
+    // Document order upward, hopping from a shadow root to its host when the
+    // element lives inside one. The seen guard makes a malformed cycle terminate.
+    const seen = [];
+    while (node !== null) {
+        if (seen.indexOf(node) !== -1)
+            break;
+        seen.push(node);
+        const anchor = node.closest('a[href]');
+        if (anchor !== null)
+            return anchor.getAttribute('href');
+        const root = node.getRootNode
+            ? node.getRootNode()
+            : null;
+        node = root !== null && root !== undefined && root.host !== undefined ? root.host : null;
+    }
+    return null;
+};
 export const hitTest = (el) => {
     const r = el.getBoundingClientRect();
     const w = r.width;

package/lib/page-snapshot.d.ts

@@ -80,17 +80,23 @@ export declare function captureLegacy(session: PlaywrightSession, page: Page, op
  * data-dsh-ref, so legacy and aria engines share the same contract.
  */
 export declare function attachDiff(session: PlaywrightSession, snap: BrowserSnapshot): BrowserSnapshot;
+/**
+ * Attach the main document response metadata observed for this page, when there
+ * is one. Challenge detection reads it before it reads a word of the page: a
+ * response header is the interceptor's own published API, unlike its prose.
+ */
+export declare function attachDocResponse(session: PlaywrightSession, page: Page, snap: BrowserSnapshot): BrowserSnapshot;
+/**
+ * The no-progress backstop — the tier that needs no vendor signature at all. It
+ * compares this capture's page-state fingerprint with the previous one and, for a
+ * post-action capture, appends an advisory note when nothing moved. The note says
+ * it is a guess on purpose: covering walls we have no signature for is the point.
+ */
+export declare function attachNoProgress(session: PlaywrightSession, snap: BrowserSnapshot, afterAction: boolean): BrowserSnapshot;
 /** Build ref -> feature signature map from a captured tree, with parent refs. */
 export declare function buildRefSignatures(_session: PlaywrightSession, nodes: readonly BrowserNode[]): Map<string, RefSignature>;
 export declare function snapshot(session: PlaywrightSession, opts?: {
     interactiveOnly?: boolean;
-}): Promise<BrowserSnapshot | {
-    url: string;
-    title: string;
-    nodes: never[];
-    totalRefs: number;
-    truncated: boolean;
-    dialogNote: string;
-}>;
+}): Promise<BrowserSnapshot>;
 export declare function refLocator(session: PlaywrightSession, ref: string): Promise<import("playwright-core").Locator>;
 export declare function assertLive(session: PlaywrightSession): void;

package/lib/page-snapshot.js

@@ -1,4 +1,5 @@
 import { captureAriaSnapshot } from "./snapshot-aria.js";
+import { detectNoProgress, snapshotFingerprint } from "./challenge.js";
 import { isContextDestroyed } from "./page-diagnostics.js";
 import { REF_PATTERN } from "./config.js";
 import { BrowserError } from "./errors.js";
@@ -72,7 +73,7 @@ export async function settleAndSnapshot(session, page, navChanged) {
             await page.waitForLoadState('load', { timeout: session.timeoutMs() }).catch(() => { });
         }
         await session.waitForPageStable(page, navChanged ? 1500 : 800);
-        return await session.capture(page, undefined);
+        return await session.capture(page, undefined, true);
     });
     if (raced.blocked)
         return session.blockedSnapshot(page, raced.pending);
@@ -109,9 +110,9 @@ export async function captureAria(session, page, opts) {
         const legacy = await session.captureLegacy(page, opts);
         return {
             ...legacy,
-            engineNote: 'smart mode could not read session page, so it was rendered with the compatible engine. ' +
+            engineNote: 'smart mode could not read this page, so it was rendered with the compatible engine. ' +
                 'The refs below belong to the compatible engine. Nothing is wrong with the page; ' +
-                'switch the page-reading mode in Settings if you want to stop seeing session.',
+                'switch the page-reading mode in Settings if you would rather not see this fallback notice.',
         };
     }
     return {
@@ -206,6 +207,52 @@ export function attachDiff(session, snap) {
     }
     return { ...snap, diff: { added, removed, changed, same, navigationReset: false } };
 }
+/**
+ * Attach the main document response metadata observed for this page, when there
+ * is one. Challenge detection reads it before it reads a word of the page: a
+ * response header is the interceptor's own published API, unlike its prose.
+ */
+export function attachDocResponse(session, page, snap) {
+    const response = session.docResponses.get(page);
+    if (response === undefined)
+        return snap;
+    // Only the response that produced the document we are actually looking at
+    // counts. A single-page app changes the URL with no document load, and reusing
+    // the previous document's headers there would report a wall on a page that is
+    // fine. Falling back to the lower tiers is the fail-safe direction: they still
+    // run, and so does the no-progress backstop.
+    if (withoutHash(response.url) !== withoutHash(snap.url))
+        return snap;
+    return { ...snap, response };
+}
+/** URL without its fragment, for comparing a page against the response it came from. */
+function withoutHash(url) {
+    const hash = url.indexOf('#');
+    return hash === -1 ? url : url.slice(0, hash);
+}
+/**
+ * The no-progress backstop — the tier that needs no vendor signature at all. It
+ * compares this capture's page-state fingerprint with the previous one and, for a
+ * post-action capture, appends an advisory note when nothing moved. The note says
+ * it is a guess on purpose: covering walls we have no signature for is the point.
+ */
+export function attachNoProgress(session, snap, afterAction) {
+    const fingerprint = snapshotFingerprint({
+        url: snap.url,
+        title: snap.title,
+        refs: snap.totalRefs,
+        nodes: snap.nodes,
+    });
+    const identical = session.lastFingerprint !== undefined && session.lastFingerprint === fingerprint;
+    session.unchangedStreak = identical ? session.unchangedStreak + 1 : 0;
+    session.lastFingerprint = fingerprint;
+    const note = detectNoProgress({
+        afterAction,
+        unchangedStreak: session.unchangedStreak,
+        refs: snap.totalRefs,
+    });
+    return note === null ? snap : { ...snap, stallNote: note };
+}
 /** Build ref -> feature signature map from a captured tree, with parent refs. */
 export function buildRefSignatures(_session, nodes) {
     const out = new Map();

package/lib/session.d.ts

@@ -5,7 +5,7 @@
  */
 import type { BrowserContext, CDPSession, Locator, Page, Request } from 'playwright-core';
 import type { PlaywrightProvider } from './provider.ts';
-import type { BrowserNode, BrowserSnapshot, DiagnosticsEntry, LoadState } from './types.ts';
+import type { BrowserNode, BrowserSnapshot, DiagnosticsEntry, DocumentResponse, LoadState } from './types.ts';
 import type { RefSignature } from './page-snapshot.ts';
 import { type CookieRow } from './login-sites.ts';
 import type { ActionResult, PendingDialogRecord } from './provider.ts';
@@ -44,6 +44,15 @@ export declare class PlaywrightSession {
         entry: DiagnosticsEntry;
         startedAt: number;
     }>;
+    /**
+     * Main document response per page. Challenge detection reads this before it
+     * reads a word of the page: a response header is the interceptor's own API.
+     */
+    docResponses: WeakMap<Page, DocumentResponse>;
+    /** Fingerprint of the previous capture's page state (no-progress backstop). */
+    lastFingerprint: string | undefined;
+    /** Consecutive captures that produced an identical page-state fingerprint. */
+    unchangedStreak: number;
     /** Ring capacity per stream. */
     diagLimit: number;
     /** ref -> feature signature of the previous capture (diff baseline). */
@@ -87,14 +96,7 @@ export declare class PlaywrightSession {
      * cached data (page.url() needs no round trip) — page.evaluate() and
      * page.title() would both stall behind the dialog.
      */
-    blockedSnapshot(page: Page, pending: PendingDialogRecord | undefined): {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    };
+    blockedSnapshot(page: Page, pending: PendingDialogRecord | undefined): BrowserSnapshot;
     /**
      * Run one page action that may raise a native dialog. Such an action never
      * resolves while the dialog is up, so race it against the dialog appearing
@@ -109,7 +111,7 @@ export declare class PlaywrightSession {
     /** Read the snapshot tree from one page (must run inside a run()). */
     capture(page: Page, opts: {
         interactiveOnly?: boolean;
-    } | undefined): Promise<BrowserSnapshot>;
+    } | undefined, afterAction?: boolean): Promise<BrowserSnapshot>;
     /**
      * Semantic-tree capture via Playwright's official ariaSnapshot(mode:'ai').
      * An unavailable or unreadable aria tree (`missing`) degrades to the legacy
@@ -153,24 +155,10 @@ export declare class PlaywrightSession {
     buildRefSignatures(nodes: readonly BrowserNode[]): Map<string, RefSignature>;
     /** The document nonce shared by this snapshot's refs, or undefined. */
     refNonce(nodes: readonly BrowserNode[]): string | undefined;
-    navigate(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    navigate(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot>;
     snapshot(opts?: {
         interactiveOnly?: boolean;
-    }): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    }): Promise<BrowserSnapshot>;
     /**
      * Codex-style click-point resolution. Tries a scroll-alignment ladder
      * (centre, then end, then start). For each alignment: scroll the element
@@ -186,14 +174,7 @@ export declare class PlaywrightSession {
         hitDesc: string;
         hitSelf: boolean;
     }>;
-    click(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    click(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /**
      * Click an element the snapshot gave no ref, addressed by its visible label
      * (e.g. a menu item revealed by browser_click with mode "hover" that is plain text). The
@@ -201,14 +182,7 @@ export declare class PlaywrightSession {
      * and the landing note names what was actually clicked plus how many
      * elements shared the label.
      */
-    clickText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    clickText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /**
      * Enforce the navigation policy for the link a click is about to follow.
      * Click navigation does not run through navigate(), so this is the only place
@@ -240,41 +214,13 @@ export declare class PlaywrightSession {
      * then report what actually received the click. The label names the target
      * in the landing note; shared is how many elements matched it (0 for refs).
      */
-    clickLocator(locator: Locator, signal: AbortSignal | undefined, label: string, shared: number): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
-    clickAt(x: number, y: number, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
-    clickAtRef(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    clickLocator(locator: Locator, signal: AbortSignal | undefined, label: string, shared: number): Promise<BrowserSnapshot>;
+    clickAt(x: number, y: number, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    clickAtRef(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     fill(ref: string, text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /** Read the field back and decide whether the fill landed. */
     verifyFill(locator: Locator, tag: string, text: string): Promise<boolean>;
-    press(ref: string, key: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    press(ref: string, key: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /**
      * Hover the referenced element: rest the pointer on it so hover-revealed
      * content appears (CSS :hover rules, JS mouseenter handlers, submenus,
@@ -308,14 +254,7 @@ export declare class PlaywrightSession {
         title: string;
         active: boolean;
     }[]>;
-    switchTab(index: number, signal?: AbortSignal): Promise<BrowserSnapshot | {
-        url: string;
-        title: string;
-        nodes: never[];
-        totalRefs: number;
-        truncated: boolean;
-        dialogNote: string;
-    }>;
+    switchTab(index: number, signal?: AbortSignal): Promise<BrowserSnapshot>;
     openTab(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot>;
     closeTab(index: number, signal?: AbortSignal): Promise<void>;
     /**

package/lib/session.js

@@ -4,7 +4,7 @@ import { asTimeoutError, isAbortError, isContextDestroyed, isCrashError } from "
 import { consoleMessages, networkRequests, pageData, trackPage } from "./page-diagnostics.js";
 import { elementStabilityProbe, pageStabilityProbe } from "./page-probes.js";
 import { assertActionable, back, clickAt, clickAtRef, clickLocator, clickText, closeTab, fill, forward, hoverLocator, hoverText, navigate, openTab, press, resolveClickPoint, runAction, scroll, switchTab, verifyFill, withAbort, } from "./page-actions.js";
-import { assertLive, attachDiff, buildRefSignatures, captureAria, captureLegacy, refLocator, resolveSnapshotEngine, settleAndSnapshot, snapshot, } from "./page-snapshot.js";
+import { assertLive, attachDiff, attachDocResponse, attachNoProgress, buildRefSignatures, captureAria, captureLegacy, refLocator, resolveSnapshotEngine, settleAndSnapshot, snapshot, } from "./page-snapshot.js";
 import { assertAllowedUrl } from "./url-policy.js";
 /** Live session over one browser context owned by one caller. */
 export class PlaywrightSession {
@@ -35,6 +35,15 @@ export class PlaywrightSession {
     diagDropped = { console: 0, network: 0 };
     /** In-flight requests keyed by request object, for status and duration attribution. */
     requestEntries = new WeakMap();
+    /**
+     * Main document response per page. Challenge detection reads this before it
+     * reads a word of the page: a response header is the interceptor's own API.
+     */
+    docResponses = new WeakMap();
+    /** Fingerprint of the previous capture's page state (no-progress backstop). */
+    lastFingerprint = undefined;
+    /** Consecutive captures that produced an identical page-state fingerprint. */
+    unchangedStreak = 0;
     /** Ring capacity per stream. */
     diagLimit = 200;
     /** ref -> feature signature of the previous capture (diff baseline). */
@@ -217,12 +226,15 @@ export class PlaywrightSession {
         });
     }
     /** Read the snapshot tree from one page (must run inside a run()). */
-    async capture(page, opts) {
+    async capture(page, opts, afterAction = false) {
         this.provider.armDialogGuard(page);
         const raw = resolveSnapshotEngine(this.provider.config.snapshot.engine) === 'aria'
             ? await this.captureAria(page, opts)
             : await this.captureLegacy(page, opts);
-        return this.attachDiff(raw);
+        // Order matters: the response metadata is attached before the diff, so the
+        // snapshot the model reads carries the same evidence the detector used, and
+        // the no-progress backstop sees the final tree.
+        return this.attachDiff(attachNoProgress(this, attachDocResponse(this, page, raw), afterAction));
     }
     /**
      * Semantic-tree capture via Playwright's official ariaSnapshot(mode:'ai').

package/lib/snapshot-aria.js

@@ -325,6 +325,22 @@ function normalizeRole(role) {
 function convertAriaNode(node, opts, refs, roles, state) {
     const actionable = isActionableRole(node.role);
     if (opts.interactiveOnly === true && !actionable) {
+        // Frames are the one non-actionable node kept: their accessible name is the
+        // embedded widget's own title, and that title appears nowhere else in the
+        // tree (see the same rule in the legacy walker).
+        if (node.role === 'iframe') {
+            state.count += 1;
+            if (state.count > opts.maxNodes) {
+                state.truncated = true;
+                return null;
+            }
+            const frameName = node.name !== '' ? node.name : (node.placeholder ?? '');
+            return {
+                role: node.role,
+                name: frameName.length > opts.maxNameLength ? frameName.slice(0, opts.maxNameLength) + '…' : frameName,
+                children: [],
+            };
+        }
         const kids = [];
         for (const child of node.children) {
             const sub = convertAriaNode(child, opts, refs, roles, state);

package/lib/tool-render.js

@@ -1,4 +1,4 @@
-import { CHALLENGE_NOTE, detectChallenge } from "./challenge.js";
+import { CHALLENGE_NOTE, detectChallenge, detectSilentPage } from "./challenge.js";
 import { renderSnapshot, renderSnapshotDiff } from "./snapshot-render.js";
 /**
  * Render one diagnostics payload as one line per entry. Diagnostics are read when
@@ -57,9 +57,32 @@ export function renderDiagnostics(kind, value) {
 }
 /** Project a provider snapshot into its canonical tool value. */
 export function snapshotValue(snapshot) {
-    const challenge = detectChallenge(snapshot);
+    // The ref count travels with the snapshot on purpose: the wording tier needs it
+    // to tell a real wall (nothing to click) from a results page whose title merely
+    // contains the phrase. Measured on 百度: 0 refs on the challenge, 57/81 on the
+    // search pages titled "安全验证_百度搜索" / "滑块验证_百度搜索".
+    const challenge = detectChallenge({
+        url: snapshot.url,
+        title: snapshot.title,
+        nodes: snapshot.nodes,
+        refs: snapshot.totalRefs,
+        ...(snapshot.response !== undefined ? { response: snapshot.response } : {}),
+    });
     const tree = renderSnapshot(snapshot);
     const notes = [];
+    // The HTTP status was captured for challenge detection but never shown, so a
+    // 404/500 error page reached the model looking like an ordinary page — measured
+    // 2026-10-17 on a real MDN 404: status 404, 35 refs, and nothing in the result
+    // said so. Suppressed when a challenge was identified, because that note
+    // already names the reason.
+    const status = snapshot.response?.status;
+    if (challenge === null && status !== undefined && (status < 200 || status >= 300)) {
+        notes.push('[http ' +
+            String(status) +
+            '] the server answered ' +
+            String(status) +
+            ' for this document, so what follows may be an error page or an interception page rather than the content you asked for.');
+    }
     const dialog = snapshot.dialogNote;
     if (dialog !== undefined && dialog !== '')
         notes.push(dialog);
@@ -72,6 +95,26 @@ export function snapshotValue(snapshot) {
     const engine = snapshot.engineNote;
     if (engine !== undefined && engine !== '')
         notes.push('[page reader] ' + engine);
+    // The no-progress backstop rides with the other notes: it is advice about the
+    // action the model just took, so it has to be in that action's result. It is
+    // suppressed when a challenge was already identified, because "this is a wall,
+    // here is why" is the actionable message and stacking a second, vaguer warning
+    // on top of it only spends prompt budget on a case that is already decided.
+    const stall = snapshot.stallNote;
+    if (challenge === null && stall !== undefined && stall !== '')
+        notes.push(stall);
+    // The backstop above needs an action to compare before and after; a page with
+    // nothing to click never gets one, so the emptiest wall-like pages used to say
+    // nothing at all. Only on a successful status: a 4xx/5xx already has its own line.
+    const healthyStatus = status === undefined || (status >= 200 && status < 300);
+    // A parked dialog means the page is fine, it is the dialog that blocks us: the
+    // dialog note already says what to do, and adding "nothing here" contradicts it.
+    const dialogPending = snapshot.dialogNote !== undefined && snapshot.dialogNote !== '';
+    if (challenge === null && healthyStatus && !dialogPending) {
+        const silent = detectSilentPage({ refs: snapshot.totalRefs, nodes: snapshot.nodes, title: snapshot.title });
+        if (silent !== null)
+            notes.push(silent);
+    }
     const head = notes.length > 0 ? notes.join('\n\n') + '\n\n' : '';
     // Incremental diff rides along when the provider computed one (snapshot.diff).
     const diffBlock = snapshot.diff !== undefined ? '\n\n' + renderSnapshotDiff(snapshot.diff) : '';
@@ -81,7 +124,19 @@ export function snapshotValue(snapshot) {
         refs: snapshot.totalRefs,
         truncated: snapshot.truncated,
         tree: head +
-            (challenge === null ? tree : challenge.engine + ': ' + challenge.hint + '.\n' + CHALLENGE_NOTE + '\n\n' + tree) +
+            (challenge === null
+                ? tree
+                : challenge.engine +
+                    ' [' +
+                    challenge.tier +
+                    ': ' +
+                    challenge.evidence +
+                    ']: ' +
+                    challenge.hint +
+                    '.\n' +
+                    CHALLENGE_NOTE +
+                    '\n\n' +
+                    tree) +
             diffBlock,
     };
 }

package/lib/tool-types.d.ts

@@ -3,6 +3,8 @@
  * @module dsh-browser-playwright-codex/tool-types
  */
 import type { StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { ChallengeTier } from './challenge-signatures.ts';
+import type { DocumentResponse } from './types.ts';
 /**
  * JSON value: the shape every tool value must be serializable to, so the
  * framework can put it on the wire. Declared locally because the installed
@@ -42,6 +44,8 @@ export interface ScreenshotValue {
 /** Minimal node shape the challenge detector walks. */
 export interface ChallengeNode {
     readonly name?: string;
+    /** Accessible role. Both built-in engines provide one; it gates the wording tier. */
+    readonly role?: string;
     readonly children?: readonly ChallengeNode[];
 }
 /** The slice of a snapshot the challenge detector reads. */
@@ -49,11 +53,23 @@ export interface ChallengeSnapshot {
     readonly title?: string;
     readonly url?: string;
     readonly nodes?: readonly ChallengeNode[];
+    /**
+     * Actionable-element count. The wording tier uses it to tell a challenge page
+     * (nothing to click) from an ordinary page whose *title* merely contains the
+     * phrase — searching Baidu for "安全验证" produces exactly that false positive.
+     */
+    readonly refs?: number;
+    /** Main document response metadata; absent when no navigation response was seen. */
+    readonly response?: DocumentResponse;
 }
 /** What the challenge detector reports when a page is an anti-bot wall. */
 export interface ChallengeMatch {
     engine: string;
     hint: string;
+    /** How it was proven, strongest first. */
+    tier: ChallengeTier;
+    /** The concrete signal that fired, so a reader can judge the call instead of trusting it. */
+    evidence: string;
 }
 /** The attachments-service face consumed at execution time. */
 export interface AttachmentServiceLike {

package/lib/types.d.ts

@@ -25,6 +25,17 @@ export interface BrowserNode {
     readonly href?: string;
     readonly children: readonly BrowserNode[];
 }
+/**
+ * Metadata of the main document response that produced a snapshot, read from the
+ * network layer. Challenge detection consults this first: a response header is the
+ * interceptor's own published API (`cf-mitigated: challenge`), unlike its wording.
+ */
+export interface DocumentResponse {
+    readonly status: number;
+    readonly url: string;
+    /** Response headers as Playwright reports them (names lowercased). */
+    readonly headers: Readonly<Record<string, string>>;
+}
 /** Bounded accessibility snapshot of the current page. */
 export interface BrowserSnapshot {
     readonly url: string;
@@ -58,6 +69,18 @@ export interface BrowserSnapshot {
      * and a user who picked smart mode kept believing it was running.
      */
     engineNote?: string;
+    /**
+     * Metadata of the main document response, when the capture observed one. It is
+     * the first thing challenge detection reads, because it is the interceptor's
+     * own API rather than its prose.
+     */
+    response?: DocumentResponse;
+    /**
+     * Advisory note appended when an action left the page identical. This is the
+     * no-progress backstop: it covers anti-bot walls whose vendor we have no
+     * signature for, by asking "did anything happen" instead of "which wall is this".
+     */
+    stallNote?: string;
 }
 /** One element that entered the tree since the previous snapshot. */
 export interface SnapshotDiffEntry {