ecw-charge-validation/docs/superpowers/specs/2026-10-14-start-bot-from-web-page-design.md

# Start the bot from the results web page — design

Date: 2026-10-14. Approved section by section by the operator in chat
(approach A, sections 1–3).

## Goal

The operator starts a Charge Validation run from the local results page
(`run_web.bat` → http://127.0.0.1:8000) instead of the terminal. While it
runs, the page shows live status; it can stop it; when it ends, the page
shows that run's results.

## Decisions (operator, 2026-10-14)

| Question | Answer |
|---|---|
| Controls | Start + live status + Stop (no settings editing on the page) |
| Save mode | **VERIFY only.** A page-started run is always `SAVE_CORRECTIONS=0`, whatever `.env` says. LIVE-WRITE stays terminal-only. |
| Message boxes | **Off** for the run's information boxes (per-claim, review-before-close, "Run the Lookup?", summaries). Boxes that need a person to act in the browser — CAPTCHA, 2FA manual step, security image — **stay on**. |
| Approach | A: the web server starts `run.py` as a separate child process (not a thread, not Task Scheduler). |

Out of scope (YAGNI): editing settings from the page, scheduling, more than
one run at a time, LIVE-WRITE from the page.

## Components

### New: `web/bot_runner.py` — process control only

- `start() -> dict` — starts `python run.py` (the project's own `run.py`,
  `sys.executable`, cwd = project root) as a child process with no console
  window of its own (`CREATE_NO_WINDOW`); the Chrome window still shows.
  The child's stdout/stderr go to `Logs\web_run_<ts>.out`, which catches a
  crash before the bot opens its own log; the bot's `Logs\run_<ts>.log`
  (named in the lock file) is the status source.
  Refuses (raises `AlreadyRunning`) when the lock file names a live pid.
- `stop() -> dict` — `taskkill /PID <pid> /T /F`: the bot and its Chrome
  close together. Clears the lock file. Status becomes "Stopped by
  operator".
- `status() -> dict` — `running` (bool), `pid`, `started_at`, `log_path`,
  `exit_code` (when this web process started it and it has ended),
  `stopped_by_operator`.
- The command is fixed. Nothing from the request reaches the command line
  or the environment.

**Child environment** — set on the child process, so it wins over `.env`
(`settings.py` loads `.env` with `os.environ.setdefault`):

```
SAVE_CORRECTIONS=0
ECW_KEEP_OPEN=0          # no "Press Enter to close" at the end
QUIET_BOXES=1            # run-flow information boxes go to the log
CONFIRM_BEFORE_LOOKUP=0
```

Everything else follows `.env` (claim file, `CLAIM_PROCESS_LIMIT`,
`RESULTS_DB`, proxy, ...).

### Lock file: `Logs\bot_run.json`

`{"pid", "started_at", "log_path", "source": "web" | "terminal"}`.

- Written by the **bot itself** at the start of `main()` (after
  `runlog.start()`, so `log_path` is known) and removed when `main()`
  returns — so a terminal run is seen by the page too.
- Before writing it, `main()` refuses to start (exit 2, before login) when
  the file names a pid that is alive: two runs would share one eCW login
  guard and one Charge Summary.
- A file naming a dead pid is stale: removed and ignored (a killed run
  cannot remove its own file).
- `bot_runner.start()` checks it too, so the page answers 409 at once.

### New: `web/run_status.py` — read the run log

Pure functions over log text (no I/O except reading the file tail):

- **Phase** from the last matching line:
  `[LOGIN]` / `[CAPTCHA]` → "Logging in"; `[OTP]` / `[2FA]` → "Waiting for
  the 2FA approval mail"; `[OK] Logged in` → "Logged in"; `[CLAIMS]` →
  "Checking claims"; process ended → "Finished" or a failure text by exit
  code.
- **Progress** from `[CLAIMS] --- claim n/N: <id> ---` → `n`, `N`, current
  claim id.
- **Counts** from the new `[RESULT]` lines (below) → Pass / Fail / Review.
- **Tail**: the last 30 lines.
- **Exit codes** (from `flows/export_medcor_ready.main`): 0 finished; 2
  config / mode gate; 3 login guard refused (its `[GUARD]` line shown); 5
  claims phase failed; 6 2FA timed out; other → "ended with code N".

### Changed: `flows/export_medcor_ready.py`

- After each claim's outcome is known in `_process_claims`, one
  machine-readable line (terminal runs print it too):

  ```
  [RESULT] claim 3/7 9126000: Review
  ```

  The word is the Category the Charge Summary gets for that claim; a claim
  that gets no Charge Summary row (not found in the grid) prints
  `Not found`.
- `main()` writes / removes the lock file as above.

### Changed: `core/msgbox.py`

- New setting `QUIET_BOXES` (default off; `settings.py`).
- `info_box(title, msg, needs_person=False)`: with `QUIET_BOXES=1` and
  `needs_person=False`, no box — one log line instead:
  `[BOX] <title>: <first line of msg>`.
- `ok_cancel` / `confirm` are unchanged (every remaining caller is a
  person-needed step: CAPTCHA, 2FA manual, LIVE-WRITE confirm — the last
  is never reached in VERIFY). The security-image `info_box` in
  `auth/login.py` passes `needs_person=True`.

### Changed: `web/app.py` + `web/templates/index.html`

Endpoints:

| Method | Path | Answer |
|---|---|---|
| POST | `/api/bot/start` | 200 `{status}`; 409 already running; 403 bad Origin/token |
| POST | `/api/bot/stop` | 200 `{status}`; 409 nothing running; 403 bad Origin/token |
| GET | `/api/bot/status` | `{running, phase, progress, counts, tail, started_at, exit_code, message}` |

Page: a "Bot run" card above the results.
- Idle: **[Start run]** and "VERIFY mode — nothing is saved to eCW".
- Running (polls `/api/bot/status` every 2 s): phase, progress bar
  "3 / 7", current claim, Pass/Fail/Review chips, collapsible "Live log"
  (last 30 lines), **[Stop]** (with a confirm dialog).
- Ended: "Finished in 4m 12s — exit 0" (or the failure text); the results
  table reloads on the newest run.

## Security

The page was read-only; Start/Stop are its first actions. The existing
TrustedHost check stops DNS rebinding but not a cross-site POST from
another tab, which could burn eCW login attempts. So every POST needs both:

1. `Origin` (or, when absent, `Referer`) is `http://127.0.0.1:8000` or
   `http://localhost:8000` — else 403.
2. Header `X-Run-Token` equals a token made at server start
   (`secrets.token_urlsafe(32)`) and embedded in the page — else 403.
   Compared with `secrets.compare_digest`.

No password on the page; `.env` credentials are read only by the bot.
Responses keep `no-store`. The page stays bound to 127.0.0.1. The live log
tail can carry PHI, as the results table already does — local only.

## Error handling

- Already running (page or terminal) → 409 "A run is already going
  (started HH:MM)".
- Guard refused (exit 3) → the `[GUARD]` line shown ("next attempt
  allowed at ...").
- Stop mid-claim: the claim form may stay open in eCW. VERIFY saves
  nothing; the next run's `clear_screen` closes it.
- Web server restarted or page closed: the bot keeps running; on reload
  the page finds it through the lock file. `exit_code` is unknown then
  (the run is shown "Ended" when its pid is gone).
- Log file not there yet → phase "Starting".

## Testing (standalone "N/M passed" scripts)

- `tests/test_bot_runner.py` — a fake child script in place of `run.py`
  (injectable command): start → running → stop → stopped; second start →
  `AlreadyRunning`; stale lock (dead pid) cleared; the child sees the forced
  env (`SAVE_CORRECTIONS=0`, `ECW_KEEP_OPEN=0`, `QUIET_BOXES=1`,
  `CONFIRM_BEFORE_LOOKUP=0`) even when the parent env says otherwise.
- `tests/test_run_status.py` — sample log text → phase, progress, counts,
  tail; each exit code's text.
- `tests/test_web_app.py` (added cases) — POST without/with wrong Origin or
  token → 403; right Origin + token → 200 (runner stubbed); status JSON
  shape; the token is in the page.
- `tests/test_msgbox.py` (added cases) — `QUIET_BOXES=1`: info box logged,
  not shown; `needs_person=True` still shown.
- Flow test — `[RESULT]` line per claim; `main()` lock file written,
  refused on a live one, removed at the end.