# Next session: manual-pick rules, then finish the 250-line cap

Paste this whole file as the first prompt of a fresh session. Everything needed
is below; you should not need the previous session's transcript.

Repo: `~/steam-backlog-enforcer`. Work on `main`. HEAD is `0f25fba`.

---

## Task 1 (do this first): change the manual-pick rules

kuhy hit this and wants it changed:

```
./run.sh pick-manual 3164500      -> Error: you already have 3 manual pick(s).
./run.sh abandon-pick 495890      -> Grace period EXPIRED ... closed 3.7 day(s) ago.
./run.sh abandon-pick 618510      -> Grace period EXPIRED ... closed 3.3 day(s) ago.
```

He is stuck: three picks locked in, and the 4-day grace window closed on two of
them, so nothing can be abandoned and no new pick can be added.

**The change he asked for, verbatim:**
"allow to abandon pick at any time but reduce number of manual picks to max of 2"

So:

1. **Abandon at any time** — drop the grace-window restriction entirely.
   - `_manual_pick_lifecycle.py:73` `can_abandon_manual_pick()` currently returns
     `remaining is not None and remaining > 0`. It should return whether the pick
     exists at all, regardless of elapsed time.
   - `_manual_pick_lifecycle.py:87` `abandon_manual_pick()` has the matching
     guard; the docstring says "if still inside its grace window" — update it.
   - `MANUAL_GRACE_DAYS = 4` is declared in **two** places:
     `_actions.py:33` and `_manual_pick_lifecycle.py:40`. Decide whether the
     constant still has a purpose after this change (see "open question" below)
     and do not leave two divergent copies.
   - `manual_pick_grace_remaining()` (`_manual_pick_lifecycle.py:47`) also feeds
     `status_payload()` at line 162 as `grace_days_left`, and `run.sh status`
     prints "undoable for N more day(s)". If grace no longer gates anything,
     that display is now a lie — either drop it or restate it.

2. **Max picks 3 → 2** — `config.py:63`, `max_manual_picks: int = 3`.
   - kuhy's `~/.config/steam_backlog_enforcer/config.json` does **not** set this
     key, so it takes the default; changing the default is sufficient and no
     config migration is needed. (Verified.)

**Open question — ask kuhy before implementing, it changes the design:**
He currently has **3** picks locked and the new max is **2**. What should happen
to the existing over-cap state? Options: leave the 3 in place and simply refuse
new picks until he abandons down to 2 (least surprising); or force him to
abandon one now. `manual_pick_slots_left()` (`_actions.py:89`) returns
`max_picks - len(picks)` and will go negative — check every caller handles that,
particularly `main/picks.py:109`.

**Verify by running, not just tests** (repo CLAUDE.md requires this):
```
./run.sh status                 # read-only, safe
./run.sh abandon-pick 495890    # MUTATES STATE - confirm with kuhy first
```
`./run.sh` with **no args defaults to `done`**, which completes the current game
and reassigns. Never run it bare. `status` and `list` are the read-only ones.

---

## Task 2: finish the 250-line cap campaign (user-approved, in progress)

Three files remain. The gate is `bash scripts/check_file_length.sh --all`
(**trust the exit code only** — `| tail` and `grep -c` both report misleadingly).

```
_stats.py:       523 lines (over by 273)
scanning.py:     521 lines (over by 271)
_web_dataset.py: 436 lines (over by 186)
```

Everything else in `pre-commit run --all-files` already passes, so these three
are the only thing between the repo and a working `git push`.

### The method that works: leaf-set extraction ONLY

Extract functions that call **nothing else in their own module**. That keeps
every new import one-way, so no cycle is possible. Splitting on any other
boundary produced circular imports three separate times, and one of them broke
`./run.sh` while kuhy was using it.

