feat(host/wire): MTU resilience for the video data plane

Video datagrams are sealed at a shard payload sized for a clean 1500-byte
MTU (1472-byte UDP payloads). A host whose route to the client crosses a
smaller-MTU hop (a VPN/overlay adapter claiming the LAN route, a lowered
NIC MTU) delivers every small flow — QUIC control, hole punch, input,
audio — while 100% of video datagrams die: the client sits on a black
screen reporting zero loss and the host streams into the void with every
gauge green. Field-reported as 'connects fine, black screen forever'.

Three legs, none of which changes a session on a healthy path:

- PUNKTFUNK_WIRE_MTU operator override: shard payload derived from a
  given on-wire IP MTU. Wire-compatible — Welcome::shard_payload is
  already negotiated per session (the v4/v6 split ships two values
  today) and every client follows the negotiated value.
- Detection: the QUIC MTU-discovery probe ceiling moves from quinn's
  stock 1452 to exactly the sealed video-datagram size (1472), so a
  control connection's settled MTU becomes a verdict on the path:
  settled at the ceiling proves it carries video, settled below proves
  it cannot. A per-session watcher samples after the search has settled
  (live-connection guard against mid-search false learns) and logs an
  actionable WARN naming the failure shape and the diagnosis commands.
- Healing: the measured budget is recorded per peer IP; the next
  handshake clamps shard_payload to fit, so a reconnect self-heals. A
  later session that reaches the ceiling erases the record.

Verified: core 286/286 --features quic + clippy -D warnings (macOS);
host clippy -D warnings + native:: tests 44/44 (pf-lxcheck container).
The regenerated C header picks up the new MIN_SHARD_PAYLOAD constant.

crates/pf-client-core/src/gamepad.rs

@@ -285,21 +285,6 @@ fn set_valve_hidapi(enabled: bool) {
     sdl3::hint::set("SDL_JOYSTICK_HIDAPI_STEAM", v);
 }
 
