CAPTCHA and bot walls (ChallengeGate)

When a site shows Cloudflare “Just a moment…”, reCAPTCHA, hCaptcha, Turnstile, or similar, VibeOS must not spam clicks or invent page content. Load the bundled skill challenge-gate and follow layers L0→L4.

This is not a guide to breaking site security. The product path is: detect → avoid → one optional provider assist → you solve in a live browser → resume, or continue with a partial brief.

Quick path (operators)

# Readiness includes ChallengeGate + optional Browserbase
vibeos research doctor

# Fill empty web.* and missing browser.challenge.* defaults
vibeos research preset research-pro --apply

# Deep pack: ChallengeGate checklist + Browserbase cloud_provider + scrapling note
vibeos research preset research-deep --apply

# Offline smoke (no live CAPTCHA)
scripts/smoke-challenge-gate.sh

# Offline handoff demo (clarify + resume contract + L4 artifacts)
scripts/demo-challenge-gate-handoff.sh

# Scaffold a workspace (includes challenge.md)
vibeos research run --topic "…" --mode brief

Desktop: Settings → Research Pro shows challenge / Browserbase / CDP pills and the same Apply behavior.

Manual E2E (live soft/hard walls, Done/Skip, CDP resume): see docs/ops/challenge-gate-manual-e2e.md in your VibeOS checkout.

Layers (plain language)

Layer	Meaning
L0 Detect	`browser_navigate` returns `challenge` / `bot_detection_warning`
L1 Avoid	Prefer `web_search` / `web_extract` / MCP OAuth; one gentle retry for soft walls
L2 Provider	Optional Browserbase stealth/proxies if configured — once
L3 Human	Agent asks via `clarify`; you solve; reply `готово` or `done`
L4 Partial	Mark `access: blocked_by_challenge` in `sources.json`, log `challenge.md`, continue

Skills that forbid bypass (e.g. ru-public-sources) skip L2 and go Detect → optional Human → L4.

What you do when the agent asks

Open the live browser window (local headed browser, Browserbase Live View, or Chrome attached with /browser connect / browser.cdp_url).
Complete the CAPTCHA yourself (do not paste passwords into chat).
Prefer Open live browser when the clarify text includes a Browserbase Live View URL (same cloud session / cookies). Otherwise use your headed Chrome / CDP window.
Reply готово or done — desktop Solve CAPTCHA also offers Done, Skip page, and Research Pro settings.
If you cannot: reply пропустить / skip — the brief continues without fabricating that page.

Template text for agents:
skills/research/challenge-gate/templates/human-handoff.md

Kanban / cron

Long research tasks should block with kind=challenge (status remains blocked, assignee becomes human) when waiting on a CAPTCHA:

vibeos kanban block <task-id> --kind challenge --reason "CAPTCHA on vendor catalog"
# → Blocked … (kind=challenge, assignee=human)

Cron must not keep unblocking and re-hitting the wall overnight — deliver a partial brief / alert instead. Recipe: docs/ops/cron-research-challenge.md. The unblock-loop breaker escalates to triage if unblock↔re-block spins.

Opt-in live detect-only (never solves):

RUN_LIVE_CHALLENGE_DETECT=1 CHALLENGE_GATE_LIVE_URL='https://…' \
  scripts/smoke-challenge-gate-live-detect.sh

# Cookie-resume prep — leave session open for Scenario E follow-up:
CHALLENGE_GATE_KEEP_SESSION=1 RUN_LIVE_CHALLENGE_DETECT=1 \
  CHALLENGE_GATE_LIVE_URL='https://…' \
  scripts/smoke-challenge-gate-live-detect.sh

Operator checklist: docs/ops/challenge-gate-manual-e2e.md (Scenario E) and docs/ops/capability-operator-runbook.md.

Logging helper

python3 skills/research/challenge-gate/scripts/append_challenge_log.py \
  --path challenge.md --also-sources sources.json <<'EOF'
{"url":"https://example.com","type":"cloudflare_iuam","severity":"hard","detected_by":"title","layer_reached":"L4","resolved":"no","human_handoff":"yes","notes":"skipped"}
EOF

Desktop: if the inline Solve CAPTCHA panel is scrolled away, a floating banner near the composer still offers Done / Skip / Research Pro.

Config (`config.yaml`)

browser:
  challenge:
    prefer_human: true          # default
    max_auto_attempts: 1
    human_timeout_seconds: 600
    allow_provider_solve: true  # Browserbase/Firecrawl assist when available
    record_artifacts: true      # write challenge.md in research workspaces
  cdp_url: ""                   # optional: attach your Chrome for trusted cookies

Secrets stay in .env: BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID (optional). Behavioral knobs stay in config.yaml.

Research artifacts

File	Role
`challenge.md`	Log of walls hit and layers reached
`sources.json`	Per-URL `access`: `ok` \| `challenge` \| `blocked_by_challenge` \| `partial`
`brief.md`	Must acknowledge blocked sources (eval harness checks this)

Skill: skills/research/challenge-gate/SKILL.md
Routing: choose-interaction-surface (CAPTCHA taxonomy: web vs native)
Computer use: never first choice for browser CAPTCHA — see computer-use skill
Research stack: Professional research
Desktop: clarify panel detects CAPTCHA copy → Done / Skip / Research Pro
Kanban: vibeos kanban block <id> --kind challenge …
Offline golden titles: tests/tools/fixtures/bot_wall_titles.yaml
Golden tasks: docs/plans/challenge-gate-golden-tasks.yaml
Plan addendum: docs/plans/2026-07-17-captcha-challenge-protocol.md

Quick path (operators)​

Layers (plain language)​

What you do when the agent asks​

Kanban / cron​

Logging helper​

Config (config.yaml)​

Research artifacts​

Related​