captchakraken 2.2.0 → 2.4.0

package/python/src/captchakraken/pinned_model.json

@@ -0,0 +1,28 @@
+{
+  "_comment": [
+    "The model this release of CaptchaKraken is PINNED to, plus the prompts it",
+    "was trained to answer. CI reads this file; see tests/test_pinned_model.py.",
+    "",
+    "Why a file and not just env defaults: the adapter and the serving prompts",
+    "are a matched pair. On 2026-07-18 the LoRA was retrained on the content",
+    "schema (action: drag / drags[] / lowercase) while planner.py still asked",
+    "for the legacy output/PascalCase schema. The model answered in a hybrid,",
+    "the parser dropped it, and EVERY drag puzzle failed as 'unsupported' with",
+    "no test going red. Recording the prompt hashes here means any edit to a",
+    "serving prompt fails CI until someone consciously re-pins — 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."
+  ],
+
+  "base_model": "RedHatAI/Qwen3.5-9B-FP8-dynamic",
+  "lora_adapter": "CaptchaKraken/CaptchaKraken_v1.1",
+  "lora_revision": "main",
+  "lora_name": "captcha",
+
+  "prompt_sha256": {
+    "PIXEL_ACTION_PROMPT": "15d4833135330aa57ec64eb9132d15739cbf4a10bcda2e6d85d2d0ad92e0216a",
+    "SELECT_GRID_PROMPT": "f014dbc1cb8c773cc9501ff97aea92ff0281e5687b3d637d1c626ded9212fd3c"
+  }
+}

package/python/src/captchakraken/planner.py

@@ -10,18 +10,155 @@ planner with detect/segment/drag-refine; that code is preserved on the
 import base64
 import json
 import os
+import re
 import sys
 from mimetypes import guess_type
 from typing import Any, Dict, List, Optional
 
 import requests
 
-from . import config
+from . import config, errors
 from .server_manager import ensure_server
 from .timing import timed
 
 DEBUG = os.getenv("CAPTCHA_DEBUG", "0") == "1"
 
