fix(#133): debounce DISPLAY_MODE_CHANGE — confirm a mode across N consecutive reads

[aradanmn]

Closes nothing yet — #133 stays open until the Deck confirms it (see Validation).

The bug

HW-2 (2026-07-22) lost a live docked session to one spurious /sys/class/drm/card0-DP-1/status = disconnected read. The projector was physically connected and DP-1 read connected immediately before and after, but watch_display_mode emitted DISPLAY_MODE_CHANGE off that single read → Minecraft moved to the internal panel → froze → teardown wedged → force reboot.

Steam Game Mode rides the Deck's known DP flicker out. We pounced on the first blip.

The fix

Both watch paths (inotify and poll) now route a candidate mode through _confirm_display_mode, which re-reads until the candidate has held for DOCK_DETECTION_CONFIRM_SAMPLES consecutive reads — default 3, spaced DOCK_DETECTION_CONFIRM_INTERVAL_S=1s — bailing on the first disagreement.

• A blip costs one interval and emits nothing.
• A real dock/undock still switches, ~2s later. That latency is the whole trade.
• Bad overrides clamp instead of killing the watcher; SAMPLES<1 degrades to the pre-dock_detection: no debounce — a single transient DRM read flips a working docked session to the internal panel #133 emit-on-first-read.

Tests — 8 → 11 (CI baseline bumped)

T1.9	transient candidate rejected
T1.10	sustained candidate confirms; SAMPLES=1 + garbage overrides clamp safely
T1.11	end-to-end: a live docked session swallows a blip, still emits the later real undock

T1.11 is mutation-verified. Worth flagging, because its first draft was worthless: it passed with the debounce replaced by true. The blip and the real change are both handheld, so the first message's content cannot discriminate. The real gate is "exactly one message" — un-debounced, the blip's revert emits a second (docked) message. Asserting that absence needs a persistent O_RDWR fd, since read -t bounds the read but not the FIFO open, which blocks until a writer appears (that hung the suite before I switched to exec 3<>).

Verified: with _confirm_display_mode stubbed to true, T1.11 fails with extra message 'DISPLAY_MODE_CHANGE docked'; the blip was not debounced.

Also in here

Both backgrounded watchers are now redirected off the CI capture pipe (>/dev/null 2>&1). CI runs out=$(bash "$suite" 2>&1), which blocks until every process holding stdout exits — the #80/#103 hang. T1.8 had the same shape; hardened while I was here.

Known gap (documented in-module, not introduced here)

The inotify branch drops DRM events that fire during the settle/confirm window, which this change grows from ~0.5s to ~2.5s. It is self-correcting whenever the state ends up steady, because confirmation samples read live status rather than replaying events. Residual risk: a change that lands inside the window and then emits no further event would leave that branch blocked until the next one. The proper fix is bounding inotifywait with -t so the loop doubles as a slow poll — out of scope here.

Verification

• tests/test_dock_detection.sh — 11/11, run 5× for flake, and once under CI's exact $(...) capture form (no hang)
• shellcheck -S warning modules/dock_detection.sh — clean; test-file delta is 3 × SC2064 matching the file's existing trap convention
• No regressions in test_controller_monitor / test_watchdog / test_runtime_context / test_utilities. test_window_manager fails 7/9 identically on main — pre-existing, encoded in the CI baseline.

Validation still required

CI cannot prove the thing that actually matters. Before #133 closes, the Deck needs: a docked session that survives a real DP flicker without moving to the internal panel, and a real undock that still switches (within ~2s). Folding into the next docked session — this is meant to make the #112 work survivable.

[aradanmn]

Parked — do not merge. On-Deck validation (2026-07-25) measured this pure-debounce fix at ~3.9s real dock/undock latency (Deck has no inotify-tools → 3s poll + 2s confirm), which is a bad trade for what looks like an N=1 event — the deliberate reproduction attempt caught zero spurious blips. See #133 for the full findings and the real-undock signature.

If #133 recurs (a passive logger is now watching for it), the right fix is corroboration (emit on status only when enabled+dpms agree; debounce a status-only anomaly) — near-zero added latency — not this blind debounce. Leaving the branch up as a reference; not merging.

[aradanmn]

Closing — parked and not merging. On-Deck testing couldn't reproduce the dock-flicker (#133), and the pure-debounce fix measured ~3.9s real-undock latency (poll path), a bad trade for an N=1 event. The passive flicker logger stays running to catch any recurrence; if #133 comes back the corroboration approach (emit on status only when enabled+dpms agree) is the fix, not this blind debounce. Branch preserved for reference.