Build plan: virtual pad rig (#136) — uhid primitive → structural rig → benchmark pilot

[aradanmn]

Build plan for the virtual pad rig. Recon: docs/RESEARCH-136-VIRTUAL-PAD-RIG.md (PR #156) — verdict: build on /dev/uhid, not uinput, because uhid takes a caller-supplied uniq and gives each pad its own device parent.

This issue is the build breakdown, in the shape #142 used for #38. Nothing here starts before PR-0 comes back green from the Deck.

Placement decisions

• The rig is test tooling — nothing lands in modules/. /proc/bus/input parsing is owned by controller_monitor.sh (ARCHITECTURE.md §2), so the rig never re-implements enumeration: it sources controller_monitor.sh and calls _list_raw_external_pads to assert what the production code sees. One encoding (PRINCIPLES feat: Add Microsoft account OAuth setup during installation #9).
• Files:
  • tests/lib/uhid_pad.py — the device primitive (create / destroy / inject). Dependency-free stdlib; uhid is write() on a chardev, no ioctls, no compiler, no container.
  • tests/lib/uhid_rig.sh — bash surface the suites call; owns PID tracking and cleanup.
  • tests/probe-uhid-feasibility.sh — the Deck gate (PR-0).
  • tests/test_uhid_pad.sh — CI suite for the pure parts.
• No production code change is expected. The research doc predicts each uhid pad gets a distinct sysfs parent, so the step-6 dedup needs no edit. PR-0 proves or disproves that before anything depends on it.

Proposed surface

uhid_pad.py create --uniq aa:bb:cc:00:00:01 --name "MCSS Test Pad 1" \
                   --vendor 0x054c --product 0x0001
    # holds the device open until killed; that IS the pad's lifetime
uhid_pad.py --emit-descriptor            # pure: report descriptor hex
uhid_pad.py --encode-report BTN_SOUTH=1,LX=200   # pure: report bytes hex

# stdin command stream to a live pad:
press BTN_SOUTH | hold BTN_SOUTH 500 | axis LX 200 | release all | destroy

uhid_rig.sh:  rig_create_pad N | rig_destroy_pad N | rig_inject N "<cmd>" | rig_cleanup

rig_cleanup kills only PIDs the rig started, from its own tracked pidfile — PRINCIPLES #7, no name matching.

PRs

PR-0 — feasibility probe (Deck-gated, blocks everything)

Deliverable: tests/probe-uhid-feasibility.sh + a minimal uhid_pad.py, answering in one bounded run:

1. /dev/uhid present; openable as deck without sudo?
2. One pad created → does it appear in /proc/bus/input/devices with our U: Uniq=?
3. What is its S: Sysfs= — does the step-6 parent-key strip yield a unique key?
4. Does joydev give it a jsN?
5. Does _has_gamepad_buttons accept its B: KEY= bitmap?
6. Does _list_raw_external_pads enumerate it as an external pad?
7. Two pads → do BOTH enumerate? (the dedup question, settled definitively)
8. Destroy + recreate with the same uniq → new eventN, same identity?
9. Does Steam mint a 28de virtual for it, as it does for a real pad?

Acceptance: every question answered with a verdict line; no lingering uhid devices or processes on exit. Bounded waits with busy-vs-waiting indicators (PRINCIPLES #6). Read-only checks run first; device creation is a separate opt-in step.

PR-1 — pad primitive + CI tests

Harden uhid_pad.py; tests/test_uhid_pad.sh covers the pure parts — descriptor bytes, report encoding, uniq/VID:PID formatting — via --emit-descriptor / --encode-report, asserting hex. Registered in the ci.yml baseline map like every other suite; no new CI machinery. Device I/O stays Deck-only. Mutation-test the new suite (PRINCIPLES #4).

PR-2 — rig control surface

tests/lib/uhid_rig.sh: create/destroy/inject/cleanup, pidfile-tracked, cleanup trap. Backgrounded work redirected off any capture pipe (PRINCIPLES #8 — this bit CI twice already, in #80/#103 and #133).

PR-3 — automate stage3_hotplug

Flag-gated MCSS_VIRTUAL_PADS=1; human-prompt mode stays the default until a full green run says otherwise (PRINCIPLES #2, dark-first). Replaces the "Plug in a SECOND/THIRD/FOURTH external controller" prompts with timed pad creation, keeping every existing geometry assertion.

PR-4 — #71 burst-spawn repro

Create 4 pads in one burst pre-launch — the case that is near-impossible to stage by hand. Either reproduces the reflow race or gives evidence it is architecturally mitigated.

PR-5 — reconnect rig (#38 / #151)

Destroy and recreate by uniq to reproduce a battery-death cycle. #151 specifically: destroy two pads, recreate in swapped order so each lands on the other's freed eventN. Turns the swap race into a repeatable test instead of a post-ship anecdote.

PR-6+ — benchmark pilot (separate track)

Do not start until PR-1..5 are trusted, and until the §5 methodology question in the research doc is decided: open-loop timed input is self-damping under load, so a slower configuration flies less far and incurs less load, flattening the A/B difference being measured. Recommendation on the table is distance-as-covariate plus log-gated transitions. Also needs --server/quickPlay confirmed from our launch path so the pilot never navigates a menu.

Gate

PR-0 green on the Deck. If Q7 says two pads still collapse, the plan changes: step-6 dedup needs a (behaviour-neutral) fix first and it becomes PR-0b.

[aradanmn]

Sequencing decision (Scott, 2026-07-29): the rig comes first

This build plan is no longer a v1.3 nice-to-have running alongside the bug work — it gates it. #151 and #71 have been moved to v1.3 and marked blocked on this issue, because neither can be reproduced by hand:

• Reconnect: node-swap race when 2+ pads disconnect at once and reclaim each other's freed eventN #151 needs two pads dropping simultaneously and reconnecting so each grabs the other's freed eventN (PR-5).
• Simultaneous multi-pad launch: last instance's window never positioned (burst-spawn reflow race) #71 needs four pads arriving near-simultaneously before launch (PR-4).

Both were found by accident and neither has a demonstrable repro today. Fixing them before the rig exists means shipping fixes we cannot first watch fail — the thing PRINCIPLES #4 is about.

What is NOT gated on this

Worth stating so the rig does not become a bottleneck it has no business being:

• Docked launch with no external controller exits silently — show a user-visible message #125 (docked launch with no external controller exits silently) — the test case is the absence of pads. The rig adds nothing. Stays in v1.2.1 and can proceed now.
• Ship a prebuilt evsieve binary (Release asset) with build-at-install fallback #126 (prebuilt evsieve binary) — unrelated.
• handheld→docked transition is a no-op: a session flipped to handheld never returns to the external display when docked is restored #134 / Nested-session teardown can wedge → no display output anywhere + orphaned dock monitor keeps switching (force reboot required) #135 (dock/undock transitions) — display-topology bugs; the rig does not simulate DRM state. Docked→handheld transition leaves the surviving instance bound to the external pad — Deck built-in controls locked out #79 partially benefits, since it is about a pad's binding surviving a transition, but the hard half is still the transition.

v1.2.1 is therefore #125 alone (#118 is closed), and can ship as a small patch without waiting for any of this.

Added scope: fold the rig into the test regime

Scott's second point — the rig is not just a bug-repro tool, it becomes part of how we test. That extends the plan beyond PR-3's stage3_hotplug automation:

• New hardware stages for the cases that only exist with the rig: a reconnect stage (destroy/recreate by uniq, asserting RESUME rather than ADOPT) and a burst-spawn stage.
• Registration in tests/hardware/run_all.sh, so the rig-driven stages run in the standard sweep rather than as one-off scripts — with the existing --check freshness gate applying to them like everything else.
• Human-prompt mode stays the fallback, not a deleted path: MCSS_VIRTUAL_PADS=0 must keep the operator-driven stages working, both because real pads remain the ground truth (PRINCIPLES docs: Add comprehensive CLAUDE.md for AI assistant guidance #3) and because the rig cannot cover everything — notably the perceptual soft gates in the benchmark protocol.
• The rig does not replace on-hardware validation with real controllers before a default flip. A uhid pad is structurally identical to a BT pad at the evdev layer, but 'identical where we looked' is exactly the assumption that has burned this project before — see the Seamless controller reconnect via a per-slot stable virtual device (input proxy) #38 reconnect bug that only the full monitor→orchestrator chain caught live.

PR-0 (#158) is merged and waiting on a Deck run. Nothing downstream starts until its SUMMARY lands here.

[aradanmn]

Milestone restructure (Scott, 2026-07-29): this moved to v1.4.

Rather than have v1.3 hold both the dock-transition work and the rig, the two are now separate releases:

• v1.3 — 'docking actually works': handheld→docked transition is a no-op: a session flipped to handheld never returns to the external display when docked is restored #134 (re-dock is a no-op), Nested-session teardown can wedge → no display output anywhere + orphaned dock monitor keeps switching (force reboot required) #135 (teardown wedge → force reboot), Docked→handheld transition leaves the surviving instance bound to the external pad — Deck built-in controls locked out #79 (pad stays bound to the external display). A coherent, narrow release, none of it rig-dependent.
• v1.4 — everything downstream of the rig: this plan, Virtual controller rig: drive N players via uhid for automated multi-player testing #136, Reconnect: node-swap race when 2+ pads disconnect at once and reclaim each other's freed eventN #151, Simultaneous multi-pad launch: last instance's window never positioned (burst-spawn reflow race) #71, and 4-up performance profile: per-instance render caps + right-sized JVM heaps (GPU saturated, VRAM carve-out full) #70's benchmark-pilot half.

Two judgement calls in that split, both worth a second look:

• Ship a prebuilt evsieve binary (Release asset) with build-at-install fallback #126 (prebuilt evsieve binary) is not rig-dependent — it landed in v1.4 for want of a better home rather than because it belongs there. Backlog or a v1.3 companion would both be defensible.
• 4-up performance profile: per-instance render caps + right-sized JVM heaps (GPU saturated, VRAM carve-out full) #70 benefits from the rig rather than depending on it. The v2 benchmark protocol already ran a full A/B campaign with human pilots; the rig makes it repeatable and cheap, not possible. If v1.4 gets long, 4-up performance profile: per-instance render caps + right-sized JVM heaps (GPU saturated, VRAM carve-out full) #70's render-cap/heap half could be pulled forward independently.

[aradanmn]

PR-0 probe run on the Deck, 2026-07-29 — blocked at V1

V10_PURE_SUITE = PASS    (18/18 tests passed here)
V1_UHID_ACCESS = DENIED  (not openable as user and sudo -n failed)

/dev/uhid is crw------- 1 root root 10, 239, and sudo -n fails on this Deck (sudo wants a password). The probe fail-closed correctly: it refused to create any device and stopped before Phase 1, so V2–V9 are still unanswered.

Two useful things came out of it anyway:

• V10 confirms CI and the Deck agree on the pure computation — 18/18 in both, on bash 5.3.3 here vs. the CI runner. That was the specific worry that motivated V10.
• The one risk flagged in the research doc as "likely friction" is real, and it is now a concrete blocker with concrete options rather than an unknown.

Access options

Recommended: a udev rule. /dev/uinput on this Deck is already crw-rw----+ with an ACL granting deck — it carries uaccess, and uhid does not. So:

# /etc/udev/rules.d/99-mcss-uhid.rules
KERNEL=="uhid", TAG+="uaccess"

That hands the seat's logged-in user access through logind's ACL — the same mechanism already making uinput work — with no setuid binary and no sudo in the automation path. Caveats: SteamOS has an immutable rootfs, so installing it needs a one-time steamos-readonly disable (operator step, root, once), and it should be treated as re-installable in case an OS update clears it.

Rejected: sudo in the rig. A rig whose purpose is unattended multi-player testing cannot depend on an interactive password prompt, and baking a NOPASSWD entry for the pad creator is a broader grant than this work justifies.

Rejected: fall back to /dev/uinput because it is already accessible. That is the interface the research doc ruled out — no uniq, so no RESUME path and no #151 reproduction, plus all pads collapsing to one parent key. Accessible-but-useless.

Plan change

PR-0 grows a step: detect DENIED and tell the operator exactly what to install, rather than just reporting the verdict. Then the same run continues into V2–V9 once access exists. The udev rule itself should ship in the repo (with the readonly-disable dance documented) so it is reproducible rather than a thing someone did once by hand.

Separately: probe hygiene bug

The probe wrote its results to $HOME/uhid-probe-<stamp>.txt. That violates the project's own convention that Deck-side artifacts belong under .workdir/ (#122) — my default path was wrong. Fixing.

[aradanmn]

★ PR-0 probe PASSED on the Deck, 2026-07-31 — the rig is unblocked ★

V10_PURE_SUITE=PASS      (18/18 tests passed here)
V1_UHID_ACCESS=USER      (openable as deck, no sudo needed)
V2_UNIQ=PRESENT          (U: Uniq=aa:bb:cc:00:00:01 reached the input device)
V3_SYSFS_PARENT=UNIQUE   (/devices/virtual/misc/uhid/0005:054C:0001.0008)
V4_JS_NODE=PRESENT       (js0, event11)
V5_GAMEPAD_CAPS=ACCEPTED (BTN_SOUTH/BTN_JOYSTICK gate passes)
V6_ENUMERATED=YES        (_list_raw_external_pads emits it)
V7_DEDUP=BOTH            (each uhid pad keeps its own parent key)
V8_RECONNECT=SAME_NODE   (identity held; no renumber forced)
V9_STEAM_VIRTUAL=MINTED  (Steam created 1 virtual — same as a real pad)

Every design assumption in the research doc is confirmed on hardware, and no production code change is required.

The two that mattered

V2 — the whole uhid-over-uinput thesis. A caller-chosen fake MAC reaches U: Uniq=, which is the field slot_manager keys reconnect identity on. This is exactly what uinput structurally cannot do.

V7 — BOTH pads enumerate. This was the verdict that could have rewritten the plan. Each uhid device gets its own sysfs parent (/devices/virtual/misc/uhid/0005:054C:0001.0008), so step-6 dedup keeps them separate. PR-0b is NOT needed — delete it from the ladder.

Fidelity is better than hoped

The pad presents as Bus=0005 Vendor=054c with its own js0, passes the production capability gate, is emitted by the real _list_raw_external_pads, and Steam mints a 28de virtual for it exactly as it does for a real pad (4 → 5 → back to 4 on destroy). Structurally indistinguishable from a Bluetooth DualShock at every layer we care about.

One honest gap

V8 = SAME_NODE, not RENUMBERED. Destroy-and-recreate returned the pad to event11 — the freed minor was still lowest-free, so no renumber was forced. Identity held across the cycle, which is the important half, but the renumber case (#112's mechanism, and what #151 is about) is still untested. Forcing it needs the 3-pad trick from the DS4 method, which is PR-5's job anyway.

Two bugs found and fixed getting here (#169)

1. The udev rule I documented was wrong. 99-mcss-uhid.rules parsed, reloaded, and did nothing — uaccess ACLs are applied by 70-uaccess.rules/73-seat-late.rules, so the tag must be added before them. Corrected to 60-mcss-uhid.rules, matching how SteamOS tags its own uinput.
2. The probe's own access test was wrong. It used Python's buffered open(), which raises UnsupportedOperation: not seekable on a character device even when the open succeeds — a false DENIED at the exact gate the probe exists to answer. Now uses os.open(O_RDWR|O_NONBLOCK), the same call uhid_pad.py makes.

Also settled: end users never need the udev rule. uhid appears only under tests/; the shipped proxy uses evsieve against /dev/uinput, which already carries uaccess.

Ladder now

PR-0b (not needed) → PR-1 primitive + CI tests → PR-2 rig surface → PR-3 automate stage3_hotplug → PR-4 #71 burst → PR-5 #151 renumber/swap.

[aradanmn]

PR-2 opened: #197 — rig control surface (tests/lib/uhid_rig.sh).

One correction to the ladder first: PR-1 turned out to already be done. PR-0/#158 shipped uhid_pad.py's --emit-descriptor/--encode-report CLI, 18 CI tests, and mutation testing — exactly PR-1's scope, just landed under the PR-0 label since the primitive and its tests were built together. Nothing was missing; docs/PLAN.md now reflects that.

PR-2 generalizes the probe's inline pad plumbing into rig_create_pad/rig_destroy_pad/rig_inject(_nowait)/rig_cleanup, pidfile-tracked (one file per pad), a FIFO + held-open write fd as the command channel, and PID-recycling-safe kill verification via /proc/<pid>/stat's starttime (#7). rig_install_traps is opt-in and refuses to clobber an existing trap — the #146 shape.

93/93 in tests/test_uhid_rig.sh (registered in ci.yml) against a protocol-double fixture (tests/lib/fake_pad.sh), since /dev/uhid doesn't exist on a runner. All 7 planned mutations confirmed red against their named tests, then reverted — full results in the PR body. One of those mutations (M4: opening the FIFO write end before backgrounding the child) was caught for real during review, not just as a drill: the implementation agent hit a session limit mid-test with that exact mutation still live in the file, which wedges the whole script. Fixed before this PR was opened.

Not yet Deck-validated. Everything here is CI-covered against the fixture; none of it has touched a real /dev/uhid. PR body lists the exact hardware checks outstanding (real pad creation, live _list_raw_external_pads queries, 4-pad burst enum timing, destroy+recreate identity, SIGKILL-the-shell teardown) — same shape as the ~20-minute driver script the PR-2 work order suggested. That's the next Deck sitting for this track.

[aradanmn]

PR-2 (#197) Deck-validated, 2026-08-01. Full writeup on the PR: comment.

Short version: core lifecycle (creation, injection, cleanup, Steam's 28de reaction, the SIGKILL-shell EOF teardown safety property) all confirmed on real /dev/uhid. One scare — a 4-pad burst appeared to lose the last pad from enumeration — turned out to be MCSS_MAX_PLAYERS=4 capping against a real controller that happened to already be connected, not a defect; confirmed clean with a genuine 0-baseline.

One thing left genuinely open: pad-removal visibility latency. A first attempt to measure it via SSH-side polling produced an untrustworthy number after the polling harness broke silently — retracted rather than reported. Next session on this track should bracket a destroy with dmesg -T instead of SSH-side wall-clock polling, which is immune to both connection blips (this Deck's dock-NIC dropped a couple of times mid-session) and client-side scripting bugs.

PR-1 note stands from the last comment: it was subsumed by PR-0/#158, nothing missing there.

Ladder now: PR-1 done (via PR-0) → PR-2 done, Deck-validated → PR-3 (automate stage3_hotplug) is next.