-/// Disable the Valve HIDAPI drivers **before SDL exists** — call this alongside the other
-/// pre-`SDL_Init` hints, not after a subsystem is up.
-///
-/// The damage these drivers do happens at *enumeration*, which is part of initialising the
-/// joystick/gamepad subsystem. Setting the hint afterwards does detach the driver, but only after
-/// it has already sent the Deck its `ID_CLEAR_DIGITAL_MAPPINGS` + `TRACKPAD_NONE` — so the
-/// built-in trackpad-mouse dies system-wide and stays dead until the firmware watchdog restores
-/// lizard mode seconds later. The threaded worker ([`run`]) has always done this in the right
-/// order; the caller-pumped path could not, because by the time it receives a
-/// [`sdl3::GamepadSubsystem`] the enumeration has already happened. Hence a separate entry point
-/// its callers can put in the right place.
-pub fn preinit_disable_valve_hidapi() {
-    set_valve_hidapi(false);
-}
-
 /// Map the SDL-reported controller type to the virtual pad we'd ask the host to create.
 fn pref_for_type(t: sdl3::gamepad::GamepadType) -> GamepadPref {
     use sdl3::gamepad::GamepadType as T;
@@ -408,12 +393,9 @@ impl GamepadService {
     /// and calls [`GamepadPump::tick`] once per loop iteration (the threaded worker's
     /// per-wakeup work: ctl drain, chord-hold check, menu repeat, feedback).
     ///
-    /// The Valve HIDAPI drivers are held off here too, but this is **too late to be the only
-    /// place it happens**: the `subsystem` argument means enumeration is already done, and that
-    /// is when the Deck driver kills the trackpad-mouse. The caller must also call
-    /// [`preinit_disable_valve_hidapi`] with its other pre-`SDL_Init` hints. This call still
-    /// earns its place — it re-asserts "off" for a process that ran a session earlier — but on
-    /// its own it only detaches a driver that has already done the damage.
+    /// Like the threaded worker, this disables the Valve HIDAPI drivers up front (their
+    /// mere enumeration kills the Deck's trackpad-mouse system-wide); they are enabled
+    /// for the duration of an attached session only.
     pub fn pumped(subsystem: sdl3::GamepadSubsystem) -> (GamepadService, GamepadPump) {
         set_valve_hidapi(false);
         let pads = Arc::new(Mutex::new(Vec::new()));
@@ -574,38 +556,6 @@ impl GamepadPump {
         self.worker.menu_poll();
         self.worker.render_feedback();
     }
-
-    /// Close every forwarded slot — flush its held wire state, tell the host to remove the pad,
-    /// and physically silence it. Call once on the way out of the caller's event loop.
-    ///
-    /// [`GamepadService::detach`] only *posts* `Ctl::Detach`; the close — the flush, the host-side
-    /// `GamepadRemove`, and the explicit `set_rumble(0, 0)` backstop in `close_slot_at` — happens
-    /// when the pump next drains it. An exit path that detached and then left the loop without
-    /// another [`tick`](Self::tick) therefore skipped all of it, and nothing else would: the slots
-    /// hold no `Drop` that silences them. A pad left mid-buzz stayed buzzing.
-    ///
-    /// This closes the slots directly rather than draining the queued `Ctl::Detach` that would
-    /// have done it. Same physical outcome by a shorter path, and deliberately so: this also runs
-    /// from `Drop`, and `drain_ctl` reaches `Mutex::lock().unwrap()`, which on a poisoned lock
-    /// would panic — during an unwind that aborts the process. Closing a slot touches no lock.
-    ///
-    /// Idempotent, and safe with nothing attached.
-    pub fn shutdown(&mut self) {
-        self.worker.close_all_slots();
-    }
-}
-
-/// The silence backstop of last resort. A caller's loop can also leave by `?` on a fatal overlay
-/// or present error — several paths do — and those would skip an explicit
-/// [`shutdown`](GamepadPump::shutdown) entirely, leaving a forwarded pad buzzing on the way out.
-///
-/// Callers should still call `shutdown` at their normal exit rather than lean on this: the pad
-/// wants to go quiet *before* a long teardown (session join, `vkDeviceWaitIdle`), not after it.
-/// Doing both is free — `shutdown` is idempotent.
-impl Drop for GamepadPump {
-    fn drop(&mut self) {
-        self.shutdown();
-    }
 }
 
 /// The lowest wire pad index (0..[`MAX_PADS`](punktfunk_core::input::MAX_PADS)) not already held
@@ -1676,11 +1626,6 @@ impl Worker {
                 HidOutput::PlayerLeds { bits, .. } if is_ds => {
                     let _ = slot.pad.send_effect(&Ds5Feedback::player_packet(bits));
                 }
-                // Every other pad with player LEDs gets them through SDL, which owns the
-                // per-device pattern. This used to fall through and do nothing at all.
-                HidOutput::PlayerLeds { bits, .. } => {
-                    let _ = set_player_leds(&slot.pad, bits);
-                }
                 HidOutput::Trigger {
                     which, ref effect, ..
                 } if is_ds => {
@@ -1688,43 +1633,12 @@ impl Worker {
                         .pad
                         .send_effect(&Ds5Feedback::trigger_packet(which, effect));
                 }
-                // Deliberately unhandled, listed rather than left to a bare `_` so a new
-                // variant cannot join them silently: adaptive triggers exist only on a
-                // DualSense, and the trackpad-haptic / raw-passthrough planes are DS-specific
-                // and carried by `send_effect` above when the pad is one.
-                HidOutput::Trigger { .. }
-                | HidOutput::TrackpadHaptic { .. }
-                | HidOutput::HidRaw { .. } => {}
+                _ => {}
             }
         }
     }
 }
 
-/// The SDL player index for the wire's positional player-LED `bits`, or `None` for "no player".
-///
-/// The wire carries a bitmask — one bit per LED, low 5 — while SDL wants a player *index* and owns
-/// the per-device pattern. The count bridges them: every convention that reaches this wire spells
-/// "player N" as N lit LEDs, both the DualSense patterns (`0x04`, `0x0A`, `0x15`, `0x1B`, `0x1F`)
-/// and the Switch/XInput run of low bits (`0x01`, `0x03`, `0x07`, `0x0F`). SDL's index is 0-based,
-/// so player 1 is index 0; no lit LED means *no* player rather than player 0.
-///
-/// Split out from [`set_player_leds`] so the mapping is testable — an `sdl3::Gamepad` needs a real
-/// device, so nothing that takes one can be.
-fn player_index_from_bits(bits: u8) -> Option<u16> {
-    match (bits & 0x1F).count_ones() {
-        0 => None,
-        n => Some((n - 1) as u16),
-    }
-}
-
-/// Drive a non-DualSense pad's player LEDs from the wire's positional `bits`.
-fn set_player_leds(pad: &sdl3::gamepad::Gamepad, bits: u8) -> Result<(), sdl3::Error> {
-    match player_index_from_bits(bits) {
-        None => pad.unset_player_index(),
-        Some(i) => pad.set_player_index(i),
-    }
-}
-
 /// The wire pad index a [`HidOutput`] is addressed to (every variant carries `pad`).
 fn hidout_pad(h: &HidOutput) -> u8 {
     match h {
@@ -2094,43 +2008,3 @@ mod slot_tests {
         );
     }
 }
