Vacation handoff 24e + commit the state-stream diff dataset (task #8)

r17a stopped deliberately at epoch 48 (resume point: the epoch-40 trainer
snapshot, also backed up to b2:exphil-artifacts/checkpoints/2026-07-24/).

test/fixtures/statestream/: two same-game pairs — the .slp Dolphin wrote
AND the recorder's live per-frame trace of that identical run. This is the
dataset for GOTCHAS #81 phase 1 (derive the exact parsed-vs-live
action_frame mapping), sized to need no GPU and no Dolphin so it can be
worked on a laptop.

HANDOFF_2026-07-24e: laptop work menu (state-stream diff, rung-1 design,
A3 metric, full test suite), the home-only queue (r17a resume + score,
policy re-gate), and the resume command.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: blasphemetheus

docs/planning/HANDOFF_2026-07-24e.md

@@ -0,0 +1,120 @@
+# HANDOFF 2026-07-24e (~08:35) — VACATION EDITION. Supersedes 24d.
+
+Written for laptop-only work (**no GPU, no Dolphin**) Jul 24–29. Everything
+is on `origin/main`; nothing needed for the laptop tasks lives only on the
+desktop. 24c/24d hold the deep narrative; GOTCHAS #78–81 hold the law.
+
+## State at handoff
+
+- **r17a was STOPPED deliberately at ~08:25** (Bradley's call, to free the
+  machine). It had reached epoch 48/100, healthy, all four levers confirmed
+  (incl. `probe-reg refit: true, shield_rows: 165` at every refit).
+  **Resume point: the epoch-40 trainer snapshot** — epochs 41–48 are lost
+  (~1.6h), by design. The stack trace at the end of
+  `logs/overnight_newera8_r17a_20260724.log` is the SIGTERM, not a crash.
+  - Local: `checkpoints/mewtwo_combo_newera_r17a_r13_policy.bin.trainer.ckpt`
+    (+ `_latest.bin`, both 06:27 = epoch 40)
+  - **Backed up to `b2:exphil-artifacts/checkpoints/2026-07-24/`**
+  - Resume (home, after vacation):
+    `nohup setsid devenv shell -- bash scripts/launch_r17a_resume.sh > logs/r17a_launcher_resume.log 2>&1 < /dev/null & disown`
+    then confirm the four levers in the drill log (R17A_RUNBOOK.md).
+- GPU idle, no training anywhere. `mix` is safe again, everywhere.
+- Multishine: teacher track DONE (fixture max chain 186, table teacher live
+  103, BC loss 0.00148). Policy gate BLOCKED on the state-stream shift below.
+
+## THE LAPTOP TASK — #8 phase 1, deliberately sized for this trip
+
+**Finding (GOTCHAS #81):** a replay-trained policy does not run on the
+features it was trained on. Same weights: 99.3% button agreement fed PARSED
+fixture states; collapses to a constant (B=100%, X=0.1%, never shines) fed
+LIVE bridge states. Peppi and libmelee disagree on `action_frame` (parsed
+jumpsquat af 0,1,2 vs live 1,2,3; 365 agrees; varies per action). The
+training loss lives entirely in parsed space, so no run can reveal this.
+Plausibly touches EVERY policy; only frame-perfect tech made it visible.
+
+**Phase 1 needs no GPU and no Dolphin, and the data is already committed:**
+`test/fixtures/statestream/` has two same-game pairs — the .slp Dolphin
+wrote AND the recorder's live per-frame trace of that identical run (see its
+README for format and an alignment hint). Write the diff script:
+
+1. Parse each .slp (Peppi is a Rust NIF — CPU fine), align frames to the
+   trace on the first jumpsquat entry (NOT frame 0 — menu frames differ).
+2. Emit the mapping table: per action, parsed af vs live af; flag any other
+   field that shifts (on_ground timing, action transitions, y).
+3. Land it as `scripts/diff_state_streams.exs` + a test pinning the mapping,
+   so the convention can never silently drift again.
+
+**Phase 2 (decision + maybe implementation, discuss before committing):**
+- Option 1: normalize at the embedding boundary — right fix, benefits every
+  policy, but touches shared code and needs a Mewtwo regression pass
+  (current behaviors may quietly depend on the shift). Can be IMPLEMENTED
+  and unit-tested on the laptop behind a flag; live regression waits for home.
+- Option 2: train drills on live-captured pairs (recorder dumps
+  `(observed_state, decided_input)`) — narrow, safe, drills only.
+- Option 3: feed parsed-convention features live — inverse of 1.
+
+**Do NOT spend DAgger rounds on this** — DAgger fixes coverage, not
+features (proven twice on 2026-07-23/24).
+
+## Other laptop-sized work, in priority order
+
+1. **Rung-1 design (Mewtwo, top of the ladder, UNSTARTED):** design what the
+   expert should SUPERVISE — the go-in decision, not the button sequence.
+   Pure thinking + doc + maybe a labeling prototype over parsed replays.
+   Corpus: `corpus/archive/mewtwo/` if present locally on the laptop clone;
+   otherwise pull from B2 (`scripts/pull_replays.sh`, rclone remote `b2`).
+2. **A3 metric (unmeasured gate):** mean connected aerials per opening,
+   next to `FailureScan.dropped_punish`. Parsing + metric + tests, all CPU.
+3. **Full test suite on the laptop** (`mix test`) — it has NOT run since the
+   multishine changes (GPU was occupied all night; the 2 touched files pass,
+   30/30). First laptop compile will be long (EXLA CPU backend); the
+   devenv shell provides everything. CUDA-tagged tests are excluded by
+   default so no GPU is needed.
+4. Housekeeping if bored: `TrainingShards.build/3` has an unused-variable
+   warning (`process_fn`, lib/exphil/data/training_shards.ex:78) that spams
+   every compile.
+
+## HOME-ONLY queue (needs GPU/Dolphin — after the 29th)
+
+| what | detail |
+|------|--------|
+| resume r17a from ep40 | command above; then score vs `R17_ACCEPTANCE_2026-07-23.md` (armed/min: PASS ≥0.5 / STRONG ≥1.0 / FAIL <0.5 vs r16's 0.17) |
+| re-gate multishine policy | ONLY after #8's fix; use `eval_policy_on_fixture.exs` offline first, then `analyze_policy_shine.exs` live |
+| re-verify the teacher after any af-convention change | its live success partly rides on table-miss → recovery-rule luck (GOTCHAS #81); `demo_expert.exs`, gate ≥5 |
+
+## Tooling map (all committed)
+
+- `scripts/eval_policy_on_fixture.exs` — offline discriminator: high
+  agreement + live failure = state-stream problem; low = training problem.
+  Run FIRST when any drill policy misbehaves.
+- `scripts/inspect_multishine_table.exs` — table coverage + state purity
+  (any `{action, af, gnd}` key carrying 2 inputs ⇒ BC will floor; caught a
+  wall-clock-keyed input that cost a 2000-epoch run). LIVE-fidelity number
+  is parsed-space only — hint, not verdict.
+- `MULTISHINE_TRACE=1` on `record_multishine.exs` — per-frame y/vy/act/af.
+- `--rollout-cap-per-state N` on `dagger_drill.exs` — opt-in; stops one
+  stuck trajectory from swamping the fixture (2609→514 frames last night).
+- `test/fixtures/statestream/` — the #8 dataset (see its README).
+- `test/fixtures/replays/fox_multishine_sloppy_2026-07-07.slp` — the OLD bad
+  fixture, kept as the metric's negative example.
+
+## Task list snapshot (rebuild the CLI list from here)
+
+| # | status | task |
+|---|--------|------|
+| 1–4, 6 | DONE | teacher verified / fixture 186 / table gate 103 / BC 0.0015 / docs |
+| 5 | BLOCKED by #8 | policy live gate (home-only once unblocked) |
+| 7 | **STOPPED ep48, resume ep40 ckpt** | r17a — resume + score at home |
+| **8** | **NEXT — laptop phase 1 ready** | state-stream diff → mapping table → choose fix |
+
+Backlog: rung-1 (design on laptop), A3 metric (laptop), PPO arch mismatch,
+#33 five-char / #23 G&W (deferred).
+
+## Caveats
+
+- Laptop environment: the repo's devenv shell should provide Elixir/Rust/
+  Python on any Nix machine; first `mix compile` is slow and EXLA runs CPU.
+  If the laptop isn't NixOS, this is the first blocker to solve.
+- `scenarios/gaps.json` stays untracked (runtime data).
+- Bradley is on the babymoon (Navarre FL, Jul 24–29, Grace 33.5 wks) — bias
+  toward small, finishable, interruptible units of work.

test/fixtures/statestream/README.md

@@ -0,0 +1,30 @@
+# State-stream reconciliation pairs (task #8 / GOTCHAS #81)
+
+Two recordings of the multishine teacher where BOTH sides of the same game
+survive:
+
+- `*.slp` — the Slippi replay Dolphin wrote (what **Peppi** parses; the
+  coordinates every trained policy learned in).
+- `*.live-trace.log` — the recorder's own per-frame observations through the
+  libmelee bridge as the game ran (`MULTISHINE_TRACE=1`; the coordinates a
+  policy actually receives at inference). Grep `\[trace\]`; fields:
+  `f<in-game-frame> act= af= gnd= y= vy=`. 300 trace lines each (5s runs).
+
+| pair | technique | why it's here |
+|------|-----------|---------------|
+| `fox_ms_float` | pre-fix teacher: aerial shine on airborne frame 2 → 22-frame float | long, varied air states |
+| `fox_ms_frame1` | final teacher: frame-1 shine, 9-frame TAS cycle | the tight loop where every af matters |
+
+Purpose: diff the two streams frame by frame to derive the EXACT
+parsed↔live mapping (known so far: parsed jumpsquat af 0,1,2 vs live 1,2,3;
+action 365 agrees; the offset varies per action — and check whether other
+fields shift too). This is the first experiment of task #8 and needs no
+Dolphin and no GPU — it is deliberately laptop-sized.
+
+Alignment hint: the in-game frame counter in the trace (`f###`) and the
+replay's frame index count the same game, but confirm alignment on an
+unambiguous event (the first jumpsquat entry) rather than assuming f0
+matches parsed frame 0 — menu frames differ between the two.
+
+Do not regenerate casually: a pair is only valid if the .slp and the trace
+come from the SAME run (record with `MULTISHINE_TRACE=1` and keep both).