captchakraken 2.6.0 → 2.8.0

package/python/src/captchakraken/pinned_model.json

@@ -12,8 +12,9 @@
     "serving prompt fails CI until someone consciously re-pins \u2014 which forces",
     "the question 'does the pinned adapter still expect this prompt?'.",
     "",
-    "To ship a new adapter: update lora_adapter/lora_revision, re-run the Tier 2",
-    "static-image gate against it, and update prompt_sha256 if the prompts moved."
+    "To ship a new adapter: update lora_adapter/lora_revision, re-run the",
+    "static-image accuracy gate against it, and update prompt_sha256 if the",
+    "prompts moved."
   ],
   "base_model": "RedHatAI/Qwen3.5-9B-FP8-dynamic",
   "lora_adapter": "CaptchaKraken/CaptchaKraken-Lora-v1.2",

package/python/src/captchakraken/planner.py

@@ -124,6 +124,14 @@ _CLIENT_ENV = "CAPTCHA_KRAKEN_CLIENT"
 _SESSION_HEADER = "X-CK-Session"
 _SESSION_ENV = "CAPTCHA_KRAKEN_SESSION"
 
+# Report whether the widget accepted, once per solve. "0" turns it off.
+#
+# ON by default because the report is what makes a failed solve improvable, and
+# because it is the only way a hosted account's failures can be found at all.
+# Opting out here stops the CLIENT sending it; `captureOptOut` on the account is
+# the server-side half, and either one alone is enough to keep nothing.
+_REPORT_OUTCOME_ENV = "CAPTCHA_REPORT_OUTCOME"
+
 # Arbitrary extra headers, as "Name: value" pairs separated by newlines or
 # commas. Empty and absent by default.
 #
@@ -284,6 +292,7 @@ class ActionPlanner:
         debug_callback: Optional[Any] = None,
         base_url: Optional[str] = None,
         api_key: Optional[str] = None,
+        expert: Optional[str] = None,
         **_: Any,
     ):
         self.debug_callback = debug_callback
@@ -309,9 +318,102 @@ class ActionPlanner:
         # the same key: an adapter reads a puzzle at the pixel band it trained
         # under. Resolved once per planner — see the note above.
         self.pixel_budget = prompts.pixel_budget(_prompt_key)
+        # WHICH ADAPTER answers each prompt family. Empty for every model that
+        # is not routed, which is every model published so far — `_model_for`
+        # then returns `self.model` for every request and the wire is unchanged.
+        #
+        # Resolved once, like the two above, and for a stronger reason: the pin
+        # is validated here, so `--expert grid` against a single-adapter model
+        # fails when the solver is BUILT rather than on the first grid it meets.
+        self.expert = (expert if expert is not None
+                       else prompts.expert_pin())
+        self.experts = prompts.experts(_prompt_key)
+        if self.expert:
+            # Raises on an unknown family, and on a pin against an unrouted
+            # model. Both are configuration errors, and a benchmark that
+            # quietly measured the generalist while reporting an expert is the
+            # exact class of silent mispairing models.json exists to prevent.
+            prompts.route(_prompt_key, None, pin=self.expert)
         # Auto-start a local vLLM server on the first request if one isn't up
         # (no-op for a healthy or remote endpoint). Guarded so we only try once.
         self._server_ensured = False