-
-#[cfg(test)]
-mod player_led_tests {
-    use super::*;
-
-    /// Both conventions that reach this wire spell "player N" as N lit LEDs, so the count is the
-    /// player number regardless of WHICH bits a given pad lights. Pinned because the mapping is
-    /// otherwise only obvious once you have seen both patterns side by side.
-    #[test]
-    fn player_index_counts_lit_leds_for_both_conventions() {
-        // DualSense / hid-playstation patterns — non-contiguous, symmetric about the centre LED.
-        assert_eq!(player_index_from_bits(0x04), Some(0)); // player 1
-        assert_eq!(player_index_from_bits(0x0A), Some(1)); // player 2
-        assert_eq!(player_index_from_bits(0x15), Some(2)); // player 3
-        assert_eq!(player_index_from_bits(0x1B), Some(3)); // player 4
-        assert_eq!(player_index_from_bits(0x1F), Some(4)); // player 5
-
-        // Switch/XInput style — a contiguous run of low bits, the same count each time.
-        assert_eq!(player_index_from_bits(0x01), Some(0));
-        assert_eq!(player_index_from_bits(0x03), Some(1));
-        assert_eq!(player_index_from_bits(0x07), Some(2));
-        assert_eq!(player_index_from_bits(0x0F), Some(3));
-    }
-
-    /// No lit LED is "no player", NOT player 0 — the difference between LEDs off and player 1 lit.
-    #[test]
-    fn no_lit_led_is_no_player() {
-        assert_eq!(player_index_from_bits(0x00), None);
-        // Only the low 5 bits are player LEDs; junk above them must not invent a player.
-        assert_eq!(player_index_from_bits(0xE0), None);
-    }
-
-    /// The mask is applied before counting, so out-of-range bits cannot inflate the index past
-    /// the 5 real LEDs.
-    #[test]
-    fn high_bits_are_masked_off_before_counting() {
-        assert_eq!(player_index_from_bits(0xFF), Some(4)); // 0x1F worth of LEDs, not 8
-        assert_eq!(player_index_from_bits(0xE4), Some(0)); // 0x04 with junk on top
-    }
-}

crates/pf-presenter/src/run.rs

@@ -466,13 +466,6 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
     #[cfg(windows)]
     crate::win32::set_app_user_model_id();
     sdl3::hint::set("SDL_JOYSTICK_THREAD", "1");
-    // Hold SDL's Valve HIDAPI drivers off BEFORE SDL_Init: the Deck driver clears the pad's
-    // digital mappings at *enumeration*, which is part of bringing the gamepad subsystem up, so a
-    // hint set after `sdl.gamepad()` — where this used to live, inside GamepadService::pumped —
-    // only detached a driver that had already killed the built-in trackpad-mouse system-wide. The
-    // symptom was the Deck losing its trackpad cursor at the start of every session until the
-    // firmware watchdog restored lizard mode. They are still enabled for an attached session.
-    pf_client_core::gamepad::preinit_disable_valve_hidapi();
     // A touchscreen (the Deck's glass) is forwarded as REAL touch passthrough below — so
     // suppress SDL's default synthesis of mouse events from touch. Left on, every touch
     // ALSO warps a synthetic mouse to the touch point, which under the stream's relative
@@ -1902,13 +1895,6 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
         }
     };
 
-    // Every exit from the loop above converges here, which is why the gamepad teardown belongs
-    // here and not on the individual `break`s. `gamepad.detach()` only queues the detach; the
-    // close — flush, host-side GamepadRemove, and the explicit rumble-stop backstop — runs when
-    // the pump drains it. Single mode broke out of the loop immediately after detaching and
-    // Event::Quit never detached at all, so both left forwarded pads unflushed and, if the game
-    // was rumbling at the time, still buzzing.
-    pump.shutdown();
     // Join the pump BEFORE the device-wide idle: its decode submissions on the shared
     // device would race vkDeviceWaitIdle otherwise.
     if let Some(st) = stream.take() {

crates/punktfunk-core/src/config.rs

@@ -341,6 +341,50 @@ pub fn mtu1500_shard_payload_for(peer: core::net::IpAddr) -> usize {
     }
 }
 
