ba-auto-daily/plan.md

# ba-auto-daily implementation plan

Personal Blue Archive JP daily-automation project. `CLAUDE.md` is the authoritative, actively-maintained reference for architecture, deployment, conventions, and the incident history behind current design decisions — read it first. This file is intentionally scoped to **forward-looking work only**: the not-yet-implemented backlog and active improvement plans. It no longer carries a phase-by-phase changelog; that history (30+ phases of live-testing retrospectives) has been retired now that every feature it covered has shipped and CLAUDE.md's "Existing features" section carries the load-bearing lessons from it.

The reference implementation lives at `~/repo/baas-reference/` (read-only — study and adapt, never edit). See `ba_auto/reference_notes/mapping.md` for the current, maintained local-feature → reference-module mapping table.

## Currently implemented (for context, not a todo list)

`login`, `mailbox`, `cafe`, `stamina`, `gem_shop`, `circle`, `battle_pass`, `story_sweep`/`story_sweep_force`, `story_sweep_hard`/`story_sweep_hard_force`, `event_sweep`, `shop_common`, `shop_tactical`, `lesson`, `arena`, `bounty`, `scrimmage`, `exit_game` — see `ba_daily.py`'s `TASKS` dict for the exact CLI surface and `CLAUDE.md`'s "Existing features" section for behavior/known gaps.

## Backlog — not yet implemented

### Commissions (Base Defense + Item Retrieval)

Reference: `~/repo/baas-reference/module/clear_special_task_power.py`
Local target: `ba_auto/tasks/commission.py`

Two sub-dungeons. OCR: port the reference's approach if it uses OCR here — do not default to a fixed-target workaround just to avoid OCR (see `CLAUDE.md`'s OCR policy).

### Crafting

Reference: `~/repo/baas-reference/module/create.py`
Local target: `ba_auto/tasks/crafting.py`

Very complex — material selection, priority lists, rarity tiers, stepper/quantity UI, filtering/sorting, OCR-like decision points. Do not start until there's a concrete need; this is the most complex remaining reference module.

### Momo Talk

Reference: `~/repo/baas-reference/module/momo_talk.py`
Local target: `ba_auto/tasks/momo_talk.py`

Runs on a different cadence from daily reset, which is why it's still worth doing despite being low-value. Likely no OCR — mostly state scanning and click flow.

### Main story push (new-stage clearing, not sweeping)

Reference: `~/repo/baas-reference/module/main_story.py`, `~/repo/baas-reference/module/explore_tasks/explore_task.py`

Distinct from `story_sweep`/`story_sweep_hard` (which only re-sweep already-cleared stages). Low priority — full grid-mode support needs a lot of per-stage scripting; a simple auto-fight-only mode could be a smaller first cut. No reusable auto-fight primitive exists yet — `arena.py` implements its battle-commit/result-detection inline rather than as a shared module, so this would either need extracting that or building fresh.

### Group Story / Mini Story

Reference: `~/repo/baas-reference/module/group_story.py`, `~/repo/baas-reference/module/mini_story.py`

Convenience only, low priority.

### Event content beyond the AP sweep panel

`event_sweep.py` already covers the sweep panel for a currently-running event (see `CLAUDE.md`). Still not built: `explore_activity_story`/`explore_activity_mission`/`explore_activity_challenge` (walking the event's map / fighting stages manually — only needed for a stage that hasn't been SSS-cleared yet) and `exchange_reward` (the reward-exchange shop). Event-specific content expires, so any calibration work here (stage-count, row positions) is only valid for whichever event is running at the time.

### Daily Free Power

Reference: `~/repo/baas-reference/module/collect_daily_free_power.py`

Deliberately deferred, not merely unstarted — its entry point is a real-money purchase menu, and automating it needs explicit user confirmation before any implementation attempt.

## Skip list

| Feature | Why skip |
|---|---|
| Total Assault / Raid | Low value and risky to automate. Reference support may be limited/stubbed. |
| Joint Firing Drill | Not worth prioritizing for JP if reference has server-specific limitations. |
| De-clothes localization toggle | CN-only / irrelevant. |
| Restart / refresh-uiautomator2 | Android/ADB backend maintenance, not applicable to PC/Steam/Proton. |
| Auto-unfriend | Risky, low value, destructive. |
| Daily minigame dispatcher | Event-specific and unstable. Handle ad hoc only. |

## Performance improvement plan (opened 2026-08-14)

Prompted by a request to review real cron run logs (`scratchpad/ba_logs/{daily,q4h}.log`, pulled from nik-gpu, covering 3 `q4h` runs + 2 `daily` runs on 2026-08-14) for where automation time actually goes and what's worth speeding up. Timestamps come from the per-line logging added in the "timestamped log output" work (see git history / `CLAUDE.md`'s log-format notes).

### Measured totals

| Run | Total | Notes |
|---|---|---|
| q4h #1 (10:00) | 9m56s | |
| q4h #2 (13:00) | 8m45s | |
| q4h #3 (17:00) | 9m13s | |
| daily #1 (03:30) | 15m32s | |
| daily #2 (04:30) | **27m20s** | full run, 7 lesson tickets spent |

### Finding 1 (implemented 2026-08-14): `lesson.py` re-screenshots per cell instead of per region

