# Captcha Session Handoff Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Retry a 705-blocked request only after the official browser verification endpoint reports success.

**Architecture:** Add a small Playwright adapter with pure response-parsing and cookie-transfer helpers. Keep request construction in `core.sms_login` unchanged and integrate the adapter at the two existing CLI retry points.

**Tech Stack:** Python 3.13, Playwright Python, requests, unittest.

---

### Task 1: Verification state and cookie transfer

**Files:**
- Create: `core/captcha_assist.py`
- Modify: `tests/test_sms_login.py`

- [ ] Write failing tests for token extraction, verify-result recognition, and cookie transfer.
- [ ] Run the focused tests and confirm failures are caused by the missing module.
- [ ] Implement the minimal dataclasses and pure helpers.
- [ ] Run the focused tests and confirm they pass.

### Task 2: Visible browser adapter

**Files:**
- Modify: `core/captcha_assist.py`
- Modify: `pyproject.toml`
- Modify: `uv.lock`
- Modify: `tests/test_sms_login.py`

- [ ] Write a failing test for browser response observation using an injected fake Playwright factory.
- [ ] Implement visible Edge launch, response observation, timeout handling, and structured errors.
- [ ] Add Playwright as a project dependency and refresh the lock file.
- [ ] Run adapter tests and confirm they pass.

### Task 3: CLI integration

**Files:**
- Modify: `tools/sms_login_cli.py`
- Modify: `tests/test_sms_login.py`
- Modify: `docs/sms_login_flow.md`

- [ ] Write failing CLI tests for verified and failed browser handoffs.
- [ ] Replace blind Enter-based retries with the adapter and preserve the manual fallback.
- [ ] Add browser channel and timeout CLI options.
- [ ] Update user-facing documentation.
- [ ] Run `uv run python -m unittest tests.test_sms_login`.

### Task 4: Verification

- [ ] Run `uv run python -m unittest discover -s tests -p 'test_*.py'` with a 60-second limit.
- [ ] Run `uv run python -m compileall -q core tools tests`.
- [ ] Record any unrelated pre-existing failures separately.