feat(client/present): PUNKTFUNK_PRESENT_MODE gains explicit mailbox and fifo_relaxed arms, and the docs stop guessing

The env knob silently folded 'mailbox' and every typo into the default arm,
FIFO_RELAXED was not reachable at all, and clients/session/README.md claimed
the default is FIFO (it is MAILBOX with a FIFO fallback). An AMD-on-Windows
client always lands on FIFO because that driver offers no MAILBOX — now
documented at the picker and in the docs-site client table, next to the ABR
probe/ceiling knobs a field report went looking for and couldn't find.

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

clients/session/README.md

@@ -61,6 +61,7 @@ default ≈1000 nits). The host still gates the upgrade behind its `PUNKTFUNK_10
 policy.
 
 Debug/bisect knobs: `PUNKTFUNK_DECODER=vulkan|vaapi|d3d11va|software`, `PUNKTFUNK_PRESENT_MODE=
-mailbox|immediate` (default FIFO), `PUNKTFUNK_VK_DEVICE=<index>` (multi-GPU), and
+mailbox|fifo|immediate|fifo_relaxed` (default MAILBOX, FIFO where the surface offers no
+MAILBOX — AMD on Windows), `PUNKTFUNK_VK_DEVICE=<index>` (multi-GPU), and
 `PUNKTFUNK_HW_FAULT=import` (fault every VAAPI dmabuf import — proves the three-strike
 demotion to software on healthy hardware).

crates/pf-presenter/src/vk/setup.rs

@@ -731,12 +731,17 @@ pub(super) fn pick_formats(
 }
 
 /// MAILBOX when the surface offers it, FIFO otherwise (`PUNKTFUNK_PRESENT_MODE=
-/// fifo|mailbox|immediate` overrides). Both are tear-free, but an arrival-paced
-/// presenter must not block in FIFO's present queue: when the compositor holds images
-/// for a vblank pass (gamescope's composite path) or arrival cadence drifts against
-/// refresh, `acquire_next_image` stalls most of a refresh — a standing 11-13 ms added
-/// to every frame at 60 Hz. MAILBOX never queues more than the newest frame, so the
+/// fifo|mailbox|immediate|fifo_relaxed` overrides). Both defaults are tear-free, but an
+/// arrival-paced presenter must not block in FIFO's present queue: when the compositor
+/// holds images for a vblank pass (gamescope's composite path) or arrival cadence drifts
+/// against refresh, `acquire_next_image` stalls most of a refresh — a standing 11-13 ms
+/// added to every frame at 60 Hz. MAILBOX never queues more than the newest frame, so the
 /// pipeline stays at decode latency and a late frame is replaced, not waited for.
+///
+/// AMD's Windows driver offers no MAILBOX (NVIDIA does), so those clients land on FIFO —
+/// expected, not a client misconfiguration. FIFO_RELAXED is opt-in only: it tears exactly
+/// when a stream frame misses the vblank it was pacing for, which on a drifting arrival
+/// cadence is often — a trade the user must choose, never a silent fallback.
 fn pick_present_mode(
     surface_i: &ash::khr::surface::Instance,
     pdev: vk::PhysicalDevice,
@@ -748,7 +753,15 @@ fn pick_present_mode(
     let want = match std::env::var("PUNKTFUNK_PRESENT_MODE").ok().as_deref() {
         Some("fifo") => vk::PresentModeKHR::FIFO,
         Some("immediate") => vk::PresentModeKHR::IMMEDIATE,
-        _ => vk::PresentModeKHR::MAILBOX,
+        Some("fifo_relaxed") => vk::PresentModeKHR::FIFO_RELAXED,
+        Some("mailbox") | None => vk::PresentModeKHR::MAILBOX,
+        Some(other) => {
+            tracing::warn!(
+                value = other,
+                "unknown PUNKTFUNK_PRESENT_MODE (expected fifo|mailbox|immediate|fifo_relaxed) — using mailbox"
+            );
+            vk::PresentModeKHR::MAILBOX
+        }
     };
     Ok(if modes.contains(&want) {
         want

docs-site/content/docs/configuration.md

@@ -241,6 +241,10 @@ A few knobs are read by the native **clients**, not the host:
 | `PUNKTFUNK_PREFER_PYROWAVE` | `1` | Ask for the [PyroWave](/docs/pyrowave) wavelet codec on a wired link, where the client's own setting isn't reachable (the gamepad console, a headless launch). |
 | `PUNKTFUNK_OSD_SCALE` | multiplier, e.g. `1.5` *(default `1`)* | Size of the in-stream overlay — the stats OSD, the capture hint and the start banner. They already follow your display's scaling setting (200 % display → twice the pixels), so set this only to nudge that: bigger for a TV across the room, smaller if your compositor reports an aggressive scale. Clamped to 0.5×–4×, and a line that would run off the screen is shrunk to fit. |
 | `PUNKTFUNK_NO_AEC` | `1` | Turn the microphone's echo cancellation off for this run, whatever **Echo cancellation** says in [client settings](/docs/client-settings#audio). One-way: it can only switch the processing off, never back on, and the setting is the normal way to control it. Linux and Windows clients. |
+| `PUNKTFUNK_PRESENT_MODE` | `mailbox` *(default)* · `fifo` · `immediate` · `fifo_relaxed` | How decoded frames meet the display (the Vulkan present mode). The default prefers MAILBOX — tear-free without queueing behind the vertical refresh — and falls back to FIFO (classic vsync) where the driver doesn't offer it. **AMD's Windows driver offers no MAILBOX**, so those clients run FIFO, which adds a standing frame-pacing wait (up to one refresh interval). `immediate` removes that wait but can tear; `fifo_relaxed` only tears when a frame is late. If your latency floor matters more than tearing, try `immediate` and judge by eye. |
+| `PUNKTFUNK_ABR_PROBE_KBPS` | kbps, e.g. `900000` | The startup link-capacity probe's burst target (default 2 Gbps — deliberately above any plausible link so the burst measures the link, not itself). Lower it on links the burst shouldn't slam, or when the measured ceiling comes out wrong for your setup. |
+| `PUNKTFUNK_ABR_PROBE` | `0` | Skip the startup link-capacity probe entirely. The adaptive-bitrate climb ceiling then stays at the negotiated starting rate — a blunt instrument; prefer `PUNKTFUNK_ABR_MAX_MBPS`. |
+| `PUNKTFUNK_ABR_MAX_MBPS` | Mbps, e.g. `300` | Hard cap on the adaptive bitrate's climb ceiling, whatever the startup probe measured. The escape hatch when adaptive sessions keep climbing past what your client's **decoder** can sustain (periodic hitch + "receive backlog stopped draining" in the client log). An explicit bitrate setting still bypasses ABR entirely. |
 
 ## Bitrate