+# Header the fleet's haproxy front (on the reverse-proxy EC2) routes on. When a
+# caller sets CAPTCHA_REQUEST_PRIORITY to a positive int, every request carries
+# `X-JH-Priority: <n>`; haproxy sends anything above its threshold (5) straight
+# to the backup GPUs so it never competes with production traffic on the main
+# 5090. The tier-2 CI gate sets this — its traffic is throwaway and must stay
+# off the primary.
+#
+# Deliberately a HEADER, not vLLM's request-body `priority` field: that field is
+# lower-is-higher and already means captcha=0 / apply=100 / label=200 on the
+# priority-scheduled primary, so a value like 10 would MISORDER there (it would
+# outrank apply/label). Routing is a fleet concern, kept out of the model's
+# scheduler.
+_PRIORITY_HEADER = "X-JH-Priority"
+_PRIORITY_ENV = "CAPTCHA_REQUEST_PRIORITY"
+
+# Hosted-API metadata. Both are OPTIONAL and absent unless deliberately set, so
+# self-hosted users never send them and are unaffected.
+#
+# X-CK-Client  — which integration issued this solve (e.g. "camoufox/0.4.11").
+#   camoufox sets CAPTCHA_KRAKEN_CLIENT in the env it spawns the solver with, so
+#   the gateway can account camoufox-attributed usage separately. Attribution
+#   ONLY: it is caller-supplied and therefore never priced on (the gateway
+#   derives billable puzzle class from the request body instead).
+# X-CK-Session — groups the 1..N inference rounds of ONE captcha into a single
+#   billable attempt. The JS driver mints a UUID per solve() and reuses it for
+#   every CLI invocation in that solve, which is what lets the gateway cap an
+#   attempt's billable rounds instead of charging per round without limit.
+_CLIENT_HEADER = "X-CK-Client"
+_CLIENT_ENV = "CAPTCHA_KRAKEN_CLIENT"
+_SESSION_HEADER = "X-CK-Session"
+_SESSION_ENV = "CAPTCHA_KRAKEN_SESSION"
+
+# Arbitrary extra headers, as "Name: value" pairs separated by newlines or
+# commas. Empty and absent by default.
+#
+# WHY THIS EXISTS. Some endpoints sit behind a gate that is not the API key —
+# our own dev gateway (api.dev.captchakraken.com) wants X-CK-Dev-Auth, and a
+# corporate egress proxy may want its own token. Without this the published
+# client simply cannot reach such an endpoint, which meant the dev environment
+# could not exercise the real client path at all: the thing dev exists to
+# rehearse was the one thing it could not do.
+#
+# IT CANNOT OVERWRITE Authorization, Content-Type, OR THE X-CK-* HEADERS. Those
+# carry the credential and the billing attribution. Allowing an env var to
+# rewrite Authorization would turn a stray export into "your key is not the key
+# being charged", and allowing it to rewrite X-CK-Session would let a caller
+# escape the per-attempt billing cap by pinning one session id forever.
+_EXTRA_HEADERS_ENV = "CAPTCHA_KRAKEN_EXTRA_HEADERS"
+_PROTECTED_HEADERS = frozenset(
+    {"authorization", "content-type", _CLIENT_HEADER.lower(), _SESSION_HEADER.lower()}
+)
+
+# These values reach the wire verbatim from the environment, so they are
+# sanitized rather than trusted: a CR/LF would otherwise splice arbitrary
+# headers into the upstream request.
+_HEADER_VALUE_MAX = 128
+
+
+# RFC 7230 token characters. Anything else is not a header name.
+_VALID_HEADER_NAME = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+
+
+def _clean_header_value(raw: str) -> str:
+    """Printable-ASCII, length-capped header value ("" when nothing survives)."""
+    return "".join(c for c in raw.strip() if 0x20 <= ord(c) < 0x7F)[:_HEADER_VALUE_MAX]
+
+
+def _extra_headers(raw: str) -> Dict[str, str]:
+    """Parse CAPTCHA_KRAKEN_EXTRA_HEADERS into a header dict.
+
+    Accepts "Name: value" pairs separated by newlines or commas:
+
+        CAPTCHA_KRAKEN_EXTRA_HEADERS='X-CK-Dev-Auth: hunter2'
+        CAPTCHA_KRAKEN_EXTRA_HEADERS=$'X-One: a\nX-Two: b'
+
+    Malformed entries are DROPPED, never guessed at. A pair with no colon is
+    not a header, and inventing one from it would put an attacker-shaped string
+    on the wire. Names are restricted to the RFC 7230 token characters for the
+    same reason the values are sanitized: a CR/LF in either would splice extra
+    headers into the request.
+
+    Protected headers are refused, so this cannot be used to replace the
+    credential or the billing attribution.
+    """
+    out: Dict[str, str] = {}
+    if not raw.strip():
+        return out
+
+    for entry in raw.replace(",", "\n").splitlines():
+        entry = entry.strip()
+        if not entry or ":" not in entry:
+            continue
+        name, _, value = entry.partition(":")
+        name = name.strip()
+        value = _clean_header_value(value)
+        if not name or not value:
+            continue
+        if not _VALID_HEADER_NAME.match(name):
+            continue
+        if name.lower() in _PROTECTED_HEADERS:
+            continue
+        out[name] = value
+    return out
+
+
+def routing_headers(env=None) -> Dict[str, str]:
+    """Fleet-routing + hosted-API headers derived from the environment.
+
+    Empty by default. Split out and env-injectable so it can be unit-tested
+    without a live server. A missing or non-integer CAPTCHA_REQUEST_PRIORITY
+    yields no header at all — an unset/garbage value must never silently tag
+    traffic for the backups.
+
+    Each header is derived independently: a malformed priority must not suppress
+    the attribution headers, or one typo would silently make a camoufox solve
+    look like direct traffic and understate the partner's revenue share.
+    """
+    env = os.environ if env is None else env
+    headers: Dict[str, str] = {}
+
+    raw = (env.get(_PRIORITY_ENV) or "").strip()
+    if raw:
+        try:
+            headers[_PRIORITY_HEADER] = str(int(raw))
+        except ValueError:
+            pass
+
+    for header, var in ((_CLIENT_HEADER, _CLIENT_ENV), (_SESSION_HEADER, _SESSION_ENV)):
+        value = _clean_header_value(env.get(var) or "")
+        if value:
+            headers[header] = value
+
+    headers.update(_extra_headers(env.get(_EXTRA_HEADERS_ENV) or ""))
+
+    return headers
+
 
 # Matches the training-distribution grid prompts in
 # cleanSamples/test/test_solutions.json -> grade.synthesize_instruction.
