# Captcha Session Handoff Design

## Goal

Replace the blind `webbrowser.open() + Enter` retry with an observable browser
handoff. A user completes the official challenge in a visible browser; the CLI
waits for the official verification request to succeed, synchronizes cookies,
and only then retries the original API request.

## Scope

Included:

- Open the HTTPS `error_url` in the normal system browser by default.
- Observe `kSecretApiVerify` and extract a masked `captchaToken` for diagnostics.
- Observe `/rest/wd/captcha/verify` and require a successful JSON result.
- Copy browser cookies into the current `requests.Session`.
- Preserve the current device profile, signed request body, and retry limits.
- Fall back to the existing manual browser flow when Playwright is unavailable.

Excluded:

- Image recognition, slider movement, trajectory generation, or fingerprint
  fabrication.
- Replaying captured captcha tokens.
- Treating a page close or terminal Enter as successful verification.

## Architecture

`core/captcha_assist.py` owns the optional Playwright observation details and
exposes one public operation returning a structured result. The CLI defaults to
the regular system browser because Playwright-launched Edge exposes
`navigator.webdriver=true`; `msedge/chrome` remain explicit diagnostic modes.
Pure helpers parse response payloads and synchronize cookies so they can be
tested without launching a browser.

## Data Flow

```text
705 error_url
  -> visible Edge page
  -> user completes official challenge
  -> observe kSecretApiVerify / captchaToken
  -> observe /rest/wd/captcha/verify result=1
  -> copy browser cookies to requests.Session
  -> retry the unchanged checker or mobileVerifyCode request
```

## Error Handling

- Reject non-HTTPS challenge URLs before browser launch.
- Report missing Playwright separately from browser launch errors.
- Stop on timeout, page close, malformed verification JSON, or non-success
  verification response.
- Never print the full captcha token unless the existing secret-display option
  is explicitly enabled.

## Testing

- Unit-test recursive token extraction and verification-result recognition.
- Unit-test browser-cookie transfer into a requests-compatible jar.
- Unit-test that CLI retries after a verified handoff and does not retry after
  a failed handoff.
- Run the focused SMS login tests and Python compilation checks.