captchakraken 2.8.0 → 2.9.0

package/dist/cli-invocation.d.ts

@@ -1,26 +1,24 @@
 /**
  * How the JS client hands a solve request to the bundled Python CLI.
  *
- * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
- * line was then echoed:
+ * Two rules govern this module, and both exist because the alternative is
+ * unsafe rather than merely untidy:
  *
- *   console.log(`Executing CaptchaKraken CLI: ${command}`);
- *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
- *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
+ *    Argv is world-readable on Linux — any local user can read
+ *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
+ *    printed alongside the command lands in CI logs and terminal scrollback.
+ *    An environment block is per-process and not world-readable.
  *
- * Two leaks from one mistake. Argv is world-readable on Linux — any local user
- * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
- * the key was additionally written to stdout, so it landed in CI logs, terminal
- * scrollback, and anything scraping driver output.
- *
- * Secrets go through the environment instead, which is per-process and not
- * world-readable, and the command is built as an ARGV ARRAY for `execFile`
- * rather than a joined string for a shell, so a path with a space or a quote
- * cannot reshape the command.
+ * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
+ *    for a shell, so a screenshot path containing a space or a quote cannot
+ *    reshape the command.
  */
 /** Env var the CLI reads the bearer token from. */
 export declare const API_KEY_ENV = "CAPTCHA_KRAKEN_API_KEY";
-/** Historical positional placeholder. The CLI still accepts the slot. */
+/** Env var carrying the re-ask level for a board the vendor already refused. */
+export declare const RESAMPLE_LEVEL_ENV = "CAPTCHA_RESAMPLE_LEVEL";
+/** Positional placeholder the CLI still accepts in this slot. */
 export declare const API_PROVIDER = "captchaKrakenApi";
 export interface SolveInvocation {
     imagePath: string;
@@ -37,7 +35,7 @@ export interface SolveInvocation {
  */
 export declare function buildSolveArgs(invocation: SolveInvocation): string[];
 /** Base env plus the credential, when there is one. */
-export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string): NodeJS.ProcessEnv;
+export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string, resampleLevel?: number): NodeJS.ProcessEnv;
 /**
  * A log line for a solve invocation, with any credential removed.
  *

package/dist/cli-invocation.js

@@ -2,31 +2,29 @@
 /**
  * How the JS client hands a solve request to the bundled Python CLI.
  *
- * The API key used to travel as a POSITIONAL ARGUMENT, and the whole command
- * line was then echoed:
+ * Two rules govern this module, and both exist because the alternative is
+ * unsafe rather than merely untidy:
  *
- *   console.log(`Executing CaptchaKraken CLI: ${command}`);
- *   // Executing CaptchaKraken CLI: python -m captchakraken.cli "shot.png" \
- *   //   captcha-v12 captchaKrakenApi b8978fa3392...  --puzzle-source=hcaptcha
+ * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
+ *    Argv is world-readable on Linux — any local user can read
+ *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
+ *    printed alongside the command lands in CI logs and terminal scrollback.
+ *    An environment block is per-process and not world-readable.
  *
- * Two leaks from one mistake. Argv is world-readable on Linux — any local user
- * can read `/proc/<pid>/cmdline` while the solve runs, and `ps` shows it — and
- * the key was additionally written to stdout, so it landed in CI logs, terminal
- * scrollback, and anything scraping driver output.
- *
- * Secrets go through the environment instead, which is per-process and not
- * world-readable, and the command is built as an ARGV ARRAY for `execFile`
- * rather than a joined string for a shell, so a path with a space or a quote
- * cannot reshape the command.
+ * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
+ *    for a shell, so a screenshot path containing a space or a quote cannot
+ *    reshape the command.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.API_PROVIDER = exports.API_KEY_ENV = void 0;
+exports.API_PROVIDER = exports.RESAMPLE_LEVEL_ENV = exports.API_KEY_ENV = void 0;
 exports.buildSolveArgs = buildSolveArgs;
 exports.solveEnv = solveEnv;
 exports.redactCommand = redactCommand;
 /** Env var the CLI reads the bearer token from. */
 exports.API_KEY_ENV = 'CAPTCHA_KRAKEN_API_KEY';