@@ -45,21 +182,21 @@ PIXEL_ACTION_PROMPT = (
     "Your task is to solve the captcha. Read the instruction at the top of the image carefully.\n\n"
     "Look at the puzzle and decide what action solves it. All coordinates you return must be on a "
     "normalized 0–1000 image scale (top-left = (0, 0), bottom-right = (1000, 1000)).\n\n"
+    "Name WHAT each object is with a short 1–2 word label, then give its position. "
     "Choose ONE response:\n\n"
     "FOR CLICK PUZZLES:\n"
-    "  Identify every position you need to click and emit them as a list of points:\n"
-    "  → \"action\": { \"action\": \"click\", \"points\": [[x1, y1], [x2, y2], ...] }\n\n"
+    "  Label each thing you click and give its point — subjects[i] names points[i]:\n"
+    "  → \"action\": \"click\", \"subjects\": [\"<label>\", ...], "
+    "\"points\": [[x1, y1], [x2, y2], ...]\n\n"
     "FOR DRAG PUZZLES:\n"
-    "  Drag ONE item at a time. The source position is the centroid of the piece you are picking up; "
-    "the destination position is where it should end up. If multiple drags are needed, drag the topmost "
-    "item first.\n"
-    "  → \"output\": [{ \"Action\": \"simulate_drag\", "
-    "\"SourceDescription\": \"...\", \"SourcePosition\": { \"x\": 1-1000, \"y\": 1-1000 }, "
-    "\"DestinationDescription\": \"...\", \"EstimatedPosition\": { \"x\": 1-1000, \"y\": 1-1000 } }]\n\n"
+    "  Drag ONE item at a time. Label the source (the piece you pick up) and the destination "
+    "(where it belongs), each with a short 1–2 word label, and give both points:\n"
+    "  → \"action\": \"drag\", \"drags\": [{ \"source\": \"<label>\", \"from\": [x, y], "
+    "\"destination\": \"<label>\", \"to\": [x, y] }, ...]\n\n"
     "Respond ONLY with JSON:\n"
     "{\n"
-    "  \"action\": { ... }\n"
-    "  // OR \"output\": [ ... ]\n"
+    "  \"action\": \"click\", \"subjects\": [ ... ], \"points\": [ ... ]\n"
+    "  // OR \"action\": \"drag\", \"drags\": [ ... ]\n"
     "}"
 )
 
@@ -128,6 +265,10 @@ class ActionPlanner:
         headers = {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
+            # Fleet routing: absent unless CAPTCHA_REQUEST_PRIORITY is set (see
+            # routing_headers). Low-priority batch traffic is steered to the
+            # backup GPUs by the haproxy front on this header.
+            **routing_headers(),
         }
 
         # Hands-off server: before the very first request, make sure something
@@ -147,21 +288,18 @@ class ActionPlanner:
         with timed("planner.chat"):
             resp = requests.post(url, headers=headers, json=payload, timeout=120)
 