+/// Floor for a negotiated `shard_payload` (even, well under every real path). A path whose UDP
+/// budget lands below this can't carry the QUIC control plane either (QUIC's own minimum is a
+/// 1200-byte UDP payload), so shrinking video shards further buys nothing — the clamp helpers
+/// bottom out here instead of producing degenerate confetti-sized shards.
+pub const MIN_SHARD_PAYLOAD: usize = 512;
+
+/// The sealed wire size of a video datagram carrying `shard_payload` bytes of shard — what
+/// actually leaves the socket as UDP payload (punktfunk header + shard + crypto overhead).
+pub const fn sealed_datagram_bytes(shard_payload: usize) -> usize {
+    HEADER_LEN + shard_payload + CRYPTO_OVERHEAD
+}
+
+/// The UDP-payload size a path must carry for full-size IPv4 video datagrams: the sealed size
+/// of the [`mtu1500_shard_payload`] default (= 1472, the exact 1500-MTU IPv4 ceiling). Doubles
+/// as the QUIC MTU-discovery probe ceiling (`quic/endpoint.rs`): with the ceiling set to
+/// exactly this value, a control connection whose discovery settles AT the ceiling has proven
+/// the path carries full-size video datagrams, and one that settles BELOW it has proven the
+/// path cannot — a discrimination quinn's stock 1452 ceiling can't make in either direction.
+pub const fn video_datagram_udp_ceiling() -> usize {
+    sealed_datagram_bytes(mtu1500_shard_payload())
+}
+
+/// Largest even shard payload whose sealed datagram fits in `udp_budget` bytes of UDP payload
+/// (the quantity QUIC MTU discovery measures — [`video_datagram_udp_ceiling`] is its probe
+/// ceiling). Clamped to the peer's family default ([`mtu1500_shard_payload_for`]) so a generous
+/// budget never grows packets past today's wire, and floored at [`MIN_SHARD_PAYLOAD`].
+pub fn shard_payload_for_udp_budget(udp_budget: usize, peer: core::net::IpAddr) -> usize {
+    let p = udp_budget.saturating_sub(HEADER_LEN + CRYPTO_OVERHEAD);
+    let p = p - p % 2; // FEC requires even shards
+    p.clamp(MIN_SHARD_PAYLOAD, mtu1500_shard_payload_for(peer))
+}
+
+/// [`shard_payload_for_udp_budget`] for an operator-supplied ON-WIRE IP MTU (the number
+/// `netsh interface ipv4 show subinterfaces` / `ip link` shows): subtracts the family's IP+UDP
+/// headers first — 28 for IPv4 (and IPv4-mapped), 48 for IPv6.
+pub fn shard_payload_for_wire_mtu(wire_mtu: usize, peer: core::net::IpAddr) -> usize {
+    let ip_udp = match peer {
+        core::net::IpAddr::V4(_) => 28,
+        core::net::IpAddr::V6(v6) if v6.to_ipv4_mapped().is_some() => 28,
+        core::net::IpAddr::V6(_) => 48,
+    };
+    shard_payload_for_udp_budget(wire_mtu.saturating_sub(ip_udp), peer)
+}
+
 /// Everything needed to construct a [`Session`](crate::session::Session).
 ///
 /// `Debug` is implemented by hand to redact `key`/`salt`, and `key`/`salt` are zeroized
@@ -514,6 +558,74 @@ mod tests {
         assert!(HEADER_LEN + (p + 2) + CRYPTO_OVERHEAD > 1452, "not maximal");
     }
 
