docs: session handoff (R5-V1/V2 + #168/#169 fixes) + roadmap; entry for next session

Next-session entry point: 2026-07-03-session-handoff.md. Two ready streams —
#170 (creature chase/attack animation, well-scoped) or R5-V3 (sticky/TS-39).
Roadmap Phase R updated: R5-V2 shipped, streaming fixes landed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/plans/2026-04-11-roadmap.md

@@ -724,9 +724,16 @@ diagnostic scaffolding, not yet the final collision system.
   system ported to Core, fully tested, UNWIRED (purely additive; renamed the
   misnamed `Physics.PositionManager` combiner → `RemoteMotionCombiner`);
   ConstraintManager unarmed (issue #167, TS-35 stays). Decomp/ACE/plan:
-  `docs/research/2026-07-03-r5-managers/`. NEXT: R5-V2/V3/V4 — the visual-gated
-  GameWindow wiring (per-entity `IPhysicsObjHost`, retire AP-79 + TS-39, apply
-  mt-0 sticky/longjump, #164, facade); plan in `r5-wiring-handoff.md`.
+  `docs/research/2026-07-03-r5-managers/`. **R5-V2 SHIPPED 2026-07-03 `fffe90b3`**
+  — wired the voyeur system per-entity via `EntityPhysicsHost`, retired AP-79;
+  verified live (remote creatures chase). Same session fixed two PRE-EXISTING
+  streaming bugs surfaced while visual-gating V2 (the user's "world doesn't load"
+  report): **#168** pending-bucket trap (`315af02f`) + **#169** cold-spawn
+  streaming hole (`9b06a9b8`) — both verified live. Filed **#170** (remote
+  creature chase+attack animation divergence vs retail — glide/over-frequency/
+  uniform attacks; decomposes into #159 + pending_motions loop + dead-reckon
+  glide). NEXT: R5-V3/V4 (sticky/TS-39, facade/#164 — `r5-wiring-handoff.md`)
+  OR #170. Entry point: `docs/research/2026-07-03-session-handoff.md`.
 - **L.2g — Inbound motion interpretation (remote-entity CMotionInterp funnel).**
   ACTIVE 2026-07-02. Port retail's inbound motion pipeline verbatim for ALL
   remote entities (players, NPCs, monsters — one funnel, user-approved):

docs/research/2026-07-03-session-handoff.md

@@ -0,0 +1,111 @@
+# Session handoff — R5-V1/V2 + world-loading fixes (2026-07-03, late)
+
+Fresh session enters HERE. Worktree `vigorous-joliot-f0c3ad`, branch
+`claude/vigorous-joliot-f0c3ad`, tree CLEAN at `64f83d7c`. Full suite **4007**
+green (+ the R5-V1 conformance tests + the #168 relocate test). Everything below
+is committed.
+
+## What landed this session
+
+| Commit | What |
+|---|---|
+| `3d89446d` | **R5-V1** — PositionManager facade + StickyManager + ConstraintManager + the full **TargetManager voyeur system** ported to Core, fully tested, UNWIRED. Renamed the misnamed `Physics.PositionManager` combiner → `RemoteMotionCombiner`. Decomp/ACE/plan in `docs/research/2026-07-03-r5-managers/`. |
+| `2b5e8a67` | R5-V1 docs: wiring handoff, register TS-35 correction, ISSUES #167 (ConstraintManager leash unarmed). |
+| `fffe90b3` | **R5-V2** — wired the TargetManager voyeur system per-entity via `EntityPhysicsHost` (App), retired the AP-79 poll adapter. **Verified live** — this is why remote creatures now chase the player. |
+| `315af02f` | **fix #168** — the pending-bucket trap (`RelocateEntity` couldn't recover an entity stranded in `_pendingByLandblock`). Invisible player / disappear-on-run-out. |
+| `9b06a9b8` | **fix #169** — the cold-spawn streaming "hole" (far login-spawn diffs against the half-loaded startup window; residence marked before loads land → hole). Now `ForceReloadWindow`s on a far login-spawn. |
+| `7c5bc97c` | ISSUES #168/#169 filed DONE. |
+| `64f83d7c` | ISSUES #170 filed (creature chase/attack animation divergence). |
+
+**The user's headline ask this session** — "the world doesn't load / character
+disappears" — is FIXED and verified live (`0xADAF` loads, player transitions
+`PENDING → DRAWSET PRESENT`). Root-caused to two pre-existing streaming bugs;
+R5-V2 was verified line-by-line to be read-only w.r.t. position/cell/landblock/
+streaming and RULED OUT as the cause. Durable lesson: `feedback_streaming_residence_race`.
+
+## NEXT — two ready work streams (Claude picks; both are teed up)
+
+### Option A — #170: remote creature chase+attack renders wrong vs retail
+**Well-scoped, user-confirmed via retail side-by-side (the oracle).** A monster
+chasing+attacking the player glides, over-plays attacks, and shows uniform/wrong
+attack animations; retail (same local ACE) renders it correctly → the divergence
+is CLIENT-side. Motion trace (`ACDREAM_DUMP_MOTION`, guid 0x80000244): ACE sends
+`mt-0 stance 0x3C` → `mt-6 chase spd 2.03` → a stream of `mt-0` attacks
+`0x62/0x63/0x64 spd 0.97`; acdream shows a MOTIONDONE `pending=True` loop.
+Decomposes into THREE sub-bugs (full detail in ISSUES #170):
+1. **Wrong/uniform attack anims** → likely **#159** (CombatAnimationPlanner uses
+   2013-decomp command numbering, not ACE/DRW — `0x10000062/63/64` misclassify).
+   This one has a KNOWN fix path (renumber `CombatAnimationMotionCommands` to
+   `DatReaderWriter.Enums.MotionCommand` values; parity test).
+2. **Over-frequency / stuck** — the `pending_motions` queue completes+re-queues
+   in a tight loop. R3/R4 animation-sequencer / MotionDone territory (grep the
+   named decomp for how retail's `CMotionInterp` handles an attack UM stream
+   arriving over an active moveto — attack one-shots should play over locomotion
+   and RETURN to it, not wedge).
+3. **Glide** — position moves (mt-6 + UP dead-reckon) but no locomotion legs play
+   (attacks override) → smooth slide. AP-80 / #160 dead-reckon-vs-animation family.
+Entry points: `MotionInterpreter`/`AnimationSequencer` attack dispatch +
+`pending_motions`; `CombatAnimationPlanner` (#159); `ServerControlledLocomotion`.
+Start with #159 (bounded), then trace the pending-motions loop with the motion
+dump. **Retail is the oracle — the user runs it side-by-side; ask for a
+frame-by-frame retail comparison, don't guess.**
+
+### Option B — R5-V3: wire PositionManager sticky, retire TS-39, apply mt-0 flags
+The paused R5 continuation. Full plan in
+`docs/research/2026-07-03-r5-managers/r5-wiring-handoff.md` (§V3). Bind
+`MoveToManager.StickTo/Unstick → PositionManager` (now that V2 gives each entity
+an `EntityPhysicsHost`, adding a `PositionManager` to it is the natural next
+step), integrate `adjust_offset` into the body tick, apply the UpdateMotion mt-0
+flags (0x1 sticky-guid → `stick_to_object`, 0x2 → `StandingLongJump`). Retires
+TS-39. Then R5-V4 (MovementManager facade + #164 + head-stance dispatch).
+
+**Recommendation:** #170 is more user-visible (they just watched it break) and is
+now well-scoped; R5-V3 is the "finish what we started" path. Either is fine —
+Claude's call per work-order autonomy. #170's part 1 (#159) is the smallest
+concrete win.
+
+## R5 arc status
+- **V1** (Core managers + tests) — DONE `3d89446d`.
+- **V2** (voyeur wiring, retire AP-79) — DONE `fffe90b3`, verified live.
+- **V3** (sticky, retire TS-39, mt-0 flags) — PENDING. `r5-wiring-handoff.md` §V3.
+- **V4** (MovementManager facade + #164 + head-stance dispatch) — PENDING. §V4.
+- Open R5-adjacent: #167 (ConstraintManager leash unarmed + 2 unknown x87 consts),
+  TS-35 (stays open until the leash is armed), #164 (action-replay Autonomous bit).
+
+## Debug apparatus that proved decisive (reuse for #170)
+- `ACDREAM_PROBE_ENT=1` — `EntityVanishProbe`: `[ent] APPEND → PENDING/LOADED`,
+  `DRAWSET PRESENT/ABSENT`, `[dyn] player DRAWN/CULLED`. Separates "not in draw
+  set" from "present-but-culled." A one-line `[lb] ADD` in `GpuWorldState.AddLandblock`
+  (added then stripped) exposed the streaming hole as a missing Y-band — re-add
+  it if you chase another streaming gap.
+- `ACDREAM_DUMP_MOTION=1` — every inbound `UM` (guid, stance, cmd, speed) + the
+  resulting `SetCycle` + `[MOTIONDONE]`. THE tool for #170 — it's how the
+  attack-stream-over-chase was found.
+
+## Session gotchas (environment)
+- **The test character `+Acdream` (0x5000000A) is saved OUT in the wilderness**
+  (landblock ~`0xADAF`/`0xAEAE`, ~1 km SE of Holtburg), from an earlier run of
+  the #168 disappear bug. It spawns there every login. **With the #169 fix that
+  now loads correctly** (far login-spawn ForceReloadWindows), so it's testable —
+  and there are Mite Scamps + a Mosswart Feeder right at the spawn (handy for
+  #170). To get back to Holtburg, the user GM-teleports.
+- **Client lifecycle: the USER manages it.** Launch with plain `dotnet run
+  --no-build` in the background (never pre-close/kill). If a rebuild is locked by
+  a running client (`The file is locked by AcDream.App`), ASK the user to close
+  it — don't kill it.
+- **ACE stale session:** a hard-closed or rapidly-relaunched client leaves ACE
+  thinking the character is still in-world → `session failed: CharacterList not
+  received` for ~3 min. Graceful close (window X / WM_CLOSE, exit 0) clears in
+  ~5 s. Don't retry-spam; wait ~160 s if it's stuck. This session hit it once
+  from rapid relaunches.
+- PowerShell `Tee-Object`/`Out-File` write UTF-16 → the plain-text grep needs
+  `tr -d '\000'` first (the launch logs read as UTF-16). Used throughout.
+
+## Pointers
+- R5 decomp/plan: `docs/research/2026-07-03-r5-managers/` (decomp per manager,
+  ACE cross-ref, port plan, wiring handoff).
+- ISSUES: #167 (constraint leash), #168/#169 (DONE this session), #170 (creature
+  animation), #159 (combat command numbering), #160/#165/#166 (remote-motion).
+- Memory: `feedback_streaming_residence_race`, and the R5 research index entry in
+  `MEMORY.md` (animation-sequencer deep-dive line).
+- Roadmap Phase R: R5-V1/V2 shipped; V3/V4 next.