docs(#38): reconnect wiring design — slot manager + resume-first-with-grace

[aradanmn]

Draft for design review — no code, just the design doc (docs/DESIGN-38-RECONNECT-WIRING.md). Grounded in this session's on-Deck #112 evdev captures + a full code trace of the reconnect path.

The problem

controller_proxy.sh — the whole of #38's seamless-reconnect mechanism — is DARK (zero callers). The live path raw-binds a pad's jsN into bwrap at launch; a reconnected pad is a new node the sandbox can't see (#61/#62). Sticky slots keep the instance alive but input-dead — exactly HW-2's "P2 dropped, session persisted, un-controllable."

Core structure (the manager)

Event handlers hold no policy. A slot_manager owns the slot record schema and every transition, so CONTROLLER_ADD/REMOVE share one get/set/release surface and the intent policy lives in exactly one verb, slot_claim, which returns SPAWN/RESUME/ADOPT/REJECT. Handlers just execute the outcome. The manager is pure state+policy → the whole reconnect decision matrix is a hardware-free unit test.

Intent policy — resume-first-with-grace

Known MAC → always resume its slot. Unknown MAC → adopt an orphaned slot when the session is full (4-up ceiling, no 5th instance) or within a grace window, else spawn a new instance, else reject.

Hardware-derived decisions (#112)

• Identity = physical pad MAC (uniq). eventN (lowest-free, not monotonic) and the UHID instance are per-connection — never cache them.
• Role = "has a js handler", but pick physical pads by excluding the 28de Steam virtuals (they carry js too, with an empty uniq). The js-owner event node is the #38 D2 blocker: evsieve dies ~2min after BT battery-death reopen — 'capabilities of the reconnected device are different than expected' #112 crash fix — evsieve reopens a pad, not the touchpad.
• RESUME re-points the proxy; ADOPT restarts it (device-id changes). The one open verification — does evsieve persist=reopen honor a moved symlink — only decides seamless-vs-sub-second-blip; the restart fallback is correct either way. Deferred to a Deck session (#38 D2 blocker: evsieve dies ~2min after BT battery-death reopen — 'capabilities of the reconnected device are different than expected' #112 step-2).

Rollout

Incremental, behind MCSS_PROXY_ENABLE, raw-binding stays the working default until the on-Deck verification passes. PR-a (manager + state, behavior-neutral) → PR-b (launch wiring) → PR-c (policy) → PR-d (watchdog + verify → flip default).

Please weigh in on §14 open questions

1. Grace default — 180s (covers a battery swap, excludes a genuine new player)?
2. ADOPT device-id flip — a different pad adopting a slot changes the virtual's vendor:product → Controlify may re-detect controller type mid-session (glyph flip, cf. Controlify shows SNES button glyphs for the Steam virtual pad (wrong prompts) #36). Acceptable, or suppress ADOPT when vendor:product differs?
3. proxy-OFF reconnect — keep today's no-reconnect (chosen), or teardown+relaunch the slot (restores input, loses game state)?
4. Steam-grab — evsieve grab may starve Steam's own 28de virtual (guide button/overlay?) — verify before default-ON.
5. REJECT-when-full → wire the Docked launch with no external controller exits silently — show a user-visible message #125 user message here?

🤖 Generated with Claude Code