+        # ONE connection, reused for every round of every solve this planner
+        # serves. `requests.post` opens a fresh TCP connection each call — and
+        # to a hosted endpoint a TLS handshake with it. Measured against the
+        # gate's own endpoint: 258ms per request connectionless vs 144ms
+        # pooled, so every inference was paying ~110ms to re-dial a server it
+        # had just finished talking to. A multi-round grid pays it per round.
+        #
+        # The planner is per-PageSolver and a PageSolver is reusable across
+        # solves, so a caller who keeps one keeps the connection warm too.
+        self._http = requests.Session()
+        # Latched off by the first 404 — see `report_outcome`.
+        self._outcome_supported = True
+
+    def _model_for(self, family: Optional[str]) -> str:
+        """The `model` string for a request in `family`.
+
+        `self.model` whenever the model is not routed, so a caller may pass a
+        family unconditionally. A routed model with no expert for this family
+        degrades to the generalist — never to another expert, never to an
+        error (docs/MOE_LORA_DESIGN.md §11).
+        """
+        if not self.experts:
+            return self.model
+        return prompts.route(self.model, family, pin=self.expert) or self.model
+
+    # ── the solve's own verdict, sent back ─────────────────────────────────
+    #
+    # THE ONE THING THE SERVER CANNOT SEE. A wrong answer reaches the gateway as
+    # a 200 with well-formed JSON in it; only this driver watched the widget.
+    # Without this report the hosted API cannot tell a solved captcha from a
+    # failed one, and the failures — the exact boards the model is worst at, on
+    # real sites — are the one dataset that cannot be collected any other way.
+    #
+    # BEST-EFFORT, ALWAYS. It runs after the solve is over and its result is
+    # already decided, so nothing it does can change the answer the caller gets.
+    # Every failure is swallowed: a self-hosted vLLM has no such route, a
+    # network blip is not the caller's problem, and an exception here would turn
+    # a successful solve into a raised one.
+    #
+    # ONE 404 IS ENOUGH. A self-hosted endpoint answers 404 forever, so the
+    # first one latches this off for the life of the planner rather than paying
+    # a round trip per solve to be told the same thing again.
+    _OUTCOME_PATH = "/solve-outcome"
+    _OUTCOME_TIMEOUT_S = 3.0
+
+    def report_outcome(self, session_id: Optional[str], solved: bool) -> bool:
+        """Tell the API whether the widget accepted. True if it was delivered.
+
+        Never raises. The return value is for tests and for `--debug`; no caller
+        should branch on it.
+        """
+        if not session_id or not self._outcome_supported:
+            return False
+        if os.getenv(_REPORT_OUTCOME_ENV, "1") == "0":
+            return False
+        url = f"{self.base_url}{self._OUTCOME_PATH}"
+        try:
+            resp = self._http.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={"session": session_id, "solved": bool(solved)},
+                timeout=self._OUTCOME_TIMEOUT_S,
+            )
+        except Exception as exc:  # noqa: BLE001 — see the note above
+            self._log(f"outcome report failed: {exc}")
+            return False
+        if resp.status_code == 404:
+            # Not an error: this endpoint does not serve the route. Stop asking.
+            self._outcome_supported = False
+            self._log("outcome reporting: endpoint has no /solve-outcome; disabled")
+            return False
+        ok = 200 <= resp.status_code < 300
+        self._log(f"outcome report {session_id} solved={solved} -> {resp.status_code}")
+        return ok
 
     def _log(self, message: str) -> None:
         if DEBUG:
@@ -319,11 +421,14 @@ class ActionPlanner:
         if self.debug_callback:
             self.debug_callback(f"[Planner] {message}")
 