+    /// The video-datagram ceiling IS the exact v4 sealed size — the QUIC MTU-discovery probe
+    /// ceiling (endpoint.rs) relies on this equality for its settled-at-vs-below verdict.
+    #[test]
+    fn video_datagram_ceiling_is_the_sealed_default() {
+        assert_eq!(
+            video_datagram_udp_ceiling(),
+            HEADER_LEN + mtu1500_shard_payload() + CRYPTO_OVERHEAD
+        );
+        assert_eq!(video_datagram_udp_ceiling(), 1472);
+    }
+
+    /// Budget-derived sizing: even, sealed-fits-the-budget, clamped to the family default
+    /// above and [`MIN_SHARD_PAYLOAD`] below.
+    #[test]
+    fn shard_payload_for_udp_budget_math() {
+        use core::net::IpAddr;
+        let v4: IpAddr = "192.168.1.50".parse().unwrap();
+        let v6: IpAddr = "fd00::50".parse().unwrap();
+        // The full ceiling reproduces the default exactly.
+        assert_eq!(
+            shard_payload_for_udp_budget(video_datagram_udp_ceiling(), v4),
+            mtu1500_shard_payload()
+        );
+        // A WARP/Tailscale-shaped 1280 budget: sealed result must fit the budget, stay even.
+        let p = shard_payload_for_udp_budget(1280, v4);
+        assert_eq!(p % 2, 0);
+        assert!(sealed_datagram_bytes(p) <= 1280);
+        assert!(sealed_datagram_bytes(p + 2) > 1280, "not maximal");
+        // Odd budgets round down to even shards.
+        assert_eq!(shard_payload_for_udp_budget(1281, v4) % 2, 0);
+        // A generous budget never grows past the family default (either family).
+        assert_eq!(
+            shard_payload_for_udp_budget(9000, v4),
+            mtu1500_shard_payload()
+        );
+        assert_eq!(
+            shard_payload_for_udp_budget(9000, v6),
+            mtu1500_shard_payload_v6()
+        );
+        // Degenerate budgets bottom out at the floor instead of confetti.
+        assert_eq!(shard_payload_for_udp_budget(100, v4), MIN_SHARD_PAYLOAD);
+    }
+
+    /// Operator-facing wire-MTU sizing subtracts the right IP+UDP header per family, and 1500
+    /// reproduces today's defaults exactly.
+    #[test]
+    fn shard_payload_for_wire_mtu_math() {
+        use core::net::IpAddr;
+        let v4: IpAddr = "192.168.1.50".parse().unwrap();
+        let v6: IpAddr = "fd00::50".parse().unwrap();
+        let mapped: IpAddr = "::ffff:192.168.1.50".parse().unwrap();
+        assert_eq!(
+            shard_payload_for_wire_mtu(1500, v4),
+            mtu1500_shard_payload()
+        );
+        assert_eq!(
+            shard_payload_for_wire_mtu(1500, mapped),
+            mtu1500_shard_payload()
+        );
+        assert_eq!(
+            shard_payload_for_wire_mtu(1500, v6),
+            mtu1500_shard_payload_v6()
+        );
+        // 1280 wire − 28 − 64 = 1188 (v4); − 48 − 64 = 1168 (v6).
+        assert_eq!(shard_payload_for_wire_mtu(1280, v4), 1188);
+        assert_eq!(shard_payload_for_wire_mtu(1280, v6), 1168);
+    }
+
     /// Family selection: genuine v6 remotes get the v6 size; v4 — including the IPv4-mapped v6
     /// form a dual-stack `[::]` socket reports for a v4 client — keeps the v4 size.
     #[test]

crates/punktfunk-core/src/quic/endpoint.rs

@@ -47,6 +47,20 @@ fn stream_transport_idle(idle: std::time::Duration) -> Arc<quinn::TransportConfi
     // plane latest-wins at the source — ~200 ms of stereo Opus (proportionally less at
     // surround bitrates), so sustained congestion costs concealable drops, never lag.
     t.datagram_send_buffer_size(4 * 1024);
+    // MTU discovery probes up to EXACTLY the sealed size of a full IPv4 video datagram (1472)
+    // instead of quinn's stock 1452. Two reasons: (a) on a clean 1500-MTU path QUIC gets the
+    // last 20 bytes per packet; (b) the ceiling turns discovery into a video-path verdict the
+    // host's wire-MTU watcher reads (`punktfunk-host` `native/wire_mtu.rs`) — settled == ceiling
+    // proves the path carries full-size video datagrams, settled BELOW it proves it cannot (a
+    // VPN/overlay adapter at MTU ~1280 blackholes every video packet while all the small flows
+    // pass: the "connects fine, black screen forever" field shape). With the stock 1452 ceiling
+    // a healthy path and a constrained one are indistinguishable at the top. This is the ONLY
+    // behavioral change on healthy paths, and it's confined to discovery: probes are padded
+    // PINGs quinn already expects to lose above a constrained hop — a lost probe settles the
+    // search lower, exactly as it did before.
+    let mut mtud = quinn::MtuDiscoveryConfig::default();
+    mtud.upper_bound(crate::config::video_datagram_udp_ceiling() as u16);
+    t.mtu_discovery_config(Some(mtud));
     Arc::new(t)
 }
 