-        # Surface auth / server errors with the actual body instead of letting
-        # resp.json() blow up with a cryptic "Expecting value: line 1 column 1"
-        # on a non-JSON response (e.g. a 401 {"error":"Unauthorized"} or an
-        # HTML error page). 401/403 almost always means the bearer token
-        # (CAPTCHA_KRAKEN_API_KEY) didn't reach this process.
+        # Surface auth / billing / server errors as something the reader can act
+        # on, instead of letting resp.json() blow up with a cryptic "Expecting
+        # value: line 1 column 1" on a non-JSON response.
+        #
+        # `errors.from_response` decides which of the two worlds we are in by
+        # looking for the gateway's `error.code`: present means the hosted API
+        # refused us and there is a real explanation to give (out of credits,
+        # rate limited, attempt abandoned); absent means a local vLLM or a proxy,
+        # and the old message — including the bearer-token hint on 401/403 — is
+        # reproduced unchanged.
         if not resp.ok:
-            body = (resp.text or "")[:300]
-            hint = ""
-            if resp.status_code in (401, 403):
-                hint = (
-                    " — check CAPTCHA_KRAKEN_API_KEY is set and forwarded to the CLI"
-                )
-            raise RuntimeError(
-                f"vLLM {resp.status_code} {resp.reason} at {url}{hint}. Body: {body}"
-            )
+            raise errors.from_response(resp, url)
 
         try:
             data = resp.json()
@@ -198,8 +336,13 @@ class ActionPlanner:
         else:
             return None
 
+        # strict=False tolerates unescaped control chars INSIDE strings — the
+        # model routinely emits coordinates as pretty-printed strings with a
+        # literal newline, e.g. "click": ["277,\n  728", ...], which strict JSON
+        # rejects. Without this the whole response fails to parse and a solvable
+        # click puzzle is dropped as "unsupported".
         try:
-            return json.loads(text[start:end])
+            return json.loads(text[start:end], strict=False)
         except json.JSONDecodeError:
             # The model sometimes truncates (hit max_tokens) or over-nests its
             # pretty-printed JSON, leaving brackets unclosed. Repair by balancing
@@ -207,7 +350,7 @@ class ActionPlanner:
             repaired = ActionPlanner._balance_json(text[start:])
             if repaired is not None:
                 try:
-                    return json.loads(repaired)
+                    return json.loads(repaired, strict=False)
                 except json.JSONDecodeError:
                     return None
             return None
@@ -284,12 +427,31 @@ class ActionPlanner:
                   "including any matches you may have overlooked."
             )
         raw = self._chat_with_image(prompt, image_path, max_tokens=128)
-        data = self._parse_json(raw)
+        out = self._normalize_grid(self._parse_json(raw), total)
+        self._log(f"grid selection -> {out}")
+        return out
+
+    @staticmethod
+    def _normalize_grid(data: Any, total: int) -> List[int]:
+        """Map the model's grid JSON to a list of 1-indexed cell numbers.
+
+        Accepts the trained shape (a bare JSON array) plus the wrapped forms the
+        model drifts into: {"target_ids": [...]} and {"action": {"target_ids":
+        [...]}}. Out-of-range and non-numeric entries are dropped rather than
+        raising — a single junk element must not cost the whole selection.
 
+        Split out of get_grid_selection so the parse is testable without a
+        model, mirroring _normalize_pixel.
+        """
         if isinstance(data, list):
             ids = data
         elif isinstance(data, dict):
-            ids = data.get("target_ids") or data.get("action", {}).get("target_ids") or []
+            # `action` is a dict on the grid path but a bare string ("drag") on
+            # the pixel path — guard so a mis-routed response returns [] rather
+            # than raising AttributeError.
+            nested = data.get("action")
+            nested_ids = nested.get("target_ids") if isinstance(nested, dict) else None
+            ids = data.get("target_ids") or nested_ids or []
         else:
             ids = []
 
@@ -297,11 +459,10 @@ class ActionPlanner:
         for v in ids:
             try:
                 iv = int(v)