-    def _chat_with_image(self, prompt: str, image_path: str, max_tokens: int = 512) -> str:
-        return self._chat_with_images(prompt, [image_path], max_tokens=max_tokens)
+    def _chat_with_image(self, prompt: str, image_path: str, max_tokens: int = 512,
+                         family: Optional[str] = None) -> str:
+        return self._chat_with_images(prompt, [image_path], max_tokens=max_tokens,
+                                      family=family)
 
     def _chat_with_images(
-        self, prompt: str, image_paths: List[str], max_tokens: int = 512
+        self, prompt: str, image_paths: List[str], max_tokens: int = 512,
+        family: Optional[str] = None,
     ) -> str:
         """One request carrying N images followed by the prompt.
 
@@ -355,8 +460,9 @@ class ActionPlanner:
             },
         ]
 
+        model = self._model_for(family)
         payload = {
-            "model": self.model,
+            "model": model,
             "messages": messages,
             "temperature": 0,
             "max_tokens": max_tokens,
@@ -387,11 +493,11 @@ class ActionPlanner:
             self._server_ensured = True
 
         url = f"{self.base_url}/chat/completions"
-        self._log(f"POST {url} model={self.model} max_tokens={max_tokens} "
+        self._log(f"POST {url} model={model} max_tokens={max_tokens} "
                   f"images={len(parts)}")
 
         with timed("planner.chat"):
-            resp = requests.post(url, headers=headers, json=payload, timeout=120)
+            resp = self._http.post(url, headers=headers, json=payload, timeout=120)
 
         # Surface auth / billing / server errors as something the reader can act
         # on, instead of letting resp.json() blow up with a cryptic "Expecting
@@ -531,7 +637,8 @@ class ActionPlanner:
                   "Return the complete list of cell numbers that match the description, "
                   "including any matches you may have overlooked."
             )
-        raw = self._chat_with_image(prompt, image_path, max_tokens=128)
+        raw = self._chat_with_image(prompt, image_path, max_tokens=128,
+                                    family="grid")
         out = self._normalize_grid(self._parse_json(raw), total)
         self._log(f"grid selection -> {out}")
         return out
@@ -592,7 +699,8 @@ class ActionPlanner:
         into ClickAction / DragAction / TypeAction.
         """
         prompt = self.prompts.text_prompt() if text_mode else self.prompts.action_prompt
-        raw = self._chat_with_image(prompt, image_path, max_tokens=512)
+        raw = self._chat_with_image(prompt, image_path, max_tokens=512,
+                                    family="text" if text_mode else "pixel")
         data = self._parse_json(raw)
         actions = self._normalize_pixel(data)
         self._log(f"pixel actions -> {actions}")
@@ -618,7 +726,8 @@ class ActionPlanner:
         # so this raises a clear error there instead of sending a v1 model a
         # keyframe request it was never trained to read.
         prompt = self.prompts.video_prompt(len(keyframe_paths))
-        raw = self._chat_with_images(prompt, list(keyframe_paths), max_tokens=512)
+        raw = self._chat_with_images(prompt, list(keyframe_paths), max_tokens=512,
+                                     family="video")
         data = self._parse_json(raw)
         actions = self._normalize_pixel(data)
         frame = self._normalize_frame(data, len(keyframe_paths))

package/python/src/captchakraken/prompts.py

@@ -247,6 +247,80 @@ def canonical_model_id(model: Optional[str]) -> Optional[str]:
     return alias if isinstance(alias, str) else None
 
 