crates/punktfunk-host/src/native.rs

@@ -26,9 +26,7 @@
 #![deny(clippy::undocumented_unsafe_blocks)]
 
 use anyhow::{anyhow, Context, Result};
-use punktfunk_core::config::{
-    mtu1500_shard_payload_for, CompositorPref, FecConfig, FecScheme, GamepadPref, Role,
-};
+use punktfunk_core::config::{CompositorPref, FecConfig, FecScheme, GamepadPref, Role};
 use punktfunk_core::input::{InputEvent, InputKind};
 use punktfunk_core::packet::{FLAG_PIC, FLAG_PROBE, FLAG_SOF};
 use punktfunk_core::quic::{
@@ -72,6 +70,9 @@ use input::{input_thread, ClientInput};
 /// The Hello→Welcome→Start negotiation (plan §W1); `serve_session` calls `handshake::negotiate`
 /// after the pairing gate.
 mod handshake;
+/// MTU resilience for the video data plane: `PUNKTFUNK_WIRE_MTU` override, the per-session
+/// path-MTU watch on the control connection, and the per-peer learned shard-payload clamp.
+mod wire_mtu;
 
 /// The mid-stream control task (plan §W1); `serve_session` spawns `control::run` after the
 /// handshake to multiplex renegotiation / speed-test control messages onto the data-plane channels.

crates/punktfunk-host/src/native/handshake.rs

@@ -491,7 +491,12 @@ pub(super) async fn negotiate(
         // per-datagram loss on Wi-Fi — the "100 Mbps badly fails on the phone" root cause.
         // Negotiated, so the client follows. Jumbo (≈8900) is a future negotiated bump (needs
         // MAX_DATAGRAM_BYTES raised + end-to-end 9000 MTU).
-        shard_payload: mtu1500_shard_payload_for(peer.ip()) as u16,
+        // Resolution order (wire_mtu.rs): `PUNKTFUNK_WIRE_MTU` operator override, then a path
+        // budget learned from a prior session whose QUIC MTU discovery settled below the
+        // video-datagram ceiling (the "VPN on the host blackholes every video packet" field
+        // shape — small flows pass, the stream is an endless black screen), then this family
+        // default. Healthy paths take the default branch and are byte-identical to before.
+        shard_payload: wire_mtu::negotiated_shard_payload(peer.ip()) as u16,
         encrypt: true,
         key,
         salt,
@@ -658,6 +663,10 @@ pub(super) async fn negotiate(
     let start =
         Start::decode(&io::read_msg(recv).await?).map_err(|e| anyhow!("Start decode: {e:?}"))?;
     bringup.mark("start");
+    // The session is real: watch this connection's MTU discovery settle and turn it into a
+    // path verdict (WARN + learned clamp for the next session on a constrained path; clears a
+    // stale clamp on a healthy one). Bounded ~10 s task, ends by itself.
+    wire_mtu::spawn_watch(conn.clone(), welcome.shard_payload as usize);
     Ok::<_, anyhow::Error>((
         hello,
         welcome,

crates/punktfunk-host/src/native/wire_mtu.rs

@@ -0,0 +1,192 @@
+//! MTU resilience for the video data plane (the "connects fine, black screen forever" field
+//! shape).
+//!
+//! Video datagrams are sealed at a per-session `shard_payload` sized for a clean 1500-byte MTU
+//! (1472-byte UDP payloads). A host whose route to the client runs through a smaller-MTU hop —
+//! a VPN/overlay adapter (Tailscale/WARP/ZeroTier default to 1280) claiming the LAN route, or a
+//! lowered NIC MTU — delivers every SMALL flow (QUIC control, hole punch, input, audio) while
+//! 100 % of video datagrams die by fragmentation or local `WSAEMSGSIZE`: the client sits on a
+//! black screen reporting `loss_ppm=0` (it can't see gaps in packets it never saw any of) and
+//! the host streams into the void with every gauge green. Neither side observes the failure
+//! directly — but the control connection CAN: its MTU discovery probes up to exactly the sealed
+//! video-datagram size ([`video_datagram_udp_ceiling`], set in `quic/endpoint.rs`), so its
+//! settled MTU is a verdict on the path.
+//!
+//! Three legs, none of which changes a session on a healthy path:
+//! - **`PUNKTFUNK_WIRE_MTU=<bytes>`** — operator override; the shard payload is derived from
+//!   the given on-wire IP MTU. Wire-compatible with every deployed client:
+//!   `Welcome::shard_payload` is already negotiated per session (the v4/v6 split ships two
+//!   values today) and clients follow the negotiated value.
+//! - **Watch** — a per-session task samples the control connection's discovered MTU once the
+//!   search has had time to finish. A connection still alive that settled BELOW the ceiling is
+//!   proof the path can't carry full-size video: log an actionable WARN and record the measured
+//!   budget for the peer.
+//! - **Heal** — the next handshake from that peer clamps `shard_payload` to the recorded
+//!   budget, so a reconnect fixes the stream. A later session that reaches the ceiling erases
+//!   the record (the learn/heal loop is self-correcting in both directions).
+
+use std::collections::HashMap;
+use std::net::IpAddr;
+use std::sync::{Mutex, OnceLock};
+
+use punktfunk_core::config::{
+    mtu1500_shard_payload_for, sealed_datagram_bytes, shard_payload_for_udp_budget,
+    shard_payload_for_wire_mtu, video_datagram_udp_ceiling,
+};
+
+/// Measured UDP-payload budget per peer IP, learned from live control connections whose MTU
+/// discovery settled below the video-datagram ceiling. In-memory only: a host restart
+/// re-learns in one session, and entries self-correct (a later ceiling-hit erases, a lower
+/// re-measure overwrites).
+fn learned() -> &'static Mutex<HashMap<IpAddr, u16>> {
+    static LEARNED: OnceLock<Mutex<HashMap<IpAddr, u16>>> = OnceLock::new();
+    LEARNED.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// The shard payload for a new session to `peer`: `PUNKTFUNK_WIRE_MTU` override, else the
+/// peer's learned path budget, else the family default (today's exact behavior). Logs whenever
+/// the result differs from the default.
+pub(super) fn negotiated_shard_payload(peer: IpAddr) -> usize {
+    let env = match std::env::var("PUNKTFUNK_WIRE_MTU") {
+        Ok(v) => match v.trim().parse::<usize>() {
+            Ok(mtu) => Some(mtu),
+            Err(_) => {
+                tracing::warn!(value = %v, "PUNKTFUNK_WIRE_MTU is not a number — ignoring it");
+                None
+            }
+        },
+        Err(_) => None,
+    };
+    let learned_budget = learned().lock().unwrap().get(&peer).copied();
+    resolve(env, learned_budget, peer)
+}
+
+/// Pure resolution (env override > learned budget > family default) — the tested core of
+/// [`negotiated_shard_payload`].
+fn resolve(env_wire_mtu: Option<usize>, learned_udp_budget: Option<u16>, peer: IpAddr) -> usize {
+    let default = mtu1500_shard_payload_for(peer);
+    if let Some(mtu) = env_wire_mtu {
+        let p = shard_payload_for_wire_mtu(mtu, peer);
+        if p != default {
+            tracing::info!(
+                wire_mtu = mtu,
+                shard_payload = p,
+                default,
+                "wire MTU: shard payload set from PUNKTFUNK_WIRE_MTU"
+            );
+        }
+        return p;
+    }
+    if let Some(budget) = learned_udp_budget {
+        let p = shard_payload_for_udp_budget(budget as usize, peer);
+        if p != default {
+            tracing::info!(
+                peer = %peer,
+                udp_budget = budget,
+                shard_payload = p,
+                default,
+                "wire MTU: shard payload clamped to this peer's measured path MTU (learned \
+                 from a prior session's QUIC MTU discovery) — video datagrams now fit the \
+                 constrained hop"
+            );
+            return p;
+        }
+    }
+    default
+}
+
+/// Sample the control connection's discovered MTU after the search has settled and turn it
+/// into a verdict. Spawned once per negotiated session; the task ends by itself after the
+/// final sample (bounded ~10 s lifetime, holding only a cheap `Connection` handle).
+pub(super) fn spawn_watch(conn: quinn::Connection, session_shard_payload: usize) {
+    tokio::spawn(async move {
+        let peer = conn.remote_address().ip();
+        let ceiling = video_datagram_udp_ceiling() as u16;
+        // Discovery finishes in a handful of RTTs on a LAN (well under the first sample) but
+        // needs a loss timeout per failed probe on a constrained path — the second sample
+        // covers that with margin. Max, because discovery only ever raises `current_mtu`.
+        let mut settled = 0u16;
+        for wait_s in [3u64, 7] {
+            tokio::time::sleep(std::time::Duration::from_secs(wait_s)).await;
+            settled = settled.max(conn.stats().path.current_mtu);
+            if settled >= ceiling {
+                break;
+            }
+        }
+        if settled >= ceiling {
+            // The path carries full-size video datagrams — erase any stale learned clamp so
+            // the next session returns to the default wire.
+            if learned().lock().unwrap().remove(&peer).is_some() {
+                tracing::info!(peer = %peer,
+                    "wire MTU: path re-measured at full size — learned clamp cleared");
+            }
+            return;
+        }
+        // A closed connection stops discovering, so a session that ended before the final
+        // sample proves nothing (a healthy high-RTT path could still be mid-search): learn
+        // only from a connection that stayed alive through the whole window.
+        if conn.close_reason().is_some() {
+            return;
+        }
+        learned().lock().unwrap().insert(peer, settled);
+        if sealed_datagram_bytes(session_shard_payload) <= settled as usize {
+            // This session was already clamped small enough — the path is still constrained
+            // (keep the record fresh) but video fits, so no alarm.
+            tracing::info!(peer = %peer, discovered_udp_mtu = settled,
+                "wire MTU: constrained path re-measured; this session's video is sized to fit");
+        } else {
+            tracing::warn!(
+                peer = %peer,
+                discovered_udp_mtu = settled,
+                needed_udp_mtu = ceiling,
+                "wire MTU: this path CANNOT carry full-size video datagrams — the control \
+                 plane works but every video packet is oversized for a hop, which streams as \
+                 an endless black screen with zero reported loss. Typical cause: a VPN/overlay \
+                 adapter (Tailscale / Cloudflare WARP / ZeroTier) claiming the LAN route, or a \
+                 lowered NIC MTU — compare `ping <client> -f -l 1450` vs `-l 1200` and check \
+                 `netsh interface ipv4 show subinterfaces` (Windows) / `ip link` (Linux). The \
+                 measured budget is recorded: the NEXT session from this client sizes video to \
+                 fit automatically. To pin it for all sessions set PUNKTFUNK_WIRE_MTU."
+            );
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+    const V4: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 2));
+    const V6: IpAddr = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
+
+    #[test]
+    fn default_when_nothing_known() {
+        assert_eq!(resolve(None, None, V4), mtu1500_shard_payload_for(V4));
+        assert_eq!(resolve(None, None, V6), mtu1500_shard_payload_for(V6));
+    }
+
+    #[test]
+    fn env_override_beats_learned() {
+        // 1280 wire − 28 IP/UDP − 64 header/crypto = 1188.
+        assert_eq!(resolve(Some(1280), Some(1472), V4), 1188);
+    }
+
+    #[test]
+    fn learned_budget_clamps() {
+        // A WARP-shaped path: 1280-byte UDP budget → 1280 − 64 = 1216.
+        assert_eq!(resolve(None, Some(1280), V4), 1216);
+    }
+
+    #[test]
+    fn learned_at_or_above_ceiling_is_the_default_wire() {
+        assert_eq!(resolve(None, Some(1472), V4), mtu1500_shard_payload_for(V4));
+        assert_eq!(resolve(None, Some(2000), V4), mtu1500_shard_payload_for(V4));
+    }
+
+    #[test]
+    fn env_full_mtu_is_the_default_wire_both_families() {
+        assert_eq!(resolve(Some(1500), None, V4), mtu1500_shard_payload_for(V4));
+        assert_eq!(resolve(Some(1500), None, V6), mtu1500_shard_payload_for(V6));
+    }
+}

include/punktfunk_core.h

@@ -333,6 +333,12 @@
 #define INBOUND_REQ_FLAG 2147483648
 #endif
 
+// Floor for a negotiated `shard_payload` (even, well under every real path). A path whose UDP
+// budget lands below this can't carry the QUIC control plane either (QUIC's own minimum is a
+// 1200-byte UDP payload), so shrinking video shards further buys nothing — the clamp helpers
+// bottom out here instead of producing degenerate confetti-sized shards.
+#define MIN_SHARD_PAYLOAD 512
+
 // 16-byte AEAD authentication tag appended by either session cipher.
 #define TAG_LEN 16