autoreg-skills-max: initial public release (restored, redacted, hardened)

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

@@ -0,0 +1,30 @@
+# 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).