+# ── availability: can these weights be obtained at all? ─────────────────────
+#
+# Same registry, same reason as prompt_version and pixel_budget: it is a fact
+# about the MODEL, and the one place that already decides what an unpinned
+# client downloads. See models.json's header comment.
+
+PUBLIC = "public"
+PRIVATE = "private"
+LICENSED = "licensed"
+#: Anything outside this set is a typo, and a typo must not read as "public".
+#: The whole class of bug this file exists to prevent is a field that fails
+#: open — `check_prompt_parity.py` rejects an unknown value at release time,
+#: and `is_licensed` below treats one as licensed rather than guessing.
+#:
+#: Spelled out as literals rather than `(PUBLIC, PRIVATE, LICENSED)`: the
+#: release gate reads this file by AST so it can run in a training venv with no
+#: client installed, and `ast.literal_eval` cannot follow a name. A tuple of
+#: names reads as "unset" to the gate, which is the check silently not running.
+#: `tests/test_prompt_registry.py` pins that all four constants agree.
+AVAILABILITIES = ("public", "private", "licensed")
+
+
+def availability(model: Optional[str]) -> str:
+    """`"public"`, `"private"` or `"licensed"` for `model`. Absent means public.
+
+    The three answer ONE question — can these weights be obtained, and by whom:
+
+      public     on the Hub, by anyone.
+      private    on the Hub in a PRIVATE repo. The bytes exist and `fetch`
+                 pulls them, but only for a token this account has authorised.
+                 Everyone else gets 401/404 from the Hub, which is the right
+                 answer and not something to pre-empt with a refusal.
+      licensed   no Hub repo at all. Hosted API or a licence we issue.
+
+    `private` is the newest and it is NOT a softer `licensed`. They differ in
+    what an authorised holder can do, which is the whole reason the field is
+    not a boolean: a licensed model has nothing to download however good your
+    credentials are, so refusing early is a KINDNESS — it replaces a
+    `RepositoryNotFoundError` that reads as "you are not logged in" with the
+    truth. Doing the same to a private model would be a lie, and would make our
+    own admin token unable to pull weights it is entitled to.
+
+    An unregistered model is public too: it is not ours, and refusing to
+    download a stranger's adapter because we have never heard of it would break
+    every self-hoster who trained their own.
+    """
+    entry = registered_models().get(canonical_model_id(model) or "") or {}
+    value = entry.get("availability")
+    return value if isinstance(value, str) and value else PUBLIC
+
+
+def is_licensed(model: Optional[str]) -> bool:
+    """True if these weights are NOT OBTAINABLE AT ALL — hosted API or licence.
+
+    Fails CLOSED on an unrecognised value. A registry that says `"licenced"`
+    must not hand out a proprietary model because of a spelling.
+
+    False for `private`: those weights are downloadable, by the holder of a
+    token we authorised. Proprietary and unobtainable are different facts, and
+    this function answers the second one — `requires_auth` answers the first.
+    """
+    return availability(model) not in (PUBLIC, PRIVATE)
+
+
+def requires_auth(model: Optional[str]) -> bool:
+    """True if pulling these weights needs a token we authorised.
+
+    Separate from `is_licensed` because the two diverge exactly where it
+    matters: a `private` model needs a token AND can be fetched with one, a
+    `licensed` model needs no token because there is nothing to fetch.
+    """
+    return availability(model) == PRIVATE
+
+
 # ── prompt sets ─────────────────────────────────────────────────────────────
 
 @dataclass
@@ -479,6 +553,114 @@ def pixel_budget(model: Optional[str]) -> PixelBudget:
     return DEFAULT_PIXEL_BUDGET
 
 