Helper scripts from the last session (outside the repo, so they don't dirty git):
`/tmp/claude-1000/-home-kuhy/0f40b913-131e-43b9-b353-23de8c80a8c8/scratchpad/`
- `leaf_split.py` — run with just a module name to LIST its leaves; add
  `--new <mod> --doc "..." --names ... --apply` to perform the split.
- `missing_names.py` — reports names a module uses but never binds. Run it on
  `steam_backlog_enforcer/*.py` after every split; this catches the fallout
  immediately instead of via 30 confusing test failures.
- `retarget.py`, `add_getattr.py` — of limited value, see the warning below.

If `/tmp` has been cleared, `leaf_split.py` is ~90 lines and easy to rewrite:
parse the module, find `FunctionDef`s whose bodies call no sibling function,
move those plus a copy of the module header into a new file, and add a
top-level `from ... import (...)` back in the original.

### Traps that cost the last session hours

- **`_web_dataset` is the hard one.** Its dataclasses (`WebGame`,
  `WebStateInfo`, `WebDataset`, `PaceVsHLTB`, `DefaultSummary`, `WebDefaults`)
  are used by both the parent and the helpers, so they must go to their own
  **leaf model module** that both import — not stay in the parent. Getting this
  wrong is what broke `run.sh`.
- **`ruff-format` silently deletes bottom-of-file re-export imports** (the
  comment above them survives, so it looks intact). Put re-exports at the top,
  or serve them through a module `__getattr__`.
- **A module `__getattr__` re-export** needs: `importlib.import_module` (a call,
  so no `PLC0415`), and a `_Reexport: TypeAlias = Any` return annotation —
  `object` fails mypy at the call sites, bare `Any` fails ruff `ANN401`.
  Working examples already in the tree: `_actions.py`, `_whitelist.py`,
  `hltb.py`, `_cmd_done.py`.
- **Patch-target rule**: the target is the module whose **source file contains
  the function under test** — not where a helper is defined, not where the test
  imports from. Fix these **per file from the pytest failure list**. Six
  attempts at bulk regex retargeting had a net effect of −11 tests; per-file
  diagnosis worked every single time.
- **`@dataclass` decorators**: when copying a module header, include decorator
  lines in the boundary or you strand a bare `@dataclass` (fails with a
  confusing `'function' object has no attribute '__mro__'`).
- **Stale `.mypy_cache`** after moving symbols → `AssertionError: Cannot find
  component`. `rm -rf .mypy_cache`; it is not a real error.

### Non-negotiables

- **Use `.ci-mirror-venv/bin/python` for pytest**, not system python3 — the
  latter has mcp 2.0 against a pinned mcp<2, so `test_mcp*.py` cannot collect
  and coverage reads ~97% instead of 100%.
- Baseline to preserve: **1347 tests, 100.00% coverage**.
- **Verify with the coverage run before committing**, not `--no-cov`. Last
  session committed 3 failures after misreading a `--no-cov` run as green.
- Never `--no-verify`. Never add `# noqa` without asking.
- **The service auto-restarts from this tree** (`Restart=always`,
  `PYTHONPATH` pointed here). After any edit that could break imports, run
  `PYTHONPATH=. python3 -c "import steam_backlog_enforcer.main"` before moving
  on, and check `systemctl show steam-backlog-enforcer -p NRestarts --value`.
- **Test runs can write to real config.** Two leaks were found and sealed last
  session (`exception_audit.log`, `owned_app_ids_cache.json`), both caused by a
  path constant moving to a new module while `tests/conftest.py` kept patching
  the old one. After any split that moves a module-level path constant, md5sum
  `~/.config/steam_backlog_enforcer` before and after a full suite run.

### When the cap is clear

`git push` (13 commits are waiting, including another session's `2ad8752` for
`install.sh`). The pre-push ci-mirror runs `pre-commit --all-files` over the
whole tree, which is why the cap has to be fully clear first.

---

## Context: what the last session actually fixed (already committed, verified)

`21fe2f7` + `919ecdf` — the enforcer was launching Steam **as root**, so Steam
answered with a `zenity` modal reading "Cannot run as root user" on kuhy's
screen. Root cause: `game_install._get_real_user()` read only `SUDO_USER`/`USER`,
neither of which systemd sets, so it returned `None` and every
`geteuid() == 0 and real_user` guard fell through to running as root. It also
caused a retry storm — 1656 attempts in 30 minutes at 1.5 GB RSS. Both fixed and
verified in production (`sudo -u kuhy env DISPLAY=:0 ... steam`, every Steam
process at uid 1000, 0 retries, ~244 MB).

Do not re-litigate that fix; it is done. Tasks 1 and 2 above are what remains.