test(presenter): PUNKTFUNK_HW_FAULT=import demotion hook (phase 2 acceptance)

Faults every dmabuf import so the failure-streak → force_software →
software-decode recovery is exercisable on healthy hardware — the plan's
§8 phase-2 acceptance requires demoting via a deliberately faulted
import rather than waiting for a broken driver.

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

clients/linux-session/README.md

@@ -25,6 +25,9 @@ chord (L1+R1+Start+Select, hold to disconnect) works the same.
 
 Decode follows the Settings preference: VAAPI frames import zero-copy into Vulkan
 (per-plane dmabuf + the stream's CICP-driven CSC shader); boxes whose driver can't
-import (NVIDIA proprietary by design) fall back to software decode automatically —
+import (NVIDIA proprietary by design) fall back to software decode automatically.
-`PUNKTFUNK_DECODER=software|vaapi` overrides for bisects. HDR/P010 and the Skia console
+Debug/bisect knobs: `PUNKTFUNK_DECODER=software|vaapi`, `PUNKTFUNK_PRESENT_MODE=
-UI (`--browse`) are later phases of the plan.
+mailbox|immediate` (default FIFO), `PUNKTFUNK_VK_DEVICE=<index>` (multi-GPU), and
+`PUNKTFUNK_HW_FAULT=import` (fault every dmabuf import — proves the three-strike
+demotion to software on healthy hardware). HDR/P010 and the Skia console UI
+(`--browse`) are later phases of the plan.

crates/pf-presenter/src/dmabuf.rs

@@ -73,6 +73,13 @@ pub fn import(
     ext_mem_fd: &ash::khr::external_memory_fd::Device,
     frame: DmabufFrame,
 ) -> Result<HwFrame> {
+    // The demotion test hook (plan §8, Phase 2 acceptance): fault every import so the
+    // failure-streak → force_software → software-decode recovery is exercisable on any
+    // box, no broken driver required. Read per hw frame — demotion silences it within
+    // three frames, so the env lookup never runs hot.
+    if std::env::var_os("PUNKTFUNK_HW_FAULT").is_some_and(|v| v == "import") {
+        bail!("injected import failure (PUNKTFUNK_HW_FAULT=import)");
+    }
     if frame.fourcc != DRM_FORMAT_NV12 {
         bail!("hw presenter handles NV12 only (got {:#x})", frame.fourcc);
     }