+# ─── expert routing: WHICH ADAPTER answers this prompt family ───────────────
+#
+# Same registry, same reason again, one more axis. A routed model is not one
+# adapter: `Abyss` is four LoRAs behind one endpoint, and the thing that picks
+# between them is the prompt family the request is about to send — grid, pixel,
+# video, text. See docs/MOE_LORA_DESIGN.md §11 ("the router is the prompt
+# family, and it already exists").
+#
+# It lives HERE rather than in the solver for the reason prompt_version does:
+# which experts exist is a fact about the MODEL. A client that hardcoded four
+# names would send them to v1.2, which serves one adapter under one name, and
+# every request would 404 on a model the endpoint has never heard of.
+#
+# ABSENT MEANS NOT ROUTED, and that is the whole backwards-compatibility story:
+# every published model today declares no `experts`, so `experts()` returns {},
+# `route()` returns the name the caller already had, and the bytes on the wire
+# are identical.
+
+EXPERT_ENV = "CAPTCHA_EXPERT"
+
+#: The prompt families, which are also the only keys an `experts` map may
+#: carry. `pixel` is the click/drag family — `PromptSet.action_prompt` — and is
+#: spelled that way rather than `action_pixel` because it is what ckgate's
+#: PROMPT_MARKERS already calls it, and two spellings of one router is how a
+#: family ends up unrouted on one side.
+PROMPT_FAMILIES = ("pixel", "grid", "video", "text")
+
+
+def experts(model: Optional[str]) -> Dict[str, str]:
+    """Prompt family -> served adapter name, for a ROUTED model.
+
+    `{}` for anything that is not routed, which is every model published so
+    far. Callers apply it unconditionally; an empty map is a no-op.
+
+    Unknown family keys are DROPPED rather than passed through. A typo in the
+    registry would otherwise be a name nothing ever selects — invisible,
+    because the fallback below is a working solve at a slightly worse score,
+    which is the exact failure mode this whole module exists to prevent.
+    """
+    repo_id = canonical_model_id(model)
+    entry = (registered_models().get(repo_id) or {}) if repo_id else {}
+    mapping = entry.get("experts")
+    if not isinstance(mapping, dict):
+        return {}
+    out = {}
+    for family in PROMPT_FAMILIES:
+        name = mapping.get(family)
+        if isinstance(name, str) and name:
+            out[family] = name
+    for key in mapping:
+        if key not in PROMPT_FAMILIES and not str(key).startswith("_"):
+            _warn(f"model {repo_id!r} declares an expert for unknown prompt "
+                  f"family {key!r}; have {', '.join(PROMPT_FAMILIES)}. It will "
+                  "never be selected.")
+    return out
+
+
+def route(model: Optional[str], family: Optional[str], *,
+          pin: Optional[str] = None) -> str:
+    """The `model` string to put on the wire for one request.
+
+    `model` is what the caller would have sent — a served name or a repo id —
+    and is returned unchanged whenever the model is not routed, which is what
+    keeps every existing deployment byte-identical.
+
+    `pin` forces one family for every request, whatever `family` says. That is
+    what a gate wants: serve one arm, grade the types it owns, serve the next.
+    An unknown `pin` RAISES, because a benchmark that silently measured the
+    generalist and reported it as the expert is a number nobody can catch.
+
+    An unrecognised or unmapped `family` degrades to `model` — the generalist —
+    never to another expert and never to an error. A caller prompting in their
+    own words is the expected case for a shipped model, and the day the
+    generation-2 `text` family reached ckgate without a marker, refusing it cost
+    every distorted-text solve in production for a day.
+    """
+    if pin is not None:
+        pin = pin.strip()
+    if pin:
+        if pin not in PROMPT_FAMILIES:
+            raise ValueError(
+                f"unknown expert {pin!r}; have {', '.join(PROMPT_FAMILIES)}")
+        family = pin
+    mapping = experts(model)
+    if not mapping:
+        if pin:
+            raise ValueError(
+                f"expert {pin!r} was requested but model {model!r} declares no "
+                "experts — it serves one adapter under one name. Drop the "
+                "expert, or point the client at a routed model.")
+        return model or ""
+    return mapping.get(family or "") or model or ""
+
+
+def _env_str(name: str) -> Optional[str]:
+    """Like `_env_int`, and read through the same indirection for the same
+    second reason: `test_public_contract.py` finds environment variables by
+    grepping for `os.environ.get(<NAME>)`, so naming the CONSTANT there records
+    `EXPERT_ENV` in the published env list as though it were a variable anyone
+    could set. The literal is picked up from the assignment above instead."""
+    return (os.environ.get(name) or "").strip() or None
+
+
+def expert_pin() -> Optional[str]:
+    """`CAPTCHA_EXPERT`, or None. Empty and unset are the same thing."""
+    return _env_str(EXPERT_ENV)
+
+
 def clear_cache() -> None:
     _cache.clear()
     global _REGISTRY

package/python/src/captchakraken/server_manager.py

