teamshare-bridge 0.27.0 → 0.27.1

package/dist/lib/browser/challenge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Cloudflare / CAPTCHA challenge handling (2026-10).
+ *
+ * The debug browser used to click blindly at a challenge page for as long as
+ * the agent kept trying. A managed challenge is not a button: it either passes
+ * on its own after Cloudflare's JS runs, or it needs a human. This module:
+ *
+ *  - DETECTS a challenge from the live DOM (title, challenge form, Turnstile /
+ *    reCAPTCHA / hCaptcha iframe, block page);
+ *  - makes at most ONE bounded attempt (a single click on a Turnstile widget,
+ *    or a passive wait for a managed challenge) within a hard timeout;
+ *  - returns a structured verdict so the agent stops and asks a human instead
+ *    of sitting on the challenge.
+ *
+ * It is deliberately NOT a CAPTCHA solver: an image grid is never attempted,
+ * and an interactive Turnstile that does not clear after one click is reported
+ * as `CHALLENGE_REQUIRED`. The prompt then pauses the run with `ask_human`;
+ * the human solves the challenge in the visible window and the answer resumes
+ * the same session.
+ */
+import type { CdpPage } from './cdp';
+export type ChallengeVendor = 'cloudflare' | 'turnstile' | 'recaptcha' | 'hcaptcha' | 'unknown';
+export type ChallengeKind = 
+/** "Just a moment..." / "Checking your browser" — usually clears itself. */
+'managed'
+/** A visible Turnstile checkbox/widget — one bounded click is worth trying. */
+ | 'turnstile'
+/** reCAPTCHA / hCaptcha image challenge — never attempted automatically. */
+ | 'captcha'
+/** Cloudflare block page (WAF / rate limit) — not a challenge to solve. */
+ | 'block';
+export interface ChallengeState {
+    detected: true;
+    vendor: ChallengeVendor;
+    kind: ChallengeKind;
+    title: string;
+    url: string;
+    /** Widget centre (CSS pixels) when a visible widget was found. */
+    widget?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Short page excerpt for the agent/human (capped). */
+    text?: string;
+}
+export interface ChallengeResolution {
+    detected: boolean;
+    attempted: boolean;
+    passed: boolean;
+    elapsedMs: number;
+    /** The challenge as detected (first sighting), when one existed. */
+    challenge?: ChallengeState;
+    /** True when a previous failure parked this host; no attempt was made. */
+    cooldown?: boolean;
+    /** What the caller should do next when `passed` is false. */
+    nextStep?: 'ask_human' | 'report_blocked';
+}
+/**
+ * The in-page probe. Exported so the unit test can syntax-check it; it must
+ * stay a self-contained expression returning a JSON string.
+ */
+export declare function buildChallengeProbeScript(): string;
+/**
+ * Read the live page for challenge markers. Never throws — a navigation or a
+ * destroyed execution context simply means "no challenge observed".
+ */
+export declare function detectChallenge(page: CdpPage): Promise<ChallengeState | null>;
+/**
+ * Bounded resolution. Callers inject `detect`/`click` so this stays pure with
+ * respect to the CDP client and can be unit-tested.
+ *
+ * - managed / block / captcha: never clicked. Managed may pass on its own.
+ * - turnstile: ONE click on the widget, then wait for clearance.
+ * - Anything still challenged at the deadline returns `passed:false` with
+ *   `nextStep` set, so the caller can stop and ask a human.
+ */
+export declare function resolveChallenge(opts: {
+    detect: () => Promise<ChallengeState | null>;
+    click?: (x: number, y: number) => Promise<void>;
+    attempt?: boolean;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<ChallengeResolution>;

package/dist/lib/browser/challenge.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChallengeProbeScript = buildChallengeProbeScript;
+exports.detectChallenge = detectChallenge;
+exports.resolveChallenge = resolveChallenge;
+const cdp_1 = require("./cdp");
+const browse_types_1 = require("./browse-types");
+const DEFAULT_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.TEAMSHARE_CHALLENGE_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 25_000;
+})();
+const POLL_MS = 500;
+/**
+ * The in-page probe. Exported so the unit test can syntax-check it; it must
+ * stay a self-contained expression returning a JSON string.
+ */
+function buildChallengeProbeScript() {
+    return `(() => {
+        const title = document.title || '';
+        const url = location.href;
+        const body = document.body ? (document.body.innerText || '') : '';
+        const text = body.slice(0, 1200);
+        const lower = text.toLowerCase();
+        const hay = (title + ' ' + lower).toLowerCase();
+
+        const iframe = Array.from(document.querySelectorAll('iframe')).find((f) => {
+          const src = String(f.getAttribute('src') || f.src || '').toLowerCase();
+          return src.includes('challenges.cloudflare.com') ||
+            src.includes('turnstile') ||
+            src.includes('recaptcha') ||
+            src.includes('hcaptcha');
+        });
+        const src = iframe ? String(iframe.getAttribute('src') || iframe.src || '').toLowerCase() : '';
+        const turnstileEl = document.querySelector(
+          '.cf-turnstile, [data-sitekey], input[name="cf-turnstile-response"], #cf-chl-widget',
+        );
+        const managedEl = document.querySelector(
+          '#challenge-form, #challenge-stage, #cf-please-wait, #cf-challenge-running, #cf-verify, .cf-browser-verification',
+        );
+        const blockEl = document.querySelector('#cf-error-details, .cf-error-details');
+
+        let vendor = 'unknown';
+        let kind = null;
+        if (blockEl || /attention required|access denied|you have been blocked|error 10\\d\\d/i.test(hay)) {
+          vendor = 'cloudflare';
+          kind = 'block';
+        } else if (src.includes('recaptcha')) {
+          vendor = 'recaptcha';
+          kind = 'captcha';
+        } else if (src.includes('hcaptcha')) {
+          vendor = 'hcaptcha';
+          kind = 'captcha';
+        } else if (src.includes('turnstile') || src.includes('challenges.cloudflare.com') || turnstileEl) {
+          vendor = 'turnstile';
+          kind = 'turnstile';
+        } else if (managedEl || /just a moment|checking your browser|verify you are human|enable javascript and cookies|cf-chl/i.test(hay)) {
+          vendor = 'cloudflare';
+          kind = 'managed';
+        }
+        if (!kind) return JSON.stringify({ detected: false });
+
+        let widget = null;
+        const el = iframe || turnstileEl;
+        if (el) {
+          const r = el.getBoundingClientRect();
+          if (r.width > 4 && r.height > 4) {
+            // Turnstile's checkbox sits ~30px from the widget's left edge;
+            // clicking the exact centre hits the label text instead.
+            const x = Math.round(r.x + Math.min(30, r.width / 2));
+            const y = Math.round(r.y + r.height / 2);
+            widget = { x, y, width: Math.round(r.width), height: Math.round(r.height) };
+          }
+        }
+        return JSON.stringify({
+          detected: true,
+          vendor,
+          kind,
+          title: title.slice(0, 200),
+          url,
+          widget,
+          text: text.slice(0, 600),
+        });
+      })()`;
+}
+/**
+ * Read the live page for challenge markers. Never throws — a navigation or a
+ * destroyed execution context simply means "no challenge observed".
+ */
+async function detectChallenge(page) {
+    try {
+        const raw = await (0, cdp_1.evaluateJs)(page, buildChallengeProbeScript());
+        const parsed = JSON.parse(String(raw ?? '{"detected":false}'));
+        return parsed && parsed.detected ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bounded resolution. Callers inject `detect`/`click` so this stays pure with
+ * respect to the CDP client and can be unit-tested.
+ *
+ * - managed / block / captcha: never clicked. Managed may pass on its own.
+ * - turnstile: ONE click on the widget, then wait for clearance.
+ * - Anything still challenged at the deadline returns `passed:false` with
+ *   `nextStep` set, so the caller can stop and ask a human.
+ */
+async function resolveChallenge(opts) {
+    const started = Date.now();
+    const timeout = Math.min(Math.max(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, 1_000), 120_000);
+    const pollMs = Math.max(opts.pollMs ?? POLL_MS, 200);
+    const first = await opts.detect().catch(() => null);
+    if (!first) {
+        return {
+            detected: false,
+            attempted: false,
+            passed: true,
+            elapsedMs: Date.now() - started,
+        };
+    }
+    const blockedKind = first.kind === 'block' || first.kind === 'captcha';
+    const canClick = opts.attempt !== false &&
+        first.kind === 'turnstile' &&
+        !!first.widget &&
+        typeof opts.click === 'function';
+    let attempted = false;
+    if (canClick) {
+        attempted = true;
+        try {
+            await opts.click(first.widget.x, first.widget.y);
+            // Give the widget a beat to react before polling; a second click is
+            // never sent - repeated clicks lower Cloudflare's score.
+            await (0, browse_types_1.sleep)(700);
+        }
+        catch {
+            /* a failed click is a failed attempt; polling still runs */
+        }
+    }
+    const deadline = started + (blockedKind ? 1_500 : timeout);
+    let last = first;
+    while (Date.now() < deadline) {
+        const now = await opts.detect().catch(() => null);
+        if (!now) {
+            return {
+                detected: true,
+                attempted,
+                passed: true,
+                elapsedMs: Date.now() - started,
+                challenge: first,
+            };
+        }
+        last = now;
+        await (0, browse_types_1.sleep)(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+    }
+    return {
+        detected: true,
+        attempted,
+        passed: false,
+        elapsedMs: Date.now() - started,
+        challenge: last ?? first,
+        nextStep: (last ?? first).kind === 'block' ? 'report_blocked' : 'ask_human',
+    };
+}
+//# sourceMappingURL=challenge.js.map

package/dist/lib/browser/challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../../../src/lib/browser/challenge.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/launch.d.ts

@@ -60,6 +60,15 @@ export interface LaunchOptions {
     startUrl?: string;
     /** Extra Chrome CLI args. */
     args?: string[];
+    /**
+     * OPT-IN (2026-10): reduce the automation fingerprint. Drops the
+     * Puppeteer-style flags (`--disable-extensions`, `--disable-sync`, …) that
+     * sites use as automation tells and disables `AutomationControlled`. The
+     * session also injects the pre-document shims (webdriver/chrome/plugins).
+     * Off by default: a deterministic QA browser is intentionally boring, and
+     * aggressive spoofing can break a site that expects a normal Chrome.
+     */
+    stealth?: boolean;
     /** Timeout to wait for Chrome to become reachable (ms, default 15000). */
     timeoutMs?: number;
 }

package/dist/lib/browser/launch.js

@@ -74,16 +74,18 @@ async function launchChrome(options) {
     const chromeArgs = [
         `--remote-debugging-port=${port}`,
         `--user-data-dir=${userDataDir}`,
-        '--no-first-run',
-        '--no-default-browser-check',
-        '--disable-background-networking',
-        '--disable-default-apps',
-        '--disable-extensions',
-        '--disable-sync',
-        '--disable-translate',
-        '--metrics-recording-only',
-        '--safebrowsing-disable-auto-update',
     ];
+    if (options?.stealth) {
+        // Minimal, ordinary-looking launch: the automation FORENSICS flags below
+        // are the ones a challenge script checks for. `AutomationControlled` off
+        // removes the `navigator.webdriver` tell at the source. First-run flags are
+        // kept because a fresh isolated profile otherwise opens a first-run tab
+        // that has nothing to do with automation.
+        chromeArgs.push('--no-first-run', '--no-default-browser-check', '--disable-blink-features=AutomationControlled');
+    }
+    else {
+        chromeArgs.push('--no-first-run', '--no-default-browser-check', '--disable-background-networking', '--disable-default-apps', '--disable-extensions', '--disable-sync', '--disable-translate', '--metrics-recording-only', '--safebrowsing-disable-auto-update');
+    }
     if (headless) {
         chromeArgs.push('--headless=new');
     }

package/dist/lib/browser/launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../../src/lib/browser/launch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../../src/lib/browser/launch.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/session.d.ts

@@ -6,6 +6,7 @@ import { type FillOtpOptions, type FillOtpResult } from './otp';
 import { type NativeDialogState, type PagePaginationState, type PageSnapshot, type WaitForKind } from './page-context';
 import { type PageEvent } from './page-events';
 import { type RefElement } from './refs';
+import { type ChallengeResolution, type ChallengeState } from './challenge';
 /**
  * Persistent Chrome profile for the AUTO-ANSWER browser (research reads,
  * `browse --auto-answer`, the web-auto-answer tool).
@@ -51,6 +52,12 @@ export interface BrowserSessionOptions {
     isolated?: boolean;
     /** Extra Chrome args for auto-launch. */
     chromeArgs?: string[];
+    /**
+     * OPT-IN (2026-10): reduce the automation fingerprint. Drops the
+     * Puppeteer-style launch flags, disables `AutomationControlled` and injects
+     * the pre-document shims before any page script runs. Off by default.
+     */
+    stealth?: boolean;
     /**
      * OPT-IN (default false): permit typing into password/credential fields.
      *
@@ -81,6 +88,8 @@ export declare class BrowserSession {
     private _headless;
     private _profileDir;
     private _chromeArgs;
+    /** Opt-in fingerprint reduction (see BrowserSessionOptions.stealth). */
+    private _stealth;
     private _connected;
     /** Opt-in credential entry (see BrowserSessionOptions.allowCredentials). */
     private _allowCredentials;
@@ -113,11 +122,26 @@ export declare class BrowserSession {
      * it. A native dialog blocks the renderer, so a page snapshot would hang.
      */
     private _nativeDialog;
+    /**
+     * Per-host challenge cooldown (2026-10): after a failed bounded attempt the
+     * same host is NOT re-attempted for 10 minutes. Without this an agent loop
+     * could sit on a challenge page forever, which is exactly what the human
+     * sees as "stuck trying Cloudflare".
+     */
+    private _challengeCooldown;
     constructor(id: string, opts?: BrowserSessionOptions);
     /** The stable session name the browser manager keys this session by. */
     get sessionKey(): string;
     /** The user-data-dir this session launches Chrome with. */
     get profileDir(): string;
+    /** Whether this session launched with the opt-in stealth shims. */
+    get stealth(): boolean;
+    /**
+     * Turn on the opt-in stealth shims for a LIVE session (2026-10). The launch
+     * flags cannot change after Chrome started, but the pre-document shims can be
+     * registered now (future navigations) and applied to the current document.
+     */
+    enableStealth(): Promise<void>;
     /** The test-account label this window is tagged for (2026-11). */
     get actor(): string | null;
     /** Tag an untagged window. A tagged window never changes hands. */
@@ -268,7 +292,32 @@ export declare class BrowserSession {
         truncated: boolean;
         stoppedBecause: string;
     }>;
-    navigate(url: string): Promise<PageInfo>;
+    navigate(url: string, opts?: {
+        autoChallenge?: boolean;
+        challengeTimeoutMs?: number;
+    }): Promise<PageInfo & {
+        challenge?: ChallengeResolution;
+    }>;
+    /** Detect a Cloudflare / CAPTCHA challenge on the live page (cheap, safe). */
+    detectChallenge(): Promise<ChallengeState | null>;
+    /**
+     * One bounded challenge attempt (2026-10): a single click for a Turnstile
+     * widget, passive wait for a managed challenge, nothing for a block/image
+     * CAPTCHA. Callers stop and ask a human when `passed` is false.
+     */
+    resolveChallenge(opts?: {
+        attempt?: boolean;
+        timeoutMs?: number;
+    }): Promise<ChallengeResolution>;
+    /**
+     * Poll only (no click). Used after a human answered a `CHALLENGE_REQUIRED`
+     * pause: the human solved it in the visible window; this waits for the page
+     * to clear and returns the new screen.
+     */
+    waitForChallenge(opts?: {
+        timeoutMs?: number;
+        attempt?: boolean;
+    }): Promise<ChallengeResolution>;
     /**
      * Set the browser viewport before a design-verification screenshot
      * (2026-11): the design's viewport IS the contract — a pixel diff at any

package/dist/lib/browser/session.js

@@ -60,6 +60,9 @@ const page_context_1 = require("./page-context");
 const page_events_1 = require("./page-events");
 const refs_1 = require("./refs");
 const screen_change_1 = require("./screen-change");
+const stealth_1 = require("./stealth");
+const browse_types_1 = require("./browse-types");
+const challenge_1 = require("./challenge");
 /**
  * Persistent Chrome profile for the AUTO-ANSWER browser (research reads,
  * `browse --auto-answer`, the web-auto-answer tool).
@@ -89,6 +92,15 @@ exports.DEBUG_PROFILE_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.te
  * CdpPage and must instrument it again.
  */
 const instrumentedPages = new WeakSet();
+/** Host of a URL for the per-host challenge cooldown ('' when unparseable). */
+function hostOf(url) {
+    try {
+        return new URL(url).host.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
 class BrowserSession {
     id;
     page = null;
@@ -98,6 +110,8 @@ class BrowserSession {
     _headless;
     _profileDir;
     _chromeArgs;
+    /** Opt-in fingerprint reduction (see BrowserSessionOptions.stealth). */
+    _stealth;
     _connected = false;
     /** Opt-in credential entry (see BrowserSessionOptions.allowCredentials). */
     _allowCredentials;
@@ -130,6 +144,13 @@ class BrowserSession {
      * it. A native dialog blocks the renderer, so a page snapshot would hang.
      */
     _nativeDialog = null;
+    /**
+     * Per-host challenge cooldown (2026-10): after a failed bounded attempt the
+     * same host is NOT re-attempted for 10 minutes. Without this an agent loop
+     * could sit on a challenge page forever, which is exactly what the human
+     * sees as "stuck trying Cloudflare".
+     */
+    _challengeCooldown = null;
     constructor(id, opts) {
         this.id = id;
         this._port = opts?.port ?? exports.DEBUG_CDP_PORT;
@@ -141,6 +162,7 @@ class BrowserSession {
                 ? opts.actor.trim()
                 : null;
         this._chromeArgs = opts?.chromeArgs ?? [];
+        this._stealth = opts?.stealth === true;
         this._allowCredentials = opts?.allowCredentials ?? false;
         this._qaVision = opts?.qaVision ?? false;
     }
@@ -152,6 +174,36 @@ class BrowserSession {
     get profileDir() {
         return this._profileDir;
     }
+    /** Whether this session launched with the opt-in stealth shims. */
+    get stealth() {
+        return this._stealth;
+    }
+    /**
+     * Turn on the opt-in stealth shims for a LIVE session (2026-10). The launch
+     * flags cannot change after Chrome started, but the pre-document shims can be
+     * registered now (future navigations) and applied to the current document.
+     */
+    async enableStealth() {
+        if (this._stealth)
+            return;
+        this._stealth = true;
+        if (!this.page)
+            return;
+        try {
+            await (0, cdp_1.cdpSend)(this.page, 'Page.addScriptToEvaluateOnNewDocument', {
+                source: (0, stealth_1.buildStealthScript)(),
+            });
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            await (0, cdp_1.evaluateJs)(this.page, (0, stealth_1.buildStealthScript)());
+        }
+        catch {
+            /* document may be mid-navigation */
+        }
+    }
     /** The test-account label this window is tagged for (2026-11). */
     get actor() {
         return this._actor;
@@ -187,6 +239,8 @@ class BrowserSession {
             this.setActor(opts.actor);
         if (opts.chromeArgs)
             this._chromeArgs = opts.chromeArgs;
+        if (opts.stealth !== undefined)
+            this._stealth = opts.stealth === true;
         if (opts.allowCredentials !== undefined) {
             this._allowCredentials = opts.allowCredentials;
         }
@@ -276,6 +330,7 @@ class BrowserSession {
                     headless: this._headless,
                     userDataDir: this._profileDir,
                     args: this._chromeArgs,
+                    stealth: this._stealth,
                     // WE launched it, so WE may close it (browser_close / the idle
                     // sweep). Without this the instance would be unkillable by design.
                     surviveStop: false,
@@ -366,6 +421,24 @@ class BrowserSession {
         catch {
             /* older Chrome may refuse; the immediate injection still runs */
         }
+        if (this._stealth) {
+            // Must be registered for FUTURE documents (before any page script) and
+            // injected now for the document that was already loading.
+            try {
+                await (0, cdp_1.cdpSend)(page, 'Page.addScriptToEvaluateOnNewDocument', {
+                    source: (0, stealth_1.buildStealthScript)(),
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+            try {
+                await (0, cdp_1.evaluateJs)(page, (0, stealth_1.buildStealthScript)());
+            }
+            catch {
+                /* document not ready yet; the new-document script covers it */
+            }
+        }
         const install = async () => {
             try {
                 await (0, cdp_1.evaluateJs)(page, (0, page_events_1.buildPageEventScript)());
@@ -719,9 +792,96 @@ class BrowserSession {
             stoppedBecause,
         };
     }
-    async navigate(url) {
+    async navigate(url, opts) {
+        this.ensureConnected();
+        const info = await (0, cdp_1.navigateTo)(this.page, url);
+        const host = hostOf(url);
+        // A host that already failed its one bounded attempt is not re-attempted:
+        // report the previous verdict (cooldown) instead of burning the run.
+        if (this._challengeCooldown &&
+            Date.now() < this._challengeCooldown.until &&
+            this._challengeCooldown.host === host) {
+            const now = await this.detectChallenge();
+            if (!now) {
+                this._challengeCooldown = null;
+                return info;
+            }
+            return {
+                ...info,
+                challenge: {
+                    ...this._challengeCooldown.state,
+                    challenge: now,
+                    attempted: false,
+                    passed: false,
+                    cooldown: true,
+                    nextStep: now.kind === 'block' ? 'report_blocked' : 'ask_human',
+                },
+            };
+        }
+        // Give a client-rendered challenge a moment to mount before probing; a
+        // challenge script usually replaces the document right after load.
+        await (0, browse_types_1.sleep)(350);
+        const challenge = await this.resolveChallenge({
+            attempt: opts?.autoChallenge !== false,
+            timeoutMs: opts?.challengeTimeoutMs,
+        });
+        if (challenge.detected) {
+            if (challenge.passed) {
+                if (this._challengeCooldown?.host === host) {
+                    this._challengeCooldown = null;
+                }
+            }
+            else {
+                this._challengeCooldown = {
+                    host,
+                    until: Date.now() + 10 * 60_000,
+                    state: challenge,
+                };
+            }
+            return { ...info, challenge };
+        }
+        return info;
+    }
+    /** Detect a Cloudflare / CAPTCHA challenge on the live page (cheap, safe). */
+    async detectChallenge() {
+        if (!this.page)
+            return null;
+        return (0, challenge_1.detectChallenge)(this.page);
+    }
+    /**
+     * One bounded challenge attempt (2026-10): a single click for a Turnstile
+     * widget, passive wait for a managed challenge, nothing for a block/image
+     * CAPTCHA. Callers stop and ask a human when `passed` is false.
+     */
+    async resolveChallenge(opts) {
+        this.ensureConnected();
+        const page = this.page;
+        return (0, challenge_1.resolveChallenge)({
+            detect: () => (0, challenge_1.detectChallenge)(page),
+            click: (x, y) => (0, cdp_1.clickAt)(page, x, y),
+            attempt: opts?.attempt !== false,
+            timeoutMs: opts?.timeoutMs,
+        });
+    }
+    /**
+     * Poll only (no click). Used after a human answered a `CHALLENGE_REQUIRED`
+     * pause: the human solved it in the visible window; this waits for the page
+     * to clear and returns the new screen.
+     */
+    async waitForChallenge(opts) {
         this.ensureConnected();
-        return (0, cdp_1.navigateTo)(this.page, url);
+        const page = this.page;
+        const result = await (0, challenge_1.resolveChallenge)({
+            detect: () => (0, challenge_1.detectChallenge)(page),
+            click: (x, y) => (0, cdp_1.clickAt)(page, x, y),
+            // Explicit first-try after a mid-flow challenge; false by default so a
+            // resume AFTER a human answer only polls.
+            attempt: opts?.attempt === true,
+            timeoutMs: opts?.timeoutMs,
+        });
+        if (result.passed)
+            this._challengeCooldown = null;
+        return result;
     }
     /**
      * Set the browser viewport before a design-verification screenshot