In the 27m20s `daily` run, `lesson` alone took 9m50s (36% of the run), and ~7 minutes of that is the "scanning all regions" phase — 12 regions × ~30-38s each — that runs *before any ticket is spent*, just to build the priority queue.

Root cause, confirmed by reading the code: `_scan_open_grid_cells` (`ba_auto/tasks/lesson.py:196`) loops 3 rows × 3 cols × 3 slots = 27 cells per region, and `_read_slot_affection` (`lesson.py:185`) calls both `detector.region_contains_color` (checkmark check) and, if not done, `detector.read_int_on_heart_badge` (OCR). Both independently call `driver.read_screenshot()`, and `read_screenshot()` fires a **brand-new `scrot` capture every call** (`ba_auto/driver.py:97-127`) — there's no reuse of a prior frame. That means a single region scan can trigger up to ~50 fresh `scrot` processes against a screen that hasn't changed at all between them (no clicks happen mid-scan, per `_scan_all_regions`'s own docstring: "a pure read, spends no tickets").

**Fix:** `detector.py` gained an optional `image=` parameter on `region_contains_color`/`read_int_on_heart_badge` (default `None`, so every other caller — `shop_utils.py`, `story_sweep.py`, `story_sweep_hard.py`, `cafe.py` — is unaffected) plus a `capture_screen()` helper. `lesson.py`'s `_scan_open_grid_cells` now takes one screenshot per region and threads it through all 27 checkmark/OCR reads instead of each one re-capturing. Pure efficiency fix — the detection logic itself (color masking thresholds, heart-badge OCR contamination handling) is untouched.

**Scope respected:** `_run_queue`'s actual ticket-spending clicks (`lesson.py:306`+) still take a fresh screenshot per check, exactly as before — batching only applies to the pure-read scan phase.

**Live-verified 2026-08-21** against a full week of real `daily` cron runs (2026-08-15 through 2026-08-21, 14 runs, all exit 0, zero `[lesson]` warnings/errors). Full 12-region scan phase now consistently takes ~3m27s, down from the ~7m2s baseline — a ~51% cut, exactly from removing the redundant per-cell `scrot` calls (per-region time dropped from ~30-38s to ~17-18s).

### Finding 1b (implemented 2026-08-14): stop scanning once triples alone cover the ticket count

Added alongside Finding 1: `_scan_all_regions` now takes `tickets` and tracks a running triple count, breaking out of the region loop once `triple_count >= tickets`. This is provably behavior-preserving, not just a heuristic: `_build_priority_queue` never reorders within a tier (triples/doubles stay in scan order) and `_run_queue` stops the instant tickets hit 0, so once enough triples are found, any cell in an unscanned region could only ever land after the ticket budget is already exhausted — `_run_queue` would never reach it either way. The queue actually executed is identical to a full scan's; only the number of regions looked at changes. When tickets exceed available triples, the condition never fires and behavior is unchanged (full scan, as today). One cosmetic side effect: the "N triple(s), M double(s), K single(s)" summary log line under-reports M/K when this fires, since those regions were never examined — expected, not a bug.

**Live-verified 2026-08-21**, same week of runs: fired correctly on 2 of 7 ticket-available days (2026-08-18: 7 triples found by region 9/12, skipped the remaining 3; 2026-08-21: 7 triples by region 10/12, skipped 2), and correctly stayed a full 12-region scan on the other 5 days where triples never reached the ticket count. Combined with Finding 1, total `lesson` task duration (start to `Done.`) ranged 5m6s-6m41s across the week, down from the 9m50s baseline.

### Finding 2 (secondary, informational — do not touch without care): `event_sweep` is called 2-4x per run by design

`ba_daily.py`'s `daily` preset calls `event_sweep` four times, `q4h` twice (`ba_daily.py:132-144`) — deliberately, per the preset's own comment, "to re-check a rotating target" as AP regenerates from `circle`/`gem_shop`/`battle_pass` claims during the run. Each call that doesn't short-circuit on insufficient AP costs 56s-153s in the logs, mostly navigation to the event badge/page. Total `event_sweep` cost across a run's multiple calls ranged from ~112s (2 skips + 2 clean 56s sweeps) to ~430s (3 calls, one hitting the slow "wrong page" retry path) in the sampled runs.

This is **not recommended as a fix target right now**: the retry/settle budget the "wrong page" path uses (badge-carousel navigation, cold-start OCR settle time) was tuned across many rounds of real live-testing failures before it reached its current reliability — shrinking it risks reintroducing missed/silently-failed sweeps, which is a strictly worse outcome than a slow-but-correct run. If run time here ever needs to come down, the safer lever is reducing *how many times* `event_sweep` is invoked per run (e.g. consolidating to fewer, better-timed calls once AP-granting tasks have run) rather than shrinking any per-call retry/wait constant.

### Other observations (not action items)

- `cafe`'s pat-loop panning cost (~4-5 min/run) is inherent to the sparkle-hunt approach and matches reference behavior — not a target.
- `shop_common`'s full-grid OCR name scan costs ~100-120s/run when most/all configured items are sold out — inherent to the OCR-based item-identification fix from the sold-out-reordering incident (see `CLAUDE.md`'s Common Shop notes); not a target without changing correctness guarantees.