-/** Historical positional placeholder. The CLI still accepts the slot. */
+/** Env var carrying the re-ask level for a board the vendor already refused. */
+exports.RESAMPLE_LEVEL_ENV = 'CAPTCHA_RESAMPLE_LEVEL';
+/** Positional placeholder the CLI still accepts in this slot. */
 exports.API_PROVIDER = 'captchaKrakenApi';
 /**
  * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
@@ -53,10 +51,20 @@ function buildSolveArgs(invocation) {
     return args;
 }
 /** Base env plus the credential, when there is one. */
-function solveEnv(base, apiKey) {
-    if (!apiKey)
-        return base;
-    return { ...base, [exports.API_KEY_ENV]: apiKey };
+function solveEnv(base, apiKey, resampleLevel) {
+    const out = apiKey ? { ...base, [exports.API_KEY_ENV]: apiKey } : { ...base };
+    // How many times THIS board has already been read and refused. The CLI is a
+    // fresh process per round, so it cannot know; and without it a re-ask is the
+    // same greedy arithmetic on the same pixels and returns the same answer,
+    // which is the whole of the "same answer 3 times running" failure.
+    //
+    // The LEVEL travels, not the temperature: the schedule lives once, in
+    // `planner.RESAMPLE_TEMPERATURES`, so the two ports cannot drift apart on a
+    // number Tier 3 would then average.
+    if (resampleLevel && resampleLevel > 0) {
+        out[exports.RESAMPLE_LEVEL_ENV] = String(resampleLevel);
+    }
+    return out;
 }
 /**
  * A log line for a solve invocation, with any credential removed.

package/dist/humanize.d.ts

@@ -2,8 +2,8 @@
  * How the driver MOVES. One pluggable object per input device.
  *
  * The TypeScript side of `python/src/captchakraken/humanize.py`; the two are one
- * design in two languages, and `tests/test_humanizer_parity.py` in
- * CaptchaKrakenFinetune pins that the mode names and the pause vocabulary have
+ * design in two languages, and `the training repo's humanizer parity tests` in
+ * the training repo pins that the mode names and the pause vocabulary have
  * not drifted.
  *
  * Humanisation used to be wired straight into `solver.ts`: every gesture was a
@@ -19,7 +19,7 @@
  *     device farm, a model of their own users) was composing two of them. That
  *     is not hypothetical — camoufox's `humanize` juggler re-humanises every
  *     `mouse.move()` it is handed, and running both measured 82.1s against
- *     13.4s on one geetest_v4_slide solve, because each of the 60 trajectory
+ *     13.4s on one a GeeTest v4 slider solve, because each of the 60 trajectory
  *     points became its own humanised sub-trajectory.
  *   - a caller on their own infrastructure, against their own fixtures, is
  *     paying for texture nobody is measuring.

package/dist/humanize.js

@@ -3,8 +3,8 @@
  * How the driver MOVES. One pluggable object per input device.
  *
  * The TypeScript side of `python/src/captchakraken/humanize.py`; the two are one
- * design in two languages, and `tests/test_humanizer_parity.py` in
- * CaptchaKrakenFinetune pins that the mode names and the pause vocabulary have
+ * design in two languages, and `the training repo's humanizer parity tests` in
+ * the training repo pins that the mode names and the pause vocabulary have
  * not drifted.
  *
  * Humanisation used to be wired straight into `solver.ts`: every gesture was a
@@ -20,7 +20,7 @@
  *     device farm, a model of their own users) was composing two of them. That
  *     is not hypothetical — camoufox's `humanize` juggler re-humanises every
  *     `mouse.move()` it is handed, and running both measured 82.1s against
- *     13.4s on one geetest_v4_slide solve, because each of the 60 trajectory
+ *     13.4s on one a GeeTest v4 slider solve, because each of the 60 trajectory
  *     points became its own humanised sub-trajectory.
  *   - a caller on their own infrastructure, against their own fixtures, is
  *     paying for texture nobody is measuring.

package/dist/model-name.d.ts

@@ -9,7 +9,7 @@
  * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
  * `<pkgRoot>/src` (dev), and published packages bundle the 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`.
+ * the source development checkout it instead lives at the sibling `../python`.
  */
 export declare function getBundledCliRoot(): string;
 /**

package/dist/model-name.js

@@ -37,7 +37,7 @@ const node_path_1 = __importDefault(require("node:path"));
  * When installed from npm this file is in `<pkgRoot>/dist` (compiled) or
  * `<pkgRoot>/src` (dev), and published packages bundle the 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`.
+ * the source development checkout it instead lives at the sibling `../python`.
  */
 function getBundledCliRoot() {
     const bundled = node_path_1.default.resolve(__dirname, '..', 'python');

package/dist/solver.d.ts

@@ -10,10 +10,71 @@ import { CaptchaKrakenConfig, SolveResult } from './types';
  * can be pinned by a test — see no-progress.test.ts. The Python port keeps the
  * same pair on `PageSolverConfig`.
  */
+/**
+ * Does this answer need the widget's box to be performed?
+ *
+ * Only a coordinate-bearing action does. `done` means "nothing left to click"
+ * and is the answer a vendor that closes on success will be showing no widget
+ * for, so requiring a box for it fails the solve at the moment it succeeded.
+ *
+ * Written as an ALLOW-LIST of what needs nothing rather than a list of what
+ * does: a new coordinate action added later must default to needing the box,
+ * because that is the direction where being wrong throws instead of clicking
+ * nowhere.
+ */
+export declare function answerNeedsElementBox(actions: ReadonlyArray<{
+    action?: string;
+}>): boolean;
+/**
+ * Is this the challenge TRANSITIONING under us, rather than a dead puzzle?
+ *
+ * hCaptcha swaps in the next round while we hold the old iframe, so a
+ * screenshot on it fails "not visible" / "Timeout" / "not attached". GeeTest
+ * does the mirror image: it CLOSES the panel the moment it accepts an answer,
+ * so the widget we are holding loses its layout box between the screenshot and
+ * the click. Both are the widget moving on, and the answer to both is to
+ * re-detect on the next round rather than to fail the solve.
+ *
+ * The caller gates this on having ALREADY INTERACTED, which is what keeps it
+ * honest: a first-frame failure is a genuine problem and still surfaces.
+ *
+ * Measured 2026-09-07 on gt4.geetest.com — every live GeeTest attempt ended
+ * "Could not get bounding box of captcha element" on a panel the vendor had
+ * just accepted, and each was recorded as the model being wrong.
+ */
+export declare function isStaleHandleError(message: string): boolean;
 export declare const SOLVE_DEFAULTS: {
     readonly maxSolveLoops: 6;
     readonly overallSolveTimeoutMs: 45000;
+    /**
+     * How long to hold a click waiting for the screen the model answered about.
+     *
+     * 9000, not the 6000 it was. A GeeTest svg board dwells p50 1.5s / p75 2.0s /
+     * max 2.7s per screen, so a 3-screen cycle runs 4.5s median and 8.1s worst
+     * case — a 6s budget could not catch the worst case however well aimed, and
+     * gave up one screen short. Named here rather than left as a literal in two
+     * places because `video_budget_ms` is derived from it on both ports and the
+     * arithmetic has to agree.
+     */
+    readonly keyframeWaitTimeoutMs: 9000;
 };
+/**
+ * How long a keyframe burst may run before it is called HUNG.
+ *
+ * A hang detector, not a budget: the solve timeout is what bounds real time.
+ * This only has to notice a screenshot that never returns, so it is
+ * deliberately slack.
+ *
+ * Sized off the CEILING, because that is what sizes the loop — the burst plans
+ * `videoBurstMaxMs` worth of frames, not `videoBurstDurationMs` worth. Must
+ * match `burst_hang_deadline_ms` in the python port, which had this guard
+ * first and had it sized off the floor: a 120-frame burst got 17s, i.e. 141ms
+ * per frame against a 100ms interval, and a burst that simply ran to its
+ * ceiling killed the attempt.
+ */
+export declare function burstHangDeadlineMs(cfg: {
+    videoBurstMaxMs?: number;
+}): number;
 export declare class CaptchaKrakenSolver {
     private config;
     /** Extra ms this solve has been granted for a recording; see recordKeyframeBurst. */
@@ -38,9 +99,56 @@ export declare class CaptchaKrakenSolver {
     private cvWorkerBuf;
     private solutionCache;
     private repeatedAnswerSeen;
+    /**
+     * The ONE recording and the ONE answer for the animated challenge on screen.
+     *
+     * A cycling board needs a single inference and no more. The burst shows the
+     * model every screen; the answer names the cell AND the screen it is on
+     * (`frame` / `await_keyframe`); the gate then holds the click until that
+     * screen is back up. Nothing about that changes between rounds — the board
+     * keeps cycling through the same pictures with the same target — so asking
+     * again buys nothing and costs a burst plus a multi-image inference.
+     *
+     * It was asking again every round. Loops 3, 4 and 5 each re-recorded and
+     * re-inferred, which is what exhausted a 66s budget on a puzzle whose whole
+     * task is one click.
+     *
+     * Dropped when the gate reports it never saw the chosen screen: that means
+     * the widget is no longer the board this plan was made for, which is exactly
+     * when a fresh recording is warranted.
+     */
+    private animatedPlan;
     private keyframeMode;
+    /**
+     * How many distinct steady screens the current clip sits on; 0 if it is not
+     * that kind of clip. THE GATE KEYS ON THIS, NOT ON `keyframeMode`.
+     *
+     * `even` was being read as "no state recurs, do not wait". It does not mean
+     * that — it means the slicer could not PROVE recurrence, which for a board
+     * whose loop is longer than a 4s burst it never can. 32 of 60 real clips
+     * sliced `even` while sitting on 2-3 steady screens, so the gate was off on
+     * every real animated captcha and the driver clicked whichever screen was up.
+     */
+    private keyframeSteadyScreens;
+    /**
+     * When the current solve must be over, in `Date.now()` terms. 0 outside one.
+     *
+     * The budget used to be checked ONLY at the top of each solve loop, so any
+     * single round could overrun it without limit — and an animated round is the
+     * long one: a 4s burst of 40 element screenshots, a multi-image inference,
+     * then a gated click per target. Measured on GeeTest svg, 2026-09-07: rounds
+     * that re-recorded ran past a 66s budget to the harness's own 180s ceiling
+     * and were reported "hung, not slow", which is a message about the model for
+     * a driver that simply never looked at the clock.
+     *
+     * The Python port has always checked mid-wait (`_check_deadline`), so this
+     * was also a cross-port divergence on exactly the puzzles Tier 3 times.
+     */
+    private solveDeadlineAt;
     private lastAnswerSig;
     private noProgressRounds;
+    /** How far up planner.RESAMPLE_TEMPERATURES this BOARD has escalated. */
+    private resampleLevel;
     private state;
     private lastSubmitFrameHash;
     private solveSessionId;
@@ -117,16 +225,37 @@ export declare class CaptchaKrakenSolver {
     private getVerifyButton;
     private hasNonEmptyFieldValue;
     /**
-     * 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.
+     * WHICH of reCAPTCHA's three bframe banners is showing, if any.
+     *
+     * They share a corner and a look and they mean different things:
+     *
+     *   `rejected`      "Please try again."  The answer was wrong; a fresh board
+     *                   follows, so the useful response is to solve that one.
+     *   `select-more`   "Please select all matching images."  Under-selected, and
+     *                   the tiles do NOT refresh — so a driver that re-submits
+     *                   the same answer loops until the session times out. This
+     *                   is the one the missed-tiles retry and the abort exist for.
+     *   `dynamic-more`  "Please also check the new images."  NOT AN ERROR. It is
+     *                   the dynamic 3x3's normal flow: cleared tiles fade out,
+     *                   replacements fade in, and the widget says so — on
+     *                   essentially every round of that variant.
+     *
+     * This used to return a boolean over all three, which made the third one
+     * indistinguishable from the first two and armed the one-retry abort with the
+     * sentence that means "you are doing fine". Every dynamic board therefore
+     * died at round two while the vendor was still dealing. Measured 2026-09-06:
+     * three of three `recaptcha_3x3_fade` attempts stopped at exactly boards=2,
+     * against `recaptcha_4x4` passing at 2, 3 and 5 boards on the same run.
+     */
+    /**
+     * May a repeat of this banner end the solve?
+     *
+     * Only for the banners where repeating means STUCK. `dynamic-more` repeating
+     * means the board is still being cleared, which is progress, and treating it
+     * as fatal is the bug this pair of methods was split to fix.
      */
-    private hasRecaptchaUnderselectError;
+    private bannerIsFatalAfterRetry;
+    private recaptchaBannerKind;
     private isRecaptchaAnchorChecked;
     private isHcaptchaAnchorChecked;
     /**
@@ -399,6 +528,28 @@ export declare class CaptchaKrakenSolver {
      * keyframes the wait gate re-reads on every poll live inside it.
      */
     private recordKeyframeBurst;
+    /**
+     * Start recording NOW, and let the caller decide later what it was for.
+     *
+     * This is what makes the speculative path possible. The burst is the only
+     * thing that can tell a cycling board from a still one, and it is also the
+     * recording that answers it — so it is started at the same moment the still
+     * screenshot goes to the model, and the two run together.
+     *
+     *   - the board never moves  -> `moved()` stays false, the still answer is
+     *     used, and the frames are thrown away. The recording cost nothing but
+     *     CPU, because it happened inside an inference we were already waiting
+     *     for.
+     *   - the board moves        -> the still answer is DISCARDED unread, the
+     *     burst runs on to the end of the cycle, and the multi-image answer is
+     *     the one acted on. Two inference CALLS, but only about one inference of
+     *     wall-clock, because the first ran during the recording.
+     *
+     * The old shape paid for that knowledge in whole ROUNDS: answer a still, act
+     * on it, notice nothing changed, answer another still, and only then record.
+     * ~15s of a 40s solve to learn something the first four frames already knew.
+     */
+    private startKeyframeBurst;
     /**
      * Slice a recorded burst into keyframes and solve them in ONE model request.
      *
@@ -434,8 +585,8 @@ export declare class CaptchaKrakenSolver {
      * one-way fade, a sprite crossing — so there is no state to come back to and
      * this can only run out its full 6s, PER CLICK, before clicking the
      * coordinates it already had. It is also the normal case, not a corner: all
-     * 116 real clips under cleanSamples/test/raw are `even` and `cycle` has never
-     * fired on real footage. Measured on hcaptcha_rotating_obj_video: 6.0s of a
+     * 116 real clips under the held-out sample corpus are `even` and `cycle` has never
+     * fired on real footage. Measured on an hCaptcha rotating-object animation: 6.0s of a
      * 28.8s solve, closest region diff 0.0721 against a 0.05 tolerance, then the
      * same click, then solved. Kept for `cycle`/`static`, where the state does
      * come back and waiting is the difference between the sprite and background.
@@ -486,6 +637,20 @@ export declare class CaptchaKrakenSolver {
      * never animated, so escalating there would swap a path that works for one
      * that cannot read a grid.
      */
+    /** Forget the recorded answer, and delete the frames it was holding. */
+    private discardAnimatedPlan;
+    /**
+     * Should this round record while it asks?
+     *
+     * reCAPTCHA is excluded for the same reason it is excluded from the animated
+     * path at all: its dynamic 3x3 REPLACES tiles in place, has its own
+     * multi-round driver with its own fade gates, and its grids are never
+     * animated — so a burst there would film a fade and call it a cycle.
+     *
+     * Distorted-text rounds are excluded because the answer is a string, not a
+     * place, and nothing about a recording helps read one.
+     */
+    private shouldSpeculate;
     private shouldRetryAsAnimated;
     private getSolution;
     /** One inference: build the CLI invocation, run it, parse what comes back. */
@@ -573,6 +738,32 @@ export declare class CaptchaKrakenSolver {
      * nothing at all.
      */
     private performSmoothMove;
+    /**
+     * Where in the element this click lands, in element-relative pixels.
+     *
+     * Split out of `executeClick` because on an animated board the point has to
+     * be chosen ONCE and then used three times — to park the pointer, to ask
+     * `match-region` about the right neighbourhood, and to press. Choosing it
+     * inside the click (it is randomised within the target) meant the gate
+     * watched the bbox centre while the press landed somewhere else.
+     */
+    private clickPointFor;
+    /**
+     * Click one target on an ANIMATED board, at the moment its screen is up.
+     *
+     * The order is the point of it. The pointer is parked on the target FIRST,
+     * then the gate opens, then the press happens in place — so the only thing
+     * between "the right screen is showing" and the click is a mouse-down.
+     *
+     * It used to wait and then call `executeClick`, which begins with a humanised
+     * move: 274ms p10 / 398ms p50 / 647ms max across a 340x384 widget, against a
+     * 1500ms median dwell. A quarter to a third of the screen's life spent
+     * travelling after we had already confirmed it was the right one — so the
+     * gate could do its job and the click still land on the next screen.
+     * `move()` short-circuits when it is already at the target, so parking early
+     * costs nothing and removes all of it.
+     */
+    private clickWhenFrameMatches;
     private executeClick;
     private executeDrag;
     /**