@@ -170,11 +170,16 @@ def ensure_server(base_url: "str | None" = None) -> None:
     """
     base_url = base_url or config.base_url()
 
-    if is_healthy(base_url):
-        return
+    # REMOTE FIRST. There is nothing to ensure about a server we do not manage,
+    # so asking it for /health before deciding that is a round trip spent to
+    # reach a `return` — and up to `timeout=2.0` of it against a hosted gateway
+    # that serves no /health at all. Paid once per ActionPlanner, which for a
+    # caller using `solve_captcha_on_page` is once per solve.
     if not is_local(base_url):
-        # Remote server we don't manage: let the actual request raise a clear
-        # connection error rather than silently trying to boot vLLM locally.
+        # Let the actual request raise a clear connection error rather than
+        # silently trying to boot vLLM locally.
+        return
+    if is_healthy(base_url):
         return
     if not config.autostart_enabled():
         return

package/python/src/captchakraken/solver.py

@@ -24,7 +24,6 @@ v1 had a SAM3-backed tool-using planner with detect/segment/drag-refine; it
 lives on the `v1-old-architecture` branch.
 """
 
-import math
 import os
 import shutil
 import sys
@@ -112,6 +111,47 @@ class DebugManager:
             return None
 
 
+#: The only cell counts a registered grid puzzle has. `find_grid` is a lattice
+#: detector, not a catalogue — it allows rectangles and any dimension from
+#: MIN_GRID_DIM up — so it will happily report 12 or 20 cells on a click puzzle's
+#: header/footer bands. Anything not in here is a false positive by construction,
+#: and it is also a board the model has never seen: the training pipeline's own
+#: `grid_overlay.detect_cells` refuses every count but these two.
+GRID_CELL_SHAPES = {9: (3, 3), 16: (4, 4)}
+
+#: Cell counts each vendor actually ships, for the vendors the driver can name.
+#: Only reCAPTCHA has a 4x4; hCaptcha's single grid puzzle is 3x3, so 16 cells on
+#: an hCaptcha board is a contradiction rather than a close call. Measured on real
+#: captures, that one line removes four of the five non-grid boards that clear
+#: both find_grid and _is_real_grid today.
+#:
+#: A vendor NOT in this table — `unknown`, or anything new — gets every shape.
+#: `unknown` is what the driver reports for GeeTest and Prosopo, both of which
+#: ship real 3x3 grids, and it is what the one-shot image API defaults to, which
+#: is the path the offline grader uses to score reCAPTCHA 4x4. Narrowing it would
+#: stop scoring a whole puzzle type while looking like a tightening.
+VENDOR_GRID_CELLS = {
+    "hcaptcha": frozenset({9}),
+    "recaptcha": frozenset({9, 16}),
+}
+
+
+def _grid_dims(n_cells, puzzle_source="unknown"):
+    """(rows, cols) if this detection could be a grid we ship, else None.
+
+    None means "do not solve this as a grid" — the caller falls through to the
+    click/drag path, which is what the board actually is. It is deliberately not
+    an exception: a false positive here is an ordinary event, not an error.
+    """
+    shape = GRID_CELL_SHAPES.get(n_cells)
+    if shape is None:
+        return None
+    allowed = VENDOR_GRID_CELLS.get(puzzle_source)
+    if allowed is not None and n_cells not in allowed:
+        return None
+    return shape
+
+
 class CaptchaSolver:
     """v2 solver: OpenCV grid detection + vLLM `captcha` LoRA."""
 
@@ -120,13 +160,15 @@ class CaptchaSolver:
         model: Optional[str] = None,
         provider: str = "captchaKrakenApi",
         api_key: Optional[str] = None,
+        expert: Optional[str] = None,
     ):
         self.debug = DebugManager(DEBUG)
         # `provider` kept for argv compatibility with the v1 CLI signature.
         if provider not in {"captchaKrakenApi"}:
             self.debug.log(f"Provider {provider!r} ignored; v2 only supports captchaKrakenApi.")
         self.planner = ActionPlanner(
-            model=model, api_key=api_key, debug_callback=self.debug.log
+            model=model, api_key=api_key, debug_callback=self.debug.log,
+            expert=expert,
         )
         self.image_processor = ImageProcessor(None, self.planner, self.debug)
         self._image_size: Optional[Tuple[int, int]] = None
