autoreg-skills-max/skills/ai-provider-autoreg/references/hcaptcha-farm-solving-stack.md

hCaptcha-protected registration farms — solver stack

For farms registering accounts on hCaptcha-gated sites (new-api panels like tooken.club). Covers solver ordering, paid-API flow, free-vision dead-end symptoms, proxy churn, and process hygiene.

Solver chain order (in the reg worker's solve_hcaptcha)

1. Paid 2captcha FIRST when any funded key exists — ~12s/solve, handles rotation/drag that free vision cannot.
2. Free local vision sidecar (CloakBrowser + qwen-vl) as fallback only.
3. Before assuming "no paid capacity": run a live getbalance sweep over every captcha key on disk (project stashes + keyhunter-style DBs). One funded key unblocks the whole farm; balance-check is POST-only — POST https://api.2captcha.com/res.php {key, action:getbalance} (GET/curl-from-chat misleads because auth material gets masked).

2captcha hCaptcha flow

• POST in.php {key, method:hcaptcha, sitekey, pageurl, json:1} → {status:1, request:<cid>}.
• Poll res.php {key, action:get, id:cid, json:1} every 5-6s; CAPCHA_NOT_READY = keep polling; status:1 + request >100 chars = token (hCaptcha tokens ~2300 chars — length is the sanity check).
• ERROR_CAPTCHA_UNSOLVABLE is transient — retry immediately; attempt 2-3 usually solves. Each in.php costs cents even on failure.
• Wire the paid solver as step 0 in the existing chain so free solvers remain fallback, not replacement.

Free vision sidecar — recognize the dead end fast

• Symptom: checkbox clicked=True then repeated no challenge canvas found after retries — the challenge frame never renders a canvas for rotation/drag tasks; raising the canvas-wait timeout does NOT fix it.
• Logs may show plausible progress (grid pick -> [1,7]) while final token length is 0 — hCaptcha rejected the answers. Judge by farm output (REGISTER ok count / keys file growth), never by sidecar logs.
• Model swap: sidecar honors env HCAPTCHA_MISTRAL_MODEL (plus hardcoded defaults in solve.py) — pass the env from the watchdog spawn instead of relying on edited defaults. A stale process keeps the port and runs the OLD model: check the listening PID's start time before believing a patch took effect.

Proxies for browser-based captcha solving

• urllib reachability tests overestimate pool quality: a proxy passing an 8-10s HTTP GET can still die under Playwright goto (ERR_TIMED_OUT/CONNECTION_RESET) because the browser pulls captcha frames + assets. Expect 30-60% churn; re-prune the pool when goto errors dominate the sidecar log.
• API proxy pools may return only a handful of IPs regardless of limit. Never overwrite a working pool file until the new candidate list has been live-tested against the target — build the alive list first, write after.

Farm process hygiene

• Watchdog respawns race: before restarting the stack, kill ALL matching processes (farm orchestrator + reg workers + old watchdog) in one psutil sweep, then start exactly one watchdog and verify one farm PID + expected worker count. Zombie workers from a previous generation keep burning proxies and flood the sidecar with 408s.
• Match worker count to solver latency: ~1 worker for slow free-vision solves (serialized under a lock, 400s+ timeouts); 3+ workers once paid solving (~12s) is primary.

Secrets handling

• Write captcha API keys to a standalone file via python string concatenation in terminal — write_file masks key-looking assignments and yields truncated keys (ERROR_WRONG_USER_KEY). Read the key from the file at runtime; verify length (2captcha = exactly 32 hex).