captchakraken 2.1.0

package/dist/solver.js

@@ -0,0 +1,1922 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptchaKrakenSolver = void 0;
+const cursory_ts_1 = require("cursory-ts");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const crypto_1 = require("crypto");
+const token_usage_1 = require("./token-usage");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+function getBundledCliRoot() {
+    // When installed from npm, this file is in `<pkgRoot>/dist` (compiled) or `<pkgRoot>/src` (dev).
+    // Published packages bundle the python engine at `<pkgRoot>/python` (copied in
+    // by scripts/copy-python.mjs at build time). In the source monorepo it instead
+    // lives at the sibling `../python`, so fall back to that for local dev/tests.
+    const bundled = path.resolve(__dirname, '..', 'python');
+    if (fs.existsSync(bundled))
+        return bundled;
+    return path.resolve(__dirname, '..', '..', 'python');
+}
+function getVenvPython(cliRoot) {
+    const venvDir = path.join(cliRoot, '.venv');
+    const candidates = [
+        path.join(venvDir, 'bin', 'python'),
+        path.join(venvDir, 'bin', 'python3'),
+        path.join(venvDir, 'Scripts', 'python.exe'),
+        path.join(venvDir, 'Scripts', 'python'),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+// Env for spawning the python CLI. Prepend the bundled `python/src` to
+// PYTHONPATH so `python -m captchakraken.cli` imports even when the postinstall
+// `pip install` was skipped or failed (best-effort bootstrap).
+function cliEnv(cliRoot) {
+    const srcDir = path.join(cliRoot, 'src');
+    const existing = process.env.PYTHONPATH;
+    return {
+        ...process.env,
+        PYTHONPATH: existing ? `${srcDir}${path.delimiter}${existing}` : srcDir,
+    };
+}
+const log = (message, ...args) => console.log(`[Solver] ${message}`, ...args);
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+class CaptchaKrakenSolver {
+    constructor(config = {}) {
+        this.imageCounter = 0; // Track images sent to CLI for debugging
+        this.sessionDebugDir = null;
+        // onStep instrumentation: monotonic step index + solve-start wall clock.
+        // Reset at the top of each solveImpl() so indices/elapsed are per-solve.
+        this.stepIndex = 0;
+        this.solveStartMs = 0;
+        // Dedicated dump dir for the reCAPTCHA 3x3 dynamic driver — frames + a JSONL
+        // state log so the click/fade/wait flow can be diagnosed offline. Always set
+        // (independent of CAPTCHA_DEBUG) so we capture the hard-to-reproduce timing.
+        this.gridDebugDir = null;
+        this.gridDebugSeq = 0;
+        // Persistent CV worker (`python -m captchakraken.cli serve`) — one long-lived process
+        // that answers find-grid / grid-cell-states polls over stdin/stdout, so the
+        // hot poll loops pay one ~0.4s interpreter+cv2 import ONCE instead of per poll.
+        this.cvWorker = null;
+        this.cvWorkerReady = null;
+        this.cvWorkerSeq = 0;
+        this.cvWorkerPending = new Map();
+        this.cvWorkerBuf = '';
+        // Per-solve cache of model responses keyed by (screenshot content hash +
+        // puzzle source + retry mode). If the page hasn't changed since we last asked
+        // the model about it, re-querying is wasted work — reuse the prior answer.
+        // Cleared at the top of each solve. See getSolution().
+        this.solutionCache = new Map();
+        this.config = config;
+        this.lastMousePosition = config.startingMousePosition ?? { x: 100, y: 100 };
+    }
+    async solve(page) {
+        try {
+            return await this.solveImpl(page);
+        }
+        finally {
+            // Always shut the persistent CV worker down when a solve ends (success,
+            // failure, or timeout) so we never leak a python process between solves.
+            this.teardownCvWorker();
+            this.cvWorkerReady = null;
+        }
+    }
+    async solveImpl(page) {
+        const maxSolveLoops = this.config.maxSolveLoops ?? 10;
+        const postSolveDelayMs = this.config.postSolveDelayMs ?? 1200;
+        const overallSolveTimeoutMs = this.config.overallSolveTimeoutMs ?? 120000;
+        const start = Date.now();
+        let cumulativeTokenUsage = [];
+        this.imageCounter = 0;
+        this.stepIndex = 0;
+        this.solveStartMs = start;
+        this.solutionCache.clear();
+        // Initialize session debug directory if debugging is enabled
+        if (process.env.CAPTCHA_DEBUG === '1') {
+            const cliRoot = this.config.repoPath ?? getBundledCliRoot();
+            const debugRunsDir = path.join(cliRoot, '..', 'debug_runs');
+            if (!fs.existsSync(debugRunsDir)) {
+                fs.mkdirSync(debugRunsDir, { recursive: true });
+            }
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+            this.sessionDebugDir = path.join(debugRunsDir, `solve_${timestamp}`);
+            fs.mkdirSync(this.sessionDebugDir, { recursive: true });
+            log(`Session debug directory: ${this.sessionDebugDir}`);
+        }
+        // Set to "missed-tiles" for the next iteration when we detect that the
+        // captcha vendor rejected our submission with an under-selection error
+        // (reCAPTCHA "Please select all matching images"). Used once, then
+        // cleared. If the error appears again after the retry, we abort —
+        // burning loops on a stuck model only delays the inevitable fail.
+        let pendingRetryMode = null;
+        let alreadyRetriedRecaptchaError = false;
+        // Track whether we've interacted with the captcha at least once. Before any
+        // interaction, a null detectCaptcha() means "not rendered yet", not "solved".
+        let hasInteracted = false;
+        // Bounded wait for an in-DOM-but-still-rendering widget (Stage 1).
+        let renderWaits = 0;
+        const MAX_RENDER_WAITS = 6;
+        for (let attempt = 1; attempt <= maxSolveLoops; attempt++) {
+            if (Date.now() - start > overallSolveTimeoutMs) {
+                throw new Error(`Captcha solve timed out after ${overallSolveTimeoutMs}ms (attempt ${attempt}/${maxSolveLoops}).`);
+            }
+            const captchaElement = await this.detectCaptcha(page);
+            if (!captchaElement) {
+                // Two-stage detection. detectCaptcha() returns null when there's no
+                // VISIBLE, unsolved widget — but that splits into two cases:
+                if (hasInteracted) {
+                    // We already clicked/solved something and now nothing actionable
+                    // remains → treat as solved.
+                    console.log('No supported captcha found (post-interaction); considering solved.');
+                    return {
+                        isSolved: true,
+                        finalMousePosition: this.lastMousePosition,
+                        tokenUsage: (0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage)
+                    };
+                }
+                // No interaction yet. Stage 1: is an interactive widget present in the
+                // DOM but simply not finished rendering?
+                if (await this.hasInteractiveWidgetInDom(page) && renderWaits < MAX_RENDER_WAITS) {
+                    renderWaits++;
+                    console.log(`Captcha widget present in DOM but not yet rendered; waiting `
+                        + `(${renderWaits}/${MAX_RENDER_WAITS}).`);
+                    await delay(800 + Math.random() * 300);
+                    continue;
+                }
+                // No interactive widget in the DOM (reCAPTCHA v3 / invisible, or an
+                // hCaptcha that only triggers on user action), or it never rendered.
+                // Fail fast rather than burning the whole loop budget.
+                throw new Error('No interactive captcha widget detected (likely reCAPTCHA v3 / '
+                    + 'invisible or a click-triggered challenge). Failing fast.');
+            }
+            console.log(`\n--- Captcha Solve Loop ${attempt}/${maxSolveLoops} ---`);
+            const retryModeThisLoop = pendingRetryMode;
+            pendingRetryMode = null;
+            let didInteract;
+            let tokenUsage;
+            try {
+                ({ didInteract, tokenUsage } = await this.solveSingle(page, captchaElement, attempt, retryModeThisLoop));
+            }
+            catch (e) {
+                // Stage 2: the widget rendered and we screenshotted it, but the CLI
+                // says the puzzle TYPE is unsupported (e.g. hCaptcha click/drag). This
+                // is a definitive verdict on a rendered frame — fail fast, don't retry.
+                if (e?.unsupported) {
+                    throw new Error('Cannot solve this kind of captcha — the rendered puzzle is not a '
+                        + 'supported grid or checkbox (likely an hCaptcha click/drag puzzle).');
+                }
+                throw e;
+            }
+            hasInteracted = hasInteracted || didInteract;
+            renderWaits = 0;
+            cumulativeTokenUsage.push(...tokenUsage);
+            // After acting, poll for the vendor's SOLVED signal (anchor checkbox
+            // checked / response token) for a short window before falling back to the
+            // normal re-detect. hCaptcha keeps the challenge iframe visible for a
+            // couple seconds while it verifies the final answer; without this, the
+            // loop re-entered the pipeline on that closing frame and burned ~18s
+            // (waitForHcaptchaChallengeImages timing out on a prompt-less frame).
+            // This ONLY early-returns on a definitive solved signal — it never
+            // re-solves, so it can't loop. If not solved in the window, the original
+            // detectCaptcha path below handles a genuine next round exactly as before.
+            const settleMs = didInteract
+                ? (this.config.postSolveOutcomeTimeoutMs ?? 2500)
+                : postSolveDelayMs + Math.random() * 300;
+            if (didInteract) {
+                const deadline = Date.now() + settleMs;
+                let solved = false;
+                while (Date.now() < deadline) {
+                    if (await this.isCaptchaSolved(page)) {
+                        solved = true;
+                        break;
+                    }
+                    // A fresh next round has rendered → stop waiting, go solve it now
+                    // (keeps multi-round solves fast instead of burning the full window).
+                    if (await this.isChallengeFreshlyRendered(page))
+                        break;
+                    await delay(200);
+                }
+                if (solved) {
+                    return {
+                        isSolved: true,
+                        finalMousePosition: this.lastMousePosition,
+                        tokenUsage: (0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage),
+                    };
+                }
+            }
+            else {
+                await delay(settleMs);
+            }
+            // Detect reCAPTCHA's under-selection error banner. If present, the
+            // vendor rejected our last submission because the model missed at
+            // least one matching tile. Set the retry flag for the next loop so
+            // the CLI augments the grid prompt with an explicit "you missed
+            // some" instruction. If we've already retried once and the error is
+            // STILL showing, bail — the model is stuck and the loop will just
+            // keep flipping between "done" and Verify until timeout.
+            const recaptchaUnderselect = await this.hasRecaptchaUnderselectError(page);
+            if (recaptchaUnderselect) {
+                if (alreadyRetriedRecaptchaError) {
+                    throw new Error('reCAPTCHA still showing the under-selection error after retry; '
+                        + 'aborting (model unable to identify the missed tile). Total usage: '
+                        + JSON.stringify((0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage)));
+                }
+                console.log('reCAPTCHA returned under-selection error; retrying with missed-tiles prompt.');
+                pendingRetryMode = 'missed-tiles';
+                alreadyRetriedRecaptchaError = true;
+            }
+            const after = await this.detectCaptcha(page);
+            if (!after) {
+                return {
+                    isSolved: true,
+                    finalMousePosition: this.lastMousePosition,
+                    tokenUsage: (0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage)
+                };
+            }
+            // If we didn't actually interact and captcha is still detected, don't spin forever.
+            if (!didInteract) {
+                throw new Error(`Captcha still detected but solver performed no interactions; aborting to avoid an infinite loop. Total usage: ${JSON.stringify((0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage))}`);
+            }
+        }
+        throw new Error(`Captcha still detected after ${maxSolveLoops} solve loops. Total usage: ${JSON.stringify((0, token_usage_1.aggregateTokenUsage)(cumulativeTokenUsage))}`);
+    }
+    /**
+     * Fire the optional onStep observer with a fresh screenshot of the captcha
+     * element. No-op (beyond a cheap early return) when no callback is set, so it
+     * stays off the critical path in normal runs. The emitted PNG is owned by the
+     * callback — we never delete it. Best-effort: a screenshot or callback error
+     * never fails the solve.
+     */
+    async emitStep(captchaElement, stage, label, puzzleSource, frameRole, attempt, meta) {
+        const cb = this.config.onStep;
+        if (!cb)
+            return;
+        this.stepIndex++;
+        let screenshotPath = path.join(os.tmpdir(), `step_${this.stepIndex}_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        try {
+            await captchaElement.screenshot({ path: screenshotPath });
+        }
+        catch {
+            screenshotPath = null;
+        }
+        try {
+            await cb({
+                index: this.stepIndex,
+                stage,
+                label,
+                screenshotPath,
+                puzzleSource,
+                frameRole,
+                attempt,
+                elapsedMs: this.solveStartMs ? Date.now() - this.solveStartMs : 0,
+                meta,
+            });
+        }
+        catch (e) {
+            log(`onStep callback threw (ignored): ${e?.message ?? e}`);
+        }
+    }
+    async solveSingle(page, captchaElement, attempt, retryMode = null) {
+        // Vendor hint helps the CLI route to the right pipeline (hCaptcha click
+        // puzzles must never go through grid detection — find_grid false-positives
+        // on the header+footer bands).
+        const src = await captchaElement.getAttribute('src').catch(() => null);
+        const puzzleSource = src && src.includes('hcaptcha.com')
+            ? 'hcaptcha'
+            : src && src.includes('recaptcha/api2')
+                ? 'recaptcha'
+                : 'unknown';
+        // Distinguish the anchor "I'm not a robot" checkbox from the open image
+        // challenge so recorders can drop the (useless) pre-challenge checkbox
+        // screenshots and keep only the real puzzle. reCAPTCHA: anchor = api2/anchor,
+        // challenge = api2/bframe. hCaptcha: anchor = frame=checkbox, challenge =
+        // frame=challenge. (Note puzzleSource alone can't tell hCaptcha's checkbox
+        // from its challenge — both srcs contain hcaptcha.com.)
+        const frameRole = !src ? 'unknown'
+            : src.includes('recaptcha/api2/bframe') || src.includes('frame=challenge')
+                ? 'challenge'
+                : src.includes('recaptcha/api2/anchor') || src.includes('frame=checkbox')
+                    ? 'checkbox'
+                    : 'unknown';
+        // hCaptcha swaps the challenge images in asynchronously — the iframe is
+        // "visible" the instant the frame opens, but the task tiles paint a beat
+        // later. Screenshotting that gap captures a blank/partial grid, which the
+        // CLI then classifies as an unsupported puzzle and fails fast. Block until
+        // the tiles have actually loaded before grabbing the frame.
+        if (puzzleSource === 'hcaptcha' && src && src.includes('frame=challenge')) {
+            await this.waitForHcaptchaChallengeImages(captchaElement);
+        }
+        // Only the image-challenge frame (bframe) holds a grid. The anchor checkbox
+        // (api2/anchor) has none — running the grid settle/detect on it just wastes
+        // an 8s timeout + a find-grid subprocess before the checkbox click. Gate the
+        // grid handling to the bframe.
+        const isRecaptchaChallenge = puzzleSource === 'recaptcha'
+            && !!src && src.includes('recaptcha/api2/bframe');
+        // reCAPTCHA fades new tiles in over ~1s (initial load and the in-place
+        // dynamic refresh after a click). Screenshotting mid-fade feeds the LoRA a
+        // blank/partial grid. Poll until the grid's cells have settled before
+        // grabbing the frame. Best-effort — falls through on timeout. The in-place
+        // refresh re-enters solveSingle each loop, so this guard covers it too.
+        // True only for a one-shot reCAPTCHA grid (4x4): click all matching tiles,
+        // then submit in the same pass — these never blank/fade, so there's no
+        // dynamic-refresh loop to run.
+        let isRecaptchaOneShotGrid = false;
+        // Grid size the solver establishes for this challenge, surfaced in the
+        // baseline step's meta so callers (e.g. the demo recorder) can bucket
+        // reCAPTCHA attempts into 3x3 vs 4x4 without scraping debug logs.
+        let establishedGridSize = null;
+        if (isRecaptchaChallenge) {
+            await this.waitForGridCellsLoaded(captchaElement);
+            // 3x3 reCAPTCHA puzzles refresh tiles in place (blank/fade → new image),
+            // so they need the multi-round driver: click → hover/wait for fades →
+            // re-solve, submitting only when the CLI says `done`. 4x4 puzzles only ever
+            // return `checked` (no in-place refresh) and are one-shot like hCaptcha.
+            // Falls through if the grid can't be established.
+            const grid = await this.getGridBoxes(captchaElement);
+            if (grid && grid.size === 3) {
+                establishedGridSize = 3;
+                const elementBox = await captchaElement.boundingBox();
+                if (elementBox) {
+                    return this.solveRecaptchaGrid(page, captchaElement, attempt, retryMode, grid, elementBox);
+                }
+            }
+            else if (grid && grid.size === 4) {
+                establishedGridSize = 4;
+                isRecaptchaOneShotGrid = true;
+            }
+        }
+        // 1. Take Screenshot
+        const screenshotPath = path.join(os.tmpdir(), `captcha_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        await captchaElement.screenshot({ path: screenshotPath });
+        // Save image to debug directory if debugging is enabled
+        this.saveImageForDebug(screenshotPath);
+        // Baseline screenshot before any action is taken. Emitted once per solve
+        // (the first time we reach a one-shot/checkbox screenshot); later loops are
+        // covered by the post-action 'submit'/'round' steps.
+        if (this.stepIndex === 0) {
+            await this.emitStep(captchaElement, 'initial', 'initial (pre-action)', puzzleSource, frameRole, attempt, establishedGridSize ? { gridSize: establishedGridSize } : undefined);
+        }
+        let performedAction = false;
+        let allTokenUsage = [];
+        try {
+            // 2. Call CLI — while the model generates (the main idle window), drift
+            //    the cursor over the challenge like a human weighing the options,
+            //    instead of freezing it in place.
+            const response = await this.withIdleWander(page, captchaElement, () => this.getSolution(screenshotPath, puzzleSource, retryMode));
+            const actions = response.actions;
+            allTokenUsage = response.token_usage;
+            // Archive debug artifacts if enabled
+            this.archiveLatestDebugRun(attempt, actions);
+            // 3. Execute Actions
+            const actionList = Array.isArray(actions) ? actions : [actions];
+            // We need the element's bounding box to translate coordinates
+            const elementBox = await captchaElement.boundingBox();
+            if (!elementBox) {
+                throw new Error('Could not get bounding box of captcha element');
+            }
+            console.log(`Executing ${actionList.length} actions.`);
+            const frame = await captchaElement.contentFrame();
+            let verifyButton = null;
+            for (const action of actionList) {
+                if (action.action === 'click') {
+                    const c = action;
+                    // v2 emits `target_bounding_boxes` (plural). v1 fields kept as fallbacks.
+                    const bboxes = c.target_bounding_boxes
+                        ?? (c.target_bounding_box ? [c.target_bounding_box] : []);
+                    if (!bboxes.length && !c.target_coordinates) {
+                        console.warn('Click action has no bboxes or coordinates', c);
+                        continue;
+                    }
+                    if (bboxes.length) {
+                        for (const bbox of bboxes) {
+                            await this.executeClick(page, captchaElement, { ...c, target_bounding_box: bbox }, elementBox);
+                            await delay(Math.random() * 80 + 80);
+                        }
+                    }
+                    else {
+                        await this.executeClick(page, captchaElement, c, elementBox);
+                    }
+                    performedAction = true;
+                    await this.emitStep(captchaElement, 'click', `clicked ${bboxes.length || 1} target(s)`, puzzleSource, frameRole, attempt, { bboxes });
+                }
+                else if (action.action === 'drag') {
+                    await this.executeDrag(page, captchaElement, action, elementBox);
+                    performedAction = true;
+                    await this.emitStep(captchaElement, 'drag', 'drag', puzzleSource, frameRole, attempt, { action });
+                }
+                else if (action.action === 'wait') {
+                    if (action.duration_ms > 0) {
+                        console.log(`Waiting for ${action.duration_ms}ms as requested by CLI`);
+                        await delay(action.duration_ms);
+                        performedAction = true;
+                        await this.emitStep(captchaElement, 'wait', `waited ${action.duration_ms}ms`, puzzleSource, frameRole, attempt, { action });
+                    }
+                }
+                if (frame) {
+                    verifyButton = await this.getVerifyButton(frame);
+                    if (verifyButton) {
+                        await this.move(page, verifyButton);
+                    }
+                }
+                // 'done' actions intentionally fall through to the Verify-button block below.
+            }
+            // Submit policy:
+            //   - hCaptcha: every puzzle is one-shot. Tiles don't refresh in place;
+            //     we must click Verify after our selection to submit and advance.
+            //   - reCAPTCHA 4x4: one-shot too — never blanks/fades — so submit right
+            //     after clicking. (3x3 is dynamic and never reaches this path; it's
+            //     handled by solveRecaptchaGrid above.)
+            //   - Otherwise (no action / 'done'): submit to advance.
+            const shouldClickSubmit = !performedAction
+                || puzzleSource === 'hcaptcha'
+                || isRecaptchaOneShotGrid;
+            if (shouldClickSubmit && frame && verifyButton) {
+                console.log(performedAction
+                    ? `Actions executed; clicking Verify to submit (${puzzleSource}).`
+                    : 'No active actions performed (empty or done). Checking for Verify/Next button...');
+                await this.moveAndClick(page, verifyButton);
+                await this.emitStep(captchaElement, 'submit', 'submitted (Verify/Next)', puzzleSource, frameRole, attempt);
+            }
+        }
+        finally {
+            // Cleanup
+            if (fs.existsSync(screenshotPath)) {
+                fs.unlinkSync(screenshotPath);
+            }
+        }
+        return { didInteract: performedAction, tokenUsage: allTokenUsage };
+    }
+    async getVerifyButton(frame) {
+        let submitted = false;
+        // 1. Try generic button selectors by text
+        const buttonTexts = ['Verify', 'Next', 'Submit', 'Skip'];
+        for (const text of buttonTexts) {
+            try {
+                // Case-insensitive contains for text
+                const btn = await frame.$(`xpath=//button[contains(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), '${text.toLowerCase()}')] | //div[@role="button" and contains(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), '${text.toLowerCase()}')]`);
+                if (btn && await btn.isVisible()) {
+                    return btn;
+                }
+            }
+            catch (e) {
+                // Ignore locator errors
+            }
+        }
+        if (!submitted) {
+            // 2. Try specific ID (Recaptcha)
+            const recaptchaVerify = await frame.$('#recaptcha-verify-button');
+            if (recaptchaVerify && await recaptchaVerify.isVisible()) {
+                return recaptchaVerify;
+            }
+        }
+        if (!submitted) {
+            // 3. Try specific class (hCaptcha)
+            const hcaptchaVerify = await frame.$('.button-submit');
+            if (hcaptchaVerify && await hcaptchaVerify.isVisible()) {
+                return hcaptchaVerify;
+            }
+        }
+        return null;
+    }
+    async hasNonEmptyFieldValue(page, selector) {
+        try {
+            const el = await page.$(selector);
+            if (!el)
+                return false;
+            const value = await page.$eval(selector, node => {
+                const anyNode = node;
+                return typeof anyNode.value === 'string' ? anyNode.value : '';
+            });
+            return typeof value === 'string' && value.trim().length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Detect reCAPTCHA's "Please select all matching images" error banner
+     * (and the related "Please try again" / "Please also check the new images"
+     * variants). These appear in the bframe AFTER clicking Verify with an
+     * incomplete selection. The tiles do NOT refresh on this error — without
+     * special handling the LoRA sees the same image, returns "done" (because
+     * to it everything matching IS selected), we click Verify again, and we
+     * loop until the session times out. We use this signal to switch the next
+     * grid call into "missed-tiles" retry mode.
+     */
+    async hasRecaptchaUnderselectError(page) {
+        try {
+            const bframe = await page.$('iframe[src*="recaptcha/api2/bframe"]');
+            if (!bframe)
+                return false;
+            const frame = await bframe.contentFrame();
+            if (!frame)
+                return false;
+            // Three selector variants reCAPTCHA uses for the same family of errors.
+            const selectors = [
+                '.rc-imageselect-error-select-more',
+                '.rc-imageselect-error-dynamic-more',
+                '.rc-imageselect-incorrect-response',
+            ];
+            for (const sel of selectors) {
+                const el = await frame.$(sel);
+                if (el) {
+                    // reCAPTCHA toggles these elements between visible / hidden via
+                    // an `aria-hidden` attribute on a wrapper — checking isVisible()
+                    // alone misses cases where the element is in the layout tree but
+                    // currently being faded in. Treat presence + non-empty text as
+                    // enough.
+                    const visible = await el.isVisible().catch(() => false);
+                    const text = (await el.textContent().catch(() => null)) ?? '';
+                    if (visible && text.trim().length > 0)
+                        return true;
+                }
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isRecaptchaAnchorChecked(anchorIframe) {
+        try {
+            const frame = await anchorIframe.contentFrame();
+            if (!frame)
+                return false;
+            const checked = await frame.$('.recaptcha-checkbox-checked');
+            return !!(checked && await checked.isVisible());
+        }
+        catch {
+            return false;
+        }
+    }
+    async isHcaptchaAnchorChecked(anchorIframe) {
+        // hCaptcha's anchor sets <div id="checkbox" aria-checked="true"> when
+        // the puzzle has been solved. We use this as a solve signal because the
+        // h-captcha-response token isn't always populated on demo pages.
+        try {
+            const frame = await anchorIframe.contentFrame();
+            if (!frame)
+                return false;
+            const ariaChecked = await frame.$('#checkbox[aria-checked="true"]');
+            return !!(ariaChecked && await ariaChecked.isVisible());
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * True the moment the vendor reports the whole captcha solved — the anchor
+     * checkbox flipped to checked, or the response token got populated. This is a
+     * definitive "done" signal that a lingering, animating-closed challenge frame
+     * is not: after the final submit, hCaptcha keeps the challenge iframe VISIBLE
+     * for a couple of seconds while it verifies, so treating that frame as a fresh
+     * puzzle (the old behavior) burned ~18s re-running the pipeline on it.
+     */
+    async isCaptchaSolved(page) {
+        try {
+            const hc = await page.$('iframe[src*="hcaptcha"][src*="frame=checkbox"]');
+            if (hc && await hc.isVisible().catch(() => false)) {
+                if (await this.hasNonEmptyFieldValue(page, '[name="h-captcha-response"]'))
+                    return true;
+                if (await this.isHcaptchaAnchorChecked(hc))
+                    return true;
+            }
+            const rc = await page.$('iframe[src*="recaptcha/api2/anchor"]');
+            if (rc && await rc.isVisible().catch(() => false)) {
+                if (await this.hasNonEmptyFieldValue(page, '[name="g-recaptcha-response"]'))
+                    return true;
+                if (await this.isRecaptchaAnchorChecked(rc))
+                    return true;
+            }
+        }
+        catch { /* fall through */ }
+        return false;
+    }
+    /**
+     * True when an image challenge is open AND has actually rendered its prompt —
+     * i.e. a fresh round we should solve, as opposed to a frame animating closed
+     * (whose prompt has already gone). Used to tell "next round" from "solved,
+     * closing" after a submit without waiting out a fixed timeout.
+     */
+    async isChallengeFreshlyRendered(page) {
+        try {
+            const hc = await page.$('iframe[src*="hcaptcha"][src*="frame=challenge"]');
+            if (hc && await hc.isVisible().catch(() => false)) {
+                const frame = await hc.contentFrame();
+                const prompt = frame && await frame.$('.prompt-text');
+                if (prompt && await prompt.isVisible().catch(() => false)) {
+                    const text = (await prompt.textContent().catch(() => '')) ?? '';
+                    if (text.trim().length > 0)
+                        return true;
+                }
+            }
+            const rc = await page.$('iframe[src*="recaptcha/api2/bframe"]');
+            if (rc && await rc.isVisible().catch(() => false)) {
+                const frame = await rc.contentFrame();
+                const instr = frame && await frame.$('.rc-imageselect-instructions, #rc-imageselect');
+                if (instr && await instr.isVisible().catch(() => false))
+                    return true;
+            }
+        }
+        catch { /* fall through */ }
+        return false;
+    }
+    /**
+     * Block until the hCaptcha challenge frame's task images have actually
+     * painted, so we don't screenshot a blank/half-loaded grid.
+     *
+     * hCaptcha renders each grid tile as a `.task-image .image` div whose
+     * `background-image` is set once the asset loads; the prompt sits in
+     * `.prompt-text`. Image-select (click/drag) challenges use a single
+     * `.challenge-example` / `canvas` surface instead. We wait for either family
+     * to be present AND for the background-image URLs to be populated (not the
+     * empty `url("")` placeholder hCaptcha ships before the asset arrives).
+     *
+     * Best-effort: a timeout or a missing content frame just falls through to the
+     * screenshot rather than throwing — the existing fail-fast path still covers a
+     * genuinely unsupported puzzle.
+     */
+    async waitForHcaptchaChallengeImages(challengeIframe) {
+        try {
+            const frame = await challengeIframe.contentFrame();
+            if (!frame)
+                return;
+            // Prompt must be present and non-empty first — it's the cheapest signal
+            // that the challenge frame has rendered its content at all.
+            await frame.waitForSelector('.prompt-text', { state: 'visible', timeout: 8000 });
+            // Then wait for the actual imagery to load. Grid tiles expose a
+            // background-image; click/drag puzzles expose a canvas or example image.
+            await frame.waitForFunction(() => {
+                const tiles = Array.from(document.querySelectorAll('.task-image .image, .task .image'));
+                if (tiles.length > 0) {
+                    // Every visible tile must have a real background-image URL.
+                    return tiles.every((el) => {
+                        const bg = getComputedStyle(el).backgroundImage;
+                        return bg && bg !== 'none' && !/url\(["']?["']?\)/.test(bg);
+                    });
+                }
+                // Non-grid (click/drag) challenge: a painted canvas or loaded example img.
+                const canvas = document.querySelector('canvas');
+                if (canvas instanceof HTMLCanvasElement && canvas.width > 0 && canvas.height > 0) {
+                    return true;
+                }
+                const example = document.querySelector('.challenge-example img, .image-wrapper img');
+                return !!(example && example.complete && example.naturalWidth > 0);
+            }, { timeout: 8000 });
+        }
+        catch {
+            // Timed out or frame detached mid-load; fall through to the screenshot.
+        }
+    }
+    /**
+     * Stage-1 detection: is an *interactive* captcha widget present in the DOM at
+     * all — even if its iframe hasn't finished rendering yet?
+     *
+     * This is deliberately broader than detectCaptcha (which only returns a
+     * VISIBLE, not-yet-solved element). We use it to distinguish two cases that
+     * detectCaptcha() === null cannot tell apart:
+     *
+     *   - A reCAPTCHA-v2 / hCaptcha widget IS in the DOM but is still loading
+     *     (iframe present, glyph not painted) → we should WAIT for it.
+     *   - There is no interactive widget — reCAPTCHA v3 (score-based, invisible)
+     *     or an hCaptcha that only triggers on a user action → we must FAIL FAST.
+     *
+     * reCAPTCHA v3 injects only `iframe[src*="recaptcha/api2/anchor"]` with
+     * `size=invisible` in the src, and never an `api2/bframe` challenge frame, so
+     * we exclude the invisible variant here.
+     */
+    async hasInteractiveWidgetInDom(page) {
+        // reCAPTCHA v2 anchor, but NOT the invisible (v3 / invisible-v2) variant.
+        const recaptchaAnchors = await page.$$('iframe[src*="recaptcha/api2/anchor"]');
+        for (const a of recaptchaAnchors) {
+            const src = (await a.getAttribute('src')) ?? '';
+            if (!/[?&]size=invisible/.test(src))
+                return true;
+        }
+        // reCAPTCHA challenge frame present at all → definitely interactive.
+        if (await page.$('iframe[src*="recaptcha/api2/bframe"]'))
+            return true;
+        // hCaptcha checkbox or challenge frame present (visible or not yet).
+        if (await page.$('iframe[src*="hcaptcha"][src*="frame=checkbox"]'))
+            return true;
+        if (await page.$('iframe[src*="hcaptcha"][src*="frame=challenge"]'))
+            return true;
+        return false;
+    }
+    async detectCaptcha(page) {
+        // Prioritize open challenges (the grid/images) over the initial checkbox
+        // Recaptcha Challenge
+        const recaptchaChallenge = await page.$('iframe[src*="recaptcha/api2/bframe"]');
+        if (recaptchaChallenge && await recaptchaChallenge.isVisible())
+            return recaptchaChallenge;
+        // hCaptcha Challenge — match the `frame=challenge` URL fragment.
+        // The anchor iframe's title is "Widget containing checkbox for hCaptcha
+        // security challenge" so a title-based fallback would mis-classify it
+        // as the challenge frame. The URL fragment is unambiguous.
+        const hcaptchaChallenge = await page.$('iframe[src*="hcaptcha"][src*="frame=challenge"]');
+        if (hcaptchaChallenge && await hcaptchaChallenge.isVisible())
+            return hcaptchaChallenge;
+        // Recaptcha Checkbox
+        const recaptchaCheckbox = await page.$('iframe[src*="recaptcha/api2/anchor"]');
+        if (recaptchaCheckbox && await recaptchaCheckbox.isVisible()) {
+            // If it's already checked, consider it solved and continue searching.
+            const checked = await this.isRecaptchaAnchorChecked(recaptchaCheckbox);
+            if (!checked)
+                return recaptchaCheckbox;
+        }
+        // hCaptcha Checkbox (anchor) — match the `frame=checkbox` URL fragment.
+        const hcaptchaCheckbox = await page.$('iframe[src*="hcaptcha"][src*="frame=checkbox"]');
+        if (hcaptchaCheckbox && await hcaptchaCheckbox.isVisible()) {
+            // Solved if EITHER the h-captcha-response token is set OR the anchor
+            // has flipped to aria-checked="true". Demo pages don't always populate
+            // the token, so the visual state is the necessary tie-breaker.
+            const hasToken = await this.hasNonEmptyFieldValue(page, '[name="h-captcha-response"]');
+            const checked = await this.isHcaptchaAnchorChecked(hcaptchaCheckbox);
+            if (!hasToken && !checked)
+                return hcaptchaCheckbox;
+        }
+        // Cloudflare Turnstile
+        // Try iframe first (if visible/open)
+        const cloudflareIframe = await page.$('iframe[src*="challenges.cloudflare.com"]');
+        if (cloudflareIframe && await cloudflareIframe.isVisible()) {
+            const hasToken = await this.hasNonEmptyFieldValue(page, '[name="cf-turnstile-response"]');
+            if (!hasToken)
+                return cloudflareIframe;
+        }
+        // Fallback to container for closed shadow roots
+        const cloudflareContainer = await page.$('.cf-turnstile');
+        if (cloudflareContainer && await cloudflareContainer.isVisible()) {
+            const hasToken = await this.hasNonEmptyFieldValue(page, '[name="cf-turnstile-response"]');
+            if (!hasToken)
+                return cloudflareContainer;
+        }
+        return null;
+    }
+    /**
+     * Initialize a fresh dump directory for one reCAPTCHA 3x3 dynamic-driver
+     * session. Frames + a state.jsonl log land here so the click/fade/wait timing
+     * can be replayed offline. Gated on CAPTCHA_DEBUG=1 — the per-frame dumps and
+     * extra state queries add latency, so they stay off in normal runs. Set
+     * CAPTCHA_DEBUG=1 to capture them when diagnosing timing. Best-effort.
+     */
+    initGridDebug() {
+        if (process.env.CAPTCHA_DEBUG !== '1') {
+            this.gridDebugDir = null;
+            return;
+        }
+        try {
+            const cliRoot = this.config.repoPath ?? getBundledCliRoot();
+            const base = path.join(cliRoot, 'latestDebugRun_grid');
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+            this.gridDebugDir = path.join(base, `griddrv_${stamp}_${Math.floor(Math.random() * 1e6)}`);
+            this.gridDebugSeq = 0;
+            fs.mkdirSync(this.gridDebugDir, { recursive: true });
+            console.log(`[grid-debug] dumping driver frames + state to: ${this.gridDebugDir}`);
+        }
+        catch (e) {
+            this.gridDebugDir = null;
+            console.warn(`[grid-debug] could not init debug dir: ${e}`);
+        }
+    }
+    /**
+     * Log a structured event for the grid driver: prints a one-line summary to the
+     * console and appends a JSON record to state.jsonl. If `framePath` is given,
+     * copies that frame into the dump dir under a sequenced, labeled name so the
+     * record can be matched to the exact pixels the detector saw. Best-effort.
+     */
+    gridDebug(event, data = {}, framePath) {
+        // No-op unless grid debugging is active (CAPTCHA_DEBUG=1). Keeps the verbose
+        // per-poll trace + frame dumps off the hot path in normal runs.
+        if (!this.gridDebugDir)
+            return;
+        const seq = ++this.gridDebugSeq;
+        console.log(`[grid-debug #${seq}] ${event} ${JSON.stringify(data)}`);
+        try {
+            let savedFrame;
+            if (framePath && fs.existsSync(framePath)) {
+                savedFrame = `${String(seq).padStart(3, '0')}_${event}.png`;
+                fs.copyFileSync(framePath, path.join(this.gridDebugDir, savedFrame));
+            }
+            const record = { seq, t: new Date().toISOString(), event, ...data, frame: savedFrame };
+            fs.appendFileSync(path.join(this.gridDebugDir, 'state.jsonl'), JSON.stringify(record) + '\n');
+        }
+        catch {
+            // best-effort; never fail the solve over debug I/O
+        }
+    }
+    saveImageForDebug(imagePath) {
+        // Check if CAPTCHA_DEBUG is enabled
+        const debugEnabled = process.env.CAPTCHA_DEBUG === '1';
+        if (!debugEnabled) {
+            return;
+        }
+        try {
+            const cliRoot = this.config.repoPath ?? getBundledCliRoot();
+            // Save input images to a separate directory that won't be cleared by the Python CLI
+            // The Python CLI clears latestDebugRun, so we use a sibling directory
+            const inputImagesDir = path.join(cliRoot, 'latestDebugRun_inputs');
+            // Ensure input images directory exists
+            if (!fs.existsSync(inputImagesDir)) {
+                fs.mkdirSync(inputImagesDir, { recursive: true });
+            }
+            // Increment counter and save with a descriptive name
+            this.imageCounter++;
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+            const debugImageName = `input_${String(this.imageCounter).padStart(3, '0')}_${timestamp}.png`;
+            const debugImagePath = path.join(inputImagesDir, debugImageName);
+            // Copy the image to debug directory
+            fs.copyFileSync(imagePath, debugImagePath);
+            console.log(`[DEBUG] Saved input image to: ${debugImagePath}`);
+        }
+        catch (error) {
+            // Don't fail the solve if debug save fails
+            console.warn(`[DEBUG] Failed to save image for debugging: ${error}`);
+        }
+    }
+    archiveLatestDebugRun(attempt, actions) {
+        if (!this.sessionDebugDir)
+            return;
+        try {
+            const cliRoot = this.config.repoPath ?? getBundledCliRoot();
+            const latestDebugDir = path.join(cliRoot, 'latestDebugRun');
+            const inputImagesDir = path.join(cliRoot, 'latestDebugRun_inputs');
+            const attemptDir = path.join(this.sessionDebugDir, `attempt_${attempt}`);
+            fs.mkdirSync(attemptDir, { recursive: true });
+            // Archive CLI artifacts if they exist
+            if (fs.existsSync(latestDebugDir)) {
+                fs.cpSync(latestDebugDir, attemptDir, { recursive: true });
+                fs.rmSync(latestDebugDir, { recursive: true, force: true });
+            }
+            // Archive input images if they exist
+            if (fs.existsSync(inputImagesDir)) {
+                const archivedInputsDir = path.join(attemptDir, 'inputs');
+                fs.mkdirSync(archivedInputsDir, { recursive: true });
+                fs.cpSync(inputImagesDir, archivedInputsDir, { recursive: true });
+                fs.rmSync(inputImagesDir, { recursive: true, force: true });
+            }
+            // Add actions info to the attempt directory
+            fs.writeFileSync(path.join(attemptDir, 'actions_result.json'), JSON.stringify(actions, null, 2));
+            console.log(`[DEBUG] Archived attempt ${attempt} debug artifacts to: ${attemptDir}`);
+        }
+        catch (error) {
+            console.warn(`[DEBUG] Failed to archive debug artifacts: ${error}`);
+        }
+    }
+    /**
+     * Resolve the bundled CaptchaKraken CLI root and the python interpreter to
+     * run it with. Prefers the packaged venv python (postinstall bootstrap),
+     * falling back to the configured/`python` command. Throws if the CLI folder
+     * is missing — callers that must not throw (e.g. runCliTool) wrap this.
+     */
+    resolveCli() {
+        const { repoPath, pythonCommand = 'python' } = this.config;
+        const cliRoot = repoPath ?? getBundledCliRoot();
+        if (!fs.existsSync(cliRoot)) {
+            throw new Error(`CaptchaKraken CLI folder not found at ${cliRoot}. ` +
+                `If you installed from npm, ensure the package ships 'python/'.`);
+        }
+        const py = getVenvPython(cliRoot) ?? pythonCommand;
+        return { cliRoot, py };
+    }
+    /**
+     * Run an OpenCV tool subcommand of the CLI (e.g. `grid-cell-states a.png
+     * b.png`) and return its parsed single-line JSON. These subcommands print
+     * exactly one JSON object on stdout (timing records go to stderr), so we
+     * parse the whole trimmed stdout. Best-effort: returns `{}` on any failure so
+     * polling callers can treat it as "inconclusive, keep going" without throwing.
+     */
+    async runCliTool(args) {
+        try {
+            const { cliRoot, py } = this.resolveCli();
+            // Use execFile (no shell) so args containing JSON / brackets / spaces —
+            // e.g. the grid_boxes payload for grid-cell-states-fixed — are passed
+            // literally without any shell quoting/globbing hazards.
+            const { stdout } = await execFileAsync(py, ['-m', 'captchakraken.cli', ...args], {
+                cwd: cliRoot,
+                env: cliEnv(cliRoot),
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return JSON.parse(stdout.trim());
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Lazily start the persistent CV worker (`python -m captchakraken.cli serve`) and resolve
+     * once it has imported cv2/numpy and emitted its `{"ready":true}` handshake.
+     * Returns false if it can't be started (caller then falls back to one-shot
+     * subprocesses). Idempotent: subsequent calls await the same readiness promise.
+     */
+    ensureCvWorker() {
+        if (this.cvWorkerReady)
+            return this.cvWorkerReady;
+        this.cvWorkerReady = new Promise((resolve) => {
+            try {
+                const { cliRoot, py } = this.resolveCli();
+                const proc = (0, child_process_1.spawn)(py, ['-m', 'captchakraken.cli', 'serve'], { cwd: cliRoot, env: cliEnv(cliRoot) });
+                this.cvWorker = proc;
+                let settled = false;
+                const fail = () => {
+                    if (!settled) {
+                        settled = true;
+                        resolve(false);
+                    }
+                    this.teardownCvWorker();
+                };
+                proc.stdout.on('data', (chunk) => {
+                    this.cvWorkerBuf += chunk.toString();
+                    let nl;
+                    while ((nl = this.cvWorkerBuf.indexOf('\n')) >= 0) {
+                        const line = this.cvWorkerBuf.slice(0, nl).trim();
+                        this.cvWorkerBuf = this.cvWorkerBuf.slice(nl + 1);
+                        if (!line)
+                            continue;
+                        let msg;
+                        try {
+                            msg = JSON.parse(line);
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (!settled && msg.ready === true) {
+                            settled = true;
+                            resolve(true);
+                            continue;
+                        }
+                        if (typeof msg.id === 'number' && this.cvWorkerPending.has(msg.id)) {
+                            const p = this.cvWorkerPending.get(msg.id);
+                            this.cvWorkerPending.delete(msg.id);
+                            if (msg.ok)
+                                p.resolve(msg.result);
+                            else
+                                p.reject(new Error(msg.error || 'cv worker error'));
+                        }
+                    }
+                });
+                proc.on('error', fail);
+                proc.on('exit', () => {
+                    // Reject any in-flight requests so callers fall back rather than hang.
+                    for (const [, p] of this.cvWorkerPending)
+                        p.reject(new Error('cv worker exited'));
+                    this.cvWorkerPending.clear();
+                    fail();
+                });
+                // Bounded readiness wait — if imports stall, fall back to one-shot.
+                setTimeout(() => { if (!settled) {
+                    settled = true;
+                    resolve(false);
+                } }, 8000);
+            }
+            catch {
+                resolve(false);
+            }
+        });
+        return this.cvWorkerReady;
+    }
+    /** Send one request to the CV worker and await its JSON result. Throws on any
+     *  worker failure so callers can fall back to the one-shot path. */
+    cvWorkerRequest(payload, timeoutMs = 10000) {
+        const proc = this.cvWorker;
+        if (!proc || proc.exitCode !== null)
+            return Promise.reject(new Error('cv worker not running'));
+        const id = ++this.cvWorkerSeq;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.cvWorkerPending.delete(id))
+                    reject(new Error('cv worker request timeout'));
+            }, timeoutMs);
+            this.cvWorkerPending.set(id, {
+                resolve: (v) => { clearTimeout(timer); resolve(v); },
+                reject: (e) => { clearTimeout(timer); reject(e); },
+            });
+            try {
+                proc.stdin.write(JSON.stringify({ id, ...payload }) + '\n');
+            }
+            catch (e) {
+                this.cvWorkerPending.delete(id);
+                clearTimeout(timer);
+                reject(e);
+            }
+        });
+    }
+    /** Kill the worker and clear state. Safe to call repeatedly. */
+    teardownCvWorker() {
+        const proc = this.cvWorker;
+        this.cvWorker = null;
+        if (proc) {
+            try {
+                proc.kill();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    /**
+     * Run a CV tool through the persistent worker when available, falling back to a
+     * one-shot `runCliTool` subprocess otherwise. `cmd`/`payload` map to the
+     * worker's protocol; `fallbackArgs` is the equivalent one-shot argv. Worker
+     * results are wrapped to match the one-shot JSON shape:
+     *   - grid-cell-states[-fixed]: worker returns the states object directly, or
+     *     {grid:null}; the one-shot returns the same shape, so just pass through.
+     *   - find-grid: worker returns the array (or null) as `result`.
+     * Best-effort: never throws.
+     */
+    async runCvTool(cmd, payload, fallbackArgs) {
+        try {
+            if (await this.ensureCvWorker()) {
+                const result = await this.cvWorkerRequest({ cmd, ...payload });
+                return result;
+            }
+        }
+        catch {
+            // fall through to one-shot
+        }
+        return this.runCliTool(fallbackArgs);
+    }
+    /**
+     * Block until a reCAPTCHA grid's cells have settled — none blank, none
+     * mid-fade — before we screenshot it for the model. reCAPTCHA fades new tiles
+     * in over ~1s; capturing mid-fade feeds the LoRA a blank/partial grid.
+     *
+     * We poll: screenshot the challenge element, keep the last two frames, and ask
+     * the CLI's batched `grid-cell-states` (one subprocess per poll) which cells
+     * are empty/changing/loaded. We return as soon as every cell is loaded, or on
+     * timeout. Best-effort, mirroring `waitForHcaptchaChallengeImages`: never
+     * throws, and falls through on timeout so a stuck/odd grid still proceeds to
+     * the normal screenshot path. Temp frames are always cleaned up.
+     */
+    async waitForGridCellsLoaded(captchaElement, opts) {
+        const interval = opts?.intervalMs ?? this.config.gridLoadPollIntervalMs ?? 250;
+        const timeout = opts?.timeoutMs ?? this.config.gridLoadTimeoutMs ?? 8000;
+        const start = Date.now();
+        const frames = [];
+        const tmp = () => path.join(os.tmpdir(), `gridpoll_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        try {
+            while (Date.now() - start < timeout) {
+                const f = tmp();
+                await captchaElement.screenshot({ path: f });
+                frames.push(f);
+                if (frames.length >= 2) {
+                    const a = frames[frames.length - 2];
+                    const b = frames[frames.length - 1];
+                    const res = await this.runCvTool('grid-cell-states', { a, b }, ['grid-cell-states', a, b]);
+                    // `{grid: null}` => grid not painted yet; keep polling. A real grid
+                    // result with no empty/changing cells and >=1 loaded cell => settled.
+                    const gridFound = res && res.grid !== null && Array.isArray(res.loaded);
+                    if (gridFound
+                        && Array.isArray(res.empty) && res.empty.length === 0
+                        && Array.isArray(res.changing) && res.changing.length === 0
+                        && res.loaded.length > 0) {
+                        return true;
+                    }
+                    // Drop the older frame so disk use stays bounded to one prior frame.
+                    const stale = frames.shift();
+                    if (stale && fs.existsSync(stale))
+                        fs.unlinkSync(stale);
+                }
+                await delay(interval);
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            for (const f of frames) {
+                if (fs.existsSync(f)) {
+                    try {
+                        fs.unlinkSync(f);
+                    }
+                    catch { /* best-effort cleanup */ }
+                }
+            }
+        }
+    }
+    /**
+     * Read a PNG's pixel dimensions from its IHDR chunk (bytes 16-23, big-endian).
+     * Avoids pulling in an image-size dependency. Returns null if the file isn't a
+     * readable PNG.
+     */
+    readPngDimensions(filePath) {
+        try {
+            const fd = fs.openSync(filePath, 'r');
+            try {
+                const buf = new Uint8Array(24);
+                const read = fs.readSync(fd, buf, 0, 24, 0);
+                if (read < 24)
+                    return null;
+                // PNG signature is 8 bytes; IHDR length+type is 8 more; then width/height
+                // as big-endian uint32s at byte offsets 16 and 20.
+                const isPng = buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47; // "PNG"
+                if (!isPng)
+                    return null;
+                const beU32 = (o) => (buf[o] << 24 | buf[o + 1] << 16 | buf[o + 2] << 8 | buf[o + 3]) >>> 0;
+                const width = beU32(16);
+                const height = beU32(20);
+                if (!width || !height)
+                    return null;
+                return { width, height };
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Detect the reCAPTCHA grid once for a puzzle session: screenshot the element,
+     * run `find-grid`, and read the screenshot's pixel dimensions. Grid boxes are
+     * pixel coords in SCREENSHOT space (not page CSS space). Returns null if no
+     * grid is detected. The geometry is stable across the in-place dynamic refresh
+     * (only tile images change), so callers cache the result for the session.
+     */
+    async getGridBoxes(captchaElement) {
+        const f = path.join(os.tmpdir(), `findgrid_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        try {
+            await captchaElement.screenshot({ path: f });
+            const res = await this.runCvTool('find-grid', { image: f }, ['find-grid', f]);
+            if (!Array.isArray(res) || (res.length !== 9 && res.length !== 16)) {
+                return null;
+            }
+            const dims = this.readPngDimensions(f);
+            if (!dims)
+                return null;
+            return {
+                boxes: res,
+                size: res.length === 16 ? 4 : 3,
+                screenshotW: dims.width,
+                screenshotH: dims.height,
+            };
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (fs.existsSync(f)) {
+                try {
+                    fs.unlinkSync(f);
+                }
+                catch { /* best-effort cleanup */ }
+            }
+        }
+    }
+    /**
+     * Map a model-returned normalized bbox (fractions of the element/screenshot)
+     * to a 1-indexed grid cell. Uses the bbox center, converts to screenshot
+     * pixels, and returns the cell whose pixel box contains it. Cell numbering is
+     * row-major (matches the CLI's find_grid output). Returns null if the center
+     * falls outside every cell (e.g. in a gutter) — callers click the raw bbox
+     * anyway and skip per-tile tracking.
+     */
+    bboxToCell(bbox, gridBoxes, screenshotW, screenshotH) {
+        const [x1, y1, x2, y2] = bbox;
+        const cx = ((x1 + x2) / 2) * screenshotW;
+        const cy = ((y1 + y2) / 2) * screenshotH;
+        for (let i = 0; i < gridBoxes.length; i++) {
+            const [bx1, by1, bx2, by2] = gridBoxes[i];
+            if (cx >= bx1 && cx <= bx2 && cy >= by1 && cy <= by2) {
+                return i + 1; // 1-indexed
+            }
+        }
+        return null;
+    }
+    /**
+     * Center of a 1-indexed grid cell in PAGE pixel space, for mouse moves.
+     * Converts the cached screenshot-pixel box to page coords via the session's
+     * scaleX/scaleY (screenshot px -> page px) and element origin.
+     */
+    cellCenterPage(cell, session) {
+        const [x1, y1, x2, y2] = session.gridBoxes[cell - 1];
+        const cxPx = (x1 + x2) / 2;
+        const cyPx = (y1 + y2) / 2;
+        return {
+            x: session.elementBox.x + cxPx * session.scaleX,
+            y: session.elementBox.y + cyPx * session.scaleY,
+        };
+    }
+    /** Smooth-move the mouse over one cell's center with intra-cell jitter. */
+    async hoverCell(page, session, cell) {
+        const cellWPage = (session.gridBoxes[0][2] - session.gridBoxes[0][0]) * session.scaleX;
+        const cellHPage = (session.gridBoxes[0][3] - session.gridBoxes[0][1]) * session.scaleY;
+        const center = this.cellCenterPage(cell, session);
+        const jitterX = (Math.random() - 0.5) * cellWPage * 0.4;
+        const jitterY = (Math.random() - 0.5) * cellHPage * 0.4;
+        await this.performSmoothMove(page, center.x + jitterX, center.y + jitterY);
+    }
+    /**
+     * Query per-cell grid state using the SESSION'S CACHED grid boxes via the
+     * `grid-cell-states-fixed` CLI command. This is critical: the dynamic refresh
+     * blanks tiles to near-white, which makes find_grid fail on that frame, so the
+     * self-detecting `grid-cell-states` would return {grid:null} mid-fade and a
+     * naive caller would misread that as "nothing loading / solved". Passing the
+     * cached boxes keeps empty/changing/selected correct even while tiles are
+     * blank. Returns null only on a genuine CLI failure. Best-effort.
+     */
+    async gridCellStates(session, frameA, frameB) {
+        const boxesJson = JSON.stringify(session.gridBoxes);
+        const res = await this.runCvTool('grid-cell-states-fixed', { a: frameA, b: frameB, grid_boxes: session.gridBoxes }, ['grid-cell-states-fixed', frameA, frameB, boxesJson]);
+        if (!res || !Array.isArray(res.empty))
+            return null;
+        return {
+            empty: res.empty ?? [],
+            changing: res.changing ?? [],
+            loaded: res.loaded ?? [],
+            selected: res.selected ?? [],
+        };
+    }
+    /** Order a loading set so `priority` cells (just-clicked) come first. */
+    orderByPriority(loading, priority) {
+        const set = new Set(loading);
+        const ordered = [];
+        for (const c of priority) {
+            if (set.has(c)) {
+                ordered.push(c);
+                set.delete(c);
+            }
+        }
+        for (const c of set)
+            ordered.push(c);
+        return ordered;
+    }
+    /**
+     * Detect whether any tiles are blank or fading, watching for the ONSET of the
+     * reCAPTCHA refresh over a short grace window. The blank/fade transition lags
+     * the click by a beat, so a single snapshot right after clicking misses it
+     * (the tile still shows its old image — not yet white, not yet changing). We
+     * poll consecutive frames and mark a cell loading if it is `empty` (≥97%
+     * near-white) OR `changing` (>2% pixels differ). HOVERS a clicked tile each
+     * poll so the mouse keeps moving (no unnatural pauses). Returns the loading
+     * cells (priority/clicked first) as soon as any appears, or [] if the whole
+     * window passes with nothing loading (→ solved). Logs every poll + frame.
+     */
+    async currentLoadingCells(page, captchaElement, session, priority = []) {
+        const grace = this.config.recaptchaFadeOnsetGraceMs ?? 4000;
+        const interval = this.config.recaptchaDynamicFadePollMs ?? 250;
+        const start = Date.now();
+        const frames = [];
+        const tmp = () => path.join(os.tmpdir(), `loadchk_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        // We care specifically about the tiles we just clicked (priority). reCAPTCHA
+        // holds them selected (old image visible) for ~1-3s, THEN blanks them to swap
+        // in a replacement. So we must watch the CLICKED cells across the whole grace
+        // window — the onset is delayed, not immediate.
+        const watch = priority.length ? priority : null; // null => watch all cells
+        this.gridDebug('fade-onset:start', { grace, priority, watching: watch ?? 'all' });
+        let hoverIdx = 0;
+        try {
+            const first = tmp();
+            await captchaElement.screenshot({ path: first });
+            frames.push(first);
+            this.gridDebug('fade-onset:baseline', {}, first);
+            let polls = 0;
+            while (Date.now() - start < grace) {
+                // Keep the mouse moving over a clicked tile during the wait, and enforce
+                // a minimum inter-frame gap so the change detector has a real diff (the
+                // worker query is near-instant, so without this polls could fire back-to-
+                // back on near-identical frames and miss a slow fade).
+                const iterStart = Date.now();
+                if (priority.length) {
+                    await this.hoverCell(page, session, priority[hoverIdx % priority.length]).catch(() => { });
+                    hoverIdx++;
+                }
+                const elapsed = Date.now() - iterStart;
+                if (elapsed < interval)
+                    await delay(interval - elapsed);
+                const f = tmp();
+                await captchaElement.screenshot({ path: f });
+                frames.push(f);
+                polls++;
+                const a = frames[frames.length - 2];
+                const b = frames[frames.length - 1];
+                const st = await this.gridCellStates(session, a, b);
+                // Restrict the loading signal to the cells we clicked (if known): a
+                // background tile changing is irrelevant; a clicked tile going blank/
+                // changing means the refresh has begun.
+                const inScope = (c) => !watch || watch.includes(c);
+                const emptyW = (st?.empty ?? []).filter(inScope);
+                const changingW = (st?.changing ?? []).filter(inScope);
+                this.gridDebug('fade-onset:poll', {
+                    poll: polls, elapsedMs: Date.now() - start,
+                    watchedEmpty: emptyW, watchedChanging: changingW,
+                    empty: st?.empty ?? null, changing: st?.changing ?? null,
+                    loaded: st?.loaded ?? null, selected: st?.selected ?? null,
+                }, b);
+                const loading = [...new Set([...emptyW, ...changingW])];
+                if (loading.length) {
+                    const ordered = this.orderByPriority(loading, priority);
+                    this.gridDebug('fade-onset:loading-detected', { loading: ordered, afterMs: Date.now() - start });
+                    return ordered;
+                }
+                const stale = frames.shift();
+                if (stale && fs.existsSync(stale))
+                    fs.unlinkSync(stale);
+            }
+            this.gridDebug('fade-onset:none', { afterMs: Date.now() - start, polls });
+            return [];
+        }
+        catch (e) {
+            this.gridDebug('fade-onset:error', { error: String(e) });
+            return [];
+        }
+        finally {
+            for (const f of frames) {
+                if (fs.existsSync(f)) {
+                    try {
+                        fs.unlinkSync(f);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+    }
+    /**
+     * After loading is detected, wait until at least one of the given blank/fading
+     * cells reaches the `loaded` state, HOVERING those cells (in order) the whole
+     * time so the mouse never sits still. Returns true once a tile loads, false on
+     * timeout (caller proceeds anyway). Uses the session's cached grid boxes so it
+     * works while tiles are blank. Logs every poll + frame.
+     */
+    async waitForAnyClickedTileLoaded(page, captchaElement, session, fadingCells) {
+        if (!fadingCells.length)
+            return true;
+        const interval = this.config.recaptchaDynamicFadePollMs ?? 250;
+        const timeout = this.config.recaptchaDynamicFadeWaitMs ?? 6000;
+        const hoverEnabled = this.config.recaptchaTileHoverEnabled ?? true;
+        const start = Date.now();
+        const frames = [];
+        const tmp = () => path.join(os.tmpdir(), `fadepoll_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+        this.gridDebug('wait-load:start', { fadingCells, timeout, interval });
+        let hoverIdx = 0;
+        let polls = 0;
+        try {
+            while (Date.now() - start < timeout) {
+                // Move over a fading tile each iteration — human waiting for the image.
+                // Always enforce a minimum inter-frame gap so the change detector has a
+                // real diff to work with even when the (now near-instant) worker query
+                // would otherwise let polls fire back-to-back.
+                const iterStart = Date.now();
+                if (hoverEnabled) {
+                    await this.hoverCell(page, session, fadingCells[hoverIdx % fadingCells.length]).catch(() => { });
+                    hoverIdx++;
+                }
+                const elapsed = Date.now() - iterStart;
+                if (elapsed < interval)
+                    await delay(interval - elapsed);
+                const f = tmp();
+                await captchaElement.screenshot({ path: f });
+                frames.push(f);
+                if (frames.length >= 2) {
+                    const a = frames[frames.length - 2];
+                    const b = frames[frames.length - 1];
+                    const st = await this.gridCellStates(session, a, b);
+                    polls++;
+                    const loadedNow = st ? fadingCells.filter(c => st.loaded.includes(c)) : [];
+                    this.gridDebug('wait-load:poll', {
+                        poll: polls, elapsedMs: Date.now() - start,
+                        empty: st?.empty ?? null, changing: st?.changing ?? null,
+                        loaded: st?.loaded ?? null, loadedTargets: loadedNow,
+                    }, b);
+                    if (loadedNow.length) {
+                        this.gridDebug('wait-load:loaded', { loadedNow, afterMs: Date.now() - start });
+                        return true;
+                    }
+                    const stale = frames.shift();
+                    if (stale && fs.existsSync(stale))
+                        fs.unlinkSync(stale);
+                }
+            }
+            this.gridDebug('wait-load:timeout', { afterMs: Date.now() - start, polls });
+            return false;
+        }
+        catch (e) {
+            this.gridDebug('wait-load:error', { error: String(e) });
+            return false;
+        }
+        finally {
+            for (const f of frames) {
+                if (fs.existsSync(f)) {
+                    try {
+                        fs.unlinkSync(f);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+    }
+    /**
+     * Multi-round driver for reCAPTCHA 3x3 dynamic puzzles ("click all X" where
+     * tiles refresh in place). One invocation = one puzzle session.
+     *
+     * The CLI is authoritative about WHAT to do — it runs the blue-badge detector,
+     * filters out already-selected and still-loading tiles, and returns one of:
+     *   - `click`: click these tiles (already filtered to fresh, ready tiles)
+     *   - `wait` : nothing to click yet, tiles are still loading — do NOT submit
+     *   - `done` : nothing matching remains — submit (click Verify)
+     *
+     * This driver owns the HUMAN-LIKE WAITING the CLI can't: after a click round,
+     * and on a `wait`, it hovers the just-clicked / currently blank+fading tiles
+     * (in click order) and waits for at least one to finish reloading before
+     * re-screenshotting and re-solving — so we don't burn a solver call on a grid
+     * that's still mid-fade. It submits only on `done`.
+     *
+     * Returns the same shape as solveSingle so the outer solve loop — including the
+     * under-selection retry and post-solve detectCaptcha — wraps it unchanged.
+     */
+    async solveRecaptchaGrid(page, captchaElement, attempt, retryMode, grid, elementBox) {
+        const maxRounds = this.config.recaptchaMaxDynamicRounds ?? 8;
+        const session = {
+            gridBoxes: grid.boxes,
+            elementBox,
+            scaleX: elementBox.width / grid.screenshotW,
+            scaleY: elementBox.height / grid.screenshotH,
+            screenshotW: grid.screenshotW,
+            screenshotH: grid.screenshotH,
+        };
+        const clickedOrder = [];
+        let performedAction = false;
+        let shouldSubmit = false;
+        const allTokenUsage = [];
+        let pendingRetry = retryMode;
+        this.initGridDebug();
+        this.gridDebug('session:init', {
+            attempt, retryMode, size: grid.size,
+            screenshotW: grid.screenshotW, screenshotH: grid.screenshotH,
+            scaleX: session.scaleX, scaleY: session.scaleY,
+            elementBox, gridBoxes: session.gridBoxes,
+        });
+        for (let round = 1; round <= maxRounds; round++) {
+            // 1. Settle and screenshot.
+            await this.waitForGridCellsLoaded(captchaElement);
+            const shotA = path.join(os.tmpdir(), `recap_${Date.now()}_${Math.floor(Math.random() * 1e9)}.png`);
+            await captchaElement.screenshot({ path: shotA });
+            this.saveImageForDebug(shotA);
+            // Per-round boundary snapshot for onStep observers. Round 1's snapshot is
+            // the baseline (pre-action) for the 3x3 dynamic path.
+            await this.emitStep(captchaElement, round === 1 ? 'initial' : 'round', `round-${round}:pre-solve`, 'recaptcha', 'challenge', attempt, { round });
+            // Log the grid state the model is about to see — diagnostic only, so we
+            // skip the extra state query unless grid debugging is active (keeps it off
+            // the critical path in normal runs).
+            if (this.gridDebugDir) {
+                const preState = await this.gridCellStates(session, shotA, shotA);
+                this.gridDebug(`round-${round}:pre-solve`, {
+                    round, pendingRetry,
+                    empty: preState?.empty ?? null, changing: preState?.changing ?? null,
+                    loaded: preState?.loaded ?? null, selected: preState?.selected ?? null,
+                    clickedOrder: [...clickedOrder],
+                }, shotA);
+            }
+            let action = null;
+            try {
+                // 2. Solve. The CLI returns a single action for grid puzzles.
+                const response = await this.getSolution(shotA, 'recaptcha', pendingRetry);
+                pendingRetry = null; // only the first round carries the inbound retry hint
+                this.archiveLatestDebugRun(attempt, response.actions);
+                allTokenUsage.push(...response.token_usage);
+                const actionList = Array.isArray(response.actions) ? response.actions : [response.actions];
+                action = actionList[0] ?? null;
+                this.gridDebug(`round-${round}:action`, { action });
+            }
+            finally {
+                if (fs.existsSync(shotA)) {
+                    try {
+                        fs.unlinkSync(shotA);
+                    }
+                    catch { /* best-effort cleanup */ }
+                }
+            }
+            // 3. Dispatch on the action type.
+            if (!action || action.action === 'done') {
+                // Nothing matching remains → submit.
+                console.log(`[recaptcha-grid] round ${round}: done; submitting.`);
+                this.gridDebug(`round-${round}:done`, {});
+                shouldSubmit = true;
+                break;
+            }
+            if (action.action === 'wait') {
+                // Tiles are still loading; the CLI explicitly told us NOT to submit.
+                // Find what's loading, hover it, and wait for at least one to settle.
+                console.log(`[recaptcha-grid] round ${round}: CLI says wait (${action.duration_ms ?? 0}ms).`);
+                const loadingCells = await this.currentLoadingCells(page, captchaElement, session, clickedOrder);
+                await this.waitForAnyClickedTileLoaded(page, captchaElement, session, loadingCells);
+                continue;
+            }
+            if (action.action === 'click') {
+                const c = action;
+                const bboxes = c.target_bounding_boxes
+                    ?? (c.target_bounding_box ? [c.target_bounding_box] : []);
+                if (!bboxes.length) {
+                    // Malformed click with no targets — treat as a soft wait so we don't
+                    // submit prematurely; re-solve next round.
+                    console.warn(`[recaptcha-grid] round ${round}: click action with no bboxes; re-solving.`);
+                    this.gridDebug(`round-${round}:click-no-bboxes`, {});
+                    await delay(500);
+                    continue;
+                }
+                // 4. Click the tiles in order, tracking cell numbers for hover ordering.
+                const clickedThisRound = [];
+                for (const bbox of bboxes) {
+                    const cell = this.bboxToCell(bbox, session.gridBoxes, session.screenshotW, session.screenshotH);
+                    await this.executeClick(page, captchaElement, { action: 'click', target_bounding_box: bbox }, elementBox);
+                    if (cell != null) {
+                        clickedOrder.push(cell);
+                        clickedThisRound.push(cell);
+                    }
+                    await delay(Math.random() * 80 + 80);
+                }
+                performedAction = true;
+                console.log(`[recaptcha-grid] round ${round}: clicked ${bboxes.length} tile(s) -> cells ${JSON.stringify(clickedThisRound)}.`);
+                this.gridDebug(`round-${round}:clicked`, { bboxes, clickedThisRound });
+                await this.emitStep(captchaElement, 'click', `round-${round}:clicked ${bboxes.length} tile(s)`, 'recaptcha', 'challenge', attempt, { round, clickedThisRound, bboxes });
+                // 5. The clicked tiles may go blank / fade out for a replacement
+                //    (dynamic puzzle), or they may just stay checked (the puzzle is
+                //    fully solved). reCAPTCHA's blank/fade transition lags the click, so
+                //    we watch a grace window (not a single instant-after snapshot).
+                const loadingCells = await this.currentLoadingCells(page, captchaElement, session, clickedThisRound);
+                if (!loadingCells.length) {
+                    // Nothing is loading/fading within the grace window → the model fully
+                    // solved it; submit immediately rather than burning another round.
+                    console.log(`[recaptcha-grid] round ${round}: no tiles loading after click; submitting.`);
+                    this.gridDebug(`round-${round}:no-loading-submit`, {});
+                    shouldSubmit = true;
+                    break;
+                }
+                // Tiles are reloading — wait (while hovering) for at least one to settle
+                // before re-solving, so we don't feed the model a mid-fade grid.
+                console.log(`[recaptcha-grid] round ${round}: tiles loading ${JSON.stringify(loadingCells)}; waiting.`);
+                await this.waitForAnyClickedTileLoaded(page, captchaElement, session, loadingCells);
+                continue;
+            }
+            // Unexpected action type for a grid (drag/type) — re-solve.
+            console.warn(`[recaptcha-grid] round ${round}: unexpected action '${action.action}'; re-solving.`);
+            this.gridDebug(`round-${round}:unexpected-action`, { action });
+        }
+        // Submit: click Verify if present (no-op if the grid is gone). Only when the
+        // CLI signalled `done` — never on a timeout/round-cap exit, which leaves the
+        // outer loop to re-detect and decide.
+        if (shouldSubmit) {
+            const frame = await captchaElement.contentFrame();
+            if (frame) {
+                const verifyButton = await this.getVerifyButton(frame);
+                if (verifyButton) {
+                    console.log('[recaptcha-grid] clicking Verify to submit.');
+                    await this.moveAndClick(page, verifyButton);
+                    await this.emitStep(captchaElement, 'submit', 'submitted (Verify)', 'recaptcha', 'challenge', attempt);
+                }
+            }
+        }
+        return { didInteract: performedAction, tokenUsage: allTokenUsage };
+    }
+    async getSolution(imagePath, puzzleSource = 'unknown', retryMode = null) {
+        // v2 ships a single provider: the JobHarvest vLLM server via the bundled
+        // CaptchaKraken CLI. The CLI's planner reads VLLM_BASE_URL and the bearer
+        // token (CAPTCHA_KRAKEN_API_KEY, falling back to VLLM_API_KEY) from the
+        // environment; we also forward the key explicitly as a CLI arg below so it
+        // works even when the subprocess doesn't inherit it.
+        const { 
+        // vLLM LoRA name. Defaults to the full-puzzle `captcha` adapter
+        // (JobHarvest/qwen3.5-9b-captcha-lora — solves grids AND click/drag/pixel
+        // puzzles). Override in code or via CAPTCHA_LORA_NAME (e.g. `captcha-grid`
+        // for the older grids-only adapter). Most users only set the endpoint URL
+        // and, for the hosted API, CAPTCHA_KRAKEN_API_KEY.
+        model = process.env.CAPTCHA_LORA_NAME ?? 'captcha', apiKey = process.env.CAPTCHA_KRAKEN_API_KEY ?? process.env.VLLM_API_KEY, } = this.config;
+        // Dedup: if we've already asked the model about a byte-identical screenshot
+        // under the same prompt (puzzle source + retry mode), the page hasn't
+        // changed and another vLLM call would be wasted work. Reuse the answer.
+        // The image bytes ARE the cache key — any real page change (tile refresh,
+        // new challenge, fade) alters pixels and misses the cache, so this never
+        // stales a genuinely-changed puzzle.
+        let cacheKey = null;
+        try {
+            const imgHash = (0, crypto_1.createHash)('sha1').update(fs.readFileSync(imagePath)).digest('hex');
+            cacheKey = `${imgHash}|${puzzleSource}|${retryMode ?? ''}`;
+            const cached = this.solutionCache.get(cacheKey);
+            if (cached) {
+                console.log('[dedup] identical screenshot already solved this session — skipping vLLM query.');
+                // Reuse the actions but drop the token usage (no new tokens were spent).
+                return { actions: cached.actions, token_usage: [] };
+            }
+        }
+        catch {
+            cacheKey = null; // hashing failed — fall through to a normal query
+        }
+        const { cliRoot, py } = this.resolveCli();
+        const cmdParts = [
+            py,
+            '-m',
+            'captchakraken.cli',
+            `"${imagePath}"`,
+            model,
+            'captchaKrakenApi',
+        ];
+        if (apiKey) {
+            cmdParts.push(apiKey);
+        }
+        // Always pass the vendor hint at the end as --puzzle-source=<vendor>; the
+        // CLI's argparse falls through to the flag form for unknown trailing args.
+        cmdParts.push(`--puzzle-source=${puzzleSource}`);
+        if (retryMode) {
+            cmdParts.push(`--retry-mode=${retryMode}`);
+        }
+        const command = cmdParts.join(' ');
+        console.log(`Executing CaptchaKraken CLI: ${command}`);
+        try {
+            const { stdout, stderr } = await execAsync(command, {
+                cwd: cliRoot,
+                env: cliEnv(cliRoot),
+                maxBuffer: 10 * 1024 * 1024 // Increase buffer for large outputs if needed
+            });
+            console.log('CaptchaKraken CLI stdout:', stdout);
+            if (stderr) {
+                console.error('CaptchaKraken CLI stderr:', stderr);
+            }
+            if (!stdout.trim()) {
+                throw new Error(`CLI returned empty output. Stderr: ${stderr}`);
+            }
+            try {
+                const lines = stdout.trim().split('\n');
+                let actions = [];
+                let tokenUsage = [];
+                for (const line of lines) {
+                    try {
+                        const parsed = JSON.parse(line);
+                        // Handle new format { actions: ..., token_usage: ... }
+                        if (parsed.actions !== undefined && parsed.token_usage !== undefined) {
+                            actions = parsed.actions;
+                            tokenUsage = parsed.token_usage;
+                            break;
+                        }
+                        // Fallback for old format or list of actions
+                        if (Array.isArray(parsed)) {
+                            actions = parsed;
+                        }
+                        else if (parsed.action && (parsed.target_bounding_box || parsed.target_coordinates || parsed.action === 'wait')) {
+                            actions = [parsed];
+                        }
+                    }
+                    catch (e) {
+                        // Not json or not relevant
+                    }
+                }
+                const response = { actions, token_usage: tokenUsage };
+                // Cache under the screenshot hash so a byte-identical re-query this
+                // session reuses this answer instead of hitting vLLM again.
+                if (cacheKey)
+                    this.solutionCache.set(cacheKey, response);
+                return response;
+            }
+            catch (parseError) {
+                throw new Error(`Failed to parse CLI output: ${stdout}\nStderr: ${stderr}`);
+            }
+        }
+        catch (error) {
+            // The CLI emits {"unsupported": true} (exit 2) when the current frame is
+            // neither a grid nor a checkbox — e.g. an hCaptcha click/drag puzzle.
+            // Surface that as a distinct error the solve loop can recognize and fail
+            // fast on (only the puzzle TYPE is unsupported; a not-yet-rendered widget
+            // is handled separately by DOM-presence waiting before we ever get here).
+            const stderr = error.stderr ?? '';
+            if (/"unsupported"\s*:\s*true/.test(stderr)) {
+                const e = new Error('UNSUPPORTED_CAPTCHA: Cannot solve this kind of captcha');
+                e.unsupported = true;
+                throw e;
+            }
+            console.error('Error executing CaptchaKraken CLI:', error);
+            if (error.stdout)
+                console.log('CLI stdout on error:', error.stdout);
+            if (error.stderr)
+                console.error('CLI stderr on error:', error.stderr);
+            throw new Error(`Failed to execute captcha solver CLI: ${error.message}`);
+        }
+    }
+    /**
+     * Run `fn` (typically the model query) while idly drifting the cursor over
+     * the captcha, so the mouse behaves like a human weighing the options instead
+     * of freezing during inference. Uses the same cursory-ts trajectories as real
+     * clicks; cancelled the instant `fn` resolves. Best-effort — any wander error
+     * is swallowed and never fails the solve. Disable via config.idleMouseWander.
+     */
+    async withIdleWander(page, element, fn) {
+        if (this.config.idleMouseWander === false)
+            return fn();
+        let box = null;
+        try {
+            box = await element.boundingBox();
+        }
+        catch {
+            box = null;
+        }
+        if (!box || box.width < 20 || box.height < 20)
+            return fn();
+        const b = box;
+        let stop = false;
+        const pad = 0.18; // keep drift inside the tile area, off the extreme edges
+        const wander = (async () => {
+            // brief pause before the first drift — don't lurch the instant we ask
+            await delay(120 + Math.random() * 180);
+            while (!stop) {
+                const tx = b.x + b.width * (pad + Math.random() * (1 - 2 * pad));
+                const ty = b.y + b.height * (pad + Math.random() * (1 - 2 * pad));
+                try {
+                    await this.performSmoothMove(page, tx, ty);
+                }
+                catch {
+                    break;
+                }
+                if (stop)
+                    break;
+                await delay(180 + Math.random() * 360); // human dwell between glances
+            }
+        })();
+        try {
+            return await fn();
+        }
+        finally {
+            stop = true;
+            await wander.catch(() => { });
+        }
+    }
+    // Simplified move function with smooth movement
+    async move(page, selectorOrElement, options = {}) {
+        let elem = null;
+        if (typeof selectorOrElement === 'string') {
+            elem = await page.waitForSelector(selectorOrElement, { state: 'visible', timeout: 10000 });
+        }
+        else {
+            elem = selectorOrElement;
+        }
+        if (!elem) {
+            throw new Error(`Element not found: ${selectorOrElement}`);
+        }
+        await elem.scrollIntoViewIfNeeded();
+        const box = await elem.boundingBox();
+        if (!box) {
+            throw new Error(`Element has no bounding box: ${selectorOrElement}`);
+        }
+        // Default padding 25% to stay well inside the element
+        const padding = (options.paddingPercentage || 25) / 100;
+        const padX = box.width * padding;
+        const padY = box.height * padding;
+        // Pick a random point within the padded area
+        const targetX = box.x + padX + Math.random() * (box.width - 2 * padX);
+        const targetY = box.y + padY + Math.random() * (box.height - 2 * padY);
+        await this.performSmoothMove(page, targetX, targetY);
+    }
+    async moveAndClick(page, element) {
+        await this.move(page, element);
+        await page.mouse.down();
+        await delay(Math.random() * 20 + 20);
+        await page.mouse.up();
+    }
+    async performSmoothMove(page, x, y) {
+        // Generate trajectory using cursory-ts with 60Hz frequency for better control
+        const [points, timings] = (0, cursory_ts_1.generate_trajectory)([this.lastMousePosition.x, this.lastMousePosition.y], [x, y], 60 // 60 points per second
+        );
+        const SPEED_MULTIPLIER = 1;
+        const vectors = [];
+        for (let i = 0; i < points.length; i++) {
+            vectors.push({
+                x: points[i][0],
+                y: points[i][1],
+                timestamp: timings[i] / SPEED_MULTIPLIER // timings are cumulative from start
+            });
+        }
+        await this.tracePath(page, vectors);
+    }
+    async tracePath(page, vectors) {
+        // Get viewport for clamping
+        let viewport = { width: 1920, height: 1080 };
+        try {
+            const vp = page.viewportSize();
+            if (vp)
+                viewport = vp;
+        }
+        catch (e) { }
+        const startTime = Date.now();
+        for (let i = 0; i < vectors.length; i++) {
+            const v = vectors[i];
+            try {
+                // Clamp coordinates to viewport
+                const clampedX = Math.max(0, Math.min(v.x, viewport.width));
+                const clampedY = Math.max(0, Math.min(v.y, viewport.height));
+                // Move mouse
+                await page.mouse.move(clampedX, clampedY);
+                // Update last position
+                this.lastMousePosition = { x: clampedX, y: clampedY };
+                // Calculate delay to match target timestamp
+                if (v.timestamp !== undefined) {
+                    const targetTime = startTime + v.timestamp;
+                    const now = Date.now();
+                    const delayMs = targetTime - now;
+                    if (delayMs > 0) {
+                        await delay(delayMs);
+                    }
+                }
+            }
+            catch (error) {
+                // Check if page closed or other fatal errors if needed, otherwise ignore
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('Target closed') || errorMessage.includes('Session closed')) {
+                    log('Warning: could not move mouse, page or session closed.');
+                    return;
+                }
+            }
+        }
+    }
+    async executeClick(page, element, action, elementBox) {
+        let relativeX;
+        let relativeY;
+        if (action.target_bounding_box) {
+            // Pick random point in padding
+            const [minX, minY, maxX, maxY] = action.target_bounding_box;
+            const pixelMinX = minX * elementBox.width;
+            const pixelMaxX = maxX * elementBox.width;
+            const pixelMinY = minY * elementBox.height;
+            const pixelMaxY = maxY * elementBox.height;
+            // Apply padding (10%)
+            const paddingX = (pixelMaxX - pixelMinX) * 0.1;
+            const paddingY = (pixelMaxY - pixelMinY) * 0.1;
+            const safeMinX = pixelMinX + paddingX;
+            const safeMaxX = pixelMaxX - paddingX;
+            const safeMinY = pixelMinY + paddingY;
+            const safeMaxY = pixelMaxY - paddingY;
+            // Random position
+            relativeX = safeMinX + Math.random() * (safeMaxX - safeMinX);
+            relativeY = safeMinY + Math.random() * (safeMaxY - safeMinY);
+        }
+        else if (action.target_coordinates) {
+            // [x, y] percentages
+            const [xPct, yPct] = action.target_coordinates;
+            relativeX = xPct * elementBox.width;
+            relativeY = yPct * elementBox.height;
+        }
+        else {
+            console.warn('Click action received without coordinates or bounding box', action);
+            return;
+        }
+        const absoluteX = elementBox.x + relativeX;
+        const absoluteY = elementBox.y + relativeY;
+        // Use the shared smooth move method
+        await this.performSmoothMove(page, absoluteX, absoluteY);
+        // Perform click
+        await page.mouse.down();
+        await page.waitForTimeout(Math.random() * 30 + 20); // Random hold duration
+        await page.mouse.up();
+    }
+    async executeDrag(page, _element, action, elementBox) {
+        const bboxCenter = (bbox) => {
+            const cx = elementBox.x + ((bbox[0] + bbox[2]) / 2) * elementBox.width;
+            const cy = elementBox.y + ((bbox[1] + bbox[3]) / 2) * elementBox.height;
+            return { x: cx, y: cy };
+        };
+        const src = bboxCenter(action.source_bounding_box);
+        const dst = bboxCenter(action.target_bounding_box);
+        await this.performSmoothMove(page, src.x, src.y);
+        await page.mouse.down();
+        await page.waitForTimeout(Math.random() * 50 + 50);
+        await this.performSmoothMove(page, dst.x, dst.y);
+        await page.waitForTimeout(Math.random() * 50 + 50);
+        await page.mouse.up();
+    }
+}
+exports.CaptchaKrakenSolver = CaptchaKrakenSolver;