-                if 1 <= iv <= total:
-                    out.append(iv)
             except (TypeError, ValueError):
                 continue
-        self._log(f"grid selection -> {out}")
+            if 1 <= iv <= total:
+                out.append(iv)
         return out
 
     def get_pixel_actions(self, image_path: str) -> List[Dict[str, Any]]:
@@ -347,10 +508,73 @@ class ActionPlanner:
                     fx, fy = min(max(fx, 0.0), 1.0), min(max(fy, 0.0), 1.0)
             return (fx, fy)
 
+        def flat_numbers(v: Any) -> List[float]:
+            """Every number anywhere inside v, in order. Handles nested lists,
+            {x,y} dicts, bare numbers, and numeric strings like "277, 728" (the
+            model sometimes emits coordinates as strings, occasionally even split
+            across separate array elements)."""
+            nums: List[float] = []
+            if isinstance(v, bool):
+                return nums
+            if isinstance(v, (list, tuple)):
+                for e in v:
+                    nums.extend(flat_numbers(e))
+            elif isinstance(v, dict):
+                for k in ("x", "y", "X", "Y"):
+                    if k in v:
+                        nums.extend(flat_numbers(v[k]))
+            elif isinstance(v, (int, float)):
+                nums.append(float(v))
+            elif isinstance(v, str):
+                nums.extend(float(m) for m in re.findall(r"-?\d+(?:\.\d+)?", v))
+            return nums
+
+        def coordish(v: Any) -> bool:
+            """True when v is a non-empty list of COORDINATES (numbers, [x,y]
+            pairs, {x,y} dicts, or numeric strings) — not text labels like
+            "dog". Used to decide whether a "click"/"coordinates" array carries
+            points we should salvage."""
+            if not isinstance(v, (list, tuple)) or not v:
+                return False
+            for e in v:
+                if isinstance(e, bool):
+                    return False
+                if isinstance(e, (int, float, list, tuple, dict)):
+                    continue
+                if isinstance(e, str) and re.search(r"\d", e):
+                    continue
+                return False
+            return True
+
         out: List[Dict[str, Any]] = []
         if not isinstance(data, dict):
             return out
 
+        # ---- drag (CANONICAL — the schema PIXEL_ACTION_PROMPT asks for and the
+        #      LoRA is trained on, see instructions.py::ACTION_INSTRUCTION):
+        #      {"action":"drag","drags":[{"source","from":[x,y],"destination","to":[x,y]}]}
+        # Note "action" here is the STRING "drag", not a dict, so the click path
+        # below never sees it. The legacy/simulate_drag branches that follow stay
+        # as fallbacks for older adapters.
+        content_drags = data.get("drags")
+        if content_drags is None and isinstance(data.get("action"), dict):
+            content_drags = data["action"].get("drags")
+        if isinstance(content_drags, dict):
+            content_drags = [content_drags]
+        if isinstance(content_drags, list) and content_drags:
+            for d in content_drags:
+                if not isinstance(d, dict):
+                    continue
+                snums = flat_numbers(d.get("from"))
+                dnums = flat_numbers(d.get("to"))
+                if len(snums) >= 2 and len(dnums) >= 2:
+                    src = norm_xy(snums[0], snums[1])
+                    dst = norm_xy(dnums[0], dnums[1])
+                    if src and dst:
+                        out.append({"kind": "drag", "src": src, "dst": dst})
+            if out:
+                return out
+
         # ---- drag: {"output": [ {simulate_drag ...}, ... ]} ----
         drags = data.get("output")
         if isinstance(drags, list) and drags:
@@ -366,6 +590,54 @@ class ActionPlanner:
             if out:
                 return out
 