@@ -183,9 +225,22 @@ class CaptchaSolver:
 
         with timed("solver.find_grid"):
             grid_boxes = find_grid(cv_image_path)
-        if grid_boxes and self._is_real_grid(cv_image_path, grid_boxes):
+        # The SHAPE gate runs before the content gate: a lattice no vendor ships
+        # is not a grid whatever its cells look like, and saying so here keeps
+        # `_solve_grid` from ever being handed dimensions it would have to invent.
+        dims = _grid_dims(len(grid_boxes), puzzle_source) if grid_boxes else None
+        if grid_boxes and dims and self._is_real_grid(cv_image_path, grid_boxes):
             self.debug.log(f"Detected grid with {len(grid_boxes)} cells")
-            return self._solve_grid(cv_image_path, grid_boxes, retry_mode=retry_mode)
+            return self._solve_grid(cv_image_path, grid_boxes, dims[0], dims[1],
+                                    retry_mode=retry_mode)
+        elif grid_boxes and not dims:
+            # e.g. a 16-cell lattice on an hCaptcha board (it ships no 4x4), or a
+            # 12-cell one on anything. Fall through to the click path, which is
+            # what this puzzle is.
+            self.debug.log(
+                f"find_grid returned {len(grid_boxes)} cells, which is not a shape "
+                f"{puzzle_source} ships — not solving as a grid."
+            )
         elif grid_boxes:
             # find_grid latched onto e.g. an hCaptcha click-puzzle's
             # header/footer bands. Reject — only true grids are supported.
@@ -403,11 +458,6 @@ class CaptchaSolver:
             if not stds:
                 return False
 
-            n = len(grid_boxes)
-            side = 3 if n == 9 else 4 if n == 16 else int(round(n ** 0.5))
-            rows = [stds[i * side:(i + 1) * side] for i in range(side)]
-            cols = [stds[i::side] for i in range(side)]
-
             self.debug.log(
                 f"_is_real_grid: per-cell stddev = {[round(s, 1) for s in stds]}"
             )
@@ -459,46 +509,35 @@ class CaptchaSolver:
                 )
                 return False
 
-            FLAT = 20.0
-            # Build a side×side flat-mask (1 = flat cell, 0 = rich cell).
-            flat_mask = [[1 if stds[r * side + c] < FLAT else 0
-                          for c in range(side)] for r in range(side)]
-            flat_count = sum(sum(row) for row in flat_mask)
-
-            # Heuristic: in a *real* captcha grid, flat tiles (sky, asphalt)
-            # always form a spatially contiguous blob (top-left sky stack,
-            # bottom road row, etc.) because the underlying image is a single
-            # photo split into tiles. In a click-puzzle false grid, the flat
-            # cells are the **left + right margins** of the middle row,
-            # separated by the rich photo cell — non-contiguous.
+            # THE FLAT-CELL CONTIGUITY HEURISTIC IS GONE, and it was the only
+            # thing rejecting real grids.
             #