+        # ---- drag: {"action": {"simulate_drag": [{source_position,
+        #                                           destination_position}]}} ----
+        # The full-puzzle LoRA actually emits drags in this snake_case shape
+        # (not the prompt's {"output":[{"Action":"simulate_drag",...}]}), and
+        # packs each coordinate as {"x": [x, y]} — flat_numbers() pulls the pair
+        # out of that. Without this branch a correctly-solved drag (e.g. hCaptcha
+        # "drag ONE character to the matching character") is dropped as
+        # "unsupported".
+        sd = data.get("simulate_drag")
+        if sd is None and isinstance(action := data.get("action"), dict):
+            sd = action.get("simulate_drag")
+        # The model emits simulate_drag as EITHER a list of drags OR a single
+        # drag object; normalize the single-object form to a one-element list so
+        # both parse (the object form was silently dropped as "unsupported").
+        if isinstance(sd, dict):
+            sd = [sd]
+        if isinstance(sd, list) and sd:
+            def _drag_coords(obj: Any, *roles: str) -> List[float]:
+                # Pull the source/destination coordinate pair regardless of key
+                # casing or separators — the LoRA freely varies between
+                # source_position / sourcePosition / SourcePosition and
+                # destination_position / destinationPosition / EstimatedPosition.
+                # The coord value may be {"x": [x, y]}, [x, y], {x, y}, or a
+                # string; flat_numbers() handles all of those.
+                if not isinstance(obj, dict):
+                    return []
+                for k, v in obj.items():
+                    kn = str(k).lower().replace("_", "").replace("-", "")
+                    if "pos" not in kn:
+                        continue
+                    if any(r in kn for r in roles):
+                        nums = flat_numbers(v)
+                        if len(nums) >= 2:
+                            return nums
+                return []
+            for d in sd:
+                if not isinstance(d, dict):
+                    continue
+                snums = _drag_coords(d, "source", "src")
+                dnums = _drag_coords(d, "destination", "dest", "estimated", "target")
+                if len(snums) >= 2 and len(dnums) >= 2:
+                    src = norm_xy(snums[0], snums[1])
+                    dst = norm_xy(dnums[0], dnums[1])
+                    if src and dst:
+                        out.append({"kind": "drag", "src": src, "dst": dst})
+            if out:
+                return out
+
         # ---- click: {"action": {"action":"click","points":[...]}} ----
         action = data.get("action")
         # The model sometimes over-wraps: {"action": {"action": {"action":
@@ -392,6 +664,26 @@ class ActionPlanner:
                     return [{"kind": "drag", "src": src, "dst": dst}]
         if points is None:
             points = data.get("points")
+        # Salvage: some responses carry the click coordinates under "click" (or
+        # "coordinates") instead of "points", as [x,y] pairs, {x,y} dicts, or
+        # "x, y" strings (sometimes split across elements), with no "points" key
+        # at all. Pull every number out of a coordinate-like value and pair them
+        # into points so a well-intentioned answer isn't dropped as "unsupported".
+        # Skipped when the value is text labels ("dog", "duck") rather than coords.
+        if not (isinstance(points, list) and points):
+            for container in (action if isinstance(action, dict) else None, data):
+                if not isinstance(container, dict):
+                    continue
+                cand = container.get("click")
+                if cand is None:
+                    cand = container.get("coordinates")
+                if coordish(cand):
+                    nums = flat_numbers(cand)
+                    if len(nums) >= 2:
+                        points = [
+                            [nums[i], nums[i + 1]] for i in range(0, len(nums) - 1, 2)
+                        ]
+                        break
         if isinstance(points, list) and points:
             pts = []
             for p in points:

package/python/src/captchakraken/server_manager.py

@@ -29,8 +29,9 @@ import requests
 
 from . import config
 
-# One shared state dir for the pidfile, lockfile, and server log.
-STATE_DIR = Path(os.getenv("CAPTCHA_KRAKEN_STATE_DIR", str(Path.home() / ".captchakraken")))
+# One shared state dir for the pidfile, lockfile, server log, and the hosted-API
+# credentials file. Defined in `config` so the path has a single definition.
+STATE_DIR = config.state_dir()
 LOCK_FILE = STATE_DIR / "vllm.lock"
 PID_FILE = STATE_DIR / "vllm.pid"
 LOG_FILE = STATE_DIR / "vllm.log"

package/python/src/captchakraken/trajectory.py

@@ -0,0 +1,172 @@
+"""
+Human-like mouse trajectories for the page driver.
+
+MIRRORS, DOES NOT PORT, `cursory-ts`. The TypeScript driver calls
+`generate_trajectory()` from cursory-ts, which selects and warps a real recorded
+human trace out of a bundled ~MB corpus (`data/trajectories.json.gz`). That
+corpus is the package's own asset, so the Python port synthesises comparable
+motion instead of shipping a second copy of someone else's data.
+
+The CONTRACT is identical, which is what matters for keeping the two drivers in
+step: given a start point, an end point and a sampling frequency, return
+`(points, timings)` where `timings[i]` is the cumulative milliseconds from the
+start of the gesture at which `points[i]` should be delivered. The caller
+(`page_solver`) sleeps against those cumulative timings exactly as the TS driver
+does, so movement pacing is driver-independent.
+
+What makes the output human rather than a lerp:
+  - a Bezier arc, not a straight line (hand motion bows)
+  - Fitts's-law duration: distance and precision set the time, not a constant
+  - an ease-in-out velocity profile, so the cursor accelerates then brakes
+  - sub-pixel jitter that scales with speed (fast motion is sloppier)
+  - a small overshoot-and-correct on longer moves, which is the single most
+    recognisable human tell and the one a linear interpolation never produces
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import List, Sequence, Tuple
+
+Point = Tuple[float, float]
+
+# Fitts's law: MT = a + b * log2(distance / width + 1). The constants are the
+# usual empirical range for a mouse; `_WIDTH` stands in for target precision.
+_FITTS_A_MS = 90.0
+_FITTS_B_MS = 105.0
+_WIDTH_PX = 28.0
+
+# Below this, a move is a nudge inside one element: no overshoot, no arc.
+_SHORT_MOVE_PX = 24.0
+# Overshooting a 30px hop looks like a twitch, not a human.
+_OVERSHOOT_MIN_DISTANCE_PX = 220.0
+
+
+def _ease_in_out(t: float) -> float:
+    """Cubic ease. Real pointer motion is roughly bell-shaped in velocity."""
+    if t < 0.5:
+        return 4.0 * t * t * t
+    return 1.0 - ((-2.0 * t + 2.0) ** 3) / 2.0
+
+
+def _cubic_bezier(p0: Point, p1: Point, p2: Point, p3: Point, t: float) -> Point:
+    u = 1.0 - t
+    x = u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0]
+    y = u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1]
+    return (x, y)
+
+
+def _control_points(start: Point, end: Point, distance: float) -> Tuple[Point, Point]:
+    """
+    Two control points offset PERPENDICULAR to the travel direction, so the path
+    bows to one side. The sign is random per gesture: always bowing the same way
+    would itself be a fingerprint.
+    """
+    dx, dy = end[0] - start[0], end[1] - start[1]
+    if distance == 0:
+        return start, end
+    # Unit normal to the direction of travel.
+    nx, ny = -dy / distance, dx / distance
+    # Bow proportional to distance, but capped — long drags don't arc absurdly.
+    bow = min(distance * random.uniform(0.06, 0.16), 140.0) * random.choice((-1.0, 1.0))
+    # Control points at roughly 1/3 and 2/3 along, each pushed off-axis.
+    c1 = (
+        start[0] + dx * random.uniform(0.20, 0.40) + nx * bow,
+        start[1] + dy * random.uniform(0.20, 0.40) + ny * bow,
+    )
+    c2 = (
+        start[0] + dx * random.uniform(0.60, 0.80) + nx * bow * random.uniform(0.4, 0.9),
+        start[1] + dy * random.uniform(0.60, 0.80) + ny * bow * random.uniform(0.4, 0.9),
+    )
+    return c1, c2
+
+
+def generate_trajectory(
+    target_start: Sequence[float],
+    target_end: Sequence[float],
+    frequency: int = 60,
+    frequency_randomizer: float = 0.12,
+) -> Tuple[List[Point], List[float]]:
+    """
+    Mirror of cursory-ts `generate_trajectory`.
+
+    Returns `(points, timings)`. `timings` is CUMULATIVE milliseconds from the
+    gesture start — not per-step deltas — because that is what the TS driver's
+    `tracePath` sleeps against, and the two must pace identically.
+
+    `frequency` is samples per second (the TS driver passes 60).
+    `frequency_randomizer` jitters each frame's timestamp so the sample interval
+    is not a metronome; a perfectly periodic mousemove stream is trivially
+    detectable.
+    """
+    start: Point = (float(target_start[0]), float(target_start[1]))
+    end: Point = (float(target_end[0]), float(target_end[1]))
+
+    dx, dy = end[0] - start[0], end[1] - start[1]
+    distance = math.hypot(dx, dy)
+
+    if distance < 1e-6:
+        return [end], [0.0]
+
+    duration_ms = _FITTS_A_MS + _FITTS_B_MS * math.log2(distance / _WIDTH_PX + 1.0)
+    duration_ms *= random.uniform(0.85, 1.20)
+
+    steps = max(2, int(round(duration_ms / 1000.0 * max(1, frequency))))
+
+    # A short hop is a straight ease with jitter — bowing a 15px move looks worse
+    # than not bowing it.
+    if distance < _SHORT_MOVE_PX:
+        c1, c2 = start, end
+    else:
+        c1, c2 = _control_points(start, end, distance)
+
+    # Overshoot: on a long move the hand arrives past the target and corrects.
+    # Modelled as a longer primary gesture to a point beyond the target, then a
+    # short settle back — the settle is appended as extra samples below.
+    overshoot = distance >= _OVERSHOOT_MIN_DISTANCE_PX and random.random() < 0.55
+    aim: Point = end
+    if overshoot:
+        over = random.uniform(0.01, 0.035) * distance
+        aim = (end[0] + dx / distance * over, end[1] + dy / distance * over)
+
+    points: List[Point] = []
+    timings: List[float] = []
+    elapsed = 0.0
+    per_step = duration_ms / steps
+
+    for i in range(steps + 1):
+        t = _ease_in_out(i / steps)
+        px, py = _cubic_bezier(start, c1, c2, aim, t)
+
+        # Jitter scales with instantaneous speed: the faster the cursor is
+        # moving, the less precisely a human tracks the intended path.
+        speed = abs(_ease_in_out(min(1.0, (i + 1) / steps)) - _ease_in_out(i / steps))
+        jitter = min(1.6, 0.25 + speed * steps * 0.5)
+        px += random.gauss(0.0, jitter * 0.5)
+        py += random.gauss(0.0, jitter * 0.5)
+
+        points.append((px, py))
+        timings.append(elapsed)
+        elapsed += per_step * random.uniform(1.0 - frequency_randomizer, 1.0 + frequency_randomizer)
+
+    if overshoot:
+        # Correction: a couple of small samples back onto the true target, at the
+        # slower pace of a deliberate fine adjustment.
+        settle_steps = random.randint(2, 4)
+        origin = points[-1]
+        for i in range(1, settle_steps + 1):
+            t = i / settle_steps
+            points.append(
+                (
+                    origin[0] + (end[0] - origin[0]) * t + random.gauss(0.0, 0.35),
+                    origin[1] + (end[1] - origin[1]) * t + random.gauss(0.0, 0.35),
+                )
+            )
+            timings.append(elapsed)
+            elapsed += random.uniform(14.0, 30.0)
+
+    # Land exactly on the requested pixel. Everything above is texture; the final
+    # sample must be the point the caller asked for or clicks drift off-target.
+    points[-1] = end
+    return points, timings