-            # Use 4-connected components on flat cells. If we get more than
-            # one component with >=1 cell each, it's the click-puzzle pattern.
-            def components(mask):
-                seen = [[False] * side for _ in range(side)]
-                comps = 0
-                for r in range(side):
-                    for c in range(side):
-                        if mask[r][c] and not seen[r][c]:
-                            comps += 1
-                            stack = [(r, c)]
-                            while stack:
-                                y, x = stack.pop()
-                                if seen[y][x] or not mask[y][x]:
-                                    continue
-                                seen[y][x] = True
-                                for dy, dx in ((1, 0), (-1, 0), (0, 1), (0, -1)):
-                                    ny, nx = y + dy, x + dx
-                                    if 0 <= ny < side and 0 <= nx < side:
-                                        stack.append((ny, nx))
-                return comps
-
-            if flat_count >= 2 and components(flat_mask) >= 2:
-                self.debug.log(
-                    f"_is_real_grid: flat cells form >=2 disjoint components "
-                    "→ reject (click-puzzle pattern)."
-                )
-                return False
+            # It assumed flat tiles in a genuine photo grid always form ONE
+            # contiguous blob (a top-left sky stack, a bottom road row), because
+            # the board is a single photo cut up; a click-puzzle false grid puts
+            # its flat cells in the left and right margins of the middle row,
+            # which is two components. True of the boards it was written for,
+            # and false of plenty of photographs — a subject centred against
+            # plain sky leaves two flat corners and nothing between them.
+            #
+            # MEASURED over every real capture we hold, restricted to lattices
+            # `_grid_dims` actually accepts (9 or 16 cells — a 25-cell gobang
+            # board never reaches this function as a grid decision):
+            #
+            #     rule                     grid false neg   board false pos
+            #     spread + mean-stddev        2/1748 0.11%       0/269 0.00%
+            #     ...plus contiguity         40/1748 2.29%       0/269 0.00%
+            #
+            # It cost 38 real grids and caught nothing the two checks above did
+            # not already catch — 19 of those were recaptcha_grid_4x4 alone,
+            # 5.5% of that family, every one of them sent to the click path to
+            # be asked for coordinates on a board answered with cell numbers.
+            # Nothing errors when that happens; the reply is simply graded
+            # against a gold it cannot match.
+            #
+            # The median-colour spread check above supersedes it and is a much
+            # cleaner separation (an 18x gap rather than a topological guess),
+            # which is why this is a deletion and not a retuning.
             return True
         except Exception as e:
             self.debug.log(f"_is_real_grid check errored ({e}); accepting grid.")
@@ -508,17 +547,18 @@ class CaptchaSolver:
         self,
         image_path: str,
         grid_boxes: List[Tuple[int, int, int, int]],
+        rows: int,
+        cols: int,
         retry_mode: Optional[str] = None,
     ) -> Union[ClickAction, DoneAction, WaitAction]:
-        n = len(grid_boxes)
-        if n == 9:
-            rows, cols = 3, 3
-        elif n == 16:
-            rows, cols = 4, 4
-        else:
-            cols = int(math.sqrt(n))
-            rows = math.ceil(n / cols)
-        self.debug.log(f"grid {rows}x{cols} ({n} cells)")
+        # The shape is PASSED IN, already cleared by `_grid_dims`. It used to be
+        # derived here, and the derivation had an `else` branch that turned any
+        # unrecognised count into `cols = int(sqrt(n)); rows = ceil(n / cols)` —
+        # so a 12-cell false positive became a 4x3 board, got stamped with twelve
+        # numbers, and was answered with cell ids. No such board can exist in the
+        # training corpus, because the generator's own detector refuses every
+        # count but 9 and 16.
+        self.debug.log(f"grid {rows}x{cols} ({len(grid_boxes)} cells)")
 
         cv_selected: List[int] = []
         cv_loading: List[int] = []

package/python/src/captchakraken/timing.py

@@ -56,9 +56,14 @@ class PhaseBudget:
     monitor spent 31s of it" is. Always on — it is a few dict updates per phase
     against multi-second waits — but only PRINTED under CAPTCHA_TIMINGS=1.
 
-    Phases may nest (a burst contains its screenshots); only the outermost of a
-    given name accumulates, so the totals stay a partition of the solve rather
-    than double-counting.
+    Phases may nest (a burst contains its screenshots). Only the outermost of a
+    GIVEN NAME accumulates, so re-entering one cannot double-count it — but a
+    phase nested inside a differently-named one counts under both, deliberately:
+    the cursor drifting over the widget WHILE the model generates is genuinely
+    both `mouse` and `inference`, and hiding either would misreport what the
+    solve was doing. The totals are therefore an attribution, not a partition,
+    and can exceed the elapsed time. `report()` prints the residual as
+    `(unattributed)` and it can go negative when they do.
     """
 
     def __init__(self) -> None: