fix(host/windows): two virtual pads stop tearing each other's reports

Three faults on the Windows pad path, two of them races that only bite when a game drives a pad hard enough for two callbacks to overlap. pf-gamepad's output ring could hand the host a torn report. Publishing is a read-modify-write — read the cursor, write the slot it names, advance it — and the framework dispatches output callbacks in parallel, so two could be inside it at once: both read the same head, both wrote the SAME slot, and both stored head+1, so the cursor moved once for two reports and the host read a single entry with two reports mixed into it. An atomic fetch_add does not fix this. It hands each writer its own slot but advances the cursor before the bytes exist, so the host is then invited to read a slot still being filled. Serializing the publish is what makes the cursor bump mean "the slot below is complete". The ring exists to stop a rumble STOP being coalesced away, and a torn slot can eat that STOP with no idle watchdog behind it. Both drivers also promised the host an ordering they never established. The host loads out_seq and rumble_seq with Acquire and says so in its own comments — "Acquire pairs with the driver's publish-then-bump store order" — but the drivers bumped both with plain writes, and an Acquire load pairs with a Release store and nothing else. On a weakly-ordered core the host could see a fresh seq against stale bytes. pf-xusb's rumble seq was racy in the same way as the ring: two SET_STATE calls could both read one value and both write back value+1, so the host saw one bump for two writes and skipped a level. A skipped stop is the one that hurts — the pad buzzes until the ~2.5 s idle force-off notices the game went quiet, which is what bounds the damage. Diagnosing an unattached driver stalled the session. The pad service thread — the one feeding input and rumble — waited up to two seconds for a pnputil enumeration, per unattached pad, at exactly the moment a session was already going wrong. The diagnosis now runs on its own thread. Off the hot path the wait no longer has to be a compromise, so it is generous enough to report what it actually found instead of giving up with "still enumerating" — which, given pnputil routinely takes longer than the old budget, is what it usually did.
Merge pull request 'chore(release): bump workspace version to 0.24.0' (#29 ) from worktree-release-0240 into main
2026-08-04 19:20:01 +02:00 · 2026-08-03 19:43:24 +00:00 · 2026-08-03 21:40:38 +02:00 · 2026-08-03 19:17:49 +00:00 · 2026-08-03 19:17:01 +00:00 · 2026-08-03 19:16:24 +00:00
103 changed files with 7840 additions and 821 deletions
@@ -947,7 +947,7 @@ dependencies = [

 [[package]]
 name = "cursor-probe"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "pf-capture",
@@ -1036,7 +1036,7 @@ dependencies = [

 [[package]]
 name = "display-disturb"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "windows 0.62.2 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -2221,7 +2221,7 @@ dependencies = [

 [[package]]
 name = "latency-probe"
-version = "0.23.0"
+version = "0.24.0"

 [[package]]
 name = "lazy_static"
@@ -2326,7 +2326,7 @@ dependencies = [

 [[package]]
 name = "libvpl-sys"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "bindgen",
 "cmake",
@@ -2361,7 +2361,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"

 [[package]]
 name = "loss-harness"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "punktfunk-core",
 ]
@@ -2850,7 +2850,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"

 [[package]]
 name = "pf-capture"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -2871,7 +2871,7 @@ dependencies = [

 [[package]]
 name = "pf-client-core"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -2897,7 +2897,7 @@ dependencies = [

 [[package]]
 name = "pf-clipboard"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -2915,7 +2915,7 @@ dependencies = [

 [[package]]
 name = "pf-console-ui"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -2936,7 +2936,7 @@ dependencies = [

 [[package]]
 name = "pf-encode"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -2960,7 +2960,7 @@ dependencies = [

 [[package]]
 name = "pf-ffvk"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "ash",
 "bindgen",
@@ -2969,7 +2969,7 @@ dependencies = [

 [[package]]
 name = "pf-frame"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "libc",
@@ -2981,7 +2981,7 @@ dependencies = [

 [[package]]
 name = "pf-gpu"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "pf-host-config",
@@ -2995,11 +2995,11 @@ dependencies = [

 [[package]]
 name = "pf-host-config"
-version = "0.23.0"
+version = "0.24.0"

 [[package]]
 name = "pf-inject"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -3028,14 +3028,14 @@ dependencies = [

 [[package]]
 name = "pf-paths"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "tracing",
 ]

 [[package]]
 name = "pf-presenter"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -3050,7 +3050,7 @@ dependencies = [

 [[package]]
 name = "pf-update"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "serde",
 "serde_json",
@@ -3058,7 +3058,7 @@ dependencies = [

 [[package]]
 name = "pf-update-check"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "base64",
@@ -3070,7 +3070,7 @@ dependencies = [

 [[package]]
 name = "pf-vdisplay"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ashpd",
@@ -3103,7 +3103,7 @@ dependencies = [

 [[package]]
 name = "pf-win-display"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "pf-paths",
@@ -3115,7 +3115,7 @@ dependencies = [

 [[package]]
 name = "pf-zerocopy"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ash",
@@ -3323,7 +3323,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-cli"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "pf-client-core",
 "punktfunk-core",
@@ -3334,7 +3334,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-android"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "android_logger",
 "jni",
@@ -3350,7 +3350,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-linux"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -3367,7 +3367,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-session"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "pf-client-core",
@@ -3382,7 +3382,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-client-windows"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "async-channel",
 "ffmpeg-next",
@@ -3402,7 +3402,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-core"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "aes-gcm",
 "bytes",
@@ -3434,7 +3434,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-host"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "aes",
 "aes-gcm",
@@ -3519,7 +3519,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-probe"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "mdns-sd",
@@ -3533,7 +3533,7 @@ dependencies = [

 [[package]]
 name = "punktfunk-tray"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "anyhow",
 "ksni",
@@ -3556,7 +3556,7 @@ checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"

 [[package]]
 name = "pyrowave-sys"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
 "bindgen",
 "cmake",
@@ -53,7 +53,7 @@ exclude = [
 ndk = { path = "clients/android/native/vendor/ndk" }

 [workspace.package]
-version = "0.23.0"
+version = "0.24.0"
 edition = "2021"
 rust-version = "1.82"
 license = "MIT OR Apache-2.0"
@@ -10,7 +10,7 @@
      "name": "MIT OR Apache-2.0",
      "identifier": "MIT OR Apache-2.0"
    },
-    "version": "0.22.3"
+    "version": "0.23.0"
  },
  "paths": {
    "/api/v1/clients": {
@@ -2170,6 +2170,51 @@
        }
      }
    },
+    "/api/v1/plugins/logs": {
+      "post": {
+        "tags": [
+          "plugins"
+        ],
+        "summary": "Ingest runner log lines",
+        "description": "The plugin/script runner ships its output here so the console's **Logs** page can show it.\n\nPlugins are not host child processes — the runner is a separate `bun` process that `import()`s\neach plugin in-process — so nothing a plugin logs passes through the host's own `tracing`, and\nbefore this endpoint the console's log page could not show a single plugin line. On Linux the\nfallback was `journalctl --user -u punktfunk-scripting`; on Windows the runner task writes no\nlog file at all, so a failing plugin was diagnosable only by stopping the scheduled task and\nre-running the runner by hand. Both are shell access on the host box, which is exactly what the\nconsole exists to avoid.\n\nLines land in the same ring as the host's own, sharing one `seq` cursor, targeted\n`plugin:<source>` — so `GET /logs` needs no second cursor and the console needs no second poll.",
+        "operationId": "ingestPluginLogs",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PluginLogBatch"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "204": {
+            "description": "Lines ingested"
+          },
+          "400": {
+            "description": "Batch too large",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or invalid bearer token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
    "/api/v1/plugins/{id}": {
      "put": {
        "tags": [
@@ -6238,6 +6283,50 @@
          "gamestream"
        ]
      },
+      "PluginLogBatch": {
+        "type": "object",
+        "description": "A batch of runner log lines.",
+        "required": [
+          "entries"
+        ],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PluginLogLine"
+            }
+          }
+        }
+      },
+      "PluginLogLine": {
+        "type": "object",
+        "description": "One log line produced by the runner or a plugin inside it (`POST /plugins/logs`).",
+        "required": [
+          "ts_ms",
+          "level",
+          "source",
+          "msg"
+        ],
+        "properties": {
+          "level": {
+            "type": "string",
+            "description": "`ERROR` | `WARN` | `INFO` | `DEBUG` | `TRACE`. Anything else is coerced to `INFO`."
+          },
+          "msg": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string",
+            "description": "Which unit emitted it — a plugin's `definePlugin` name, a package name, or `runner`.\nSurfaced in the console's target column as `plugin:<source>`."
+          },
+          "ts_ms": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When the line was produced, unix milliseconds. Kept verbatim — see\n[`crate::log_capture::LogRing::push_remote`].",
+            "minimum": 0
+          }
+        }
+      },
      "PluginRegistration": {
        "type": "object",
        "description": "Register/renew body for `PUT /plugins/{id}`.",
@@ -401,8 +401,15 @@ private fun buildSettingsRows(
            s.echoCancel,
        ) { update(s.copy(echoCancel = it)) },

+        toggle(
+            "padForward", "Controllers", "Forward controllers",
+            "Send this device's controllers to the host. Turn it off when your controller " +
+                "already reaches the host another way — USB passthrough such as VirtualHere — " +
+                "so games don't see two of them.",
+            s.gamepadForwarding,
+        ) { update(s.copy(gamepadForwarding = it)) },
        choice(
-            "padType", "Controllers", "Controller type",
+            "padType", null, "Controller type",
            "The virtual pad the host creates — Automatic matches this controller.",
            GAMEPAD_OPTIONS, s.gamepad,
        ) { update(s.copy(gamepad = it)) },
@@ -43,6 +43,7 @@ data class SettingsOverlay(
    val mouseMode: MouseMode? = null,
    val invertScroll: Boolean? = null,
    val gamepad: Int? = null,
+    val gamepadForwarding: Boolean? = null,
    val statsVerbosity: StatsVerbosity? = null,
    /**
     * Android-only tier-P addition (design §3): the decode pipeline is a device fact everywhere
@@ -76,6 +77,7 @@ data class SettingsOverlay(
        mouseMode = mouseMode ?: base.mouseMode,
        invertScroll = invertScroll ?: base.invertScroll,
        gamepad = gamepad ?: base.gamepad,
+        gamepadForwarding = gamepadForwarding ?: base.gamepadForwarding,
        statsVerbosity = statsVerbosity ?: base.statsVerbosity,
        lowLatencyMode = lowLatencyMode ?: base.lowLatencyMode,
        presentPriority = presentPriority ?: base.presentPriority,
@@ -110,6 +112,9 @@ data class SettingsOverlay(
        mouseMode = if (after.mouseMode != before.mouseMode) after.mouseMode else mouseMode,
        invertScroll = if (after.invertScroll != before.invertScroll) after.invertScroll else invertScroll,
        gamepad = if (after.gamepad != before.gamepad) after.gamepad else gamepad,
+        gamepadForwarding =
+            if (after.gamepadForwarding != before.gamepadForwarding) after.gamepadForwarding
+            else gamepadForwarding,
        statsVerbosity = if (after.statsVerbosity != before.statsVerbosity) after.statsVerbosity else statsVerbosity,
        lowLatencyMode = if (after.lowLatencyMode != before.lowLatencyMode) after.lowLatencyMode else lowLatencyMode,
        presentPriority = if (after.presentPriority != before.presentPriority) after.presentPriority else presentPriority,
@@ -136,6 +141,7 @@ data class SettingsOverlay(
        "mouse_mode" -> copy(mouseMode = null)
        "invert_scroll" -> copy(invertScroll = null)
        "gamepad" -> copy(gamepad = null)
+        "gamepad_forwarding" -> copy(gamepadForwarding = null)
        "stats_verbosity" -> copy(statsVerbosity = null)
        "low_latency_mode" -> copy(lowLatencyMode = null)
        "present_priority" -> copy(presentPriority = null)
@@ -159,6 +165,7 @@ data class SettingsOverlay(
        if (mouseMode != null) add("mouse_mode")
        if (invertScroll != null) add("invert_scroll")
        if (gamepad != null) add("gamepad")
+        if (gamepadForwarding != null) add("gamepad_forwarding")
        if (statsVerbosity != null) add("stats_verbosity")
        if (lowLatencyMode != null) add("low_latency_mode")
        if (presentPriority != null) add("present_priority")
@@ -190,6 +197,7 @@ data class SettingsOverlay(
        mouseMode?.let { j.put("mouse_mode", it.storedName) }
        invertScroll?.let { j.put("invert_scroll", it) }
        gamepad?.let { j.put("gamepad", it) }
+        gamepadForwarding?.let { j.put("gamepad_forwarding", it) }
        statsVerbosity?.let { j.put("stats_verbosity", it.name) }
        lowLatencyMode?.let { j.put("low_latency_mode", it) }
        presentPriority?.let { j.put("present_priority", it) }
@@ -205,7 +213,8 @@ data class SettingsOverlay(
        private val KNOWN = setOf(
            "width", "height", "refresh_hz", "bitrate_kbps", "render_scale", "codec",
            "hdr_enabled", "compositor", "audio_channels", "mic_enabled", "echo_cancel",
-            "touch_mode", "mouse_mode", "invert_scroll", "gamepad", "stats_verbosity",
+            "touch_mode", "mouse_mode", "invert_scroll", "gamepad", "gamepad_forwarding",
+            "stats_verbosity",
            "low_latency_mode", "present_priority", "smooth_buffer",
        )

@@ -227,6 +236,7 @@ data class SettingsOverlay(
                ?.let { n -> MouseMode.entries.firstOrNull { it.storedName == n } },
            invertScroll = j.optBooleanOrNull("invert_scroll"),
            gamepad = j.optIntOrNull("gamepad"),
+            gamepadForwarding = j.optBooleanOrNull("gamepad_forwarding"),
            statsVerbosity = j.optStringOrNull("stats_verbosity")
                ?.let { n -> StatsVerbosity.entries.firstOrNull { it.name == n } },
            lowLatencyMode = j.optBooleanOrNull("low_latency_mode"),
@@ -34,6 +34,17 @@ data class Settings(
    val hdrEnabled: Boolean = true,
    val compositor: Int = 0,
    val gamepad: Int = 0,
+    /**
+     * Forward this device's controllers to the host at all. Default on — that was the
+     * unconditional behaviour before this became a setting.
+     *
+     * Off is for a couch whose controller reaches the host another way: a USB passthrough tool
+     * (VirtualHere and friends), or a pad simply plugged into the host itself. Leaving it on
+     * there gives the host two controllers for one pair of hands, and games read both. It also
+     * stops this device CLAIMING the pad — a device held open is one a passthrough tool can't
+     * bind — which is why it gates the USB capture paths, not just the wire sends.
+     */
+    val gamepadForwarding: Boolean = true,
    /** Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
     * can capture; the resolved count drives the decoder + AAudio layout. */
    val audioChannels: Int = 2,
@@ -216,6 +227,7 @@ class SettingsStore(context: Context) {
        hdrEnabled = prefs.getBoolean(K_HDR, true),
        compositor = prefs.getInt(K_COMPOSITOR, 0),
        gamepad = prefs.getInt(K_GAMEPAD, 0),
+        gamepadForwarding = prefs.getBoolean(K_GAMEPAD_FORWARDING, true),
        audioChannels = prefs.getInt(K_AUDIO_CH, 2),
        codec = prefs.getString(K_CODEC, "auto") ?: "auto",
        micEnabled = prefs.getBoolean(K_MIC, false),
@@ -262,6 +274,7 @@ class SettingsStore(context: Context) {
            .putBoolean(K_HDR, s.hdrEnabled)
            .putInt(K_COMPOSITOR, s.compositor)
            .putInt(K_GAMEPAD, s.gamepad)
+            .putBoolean(K_GAMEPAD_FORWARDING, s.gamepadForwarding)
            .putInt(K_AUDIO_CH, s.audioChannels)
            .putString(K_CODEC, s.codec)
            .putBoolean(K_MIC, s.micEnabled)
@@ -291,6 +304,7 @@ class SettingsStore(context: Context) {
        const val K_HDR = "hdr_enabled"
        const val K_COMPOSITOR = "compositor"
        const val K_GAMEPAD = "gamepad"
+        const val K_GAMEPAD_FORWARDING = "gamepad_forwarding"
        const val K_AUDIO_CH = "audio_channels"
        const val K_CODEC = "codec"
        const val K_MIC = "mic_enabled"
@@ -818,11 +818,23 @@ private fun AudioSettings(s: Settings, update: (Settings) -> Unit, onMicChange:
@Composable
 private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenControllers: () -> Unit) {
    SettingsGroup(footer = "Applies from the next session.") {
+        // The master switch, above everything it governs. Profileable, so it shows in both
+        // scopes: a "Work" profile can decline to forward what "Game" forwards.
+        ToggleRow(
+            title = "Forward controllers",
+            subtitle = "Send this device's controllers to the host. Turn it off when your " +
+                "controller already reaches the host another way — USB passthrough such as " +
+                "VirtualHere, or a pad plugged into the host — so games don't see two of them",
+            checked = s.gamepadForwarding,
+            field = "gamepad_forwarding",
+            onCheckedChange = { on -> update(s.copy(gamepadForwarding = on)) },
+        )
        SettingDropdown(
            label = "Controller type",
            options = GAMEPAD_OPTIONS,
            selected = s.gamepad,
            field = "gamepad",
+            enabled = s.gamepadForwarding,
            caption = "The virtual pad the host creates. Automatic matches your controller; " +
                "every connected one is forwarded as its own player.",
        ) { g -> update(s.copy(gamepad = g)) }
@@ -852,6 +864,7 @@ private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenCo
                subtitle = "Stream a Steam Controller 2 as-is — Steam on the host drives its " +
                    "trackpads, gyro and haptics directly",
                checked = s.sc2Capture,
+                enabled = s.gamepadForwarding,
                onCheckedChange = { on -> update(s.copy(sc2Capture = on)) },
            )
            // Same no-vibrator-gate reasoning as the SC2 row: this capture renders feedback on
@@ -861,6 +874,7 @@ private fun ControllerSettings(s: Settings, update: (Settings) -> Unit, onOpenCo
                subtitle = "Drive a USB-connected Sony pad directly — rumble on any phone, " +
                    "plus adaptive triggers, lightbar and gyro",
                checked = s.dsCapture,
+                enabled = s.gamepadForwarding,
                onCheckedChange = { on -> update(s.copy(dsCapture = on)) },
            )
        }
@@ -1013,6 +1027,7 @@ private fun <T> SettingDropdown(
    selected: T,
    field: String? = null,
    caption: String? = null,
+    enabled: Boolean = true,
    onSelect: (T) -> Unit,
 ) {
    var expanded by remember { mutableStateOf(false) }
@@ -1020,18 +1035,25 @@ private fun <T> SettingDropdown(
        ?: options.firstOrNull()?.second.orEmpty()
    Column {
        OverrideBadge(field)
-        ExposedDropdownMenuBox(expanded = expanded, onExpandedChange = { expanded = it }) {
+        ExposedDropdownMenuBox(
+            expanded = expanded && enabled,
+            onExpandedChange = { if (enabled) expanded = it },
+        ) {
            OutlinedTextField(
                value = selectedLabel,
                onValueChange = {},
                readOnly = true,
+                enabled = enabled,
                label = { Text(label) },
                trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
                modifier = Modifier
                    .menuAnchor(ExposedDropdownMenuAnchorType.PrimaryNotEditable)
                    .fillMaxWidth(),
            )
-            ExposedDropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
+            ExposedDropdownMenu(
+                expanded = expanded && enabled,
+                onDismissRequest = { expanded = false },
+            ) {
                options.forEach { (value, lbl) ->
                    DropdownMenuItem(
                        text = { Text(lbl) },
@@ -321,7 +321,9 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
        // Multi-controller router: a stable wire pad index per connected controller, per-device axis
        // state, Arrival/Remove on hot-plug, and feedback routed back by pad index. Forwards every
        // controller (Automatic). Built here, released on dispose.
-        val router = GamepadRouter(context, handle, initialSettings.gamepad)
+        val router = GamepadRouter(
+            context, handle, initialSettings.gamepad, initialSettings.gamepadForwarding,
+        )
        activity?.gamepadRouter = router
        // Select+Start+L1+R1 chord leaves the stream — a deliberate quit (signal it so the host skips
        // the keep-alive linger), unlike a host-ended / backgrounded drop. The router debounces it
@@ -442,7 +444,11 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
        // The menu-time capture (UI navigation) must let go before the stream-mode capture can
        // claim the interfaces; it resumes in onDispose once the stream releases them.
        activity?.stopSc2MenuNav()
-        val sc2 = if (initialSettings.sc2Capture) Sc2Capture(context, router) else null
+        val sc2 = if (initialSettings.sc2Capture && initialSettings.gamepadForwarding) {
+            Sc2Capture(context, router)
+        } else {
+            null
+        }
        var sc2UsbReceiver: BroadcastReceiver? = null
        if (sc2 != null) {
            feedback.onHidRaw = sc2::onHidRaw
@@ -492,7 +498,11 @@ fun StreamScreen(session: ActiveSession, onDisconnect: () -> Unit) {
        // the automatic fallback. Host feedback routes back through feedback.sink; the claim
        // frees the pad's InputDevice slot itself (see DsCapture.startUsb), so the wire index
        // hands over deterministically.
-        val ds = if (initialSettings.dsCapture) DsCapture(context, router) else null
+        val ds = if (initialSettings.dsCapture && initialSettings.gamepadForwarding) {
+            DsCapture(context, router)
+        } else {
+            null
+        }
        var dsUsbReceiver: BroadcastReceiver? = null
        if (ds != null) {
            feedback.sink = ds
@@ -33,7 +33,24 @@ import java.util.concurrent.ConcurrentHashMap
 * InputManager hot-plug callbacks both land there). [deviceForPad] is read from the feedback poll
 * threads, so the slot table is a [ConcurrentHashMap].
 */
-class GamepadRouter(context: Context, private val handle: Long, private val setting: Int) {
+class GamepadRouter(
+    context: Context,
+    private val handle: Long,
+    private val setting: Int,
+    /**
+     * Forward this device's controllers to the host at all (`Settings.gamepadForwarding`,
+     * default true). Off is for a couch whose controller reaches the host another way — USB
+     * passthrough such as VirtualHere, or a pad plugged into the host itself — where forwarding
+     * as well would give the host two pads for one pair of hands.
+     *
+     * Off still opens slots and tracks held state; it only stops the wire sends. That is
+     * deliberate: the exit and mic chords are read off the same slots, and a couch that lost its
+     * quit shortcut because a forwarding preference was off would be the worse bug. Nothing is
+     * claimed by keeping a slot — the Android input stack shares controllers — unlike the USB
+     * capture links, which `StreamScreen` does not start at all while this is off.
+     */
+    private val forwarding: Boolean = true,
+) {

    /** One forwarded controller: its stable wire pad index, per-device axis state, and held buttons. */
    private class Slot(val index: Int, val mapper: Gamepad.AxisMapper) {
@@ -123,7 +140,9 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
     */
    private fun slotButton(slot: Slot, bit: Int, down: Boolean, send: Boolean) {
        if (down) {
-            if (send) NativeBridge.nativeSendGamepadButton(handle, bit, true, slot.index)
+            if (send && forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, bit, true, slot.index)
+            }
            val wasHeld = slot.held
            slot.held = slot.held or bit
            // Full chord now held on this pad → start the hold countdown (idempotent while held).
@@ -136,7 +155,9 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
                onMicChord?.invoke()
            }
        } else {
-            if (send) NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
+            if (send && forwarding) {
+                NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
+            }
            slot.held = slot.held and bit.inv()
            // A chord button lifted before the hold elapsed → cancel, unless another pad still
            // holds the full chord.
@@ -186,7 +207,7 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        val dev = event.device ?: return false
        if (!isForwardable(dev)) return false
        val slot = slotFor(dev) ?: return false
-        slot.mapper.onMotion(event)
+        if (forwarding) slot.mapper.onMotion(event)
        return true
    }

@@ -221,24 +242,26 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett

        /** One axis update ([Gamepad].AXIS_*: stick i16 +y=up / trigger 0..255). On-change only. */
        fun axis(id: Int, value: Int) {
-            if (slot != null) NativeBridge.nativeSendGamepadAxis(handle, id, value, index)
+            if (slot != null && forwarding) NativeBridge.nativeSendGamepadAxis(handle, id, value, index)
        }

        /** One raw HID report, forwarded verbatim for the host's as-is virtual pad. */
        fun hidReport(buf: java.nio.ByteBuffer, len: Int) {
-            if (slot != null) NativeBridge.nativeSendPadHidReport(handle, index, buf, len)
+            if (slot != null && forwarding) NativeBridge.nativeSendPadHidReport(handle, index, buf, len)
        }

        /** One touchpad contact on the rich plane: [finger] 0/1, x/y normalized 0..65535 in
         *  SCREEN convention (+y down); `active = false` lifts the finger. On-change only. */
        fun touch(finger: Int, active: Boolean, x: Int, y: Int) {
-            if (slot != null) NativeBridge.nativeSendPadTouch(handle, index, finger, active, x, y)
+            if (slot != null && forwarding) {
+                NativeBridge.nativeSendPadTouch(handle, index, finger, active, x, y)
+            }
        }

        /** One motion sample on the rich plane (gyro pitch/yaw/roll + accel, raw device i16
         *  units — the host passes them straight into the virtual pad's report). Per report. */
        fun motion(gyro: IntArray, accel: IntArray) {
-            if (slot != null) {
+            if (slot != null && forwarding) {
                NativeBridge.nativeSendPadMotion(
                    handle, index,
                    gyro[0], gyro[1], gyro[2],
@@ -260,7 +283,7 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        // Synthetic ids live below any real InputDevice id (those are positive), so they can't
        // collide and InputDevice.getDevice(id) resolves them to null for the feedback path.
        val syntheticId = EXTERNAL_ID_BASE - index
-        NativeBridge.nativeSendGamepadArrival(handle, pref, index)
+        if (forwarding) NativeBridge.nativeSendGamepadArrival(handle, pref, index)
        slots[syntheticId] = Slot(index, Gamepad.AxisMapper(handle, index))
        return ExternalPad(syntheticId, index)
    }
@@ -317,7 +340,7 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        // Automatic resolves the pad's type from its VID/PID; an explicit setting forces every pad
        // to that type (a single global choice — matches the handshake's session-default pref).
        val pref = if (setting == Gamepad.PREF_AUTO) Gamepad.prefFor(dev) else setting
-        NativeBridge.nativeSendGamepadArrival(handle, pref, index)
+        if (forwarding) NativeBridge.nativeSendGamepadArrival(handle, pref, index)
        val slot = Slot(index, Gamepad.AxisMapper(handle, index))
        slots[dev.id] = slot
        return slot
@@ -330,7 +353,7 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
    private fun closeSlot(deviceId: Int) {
        val slot = slots.remove(deviceId) ?: return
        releaseHeld(slot)
-        NativeBridge.nativeSendGamepadRemove(handle, slot.index)
+        if (forwarding) NativeBridge.nativeSendGamepadRemove(handle, slot.index)
        // If this pad was mid-exit-chord, its removal may have left no pad holding it — drop the timer.
        if (slots.values.none { it.held and EXIT_CHORD == EXIT_CHORD }) disarmExit()
        // Release this controller's feedback bindings (close its lights session / cancel rumble).
@@ -342,11 +365,11 @@ class GamepadRouter(context: Context, private val handle: Long, private val sett
        var bits = slot.held
        while (bits != 0) {
            val bit = bits and -bits // lowest set bit
-            NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
+            if (forwarding) NativeBridge.nativeSendGamepadButton(handle, bit, false, slot.index)
            bits = bits and bit.inv()
        }
        slot.held = 0
-        slot.mapper.reset() // zero sticks/triggers + release the HAT dpad
+        if (forwarding) slot.mapper.reset() // zero sticks/triggers + release the HAT dpad
    }

    /** Lowest wire index 0..[MAX_PADS) not held by a slot, or null when full — stable lowest-free keeps indices from shuffling on hot-plug. */
@@ -392,7 +392,7 @@ pub(super) fn run_async(
        // even when the choreographer clock is absent.
        if let Some(p) = presenter.as_mut() {
            let clock = vsync.as_ref().map(|v| v.shared().as_ref());
-            if p.pump(&codec, clock, &tracker, &stats, now_monotonic_ns()) {
+            if p.pump(&codec, clock, &tracker, &meter, &stats, now_monotonic_ns()) {
                rendered += 1;
            }
            // The 1 Hz window flush doubles as the phase-lock report tick. v3 sensor: the
@@ -822,8 +822,21 @@ fn feed_ready(
            }
        }
        let Some(dst) = codec.input_buffer(idx) else {
-            log::warn!("decode: input_buffer({idx}) returned None — dropping AU");
-            continue;
+            // Nothing was written and nothing was queued, so BOTH stay ours. Dropping the slot
+            // here leaked one of the codec's input buffers per occurrence — we forget it and the
+            // codec never frees what it never received, so the pipeline quietly runs out of input
+            // slots, `pending_aus` overflows, and the resulting drop storm reads as a decode
+            // fault. Dropping the AU on top of that punched a hole in the reference chain with no
+            // keyframe request behind it, unlike every sibling path here.
+            //
+            // `break`, not `continue`: a codec that cannot hand out an input buffer it just
+            // advertised is in no state to be fed the rest of the parked queue this pass, and
+            // retrying the same index against every parked AU would burn the whole backlog. The
+            // loop re-runs within the housekeeping wake (≤ 5 ms) if it was transient.
+            log::warn!("decode: input_buffer({idx}) returned None — retrying next pass");
+            free_inputs.push_front(idx);
+            pending_aus.push_front(frame);
+            break;
        };
        let au = &frame.data;
        if au.len() > dst.len() {
@@ -115,9 +115,14 @@ pub(crate) struct DecodeOptions {
    /// The smoothness buffer depth (`smooth_buffer` setting): 0 = automatic (2), else 1..=3.
    /// Only meaningful with `present_priority` = smooth.
    pub smooth_buffer: i32,
-    /// The display mode's own refresh rate (Kotlin's `display.refreshRate` at stream start;
-    /// 0 = unknown) — the latch grid the presenter subdivides onto when the app's choreographer
-    /// stream is down-rated below the panel (see `vsync.rs`).
+    /// SEED for the panel's refresh period — the latch grid the presenter subdivides onto when
+    /// the app's choreographer stream is down-rated below the panel (see `vsync.rs`). Kotlin
+    /// resolves it from the display mode TABLE (`MainActivity.streamPanelFps`), not
+    /// `display.refreshRate`, which reports a per-uid override rather than the panel. 0 = unknown.
+    ///
+    /// ⚠ Only a seed: `preferredDisplayModeId` is a REQUEST the system may refuse, so the mode
+    /// named here is not necessarily the one the panel ends up in. The measured timeline spacing
+    /// corrects it in both directions ([`punktfunk_core::phase::PanelGrid`]).
    pub panel_hz: i32,
 }

@@ -4,10 +4,12 @@
 //!  * a **newest-wins slot** (or a small smoothing FIFO, by user intent) between decode and
 //!    release, so a burst coalesces in the app — as an explicit, counted drop — instead of
 //!    queueing behind the display;
-//!  * a **glass budget of exactly one**: at most one undisplayed release in flight to
-//!    SurfaceFlinger, reopened on the clock-predicted latch (with a 100 ms stale force-open as
-//!    the liveness backstop, mirroring Apple's `PresentGate.staleAfter`). The BufferQueue can
-//!    hold at most the frame being scanned out plus one — a standing queue is unconstructible;
+//!  * a **glass budget of one**: at most one undisplayed release in flight to SurfaceFlinger,
+//!    reopened on the clock-predicted latch (with a 100 ms stale force-open as the liveness
+//!    backstop, mirroring Apple's `PresentGate.staleAfter`), and bounded underneath by what
+//!    `OnFrameRendered` actually confirmed reached glass ([`UNDISPLAYED_CAP`]) — because the
+//!    prediction is only as good as the panel grid behind it, and 0.23.0 shipped a grid that
+//!    could be wrong in one direction forever;
 //!  * a **timed release**: `AMediaCodec_releaseOutputBufferAtTime` targeting the platform's own
 //!    frame timeline (API 33+, via [`super::vsync`]), so the latch phase is deterministic instead
 //!    of inheriting network + decode jitter. On the 31/32 fallback the release is ASAP —
@@ -20,6 +22,7 @@

 use ndk::media::media_codec::MediaCodec;
 use std::collections::VecDeque;
+use std::sync::atomic::{AtomicBool, AtomicI32, Ordering};
 use std::sync::Mutex;
 use std::time::Instant;

@@ -36,9 +39,9 @@ use super::vsync::VsyncShared;
 ///
 /// 2.5 ms: SF's latch runs ~1-2 ms before present on modern devices (its `sfOffset`), and the
 /// release itself is a binder call well under a ms. 4 ms measured latch p50 8-10; each ms cut
-/// here is a ms off every frame's display stage. If a device misses at this margin the `paced`
-/// counter shows it (a miss presents one vsync later, coalescing the next frame) — that is the
-/// signal to widen, not stutter.
+/// here is a ms off every frame's display stage. A device that misses at the live margin shows it
+/// as a measured latch beyond one panel period (see the adaptation in
+/// [`Presenter::flush_log`]) — that, not a drop counter, is the signal to widen.
 const LATCH_MARGIN_NS: i64 = 2_500_000;

 /// `debug.punktfunk.latch_margin_us` (0..=8000 µs): PIN the submit margin for a sweep —
@@ -71,6 +74,26 @@ fn latch_margin_ns() -> Option<i64> {
 /// `forced` — reads 0 on healthy systems (Apple's `PresentGate.staleAfter`, same value).
 const STALE_REOPEN_NS: i64 = 100_000_000;

+/// Releases still unconfirmed by `OnFrameRendered` at which the presenter stops handing
+/// SurfaceFlinger more work.
+///
+/// The reopen above is a PREDICTION off the learned panel grid. A grid finer than the panel
+/// (0.23.0 could pin one permanently — see [`punktfunk_core::phase::PanelGrid`]) reopens the
+/// budget before the display has consumed anything, and the presenter then releases faster than
+/// the panel scans: the BufferQueue fills, MediaCodec runs out of output buffers, the decoder
+/// stalls, and the no-output backstop starts begging for keyframes. The render callback is the
+/// ground truth about what actually reached glass, so it bounds the prediction.
+///
+/// Six, not one: the platform is explicitly allowed to deliver these callbacks BATCHED, and this
+/// module's own `RENDERED_CAP` note records them trailing a release by a vsync or two — so a
+/// healthy device sits at 1-3 outstanding and a tight cap would throttle it for nothing (a held
+/// frame in the newest-wins slot is a DROPPED frame the moment a fresher one decodes). This is
+/// not a pacing knob; it is the "something is structurally wrong" rail, and a presenter genuinely
+/// out-running its display climbs past any fixed cap within a second. If a device's BufferQueue
+/// is shallower than this the rail simply never engages and the no-output backstop handles it,
+/// exactly as before — best-effort, never worse than not having it.
+const UNDISPLAYED_CAP: i32 = 6;
+
 /// Fallback latch-prediction period while the vsync clock is unmeasured/absent: one 120 Hz frame.
 const FALLBACK_PERIOD_NS: i64 = 8_333_333;

@@ -121,6 +144,14 @@ struct InFlight {
 /// a HUD-off wireless A/B readable from logcat.
 pub(super) struct PresentMeter {
    inner: Mutex<PresentMeterInner>,
+    /// Frames released to SurfaceFlinger that `OnFrameRendered` has not yet confirmed reached
+    /// glass. The presenter's structural rail (see [`UNDISPLAYED_CAP`]) and the pf-present line's
+    /// queue-depth readout. Lock-free because the release side runs on the decode loop and the
+    /// confirm side on the codec's callback thread, once per frame each.
+    undisplayed: AtomicI32,
+    /// This device delivers render callbacks at all (API ≥ 33 and the platform accepted the
+    /// registration). Until one arrives, `undisplayed` is meaningless and the rail stays down.
+    confirms: AtomicBool,
 }

 struct PresentMeterInner {
@@ -147,11 +178,23 @@ impl PresentMeter {
                codec_us: Vec::with_capacity(256),
                e2e_us: Vec::with_capacity(256),
            }),
+            undisplayed: AtomicI32::new(0),
+            confirms: AtomicBool::new(false),
        }
    }

    /// One displayed frame's release→displayed latch, µs. Callback thread; poison-proof.
+    ///
+    /// Also the glass budget's CONFIRM: this frame left the BufferQueue, so one outstanding
+    /// release is settled. Clamped at zero — the legacy `arrival` path renders without going
+    /// through [`Presenter::pump`], so confirms can outnumber counted releases.
    pub(super) fn note_latch(&self, latch_us: Option<u64>) {
+        self.confirms.store(true, Ordering::Relaxed);
+        let _ = self
+            .undisplayed
+            .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| {
+                Some((v - 1).max(0))
+            });
        let mut g = self
            .inner
            .lock()
@@ -164,6 +207,26 @@ impl PresentMeter {
        }
    }

+    /// One frame handed to SurfaceFlinger, awaiting its confirm. Decode thread.
+    fn note_released(&self) {
+        self.undisplayed.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Releases still unconfirmed, and whether confirms happen on this device at all.
+    fn outstanding(&self) -> (i32, bool) {
+        (
+            self.undisplayed.load(Ordering::Relaxed),
+            self.confirms.load(Ordering::Relaxed),
+        )
+    }
+
+    /// Write off the outstanding releases: the platform stopped confirming (it is allowed to
+    /// drop callbacks under load) or SurfaceFlinger discarded the buffers without presenting
+    /// them. Never stall the stream on a ledger we cannot audit.
+    fn forgive_outstanding(&self) {
+        self.undisplayed.store(0, Ordering::Relaxed);
+    }
+
    /// One decoded frame's always-on measurements: the `decode`-stage split (feed =
    /// received→queued when a receipt stamp matched; codec = queued→decoded when the queued
    /// stamp did) and the capture→decoded end-to-end, µs. Decode thread; poison-proof.
@@ -239,6 +302,13 @@ pub(super) struct Presenter {
    no_budget: u64,
    forced: u64,
    dry: u64,
+    /// Pump passes that held a frame back because too many earlier releases were still
+    /// unconfirmed ([`UNDISPLAYED_CAP`]) — reads 0 on a healthy device, and a climbing value is
+    /// the signature of a presenter out-running its display.
+    queue_waits: u64,
+    /// When the unconfirmed-release rail first engaged, so it can be forgiven if the confirms
+    /// simply stopped coming. `None` while the rail is down.
+    backed_up_since: Option<i64>,
    pace_us: Vec<u64>,
    last_flush: Instant,
    /// The live submit margin. Starts at 0 (P2e on-glass: SurfaceFlinger latched every
@@ -280,6 +350,8 @@ impl Presenter {
            no_budget: 0,
            forced: 0,
            dry: 0,
+            queue_waits: 0,
+            backed_up_since: None,
            pace_us: Vec::with_capacity(256),
            last_flush: Instant::now(),
            margin_ns,
@@ -334,6 +406,7 @@ impl Presenter {
        codec: &MediaCodec,
        clock: Option<&VsyncShared>,
        tracker: &DisplayTracker,
+        meter: &PresentMeter,
        stats: &crate::stats::VideoStats,
        now_mono_ns: i64,
    ) -> bool {
@@ -346,6 +419,10 @@ impl Presenter {
                self.inflight = None;
            }
        }
+        // The measured rail beneath that prediction (see `UNDISPLAYED_CAP`). Evaluated on every
+        // pass — frame waiting or not — so its forgiveness timer measures real elapsed time
+        // rather than how often a frame happened to be ready.
+        let backlogged = self.unconfirmed_backlog(meter, now_mono_ns);
        // Pick the frame this pump may release.
        let frame = if self.fifo_capacity == 0 {
            self.frames.pop_back() // submit() kept it a single slot; back == the newest
@@ -373,9 +450,12 @@ impl Presenter {
            self.frames.pop_front()
        };
        let Some(frame) = frame else { return false };
-        if self.inflight.is_some() {
+        if self.inflight.is_some() || backlogged {
            // Budget closed — park it back; a fresher submit replaces it (newest-wins), the next
            // vsync tick / loop pass retries the pairing.
+            if backlogged {
+                self.queue_waits += 1;
+            }
            self.no_budget += 1;
            match self.fifo_capacity {
                0 => self.frames.push_back(frame),
@@ -412,6 +492,7 @@ impl Presenter {
            released_at_ns: now_mono_ns,
        });
        self.released += 1;
+        meter.note_released();
        let release_real_ns = now_realtime_ns();
        let pace_us = ((release_real_ns - frame.decoded_ns).max(0) / 1000) as u64;
        if self.pace_us.len() < 4096 {
@@ -422,6 +503,33 @@ impl Presenter {
        true
    }

+    /// Whether SurfaceFlinger is sitting on too many unconfirmed releases to be handed another.
+    ///
+    /// The predicted reopen is only as good as the panel grid behind it; this is the measured
+    /// rail underneath it (see [`UNDISPLAYED_CAP`]). It self-clears two ways — the confirms catch
+    /// up, or [`STALE_REOPEN_NS`] passes with the backlog stuck, which means the ledger itself is
+    /// unreliable (callbacks dropped under load, or SF discarded the buffers) and is written off
+    /// rather than allowed to wedge the stream.
+    fn unconfirmed_backlog(&mut self, meter: &PresentMeter, now_ns: i64) -> bool {
+        let (outstanding, confirms_live) = meter.outstanding();
+        if !confirms_live || outstanding < UNDISPLAYED_CAP {
+            self.backed_up_since = None;
+            return false;
+        }
+        match self.backed_up_since {
+            Some(t) if now_ns - t > STALE_REOPEN_NS => {
+                meter.forgive_outstanding();
+                self.backed_up_since = None;
+                self.forced += 1;
+                false
+            }
+            _ => {
+                self.backed_up_since.get_or_insert(now_ns);
+                true
+            }
+        }
+    }
+
    /// Release every held buffer unrendered — the teardown path, BEFORE `codec.stop()`.
    pub(super) fn release_all(&mut self, codec: &MediaCodec) {
        while let Some(f) = self.frames.pop_front() {
@@ -434,7 +542,9 @@ impl Presenter {
    /// `pf-present` line, so a HUD-off on-device A/B is readable wirelessly:
    /// `released` (to glass) / `displays` (OnFrameRendered confirms) / `paced` (policy drops) /
    /// `noBudget` (waits on the closed budget) / `forced` (stale force-opens — 0 when healthy) /
-    /// `qDry` (FIFO underflows) / `pace` (decoded→release) / `latch` (release→displayed) /
+    /// `qDry` (FIFO underflows) / `qWait` (pumps held back by unconfirmed releases — 0 when
+    /// healthy) / `unconfirmed` (releases OnFrameRendered hasn't settled) /
+    /// `pace` (decoded→release) / `latch` (release→displayed) /
    /// `feed`+`codec` (the decode stage split: received→queued hand-off/slot wait + the
    /// codec-pure queued→decoded time) / `e2e` (capture→decoded, skew-corrected — the wireless
    /// A/B headline) / `vsync` (the measured panel period).
@@ -462,14 +572,15 @@ impl Presenter {
        let circ = clock.and_then(|c| {
            punktfunk_core::phase::circular_latch(&latch, c.panel_period_ns().max(c.period_ns()))
        });
+        let latch_samples = latch.len();
        let (latch_p50, latch_max) = p50_max_ms(latch);
        let period_ms = clock.map(|c| c.period_ns() as f64 / 1e6).unwrap_or(0.0);
-        let panel_ms = clock
-            .map(|c| c.panel_period_ns() as f64 / 1e6)
-            .unwrap_or(0.0);
+        let panel_ns = clock.map(|c| c.panel_period_ns()).unwrap_or(0);
+        let (outstanding, _) = meter.outstanding();
        log::info!(
            target: "pf.present",
            "released={} displays={} paced={} noBudget={} forced={} qDry={} \
+             qWait={} unconfirmed={} \
             paceMs p50={:.2} max={:.2} latchMs p50={:.2} max={:.2} \
             feedMs p50={:.2} max={:.2} codecMs p50={:.2} max={:.2} \
             e2eMs p50={:.2} max={:.2} circ={:.2}ms coh={} \
@@ -480,6 +591,8 @@ impl Presenter {
            self.no_budget,
            self.forced,
            self.dry,
+            self.queue_waits,
+            outstanding,
            pace_p50,
            pace_max,
            latch_p50,
@@ -493,25 +606,48 @@ impl Presenter {
            circ.map(|(m, _)| m as f64 / 1e6).unwrap_or(0.0),
            circ.map(|(_, c)| c).unwrap_or(0),
            period_ms,
-            panel_ms,
+            panel_ns as f64 / 1e6,
        );
        self.released = 0;
-        // Margin adaptation: repeated latch misses in one window (a miss presents a vsync
-        // late and coalesces the next frame into `paced`) mean this device's SF does need
-        // lead — widen toward the pre-sweep ceiling. One-way by design: a margin that once
-        // proved necessary is never re-gambled mid-stream (the next stream restarts at 0).
-        if !self.margin_pinned && self.paced_drops > 2 && self.margin_ns < LATCH_MARGIN_NS {
+        // Margin adaptation, off the MEASURED latch. A release targets the first grid point past
+        // `now + margin`, so a frame that makes its vsync is on glass within one panel period of
+        // that margin; beyond it, SurfaceFlinger wanted more lead and the frame waited out an
+        // extra refresh. Widen toward the pre-sweep ceiling. One-way by design: a margin that
+        // once proved necessary is never re-gambled mid-stream (the next stream restarts at 0).
+        //
+        // ⚠ NOT `paced_drops`, which 0.23.0 used: those are the newest-wins store's own policy
+        // evictions — a second frame decoding while one is held — which happen whenever the
+        // stream out-runs the panel and say nothing at all about SF's latch lead. Driving the
+        // margin from them widened it to the ceiling on healthy devices, re-imposing the 2.5 ms
+        // of pure display latency the P2e sweep had just measured away.
+        let latch_p50_ns = (latch_p50 * 1e6) as i64;
+        if !self.margin_pinned
+            && self.margin_ns < LATCH_MARGIN_NS
+            && panel_ns > 0
+            && latch_samples >= 8
+            && latch_p50_ns > panel_ns + self.margin_ns
+        {
            self.margin_ns = (self.margin_ns + 500_000).min(LATCH_MARGIN_NS);
            log::warn!(
-                "presenter: {} latch misses in 1s — margin widened to {}us",
-                self.paced_drops,
+                "presenter: latch p50 {:.2}ms over the {:.2}ms panel period — margin widened to {}us",
+                latch_p50,
+                panel_ns as f64 / 1e6,
                self.margin_ns / 1_000
            );
        }
+        if self.queue_waits > 0 {
+            log::warn!(
+                "presenter: {} pump(s) held back — {} release(s) still unconfirmed by \
+                 OnFrameRendered (the display is not keeping up with the release rate)",
+                self.queue_waits,
+                outstanding
+            );
+        }
        self.paced_drops = 0;
        self.no_budget = 0;
        self.forced = 0;
        self.dry = 0;
+        self.queue_waits = 0;
        circ
    }
 }
@@ -58,8 +58,10 @@ pub(super) struct VsyncShared {
    /// video to THIS rate would cap the stream — hence `panel_period_ns` + the subdivision in
    /// [`Self::next_target`].
    period_ns: AtomicI64,
-    /// The panel's own refresh period (from the display mode Kotlin resolved at stream start;
-    /// 0 = unknown). The grid SurfaceFlinger actually latches on.
+    /// The panel's own refresh period — the grid SurfaceFlinger actually latches on (0 = unknown).
+    /// Seeded from the display mode Kotlin resolved at stream start and then corrected by
+    /// measurement; the learner itself is [`punktfunk_core::phase::PanelGrid`], owned by the
+    /// choreographer thread (see [`CallbackCtx::panel`]) and published here for the decode loop.
    panel_period_ns: AtomicI64,
    /// Callback count, for the one-shot cadence diagnostic log.
    ticks: std::sync::atomic::AtomicU32,
@@ -231,6 +233,11 @@ struct CallbackCtx {
    choreographer: *mut c_void,
    shared: Arc<VsyncShared>,
    on_tick: Box<dyn Fn() + Send>,
+    /// The panel-period learner. `Cell` rather than an atomic because it is touched from exactly
+    /// one thread — callbacks only ever fire inside this thread's looper poll (see the struct
+    /// doc) — and its streak state is nobody else's business; only the settled period is
+    /// published, to `shared.panel_period_ns`.
+    panel: std::cell::Cell<punktfunk_core::phase::PanelGrid>,
 }

 impl CallbackCtx {
@@ -240,22 +247,25 @@ impl CallbackCtx {
            .shared
            .last_vsync_ns
            .swap(frame_time_ns, Ordering::Relaxed);
-        // Panel-grid learner: timeline spacing is SurfaceFlinger's own grid, and the finest
-        // spacing ever observed is the panel's true period — trustworthy where the configured
-        // value is not (under a per-uid frame-rate override, `Display.getRefreshRate` REPORTS
-        // THE OVERRIDE, observed on-glass: a 120 Hz panel read back as 60 while early timelines
-        // ran at 8.28 ms). Corrects DOWNWARD only: subdividing onto a finer real grid is always
-        // valid, widening on a later down-rated window never is.
+        // Panel-grid learner: timeline spacing is SurfaceFlinger's own grid, and therefore the
+        // only honest witness to what the panel is doing — the configured mode is not (under a
+        // per-uid frame-rate override `Display.getRefreshRate` REPORTS THE OVERRIDE, observed
+        // on-glass: a 120 Hz panel read back as 60 while its timelines ran at 8.28 ms), and
+        // neither is the mode Kotlin *requested* (`preferredDisplayModeId` is a hint the system
+        // may refuse). Both directions matter and the asymmetry lives in `PanelGrid`.
        if timelines.len() >= 2 {
            let spacing = timelines[1].expected_present_ns - timelines[0].expected_present_ns;
-            if (2_000_000..=42_000_000).contains(&spacing) {
-                let cur = self.shared.panel_period_ns.load(Ordering::Relaxed);
-                if cur == 0 || spacing < cur - 200_000 {
-                    self.shared
-                        .panel_period_ns
-                        .store(spacing, Ordering::Relaxed);
-                }
+            let mut grid = self.panel.get();
+            if grid.observe(spacing) {
+                self.shared
+                    .panel_period_ns
+                    .store(grid.period_ns(), Ordering::Relaxed);
+                log::info!(
+                    "vsync: panel grid now {:.2}ms",
+                    grid.period_ns() as f64 / 1e6
+                );
            }
+            self.panel.set(grid);
        }
        // One-shot cadence diagnostic (3rd tick, once deltas exist): the callback cadence vs the
        // panel period is exactly the down-rating question, and this line answers it on-glass.
@@ -372,8 +382,9 @@ pub(super) struct VsyncClock {
 impl VsyncClock {
    /// Spawn the choreographer thread. `on_tick` fires once per vsync ON THAT THREAD — it must
    /// only do something cheap and `Send` (the decode loop passes an event-channel send).
-    /// `panel_hz` is the display mode's own refresh rate (0 = unknown), the latch grid that
-    /// [`VsyncShared::next_target`] subdivides onto. `None` when the platform surface is missing
+    /// `panel_hz` SEEDS the panel-grid learner (0 = unknown) — the latch grid that
+    /// [`VsyncShared::next_target`] subdivides onto. A seed, not a fact: it names the display
+    /// mode Kotlin *requested*, and the observed timeline spacing is what settles it. `None` when the platform surface is missing
    /// (very old device) — the presenter then runs clock-less (ASAP targets, predicted-latch
    /// budget).
    pub(super) fn start(panel_hz: i32, on_tick: Box<dyn Fn() + Send>) -> Option<VsyncClock> {
@@ -383,11 +394,9 @@ impl VsyncClock {
            stop: AtomicBool::new(false),
            last_vsync_ns: AtomicI64::new(0),
            period_ns: AtomicI64::new(0),
-            panel_period_ns: AtomicI64::new(if panel_hz > 0 {
-                1_000_000_000 / panel_hz as i64
-            } else {
-                0
-            }),
+            panel_period_ns: AtomicI64::new(
+                punktfunk_core::phase::PanelGrid::seeded(panel_hz).period_ns(),
+            ),
            ticks: std::sync::atomic::AtomicU32::new(0),
            timelines: Mutex::new(Vec::new()),
        });
@@ -408,6 +417,7 @@ impl VsyncClock {
                    choreographer,
                    shared: thread_shared,
                    on_tick,
+                    panel: std::cell::Cell::new(punktfunk_core::phase::PanelGrid::seeded(panel_hz)),
                };
                ctx.repost();
                // The bounded poll doubles as the stop check: no cross-thread wake needed, worst
@@ -672,7 +672,11 @@ final class SessionModel: ObservableObject {
        // back to the pad it's addressed to (rumble always; lightbar/player-LEDs/adaptive-triggers
        // when a pad's virtual device is a DualSense). Same trust gate as audio — nothing is
        // forwarded during the trust prompt.
-        let capture = GamepadCapture(connection: conn, manager: .shared)
+        // `gamepadForwarding` off means the host gets this device's pads from somewhere else
+        // (USB passthrough, or a pad plugged into the host) — capture still runs, and still
+        // watches for the escape chord, but puts nothing on the wire.
+        let capture = GamepadCapture(
+            connection: conn, manager: .shared, forwarding: settings.gamepadForwarding)
        // The cross-client escape chord (hold L1+R1+Start+Select 1.5 s) — on tvOS the only
        // controller way out of a stream (B/Menu is swallowed during sessions; see ContentView).
        capture.onDisconnectRequest = { [weak self] in self?.disconnect() }
@@ -26,6 +26,7 @@ struct GamepadSettingsView: View {
    @AppStorage(DefaultsKey.streamHz) private var hz = 60
    @AppStorage(DefaultsKey.compositor) private var compositor = 0
    @AppStorage(DefaultsKey.gamepadType) private var gamepadType = 0
+    @AppStorage(DefaultsKey.gamepadForwarding) private var gamepadForwarding = true
    @AppStorage(DefaultsKey.bitrateKbps) private var bitrateKbps = 0
    @AppStorage(DefaultsKey.audioChannels) private var audioChannels = 2
    @AppStorage(DefaultsKey.hdrEnabled) private var hdrEnabled = true
@@ -323,8 +324,15 @@ struct GamepadSettingsView: View {
                    + "speaker setups feeding the game back to the host.",
                value: $echoCancel),

+            toggleRow(
+                id: "padForward", header: "Controller", icon: "gamecontroller",
+                label: "Forward controllers",
+                detail: "Send this device's controllers to the host. Turn it off when your "
+                    + "controller already reaches the host another way — USB passthrough such "
+                    + "as VirtualHere — so games don't see two of them.",
+                value: $gamepadForwarding),
            choiceRow(
-                id: "pad", header: "Controller", icon: "gamecontroller", label: "Use controller",
+                id: "pad", icon: "gamecontroller", label: "Use controller",
                detail: "Which pad is forwarded to the host, as player 1.",
                options: controllers, current: gamepads.preferredID
            ) { gamepads.preferredID = $0 },
@@ -122,6 +122,10 @@ enum SettingsFields {
        .init(name: "gamepad", key: DefaultsKey.gamepadType,
              overlay: \.gamepadType, effective: \.gamepadType)
    }
+    static var gamepadForwarding: SettingsField<Bool> {
+        .init(name: "gamepad_forwarding", key: DefaultsKey.gamepadForwarding,
+              overlay: \.gamepadForwarding, effective: \.gamepadForwarding)
+    }
    static var statsVerbosity: SettingsField<String> {
        .init(name: "stats_verbosity", key: DefaultsKey.statsVerbosity,
              overlay: \.statsVerbosity, effective: \.statsVerbosity)
@@ -181,6 +185,7 @@ extension SettingsView {
        base.micEnabled = micEnabled
        base.echoCancel = echoCancel
        base.gamepadType = gamepadType
+        base.gamepadForwarding = gamepadForwarding
        base.statsVerbosity = statsVerbosityRaw
        base.fullscreenWhileStreaming = fullscreenWhileStreaming
        base.presentPriority = presentPriority
@@ -641,6 +641,15 @@ extension SettingsView {

    @ViewBuilder var controllersSection: some View {
        Section {
+            // The master switch, above everything it governs. Profileable, so it renders in
+            // both scopes: a "Work" profile can decline to forward what "Game" forwards.
+            described("Sends controllers connected to this device to the host. Turn it off when "
+                + "your controller already reaches the host another way — USB passthrough such "
+                + "as VirtualHere, or a pad plugged into the host itself — so games don't see "
+                + "two of them.",
+                field: "gamepad_forwarding") {
+                Toggle("Forward controllers", isOn: scoped(SettingsFields.gamepadForwarding))
+            }
            // Which physical pad this device forwards, and what its own haptics do, are facts
            // about THIS device (tier G) — only the virtual pad the host creates is profileable.
            if !inProfileScope {
@@ -659,6 +668,7 @@ extension SettingsView {
                            Text(option.label).tag(option.tag)
                        }
                    }
+                    .disabled(!effective.gamepadForwarding)
                }
            }
            described("The virtual pad created on the host. Automatic matches your controller "
@@ -669,6 +679,7 @@ extension SettingsView {
                        Text(option.label).tag(option.tag)
                    }
                }
+                .disabled(!effective.gamepadForwarding)
            }
            #if os(iOS)
            // iPhone only in practice: hidden where the device itself can't play haptics (iPad).
@@ -49,6 +49,7 @@ struct SettingsView: View {
    @AppStorage(DefaultsKey.renderScale) var renderScale = 1.0
    @AppStorage(DefaultsKey.compositor) var compositor = 0
    @AppStorage(DefaultsKey.gamepadType) var gamepadType = 0
+    @AppStorage(DefaultsKey.gamepadForwarding) var gamepadForwarding = true
    @AppStorage(DefaultsKey.bitrateKbps) var bitrateKbps = 0
    @AppStorage(DefaultsKey.presentPriority) var presentPriority =
        SettingsOptions.presentPriorityDefault
@@ -98,9 +98,27 @@ public final class GamepadCapture {
    /// gameplay can't end it (see ContentView's tvOS session branch).
    public var onDisconnectRequest: (() -> Void)?

-    public init(connection: PunktfunkConnection, manager: GamepadManager) {
+    /// Forward this device's controllers to the host at all (`Settings.gamepadForwarding`,
+    /// default true). Off is for a couch whose controller reaches the host another way — USB
+    /// passthrough such as VirtualHere, or a pad plugged into the host itself — where
+    /// forwarding as well would give the host two pads for one pair of hands.
+    ///
+    /// Off still opens slots and tracks button state; it just sends nothing (see `wire`). That
+    /// is deliberate, not laziness: the escape chord is read off the same slots, and on tvOS it
+    /// is the ONLY controller way out of a stream — a session that silently lost its exit
+    /// because a forwarding preference was off would be a worse bug than the one this fixes.
+    /// Unlike pf-client-core's slots, GameController claims nothing exclusive, so holding one
+    /// open costs the host nothing and blocks no passthrough tool.
+    public let forwarding: Bool
+
+    /// The connection, or nil while forwarding is off — every wire send goes through this, so
+    /// "don't forward" is one fact in one place rather than a condition at twelve call sites.
+    private var wire: PunktfunkConnection? { forwarding ? connection : nil }
+
+    public init(connection: PunktfunkConnection, manager: GamepadManager, forwarding: Bool = true) {
        self.connection = connection
        self.manager = manager
+        self.forwarding = forwarding
    }

    public func start() {
@@ -205,8 +223,8 @@ public final class GamepadCapture {
        // core re-sends it a few times against datagram loss; an older host ignores it and uses
        // the session-default kind. Then wake the host pad (pads are created lazily from the first
        // event; a DualSense's UHID handshake + initial lightbar write only start then).
-        connection.send(.gamepadArrival(pref: slot.pref.rawValue, pad: slot.pad))
-        connection.send(.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: slot.pad))
+        wire?.send(.gamepadArrival(pref: slot.pref.rawValue, pad: slot.pad))
+        wire?.send(.gamepadAxis(GamepadWire.axisLSX, value: 0, pad: slot.pad))
        sync(slot, ext)

        if let tp = Self.touchpad(ext) {
@@ -233,7 +251,7 @@ public final class GamepadCapture {
        flush(slot)
        // Sent after the flush so the core stamps it with a seq past the zeroing snapshots; the host
        // seq-gates it, so a reordered snapshot can't resurrect the removed pad.
-        connection.send(.gamepadRemove(pad: slot.pad))
+        wire?.send(.gamepadRemove(pad: slot.pad))
        let c = slot.controller
        if let ext = c.extendedGamepad {
            ext.valueChangedHandler = nil
@@ -275,7 +293,7 @@ public final class GamepadCapture {
        let changed = newButtons ^ slot.buttons
        if changed != 0 {
            for bit in GamepadWire.allButtons where changed & bit != 0 {
-                connection.send(.gamepadButton(bit, down: newButtons & bit != 0, pad: slot.pad))
+                wire?.send(.gamepadButton(bit, down: newButtons & bit != 0, pad: slot.pad))
            }
            slot.buttons = newButtons
        }
@@ -288,7 +306,7 @@ public final class GamepadCapture {
            Int32(g.rightTrigger.value * 255),
        ]
        for (i, v) in newAxes.enumerated() where v != slot.axes[i] {
-            connection.send(.gamepadAxis(UInt32(i), value: v, pad: slot.pad))
+            wire?.send(.gamepadAxis(UInt32(i), value: v, pad: slot.pad))
            slot.axes[i] = v
        }
        updateEscapeChord()
@@ -302,7 +320,7 @@ public final class GamepadCapture {
        let bit = GamepadWire.guide
        let now = down ? (slot.buttons | bit) : (slot.buttons & ~bit)
        guard now != slot.buttons else { return }
-        connection.send(.gamepadButton(bit, down: down, pad: slot.pad))
+        wire?.send(.gamepadButton(bit, down: down, pad: slot.pad))
        slot.buttons = now
    }

@@ -365,13 +383,13 @@ public final class GamepadCapture {
        if lifted {
            if slot.fingerActive[finger] {
                slot.fingerActive[finger] = false
-                connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: false, x: 0, y: 0)
+                wire?.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: false, x: 0, y: 0)
            }
            return
        }
        slot.fingerActive[finger] = true
        let w = GamepadWire.touchpad(x: x, y: y)
-        connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: true, x: w.x, y: w.y)
+        wire?.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(finger), active: true, x: w.x, y: w.y)
    }

    private func forwardMotion(_ slot: Slot, _ m: GCMotion) {
@@ -394,7 +412,7 @@ public final class GamepadCapture {
        }
        let gs = GamepadWire.gyroLSBPerRadS
        let as_ = GamepadWire.accelLSBPerG
-        connection.sendMotion(
+        wire?.sendMotion(
            pad: UInt8(slot.pad),
            gyro: (
                GamepadWire.motionRaw(Float(m.rotationRate.x), scale: gs),
@@ -432,15 +450,15 @@ public final class GamepadCapture {
    /// GamepadRemove (that's `closeSlot`).
    private func flush(_ slot: Slot) {
        for bit in GamepadWire.allButtons where slot.buttons & bit != 0 {
-            connection.send(.gamepadButton(bit, down: false, pad: slot.pad))
+            wire?.send(.gamepadButton(bit, down: false, pad: slot.pad))
        }
        slot.buttons = 0
        for (i, v) in slot.axes.enumerated() where v != 0 {
-            connection.send(.gamepadAxis(UInt32(i), value: 0, pad: slot.pad))
+            wire?.send(.gamepadAxis(UInt32(i), value: 0, pad: slot.pad))
            slot.axes[i] = 0
        }
        for (f, active) in slot.fingerActive.enumerated() where active {
-            connection.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(f), active: false, x: 0, y: 0)
+            wire?.sendTouchpad(pad: UInt8(slot.pad), finger: UInt8(f), active: false, x: 0, y: 0)
            slot.fingerActive[f] = false
        }
    }
@@ -175,6 +175,46 @@ public final class StreamViewController: StreamViewControllerBase {
    /// renegotiates the host mode (1:1, no presenter resample). iOS only (iPhone naturally no-ops
    /// its fixed full-screen scene; tvOS drives display modes via AVDisplayManager instead).
    private var matchFollower: MatchWindowFollower?
+    // MARK: Escape-drop re-lock
+    //
+    // iPadOS releases the pointer lock BY ITSELF when the user presses Escape — the platform's
+    // built-in "let me out", mirroring the web Pointer Lock API's default unlock gesture. Nothing
+    // in our code does it: a bare Esc never touches `captured`, so it keeps forwarding to the host
+    // as the game key it is. But the lock going away flips the mouse onto the absolute UIKit path
+    // and un-hides the iPadOS cursor, so hitting Esc for an in-game menu silently costs the capture
+    // until the user clicks to win it back. Esc is a GAME key here, not a request to hand the
+    // pointer back to iPadOS, so an unwanted drop is re-requested below. The DELIBERATE releases
+    // (⌘⎋, ⌃⌥⇧Q, the Stream menu, backgrounding) all clear `captured` first, so `wantsPointerLock`
+    // is already false when their drop is observed and none of them are fought here.
+    /// Whether this capture ever actually held the lock. Only a lock we HELD is worth winning back
+    /// — never having been granted one means the scene doesn't qualify, not that Esc took it.
+    /// Cleared when capture ends, so each capture starts from a clean slate.
+    private var pointerLockWasEngaged = false
+    /// Attempts spent in the current re-lock burst, and when the burst began.
+    private var pointerRelockAttempt = 0
+    private var pointerRelockBurstStart: CFTimeInterval = 0
+    /// True from an unwanted drop until the lock is back (or the burst gives up). While pending,
+    /// the local cursor stays hidden and absolute pointer MOTION stays muted, so a re-lock that
+    /// lands a frame or two later is invisible instead of flashing the iPadOS cursor and
+    /// teleporting the host's to the pointer's absolute position.
+    private var pointerRelockPending = false
+    /// Forces `prefersPointerLocked` to report false for one resolve pass, so the escalated attempt
+    /// presents the system with a genuine false→true transition instead of re-asserting a value it
+    /// already holds. See `requestPointerRelock()`.
+    private var pointerLockForcedOff = false
+    /// A burst is 3 attempts, and a burst can't restart inside 2 s. A scene the system will never
+    /// lock (Stage Manager, Split View) therefore costs three cheap re-resolves and then falls back
+    /// to today's click-to-recapture, rather than retrying forever.
+    private static let pointerRelockAttemptLimit = 3
+    private static let pointerRelockBurstWindow: CFTimeInterval = 2
+    /// Gap between attempts in a burst — long enough for the system to answer the previous
+    /// re-resolve, short enough that the whole burst fits in ~0.6 s. Must exceed
+    /// `pointerLockForcedOffHold` so an escalated attempt is back to preferring the lock before the
+    /// next attempt evaluates.
+    private static let pointerRelockRetryDelay: TimeInterval = 0.2
+    /// How long an escalated attempt reports `prefersPointerLocked == false` before flipping back,
+    /// so the system observes a real transition instead of coalescing the flip away.
+    private static let pointerLockForcedOffHold: TimeInterval = 0.05
    #endif

    /// Reads whether the scene's pointer is actually locked right now; nil = state
@@ -260,7 +300,7 @@ public final class StreamViewController: StreamViewControllerBase {
        captured && pointerCaptureEnabled && UIDevice.current.userInterfaceIdiom == .pad
    }

-    public override var prefersPointerLocked: Bool { wantsPointerLock }
+    public override var prefersPointerLocked: Bool { wantsPointerLock && !pointerLockForcedOff }
    public override var prefersHomeIndicatorAutoHidden: Bool { true }

    // NOTE: we deliberately do NOT override `childViewControllerForPointerLock`. The default
@@ -383,6 +423,11 @@ public final class StreamViewController: StreamViewControllerBase {
        // is the exact mirror of the GCMouse handlers, which fire only while locked.
        streamView.onPointerMoveAbs = { [weak self] p in
            guard let self, self.inputCapture?.gcMouseForwarding == false else { return }
+            // A re-lock is in flight after an Esc-drop: the absolute path would teleport the host
+            // cursor to wherever the local pointer sits, undoing the relative aiming we're about to
+            // resume. Motion only — BUTTONS still forward (they carry no position, so a click during
+            // the couple of frames a re-lock takes must not be swallowed mid-firefight).
+            guard !self.pointerRelockPending else { return }
            self.inputCapture?.sendMouseAbs(
                x: p.x, y: p.y, surfaceWidth: p.w, surfaceHeight: p.h)
        }
@@ -693,6 +738,24 @@ public final class StreamViewController: StreamViewControllerBase {
    /// change and capture toggle. Main queue.
    private func syncPointerLock() {
        let locked = pointerLockEngaged() == true
+        // Wanted, previously HELD, and now gone is the Esc-drop signature. The "previously held"
+        // half matters: a lock that was never granted is a scene that doesn't qualify (Stage
+        // Manager, Split View), and burst-requesting there would hide the cursor for the burst's
+        // duration to win a lock that isn't coming. A first grant is already driven by the chain
+        // engage in setCaptured/viewDidAppear.
+        if locked {
+            pointerLockWasEngaged = true
+            pointerRelockPending = false
+            pointerRelockAttempt = 0
+        } else if wantsPointerLock, pointerLockWasEngaged {
+            requestPointerRelock()
+        } else {
+            // Capture is gone (or the lock was never ours) — settle, and let the next capture
+            // start from a clean "never held" slate.
+            if !wantsPointerLock { pointerLockWasEngaged = false }
+            pointerRelockPending = false
+            pointerRelockAttempt = 0
+        }
        let useGCMouse = captured && locked
        // Lock dropped (or capture ended) while the GCMouse path held a button down: once
        // gcMouseForwarding flips false its release handler is gated off, so flush any held
@@ -704,7 +767,83 @@ public final class StreamViewController: StreamViewControllerBase {
        pointerInteraction?.invalidate() // re-resolve the hidden/visible cursor for the state
        if iosInputDebug {
            iosInputLog.debug(
-                "pointer lock isLocked=\(locked, privacy: .public) captured=\(self.captured, privacy: .public)")
+                """
+                pointer lock isLocked=\(locked, privacy: .public) \
+                captured=\(self.captured, privacy: .public) \
+                relockPending=\(self.pointerRelockPending, privacy: .public) \
+                relockAttempt=\(self.pointerRelockAttempt, privacy: .public)
+                """)
+        }
+    }
+
+    /// Ask the system for the lock back after it dropped one we still want (see the Escape-drop
+    /// note on the state above). Bounded to a short burst; idempotent within it. Main queue.
+    private func requestPointerRelock() {
+        // Only a frontmost scene can hold the lock at all. Anywhere else the drop is the system
+        // saying we don't qualify, not the Esc key — re-asking would be noise, and the qualifying
+        // states (foreground, appearance, reparent) each re-resolve on their own already.
+        guard view.window?.windowScene?.activationState == .foregroundActive else {
+            pointerRelockPending = false
+            return
+        }
+        let now = CACurrentMediaTime()
+        // attempt == 0 is a fresh burst (first drop, or one the settle branch cleared); the window
+        // is the backstop for the pathological case where a grant is immediately revoked again and
+        // re-arms us. Even then this stays timer-driven at a few Hz — never a spin.
+        if pointerRelockAttempt == 0 || now - pointerRelockBurstStart > Self.pointerRelockBurstWindow {
+            pointerRelockBurstStart = now
+            pointerRelockAttempt = 0
+        }
+        guard pointerRelockAttempt < Self.pointerRelockAttemptLimit else {
+            // Out of budget: fall back to exactly today's behavior — the iPadOS cursor comes back
+            // and a click into the video re-captures. The caller invalidates the interaction, so
+            // the cursor can never stay hidden on a lock the system won't grant.
+            pointerRelockPending = false
+            return
+        }
+        pointerRelockAttempt += 1
+        pointerRelockPending = true
+        let escalate = pointerRelockAttempt > 1
+        // Deferred a turn so a ⌘⎋ whose GC keystroke lands after the system's unlock notification
+        // has already cleared `captured` — then the guard below drops this attempt instead of
+        // fighting the user's own release.
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.pointerRelockPending else { return }
+            guard self.wantsPointerLock, self.pointerLockEngaged() != true else {
+                // The grant landed, or the capture went away under us (⌘⎋ / ⌃⌥⇧Q / resign).
+                // Settle through the one decision point rather than returning with `pending` still
+                // set — that flag hides the cursor, so it must never outlive the burst.
+                self.syncPointerLock()
+                return
+            }
+            if escalate {
+                // Re-asserting a value the system already holds didn't take. Present a real
+                // false→true transition instead — the documented way to change your mind about the
+                // lock — and re-anchor the chain in case a reparent broke the downward walk to us.
+                // Held for a beat rather than cleared on the next turn: the system resolves the
+                // property asynchronously, and a same-turn flip back to true can be coalesced into
+                // no transition at all. We are already unlocked, so the false pass costs nothing.
+                self.pointerLockForcedOff = true
+                self.setNeedsUpdateOfPrefersPointerLocked()
+                self.updatePointerLockChain()
+                DispatchQueue.main.asyncAfter(deadline: .now() + Self.pointerLockForcedOffHold) {
+                    [weak self] in
+                    guard let self else { return }
+                    self.pointerLockForcedOff = false
+                    self.setNeedsUpdateOfPrefersPointerLocked()
+                }
+            } else {
+                self.setNeedsUpdateOfPrefersPointerLocked()
+            }
+            // A GRANT arrives as a didChange → syncPointerLock, which settles the burst and makes
+            // this retry a no-op. Routed back through syncPointerLock (not straight into another
+            // requestPointerRelock) so the give-up path re-resolves the cursor through the one
+            // place that does it.
+            DispatchQueue.main.asyncAfter(deadline: .now() + Self.pointerRelockRetryDelay) {
+                [weak self] in
+                guard let self, self.pointerRelockPending else { return }
+                self.syncPointerLock()
+            }
        }
    }
    #endif
@@ -724,7 +863,11 @@ extension StreamViewController: UIPointerInteractionDelegate {
        // host renders its own cursor from GCMouse deltas and a visible local one would just
        // diverge. When the lock isn't held the cursor stays VISIBLE so the user can aim; the
        // pointer is forwarded as an absolute position, both cursors tracking together.
-        captured && pointerLockEngaged() == true ? .hidden() : nil
+        // …except across an Esc-drop we're actively re-locking (`pointerRelockPending`): staying
+        // hidden for those couple of frames is what turns the fix into "Esc did nothing to my
+        // mouse" rather than a cursor that blinks in and out. The burst is bounded and clears
+        // itself on give-up, so the cursor can never stay hidden on a lock that isn't coming.
+        captured && (pointerLockEngaged() == true || pointerRelockPending) ? .hidden() : nil
    }
 }
 #endif
@@ -32,6 +32,12 @@ public enum DefaultsKey {
    public static let compositor = "punktfunk.compositor"
    public static let gamepadType = "punktfunk.gamepadType"
    public static let gamepadID = "punktfunk.gamepadID"
+    /// Forward this device's controllers to the host at all (default true). Off is for a
+    /// couch whose controller reaches the host another way — USB passthrough such as
+    /// VirtualHere, or a pad plugged into the host — where forwarding as well would give the
+    /// host two pads for one pair of hands. Read at connect: `SessionModel` then never starts
+    /// `GamepadCapture`, so no slot opens, no arrival is sent and no virtual pad is built.
+    public static let gamepadForwarding = "punktfunk.gamepadForwarding"
    public static let bitrateKbps = "punktfunk.bitrateKbps"
    /// Requested audio channel count: 2 (stereo), 6 (5.1) or 8 (7.1). The host clamps to what it
    /// can capture; the resolved count drives the in-core decode + AVAudioEngine layout.
@@ -34,6 +34,7 @@ public struct EffectiveSettings: Equatable, Sendable {
    public var mouseMode = "capture"
    public var invertScroll = false
    public var gamepadType = 0
+    public var gamepadForwarding = true
    /// A `StatsVerbosity` raw value; the enum lives in PunktfunkKit, which this module can't see.
    public var statsVerbosity = "normal"
    public var fullscreenWhileStreaming = true
@@ -93,6 +94,7 @@ public struct EffectiveSettings: Equatable, Sendable {
        mouseMode = str(DefaultsKey.mouseMode, mouseMode)
        invertScroll = bool(DefaultsKey.invertScroll, invertScroll)
        gamepadType = int(DefaultsKey.gamepadType, gamepadType)
+        gamepadForwarding = bool(DefaultsKey.gamepadForwarding, gamepadForwarding)
        statsVerbosity = Self.storedStatsVerbosity(defaults)
        fullscreenWhileStreaming = bool(
            DefaultsKey.fullscreenWhileStreaming, fullscreenWhileStreaming)
@@ -140,6 +142,7 @@ public struct EffectiveSettings: Equatable, Sendable {
        if let v = overlay.mouseMode { s.mouseMode = v }
        if let v = overlay.invertScroll { s.invertScroll = v }
        if let v = overlay.gamepadType { s.gamepadType = v }
+        if let v = overlay.gamepadForwarding { s.gamepadForwarding = v }
        if let v = overlay.statsVerbosity { s.statsVerbosity = v }
        if let v = overlay.fullscreenWhileStreaming { s.fullscreenWhileStreaming = v }
        if let v = overlay.enable444 { s.enable444 = v }
@@ -110,6 +110,7 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
    public var mouseMode: String?
    public var invertScroll: Bool?
    public var gamepadType: Int?
+    public var gamepadForwarding: Bool?
    /// A `StatsVerbosity` raw value ("off"/"compact"/"normal"/"detailed") — the enum lives in
    /// PunktfunkKit, which this module must not depend on.
    public var statsVerbosity: String?
@@ -151,6 +152,7 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
        case mouseMode = "mouse_mode"
        case invertScroll = "invert_scroll"
        case gamepadType = "gamepad"
+        case gamepadForwarding = "gamepad_forwarding"
        case statsVerbosity = "stats_verbosity"
        case fullscreenWhileStreaming = "fullscreen_on_stream"
        case enable444 = "enable_444"
@@ -184,6 +186,7 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
        mouseMode = str(.mouseMode)
        invertScroll = bool(.invertScroll)
        gamepadType = int(.gamepadType)
+        gamepadForwarding = bool(.gamepadForwarding)
        statsVerbosity = str(.statsVerbosity)
        fullscreenWhileStreaming = bool(.fullscreenWhileStreaming)
        enable444 = bool(.enable444)
@@ -219,6 +222,8 @@ public struct SettingsOverlay: Codable, Equatable, Sendable {
        try c.encodeIfPresent(mouseMode, forKey: AnyKey(Key.mouseMode.rawValue))
        try c.encodeIfPresent(invertScroll, forKey: AnyKey(Key.invertScroll.rawValue))
        try c.encodeIfPresent(gamepadType, forKey: AnyKey(Key.gamepadType.rawValue))
+        try c.encodeIfPresent(
+            gamepadForwarding, forKey: AnyKey(Key.gamepadForwarding.rawValue))
        try c.encodeIfPresent(statsVerbosity, forKey: AnyKey(Key.statsVerbosity.rawValue))
        try c.encodeIfPresent(
            fullscreenWhileStreaming, forKey: AnyKey(Key.fullscreenWhileStreaming.rawValue))
@@ -271,6 +276,7 @@ public enum OverlayField {
        case "mouse_mode": overlay.mouseMode = nil
        case "invert_scroll": overlay.invertScroll = nil
        case "gamepad": overlay.gamepadType = nil
+        case "gamepad_forwarding": overlay.gamepadForwarding = nil
        case "stats_verbosity": overlay.statsVerbosity = nil
        case "fullscreen_on_stream": overlay.fullscreenWhileStreaming = nil
        case "enable_444": overlay.enable444 = nil
@@ -306,6 +312,7 @@ public enum OverlayField {
        case "mouse_mode": return o.mouseMode != nil
        case "invert_scroll": return o.invertScroll != nil
        case "gamepad": return o.gamepadType != nil
+        case "gamepad_forwarding": return o.gamepadForwarding != nil
        case "stats_verbosity": return o.statsVerbosity != nil
        case "fullscreen_on_stream": return o.fullscreenWhileStreaming != nil
        case "enable_444": return o.enable444 != nil
@@ -24,8 +24,15 @@ the panel looks and feels native to Gaming Mode.
   browser (aurora backdrop + poster coverflow; A plays, B returns to Gaming Mode). Pins survive
   plugin reinstalls (stored next to the client's config) and follow a host across IP changes
   (matched by certificate fingerprint).
-5. **Settings** — resolution / refresh / bitrate / gamepad type / host compositor / mic, written
-   to the client's config.
+5. **Settings** — the client's whole settings store, written to its config. Laid out like SteamOS's
+   own Settings: a left rail of categories (`SidebarNavigation`), one page each, so no page needs
+   scrolling. The categories and their order are the console settings screen's — Stream (resolution
+   / refresh / render scale / bitrate / compositor), Video (codec / decoder / GPU / HDR / 4:4:4),
+   Presentation (prioritize / smoothness buffer / V-Sync / VRR), Audio (channels / output + mic
+   device / echo cancellation), Controllers, Touch & mouse, Interface (stats overlay / auto-wake /
+   library / fullscreen). The device pickers are populated
+   from the session binary (`--list-adapters` / `--list-audio`); the GPU row appears only where
+   there is more than one adapter.
 6. **About** — plugin version, an explicit "Check for updates" button, the setup-guide link, and
   a force-stop for a wedged stream client.

@@ -93,7 +100,7 @@ restart is required for an out-of-band install to appear.
 | --- | --- |
 | `src/index.tsx` | Plugin entry: the QAM panel + route registration. |
 | `src/page.tsx` | The `/punktfunk` fullscreen page — Hosts (with per-host details) / Settings / About tabs. |
-| `src/settings.tsx` · `src/pair.tsx` | Stream-settings section; the gamepad-navigable PIN-pairing modal. |
+| `src/settings.tsx` · `src/pair.tsx` | The settings screen (a `SidebarNavigation` of seven category pages over one shared settings object); the gamepad-navigable PIN-pairing modal. |
 | `src/library.tsx` | The per-host game picker (pin/unpin, "Open library on screen") + the pinned-game launch helper. |
 | `src/hostmgmt.tsx` | Add / edit host dialogs — mutate the shared known-hosts store (`client-known-hosts.json`) via the flatpak client's headless modes, so a host saved here shows up in the desktop client too. |
 | `src/ui.tsx` | Shared UI primitives for the fullscreen page + modals (right-aligned row actions, consistent Field layout). |
@@ -21,6 +21,10 @@ The backend's jobs are the things Steam can't do:
  the frontend so it can create/point the Steam shortcut.
 * **get_settings() / set_settings()** — read/write the flatpak client's stream settings JSON
  (resolution / bitrate / gamepad), so the Deck UI configures the stream the client reads.
+  ``set_settings`` MERGES onto the file: it is shared with the desktop client and the console.
+* **list_devices() / refresh_devices()** — the GPUs and audio endpoints the settings tab's
+  device pickers offer, read from the session binary (``--list-adapters`` / ``--list-audio``)
+  and cached, since enumerating them costs a Vulkan + PipeWire init.
 * **kill_stream()** — force-stop a wedged stream (``flatpak kill``).
 * **check_update()** — report pending updates for BOTH the plugin and the client. The plugin's
  comes from the registry's per-channel ``manifest.json`` (the frontend then drives Decky's own
@@ -343,6 +347,9 @@ def _flatpak() -> str | None:
 # settings in the same ~/.config/punktfunk (the flatpak's sandbox HOME resolves to the real
 # home), so nothing else in this file has to care which one answered.
 NATIVE_BIN = "punktfunk-client"
+# The Vulkan session binary the shell execs to stream — and the only thing that can enumerate
+# this device's GPUs and audio endpoints for the settings pickers.
+SESSION_BIN = "punktfunk-session"

 # Prefixes to try when PATH doesn't have it. The Decky backend runs with a minimal PATH, and
 # SteamOS's read-only /usr pushes native installs into a sysext or the user's own prefix.
@@ -398,6 +405,25 @@ def _client_argv() -> list[str] | None:
    return [native] if native else None


+def _session_argv() -> list[str] | None:
+    """The argv PREFIX that runs the SESSION binary headlessly, or None when it isn't there.
+
+    The device enumerations the settings pickers need (`--list-adapters`, `--list-audio`) live on
+    `punktfunk-session`, not on the client: the GTK shell deliberately links no Vulkan itself and
+    shells out to the session for exactly the same two lists (clients/linux/src/app.rs). The
+    flatpak installs both binaries into /app/bin, so `--command=` picks the other one; a native
+    install puts them in the same bindir, so the session is the client's sibling.
+    """
+    prefix = _client_argv()
+    if not prefix:
+        return None
+    if prefix[0] == _flatpak():
+        # `flatpak run --command=<bin> <app>` — the app id must stay LAST.
+        return [*prefix[:-1], f"--command={SESSION_BIN}", prefix[-1]]
+    sibling = Path(prefix[0]).with_name(SESSION_BIN)
+    return [str(sibling)] if sibling.exists() else None
+
+
 def _client_is_flatpak() -> bool:
    """Is the client this plugin actually drives the FLATPAK one?

@@ -511,6 +537,63 @@ async def _run_client(client_args: list[str], timeout: float = 20.0) -> tuple[in
        return -1, "", ""


+def _parse_audio_endpoints(out: str) -> tuple[list[dict], list[dict]]:
+    """Split `punktfunk-session --list-audio` into ``(sinks, sources)``.
+
+    Its format is one endpoint per line, ``sink|source<TAB>node.name<TAB>description``. The
+    node.name is what gets STORED (it is the stable id the client resolves against), so a line
+    without one is unusable and dropped; a missing description falls back to the name rather than
+    rendering a picker entry with no label. Anything else on the line is ignored, so an extra
+    trailing column in a future client can't break this.
+    """
+    sinks: list[dict] = []
+    sources: list[dict] = []
+    for line in out.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3 or not parts[1].strip():
+            continue
+        kind, name, description = parts[0].strip(), parts[1].strip(), parts[2].strip()
+        entry = {"name": name, "description": description or name}
+        if kind == "sink":
+            sinks.append(entry)
+        elif kind == "source":
+            sources.append(entry)
+    return sinks, sources
+
+
+async def _run_session(session_args: list[str], timeout: float = 25.0) -> tuple[int, str]:
+    """Run the SESSION binary headlessly, returning ``(returncode, stdout)``; ``(-1, "")`` when
+    it isn't installed or the call errors/times out.
+
+    Only ever used for the two read-only device enumerations — the launch path goes through the
+    Steam shortcut and the wrapper script, never through here. The timeout is generous because
+    `--list-adapters` initialises Vulkan on a cold flatpak."""
+    prefix = _session_argv()
+    if not prefix:
+        return -1, ""
+    proc = None
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *prefix, *session_args,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL,
+            env=_flatpak_env(),
+        )
+        out, _ = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        rc = proc.returncode if proc.returncode is not None else -1
+        return rc, (out or b"").decode("utf-8", "replace")
+    except asyncio.TimeoutError:
+        decky.logger.warning("session %s timed out", " ".join(session_args))
+        if proc:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+        return -1, ""
+    except Exception:  # noqa: BLE001
+        decky.logger.exception("session %s failed", " ".join(session_args))
+        return -1, ""
+
+
 # The QAM panel and the full page each mount their own hosts view, and Gaming Mode remounts the
 # QAM often — every mount calls list_hosts, which spawns a flatpak cold-start plus a reachability
 # probe. Cache the last result briefly so back-to-back opens reuse it instead of re-probing; any
@@ -518,6 +601,11 @@ async def _run_client(client_args: list[str], timeout: float = 20.0) -> tuple[in
 _HOSTS_TTL_S = 12.0
 _hosts_cache: dict = {"at": 0.0, "probed": None, "data": None}

+# The settings tab's device lists (GPUs / audio endpoints). No TTL: this is hardware, and reading
+# it costs a Vulkan + PipeWire init. Held for the life of the plugin backend; `refresh_devices`
+# clears it for the user who just plugged a headset in.
+_devices_cache: dict = {"data": None}
+

 def _invalidate_hosts_cache() -> None:
    _hosts_cache["data"] = None
@@ -1044,24 +1132,84 @@ class Plugin:
        try:
            return json.loads(_settings_path().read_text())
        except (OSError, json.JSONDecodeError):
-            # The client's own defaults (native display, host-default bitrate, auto pad).
+            # The client's own defaults (native display, host-default bitrate, auto pad,
+            # stats overlay at Normal — `Settings::default` is `show_stats: true`).
            return {
                "width": 0, "height": 0, "refresh_hz": 0, "render_scale": 1.0,
-                "bitrate_kbps": 0, "codec": "auto", "gamepad": "auto", "compositor": "auto",
+                "bitrate_kbps": 0, "codec": "auto", "gamepad": "auto",
+                "gamepad_forwarding": True, "compositor": "auto",
                "inhibit_shortcuts": True, "mic_enabled": False,
+                "stats_verbosity": "normal", "show_stats": True,
            }

    async def set_settings(self, settings: dict) -> dict:
-        """Write the stream settings JSON the (sandboxed) client reads on launch."""
+        """Write the stream settings JSON the (sandboxed) client reads on launch.
+
+        MERGED onto whatever is on disk, never a wholesale replace: this file is shared with
+        the desktop client and the console's settings screen, and it holds far more keys than
+        this panel models (decoder, GPU, profiles, touch/mouse model…). The panel reads it once
+        when it mounts, so a straight write would post a snapshot that predates anything those
+        other editors stored in the meantime — silently reverting it.
+        """
        try:
            d = _client_config_dir()
            d.mkdir(parents=True, exist_ok=True)
-            _settings_path().write_text(json.dumps(settings, indent=2))
+            try:
+                on_disk = json.loads(_settings_path().read_text())
+                if not isinstance(on_disk, dict):
+                    on_disk = {}
+            except (OSError, json.JSONDecodeError):
+                on_disk = {}  # no file yet (or an unreadable one): this write creates it
+            on_disk.update(settings)
+            _settings_path().write_text(json.dumps(on_disk, indent=2))
            return {"ok": True}
        except OSError as exc:
            decky.logger.exception("could not write settings")
            return {"ok": False, "error": str(exc)}

+    async def list_devices(self) -> dict:
+        """GPUs + audio endpoints for the settings tab's device pickers.
+
+        Two subprocesses that initialise Vulkan and PipeWire, so the result is cached for the
+        Decky session: hardware doesn't come and go often enough to justify paying that on every
+        remount of the page, and a stale entry is harmless — a picked device that has since
+        vanished falls back to the OS default in the client anyway. `refresh_devices` clears it.
+
+        Best-effort in the same way every other client call here is: no session binary (an old
+        flatpak that predates the two-binary split, or a native install missing its sibling) just
+        means empty lists and `ok: false`, which the UI shows as "couldn't read" rather than as
+        "you have no devices".
+        """
+        if _devices_cache["data"] is not None:
+            return _devices_cache["data"]
+
+        adapters: list[str] = []
+        sinks: list[dict] = []
+        sources: list[dict] = []
+        rc_a, out_a = await _run_session(["--list-adapters"])
+        if rc_a == 0:
+            adapters = [ln.strip() for ln in out_a.splitlines() if ln.strip()]
+        rc_d, out_d = await _run_session(["--list-audio"])
+        if rc_d == 0:
+            sinks, sources = _parse_audio_endpoints(out_d)
+
+        result = {
+            "ok": rc_a == 0 or rc_d == 0,
+            "adapters": adapters,
+            "sinks": sinks,
+            "sources": sources,
+        }
+        # Only a run that actually answered is worth remembering — caching a failure would make
+        # a client installed after the page was first opened stay invisible until a Decky restart.
+        if result["ok"]:
+            _devices_cache["data"] = result
+        return result
+
+    async def refresh_devices(self) -> dict:
+        """Drop the cached enumeration and read it again (a headset was just plugged in)."""
+        _devices_cache["data"] = None
+        return await self.list_devices()
+
    # ---- Shared known-hosts store (the SAME file the desktop client reads/writes) ----

    async def list_hosts(self, probe: bool = True) -> dict:
@@ -144,6 +144,33 @@ got = asyncio.run(plugin.get_pins())["pins"]
 check("pins: paired via known-hosts fp (case-insensitive)", got[0]["paired"] is True)
 shutil.rmtree(decky.DECKY_USER_HOME, ignore_errors=True)

+# ---- `--list-audio` parsing (the settings tab's device pickers) --------------------------
+sinks, sources = main._parse_audio_endpoints(
+    "sink\talsa_output.pci-0000_04_00.6.analog-stereo\tSteam Deck Speakers\n"
+    "sink\tbluez_output.AC_12_2F.1\tWH-1000XM4\n"
+    "source\talsa_input.pci-0000_04_00.6.analog-stereo\tSteam Deck Microphone\n"
+)
+check("audio: sinks parsed", [d["name"] for d in sinks] == [
+    "alsa_output.pci-0000_04_00.6.analog-stereo", "bluez_output.AC_12_2F.1"
+])
+check("audio: sources parsed", len(sources) == 1)
+check("audio: description kept", sinks[1]["description"] == "WH-1000XM4")
+
+# Junk the picker must not offer: no node.name is unusable (it is the id that gets stored), a
+# short line is malformed, and an unknown kind belongs to neither list. A blank description
+# falls back to the name so no entry renders unlabelled.
+sinks, sources = main._parse_audio_endpoints(
+    "sink\t\tNo node name\n"
+    "sink\tonly-two-columns\n"
+    "monitor\tsome.monitor\tNot a sink or source\n"
+    "source\tbare.node\t\n"
+    "\n"
+)
+check("audio: junk lines dropped", sinks == [])
+check("audio: blank description falls back to the node name", sources == [
+    {"name": "bare.node", "description": "bare.node"}
+])
+
 print()
 if failures:
    print(f"{failures} check(s) FAILED")
@@ -101,24 +101,97 @@ export interface RunnerInfo {
  client_bin?: string;
 }

-// The slice of the flatpak client's settings JSON this UI surfaces. The file can hold more
-// keys (decoder, … set from the desktop client's own UI) — they round-trip untouched
-// because get_settings returns the whole parsed file and patches are object spreads.
+// The flatpak client's settings JSON — the SAME `client-gtk-settings.json` the desktop client
+// and the console's settings screen own, so a value changed in any of them shows in the others.
+//
+// Every field the client's `Settings` struct persists is modelled here EXCEPT the ones that
+// cannot be answered from a plugin backend or aren't settings at all:
+//   • `forward_pad`   — which physical pad is player 1. Needs SDL's live device list, which only
+//                       the client process has; there is no CLI that enumerates pads.
+//   • `last_window_w/h` — the session's remembered window size, written BY the client, not a
+//                       preference anyone sets.
+// Both round-trip untouched: get_settings returns the whole parsed file, patches are object
+// spreads, and set_settings merges onto what's on disk.
+//
+// Optional (`?`) marks a key the client writes with a serde `default`, so a store written before
+// that key existed simply lacks it. Read those through the same fallback the client uses —
+// `?? true` for the default-on ones, never `!!` — or a pre-existing file reads as "off" here
+// while the stream runs with it on.
 export interface StreamSettings {
+  // ---- Stream mode ----
  width: number; // 0 = native
  height: number; // 0 = native
  refresh_hz: number; // 0 = native
  render_scale?: number; // render-resolution multiplier; 1.0 = native (absent in pre-scale files)
  bitrate_kbps: number; // 0 = host default
-  codec?: string; // "auto" | "hevc" | "h264" | "av1" — soft preference (absent in pre-codec files)
-  gamepad: string; // "auto" | "xbox360" | "xboxone" | "dualsense" | "dualshock4" | "steamdeck"
  compositor: string; // "auto" | "kwin" | "wlroots" | "mutter" | "gamescope"
-  // Round-trips only — deliberately NOT offered as a row here. It decides whether the session
-  // grabs the keyboard so Alt+Tab/Super reach the host, and Game Mode is gamescope: it has no
-  // compositor shortcuts to inhibit and hands the focused window every key already. A toggle
-  // here would be a dead one. The desktop client's row still edits this same file.
-  inhibit_shortcuts: boolean;
+  // Stream mode follows the session window instead of width/height, renegotiating on resize.
+  // Overrides width/height while on; degenerates to the display's native mode on fullscreen.
+  match_window?: boolean;
+
+  // ---- Video ----
+  codec?: string; // "auto" | "hevc" | "h264" | "av1" | "pyrowave" (absent in pre-codec files)
+  decoder?: string; // "auto" | "vulkan" | "vaapi" | "software"
+  hdr_enabled?: boolean; // default ON — advertise 10-bit/HDR10
+  enable_444?: boolean; // default off — ask for full chroma
+  adapter?: string; // decode/present GPU by marketing name; "" = automatic
+
+  // ---- Presentation ----
+  // What the client optimises for when a decoded frame is ready: "latency" | "smooth". Shared
+  // with the Apple and Android clients under this name, so one profile reads the same everywhere.
+  present_priority?: string;
+  smooth_buffer?: number; // frames held back under "smooth"; 0 = Automatic (resolves to 2), else 1–3
+  vsync?: boolean; // default ON — tear-free; off asks for a tearing present mode (best-effort)
+  allow_vrr?: boolean; // default ON — let a VRR panel refresh in step with the stream
+
+  // ---- Audio ----
+  audio_channels?: number; // 2 (stereo) | 6 (5.1) | 8 (7.1)
+  speaker_device?: string; // PipeWire node.name for playback; "" = system default
  mic_enabled: boolean;
+  mic_device?: string; // PipeWire node.name for capture; "" = system default
+  echo_cancel?: boolean; // default ON; only meaningful while mic_enabled
+
+  // ---- Controllers ----
+  gamepad: string; // "auto" | "xbox360" | "xboxone" | "dualsense" | "dualshock4" | "steamdeck"
+  // Forward this device's controllers at all. Absent in pre-forwarding files, where the
+  // client's own serde default (true) applies — so `?? true` at every read, never `!!`.
+  gamepad_forwarding?: boolean;
+
+  // ---- Touchscreen, mouse & keyboard ----
+  touch_mode?: string; // "trackpad" | "pointer" | "touch"
+  mouse_mode?: string; // "capture" | "desktop"
+  invert_scroll?: boolean;
+  // Whether the session grabs the keyboard so Alt+Tab/Super reach the host.
+  inhibit_shortcuts: boolean;
+
+  // ---- Interface & behaviour ----
+  // Stats-overlay tier: "off" | "compact" | "normal" | "detailed". Absent in a pre-tier file,
+  // which resolves through `show_stats` — read both the way the client's
+  // `Settings::stats_verbosity` does, and write both the way `set_stats_verbosity` does.
+  stats_verbosity?: string;
+  // The legacy on/off the tier supersedes; kept written in sync so a client that predates the
+  // tiers still honours an Off chosen here.
+  show_stats?: boolean;
+  fullscreen_on_stream?: boolean;
+  auto_wake?: boolean; // default ON — Wake-on-LAN a sleeping host before connecting
+  library_enabled?: boolean; // the CLIENT's own library browser (this plugin has its own)
+}
+
+// One audio endpoint from the client's enumeration: the stable id that gets stored, plus the
+// human name to show.
+export interface AudioDevice {
+  name: string; // PipeWire node.name — what `speaker_device` / `mic_device` store
+  description: string; // human label ("Steam Deck Speakers")
+}
+
+// What the device pickers need, read from the session binary (`--list-adapters` / `--list-audio`).
+// `ok: false` = the session binary couldn't be run or failed; every list is then empty and the
+// pickers stay on their stored value rather than pretending the device is gone.
+export interface DeviceLists {
+  ok: boolean;
+  adapters: string[]; // Vulkan physical devices, discrete first
+  sinks: AudioDevice[]; // playback endpoints
+  sources: AudioDevice[]; // capture endpoints
 }

 export interface UpdateInfo {
@@ -185,6 +258,11 @@ export const getSettings = callable<[], StreamSettings>("get_settings");
 export const setSettings = callable<[settings: StreamSettings], { ok: boolean }>(
  "set_settings",
 );
+// GPUs + audio endpoints for the device pickers. Costs a subprocess that initialises Vulkan and
+// PipeWire, so it is called ONCE when the settings tab mounts and never on the launch path.
+export const listDevices = callable<[], DeviceLists>("list_devices");
+// The same, bypassing the backend's cache — for the user who just plugged in a headset.
+export const refreshDevices = callable<[], DeviceLists>("refresh_devices");
 export const killStream = callable<[], { ok: boolean }>("kill_stream");
 // Send a Wake-on-LAN magic packet to a saved host (headless flatpak --wake) so a sleeping host is
 // up by the time the stream connects. The MAC is looked up from the flatpak client's own
@@ -334,8 +334,14 @@ const HostsTab: FC<{
  </div>
 );

+// NOT `tabScroll`: the settings screen is a SidebarNavigation, which lays out its own rail +
+// content pane and scrolls the pane itself. Wrapping it in an outer scroll area would give it an
+// indefinite height to fill, collapsing the rail — so this pane only hands it the full height and
+// keeps its hands off the overflow. The footer inset lives inside the pages instead.
+const settingsPane: CSSProperties = { height: "100%", overflow: "hidden" };
+
 const SettingsTab: FC = () => (
-  <div style={tabScroll}>
+  <div style={settingsPane}>
    <SettingsSection />
  </div>
 );
@@ -1,10 +1,59 @@
-// Stream settings — resolution / refresh / bitrate / gamepad / compositor / mic, written to
-// the flatpak client's JSON (main.py set_settings), which the client reads on launch. The
-// accepted gamepad/compositor names mirror punktfunk-core's `*Pref::from_name`.
-import { Dropdown, Field, SliderField, Spinner, ToggleField } from "@decky/ui";
-import { CSSProperties, FC, useEffect, useState } from "react";
-import { getSettings, setSettings, StreamSettings } from "./backend";
-import { RowActions } from "./ui";
+// Stream settings — the client's WHOLE settings store, written to the JSON the client reads on
+// launch (main.py set_settings, merged onto what's on disk). This is the same
+// `client-gtk-settings.json` the desktop client and the console's settings screen own, so a value
+// changed in any of the three shows in the other two.
+//
+// SHAPE OF THIS SCREEN. Thirty rows is too many to scroll past on a thumbstick, so they are split
+// across a `SidebarNavigation` — the same left-rail-of-categories layout SteamOS's own Settings
+// uses, and the one Deck users already know. Every page fits on screen without scrolling, which is
+// the whole point of the split: the rail is the index, so nothing is more than one hop away.
+//
+// The categories, their order, and the wording of the rows are the console's settings screen
+// (pf-console-ui/src/screens/settings.rs) — that screen is the other settings editor a user
+// reaches without leaving Gaming Mode, and two different orders for one store is how people stop
+// trusting either. It shows them as one steppable list because it has no pointer and no room for
+// a rail; here they become the rail's pages, same groups, same sequence. Three more rules:
+//
+//   • A setting that depends on another is INDENTED under it and DISABLED, never hidden — the
+//     console dims those rows rather than dropping them, and a row that vanishes as you toggle
+//     the one above it is a moving target for a thumbstick.
+//   • A picker whose options this device doesn't have doesn't appear at all (the GPU row on a
+//     one-GPU Deck). A dead control is worse than an absent one.
+//   • Anything that behaves differently *here* than it does on a desktop says so in its own
+//     description, rather than being silently dropped from the screen.
+//
+// The accepted gamepad/compositor/codec/decoder names mirror punktfunk-core's `*Pref::from_name`
+// and the console's tables; the tier/mode names mirror the `StatsVerbosity` / `TouchMode` /
+// `MouseMode` enums, which serialize lowercase.
+import {
+  DialogButton,
+  Dropdown,
+  Field,
+  SidebarNavigation,
+  SliderField,
+  Spinner,
+  ToggleField,
+} from "@decky/ui";
+import { CSSProperties, FC, ReactElement, ReactNode, useEffect, useState } from "react";
+import {
+  FaDesktop,
+  FaGamepad,
+  FaHandPointer,
+  FaSlidersH,
+  FaTv,
+  FaVideo,
+  FaVolumeUp,
+} from "react-icons/fa";
+import {
+  AudioDevice,
+  DeviceLists,
+  getSettings,
+  listDevices,
+  refreshDevices,
+  setSettings,
+  StreamSettings,
+} from "./backend";
+import { actionButton, RowActions } from "./ui";

 // Decky's Dropdown has no width prop — it fills whatever container it's in, and a
 // `childrenContainerWidth="max"` Field is the whole row. Wrapping it in this fit-content shell
@@ -17,50 +66,543 @@ const selectShell: CSSProperties = {
  maxWidth: "24em",
 };

+// ----------------------------------------------------------------------------------------
+// Option tables — the console's, so the two Gaming-Mode editors offer the same choices.
+// ----------------------------------------------------------------------------------------
+
+// "native" and "match" are virtual: they store `width`/`height` of 0 with `match_window` off/on.
+// Match window is offered even though this plugin's launches are always fullscreen (where it
+// degenerates to the display's native mode) — leaving it out would make the row lie about a
+// store the desktop client can set it in.
+const MATCH_WINDOW = "match";
 const RESOLUTIONS: [number, number, string][] = [
  [0, 0, "Native display"],
  [1280, 720, "1280 × 720"],
  [1280, 800, "1280 × 800 (Deck)"],
  [1920, 1080, "1920 × 1080"],
  [2560, 1440, "2560 × 1440"],
+  [3840, 2160, "3840 × 2160"],
 ];
+const resolutionKey = (w: number, h: number): string => (w === 0 && h === 0 ? "native" : `${w}x${h}`);
+
 const REFRESH = [0, 30, 60, 90, 120];
 // Render-resolution multipliers (mirrors punktfunk_core::render_scale::PRESETS). 1.0 = native.
 const RENDER_SCALES = [0.5, 0.67, 0.75, 1.0, 1.25, 1.5, 2.0, 3.0, 4.0];
 const renderScaleLabel = (x: number): string =>
  x === 1 ? "Native (1×)" : x > 1 ? `${x}× · supersample` : `${x}×`;
-const GAMEPADS = ["auto", "xbox360", "xboxone", "dualsense", "dualshock4", "steamdeck"];
-const GAMEPAD_LABELS: Record<string, string> = {
-  auto: "Automatic",
-  xbox360: "Xbox 360",
-  xboxone: "Xbox One",
-  dualsense: "DualSense",
-  dualshock4: "DualShock 4",
-  steamdeck: "Steam Deck",
+
+const COMPOSITORS: [string, string][] = [
+  ["auto", "Automatic"],
+  ["kwin", "KDE Plasma (KWin)"],
+  ["wlroots", "Sway (wlroots)"],
+  ["mutter", "GNOME (Mutter)"],
+  ["gamescope", "gamescope"],
+];
+const CODECS: [string, string][] = [
+  ["auto", "Automatic"],
+  ["hevc", "HEVC (H.265)"],
+  ["h264", "H.264 (AVC)"],
+  ["av1", "AV1"],
+  // Opt-in wired-LAN low-latency codec (100–400 Mbit/s class, 8-bit SDR). Only ever selected
+  // when the host advertises it too; anything else falls back to HEVC.
+  ["pyrowave", "PyroWave (wired LAN)"],
+];
+const DECODERS: [string, string][] = [
+  ["auto", "Automatic"],
+  ["vulkan", "Vulkan Video"],
+  ["vaapi", "VAAPI"],
+  ["software", "Software"],
+];
+// Presentation intent — the `present_priority` key shared with the Apple and Android clients, so
+// one profile reads the same on every device.
+const PRESENT_PRIORITIES: [string, string][] = [
+  ["latency", "Lowest latency"],
+  ["smooth", "Smoothness"],
+];
+// Smoothness buffer depth in frames; 0 = Automatic (resolves to 2).
+const SMOOTH_BUFFERS: [number, string][] = [
+  [0, "Automatic"],
+  [1, "1 frame"],
+  [2, "2 frames"],
+  [3, "3 frames"],
+];
+const AUDIO_CHANNELS: [number, string][] = [
+  [2, "Stereo"],
+  [6, "5.1 surround"],
+  [8, "7.1 surround"],
+];
+const GAMEPADS: [string, string][] = [
+  ["auto", "Automatic"],
+  ["xbox360", "Xbox 360"],
+  ["xboxone", "Xbox One"],
+  ["dualsense", "DualSense"],
+  ["dualshock4", "DualShock 4"],
+  ["steamdeck", "Steam Deck"],
+];
+const TOUCH_MODES: [string, string][] = [
+  ["trackpad", "Trackpad"],
+  ["pointer", "Direct pointer"],
+  ["touch", "Touch passthrough"],
+];
+const MOUSE_MODES: [string, string][] = [
+  ["capture", "Capture (games)"],
+  ["desktop", "Desktop (absolute)"],
+];
+const STATS_TIERS: [string, string][] = [
+  ["off", "Off"],
+  ["compact", "Compact"],
+  ["normal", "Normal"],
+  ["detailed", "Detailed"],
+];
+
+// ----------------------------------------------------------------------------------------
+// Row primitives — every picker row is Field + right-aligned, content-sized Dropdown, so the
+// twelve of them below stay one line each and can't drift apart.
+// ----------------------------------------------------------------------------------------
+
+const SelectRow = <T extends string | number>({
+  label,
+  description,
+  options,
+  value,
+  onChange,
+  formatUnknown,
+  disabled,
+  indent,
+}: {
+  label: string;
+  description?: ReactNode;
+  options: [T, string][];
+  value: T;
+  onChange: (v: T) => void;
+  // How to name a stored value this table doesn't list (see below); defaults to the raw value.
+  formatUnknown?: (v: T) => string;
+  disabled?: boolean;
+  indent?: boolean;
+}): ReactElement => {
+  // A Dropdown can only display a value that is one of its options, and this store has four other
+  // writers — the desktop client, the console, a settings profile, a newer client with presets
+  // this build doesn't know. Rather than render a blank control (or, worse, silently show a
+  // different value than the stream will actually use), carry the stored one as its own entry.
+  const shown: [T, string][] = options.some(([v]) => v === value)
+    ? options
+    : [...options, [value, formatUnknown ? formatUnknown(value) : String(value)]];
+  return (
+    <Field
+      label={label}
+      description={description}
+      disabled={disabled}
+      indentLevel={indent ? 1 : undefined}
+      childrenContainerWidth="max"
+    >
+      <RowActions>
+        <div style={selectShell}>
+          <Dropdown
+            disabled={disabled}
+            rgOptions={shown.map(([data, l]) => ({ data, label: l }))}
+            selectedOption={value}
+            onChange={(o) => onChange(o.data as T)}
+          />
+        </div>
+      </RowActions>
+    </Field>
+  );
 };
-// Mirrors the desktop client's picker (ui_settings.rs CODECS) — a soft preference the host
-// falls back from when its GPU can't encode it.
-const CODECS = ["auto", "hevc", "h264", "av1"];
-const CODEC_LABELS: Record<string, string> = {
-  auto: "Automatic",
-  hevc: "HEVC (H.265)",
-  h264: "H.264 (AVC)",
-  av1: "AV1",
+
+// An audio-endpoint picker. The stored value is a PipeWire `node.name`; "" means "whatever the OS
+// is using". A stored endpoint that isn't in the current enumeration still gets an entry — it is
+// a real preference that simply isn't plugged in right now, and dropping it would silently
+// re-point the next stream at the default without ever showing the user why.
+const DeviceRow: FC<{
+  label: string;
+  description: string;
+  devices: AudioDevice[] | null;
+  value: string;
+  onChange: (v: string) => void;
+  disabled?: boolean;
+  indent?: boolean;
+}> = ({ label, description, devices, value, onChange, disabled, indent }) => {
+  const options: [string, string][] = [["", "System default"]];
+  for (const d of devices ?? []) options.push([d.name, d.description]);
+  if (value && !options.some(([name]) => name === value)) {
+    options.push([value, `${value} (not connected)`]);
+  }
+  return (
+    <SelectRow
+      label={label}
+      description={devices === null ? "Reading this device's audio endpoints…" : description}
+      options={options}
+      value={value}
+      onChange={onChange}
+      disabled={disabled || devices === null}
+      indent={indent}
+    />
+  );
 };
-const COMPOSITORS = ["auto", "kwin", "wlroots", "mutter", "gamescope"];
-const COMPOSITOR_LABELS: Record<string, string> = {
-  auto: "Automatic",
-  kwin: "KDE Plasma (KWin)",
-  wlroots: "Sway (wlroots)",
-  mutter: "GNOME (Mutter)",
-  gamescope: "gamescope",
+
+// ----------------------------------------------------------------------------------------
+// The pages. One settings object, seven views on it — every page takes the same context rather
+// than fetching or holding state of its own, so a change on one page is visible on the others
+// the moment you switch.
+// ----------------------------------------------------------------------------------------
+
+interface PageCtx {
+  s: StreamSettings;
+  patch: (p: Partial<StreamSettings>) => void;
+  devices: DeviceLists | null;
+  reading: boolean;
+  readDevices: (again: boolean) => void;
+}
+
+// SidebarNavigation gives each page Steam's own padding, but the routed page still renders
+// UNDER Gaming Mode's footer hint bar, so the last row of a page needs to clear it (the same
+// inset the tabs use).
+const pageBody: CSSProperties = { paddingBottom: "80px" };
+
+const StreamPage: FC<PageCtx> = ({ s, patch }) => {
+  const renderScale = s.render_scale ?? 1;
+  const resolution = s.match_window ? MATCH_WINDOW : resolutionKey(s.width, s.height);
+  return (
+    <div style={pageBody}>
+      <SelectRow
+        label="Resolution"
+        description="The host creates a virtual display at exactly this size — no scaling. Match window follows the stream window instead, which in Gaming Mode means the Deck's native size."
+        options={[
+          ...RESOLUTIONS.map(([w, h, label]) => [resolutionKey(w, h), label] as [string, string]),
+          [MATCH_WINDOW, "Match window"] as [string, string],
+        ]}
+        value={resolution}
+        // A size set from a desktop profile that isn't one of these presets, spelled the way the
+        // presets are rather than left as the raw "1600x900" key.
+        formatUnknown={(v) => v.replace("x", " × ")}
+        onChange={(v) => {
+          if (v === MATCH_WINDOW) {
+            // The tri-state the console stores: the flag on, the explicit size cleared.
+            patch({ match_window: true, width: 0, height: 0 });
+            return;
+          }
+          const found = RESOLUTIONS.find(([w, h]) => resolutionKey(w, h) === v);
+          patch({ match_window: false, width: found?.[0] ?? 0, height: found?.[1] ?? 0 });
+        }}
+      />
+      <SelectRow
+        label="Refresh rate"
+        description="Native follows the display the stream is on."
+        options={REFRESH.map((r) => [r, r === 0 ? "Native" : `${r} Hz`] as [number, string])}
+        value={s.refresh_hz}
+        formatUnknown={(v) => `${v} Hz`}
+        onChange={(v) => patch({ refresh_hz: v })}
+      />
+      <SelectRow
+        label="Render scale"
+        description="The host renders larger or smaller than the stream mode and the Deck resamples — above 1× supersamples for sharpness, below 1× saves bandwidth."
+        options={RENDER_SCALES.map((x) => [x, renderScaleLabel(x)] as [number, string])}
+        // Snap the stored value to the nearest preset so the dropdown always shows a match.
+        value={RENDER_SCALES.reduce((best, x) =>
+          Math.abs(x - renderScale) < Math.abs(best - renderScale) ? x : best,
+        )}
+        onChange={(v) => patch({ render_scale: v })}
+      />
+      <SliderField
+        label="Bitrate"
+        description="0 = the host's own default (20 Mbit/s)."
+        value={Math.round(s.bitrate_kbps / 1000)}
+        min={0}
+        max={150}
+        step={5}
+        showValue
+        valueSuffix=" Mbit/s"
+        onChange={(v) => patch({ bitrate_kbps: v * 1000 })}
+      />
+      <SelectRow
+        label="Host compositor"
+        description="Which compositor drives the virtual display — honoured only if it's available on the host. Automatic suits almost every host."
+        options={COMPOSITORS}
+        value={s.compositor}
+        onChange={(v) => patch({ compositor: v })}
+      />
+    </div>
+  );
 };

+const VideoPage: FC<PageCtx> = ({ s, patch, devices }) => {
+  // Only worth a row on a box that actually has a choice to make. A Deck has one adapter, and a
+  // picker with a single option is a control that can't do anything.
+  const showGpuRow = (devices?.adapters.length ?? 0) > 1;
+  return (
+    <div style={pageBody}>
+      <SelectRow
+        label="Video codec"
+        description="A preference — the host falls back when its GPU can't encode this one."
+        options={CODECS}
+        value={s.codec ?? "auto"}
+        onChange={(v) => patch({ codec: v })}
+      />
+      <SelectRow
+        label="Video decoder"
+        description="How the Deck decodes the stream. Automatic prefers Vulkan Video, then VAAPI, then software."
+        options={DECODERS}
+        value={s.decoder ?? "auto"}
+        onChange={(v) => patch({ decoder: v })}
+      />
+      {showGpuRow && (
+        <SelectRow
+          label="Decode GPU"
+          description="Which adapter decodes and presents the stream. Automatic picks the discrete GPU where there is one."
+          options={[
+            ["", "Automatic"],
+            ...(devices?.adapters ?? []).map((a) => [a, a] as [string, string]),
+          ]}
+          value={s.adapter ?? ""}
+          onChange={(v) => patch({ adapter: v })}
+        />
+      )}
+      <ToggleField
+        label="10-bit HDR"
+        description="Advertise HDR10 so the host sends 10-bit when the content is HDR. Off means never ask for 10-bit."
+        checked={s.hdr_enabled ?? true}
+        onChange={(v) => patch({ hdr_enabled: v })}
+      />
+      <ToggleField
+        label="Full chroma (4:4:4)"
+        description="Full-colour video: crisp small text and thin lines, at more bandwidth. Needs an NVIDIA host (NVENC) or the PyroWave codec — other encoders stream 4:2:0 and the session falls back silently."
+        checked={s.enable_444 ?? false}
+        onChange={(v) => patch({ enable_444: v })}
+      />
+    </div>
+  );
+};
+
+const PresentationPage: FC<PageCtx> = ({ s, patch }) => {
+  const smooth = (s.present_priority ?? "latency") === "smooth";
+  return (
+    <div style={pageBody}>
+      <SelectRow
+        label="Prioritize"
+        description="What to optimise for when a decoded frame is ready. Lowest latency shows each frame the moment the display can take it — a network hiccup becomes an occasional repeated or skipped frame. Smoothness buffers a little to even those out."
+        options={PRESENT_PRIORITIES}
+        value={s.present_priority ?? "latency"}
+        onChange={(v) => patch({ present_priority: v })}
+      />
+      <SelectRow
+        label="Smoothness buffer"
+        description="Frames held back before showing. Each one absorbs about a refresh of network hiccup and adds a refresh of delay. Automatic holds two."
+        options={SMOOTH_BUFFERS}
+        value={s.smooth_buffer ?? 0}
+        formatUnknown={(v) => `${v} frames`}
+        onChange={(v) => patch({ smooth_buffer: v })}
+        disabled={!smooth}
+        indent
+      />
+      <ToggleField
+        label="V-Sync"
+        description="Tear-free. Off removes the wait for the screen's refresh — the lowest possible delay, at the cost of visible tearing. Best-effort: not every driver offers it, and the Detailed stats overlay names the mode actually in use."
+        checked={s.vsync ?? true}
+        onChange={(v) => patch({ vsync: v })}
+      />
+      <ToggleField
+        label="Follow variable refresh"
+        description="On a VRR screen, let the panel refresh in step with the stream instead of on a fixed cadence. Applies to fullscreen sessions — which a Gaming-Mode stream always is — and is harmless on a fixed-refresh screen."
+        checked={s.allow_vrr ?? true}
+        onChange={(v) => patch({ allow_vrr: v })}
+      />
+    </div>
+  );
+};
+
+const AudioPage: FC<PageCtx> = ({ s, patch, devices, reading, readDevices }) => {
+  const micOn = s.mic_enabled;
+  // What the pickers get: null while the enumeration is in flight (they show a loading state),
+  // [] when it answered but couldn't read the endpoints (System default plus whatever is
+  // stored), and the real list otherwise.
+  const endpoints = (list: AudioDevice[] | undefined): AudioDevice[] | null =>
+    reading || !devices ? null : devices.ok ? (list ?? []) : [];
+  return (
+    <div style={pageBody}>
+      <SelectRow
+        label="Audio channels"
+        description="The speaker layout requested from the host, which clamps it to what it can capture."
+        options={AUDIO_CHANNELS}
+        value={s.audio_channels ?? 2}
+        formatUnknown={(v) => `${v} channels`}
+        onChange={(v) => patch({ audio_channels: v })}
+      />
+      <DeviceRow
+        label="Output device"
+        description="Where stream audio plays. System default follows whatever the Deck is using, including a headset you plug in mid-stream."
+        devices={endpoints(devices?.sinks)}
+        value={s.speaker_device ?? ""}
+        onChange={(v) => patch({ speaker_device: v })}
+      />
+      <ToggleField
+        label="Stream microphone"
+        description="Send the Deck's microphone to the host's virtual mic. Ctrl+Alt+Shift+V mutes and unmutes it mid-stream."
+        checked={micOn}
+        onChange={(v) => patch({ mic_enabled: v })}
+      />
+      <DeviceRow
+        label="Microphone device"
+        description="Which input the mic uplink captures from."
+        devices={endpoints(devices?.sources)}
+        value={s.mic_device ?? ""}
+        onChange={(v) => patch({ mic_device: v })}
+        disabled={!micOn}
+        indent
+      />
+      <ToggleField
+        label="Echo cancellation"
+        description="Stops the host's audio, playing from the Deck's speakers, being picked up and sent back. Turn it off if your microphone already runs its own processing."
+        checked={s.echo_cancel ?? true}
+        onChange={(v) => patch({ echo_cancel: v })}
+        disabled={!micOn}
+        indentLevel={1}
+      />
+      {/* The escape hatch for a headset plugged in after this page was opened, and the honest
+          answer when the enumeration failed outright (a client too old to ship the session
+          binary). Rendered unconditionally, including while it is reading: a row that comes and
+          goes under a thumbstick is a moving target, so only its wording changes. */}
+      <Field
+        label={
+          !reading && devices && !devices.ok ? "Couldn't read this device's hardware" : "Devices"
+        }
+        description={
+          reading
+            ? "Reading this device's audio endpoints and GPUs…"
+            : devices && !devices.ok
+              ? "The output, microphone and GPU pickers fall back to Automatic. Reading them needs the client's session binary, which a client older than the two-binary split doesn't ship — update it from the About tab."
+              : "Plugged something in just now? Read the audio endpoints and GPUs again."
+        }
+        childrenContainerWidth="max"
+      >
+        <RowActions>
+          <DialogButton style={actionButton} disabled={reading} onClick={() => readDevices(true)}>
+            {reading ? <Spinner style={{ height: "1em" }} /> : "Refresh"}
+          </DialogButton>
+        </RowActions>
+      </Field>
+    </div>
+  );
+};
+
+const ControllersPage: FC<PageCtx> = ({ s, patch }) => {
+  const forwarding = s.gamepad_forwarding ?? true;
+  return (
+    <div style={pageBody}>
+      <ToggleField
+        label="Forward controllers"
+        description="Send controllers connected to the Deck to the host. Turn it off when your controller already reaches the host another way — USB passthrough such as VirtualHere, or a pad plugged into the host — so games don't see two of them."
+        checked={forwarding}
+        onChange={(v) => patch({ gamepad_forwarding: v })}
+      />
+      <SelectRow
+        label="Controller type"
+        description="The virtual pad the host creates. Automatic matches the controller you're holding."
+        options={GAMEPADS}
+        value={s.gamepad}
+        onChange={(v) => patch({ gamepad: v })}
+        disabled={!forwarding}
+        indent
+      />
+      {forwarding && (s.gamepad === "steamdeck" || s.gamepad === "auto") && (
+        <Field
+          label="⚠ Disable Steam Input"
+          description="On a Deck, Automatic forwards the built-in controller as a Steam Deck pad — paddles, both trackpads, and gyro included. For that, Steam Input must be OFF for Punktfunk: on the game page tap ⚙ → Controller Settings → set Steam Input to Off. Otherwise Steam keeps the Deck's controls and only the sticks + buttons reach the host."
+          indentLevel={1}
+        />
+      )}
+    </div>
+  );
+};
+
+const PointerPage: FC<PageCtx> = ({ s, patch }) => (
+  <div style={pageBody}>
+    <SelectRow
+      label="Touch mode"
+      description="How the touchscreen drives the host: Trackpad (relative cursor, tap to click), Direct pointer (the cursor jumps to your finger), or Touch passthrough (every finger is a host contact — only helps apps that understand touch)."
+      options={TOUCH_MODES}
+      value={s.touch_mode ?? "trackpad"}
+      onChange={(v) => patch({ touch_mode: v })}
+    />
+    <SelectRow
+      label="Mouse mode"
+      description="How a physical mouse drives the host: Capture locks the pointer for games, Desktop leaves it free and sends absolute positions. Ctrl+Alt+Shift+M switches it live mid-stream."
+      options={MOUSE_MODES}
+      value={s.mouse_mode ?? "capture"}
+      onChange={(v) => patch({ mouse_mode: v })}
+    />
+    <ToggleField
+      label="Invert scroll direction"
+      description="Reverses the wheel and trackpad scroll direction sent to the host."
+      checked={s.invert_scroll ?? false}
+      onChange={(v) => patch({ invert_scroll: v })}
+    />
+    <ToggleField
+      label="Capture system shortcuts"
+      description="Sends Alt+Tab, Super and friends to the host while input is captured, instead of leaving them to the local desktop. Gaming Mode is gamescope, which has no shortcuts to hold back — this is for a keyboard attached to the Deck in Desktop Mode, and for the desktop client sharing these settings."
+      checked={s.inhibit_shortcuts}
+      onChange={(v) => patch({ inhibit_shortcuts: v })}
+    />
+  </div>
+);
+
+const InterfacePage: FC<PageCtx> = ({ s, patch }) => {
+  // `Settings::stats_verbosity`: no tier = a pre-tier store, resolved through the legacy bool,
+  // which itself defaults to true.
+  const statsTier = s.stats_verbosity ?? ((s.show_stats ?? true) ? "normal" : "off");
+  return (
+    <div style={pageBody}>
+      <SelectRow
+        label="Statistics overlay"
+        description="How much the in-stream overlay shows: Compact (fps · latency · bitrate on one line) → Normal → Detailed. A three-finger tap on the touchscreen cycles it mid-stream."
+        options={STATS_TIERS}
+        value={statsTier}
+        // Both keys, in sync — the same pairing `Settings::set_stats_verbosity` keeps, so a
+        // client too old for the tiers still honours an Off chosen here.
+        onChange={(v) => patch({ stats_verbosity: v, show_stats: v !== "off" })}
+      />
+      <ToggleField
+        label="Wake hosts automatically"
+        description="Send Wake-on-LAN to a sleeping host before connecting and wait for it to boot. Turn it off for hosts reached over a VPN, where an offline-looking host is really just unreachable by broadcast and the wait only adds delay."
+        checked={s.auto_wake ?? true}
+        onChange={(v) => patch({ auto_wake: v })}
+      />
+      <ToggleField
+        label="Show game library in the client"
+        description="Lets the client's own host cards browse a paired host's games. This plugin's library browser works either way — this is for the client's screens."
+        checked={s.library_enabled ?? false}
+        onChange={(v) => patch({ library_enabled: v })}
+      />
+      <ToggleField
+        label="Start streams fullscreen"
+        description="Streams open fullscreen instead of windowed. Launches from this plugin are always fullscreen whatever this says — it's here because the desktop client reads the same settings."
+        checked={s.fullscreen_on_stream ?? true}
+        onChange={(v) => patch({ fullscreen_on_stream: v })}
+      />
+    </div>
+  );
+};
+
+// ----------------------------------------------------------------------------------------
+
 export const SettingsSection: FC = () => {
  const [s, setS] = useState<StreamSettings | null>(null);
+  // null until the enumeration answers — the pickers show a loading state rather than briefly
+  // claiming this device has no endpoints.
+  const [devices, setDevices] = useState<DeviceLists | null>(null);
+  const [reading, setReading] = useState(true);
+
+  const readDevices = (again: boolean) => {
+    setReading(true);
+    void (again ? refreshDevices() : listDevices())
+      .then(setDevices)
+      .finally(() => setReading(false));
+  };

  useEffect(() => {
    void getSettings().then(setS);
+    // Deliberately not awaited together with the settings: a cold flatpak initialising Vulkan
+    // takes seconds, and the rest of the screen must not wait for it.
+    readDevices(false);
  }, []);

  const patch = (p: Partial<StreamSettings>) => {
@@ -74,128 +616,42 @@ export const SettingsSection: FC = () => {

  if (!s) return <Spinner style={{ height: "1.5em" }} />;

-  const resIdx = Math.max(
-    0,
-    RESOLUTIONS.findIndex(([w, h]) => w === s.width && h === s.height),
-  );
-
+  const ctx: PageCtx = { s, patch, devices, reading, readDevices };
  return (
-    <>
-      <Field
-        label="Resolution"
-        description="The host creates a virtual output at exactly this size"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={RESOLUTIONS.map(([, , label], i) => ({ data: i, label }))}
-              selectedOption={resIdx}
-              onChange={(o) => {
-                const [w, h] = RESOLUTIONS[o.data as number];
-                patch({ width: w, height: h });
-              }}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      <Field label="Refresh rate" childrenContainerWidth="max">
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={REFRESH.map((r) => ({ data: r, label: r === 0 ? "Native" : `${r} Hz` }))}
-              selectedOption={s.refresh_hz}
-              onChange={(o) => patch({ refresh_hz: o.data as number })}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      <Field
-        label="Render scale"
-        description="Supersample for sharpness (> 1×, more bandwidth) or render below native (< 1×) — the Deck resamples to its screen"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={RENDER_SCALES.map((x) => ({ data: x, label: renderScaleLabel(x) }))}
-              // Snap the stored value to the nearest preset so the dropdown always shows a match.
-              selectedOption={RENDER_SCALES.reduce((best, x) =>
-                Math.abs(x - (s.render_scale ?? 1)) < Math.abs(best - (s.render_scale ?? 1)) ? x : best,
-              )}
-              onChange={(o) => patch({ render_scale: o.data as number })}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      <SliderField
-        label="Bitrate"
-        description="Mbit/s · 0 = host default"
-        value={Math.round(s.bitrate_kbps / 1000)}
-        min={0}
-        max={150}
-        step={5}
-        showValue
-        valueSuffix=" Mbit/s"
-        onChange={(v) => patch({ bitrate_kbps: v * 1000 })}
-      />
-      <Field
-        label="Video codec"
-        description="Preferred stream codec — the host falls back when its GPU can't encode it"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={CODECS.map((c) => ({ data: c, label: CODEC_LABELS[c] ?? c }))}
-              selectedOption={s.codec ?? "auto"}
-              onChange={(o) => patch({ codec: o.data as string })}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      <Field
-        label="Gamepad type"
-        description="Which virtual controller the host creates for your inputs"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={GAMEPADS.map((g) => ({ data: g, label: GAMEPAD_LABELS[g] ?? g }))}
-              selectedOption={s.gamepad}
-              onChange={(o) => patch({ gamepad: o.data as string })}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      {(s.gamepad === "steamdeck" || s.gamepad === "auto") && (
-        <Field
-          label="⚠ Disable Steam Input"
-          description="On a Deck, Automatic forwards the built-in controller as a Steam Deck pad — paddles, both trackpads, and gyro included. For that, Steam Input must be OFF for Punktfunk: on the game page tap ⚙ → Controller Settings → set Steam Input to Off. Otherwise Steam keeps the Deck's controls and only the sticks + buttons reach the host."
-        />
-      )}
-      <Field
-        label="Host compositor"
-        description="Which compositor backend the host uses for the virtual display — Automatic suits almost every host"
-        childrenContainerWidth="max"
-      >
-        <RowActions>
-          <div style={selectShell}>
-            <Dropdown
-              rgOptions={COMPOSITORS.map((c) => ({ data: c, label: COMPOSITOR_LABELS[c] ?? c }))}
-              selectedOption={s.compositor}
-              onChange={(o) => patch({ compositor: o.data as string })}
-            />
-          </div>
-        </RowActions>
-      </Field>
-      <ToggleField
-        label="Stream microphone"
-        description="Send the Deck's microphone to the host's virtual mic"
-        checked={s.mic_enabled}
-        onChange={(v) => patch({ mic_enabled: v })}
-      />
-    </>
+    <SidebarNavigation
+      // We are already inside the plugin's own `/punktfunk` route, rendered in a tab. Route
+      // reporting would have this nav push entries of its own onto the router and fight the
+      // page for the back gesture; the pages are addressed by `identifier` instead.
+      disableRouteReporting
+      pages={[
+        { title: "Stream", identifier: "stream", icon: <FaDesktop />, content: <StreamPage {...ctx} /> },
+        { title: "Video", identifier: "video", icon: <FaVideo />, content: <VideoPage {...ctx} /> },
+        {
+          title: "Presentation",
+          identifier: "presentation",
+          icon: <FaTv />,
+          content: <PresentationPage {...ctx} />,
+        },
+        { title: "Audio", identifier: "audio", icon: <FaVolumeUp />, content: <AudioPage {...ctx} /> },
+        {
+          title: "Controllers",
+          identifier: "controllers",
+          icon: <FaGamepad />,
+          content: <ControllersPage {...ctx} />,
+        },
+        {
+          title: "Touch & mouse",
+          identifier: "pointer",
+          icon: <FaHandPointer />,
+          content: <PointerPage {...ctx} />,
+        },
+        {
+          title: "Interface",
+          identifier: "interface",
+          icon: <FaSlidersH />,
+          content: <InterfacePage {...ctx} />,
+        },
+      ]}
+    />
  );
 };
@@ -156,6 +156,20 @@ mod index {
    pub fn gamepad(s: &Settings) -> u32 {
        GAMEPADS.iter().position(|&g| g == s.gamepad).unwrap_or(0) as u32
    }
+
+    pub fn present_priority(s: &Settings) -> u32 {
+        // Unknown values (a newer client's intent) read as the default, exactly as
+        // `PresentPriority::resolve` treats them.
+        PRESENT_PRIORITIES
+            .iter()
+            .position(|&p| p == s.present_priority)
+            .unwrap_or(0) as u32
+    }
+
+    pub fn smooth_buffer(s: &Settings) -> u32 {
+        // The index IS the stored value: 0 = Automatic, 1..3 = frames.
+        u32::from(s.smooth_buffer).min(SMOOTH_BUFFER_LABELS.len() as u32 - 1)
+    }
 }

 /// The chip palette a profile can carry (`StreamProfile.accent`). Eight entries rather than a
@@ -625,12 +639,27 @@ fn commit_profile(active: &StreamProfile, touched: &Touched, values: &Settings)
    if touched.has("gamepad") {
        o.gamepad = Some(values.gamepad.clone());
    }
+    if touched.has("gamepad_forwarding") {
+        o.gamepad_forwarding = Some(values.gamepad_forwarding);
+    }
    if touched.has("stats_verbosity") {
        o.stats_verbosity = Some(values.stats_verbosity());
    }
    if touched.has("fullscreen_on_stream") {
        o.fullscreen_on_stream = Some(values.fullscreen_on_stream);
    }
+    if touched.has("present_priority") {
+        o.present_priority = Some(values.present_priority.clone());
+    }
+    if touched.has("smooth_buffer") {
+        o.smooth_buffer = Some(values.smooth_buffer);
+    }
+    if touched.has("vsync") {
+        o.vsync = Some(values.vsync);
+    }
+    if touched.has("allow_vrr") {
+        o.allow_vrr = Some(values.allow_vrr);
+    }
    // Resets are not handled here: they clear the field and re-seed their row the moment the
    // user asks, so by the time this runs the catalog already reflects them and the row is no
    // longer marked touched.
@@ -684,6 +713,20 @@ const TOUCH_MODE_CAPTIONS: &[&str] = &[
    "The cursor jumps to your finger — a tap clicks there",
    "Real multi-touch reaches the host — for touch-native apps",
 ];
+/// Presentation-intent values (persisted under the `present_priority` key the Apple and
+/// Android clients share) + labels + dynamic captions. Captions stay ONE line, like the
+/// touch/mouse rows.
+const PRESENT_PRIORITIES: &[&str] = &["latency", "smooth"];
+const PRESENT_PRIORITY_LABELS: &[&str] = &["Lowest latency", "Smoothness"];
+const PRESENT_PRIORITY_CAPTIONS: &[&str] = &[
+    "Each frame shows the moment the display can take it",
+    "Buffers a little to even out network hiccups",
+];
+/// Smoothness buffer depth, in frames — the index IS the stored `smooth_buffer` value
+/// (0 = Automatic, which resolves to 2). No millisecond hints: the cost is one refresh
+/// per frame, and the session's refresh isn't known here when the mode is Native.
+const SMOOTH_BUFFER_LABELS: &[&str] = &["Automatic", "1 frame", "2 frames", "3 frames"];
+
 /// Physical-mouse model values (persisted) + labels + dynamic captions — same idiom as
 /// the touch rows. Ctrl+Alt+Shift+M flips the model live in-stream.
 const MOUSE_MODES: &[&str] = &["capture", "desktop"];
@@ -1213,6 +1256,50 @@ pub fn show_scoped(
        row
    });

+    // ---- Display: Presentation ----
+    // The intent pair the Apple and Android clients already carry. The buffer row only
+    // means anything under Smoothness, so it hides itself the rest of the time rather
+    // than sitting there inert.
+    let present_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Prioritize",
+        PRESENT_PRIORITY_CAPTIONS[0],
+        PRESENT_PRIORITY_LABELS,
+    );
+    let buffer_row = ChoiceRow::new(
+        &dialog,
+        inline,
+        "Smoothness buffer",
+        "Each frame held absorbs one refresh of hiccup and adds one of delay",
+        SMOOTH_BUFFER_LABELS,
+    );
+    {
+        let w = present_row.widget().clone();
+        let buffer = buffer_row.widget().clone();
+        present_row.connect_changed(move |i| {
+            let i = (i as usize).min(PRESENT_PRIORITY_CAPTIONS.len() - 1);
+            set_row_subtitle(&w, PRESENT_PRIORITY_CAPTIONS[i]);
+            buffer.set_visible(PRESENT_PRIORITIES[i] == "smooth");
+        });
+    }
+    let vsync_row = adw::SwitchRow::builder()
+        .title("V-Sync")
+        .subtitle(
+            "Tear-free. Turning it off removes the wait for the screen's refresh — the \
+             lowest possible delay, at the cost of visible tearing. Not every driver \
+             offers it; the stats overlay names the mode actually in use",
+        )
+        .build();
+    let vrr_row = adw::SwitchRow::builder()
+        .title("Follow variable refresh rate")
+        .subtitle(
+            "On a VRR/FreeSync/G-Sync screen, let the panel refresh in step with the \
+             stream instead of on a fixed cadence. Applies to fullscreen sessions; \
+             harmless on a fixed-refresh screen",
+        )
+        .build();
+
    // ---- Display: Host output ----
    let compositor_row = ChoiceRow::new(
        &dialog,
@@ -1376,6 +1463,17 @@ pub fn show_scoped(
    // controller (single-player). The pin is persisted by stable key (`Settings::forward_pad`),
    // so it survives restarts — and disconnects: an offline pinned pad keeps its entry here
    // instead of silently snapping back to Automatic.
+    // Off = this device's controllers are not sent at all, because they reach the host
+    // another way (USB passthrough such as VirtualHere, or a pad plugged into the host).
+    // It also stops the session OPENING the pad, which is what frees the device for a
+    // passthrough tool to bind — so the two rows below have nothing to act on while it is
+    // off, and are desensitised to say so.
+    let pad_forward_row = adw::SwitchRow::builder()
+        .title("Forward controllers")
+        .subtitle(
+            "Send this device's controllers to the host — off if it already has them another way",
+        )
+        .build();
    let pads = gamepads.pads();
    let saved_pin = settings.borrow().forward_pad.clone();
    let mut pad_names = vec!["Automatic (all controllers)".to_string()];
@@ -1444,6 +1542,18 @@ pub fn show_scoped(
            "Steam Deck",
        ],
    );
+    // Both pad rows only mean something while something is being forwarded (the same
+    // relationship mic → echo cancellation draws just above, initial state included: the
+    // seed's `set_active` fires this only when it CHANGES the switch).
+    {
+        let (f, t) = (forward_row.widget().clone(), pad_row.widget().clone());
+        f.set_sensitive(seed.gamepad_forwarding);
+        t.set_sensitive(seed.gamepad_forwarding);
+        pad_forward_row.connect_active_notify(move |r| {
+            f.set_sensitive(r.is_active());
+            t.set_sensitive(r.is_active());
+        });
+    }

    // ---- Seed from the effective settings for this scope ----
    {
@@ -1454,6 +1564,7 @@ pub fn show_scoped(
        hz_row.set_selected(index::refresh(s));
        scale_row.set_selected(index::render_scale(s));
        bitrate_row.set_value(f64::from(s.bitrate_kbps) / 1000.0);
+        pad_forward_row.set_active(s.gamepad_forwarding);
        pad_row.set_selected(index::gamepad(s));
        let touch_i = index::touch(s);
        touch_row.set_selected(touch_i);
@@ -1479,6 +1590,19 @@ pub fn show_scoped(
        let codec_i = index::codec(s);
        codec_row.set_selected(codec_i);
        set_row_subtitle(codec_row.widget(), codec_caption(codec_i));
+        let present_i = index::present_priority(s);
+        present_row.set_selected(present_i);
+        set_row_subtitle(
+            present_row.widget(),
+            PRESENT_PRIORITY_CAPTIONS[present_i as usize],
+        );
+        buffer_row.set_selected(index::smooth_buffer(s));
+        // `set_selected` never fires the changed hook, so mirror its visibility rule here.
+        buffer_row
+            .widget()
+            .set_visible(PRESENT_PRIORITIES[present_i as usize] == "smooth");
+        vsync_row.set_active(s.vsync);
+        vrr_row.set_active(s.allow_vrr);
    }

    // ---- Override markers, per-row reset, and the touch that creates an override ----
@@ -1671,6 +1795,26 @@ pub fn show_scoped(
            index::surround
        );
        choice!(pad_row, "gamepad", o.gamepad.is_some(), index::gamepad);
+        toggle!(
+            pad_forward_row,
+            "gamepad_forwarding",
+            o.gamepad_forwarding.is_some(),
+            gamepad_forwarding
+        );
+        choice!(
+            present_row,
+            "present_priority",
+            o.present_priority.is_some(),
+            index::present_priority
+        );
+        choice!(
+            buffer_row,
+            "smooth_buffer",
+            o.smooth_buffer.is_some(),
+            index::smooth_buffer
+        );
+        toggle!(vsync_row, "vsync", o.vsync.is_some(), vsync);
+        toggle!(vrr_row, "allow_vrr", o.allow_vrr.is_some(), allow_vrr);
        toggle!(hdr_row, "hdr_enabled", o.hdr_enabled.is_some(), hdr_enabled);
        toggle!(chroma_row, "enable_444", o.enable_444.is_some(), enable_444);
        toggle!(
@@ -1775,6 +1919,11 @@ pub fn show_scoped(
    if let (Some(r), false) = (&gpu_row, profile_mode) {
        quality_group.add(r.widget());
    }
+    let presentation_group = group("Presentation", "");
+    presentation_group.add(present_row.widget());
+    presentation_group.add(buffer_row.widget());
+    presentation_group.add(&vsync_row);
+    presentation_group.add(&vrr_row);
    // The one form-level note (deliberately not repeated on every row).
    let output_group = group(
        "Host output",
@@ -1783,6 +1932,7 @@ pub fn show_scoped(
    output_group.add(compositor_row.widget());
    display.add(&resolution_group);
    display.add(&quality_group);
+    display.add(&presentation_group);
    display.add(&output_group);

    let input = page("Input", "input-keyboard-symbolic");
@@ -1843,6 +1993,10 @@ pub fn show_scoped(
            controllers_group.add(&row);
        }
    }
+    // Profileable, so it shows in both scopes — unlike the pin below it, which is about
+    // which of THIS device's pads goes first: a "Work" profile can decline to forward
+    // controllers to a host that a "Game" profile forwards them to.
+    controllers_group.add(&pad_forward_row);
    if !profile_mode {
        controllers_group.add(forward_row.widget());
    }
@@ -1915,6 +2069,7 @@ pub fn show_scoped(
            s.auto_wake = wake_row.is_active();
            s.inhibit_shortcuts = inhibit_row.is_active();
            s.invert_scroll = invert_row.is_active();
+            s.gamepad_forwarding = pad_forward_row.is_active();
            s.mic_enabled = mic_row.is_active();
            s.echo_cancel = echo_row.is_active();
            s.hdr_enabled = hdr_row.is_active();
@@ -1925,6 +2080,14 @@ pub fn show_scoped(
                _ => 2,
            };
            s.codec = CODECS[(codec_row.selected() as usize).min(CODECS.len() - 1)].to_string();
+            s.present_priority = PRESENT_PRIORITIES
+                [(present_row.selected() as usize).min(PRESENT_PRIORITIES.len() - 1)]
+            .to_string();
+            // The index IS the value (0 = Automatic).
+            s.smooth_buffer =
+                (buffer_row.selected() as u8).min(SMOOTH_BUFFER_LABELS.len() as u8 - 1);
+            s.vsync = vsync_row.is_active();
+            s.allow_vrr = vrr_row.is_active();
            s.library_enabled = library_row.is_active();
        };

@@ -169,6 +169,11 @@ pub fn run(target: Option<&str>) -> u8 {
        mouse_mode: settings_at_start.mouse_mode(),
        invert_scroll: settings_at_start.invert_scroll,
        inhibit_shortcuts: settings_at_start.inhibit_shortcuts,
+        // Presentation-tier like the rows above: latched at console start, a per-host
+        // profile cannot move it in this mode (the documented P4 gap).
+        present_priority: settings_at_start.present_priority(),
+        vsync: settings_at_start.vsync,
+        allow_vrr: settings_at_start.allow_vrr,
        json_status,
        on_connected: Some(Box::new(move |fingerprint: [u8; 32]| {
            let fp_hex = trust::hex(&fingerprint);
@@ -188,6 +188,12 @@ mod session_main {
        if !settings.forward_pad.is_empty() {
            gamepad.set_pinned(Some(settings.forward_pad.clone()));
        }
+        // Whether to forward controllers AT ALL (off = the pad reaches the host by some other
+        // route — VirtualHere and friends). Set unconditionally, not only when off: browse mode
+        // reuses one service across launches, so a stream that follows one with it off must put
+        // it back. It goes on before the attach below, so a non-forwarding session never opens
+        // — never grabs — the device.
+        gamepad.set_forwarding(settings.gamepad_forwarding);
        let mode = Mode {
            width: if settings.width == 0 {
                native.width
@@ -617,6 +623,9 @@ mod session_main {
            mouse_mode: settings.mouse_mode(),
            invert_scroll: settings.invert_scroll,
            inhibit_shortcuts: settings.inhibit_shortcuts,
+            present_priority: settings.present_priority(),
+            vsync: settings.vsync,
+            allow_vrr: settings.allow_vrr,
            json_status: true,
            on_connected: Some(Box::new(|fingerprint: [u8; 32]| {
                // This host's card carries the accent bar in the desktop client now.
@@ -623,8 +623,14 @@ pub(crate) fn hosts_page(props: &HostsProps, cx: &mut RenderCx) -> Element {
                actions.push(
                    icon_btn("Settings", Symbol::Setting)
                        .on_click({
-                            let ss = set_screen.clone();
-                            move || ss.call(Screen::Settings)
+                            let (c, ss) = (ctx.clone(), set_screen.clone());
+                            move || {
+                                // Re-base the settings snapshot on the file before the page
+                                // renders — this process is not its only writer (see
+                                // settings::refresh_snapshot).
+                                super::settings::refresh_snapshot(&c);
+                                ss.call(Screen::Settings)
+                            }
                        })
                        .into(),
                );
@@ -2,7 +2,8 @@
 //! Settings).

 use super::style::*;
-use super::Screen;
+use super::{AppCtx, Screen};
+use std::sync::Arc;
 use windows_reactor::*;

 /// punktfunk's own license (MIT OR Apache-2.0).
@@ -15,10 +16,15 @@ const APP_LICENSE: &str = concat!(
 /// scripts/gen-third-party-notices.sh; the MSIX also ships this under licenses/).
 const THIRD_PARTY_NOTICES: &str = include_str!("../../../../THIRD-PARTY-NOTICES.txt");

-pub(crate) fn licenses_page(set_screen: &AsyncSetState<Screen>) -> Element {
+pub(crate) fn licenses_page(ctx: &Arc<AppCtx>, set_screen: &AsyncSetState<Screen>) -> Element {
    let back_btn = button("Back").accent().icon(Symbol::Back).on_click({
-        let ss = set_screen.clone();
-        move || ss.call(Screen::Settings)
+        let (c, ss) = (ctx.clone(), set_screen.clone());
+        move || {
+            // Back RE-ENTERS the settings page — re-base its snapshot on the file, same
+            // as the hosts page's Settings button (see settings::refresh_snapshot).
+            super::settings::refresh_snapshot(&c);
+            ss.call(Screen::Settings)
+        }
    });

    let app_card = card(
@@ -172,6 +172,10 @@ pub(crate) struct Shared {

 pub struct AppCtx {
    pub(crate) identity: (String, String),
+    /// The settings snapshot the UI renders from. Loaded once at startup, and RE-BASED on
+    /// the file when the settings page is (re)entered (`settings::refresh_snapshot`) and
+    /// inside every `commit` — this process is not the file's only writer (session resize,
+    /// console UI, Decky), so a plain process-lifetime snapshot goes stale on screen.
    pub(crate) settings: Mutex<Settings>,
    pub(crate) gamepad: GamepadService,
    pub(crate) shared: Arc<Shared>,
@@ -688,7 +692,7 @@ fn root(cx: &mut RenderCx, ctx: &Arc<AppCtx>) -> Element {
            &set_settings_rev,
            nav_progress,
        ),
-        Screen::Licenses => licenses::licenses_page(&set_screen),
+        Screen::Licenses => licenses::licenses_page(ctx, &set_screen),
        Screen::Help => help::help_page(&set_screen),
        Screen::Pair => component(pair::pair_page, svc),
        Screen::SpeedTest => component(speed::speed_page, SpeedProps { svc, state: speed }),
@@ -101,6 +101,19 @@ const MOUSE_MODES: &[(&str, &str)] = &[
    ("capture", "Capture (games)"),
    ("desktop", "Desktop (absolute)"),
 ];
+/// Presentation intent: `(stored value, display label)` — the `present_priority` key the
+/// Apple and Android clients share, so one profile means the same thing everywhere.
+const PRESENT_PRIORITIES: &[(&str, &str)] =
+    &[("latency", "Lowest latency"), ("smooth", "Smoothness")];
+/// Smoothness buffer depth in frames: `(stored value, display label)`. `0` = Automatic,
+/// which resolves to 2 (`PresentPriority::resolve`). No millisecond hints — the cost is
+/// one refresh per frame, and the refresh isn't known here when the mode is Native.
+const SMOOTH_BUFFERS: &[(u8, &str)] = &[
+    (0, "Automatic"),
+    (1, "1 frame"),
+    (2, "2 frames"),
+    (3, "3 frames"),
+];
 /// Host compositor presets: `(stored value, display label)`. Advisory — the host falls back to
 /// auto-detect when the choice is unavailable. Only meaningful against a Linux host.
 const COMPOSITORS: &[(&str, &str)] = &[
@@ -411,7 +424,16 @@ fn commit(
        return;
    }
    let mut catalog = ProfilesFile::load();
-    let base = ctx.settings.lock().unwrap().clone();
+    // The same rebase as the global arm above: `base` is what `absorb`'s before/after
+    // effective settings derive from, and the snapshot is not the file — another process
+    // (session resize, console UI, Decky) may have moved a global under us. The historical
+    // rebase fix ("settings saves stop reverting each other") covered the whole-file
+    // writers but missed this arm.
+    let base = {
+        let mut s = ctx.settings.lock().unwrap();
+        *s = Settings::load();
+        s.clone()
+    };
    let Some(p) = catalog.profiles.iter_mut().find(|p| p.id == scope) else {
        return; // deleted from under us; the next render falls back to the defaults scope
    };
@@ -425,6 +447,17 @@ fn commit(
    rev.1.call(rev.0 + 1);
 }

+/// Re-base the process-lifetime settings snapshot on the file — called from the navigation
+/// handlers that (re)enter this page, NOT per render pass. `ctx.settings` is loaded once at
+/// process start and this process is not the file's only writer (a spawned session persists
+/// its match-window size, the console UI and Decky save too — profiles.rs documents the
+/// family), so without this the page opens showing values another process already replaced,
+/// which then visibly "jump" the moment a row is touched and `commit`'s rebase pulls the
+/// file in. The field report this fixes: a codec setting that "changed by itself".
+pub(crate) fn refresh_snapshot(ctx: &Arc<AppCtx>) {
+    *ctx.settings.lock().unwrap() = Settings::load();
+}
+
 /// Which tier-P rows the profile in scope overrides. Plain bools rather than a lookup so the
 /// call sites read as `over.codec` — the row and its flag stay visibly paired.
 #[derive(Default)]
@@ -445,8 +478,13 @@ struct OverrideFlags {
    invert_scroll: bool,
    inhibit_shortcuts: bool,
    gamepad: bool,
+    gamepad_forwarding: bool,
    stats_verbosity: bool,
    fullscreen_on_stream: bool,
+    present_priority: bool,
+    smooth_buffer: bool,
+    vsync: bool,
+    allow_vrr: bool,
 }

 impl OverrideFlags {
@@ -473,8 +511,13 @@ impl OverrideFlags {
            invert_scroll: o.invert_scroll.is_some(),
            inhibit_shortcuts: o.inhibit_shortcuts.is_some(),
            gamepad: o.gamepad.is_some(),
+            gamepad_forwarding: o.gamepad_forwarding.is_some(),
            stats_verbosity: o.stats_verbosity.is_some(),
            fullscreen_on_stream: o.fullscreen_on_stream.is_some(),
+            present_priority: o.present_priority.is_some(),
+            smooth_buffer: o.smooth_buffer.is_some(),
+            vsync: o.vsync.is_some(),
+            allow_vrr: o.allow_vrr.is_some(),
        }
    }
 }
@@ -851,6 +894,32 @@ pub(crate) fn settings_page(
    let chroma_toggle = setting_toggle(ctx, scope, (rev, set_rev), s.enable_444, |s, on| {
        s.enable_444 = on
    });
+    // Presentation intent (design/desktop-presentation-rebuild.md). The buffer row is
+    // rendered only under Smoothness — `commit` bumps the revision, so flipping the
+    // intent re-renders the section and the row appears/disappears with it.
+    let (present_names, present_i) = presets(PRESENT_PRIORITIES, |v| *v == s.present_priority);
+    let present_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        present_names,
+        present_i,
+        |s, i| s.present_priority = PRESENT_PRIORITIES[i].0.to_string(),
+    );
+    let smoothing = s.present_priority == "smooth";
+    let (buffer_names, buffer_i) = presets(SMOOTH_BUFFERS, |v| *v == s.smooth_buffer);
+    let buffer_combo = setting_combo(
+        ctx,
+        scope,
+        (rev, set_rev),
+        buffer_names,
+        buffer_i,
+        |s, i| s.smooth_buffer = SMOOTH_BUFFERS[i].0,
+    );
+    let vsync_toggle = setting_toggle(ctx, scope, (rev, set_rev), s.vsync, |s, on| s.vsync = on);
+    let vrr_toggle = setting_toggle(ctx, scope, (rev, set_rev), s.allow_vrr, |s, on| {
+        s.allow_vrr = on
+    });

    // --- Input -----------------------------------------------------------------------------
    // Controller forwarding: Automatic forwards EVERY real controller, each as its own pad;
@@ -898,6 +967,10 @@ pub(crate) fn settings_page(
                s.save();
            })
    };
+    let pad_forward_toggle =
+        setting_toggle(ctx, scope, (rev, set_rev), s.gamepad_forwarding, |s, on| {
+            s.gamepad_forwarding = on
+        });
    let (pad_names, pad_i) = presets(GAMEPADS, |v| {
        GamepadPref::from_name(v) == GamepadPref::from_name(&s.gamepad)
    });
@@ -972,6 +1045,16 @@ pub(crate) fn settings_page(
        let ss = set_screen.clone();
        button("Third-party licenses").on_click(move || ss.call(Screen::Licenses))
    };
+    // The client log's home (%LOCALAPPDATA%\punktfunk\logs) — the file every "check the
+    // client log" message means, which until this row had no way in from the UI at all.
+    // The folder rather than the file so the rotated `.old` generation is in reach too.
+    // Best-effort, like the log itself: a missing dir or a failed spawn stays silent.
+    let logs_button = button("Open log folder").on_click(|| {
+        if let Some(dir) = crate::logfile::log_dir() {
+            let _ = std::fs::create_dir_all(&dir);
+            let _ = std::process::Command::new("explorer.exe").arg(&dir).spawn();
+        }
+    });
    let library_toggle = setting_toggle(ctx, scope, (rev, set_rev), s.library_enabled, |s, on| {
        s.library_enabled = on
    });
@@ -1065,8 +1148,9 @@ pub(crate) fn settings_page(
                        "HDR10, when the host has HDR content and this display supports it. \
                         HEVC only; otherwise the stream stays SDR.",
                    ),
-                    // Wording shared with the GTK client (its chroma_row) — same setting,
-                    // same constraints.
+                    // First sentence shared with the GTK client (its chroma_row); the
+                    // constraint sentence names the real gate (host: PyroWave || NVENC) —
+                    // "where the host can encode it" cost field users the discovery time.
                    described_overridable(
                        (rev, set_rev),
                        scope,
@@ -1075,7 +1159,8 @@ pub(crate) fn settings_page(
                        over.enable_444,
                        chroma_toggle,
                        "Full-colour video: crisp small text and thin lines, at more \
-                         bandwidth. HEVC only, and only where the host can encode it.",
+                         bandwidth. Requires an NVIDIA host (NVENC) or the PyroWave \
+                         codec \u{2014} other encoders stream 4:2:0.",
                    ),
                ],
                None,
@@ -1105,6 +1190,60 @@ pub(crate) fn settings_page(
                },
                None,
            ));
+            out.extend(group(
+                Some("Presentation"),
+                {
+                    let mut fields = vec![described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "present_priority",
+                        "Prioritize",
+                        over.present_priority,
+                        present_combo,
+                        "Lowest latency shows each frame the moment the display can take \
+                         it \u{2014} a network hiccup becomes an occasional repeated or \
+                         skipped frame. Smoothness buffers a little to even those out.",
+                    )];
+                    if smoothing {
+                        fields.push(described_overridable(
+                            (rev, set_rev),
+                            scope,
+                            "smooth_buffer",
+                            "Smoothness buffer",
+                            over.smooth_buffer,
+                            buffer_combo,
+                            "Frames held back before showing. Each one absorbs about a \
+                             refresh of network hiccup and adds a refresh of delay. \
+                             Automatic holds two.",
+                        ));
+                    }
+                    fields.push(described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "vsync",
+                        "V-Sync",
+                        over.vsync,
+                        vsync_toggle,
+                        "Tear-free. Turning it off removes the wait for the screen\u{2019}s \
+                         refresh \u{2014} the lowest possible delay, at the cost of visible \
+                         tearing. Not every driver offers it; the stats overlay names the \
+                         mode actually in use.",
+                    ));
+                    fields.push(described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "allow_vrr",
+                        "Follow variable refresh rate",
+                        over.allow_vrr,
+                        vrr_toggle,
+                        "On a VRR/FreeSync/G-Sync screen, let the panel refresh in step with \
+                         the stream instead of on a fixed cadence. Applies to fullscreen \
+                         sessions; harmless on a fixed-refresh screen.",
+                    ));
+                    fields
+                },
+                None,
+            ));
            out.extend(group(
                Some("Host output"),
                vec![described_overridable(
@@ -1223,6 +1362,23 @@ pub(crate) fn settings_page(
                            "Plug in or pair a controller and it appears here.",
                        )
                    }),
+                    // Whether ANY controller is forwarded — profileable, so it renders in
+                    // both scopes (a "Work" profile can decline what "Game" forwards),
+                    // unlike the device-fact picker below it.
+                    Some(described_overridable(
+                        (rev, set_rev),
+                        scope,
+                        "gamepad_forwarding",
+                        "Forward controllers",
+                        over.gamepad_forwarding,
+                        pad_forward_toggle,
+                        "Sends controllers connected to this PC to the host. Turn it off when \
+                         your controller already reaches the host another way \u{2014} USB \
+                         passthrough such as VirtualHere, or a pad plugged into the host \
+                         itself \u{2014} so games don't see two of them. Off, this PC never \
+                         opens the controller at all, which is what leaves it free for a \
+                         passthrough tool to claim.",
+                    )),
                    // NOT Apple's wording: Apple forwards ONE pad as player 1, this client
                    // forwards every controller as its own player. Same picker, different rule.
                    // Which physical pad this device forwards is a device fact (tier G), so it
@@ -1325,7 +1481,16 @@ pub(crate) fn settings_page(
            "About",
            group(
                None,
-                vec![about_identity.into(), licenses_button.into()],
+                vec![
+                    about_identity.into(),
+                    described_labeled(
+                        "Diagnostics",
+                        logs_button,
+                        "The client log (client.log, plus the session\u{2019}s whole \
+                         receive/decode/present trail) \u{2014} attach it to a bug report.",
+                    ),
+                    licenses_button.into(),
+                ],
                None,
            ),
        ),
@@ -1727,5 +1892,26 @@ mod tests {
        let f3 = OverrideFlags::of(Some(&p3));
        assert!(f3.echo_cancel);
        assert!(!f3.mic_enabled);
+
+        // The presentation pair, likewise independent: pinning the intent doesn't claim
+        // the buffer (a "Smoothness, whatever the global buffer is" profile is valid).
+        let mut p4 = StreamProfile::new("t4".to_string());
+        p4.overrides = SettingsOverlay {
+            present_priority: Some("smooth".into()),
+            ..Default::default()
+        };
+        let f4 = OverrideFlags::of(Some(&p4));
+        assert!(f4.present_priority);
+        assert!(!f4.smooth_buffer);
+
+        // V-Sync and VRR are independent of each other and of the intent pair.
+        let mut p5 = StreamProfile::new("t5".to_string());
+        p5.overrides = SettingsOverlay {
+            vsync: Some(false),
+            ..Default::default()
+        };
+        let f5 = OverrideFlags::of(Some(&p5));
+        assert!(f5.vsync);
+        assert!(!f5.allow_vrr && !f5.present_priority);
    }
 }
@@ -21,11 +21,12 @@ const ROTATE_BYTES: u64 = 10 * 1024 * 1024;

 static SINK: OnceLock<Option<Arc<Mutex<File>>>> = OnceLock::new();

-fn log_dir() -> Option<PathBuf> {
+/// The log directory — Settings ▸ About's "Open log folder" opens it in Explorer.
+pub(crate) fn log_dir() -> Option<PathBuf> {
    Some(PathBuf::from(std::env::var_os("LOCALAPPDATA")?).join(r"punktfunk\logs"))
 }

-/// The log file's path, for the "logs land here" startup line (and any future UI affordance).
+/// The log file's path, for the "logs land here" startup line and the failed-spawn banner.
 pub(crate) fn path() -> Option<PathBuf> {
    Some(log_dir()?.join("client.log"))
 }
@@ -105,7 +105,14 @@ fn parse_line(line: &str) -> Option<ChildLine> {
 /// connect that silently drops back to the host list.
 pub(crate) fn silent_exit_banner(code: i32) -> Option<String> {
    (code != 0 && code != -1).then(|| {
-        format!("The session didn't start (punktfunk-session exited with code {code}). Check the client log.")
+        // Name the log's actual location — "check the client log" without a path is a
+        // scavenger hunt (Settings ▸ About's "Open log folder" reaches it too).
+        let log = crate::logfile::path()
+            .map(|p| p.display().to_string())
+            .unwrap_or_else(|| "the client log".into());
+        format!(
+            "The session didn't start (punktfunk-session exited with code {code}). Check {log}."
+        )
    })
 }

@@ -612,7 +612,10 @@ pub fn open_portal_monitor(
 /// 10-bit PQ/BT.2020 formats instead of the SDR set — pass it only when the output was actually
 /// brought up HDR (a gamescope spawned with `--hdr-enabled` off our `pipewire-hdr` build); the
 /// host resolves that in `capture::capturer_supports_hdr_for` **before** the Welcome, because a
-/// session that negotiated PQ cannot fall back to SDR afterwards.
+/// session that negotiated PQ cannot fall back to SDR afterwards. `cursor_id0_hides` declares the
+/// producer's cursor-meta contract — pass it for outputs whose compositor rewrites
+/// `SPA_META_Cursor` on every buffer (KWin), where an `id == 0` meta is an authoritative
+/// "pointer hidden" the composited/forwarded cursor must honor.
 #[cfg(target_os = "linux")]
 #[allow(clippy::too_many_arguments)]
 pub fn open_virtual_output(
@@ -625,6 +628,7 @@ pub fn open_virtual_output(
    want_hdr: bool,
    policy: ZeroCopyPolicy,
    expect_exact_dims: bool,
+    cursor_id0_hides: bool,
 ) -> Result<Box<dyn Capturer>> {
    linux::PortalCapturer::from_virtual_output(
        remote_fd,
@@ -636,6 +640,7 @@ pub fn open_virtual_output(
        want_hdr && !hdr_capture_failed(HdrSource::VirtualOutput),
        policy,
        expect_exact_dims,
+        cursor_id0_hides,
    )
    .map(|c| Box::new(c) as Box<dyn Capturer>)
 }
@@ -72,6 +72,11 @@ struct CaptureOpts {
    /// the doomed birth mode. `false` everywhere else (Mutter SIZES the monitor from negotiation and
    /// gamescope fixates its own — gating those would starve legitimate first frames).
    expect_exact_dims: bool,
+    /// The producer rewrites `SPA_META_Cursor` on EVERY buffer, so an `id == 0` meta is an
+    /// authoritative "pointer hidden / off this output" the blend must honor (KWin). `false` for
+    /// the stale-meta producers (Mutter recycles buffers without rewriting the region) — see
+    /// [`pw_cursor::CursorState::id0_hides`](pw_cursor) for the full contract.
+    cursor_id0_hides: bool,
 }

 /// The shared state the PipeWire thread PUBLISHES and the capturer READS — one struct instead of
@@ -301,6 +306,10 @@ impl PortalCapturer {
                want_444: false,
                want_hdr,
                expect_exact_dims: false,
+                // The portal-monitor path today is Mutter (the GNOME HDR mirror) — the stale-meta
+                // id-0 contract. A KDE portal capture would rewrite per buffer, but nothing routes
+                // one through here yet; the virtual-output path below carries the real flag.
+                cursor_id0_hides: false,
            },
            policy,
        )?
@@ -316,7 +325,8 @@ impl PortalCapturer {
    /// the GPU zero-copy path subject to `PUNKTFUNK_ZEROCOPY`. `want_444` (a 4:4:4 session) makes the
    /// zero-copy worker convert tiled dmabufs to planar YUV444 on the GPU instead of NV12/RGB.
    /// `want_hdr` runs the 10-bit PQ/BT.2020 offer instead of the SDR set — see
-    /// [`crate::open_virtual_output`] for who is allowed to pass it.
+    /// [`crate::open_virtual_output`] for who is allowed to pass it. `cursor_id0_hides` declares
+    /// the producer's cursor-meta contract ([`CaptureOpts::cursor_id0_hides`]).
    #[allow(clippy::too_many_arguments)]
    pub fn from_virtual_output(
        remote_fd: Option<OwnedFd>,
@@ -328,6 +338,7 @@ impl PortalCapturer {
        want_hdr: bool,
        policy: ZeroCopyPolicy,
        expect_exact_dims: bool,
+        cursor_id0_hides: bool,
    ) -> Result<PortalCapturer> {
        tracing::info!(
            node_id,
@@ -335,6 +346,7 @@ impl PortalCapturer {
            want_444,
            want_hdr,
            expect_exact_dims,
+            cursor_id0_hides,
            "connecting PipeWire to virtual output"
        );
        // Most virtual outputs are SDR-only upstream (Mutter's RecordVirtual streams advertise
@@ -350,6 +362,7 @@ impl PortalCapturer {
                want_444,
                want_hdr,
                expect_exact_dims,
+                cursor_id0_hides,
            },
            policy,
        )?
@@ -811,6 +811,7 @@ pub fn pipewire_thread(
        want_444,
        want_hdr,
        expect_exact_dims,
+        cursor_id0_hides,
        ..
    } = opts;
    crate::pwinit::ensure_init();
@@ -985,7 +986,7 @@ pub fn pipewire_thread(
        yuv444: want_444,
        linear_nv12_failed: false,
        dbg_log_n: 0,
-        cursor: CursorState::default(),
+        cursor: CursorState::new(cursor_id0_hides),
        expect_dims: if expect_exact_dims {
            preferred.map(|(w, h, _)| (w, h))
        } else {
@@ -39,9 +39,23 @@ pub(super) struct CursorState {
    /// negotiated). Per-stream deliberately — a host serves many sessions per process, and a
    /// process-wide latch made the second session's triage read as "no meta".
    seen_meta: bool,
+    /// This stream's producer rewrites the cursor meta on EVERY buffer, so an `id == 0` meta is
+    /// an authoritative "pointer hidden / off this output" rather than a stale recycled region.
+    /// True for KWin virtual outputs; false for the stale-meta producers (Mutter) — see
+    /// [`note_cursor_id`].
+    id0_hides: bool,
 }

 impl CursorState {
+    /// The per-stream state, declaring which `id == 0` contract the producer follows
+    /// ([`Self::id0_hides`]).
+    pub(super) fn new(id0_hides: bool) -> CursorState {
+        CursorState {
+            id0_hides,
+            ..CursorState::default()
+        }
+    }
+
    /// A shareable overlay for the encode/forward paths, or `None` before the first bitmap
    /// arrived. A HIDDEN pointer still yields `Some` (with `visible: false`): the
    /// cursor-forward channel needs "known but hidden" — an app grabbed the pointer, the
@@ -79,6 +93,31 @@ pub(super) fn decode_bitmap_pixel(vfmt: u32, s: &[u8]) -> (u8, u8, u8, u8) {
    }
 }

+/// Apply one parsed `spa_meta_cursor.id` to the visibility state; returns whether the rest of the
+/// meta region (position, bitmap) is worth parsing.
+///
+/// Two producer contracts meet on `id == 0`. **KWin** rewrites the cursor meta on EVERY enqueued
+/// buffer, and writes id 0 whenever `Cursor::isOnOutput` says the pointer is not in this stream —
+/// which covers a globally hidden cursor AND a client null-cursor surface (empty cursor geometry
+/// intersects nothing). There id 0 is the authoritative hide, and honoring it is what lets a game
+/// or Big Picture hide the pointer mid-stream ([`CursorState::id0_hides`], set for KWin virtual
+/// outputs; without it the composited arrow outlived every hide — the 0.22.0 field report).
+/// **Mutter** only rewrites a buffer's meta region when the cursor changed, so recycled buffers
+/// between damage frames carry a stale id-0 meta — treating that as hidden flickered the cursor
+/// off between hovers (on-glass round 5). There the last-known state holds, and a pointer that
+/// really left/hid simply stops producing updates (the M3 hidden hint has no Mutter signal —
+/// Windows has its own CURSOR_SUPPRESSED source).
+fn note_cursor_id(cursor: &mut CursorState, id: u32) -> bool {
+    if id == 0 {
+        if cursor.id0_hides {
+            cursor.visible = false;
+        }
+        return false;
+    }
+    cursor.visible = true;
+    true
+}
+
 /// Update `cursor` from the newest buffer's `SPA_META_Cursor` (no-op when the buffer carries no
 /// cursor meta — producer doesn't support it, or the portal isn't in Metadata cursor mode).
 /// Called for EVERY dequeued buffer, before the stale-frame skip, so pointer-only movements
@@ -121,16 +160,9 @@ pub(super) fn update_cursor_meta(cursor: &mut CursorState, spa_buf: *mut spa::sy
            (*cur).bitmap_offset,
        )
    };
-    if id == 0 {
-        // SPA contract: id 0 = "no cursor information", NOT "cursor hidden". Mutter only
-        // REWRITES a buffer's meta region when the cursor changed, so recycled buffers
-        // between damage frames carry a stale id-0 meta — treating that as hidden flickered
-        // the cursor off between hovers (on-glass round 5). Keep the last-known state; a
-        // pointer that really left/hid simply stops producing updates. (The M3 hidden hint
-        // loses its Mutter signal — Windows has its own CURSOR_SUPPRESSED source.)
+    if !note_cursor_id(cursor, id) {
        return;
    }
-    cursor.visible = true;
    cursor.x = pos_x - hot_x;
    cursor.y = pos_y - hot_y;
    cursor.hot_x = hot_x;
@@ -367,9 +399,44 @@ mod tests {
            hot_x: 0,
            hot_y: 0,
            seen_meta: true,
+            id0_hides: false,
        }
    }

+    // ---- note_cursor_id: the two producer id-0 contracts --------------------------------------
+
+    #[test]
+    fn id_zero_hides_only_on_a_rewriting_producer() {
+        // KWin contract (`id0_hides`): id 0 is written fresh on every buffer, so it IS the hide —
+        // a game or Big Picture hiding the pointer must reach the stream.
+        let mut kwin = cursor(10, 10, 8, 8, (255, 255, 255), 255);
+        kwin.id0_hides = true;
+        assert!(!note_cursor_id(&mut kwin, 0), "id 0 parses no further");
+        let o = kwin.overlay().expect("bitmap stays cached across a hide");
+        assert!(!o.visible, "KWin id 0 must hide the overlay");
+        // The pointer coming back re-shows the SAME cached bitmap.
+        assert!(note_cursor_id(&mut kwin, 1));
+        assert!(kwin.overlay().expect("still cached").visible);
+
+        // Mutter contract: recycled buffers carry stale id-0 metas — the last-known state holds
+        // (honoring them flickered the cursor off between hovers, on-glass round 5).
+        let mut mutter = cursor(10, 10, 8, 8, (255, 255, 255), 255);
+        assert!(!note_cursor_id(&mut mutter, 0));
+        assert!(
+            mutter.overlay().expect("cached").visible,
+            "a stale-meta producer's id 0 must NOT hide"
+        );
+    }
+
+    #[test]
+    fn id_zero_before_any_bitmap_yields_no_overlay() {
+        // A KWin stream whose pointer was never on the output: hides arrive before any bitmap —
+        // `overlay()` must stay `None` (nothing to blend), not a phantom empty cursor.
+        let mut c = CursorState::new(true);
+        assert!(!note_cursor_id(&mut c, 0));
+        assert!(c.overlay().is_none());
+    }
+
    // ---- bitmap_extent: the guard whose absence SIGSEGVs uncatchably -------------------------

    #[test]
@@ -336,6 +336,7 @@ enum Ctl {
    Detach,
    Pin(Option<String>),
    KindOverride(GamepadPref),
+    Forwarding(bool),
    MenuMode(bool),
    MenuRumble(MenuPulse),
 }
@@ -482,6 +483,26 @@ impl GamepadService {
        let _ = self.ctl.send(Ctl::KindOverride(pref));
    }

+    /// Forward this device's controllers to the host at all ([`Settings::gamepad_forwarding`],
+    /// default on). Off is for a couch whose pad reaches the host another way — a USB
+    /// passthrough tool like VirtualHere, or a controller plugged into the host itself —
+    /// where forwarding as well would give the host two pads for one pair of hands.
+    ///
+    /// Off holds no slot open, so nothing is sent AND nothing is *grabbed*: no arrival, no
+    /// virtual pad host-side, and the hidraw node stays free for the passthrough tool to
+    /// bind (SDL's HIDAPI drivers take it at open — a held device cannot be bound away).
+    /// It follows that the escape chord, which only listens on forwarded pads, is not
+    /// available while off; the keyboard chord and the client's own UI still end a session.
+    ///
+    /// Menu navigation is untouched: the launcher still opens the active pad to drive its
+    /// UI, and a session — which supersedes menu mode whether it forwards or not — releases
+    /// it again, so the pad is free for the whole time a stream is up.
+    ///
+    /// [`Settings::gamepad_forwarding`]: crate::trust::Settings::gamepad_forwarding
+    pub fn set_forwarding(&self, on: bool) {
+        let _ = self.ctl.send(Ctl::Forwarding(on));
+    }
+
    pub fn attach(&self, connector: Arc<NativeClient>) {
        let _ = self.ctl.send(Ctl::Attach(connector));
    }
@@ -721,6 +742,10 @@ struct Worker {
    /// connected pads, so it survives restarts and disconnects. A pin forwards ONLY that pad
    /// (an explicit single-player choice); Automatic forwards every real controller.
    pinned: Option<String>,
+    /// Forward controllers to an attached session at all ([`GamepadService::set_forwarding`]).
+    /// Off makes [`Self::forwarded_ids`] empty, so a session opens no slot — the whole point
+    /// being that the hardware stays ungrabbed for a USB passthrough tool.
+    forwarding: bool,
    /// The user's explicit "controller type" setting ([`GamepadService::set_kind_override`]);
    /// `Auto` = per-pad detection. Applied at slot open to the kind DECLARED to the host, never
    /// to [`Slot::pref`] — the local feedback paths must keep reading the physical pad.
@@ -815,6 +840,11 @@ impl Worker {
    /// back to the single most-recent pad when only a Steam-virtual pad is present (the Deck
    /// game-mode case — otherwise its gyro/paddles/input would have nowhere to land).
    fn forwarded_ids(&self) -> Vec<u32> {
+        // Forwarding off: nothing is forwarded, so nothing is opened either — the device stays
+        // free for whatever route the user's controller actually takes to the host.
+        if !self.forwarding {
+            return Vec::new();
+        }
        if let Some(key) = &self.pinned {
            if let Some(id) = self
                .order
@@ -1243,10 +1273,16 @@ impl Worker {
                Ok(Ctl::Attach(c)) => {
                    self.attached = Some(c);
                    self.reset_chord(); // every session starts un-latched (Attach doesn't flush)
-                                        // The Valve HIDAPI drivers run only in-session (see set_valve_hidapi);
-                                        // enabling them re-enumerates a Deck's built-in pad with paddles/
-                                        // trackpads/gyro first-class — sync_open opens a slot per forwarded pad.
-                    set_valve_hidapi(true);
+
+                    // The Valve HIDAPI drivers run only in-session (see set_valve_hidapi);
+                    // enabling them re-enumerates a Deck's built-in pad with paddles/
+                    // trackpads/gyro first-class — sync_open opens a slot per forwarded pad.
+                    // Not with forwarding off: this session opens no slot, and the drivers'
+                    // mere enumeration both kills the Deck's trackpad-mouse and is the
+                    // opposite of leaving the hardware alone for a passthrough tool.
+                    if self.forwarding {
+                        set_valve_hidapi(true);
+                    }
                    self.sync_open();
                }
                Ok(Ctl::Detach) => {
@@ -1269,6 +1305,31 @@ impl Worker {
                    self.refresh_active();
                }
                Ok(Ctl::KindOverride(pref)) => self.kind_override = pref,
+                Ok(Ctl::Forwarding(on)) => {
+                    if self.forwarding == on {
+                        continue;
+                    }
+                    self.forwarding = on;
+                    self.reset_chord(); // no forwarded pad can be mid-chord across the flip
+
+                    // Applied live rather than at attach only, so a mid-session flip (an
+                    // in-stream settings screen) takes effect on the pad in your hands.
+                    //
+                    // The Valve HIDAPI drivers are an in-session-only thing (see
+                    // set_valve_hidapi), and forwarding off is — for their purpose — not in
+                    // session. Order matters and differs by direction: ON must enable them
+                    // BEFORE `sync_open`, or a Deck's built-in pad opens under its old
+                    // identity; OFF must disable them AFTER, so no slot outlives the driver
+                    // that opened it.
+                    let attached = self.attached.is_some();
+                    if on && attached {
+                        set_valve_hidapi(true);
+                    }
+                    self.sync_open();
+                    if !on && attached {
+                        set_valve_hidapi(false);
+                    }
+                }
                Ok(Ctl::MenuMode(on)) => {
                    self.menu_mode = on;
                    if on {
@@ -1608,6 +1669,7 @@ impl Worker {
            menu_open: None,
            order: Vec::new(),
            pinned: None,
+            forwarding: true,
            kind_override: GamepadPref::Auto,
            attached: None,
            escape_tx,
@@ -982,6 +982,10 @@ mod tests {
                height: 1440,
                bitrate_kbps: 55000,
                codec: "av1".into(),
+                present_priority: "smooth".into(),
+                smooth_buffer: 2,
+                vsync: false,
+                allow_vrr: false,
                ..Default::default()
            },
            clipboard: true,
@@ -74,9 +74,23 @@ pub struct SettingsOverlay {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub gamepad: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
+    pub gamepad_forwarding: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
    pub stats_verbosity: Option<StatsVerbosity>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fullscreen_on_stream: Option<bool>,
+    /// The presentation cluster — the keys the Apple client already writes into this
+    /// same catalog shape (`present_priority`/`smooth_buffer`/`vsync`/`allow_vrr`;
+    /// Android carries the first two). First-class here so a profile authored on any
+    /// client applies on all of them instead of riding `extra` unapplied.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub present_priority: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub smooth_buffer: Option<u8>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub vsync: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_vrr: Option<bool>,
    /// Overlay keys a newer client wrote and this one doesn't model — carried through a
    /// load→save round-trip untouched.
    #[serde(flatten)]
@@ -142,6 +156,9 @@ impl SettingsOverlay {
        if let Some(v) = &self.gamepad {
            s.gamepad = v.clone();
        }
+        if let Some(v) = self.gamepad_forwarding {
+            s.gamepad_forwarding = v;
+        }
        if let Some(v) = self.stats_verbosity {
            // Through the setter so the legacy `show_stats` bool stays coherent for
            // pre-tier binaries reading the same settings file.
@@ -150,6 +167,18 @@ impl SettingsOverlay {
        if let Some(v) = self.fullscreen_on_stream {
            s.fullscreen_on_stream = v;
        }
+        if let Some(v) = &self.present_priority {
+            s.present_priority = v.clone();
+        }
+        if let Some(v) = self.smooth_buffer {
+            s.smooth_buffer = v;
+        }
+        if let Some(v) = self.vsync {
+            s.vsync = v;
+        }
+        if let Some(v) = self.allow_vrr {
+            s.allow_vrr = v;
+        }
        s
    }

@@ -220,12 +249,27 @@ impl SettingsOverlay {
        if after.gamepad != before.gamepad {
            self.gamepad = Some(after.gamepad.clone());
        }
+        if after.gamepad_forwarding != before.gamepad_forwarding {
+            self.gamepad_forwarding = Some(after.gamepad_forwarding);
+        }
        if after.stats_verbosity() != before.stats_verbosity() {
            self.stats_verbosity = Some(after.stats_verbosity());
        }
        if after.fullscreen_on_stream != before.fullscreen_on_stream {
            self.fullscreen_on_stream = Some(after.fullscreen_on_stream);
        }
+        if after.present_priority != before.present_priority {
+            self.present_priority = Some(after.present_priority.clone());
+        }
+        if after.smooth_buffer != before.smooth_buffer {
+            self.smooth_buffer = Some(after.smooth_buffer);
+        }
+        if after.vsync != before.vsync {
+            self.vsync = Some(after.vsync);
+        }
+        if after.allow_vrr != before.allow_vrr {
+            self.allow_vrr = Some(after.allow_vrr);
+        }
    }

    /// Drop one override by its overlay field name, putting the row back to inheriting. The
@@ -257,8 +301,13 @@ impl SettingsOverlay {
            "invert_scroll" => self.invert_scroll = None,
            "inhibit_shortcuts" => self.inhibit_shortcuts = None,
            "gamepad" => self.gamepad = None,
+            "gamepad_forwarding" => self.gamepad_forwarding = None,
            "stats_verbosity" => self.stats_verbosity = None,
            "fullscreen_on_stream" => self.fullscreen_on_stream = None,
+            "present_priority" => self.present_priority = None,
+            "smooth_buffer" => self.smooth_buffer = None,
+            "vsync" => self.vsync = None,
+            "allow_vrr" => self.allow_vrr = None,
            _ => return false,
        }
        true
@@ -433,6 +482,10 @@ mod tests {
        assert_eq!((out.width, out.height), (1920, 1080));
        assert_eq!(out.bitrate_kbps, 20000);
        assert_eq!(out.codec, "hevc");
+        assert!(
+            out.gamepad_forwarding,
+            "default on, and an empty overlay leaves it alone"
+        );
        assert!(empty.is_empty());

        let overlay = SettingsOverlay {
@@ -452,9 +505,14 @@ mod tests {
            invert_scroll: Some(true),
            inhibit_shortcuts: Some(false),
            gamepad: Some("dualsense".into()),
+            gamepad_forwarding: Some(false),
            match_window: Some(true),
            fullscreen_on_stream: Some(false),
            stats_verbosity: Some(StatsVerbosity::Detailed),
+            present_priority: Some("smooth".into()),
+            smooth_buffer: Some(3),
+            vsync: Some(false),
+            allow_vrr: Some(false),
            ..Default::default()
        };
        assert!(!overlay.is_empty());
@@ -473,9 +531,14 @@ mod tests {
        assert!(out.invert_scroll);
        assert!(!out.inhibit_shortcuts);
        assert_eq!(out.gamepad, "dualsense");
+        assert!(!out.gamepad_forwarding);
        assert!(out.match_window);
        assert!(!out.fullscreen_on_stream);
        assert_eq!(out.stats_verbosity(), StatsVerbosity::Detailed);
+        assert_eq!(out.present_priority, "smooth");
+        assert_eq!(out.smooth_buffer, 3);
+        assert!(!out.vsync);
+        assert!(!out.allow_vrr);
        // The tier goes through the setter, so the legacy bool a pre-tier binary reads
        // stays coherent with it.
        assert!(out.show_stats);
@@ -573,6 +636,59 @@ mod tests {
        assert!(o.is_empty());
    }

+    /// The presentation cluster is first-class, not `extra` passengers: it applies,
+    /// absorbs, clears, and serialises under the exact keys the Apple client already
+    /// writes (`present_priority`/`smooth_buffer`/`vsync`/`allow_vrr`) — one catalog
+    /// has to round-trip through every platform, and a mismatched key would be carried
+    /// but never applied.
+    #[test]
+    fn presentation_cluster_is_first_class() {
+        let base = Settings::default();
+        let mut o = SettingsOverlay::default();
+        let before = o.apply(&base);
+        let mut after = before.clone();
+        after.present_priority = "smooth".into();
+        o.absorb(&before, &after);
+        let before = o.apply(&base);
+        let mut after = before.clone();
+        after.smooth_buffer = 1;
+        o.absorb(&before, &after);
+        assert_eq!(o.present_priority.as_deref(), Some("smooth"));
+        assert_eq!(o.smooth_buffer, Some(1));
+        assert!(
+            o.extra.is_empty(),
+            "modelled fields must never land in the passthrough"
+        );
+        let out = o.apply(&base);
+        assert_eq!(
+            out.present_priority(),
+            crate::trust::PresentPriority::Smooth { buffer: 1 }
+        );
+
+        // Serialised under the shared keys, and read back from a foreign client's file.
+        let text = serde_json::to_string(&o).unwrap();
+        assert!(text.contains("\"present_priority\":\"smooth\""), "{text}");
+        assert!(text.contains("\"smooth_buffer\":1"), "{text}");
+        let from_apple: SettingsOverlay = serde_json::from_str(
+            r#"{"present_priority":"latency","smooth_buffer":2,"vsync":true,"allow_vrr":false}"#,
+        )
+        .unwrap();
+        assert_eq!(from_apple.present_priority.as_deref(), Some("latency"));
+        assert_eq!(from_apple.smooth_buffer, Some(2));
+        assert_eq!(from_apple.vsync, Some(true));
+        assert_eq!(from_apple.allow_vrr, Some(false));
+        assert!(from_apple.extra.is_empty());
+
+        assert!(o.clear("present_priority"));
+        assert!(o.clear("smooth_buffer"));
+        assert_eq!(o.present_priority, None);
+        assert!(o.is_empty());
+        let mut vrr = from_apple;
+        assert!(vrr.clear("vsync"));
+        assert!(vrr.clear("allow_vrr"));
+        assert_eq!((vrr.vsync, vrr.allow_vrr), (None, None));
+    }
+
    /// `clear` is the explicit way back to inheriting, including the resolution tri-state.
    #[test]
    fn clear_drops_one_override() {
@@ -591,6 +707,29 @@ mod tests {
        assert!(!o.clear("no_such_field"));
    }

+    /// Controller forwarding defaults ON, so its interesting override is the FALSE one — and a
+    /// `false` that `apply` dropped would silently forward a pad the profile said not to.
+    /// `absorb` must record it, `clear` must undo it, and the serialized name both carry is the
+    /// one every client's reset button sends.
+    #[test]
+    fn gamepad_forwarding_overrides_off_and_resets_back() {
+        let base = Settings::default();
+        assert!(base.gamepad_forwarding, "the shipped default");
+
+        let mut o = SettingsOverlay::default();
+        let mut after = base.clone();
+        after.gamepad_forwarding = false;
+        o.absorb(&base, &after);
+        assert_eq!(o.gamepad_forwarding, Some(false));
+        assert!(!o.apply(&base).gamepad_forwarding);
+
+        assert!(o.clear("gamepad_forwarding"));
+        assert_eq!(o.gamepad_forwarding, None);
+        assert!(o.is_empty());
+        // Back to inheriting: the global's live value, not a remembered false.
+        assert!(o.apply(&base).gamepad_forwarding);
+    }
+
    /// Stats verbosity Off must survive `apply` — it is a legitimate override, and going
    /// through `set_stats_verbosity` keeps `show_stats` in sync in that direction too.
    #[test]
@@ -14,6 +14,7 @@ use anyhow::{anyhow, Context, Result};
 use punktfunk_core::client::NativeClient;
 use punktfunk_core::quic::endpoint;
 use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};

 pub fn config_dir() -> Result<PathBuf> {
@@ -787,6 +788,45 @@ impl MouseMode {
    }
 }

+/// Presentation intent — what the presenter optimizes for
+/// (design/desktop-presentation-rebuild.md; the Apple/Android clients' shared
+/// `present_priority`/`smooth_buffer` pair). Stored stringly in
+/// [`Settings::present_priority`] + [`Settings::smooth_buffer`]; resolved with
+/// [`PresentPriority::resolve`], whose rules match the Android reference
+/// (`decode/presenter.rs`): anything but an explicit `"smooth"` is latency, and a
+/// smooth buffer outside 1..=3 (including 0 = Automatic) becomes 2.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum PresentPriority {
+    /// Every frame presents the moment the display can take it; a network hiccup is an
+    /// occasional repeated or skipped frame. The default.
+    Latency,
+    /// A small frame buffer (1–3 frames) evens out network/decode jitter, at the
+    /// buffer's worth of added display latency.
+    Smooth { buffer: u8 },
+}
+
+impl PresentPriority {
+    /// The shared cross-client resolution rule — pure, so every embedder agrees on what
+    /// a foreign profile's values mean.
+    pub fn resolve(name: &str, buffer: u8) -> PresentPriority {
+        if name == "smooth" {
+            PresentPriority::Smooth {
+                buffer: if (1..=3).contains(&buffer) { buffer } else { 2 },
+            }
+        } else {
+            PresentPriority::Latency
+        }
+    }
+
+    /// Frames the smoothing store holds; `0` = newest-wins (the latency intent).
+    pub fn fifo_capacity(self) -> u8 {
+        match self {
+            PresentPriority::Latency => 0,
+            PresentPriority::Smooth { buffer } => buffer,
+        }
+    }
+}
+
 /// App settings, persisted as JSON. Stringly-typed gamepad/compositor prefs so the file
 /// stays readable; parsed with `*Pref::from_name` at connect time.
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
@@ -808,6 +848,21 @@ pub struct Settings {
    /// container `#[serde(default)]`.
    pub render_scale: f64,
    pub gamepad: String,
+    /// Forward this device's controllers to the host at all. Default ON — that was the
+    /// unconditional behaviour before this became a setting.
+    ///
+    /// Off is for the couch whose controller reaches the host by some *other* route: a USB
+    /// passthrough tool (VirtualHere and friends), or a pad simply plugged into the host
+    /// itself. Leaving forwarding on there gives the host two controllers for one pair of
+    /// hands, and games read both.
+    ///
+    /// It is deliberately stronger than "send no input": with it off the client never
+    /// *opens* the controller, and opening is what grabs the hardware (SDL's HIDAPI drivers
+    /// take the hidraw node) — a held device is one a passthrough tool cannot bind. Menu
+    /// navigation in the launcher still opens the active pad, and the session releases it;
+    /// see [`crate::gamepad::GamepadService::set_forwarding`].
+    #[serde(default = "default_true")]
+    pub gamepad_forwarding: bool,
    /// Stable identity (`vid:pid:name`, see `PadInfo::key`) of the physical controller
    /// forwarded as pad 0; empty = automatic (most recently connected). Applied to the
    /// gamepad service at startup so the choice survives restarts.
@@ -874,6 +929,32 @@ pub struct Settings {
    /// `default = true`: the Linux stores never carried this and always advertised.
    #[serde(default = "default_true")]
    pub hdr_enabled: bool,
+    /// Presentation intent: `"latency"` (default) or `"smooth"` — the Apple/Android
+    /// clients' shared `present_priority` profile key, resolved with
+    /// [`PresentPriority::resolve`] (via [`Settings::present_priority`]). Anything
+    /// unknown reads as latency, so a newer client's future value degrades safely.
+    #[serde(default = "default_present_priority")]
+    pub present_priority: String,
+    /// Smoothness buffer size in frames: `0` = Automatic (resolves to 2), else 1–3.
+    /// Only meaningful under `present_priority = "smooth"` (the shared `smooth_buffer`
+    /// key). Each buffered frame absorbs about one refresh of jitter and adds one
+    /// refresh of display latency.
+    #[serde(default)]
+    pub smooth_buffer: u8,
+    /// Tear-free presentation (default ON = today's behavior: MAILBOX, FIFO fallback).
+    /// Off asks for a tearing present mode (IMMEDIATE) for the lowest possible latch
+    /// latency — best-effort: platforms/drivers without tearing silently stay tear-free
+    /// and the active mode is visible in the detailed stats. The shared `vsync` profile
+    /// key; the desktop default differs from macOS's (`false` there) deliberately —
+    /// sync-off means something different on each platform, the key is the contract.
+    #[serde(default = "default_true")]
+    pub vsync: bool,
+    /// Let a variable-refresh display follow the stream cadence: prefers the present
+    /// mode that drives VRR panels directly when fullscreen. Inert on fixed-refresh
+    /// displays (detection is measured from on-glass timestamps, not queried). The
+    /// shared `allow_vrr` profile key. Default ON, like the Apple client.
+    #[serde(default = "default_true")]
+    pub allow_vrr: bool,
    /// Legacy on/off for the stats overlay — superseded by `stats_verbosity` but kept
    /// written in sync (`set_stats_verbosity`) so pre-tier binaries reading the same
    /// file keep working. `alias`: the pre-unification WinUI shell (≤ 0.8.4) persisted
@@ -925,6 +1006,14 @@ pub struct Settings {
    /// the user will be looking at. `0` = never stored → the 1280×720 default.
    pub last_window_w: u32,
    pub last_window_h: u32,
+    /// Settings keys this build doesn't model (a newer client's field), carried through a
+    /// load→save round-trip untouched — [`crate::profiles::SettingsOverlay`]'s `extra`
+    /// pattern extended to the globals. Without it, every whole-file writer of this store
+    /// (two shells, the console settings screen, the session's resize callback, Decky)
+    /// running as an OLDER binary silently drops what a newer one persisted. Empty on
+    /// every existing store, and an empty map serializes to nothing, so files don't churn.
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, serde_json::Value>,
 }

 fn default_codec() -> String {
@@ -939,6 +1028,10 @@ fn default_mouse_mode() -> String {
    "capture".into()
 }

+fn default_present_priority() -> String {
+    "latency".into()
+}
+
 fn default_true() -> bool {
    true
 }
@@ -970,6 +1063,12 @@ impl Settings {
        MouseMode::from_name(&self.mouse_mode)
    }

+    /// The presentation intent for this session (the resolved
+    /// `present_priority` × `smooth_buffer` pair).
+    pub fn present_priority(&self) -> PresentPriority {
+        PresentPriority::resolve(&self.present_priority, self.smooth_buffer)
+    }
+
    /// The `codec` setting as a `quic::CODEC_*` preference bit (`0` = auto).
    pub fn preferred_codec(&self) -> u8 {
        match self.codec.as_str() {
@@ -994,6 +1093,7 @@ impl Default for Settings {
            bitrate_kbps: 0,
            render_scale: 1.0,
            gamepad: "auto".into(),
+            gamepad_forwarding: true,
            forward_pad: String::new(),
            compositor: "auto".into(),
            touch_mode: "trackpad".into(),
@@ -1007,6 +1107,10 @@ impl Default for Settings {
            adapter: String::new(),
            enable_444: false,
            hdr_enabled: true,
+            present_priority: "latency".into(),
+            smooth_buffer: 0,
+            vsync: true,
+            allow_vrr: true,
            show_stats: true,
            stats_verbosity: None,
            fullscreen_on_stream: true,
@@ -1018,6 +1122,7 @@ impl Default for Settings {
            match_window: false,
            last_window_w: 0,
            last_window_h: 0,
+            extra: BTreeMap::new(),
        }
    }
 }
@@ -1144,6 +1249,43 @@ mod tests {
        }
    }

+    /// A settings file predating the presentation cluster loads with the shipped
+    /// defaults (latency intent, Automatic buffer, tear-free, VRR allowed), and the
+    /// resolution rules match the Apple/Android reference: anything but an explicit
+    /// `"smooth"` is latency, and a smooth buffer outside 1..=3 becomes 2.
+    #[test]
+    fn settings_presentation_defaults_and_resolution() {
+        let old = r#"{"width":1280,"height":720,"gamepad":"auto","compositor":"auto"}"#;
+        let s: Settings = serde_json::from_str(old).unwrap();
+        assert_eq!(s.present_priority, "latency");
+        assert_eq!(s.smooth_buffer, 0);
+        assert!(s.vsync);
+        assert!(s.allow_vrr);
+        assert_eq!(s.present_priority(), PresentPriority::Latency);
+
+        assert_eq!(
+            PresentPriority::resolve("smooth", 0),
+            PresentPriority::Smooth { buffer: 2 },
+            "Automatic resolves to 2"
+        );
+        assert_eq!(
+            PresentPriority::resolve("smooth", 3),
+            PresentPriority::Smooth { buffer: 3 }
+        );
+        assert_eq!(
+            PresentPriority::resolve("smooth", 9),
+            PresentPriority::Smooth { buffer: 2 },
+            "out-of-range pins to the Automatic resolution"
+        );
+        assert_eq!(
+            PresentPriority::resolve("balanced-from-the-future", 2),
+            PresentPriority::Latency,
+            "unknown intents degrade to latency"
+        );
+        assert_eq!(PresentPriority::Latency.fifo_capacity(), 0);
+        assert_eq!(PresentPriority::Smooth { buffer: 3 }.fifo_capacity(), 3);
+    }
+
    /// A pre-`forward_pad` settings file (≤ 0.5.0) loads with the pin on automatic.
    #[test]
    fn settings_forward_pad_defaults_empty() {
@@ -1192,6 +1334,28 @@ mod tests {
        assert!(s.echo_cancel);
    }

+    /// A key this build doesn't model (a newer client's setting) survives a load→save
+    /// round trip instead of being dropped by the next whole-file write — the same
+    /// contract `SettingsOverlay.extra` gives profiles. And when there are no unknown
+    /// keys, the flatten map adds nothing, so existing files don't churn.
+    #[test]
+    fn settings_unknown_keys_survive_round_trip() {
+        let newer = r#"{"width":1920,"height":1080,"frob_mode":"fancy","frob_level":3}"#;
+        let s: Settings = serde_json::from_str(newer).unwrap();
+        assert_eq!((s.width, s.height), (1920, 1080));
+        assert_eq!(
+            s.extra.get("frob_mode").and_then(|v| v.as_str()),
+            Some("fancy")
+        );
+        let out = serde_json::to_string(&s).unwrap();
+        assert!(out.contains(r#""frob_mode":"fancy""#), "{out}");
+        assert!(out.contains(r#""frob_level":3"#), "{out}");
+        // No unknown keys → no artifact of the passthrough field in the file.
+        let plain = serde_json::to_string(&Settings::default()).unwrap();
+        assert!(!plain.contains("extra"), "{plain}");
+        assert!(!plain.contains("frob"), "{plain}");
+    }
+
    /// Stats-tier resolution: a pre-tier store falls back to `show_stats` (off → Off,
    /// on/absent → Normal), an explicit tier wins, and setting a tier keeps the legacy
    /// bool in sync so pre-tier binaries reading the same file agree on off vs on.
@@ -26,9 +26,14 @@ enum RowId {
    Decoder,
    Hdr,
    Chroma444,
+    PresentPriority,
+    SmoothBuffer,
+    Vsync,
+    AllowVrr,
    Audio,
    Mic,
    EchoCancel,
+    PadForward,
    Pad,
    PadType,
    Touch,
@@ -46,7 +51,7 @@ enum RowId {
 // scroll/shortcut behavior, fullscreen-on-stream, auto-wake, the library toggle and echo
 // cancellation all were). Still deliberately smaller than the desktop dialogs — device
 // pickers (GPU/speaker/mic) and the profile catalog stay desktop-only.
-const ROWS: [RowId; 22] = [
+const ROWS: [RowId; 27] = [
    RowId::Resolution,
    RowId::Refresh,
    RowId::RenderScale,
@@ -56,9 +61,14 @@ const ROWS: [RowId; 22] = [
    RowId::Decoder,
    RowId::Hdr,
    RowId::Chroma444,
+    RowId::PresentPriority,
+    RowId::SmoothBuffer,
+    RowId::Vsync,
+    RowId::AllowVrr,
    RowId::Audio,
    RowId::Mic,
    RowId::EchoCancel,
+    RowId::PadForward,
    RowId::Pad,
    RowId::PadType,
    RowId::Touch,
@@ -117,6 +127,17 @@ const DECODERS: [(&str, &str); 4] = [
    ("software", "Software"),
 ];
 const AUDIO: [(u8, &str); 3] = [(2, "Stereo"), (6, "5.1"), (8, "7.1")];
+/// Presentation intent — the `present_priority` key shared with the Apple and Android
+/// clients, so one profile reads the same on every device.
+const PRESENT_PRIORITIES: [(&str, &str); 2] =
+    [("latency", "Lowest latency"), ("smooth", "Smoothness")];
+/// Smoothness buffer depth in frames; `0` = Automatic (resolves to 2).
+const SMOOTH_BUFFERS: [(u8, &str); 4] = [
+    (0, "Automatic"),
+    (1, "1 frame"),
+    (2, "2 frames"),
+    (3, "3 frames"),
+];
 const PAD_TYPES: [(&str, &str); 6] = [
    ("auto", "Automatic"),
    ("xbox360", "Xbox 360"),
@@ -222,9 +243,18 @@ impl SettingsScreen {

 fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
    let s = &ctx.settings;
-    // Echo cancellation only means anything while the mic streams — dimmed and inert while it
-    // doesn't, the same relationship the desktop shells draw with a greyed-out row.
-    let enabled = !matches!(id, RowId::EchoCancel) || s.mic_enabled;
+    // Several rows follow another: echo cancellation only means anything while the mic
+    // streams, the pad rows only while any controller is forwarded at all, and the
+    // smoothness buffer only while that intent is chosen. All go dim and inert otherwise
+    // — the same relationship the desktop shells draw by greying a row out (they hide the
+    // buffer row entirely; a fixed row list can't, and a row that vanished mid-list would
+    // move everything under the cursor).
+    let enabled = match id {
+        RowId::EchoCancel => s.mic_enabled,
+        RowId::Pad | RowId::PadType => s.gamepad_forwarding,
+        RowId::SmoothBuffer => s.present_priority == "smooth",
+        _ => true,
+    };
    let (header, label, value): (Option<&'static str>, &str, String) = match id {
        RowId::Resolution => (
            Some("Stream"),
@@ -279,6 +309,22 @@ fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
        RowId::Decoder => (None, "Decoder", label_for(&DECODERS, &s.decoder).into()),
        RowId::Hdr => (None, "10-bit HDR", on_off(s.hdr_enabled).into()),
        RowId::Chroma444 => (None, "Full chroma (4:4:4)", on_off(s.enable_444).into()),
+        RowId::PresentPriority => (
+            Some("Presentation"),
+            "Prioritize",
+            label_for(&PRESENT_PRIORITIES, &s.present_priority).into(),
+        ),
+        RowId::SmoothBuffer => (
+            None,
+            "Smoothness buffer",
+            SMOOTH_BUFFERS
+                .iter()
+                .find(|(v, _)| *v == s.smooth_buffer)
+                .map_or("Automatic", |(_, l)| l)
+                .into(),
+        ),
+        RowId::Vsync => (None, "V-Sync", on_off(s.vsync).into()),
+        RowId::AllowVrr => (None, "Follow variable refresh", on_off(s.allow_vrr).into()),
        RowId::Audio => (
            Some("Audio"),
            "Audio channels",
@@ -290,8 +336,13 @@ fn row_spec(id: RowId, ctx: &Ctx) -> RowSpec {
        ),
        RowId::Mic => (None, "Microphone", on_off(s.mic_enabled).into()),
        RowId::EchoCancel => (None, "Echo cancellation", on_off(s.echo_cancel).into()),
-        RowId::Pad => (
+        RowId::PadForward => (
            Some("Controller"),
+            "Forward controllers",
+            on_off(s.gamepad_forwarding).into(),
+        ),
+        RowId::Pad => (
+            None,
            "Use controller",
            if s.forward_pad.is_empty() {
                "Automatic".into()
@@ -368,6 +419,24 @@ fn detail(id: RowId) -> &'static str {
             Needs an NVIDIA host (NVENC) or the PyroWave codec — other encoders \
             stream 4:2:0 and the session falls back silently."
        }
+        RowId::PresentPriority => {
+            "Lowest latency shows each frame the moment the display can take it — a \
+             network hiccup becomes an occasional repeated or skipped frame. Smoothness \
+             buffers a little to even those out."
+        }
+        RowId::SmoothBuffer => {
+            "Frames held back before showing. Each one absorbs about a refresh of network \
+             hiccup and adds a refresh of delay. Automatic holds two."
+        }
+        RowId::Vsync => {
+            "Tear-free. Off removes the wait for the screen's refresh — the lowest \
+             possible delay, at the cost of visible tearing. Not every driver offers it; \
+             the stats overlay names the mode actually in use."
+        }
+        RowId::AllowVrr => {
+            "On a VRR screen, let the panel refresh in step with the stream instead of on \
+             a fixed cadence. Applies to fullscreen sessions; harmless on a fixed screen."
+        }
        RowId::Audio => "The speaker layout requested from the host.",
        RowId::Mic => {
            "Send this device's microphone to the host's virtual mic. \
@@ -377,6 +446,11 @@ fn detail(id: RowId) -> &'static str {
            "Stops the host's audio, playing from this device's speakers, being picked up \
             and sent back. Turn it off if your microphone already runs its own processing."
        }
+        RowId::PadForward => {
+            "Send controllers connected to this device to the host. Turn it off when your \
+             controller already reaches the host another way — USB passthrough such as \
+             VirtualHere, or a pad plugged into the host — so games don't see two of them."
+        }
        RowId::Pad => "Which pad is forwarded to the host, as player 1.",
        RowId::PadType => "The virtual pad the host creates — Automatic matches this controller.",
        RowId::Touch => {
@@ -463,6 +537,27 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
        RowId::Decoder => step_str(&DECODERS, &mut s.decoder, delta, wrap),
        RowId::Hdr => toggle(&mut s.hdr_enabled, delta, wrap),
        RowId::Chroma444 => toggle(&mut s.enable_444, delta, wrap),
+        RowId::PresentPriority => {
+            let cur = PRESENT_PRIORITIES
+                .iter()
+                .position(|(v, _)| *v == s.present_priority);
+            step_option(cur, PRESENT_PRIORITIES.len(), delta, wrap)
+                .map(|i| s.present_priority = PRESENT_PRIORITIES[i].0.to_string())
+        }
+        // Inert unless smoothness is chosen — a boundary thud, matching the dimmed row.
+        RowId::SmoothBuffer => {
+            if s.present_priority == "smooth" {
+                let cur = SMOOTH_BUFFERS
+                    .iter()
+                    .position(|(v, _)| *v == s.smooth_buffer);
+                step_option(cur, SMOOTH_BUFFERS.len(), delta, wrap)
+                    .map(|i| s.smooth_buffer = SMOOTH_BUFFERS[i].0)
+            } else {
+                None
+            }
+        }
+        RowId::Vsync => toggle(&mut s.vsync, delta, wrap),
+        RowId::AllowVrr => toggle(&mut s.allow_vrr, delta, wrap),
        RowId::Audio => {
            let cur = AUDIO.iter().position(|(v, _)| *v == s.audio_channels);
            step_option(cur, AUDIO.len(), delta, wrap).map(|i| s.audio_channels = AUDIO[i].0)
@@ -476,7 +571,11 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
                None
            }
        }
+        RowId::PadForward => toggle(&mut s.gamepad_forwarding, delta, wrap),
        RowId::Pad => {
+            if !s.gamepad_forwarding {
+                return false;
+            }
            // Automatic first, then every connected pad by stable key.
            let keys: Vec<String> = std::iter::once(String::new())
                .chain(ctx.pads.iter().map(|p| p.key.clone()))
@@ -484,7 +583,12 @@ fn adjust(id: RowId, delta: i32, wrap: bool, ctx: &mut Ctx) -> bool {
            let cur = keys.iter().position(|c| *c == s.forward_pad);
            step_option(cur, keys.len(), delta, wrap).map(|i| s.forward_pad = keys[i].clone())
        }
-        RowId::PadType => step_str(&PAD_TYPES, &mut s.gamepad, delta, wrap),
+        RowId::PadType => {
+            if !s.gamepad_forwarding {
+                return false;
+            }
+            step_str(&PAD_TYPES, &mut s.gamepad, delta, wrap)
+        }
        RowId::Touch => {
            let cur = TouchMode::ALL.iter().position(|m| *m == s.touch_mode());
            step_option(cur, TouchMode::ALL.len(), delta, wrap)
@@ -648,6 +752,45 @@ mod tests {
        assert!(ctx.settings.echo_cancel);
    }

+    /// The smoothness buffer follows the presentation intent, exactly as echo cancellation
+    /// follows the mic: dimmed and inert under Lowest latency (where holding frames means
+    /// nothing), live under Smoothness. The desktop shells hide the row instead; a fixed
+    /// row list dims it, because a row vanishing mid-list would shift everything under the
+    /// cursor.
+    #[test]
+    fn smoothness_buffer_follows_the_intent() {
+        let (mut settings, pads) = ctx_parts();
+        assert_eq!(settings.present_priority, "latency", "the shipped default");
+        let library = crate::library::LibraryShared::default();
+        let mut ctx = Ctx {
+            hosts: &[],
+            library: &library,
+            settings: &mut settings,
+            pads: &pads,
+            deck: false,
+            device_name: "t",
+            t: 0.0,
+        };
+        assert!(!row_spec(RowId::SmoothBuffer, &ctx).enabled);
+        assert!(
+            !adjust(RowId::SmoothBuffer, 1, false, &mut ctx),
+            "latency intent = thud"
+        );
+        assert_eq!(ctx.settings.smooth_buffer, 0, "and nothing was written");
+
+        // Stepping the intent to Smoothness brings the buffer row to life.
+        assert!(adjust(RowId::PresentPriority, 1, false, &mut ctx));
+        assert_eq!(ctx.settings.present_priority, "smooth");
+        assert!(row_spec(RowId::SmoothBuffer, &ctx).enabled);
+        assert!(adjust(RowId::SmoothBuffer, 1, false, &mut ctx));
+        assert_eq!(ctx.settings.smooth_buffer, 1);
+
+        // The intent wraps back and the row goes inert again.
+        assert!(adjust(RowId::PresentPriority, -1, false, &mut ctx));
+        assert_eq!(ctx.settings.present_priority, "latency");
+        assert!(!row_spec(RowId::SmoothBuffer, &ctx).enabled);
+    }
+
    #[test]
    fn touch_mode_steps_and_wraps() {
        let (mut settings, pads) = ctx_parts();
@@ -669,6 +669,11 @@ impl GamepadManager {
    /// Service every pad's FF protocol; `send(index, low, high)` is invoked for each pad whose
    /// mixed rumble level changed. Call frequently (games block in `EVIOCSFF` until answered).
    pub fn pump_rumble(&mut self, mut send: impl FnMut(u16, u16, u16)) {
+        // Finish any unplug whose removal frame only armed the grace — the producer sends that
+        // frame once, so without this the uinput node would outlive the controller. The swept
+        // mask is discarded because this manager keeps no per-index sibling state (the pads mix
+        // rumble internally); if that ever changes, consume it like the other two backends do.
+        self.slots.reap();
        for (i, pad) in self.slots.iter_mut() {
            if let Some((low, high)) = pad.pump_ff() {
                send(i as u16, low, high);
@@ -62,15 +62,30 @@ impl<P> PadSlots<P> {
        self.label
    }

-    /// Drop every allocated pad whose `active_mask` bit has stayed clear for [`SWEEP_GRACE`] (the
-    /// unplug sweep run on each state frame), logging each. Returns the swept indices as a bitmask
-    /// so the caller resets its per-index sibling state; an index another manager owns is `None`
-    /// here, so it is never swept. The grace is the devnode-churn debounce: a mask that glitches
-    /// clear for a few frames and returns re-arms nothing.
+    /// Fold one state frame's `active_mask` into the grace clocks, then drop whatever has run out
+    /// (see [`Self::reap`]). Returns the dropped indices as a bitmask so the caller resets its
+    /// per-index sibling state; an index another manager owns is `None` here, so it is never
+    /// touched. The grace is the devnode-churn debounce: a mask that glitches clear for a few
+    /// frames and returns re-arms nothing.
+    ///
+    /// A frame can only ARM the grace, never complete it — no time has passed at the instant the
+    /// clock starts. Since the producer emits exactly ONE frame per detach, [`Self::reap`] on the
+    /// manager's periodic pump is what actually finishes the unplug; a backend that only ever
+    /// called `sweep` would keep the detached pad alive for the rest of the session.
    pub fn sweep(&mut self, active_mask: u16) -> u16 {
        self.sweep_at(active_mask, Instant::now())
    }

+    /// Drop every allocated pad whose grace has run out, logging each — the half of the unplug
+    /// that needs no state frame. Returns the dropped indices as a bitmask, same as [`Self::sweep`].
+    ///
+    /// This can only ever *complete* an unplug some frame already started: it never arms a clock,
+    /// so however often it runs it cannot drop a pad whose `active_mask` bit never went clear.
+    /// That is what makes it safe to call from a hot pump loop.
+    pub fn reap(&mut self) -> u16 {
+        self.reap_at(Instant::now())
+    }
+
    /// Backdate every armed grace clock by [`SWEEP_GRACE`], so the NEXT sweep drops the pads
    /// whose bits are still clear — consumer tests (the managers') drive the debounce without
    /// wall-clock sleeps. Test-only: production code has no business expiring the grace.
@@ -81,26 +96,37 @@ impl<P> PadSlots<P> {
        }
    }

-    /// [`Self::sweep`] with an injectable clock (unit tests drive the grace window).
+    /// [`Self::sweep`] with an injectable clock (unit tests drive the grace window): arm or disarm
+    /// each slot's clock from the mask, then reap whatever has already run out.
    fn sweep_at(&mut self, active_mask: u16, now: Instant) -> u16 {
-        let mut swept = 0u16;
-        for (i, slot) in self.pads.iter_mut().enumerate() {
+        for i in 0..MAX_PADS {
            if active_mask & (1 << i) != 0 {
                self.inactive_since[i] = None; // active (again): a glitch never reaches the drop
+            } else if self.pads[i].is_some() && self.inactive_since[i].is_none() {
+                self.inactive_since[i] = Some(now); // newly inactive — start the grace
+            }
+        }
+        self.reap_at(now)
+    }
+
+    /// [`Self::reap`] with an injectable clock. Deliberately arms nothing — it only ever reads
+    /// `inactive_since` and clears it, so a pad whose bit never went clear has no clock to run out
+    /// and cannot be dropped here.
+    fn reap_at(&mut self, now: Instant) -> u16 {
+        let mut swept = 0u16;
+        for i in 0..MAX_PADS {
+            let Some(since) = self.inactive_since[i] else {
+                continue; // active, or never went clear — nothing to complete
+            };
+            if self.pads[i].is_none() {
+                self.inactive_since[i] = None; // the slot went away by some other route
                continue;
            }
-            if slot.is_none() {
-                continue;
-            }
-            match self.inactive_since[i] {
-                None => self.inactive_since[i] = Some(now), // newly inactive — start the grace
-                Some(since) if now.duration_since(since) >= SWEEP_GRACE => {
-                    tracing::info!(index = i, "controller unplugged ({})", self.label);
-                    *slot = None;
-                    self.inactive_since[i] = None;
-                    swept |= 1 << i;
-                }
-                Some(_) => {} // inside the grace — hold
+            if now.duration_since(since) >= SWEEP_GRACE {
+                tracing::info!(index = i, "controller unplugged ({})", self.label);
+                self.pads[i] = None;
+                self.inactive_since[i] = None;
+                swept |= 1 << i;
            }
        }
        swept
@@ -161,6 +187,56 @@ mod tests {
        PadSlots::new("Test", "test pad", "")
    }

+    #[test]
+    fn a_single_frame_plus_a_reap_completes_the_unplug() {
+        // The shape production actually produces: ONE cleared-mask frame, then time, then a reap
+        // with no further frame. Before the arm/reap split the pad survived here forever.
+        let mut s = slots();
+        assert!(s.ensure(2, |i| Ok(i as u32)));
+        assert_eq!(
+            s.sweep(0b0),
+            0,
+            "a frame arms the grace but cannot itself drop"
+        );
+        assert!(s.get(2).is_some());
+        s.expire_grace();
+        assert_eq!(s.reap(), 1 << 2, "the reap did not complete the unplug");
+        assert!(s.get(2).is_none());
+        assert_eq!(s.reap(), 0, "nothing left to reap");
+    }
+
+    #[test]
+    fn reap_never_drops_a_pad_no_frame_ever_deactivated() {
+        // Reaping COMPLETES an unplug; it must never invent one. A pad whose bit never went clear
+        // has no armed clock, so any number of reaps — even with the clock backdated — leaves it.
+        let mut s = slots();
+        assert!(s.ensure(0, |i| Ok(i as u32)));
+        for _ in 0..10 {
+            assert_eq!(s.reap(), 0);
+            s.expire_grace();
+        }
+        assert!(
+            s.get(0).is_some(),
+            "reap dropped a pad that never went inactive"
+        );
+    }
+
+    #[test]
+    fn a_glitch_that_returns_inside_the_grace_never_drops_the_pad() {
+        // The anti-flap guarantee, now that reaps are frequent: a client mask that blips clear and
+        // comes back must not churn a PnP devnode.
+        let mut s = slots();
+        assert!(s.ensure(0, |i| Ok(i as u32)));
+        assert_eq!(s.sweep(0b0), 0); // bit clears — arms only
+        for _ in 0..5 {
+            assert_eq!(s.reap(), 0, "dropped a pad inside its grace");
+        }
+        assert_eq!(s.sweep(0b1), 0); // the bit returns — disarms
+        s.expire_grace();
+        assert_eq!(s.reap(), 0, "a returned bit must leave nothing armed");
+        assert!(s.get(0).is_some());
+    }
+
    #[test]
    fn ensure_creates_once_and_reports_freshness() {
        let mut s = slots();
@@ -217,13 +217,10 @@ impl<B: PadProto> UhidManager<B> {
                if idx >= MAX_PADS {
                    return;
                }
-                // Unplugs: drop any allocated pad whose mask bit cleared, resetting its state.
+                // Unplugs: arm the grace for any pad whose mask bit cleared (the drop itself lands
+                // on a later `pump` tick — this frame is the only one the producer sends).
                let swept = self.slots.sweep(f.active_mask);
-                for i in 0..MAX_PADS {
-                    if swept & (1 << i) != 0 {
-                        self.reset_pad(i);
-                    }
-                }
+                self.reset_swept(swept);
                if f.active_mask & (1 << idx) == 0 {
                    return; // this event WAS the unplug
                }
@@ -282,6 +279,12 @@ impl<B: PadProto> UhidManager<B> {
        mut hidout: impl FnMut(HidOutput),
    ) {
        let now = Instant::now();
+        // Finish any unplug whose removal frame only armed the grace. The producer emits that
+        // frame exactly once, so without this a detached pad — the single-pad session being the
+        // common case — would never be destroyed. Runs BEFORE the loop so a reaped index is
+        // already gone for `get_mut` here and for `heartbeat`'s `get` later in the same tick.
+        let swept = self.slots.reap();
+        self.reset_swept(swept);
        for i in 0..MAX_PADS {
            let Some(pad) = self.slots.get_mut(i) else {
                continue;
@@ -360,6 +363,18 @@ impl<B: PadProto> UhidManager<B> {
        }
    }

+    /// Reset the sibling state of every index a sweep or reap just dropped. Both halves of the
+    /// unplug land here, so a pad torn down on the pump tick clears exactly what one torn down on
+    /// a state frame would — in particular `hidout_dedup`, which has no watchdog to re-arm it and
+    /// would otherwise swallow an identical lightbar/trigger re-assert after a re-plug.
+    fn reset_swept(&mut self, swept: u16) {
+        for i in 0..MAX_PADS {
+            if swept & (1 << i) != 0 {
+                self.reset_pad(i);
+            }
+        }
+    }
+
    /// Reset one pad's sibling state (on create and unplug) so the first frame/feedback after a
    /// (re)connect starts from scratch and is always forwarded.
    fn reset_pad(&mut self, idx: usize) {
@@ -494,18 +509,36 @@ mod tests {
    }

    #[test]
-    fn removal_frame_never_recreates_the_pad_it_swept() {
+    fn one_removal_frame_plus_a_pump_tick_completes_the_unplug() {
+        // The producer emits the cleared-mask frame exactly ONCE — `native/input.rs` guards it on
+        // the bit still being set — so the teardown has to finish on the periodic pump. The
+        // previous version of this test hand-fed a SECOND removal frame, which is what let the
+        // never-reaped pad hide: with one frame and no pump, the device outlived the session.
        let mut m = mgr();
        m.handle(&frame(1, 0b10, 0));
        assert!(m.slots.get(1).is_some());
-        // Bit 1 cleared: the first sweep only ARMS the devnode-churn grace — the pad holds (a
-        // mask glitch must not flap PnP devices; see pad_slots::SWEEP_GRACE).
+        // The one removal frame: arms the devnode-churn grace, drops nothing.
        m.handle(&frame(1, 0b00, 0));
        assert!(m.slots.get(1).is_some(), "inside the grace — not yet swept");
-        // Grace elapsed: the frame IS pad 1's removal — sweep, then early-return (no ensure).
+        // A tick inside the grace must NOT flap the devnode (pad_slots::SWEEP_GRACE).
+        m.pump(|_, _, _| {}, |_| {});
+        assert!(
+            m.slots.get(1).is_some(),
+            "a tick inside the grace dropped it"
+        );
+        // Grace elapsed: the next tick completes the unplug, with no further frame.
        m.slots.expire_grace();
+        m.pump(|_, _, _| {}, |_| {});
+        assert!(
+            m.slots.get(1).is_none(),
+            "the pump tick never completed the unplug"
+        );
+        // …and a further cleared-mask frame must not resurrect it (the arm branch early-returns).
        m.handle(&frame(1, 0b00, 0));
-        assert!(m.slots.get(1).is_none());
+        assert!(
+            m.slots.get(1).is_none(),
+            "a cleared-mask frame recreated the pad"
+        );
    }

    #[test]
@@ -551,10 +584,15 @@ mod tests {
        assert_eq!(collect(&mut m), vec![(0, 100, 0)]); // first value forwards
        assert_eq!(collect(&mut m), vec![]); // exact repeat deduped
        assert_eq!(collect(&mut m), vec![(0, 7, 7)]); // change forwards
-                                                      // Unplug + recreate re-arms the dedup: the same level forwards again.
-        m.handle(&frame(0, 0b0, 0)); // arms the sweep grace
+                                                      // Unplug + recreate re-arms the dedup: the same level forwards again. The unplug completes
+                                                      // on a PUMP tick, not on a second frame — that is all production ever sends.
+        m.handle(&frame(0, 0b0, 0)); // the one removal frame — arms the grace
        m.slots.expire_grace();
-        m.handle(&frame(0, 0b0, 0)); // grace elapsed — actually swept
+        assert_eq!(collect(&mut m), vec![]); // this tick reaps; nothing queued to forward
+        assert!(
+            m.slots.get(0).is_none(),
+            "the pump tick completed the unplug"
+        );
        m.handle(&frame(0, 0b1, 0));
        *m.backend.feedback.borrow_mut() = vec![rumble((7, 7))];
        assert_eq!(collect(&mut m), vec![(0, 7, 7)]);
@@ -819,46 +819,77 @@ impl DriverAttach {

    /// One-shot WARN with everything the host can find out about WHY the driver isn't attached:
    /// driver-store presence, the devnode's PnP status/problem code, and where to look next.
+    ///
+    /// Runs on its own thread and returns immediately. The caller is the session's pad service
+    /// thread — the one feeding input and rumble — and everything below is slow: the driver-store
+    /// check waits up to [`INVENTORY_WAIT`] for a `pnputil` enumeration that can take tens of
+    /// seconds, and the devnode lookup is a synchronous PnP call. Blocking there stalled input for
+    /// up to two seconds *per unattached pad* (the wait is a deadline, not a one-off: while the
+    /// enumeration is still outstanding every pad pays it again), at exactly the moment a session
+    /// is already going wrong. Diagnostics must never be able to hurt the thing they diagnose.
+    ///
+    /// Off the hot path the wait also stops being a compromise — it can afford to be patient and
+    /// report what it actually found rather than "still enumerating".
    fn diagnose(&self) {
-        let store = match driver_store_has(self.inf) {
-            Some(true) => "driver package present in the driver store",
-            Some(false) => {
-                "driver package NOT in the driver store — run: punktfunk-host.exe driver install --gamepad"
-            }
-            None => "driver store could not be queried (pnputil failed or still enumerating)",
-        };
-        let devnode = match &self.instance_id {
-            Some(id) => devnode_status_line(id),
-            None => {
-                "no per-session devnode (SwDeviceCreate failed earlier — see the warning above)"
-                    .to_string()
-            }
-        };
-        tracing::warn!(
-            driver = self.driver,
-            shm = %self.shm_name,
-            grace_secs = ATTACH_GRACE.as_secs(),
-            store,
-            devnode = %devnode,
-            driver_log = self.driver_log,
-            "gamepad driver has not attached to the shared section — the virtual pad exists but no \
-             driver is serving it (games will not see it); an old (pre-sealed-channel) driver also \
-             reads as not-attached: update with punktfunk-host.exe driver install --gamepad \
-             (driver_log is only written by debug driver builds, or with the PFXUSB_DEBUG_LOG / \
-             PFGAMEPAD_DEBUG_LOG / PFMOUSE_DEBUG_LOG system env var set + the device restarted)"
-        );
+        let (driver, inf, driver_log) = (self.driver, self.inf, self.driver_log);
+        let shm_name = self.shm_name.clone();
+        let instance_id = self.instance_id.clone();
+        std::thread::Builder::new()
+            .name("pf-driver-diagnose".into())
+            .spawn(move || diagnose_blocking(driver, inf, driver_log, &shm_name, instance_id))
+            .ok();
    }
 }

-/// How long [`driver_store_inventory`] lets the caller wait for the background pnputil query
-/// before reporting without it — [`observe`] runs on the pad service thread, which must keep
-/// draining pad slots even when the driver store is wedged.
-const INVENTORY_WAIT: Duration = Duration::from_secs(2);
+/// The body of [`DriverAttach::diagnose`], on its own thread. Split out rather than inlined into
+/// the closure so the blocking calls stay visible as blocking.
+fn diagnose_blocking(
+    driver: &'static str,
+    inf: &'static str,
+    driver_log: &'static str,
+    shm_name: &str,
+    instance_id: Option<String>,
+) {
+    let store = match driver_store_has(inf) {
+        Some(true) => "driver package present in the driver store",
+        Some(false) => {
+            "driver package NOT in the driver store — run: punktfunk-host.exe driver install --gamepad"
+        }
+        None => "driver store could not be queried (pnputil failed or still enumerating)",
+    };
+    let devnode = match &instance_id {
+        Some(id) => devnode_status_line(id),
+        None => "no per-session devnode (SwDeviceCreate failed earlier — see the warning above)"
+            .to_string(),
+    };
+    tracing::warn!(
+        driver,
+        shm = %shm_name,
+        grace_secs = ATTACH_GRACE.as_secs(),
+        store,
+        devnode = %devnode,
+        driver_log,
+        "gamepad driver has not attached to the shared section — the virtual pad exists but no \
+         driver is serving it (games will not see it); an old (pre-sealed-channel) driver also \
+         reads as not-attached: update with punktfunk-host.exe driver install --gamepad \
+         (driver_log is only written by debug driver builds, or with the PFXUSB_DEBUG_LOG / \
+         PFGAMEPAD_DEBUG_LOG / PFMOUSE_DEBUG_LOG system env var set + the device restarted)"
+    );
+}
+
+/// How long [`driver_store_inventory`] waits for the background pnputil query before reporting
+/// without it. Only [`diagnose_blocking`] waits, and that has a thread to itself, so this is
+/// generous: pnputil routinely takes longer than a couple of seconds on a busy driver store, and
+/// the old two-second budget — chosen to limit the damage while this ran on the pad service thread
+/// — meant the diagnosis usually gave up and printed "still enumerating", which is the one answer
+/// that helps nobody. Nothing waits on this thread, so patience costs only a late log line.
+const INVENTORY_WAIT: Duration = Duration::from_secs(30);

 /// Driver-store inventory (`pnputil /enum-drivers`), lower-cased, fetched once per process — only
 /// consulted on the failure path, so the subprocess cost never hits a healthy session. The query
 /// runs on its OWN thread: pnputil can block for tens of seconds on a busy/wedged driver store,
-/// and the caller is the pad service thread. `None` = not available yet (query still running) or
+/// and this keeps one wedged query from being re-run per pad. `None` = not available yet (query
+/// still running past [`INVENTORY_WAIT`]) or
 /// failed; a query that outlives [`INVENTORY_WAIT`] still lands in the cache for later reports.
 fn driver_store_inventory() -> Option<&'static str> {
    static INV: OnceLock<String> = OnceLock::new();
@@ -318,14 +318,10 @@ impl GamepadManager {
                if idx >= MAX_PADS {
                    return;
                }
-                // Unplugs: drop any allocated pad whose mask bit cleared.
+                // Unplugs: arm the grace for any pad whose mask bit cleared (the drop itself lands
+                // on a later `pump_rumble` tick — this frame is the only one the producer sends).
                let swept = self.slots.sweep(f.active_mask);
-                for i in 0..MAX_PADS {
-                    if swept & (1 << i) != 0 {
-                        self.last_rumble[i] = (0, 0);
-                        self.last_active[i] = Instant::now();
-                    }
-                }
+                self.reset_swept(swept);
                if f.active_mask & (1 << idx) == 0 {
                    return;
                }
@@ -345,10 +341,25 @@ impl GamepadManager {
        }
    }

+    /// Reset the sibling state of every index a sweep or reap just dropped, so both halves of the
+    /// unplug clear the same things.
+    fn reset_swept(&mut self, swept: u16) {
+        for i in 0..MAX_PADS {
+            if swept & (1 << i) != 0 {
+                self.last_rumble[i] = (0, 0);
+                self.last_active[i] = Instant::now();
+            }
+        }
+    }
+
    /// Relay any changed rumble level to the client. XUSB motors are 0..255; the wire carries
    /// 0..65535, so scale by 257. `large` (low-frequency) → the datagram's `low`, `small`
    /// (high-frequency) → `high` — matching the other backends.
    pub fn pump_rumble(&mut self, mut send: impl FnMut(u16, u16, u16)) {
+        // Finish any unplug whose removal frame only armed the grace — the producer sends that
+        // frame once, so without this the XUSB devnode would outlive the controller.
+        let swept = self.slots.reap();
+        self.reset_swept(swept);
        for (i, pad) in self.slots.iter_mut() {
            if let Some((large, small)) = pad.service() {
                // The game drove the pad this poll (SET_STATE bumped the seq) — refresh the
@@ -52,6 +52,8 @@ pub mod keymap_sdl;
 #[cfg(any(target_os = "linux", windows))]
 pub mod overlay;
 #[cfg(any(target_os = "linux", windows))]
+mod present_pace;
+#[cfg(any(target_os = "linux", windows))]
 mod run;
 #[cfg(any(target_os = "linux", windows))]
 pub mod touch;
@@ -0,0 +1,751 @@
+//! The presentation intent engine (design/desktop-presentation-rebuild.md WP2): the
+//! store, clock, and gate the run loop composes into the two intents.
+//!
+//! * [`FrameStore`] — newest-wins slot (latency) or smoothing FIFO with preroll
+//!   (smoothness), ported from the Apple `FrameStore` / Android `presenter.rs` so all
+//!   three clients agree on what the intents mean.
+//! * [`LatchClock`] — the panel latch grid, learned from `VK_KHR_present_wait` on-glass
+//!   stamps (measured, never queried — the Android refresh-rate lie and VRR both punish
+//!   trusting a reported rate). Without present-wait it degrades to a grid rooted at the
+//!   last submit on the mode's refresh period.
+//! * [`PresentGate`] — the FIFO glass budget: one undisplayed present in flight, so the
+//!   swapchain's own queue can never become a standing queue (+1 refresh per slot,
+//!   forever — the law every bounded-FIFO pacing rediscovered on Apple). MAILBOX cannot
+//!   queue and never needs it.
+//!
+//! Everything here is pure state + arithmetic on `CLOCK_REALTIME` ns (the
+//! `pf_client_core::session::now_ns` domain the on-glass stamps live in); the run loop
+//! owns all clocks and Vulkan calls, which is what keeps this testable.
+
+use std::collections::VecDeque;
+
+/// Stale-present force-open: an undisplayed present older than this is presumed lost
+/// (occluded window, wedged compositor) and the gate opens anyway, counted as `forced`
+/// — reads 0 on healthy systems. The Apple/Android presenters use the same 100 ms.
+const STALE_REOPEN_NS: u64 = 100_000_000;
+
+/// The adaptive slot-pick margin's ceiling and step (Android's measured values: start
+/// at 0 — a fixed lead was pure display tax on the reference device — and widen only
+/// when measured misses demand it).
+pub(crate) const MARGIN_STEP_NS: u64 = 500_000;
+pub(crate) const MARGIN_MAX_NS: u64 = 2_500_000;
+
+/// The decoded-frame store between the wake channel and the present call.
+///
+/// `capacity == 0` = newest-wins (latency intent): `submit` replaces, `take` clears.
+/// `capacity 1..=3` = smoothing FIFO: preroll-to-capacity, drop-oldest on overflow,
+/// an underflow after preroll re-arms the preroll (the previous frame persists on
+/// glass — a repeat by omission) while headroom rebuilds.
+pub(crate) struct FrameStore<T> {
+    capacity: usize,
+    frames: VecDeque<T>,
+    prerolled: bool,
+    /// Newest-wins displacements (normal operation under latency, not a fault signal).
+    replaced: u32,
+    /// FIFO drop-oldest evictions — the Apple debug line's `qDrop`.
+    overflow_drops: u32,
+    /// FIFO dry-after-preroll events — `qDry`.
+    underflows: u32,
+}
+
+impl<T> FrameStore<T> {
+    pub(crate) fn new(capacity: usize) -> FrameStore<T> {
+        FrameStore {
+            capacity,
+            frames: VecDeque::with_capacity(capacity.max(1) + 1),
+            prerolled: false,
+            replaced: 0,
+            overflow_drops: 0,
+            underflows: 0,
+        }
+    }
+
+    pub(crate) fn is_smoothing(&self) -> bool {
+        self.capacity > 0
+    }
+
+    pub(crate) fn is_empty(&self) -> bool {
+        self.frames.is_empty()
+    }
+
+    pub(crate) fn submit(&mut self, f: T) {
+        if self.capacity == 0 {
+            if self.frames.pop_front().is_some() {
+                self.replaced += 1;
+            }
+            self.frames.push_back(f);
+        } else {
+            self.frames.push_back(f);
+            // Drop the OLDEST past capacity: bounded added latency, the newest keeps
+            // flowing. Also trims a transient capacity+1 a put_back left behind.
+            while self.frames.len() > self.capacity {
+                self.frames.pop_front();
+                self.overflow_drops += 1;
+            }
+        }
+    }
+
+    pub(crate) fn take(&mut self) -> Option<T> {
+        if self.capacity == 0 {
+            return self.frames.pop_front();
+        }
+        if !self.prerolled {
+            // Preroll gate: without it a steady stream drains every frame on arrival
+            // and jitter headroom never builds (the Apple store's lesson).
+            if self.frames.len() < self.capacity {
+                return None;
+            }
+            self.prerolled = true;
+        }
+        match self.frames.pop_front() {
+            Some(f) => Some(f),
+            None => {
+                self.underflows += 1;
+                self.prerolled = false;
+                None
+            }
+        }
+    }
+
+    /// A frame taken but not presented (gate closed, present failed before consuming
+    /// it). Newest-wins reinserts only into an empty slot — a fresher decode wins;
+    /// FIFO puts it back at the front (it is the oldest).
+    pub(crate) fn put_back(&mut self, f: T) {
+        if self.capacity == 0 {
+            if self.frames.is_empty() {
+                self.frames.push_back(f);
+            }
+        } else {
+            self.frames.push_front(f);
+        }
+    }
+
+    /// Collapse to newest-wins for the rest of the stream (PyroWave: its plane-ring
+    /// retirement accounting assumes the depth-2 newest-wins hand-off, and its all-intra
+    /// frames make buffering pointless anyway).
+    ///
+    /// Gated with its only caller: the power-user build (`--no-default-features`, which
+    /// the Windows ARM64 leg ships) has no PyroWave decode path, and an ungated helper
+    /// is dead code there.
+    #[cfg(feature = "pyrowave")]
+    pub(crate) fn force_latency(&mut self) {
+        if self.capacity == 0 {
+            return;
+        }
+        self.capacity = 0;
+        self.prerolled = false;
+        while self.frames.len() > 1 {
+            self.frames.pop_front();
+        }
+    }
+
+    /// Drain the window's counters: `(replaced, overflow_drops, underflows)`.
+    pub(crate) fn take_counters(&mut self) -> (u32, u32, u32) {
+        let c = (self.replaced, self.overflow_drops, self.underflows);
+        self.replaced = 0;
+        self.overflow_drops = 0;
+        self.underflows = 0;
+        c
+    }
+}
+
+/// The panel latch grid: a recent on-glass instant + the latch period, extrapolated
+/// forward for slot targeting.
+///
+/// The period learner is the SHARED [`punktfunk_core::phase::PanelGrid`], not a local
+/// rule. An earlier version of this clock capped the learned period at the display
+/// mode's refresh, on the reasoning that a stream running below panel rate spaces its
+/// presents at k×period and the cap stops a 30 fps stream claiming a 30 Hz panel. That
+/// cap is the same defect the Android presenter shipped in 0.23.0: the seed is only what
+/// the *mode* claims, and when the real panel is slower (a refused mode switch, a
+/// compositor running its own rate) a downward-only learner pins a grid that never
+/// arrives, for the whole session, with no way back. `PanelGrid` moves both ways —
+/// narrowing at once, widening only after eight consecutive agreeing observations and
+/// then to the narrowest of them.
+///
+/// What is fed to it is still the window's MIN spacing: within one window that resists
+/// the k×period inflation the old cap was aimed at, while the streak requirement means a
+/// genuinely slower panel is still discovered. Same grid the host-facing `LatchGrid`
+/// publish reads, so the phase-lock report and the local scheduler cannot disagree.
+pub(crate) struct LatchClock {
+    anchor_ns: u64,
+    /// The previous stamp, kept ACROSS calls. The run loop drains present-wait samples
+    /// every pass, so a "batch" is very often a single stamp — computing spacings only
+    /// within a batch (`windows(2)`) observed nothing at all on glass, and the learner
+    /// silently ran on its seed forever.
+    last_ns: u64,
+    /// Narrowest spacing seen since the last handoff to the grid, and how many have
+    /// accumulated. The grid is fed the MIN of a run rather than every spacing: our
+    /// observations are the spacing of OUR presents, which is k×period whenever the
+    /// stream runs below panel rate, and the min over a run is the best available
+    /// estimate of the true grid step.
+    pending_min_ns: u64,
+    pending_count: u32,
+    grid: punktfunk_core::phase::PanelGrid,
+    fallback_period_ns: u64,
+}
+
+/// Spacings per handoff to [`punktfunk_core::phase::PanelGrid`]. Small enough that a real
+/// mode change is picked up in well under a second at any sane frame rate.
+const GRID_OBSERVE_EVERY: u32 = 16;
+
+impl LatchClock {
+    pub(crate) fn new(refresh_hz: u32) -> LatchClock {
+        LatchClock {
+            anchor_ns: 0,
+            last_ns: 0,
+            pending_min_ns: 0,
+            pending_count: 0,
+            grid: punktfunk_core::phase::PanelGrid::seeded(refresh_hz as i32),
+            fallback_period_ns: 1_000_000_000 / u64::from(refresh_hz.max(1)),
+        }
+    }
+
+    /// Fold on-glass stamps (ascending). Spacings are measured against the previous
+    /// stamp whatever the batching, so the loop's one-sample-per-pass drain still feeds
+    /// the learner.
+    pub(crate) fn note_batch(&mut self, stamps: &[u64]) {
+        for &s in stamps {
+            if self.last_ns != 0 && s > self.last_ns {
+                let d = s - self.last_ns;
+                // < 1 ms apart = a queued pair, not a grid step.
+                if d > 1_000_000 {
+                    self.pending_min_ns = if self.pending_min_ns == 0 {
+                        d
+                    } else {
+                        self.pending_min_ns.min(d)
+                    };
+                    self.pending_count += 1;
+                    if self.pending_count >= GRID_OBSERVE_EVERY {
+                        self.grid.observe(self.pending_min_ns as i64);
+                        self.pending_min_ns = 0;
+                        self.pending_count = 0;
+                    }
+                }
+            }
+            self.last_ns = s;
+        }
+        if let Some(&last) = stamps.last() {
+            self.anchor_ns = last;
+        }
+    }
+
+    pub(crate) fn period_ns(&self) -> u64 {
+        let learned = self.grid.period_ns();
+        if learned > 0 {
+            learned as u64
+        } else {
+            self.fallback_period_ns
+        }
+    }
+
+    pub(crate) fn anchor_ns(&self) -> u64 {
+        self.anchor_ns
+    }
+
+    /// The first predicted latch strictly after `after_ns` (`anchor + k·period`). With
+    /// no anchor yet: one period out — callers get a usable, if unanchored, deadline.
+    pub(crate) fn next_slot_after(&self, after_ns: u64) -> u64 {
+        let p = self.period_ns();
+        if self.anchor_ns == 0 || after_ns < self.anchor_ns {
+            return after_ns.saturating_add(p);
+        }
+        let k = (after_ns - self.anchor_ns) / p + 1;
+        self.anchor_ns + k * p
+    }
+}
+
+/// Whether the panel is refreshing on a fixed grid or following our cadence.
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
+pub(crate) enum Cadence {
+    /// Not enough evidence yet — say nothing rather than guess.
+    #[default]
+    Unknown,
+    /// On-glass instants land on multiples of the panel period: a fixed-refresh panel.
+    Fixed,
+    /// On-glass instants track our present spacing instead: variable refresh is live.
+    Variable,
+}
+
+impl Cadence {
+    pub(crate) fn label(self) -> &'static str {
+        match self {
+            Cadence::Unknown => "",
+            Cadence::Fixed => "no",
+            Cadence::Variable => "yes",
+        }
+    }
+}
+
+/// Is variable refresh actually live? **Measured, never queried** — no portable query
+/// exists (SDL exposes none, Wayland does not report adaptive-sync state, and Windows
+/// surfaces nothing through Vulkan), and the platforms that *do* answer have been caught
+/// lying before (Android reports a game-uid's down-rated refresh as the panel's).
+///
+/// The discriminator is quantization. On a fixed-refresh panel every on-glass instant
+/// lands on the vblank grid, so the spacing between consecutive presents is always
+/// ~k×period for whole k — even when the stream runs slower than the panel, where it just
+/// picks a larger k. Under real VRR the panel refreshes *when we present*, so the spacing
+/// follows our own cadence and sits wherever it likes relative to the grid.
+///
+/// So: fold each delta to its distance from the nearest multiple of the period. Tight
+/// against the grid ⇒ Fixed; consistently off it ⇒ Variable. A stream running exactly at
+/// panel rate is indistinguishable either way (both give delta ≈ period), which is
+/// harmless — at that rate VRR has nothing to do.
+pub(crate) struct CadenceProbe {
+    /// Off-grid distances as a fraction of the period, in thousandths.
+    off_grid_milli: Vec<u32>,
+    /// Previous stamp, kept across calls for the same reason [`LatchClock`] does: the
+    /// live drain hands over one sample at a time.
+    last_ns: u64,
+    /// The last round's raw reading and how many rounds have agreed — a verdict is only
+    /// published once [`CADENCE_STABLE_ROUNDS`] agree.
+    candidate: Cadence,
+    agree_rounds: u8,
+    verdict: Cadence,
+}
+
+/// Enough deltas to distinguish jitter from a real off-grid cadence.
+const CADENCE_MIN_SAMPLES: usize = 24;
+/// Consecutive agreeing rounds before a verdict is published.
+///
+/// ⭐ On glass (GNOME/Wayland, .21, 2026-08-02) the raw per-round verdict FLAPPED between
+/// runs with VRR provably disabled. The cause is structural, not a tuning miss: under a
+/// compositor our on-glass stamp is the compositor's release, so anything that perturbs
+/// delivery — an occluded or unfocused surface being throttled, a distressed pipeline
+/// missing vblanks — smears the spacings exactly the way real VRR does. This probe can
+/// therefore only ever say "presents are not landing on the grid", so it demands
+/// agreement across rounds and refuses evidence from a distressed window (see
+/// [`CadenceProbe::note`]'s `healthy` flag) before claiming anything.
+const CADENCE_STABLE_ROUNDS: u8 = 2;
+/// Median off-grid distance under this fraction of a period reads as grid-locked. Present
+/// stamps carry real measurement jitter (the wait returns, then we read the clock), so
+/// this is deliberately loose — the two regimes differ by far more than this in practice.
+const CADENCE_FIXED_MILLI: u32 = 150;
+
+impl CadenceProbe {
+    pub(crate) fn new() -> CadenceProbe {
+        CadenceProbe {
+            off_grid_milli: Vec::with_capacity(64),
+            last_ns: 0,
+            candidate: Cadence::Unknown,
+            agree_rounds: 0,
+            verdict: Cadence::Unknown,
+        }
+    }
+
+    /// Fold on-glass stamps against the learned panel period. Spacings are measured
+    /// against the previous stamp whatever the batching.
+    ///
+    /// `healthy` is the caller's statement that this window's presents were flowing
+    /// normally (no stale force-opens). A distressed pipeline smears spacings for reasons
+    /// that have nothing to do with the panel, so its evidence is dropped — the timeline
+    /// continuity is still advanced, it simply does not count as a sample.
+    pub(crate) fn note(&mut self, stamps: &[u64], period_ns: u64, healthy: bool) {
+        if period_ns == 0 || !healthy {
+            self.last_ns = stamps.last().copied().unwrap_or(self.last_ns);
+            return;
+        }
+        for &s in stamps {
+            let prev = std::mem::replace(&mut self.last_ns, s);
+            if prev == 0 || s <= prev {
+                continue;
+            }
+            let delta = s - prev;
+            let rem = delta % period_ns;
+            // Distance to the NEAREST multiple, so a delta just under k×period reads as
+            // close to the grid rather than a whole period away from k-1.
+            let off = rem.min(period_ns - rem);
+            self.off_grid_milli
+                .push((off.saturating_mul(1000) / period_ns) as u32);
+            // A round closes on the SAMPLE count, inside the loop — not once per call.
+            // Evaluating per call would make the verdict depend on how the caller happens
+            // to batch its stamps (one big batch = one round, forever short of the
+            // agreement requirement), and the live drain and the tests batch differently.
+            self.close_round_if_ready();
+        }
+    }
+
+    /// Publish a verdict once a round's worth of spacings agree with the previous round.
+    fn close_round_if_ready(&mut self) {
+        if self.off_grid_milli.len() >= CADENCE_MIN_SAMPLES {
+            self.off_grid_milli.sort_unstable();
+            let median = self.off_grid_milli[self.off_grid_milli.len() / 2];
+            let round = if median <= CADENCE_FIXED_MILLI {
+                Cadence::Fixed
+            } else {
+                Cadence::Variable
+            };
+            if round == self.candidate {
+                self.agree_rounds = self.agree_rounds.saturating_add(1);
+            } else {
+                self.candidate = round;
+                self.agree_rounds = 1;
+            }
+            if self.agree_rounds >= CADENCE_STABLE_ROUNDS {
+                self.verdict = round;
+            }
+            self.off_grid_milli.clear();
+        }
+    }
+
+    pub(crate) fn verdict(&self) -> Cadence {
+        self.verdict
+    }
+
+    /// A mode switch / display change invalidates the evidence.
+    pub(crate) fn reset(&mut self) {
+        self.off_grid_milli.clear();
+        self.last_ns = 0;
+        self.candidate = Cadence::Unknown;
+        self.agree_rounds = 0;
+        self.verdict = Cadence::Unknown;
+    }
+}
+
+/// The FIFO glass budget: at most one undisplayed present in flight, measured by the
+/// present-wait waiter's outstanding count. Never consulted under MAILBOX/IMMEDIATE
+/// (they cannot queue) or without present-wait (nothing to count with — behavior is
+/// then exactly the shipped arrival pacing).
+#[derive(Default)]
+pub(crate) struct PresentGate {
+    /// Submit stamp of the newest tracked present; 0 = none yet.
+    last_present_ns: u64,
+    gated: u32,
+    forced: u32,
+}
+
+impl PresentGate {
+    /// May a new present go out? Open when nothing undisplayed is in flight; a stale
+    /// in-flight present (occlusion, wedged compositor) force-opens after 100 ms so the
+    /// stream survives, counted as `forced`.
+    pub(crate) fn open(&mut self, outstanding: usize, now_ns: u64) -> bool {
+        if outstanding == 0 {
+            return true;
+        }
+        if self.last_present_ns != 0
+            && now_ns.saturating_sub(self.last_present_ns) > STALE_REOPEN_NS
+        {
+            self.forced += 1;
+            return true;
+        }
+        self.gated += 1;
+        false
+    }
+
+    pub(crate) fn note_present(&mut self, now_ns: u64) {
+        self.last_present_ns = now_ns;
+    }
+
+    /// Drain the window's counters: `(gated, forced)`.
+    pub(crate) fn take_counters(&mut self) -> (u32, u32) {
+        let c = (self.gated, self.forced);
+        self.gated = 0;
+        self.forced = 0;
+        c
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Newest-wins: submit replaces, take clears, put_back only fills an empty slot.
+    #[test]
+    fn newest_wins_replaces_and_putback_never_clobbers() {
+        let mut s: FrameStore<u32> = FrameStore::new(0);
+        assert!(!s.is_smoothing());
+        assert_eq!(s.take(), None);
+        s.submit(1);
+        s.submit(2);
+        s.submit(3);
+        assert_eq!(s.take(), Some(3), "only the newest survives");
+        assert_eq!(s.take(), None);
+        // A taken-but-unpresented frame returns — unless a fresher one arrived.
+        s.submit(4);
+        let f = s.take().unwrap();
+        s.put_back(f);
+        assert_eq!(s.take(), Some(4));
+        let f = s.take();
+        assert_eq!(f, None);
+        s.submit(5);
+        let f = s.take().unwrap();
+        s.submit(6);
+        s.put_back(f); // 6 arrived while 5 was out — 6 wins
+        assert_eq!(s.take(), Some(6));
+        assert_eq!(
+            s.take_counters(),
+            (2, 0, 0),
+            "two displacements, no fifo counters"
+        );
+    }
+
+    /// FIFO: preroll to capacity, drop-oldest overflow, underflow re-arms the preroll.
+    #[test]
+    fn fifo_prerolls_overflows_oldest_and_rearms_on_dry() {
+        let mut s: FrameStore<u32> = FrameStore::new(2);
+        assert!(s.is_smoothing());
+        s.submit(1);
+        assert_eq!(s.take(), None, "prerolling: below capacity, nothing vends");
+        s.submit(2);
+        assert_eq!(s.take(), Some(1), "preroll reached — FIFO order");
+        assert_eq!(
+            s.take(),
+            Some(2),
+            "once prerolled the buffer drains normally"
+        );
+        // Dry after preroll = one underflow, preroll re-arms.
+        assert_eq!(s.take(), None);
+        s.submit(3);
+        assert_eq!(s.take(), None, "re-armed preroll holds again");
+        s.submit(4);
+        assert_eq!(s.take(), Some(3));
+        // Overflow drops the OLDEST: [4] → [4,5] → 6 evicts 4 → 7 evicts 5.
+        s.submit(5);
+        s.submit(6);
+        s.submit(7);
+        assert_eq!(s.take(), Some(6));
+        assert_eq!(s.take(), Some(7));
+        let (replaced, drops, dry) = s.take_counters();
+        assert_eq!(replaced, 0);
+        assert_eq!(drops, 2, "6 evicted 4, 7 evicted 5");
+        assert_eq!(dry, 1);
+    }
+
+    /// put_back under FIFO goes to the FRONT (it is the oldest), and the transient
+    /// capacity+1 is trimmed by the next submit.
+    #[test]
+    fn fifo_putback_restores_order() {
+        let mut s: FrameStore<u32> = FrameStore::new(2);
+        s.submit(1);
+        s.submit(2);
+        let f = s.take().unwrap();
+        s.put_back(f);
+        assert_eq!(s.take(), Some(1), "the put-back frame is still first");
+    }
+
+    /// force_latency collapses a smoothing store to a newest-wins slot mid-stream.
+    #[cfg(feature = "pyrowave")]
+    #[test]
+    fn force_latency_collapses_to_one_slot() {
+        let mut s: FrameStore<u32> = FrameStore::new(3);
+        s.submit(1);
+        s.submit(2);
+        s.submit(3);
+        s.force_latency();
+        assert!(!s.is_smoothing());
+        assert_eq!(s.take(), Some(3), "only the newest survives the collapse");
+        s.submit(4);
+        s.submit(5);
+        assert_eq!(s.take(), Some(5));
+    }
+
+    /// The clock learns the min positive spacing (capped at the mode refresh), anchors
+    /// on the newest stamp, and extrapolates the next slot; sub-ms pairs (a queued
+    /// double-present) never become the period.
+    #[test]
+    fn latch_clock_learns_and_extrapolates() {
+        const P: u64 = 16_666_666; // 60 Hz
+        let mut c = LatchClock::new(60);
+        assert_eq!(c.period_ns(), P, "fallback = the mode refresh");
+        // No anchor: a usable deadline one period out.
+        assert_eq!(c.next_slot_after(1_000), 1_000 + P);
+
+        c.note_batch(&[1_000_000_000, 1_000_000_000 + P, 1_000_000_000 + 2 * P]);
+        assert_eq!(c.period_ns(), P);
+        assert_eq!(c.anchor_ns(), 1_000_000_000 + 2 * P);
+        let next = c.next_slot_after(c.anchor_ns());
+        assert_eq!(next, 1_000_000_000 + 3 * P);
+        // Mid-slot query lands on the same boundary; a later one steps whole periods.
+        assert_eq!(c.next_slot_after(next - 1), next);
+        assert_eq!(c.next_slot_after(next), next + P);
+
+        // A queued pair (< 1 ms apart) must not poison the period.
+        c.note_batch(&[2_000_000_000, 2_000_000_500]);
+        assert_eq!(c.period_ns(), P);
+        assert_eq!(c.anchor_ns(), 2_000_000_500, "the anchor still advances");
+
+        // A stream presenting every OTHER refresh spaces its glass stamps at 2×P. One
+        // such window must NOT move the grid — the shared learner needs a streak before
+        // it will widen, which is what keeps a briefly-slow stream from claiming a slow
+        // panel while still allowing a genuinely slower display to be discovered.
+        c.note_batch(&[3_000_000_000, 3_000_000_000 + 2 * P]);
+        assert_eq!(c.period_ns(), P, "one wide window is not a slower panel");
+
+        // A single stamp re-anchors without touching the period.
+        c.note_batch(&[5_000_000_000]);
+        assert_eq!(c.anchor_ns(), 5_000_000_000);
+        assert_eq!(c.period_ns(), P);
+
+        // A faster panel learns its own finer grid.
+        let mut fast = LatchClock::new(120);
+        fast.note_batch(&[1_000_000_000, 1_008_333_333]);
+        assert_eq!(fast.period_ns(), 8_333_333);
+    }
+
+    /// ⭐ The live loop drains present-wait samples EVERY pass, so stamps arrive one at a
+    /// time. Measuring spacings only within a batch meant the learner observed nothing on
+    /// glass and silently ran on its seed (found on .21, 2026-08-02: `period_us` read back
+    /// exactly the 60 Hz fallback while the panel really was 60 Hz — correct by luck, and
+    /// wrong the moment the mode lies).
+    #[test]
+    fn latch_clock_learns_from_one_sample_at_a_time() {
+        const REAL: u64 = 16_666_666;
+        let mut c = LatchClock::new(120); // seeded too fast, as a refused mode switch would
+        let mut t = 1_000_000_000u64;
+        for _ in 0..(GRID_OBSERVE_EVERY * 8 + 8) {
+            t += REAL;
+            c.note_batch(&[t]); // ONE stamp per call — the live shape
+        }
+        assert_eq!(
+            c.period_ns(),
+            REAL,
+            "single-stamp batches must still feed the grid learner"
+        );
+        assert_eq!(c.anchor_ns(), t);
+    }
+
+    /// The mode's refresh is a CLAIM, not a measurement — a refused mode switch or a
+    /// compositor running its own rate leaves the seed too fast. The old downward-only
+    /// cap pinned that wrong grid for the session (the Android 0.23.0 defect); the
+    /// shared learner climbs back out once the evidence is consistent.
+    #[test]
+    fn latch_clock_recovers_from_a_seed_faster_than_the_real_panel() {
+        const REAL: u64 = 16_666_666; // the panel is really 60 Hz…
+        let mut c = LatchClock::new(120); // …but the mode claimed 120
+        assert_eq!(c.period_ns(), 8_333_333, "seeded from the claim");
+
+        // Consistent 60 Hz evidence. The grid is fed the MIN of every
+        // GRID_OBSERVE_EVERY spacings, and PanelGrid widens only after 8 agreeing
+        // observations, so a real widen needs 8 × GRID_OBSERVE_EVERY spacings — the
+        // deliberate cost of not letting one slow patch redefine the panel.
+        let mut t = 1_000_000_000u64;
+        for _ in 0..(GRID_OBSERVE_EVERY * 8 + GRID_OBSERVE_EVERY) {
+            t += REAL;
+            c.note_batch(&[t]);
+        }
+        assert_eq!(
+            c.period_ns(),
+            REAL,
+            "a sustained slower grid is adopted instead of aimed past forever"
+        );
+    }
+
+    /// The VRR discriminator: presents landing on the vblank grid read Fixed, presents
+    /// landing wherever our own cadence puts them read Variable — including the case that
+    /// matters most, a stream SLOWER than the panel, where a fixed panel still quantizes
+    /// to a larger whole multiple.
+    #[test]
+    fn cadence_probe_separates_grid_locked_from_variable() {
+        const P: u64 = 8_333_333; // 120 Hz
+                                  // Enough spacings for CADENCE_STABLE_ROUNDS full rounds: a verdict is published
+                                  // only once consecutive rounds agree (on glass a single round FLAPPED).
+        const ROUNDS: u64 = (CADENCE_MIN_SAMPLES as u64) * (CADENCE_STABLE_ROUNDS as u64) + 4;
+
+        // Fixed panel, stream at panel rate: every delta is exactly one period.
+        let mut probe = CadenceProbe::new();
+        assert_eq!(probe.verdict(), Cadence::Unknown, "no evidence yet");
+        let stamps: Vec<u64> = (0..ROUNDS).map(|i| 1_000_000_000 + i * P).collect();
+        probe.note(&stamps, P, true);
+        assert_eq!(probe.verdict(), Cadence::Fixed);
+
+        // Fixed panel, stream at HALF panel rate: deltas are 2×P — still grid-locked.
+        let mut probe = CadenceProbe::new();
+        let stamps: Vec<u64> = (0..ROUNDS).map(|i| 1_000_000_000 + i * 2 * P).collect();
+        probe.note(&stamps, P, true);
+        assert_eq!(
+            probe.verdict(),
+            Cadence::Fixed,
+            "a slower stream on a fixed panel picks a larger k, it does not leave the grid"
+        );
+
+        // Fixed panel with realistic measurement jitter (±0.5 ms on an 8.3 ms period)
+        // must not read as variable.
+        let mut probe = CadenceProbe::new();
+        let jitter = [0i64, 300_000, -250_000, 120_000, -400_000, 80_000];
+        let stamps: Vec<u64> = (0..ROUNDS as usize)
+            .map(|i| (1_000_000_000 + i as i64 * P as i64 + jitter[i % jitter.len()]) as u64)
+            .collect();
+        probe.note(&stamps, P, true);
+        assert_eq!(probe.verdict(), Cadence::Fixed, "jitter is not VRR");
+
+        // VRR live: a 100 fps stream on a 120 Hz-max panel. 10 ms is not a multiple of
+        // 8.33 ms, so every present sits off the grid.
+        let mut probe = CadenceProbe::new();
+        let stamps: Vec<u64> = (0..ROUNDS)
+            .map(|i| 1_000_000_000 + i * 10_000_000)
+            .collect();
+        probe.note(&stamps, P, true);
+        assert_eq!(probe.verdict(), Cadence::Variable);
+
+        // A display change throws the evidence away rather than carrying a stale verdict.
+        probe.reset();
+        assert_eq!(probe.verdict(), Cadence::Unknown);
+
+        // Below the sample floor nothing is claimed.
+        let mut probe = CadenceProbe::new();
+        probe.note(&[1_000_000_000, 1_010_000_000, 1_020_000_000], P, true);
+        assert_eq!(probe.verdict(), Cadence::Unknown);
+
+        // ⭐ THE SHAPE THE LIVE LOOP ACTUALLY PRODUCES: the run loop drains present-wait
+        // samples every pass, so stamps arrive ONE AT A TIME. Measuring spacings only
+        // within a batch observed nothing at all on glass — `vrr` stayed Unknown and the
+        // latch clock ran on its seed forever. Found on .21, 2026-08-02.
+        let mut probe = CadenceProbe::new();
+        for i in 0..ROUNDS {
+            probe.note(&[1_000_000_000 + i * 10_000_000], P, true); // 100 fps, off a 120 Hz grid
+        }
+        assert_eq!(
+            probe.verdict(),
+            Cadence::Variable,
+            "one-sample batches must still yield spacings"
+        );
+
+        // A period we never learned can't discriminate anything.
+        let mut probe = CadenceProbe::new();
+        let stamps: Vec<u64> = (0..ROUNDS)
+            .map(|i| 1_000_000_000 + i * 10_000_000)
+            .collect();
+        probe.note(&stamps, 0, true);
+        assert_eq!(probe.verdict(), Cadence::Unknown);
+    }
+
+    /// ⭐ Batching must not change the verdict. The same spacings delivered as one big
+    /// batch, or one stamp at a time, must reach the same conclusion — the live loop
+    /// drains one at a time while tests hand over vectors, and an evaluation keyed to
+    /// call boundaries silently made the two disagree.
+    #[test]
+    fn cadence_verdict_is_independent_of_batching() {
+        const P: u64 = 8_333_333;
+        let n = (CADENCE_MIN_SAMPLES as u64) * (CADENCE_STABLE_ROUNDS as u64) + 4;
+
+        let stamps: Vec<u64> = (0..n).map(|i| 1_000_000_000 + i * P).collect();
+        let mut bulk = CadenceProbe::new();
+        bulk.note(&stamps, P, true);
+
+        let mut drip = CadenceProbe::new();
+        for s in &stamps {
+            drip.note(&[*s], P, true);
+        }
+
+        assert_eq!(bulk.verdict(), Cadence::Fixed);
+        assert_eq!(drip.verdict(), bulk.verdict(), "batching must not matter");
+    }
+
+    /// Gate: open at zero outstanding, closed at one, force-open past the stale bound.
+    #[test]
+    fn gate_budgets_one_undisplayed_present() {
+        let mut g = PresentGate::default();
+        let t0 = 1_000_000_000u64;
+        assert!(g.open(0, t0));
+        g.note_present(t0);
+        assert!(!g.open(1, t0 + 8_000_000), "one in flight — hold");
+        assert!(
+            g.open(1, t0 + STALE_REOPEN_NS + 1),
+            "stale in-flight present force-opens"
+        );
+        let (gated, forced) = g.take_counters();
+        assert_eq!((gated, forced), (1, 1));
+        assert_eq!(g.take_counters(), (0, 0), "counters drain");
+    }
+}
@@ -18,12 +18,15 @@

 use crate::input::{Capture, FingerPhase};
 use crate::overlay::{FrameCtx, Overlay, OverlayAction, OverlayFrame, SessionPhase};
+use crate::present_pace::{
+    Cadence, CadenceProbe, FrameStore, LatchClock, PresentGate, MARGIN_MAX_NS, MARGIN_STEP_NS,
+};
 use crate::touch::Abs;
 use crate::vk::{FrameInput, Presenter};
 use anyhow::{Context as _, Result};
 use pf_client_core::gamepad::GamepadService;
 use pf_client_core::session::{self, SessionEvent, SessionHandle, SessionParams, Stats};
-use pf_client_core::trust::{MouseMode, StatsVerbosity, TouchMode};
+use pf_client_core::trust::{MouseMode, PresentPriority, StatsVerbosity, TouchMode};
 use pf_client_core::video::VulkanDecodeDevice;
 use pf_client_core::video::{DecodedFrame, DecodedImage};
 use punktfunk_core::client::NativeClient;
@@ -63,6 +66,20 @@ pub struct SessionOpts {
    /// work profile that streams on a second screen and still Alt-Tabs here. Never applies
    /// under the `desktop` mouse model, which is something you Alt-Tab *away* from.
    pub inhibit_shortcuts: bool,
+    /// Presentation intent ([`Settings::present_priority`] resolved): `Latency` keeps the
+    /// shipped arrival pacing (newest-wins, present the moment a frame can go out);
+    /// `Smooth { buffer }` runs the smoothing FIFO drained one frame per latch slot
+    /// (design/desktop-presentation-rebuild.md). `PUNKTFUNK_PRESENTER=arrival` overrides
+    /// the whole engine back to the legacy drain for field A/B without a rebuild.
+    pub present_priority: PresentPriority,
+    /// Tear-free presentation ([`Settings::vsync`], default on). Off asks for a tearing
+    /// present mode for the lowest possible latch — best-effort, and the mode that
+    /// actually took is named in the stats line.
+    pub vsync: bool,
+    /// Let a variable-refresh display follow the stream cadence ([`Settings::allow_vrr`],
+    /// default on) — prefers the present mode that drives VRR panels directly when the
+    /// session starts fullscreen.
+    pub allow_vrr: bool,
    /// Emit the `{"ready":true}` stdout line after the first presented frame.
    pub json_status: bool,
    /// Called once on `Connected` with the host's fingerprint (trust persistence is the
@@ -213,8 +230,47 @@ struct StreamState {
    // capture→displayed (host-clock corrected) p50+p95, display = decoded→displayed p50.
    win_e2e_us: Vec<u64>,
    win_disp_us: Vec<u64>,
+    /// The display stage's two halves (present-timing sessions only): decoded→submit and
+    /// submit→on-glass. See [`PresentedWindow::pace_ms`].
+    win_pace_us: Vec<u64>,
+    win_latch_us: Vec<u64>,
    win_start: Instant,
    presented: PresentedWindow,
+    /// The intent engine (design/desktop-presentation-rebuild.md WP2): the decoded-frame
+    /// store between the wake channel and the present call — a newest-wins slot under
+    /// the latency intent (behaviorally the shipped drain), the smoothing FIFO under
+    /// smoothness. NOTE: a smoothing store holds decoder-pool frames (Vulkan-Video
+    /// AVFrames) up to `buffer` deep on top of the depth-2 wake channels — within pool
+    /// headroom for 1..=3, but any deeper store must revisit pool sizing.
+    store: FrameStore<DecodedFrame>,
+    /// The panel latch grid (present-wait glass stamps; submit-anchored fallback) — the
+    /// smoothness slot clock, and the values published to the host-facing `latch_grid`.
+    clock: LatchClock,
+    /// The FIFO glass budget (one undisplayed present in flight) — inert off FIFO modes
+    /// or without present timing.
+    gate: PresentGate,
+    /// Is variable refresh actually live? Measured from the same on-glass stamps (no
+    /// portable query exists) — see [`CadenceProbe`].
+    cadence: CadenceProbe,
+    /// The DISPLAY MODE's refresh period — the vblank grid presents quantize to when
+    /// VRR is off, and so the cadence probe's reference. Deliberately not the learned
+    /// period (see the probe's call site).
+    mode_period_ns: u64,
+    /// The latch slot the last smoothness present served (one present per slot); 0 =
+    /// none yet.
+    last_target_ns: u64,
+    /// Smoothness slot-pick margin: starts 0 (a fixed lead is pure display tax —
+    /// measured on Android), widens +500 µs per >2-miss window toward 2.5 ms.
+    margin_ns: u64,
+    /// This window's latch misses (a present that reached glass > 1.5 latch periods
+    /// after submit) — the adaptive margin's error signal.
+    win_misses: u32,
+    /// This window's peak undisplayed-presents-in-flight (present timing only).
+    win_out_max: usize,
+    /// One-shot log latch: smoothness was requested but a PyroWave stream collapsed the
+    /// store to latency (its plane-ring retirement assumes the newest-wins hand-off).
+    #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+    pyro_latency_forced: bool,
    // Hardware-path health: a failure streak (or a device with no import support at
    // all) demotes the decoder to software via the shared flag — once per session.
    dmabuf_demoted: bool,
@@ -279,6 +335,8 @@ impl StreamState {
        params: SessionParams,
        force_software: Arc<AtomicBool>,
        wake: sdl3::event::EventSender,
+        priority: PresentPriority,
+        native_refresh_hz: u32,
    ) -> StreamState {
        let profile = params.profile.clone();
        // The presenter's half of phase-locked capture: it writes the latch grid the
@@ -316,8 +374,21 @@ impl StreamState {
            hdr_untonemapped: false,
            win_e2e_us: Vec::with_capacity(256),
            win_disp_us: Vec::with_capacity(256),
+            win_pace_us: Vec::with_capacity(256),
+            win_latch_us: Vec::with_capacity(256),
            win_start: Instant::now(),
            presented: PresentedWindow::default(),
+            store: FrameStore::new(usize::from(priority.fifo_capacity())),
+            clock: LatchClock::new(native_refresh_hz),
+            gate: PresentGate::default(),
+            cadence: CadenceProbe::new(),
+            mode_period_ns: 1_000_000_000 / u64::from(native_refresh_hz.max(1)),
+            last_target_ns: 0,
+            margin_ns: 0,
+            win_misses: 0,
+            win_out_max: 0,
+            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+            pyro_latency_forced: false,
            dmabuf_demoted: false,
            #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
            pyro_present_warned: false,
@@ -356,6 +427,25 @@ impl StreamState {
        }
        self.handle.stop.store(true, Ordering::SeqCst);
    }
+
+    /// The event-loop wait bound: a smoothness stream with buffered frames sleeps only
+    /// to its next latch-slot deadline; everything else keeps the 15 ms housekeeping
+    /// tick (frames, input, and present completions all wake the loop early anyway).
+    fn wake_timeout(&self) -> Duration {
+        const TICK: Duration = Duration::from_millis(15);
+        if !self.store.is_smoothing() || self.store.is_empty() {
+            return TICK;
+        }
+        let now = session::now_ns();
+        let mut target = self
+            .clock
+            .next_slot_after(now.saturating_add(self.margin_ns));
+        if target == self.last_target_ns {
+            // This slot is already served — the next boundary is the deadline.
+            target += self.clock.period_ns();
+        }
+        Duration::from_nanos(target.saturating_sub(now)).clamp(Duration::from_millis(1), TICK)
+    }
 }

 /// Whether a present error is `VK_ERROR_DEVICE_LOST` anywhere in its chain. A lost
@@ -438,9 +528,43 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
    let instance_exts = window
        .vulkan_instance_extensions()
        .map_err(|e| anyhow::anyhow!("vulkan instance extensions: {e}"))?;
-    let mut presenter = Presenter::new(&window, &instance_exts).context("vulkan presenter")?;
+    let mut presenter = Presenter::new(
+        &window,
+        &instance_exts,
+        crate::vk::PresentPref {
+            vsync: opts.vsync,
+            allow_vrr: opts.allow_vrr,
+            fullscreen: opts.fullscreen,
+            // `vrr_fifo_opt_in` (env) and `fifo_latest_ready` (device capability) are
+            // both resolved inside `Presenter::new` — the swapchain owns those, so every
+            // caller gets the same answer. `..Default` keeps this site from breaking each
+            // time the struct learns another one.
+            ..Default::default()
+        },
+    )
+    .context("vulkan presenter")?;
    // A valid black frame immediately — the window is honest while the connect runs.
    presenter.present(&window, FrameInput::Redraw, None)?;
+
+    // `PUNKTFUNK_PRESENTER=arrival` — the legacy drain, the intent engine's field-A/B
+    // kill switch (the Android sysprop pattern: no rebuild to bisect a pacing suspicion).
+    let arrival_override = std::env::var("PUNKTFUNK_PRESENTER").ok().as_deref() == Some("arrival");
+    let present_priority = if arrival_override {
+        tracing::info!("PUNKTFUNK_PRESENTER=arrival — presentation pacing disabled");
+        PresentPriority::Latency
+    } else {
+        opts.present_priority
+    };
+    let pacing_active = !arrival_override;
+    let present_debug = std::env::var_os("PUNKTFUNK_PRESENT_DEBUG").is_some();
+    // Present completions wake the loop exactly like decoded frames: a glass-gate
+    // reopen or a smoothness slot must not wait out the event timeout.
+    {
+        let sender = events.event_sender();
+        presenter.set_present_wake(Box::new(move || {
+            let _ = sender.push_custom_event(FrameWake);
+        }));
+    }
    // Browse mode is "ready" the moment the library window presents — there may never be
    // a stream. (Single mode announces on the first VIDEO frame instead, further down, so
    // a shell only yields to a window that actually shows the stream.)
@@ -517,6 +641,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                params,
                force_software,
                events.event_sender(),
+                present_priority,
+                native.refresh_hz,
            ))
        }
        ModeCtl::Browse(_) => None,
@@ -544,8 +670,11 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
        // forwarder's FrameWake) all land in this one queue, so the loop wakes exactly
        // when there is work — a short-timeout poll here burned a full core (measured;
        // the timeout only bounds stop-flag/pump-tick latency now). In browse-idle the
-        // per-iteration FIFO present vsync-throttles the loop anyway.
-        let timeout = Duration::from_millis(15);
+        // per-iteration FIFO present vsync-throttles the loop anyway. A smoothness
+        // stream tightens the bound to its next latch-slot deadline.
+        let timeout = stream
+            .as_ref()
+            .map_or(Duration::from_millis(15), |st| st.wake_timeout());
        let first = event_pump.wait_event_timeout(timeout);
        let mut queued: Vec<Event> = Vec::new();
        if let Some(e) = first {
@@ -608,6 +737,29 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                            }
                        }
                    }
+                    // Dragged to another monitor (or the mode changed under us): the
+                    // latch grid and the VRR verdict both belong to the OLD panel. The
+                    // refresh rate used to be read once at startup and never revisited,
+                    // so a 60 Hz-seeded clock would keep pacing a 144 Hz panel.
+                    WindowEvent::DisplayChanged(..) => {
+                        let hz = window
+                            .get_display()
+                            .and_then(|d| d.get_mode())
+                            .map(|m| m.refresh_rate.round().max(0.0) as u32)
+                            .unwrap_or(0);
+                        if let Some(st) = stream.as_mut() {
+                            if hz > 0 {
+                                st.clock = LatchClock::new(hz);
+                                st.mode_period_ns = 1_000_000_000 / u64::from(hz);
+                            }
+                            st.cadence.reset();
+                            st.last_target_ns = 0;
+                            tracing::info!(
+                                refresh_hz = hz,
+                                "display changed — relearning the latch grid"
+                            );
+                        }
+                    }
                    WindowEvent::Exposed => {
                        presenter.present(&window, FrameInput::Redraw, overlay_frame.as_ref())?;
                    }
@@ -1032,6 +1184,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                                    *params,
                                    force_software,
                                    events.event_sender(),
+                                    present_priority,
+                                    native.refresh_hz,
                                ));
                                if let Some(o) = overlay.as_mut() {
                                    o.session_phase(SessionPhase::Connecting);
@@ -1279,11 +1433,148 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                    presenter.set_hdr_metadata(m);
                }
            }
-            let mut newest: Option<DecodedFrame> = None;
-            while let Ok(f) = st.frames.try_recv() {
-                newest = Some(f);
+            // Present-wait completions drive the latch clock, the glass gate, and the
+            // host-facing grid — drained every pass (a 1 Hz batch would starve all
+            // three; the waiter's SDL wake pairs with this so completions never wait
+            // out the event timeout).
+            if presenter.present_timing_active() {
+                let samples = presenter.take_presented_samples();
+                if !samples.is_empty() {
+                    let clock_offset_ns = st
+                        .clock_offset
+                        .as_ref()
+                        .map_or(0, |o| o.load(Ordering::Relaxed));
+                    let period = st.clock.period_ns();
+                    let mut stamps = Vec::with_capacity(samples.len());
+                    for s in &samples {
+                        let e2e = (s.displayed_ns as i128 + clock_offset_ns as i128
+                            - s.pts_ns as i128)
+                            .max(0) as u64;
+                        if e2e > 0 && e2e < 10_000_000_000 {
+                            st.win_e2e_us.push(e2e / 1000);
+                        }
+                        st.win_disp_us
+                            .push(s.displayed_ns.saturating_sub(s.decoded_ns) / 1000);
+                        // The display split (WP4): our pipeline vs the vsync latch. Only
+                        // meaningful with true glass stamps, which is exactly when this
+                        // branch runs.
+                        st.win_pace_us
+                            .push(s.submitted_ns.saturating_sub(s.decoded_ns) / 1000);
+                        st.win_latch_us
+                            .push(s.displayed_ns.saturating_sub(s.submitted_ns) / 1000);
+                        // Latch miss (the adaptive margin's error signal): glass later
+                        // than one panel period past submit, PLUS the lead we already
+                        // applied — i.e. the slot we aimed at was missed. Measuring the
+                        // real latch rather than the store's own evictions is the
+                        // Android 0.23.0 correction: policy drops happen whenever the
+                        // stream out-runs the panel and say nothing about the latch, and
+                        // widening on them walked the margin to its ceiling on healthy
+                        // devices, re-imposing the very display latency it had removed.
+                        if st.store.is_smoothing()
+                            && s.displayed_ns.saturating_sub(s.submitted_ns) > period + st.margin_ns
+                        {
+                            st.win_misses += 1;
+                        }
+                        stamps.push(s.displayed_ns);
+                    }
+                    st.clock.note_batch(&stamps);
+                    // Same stamps answer "is VRR live" — the panel either quantizes them
+                    // to its grid or follows our cadence. Evidence only counts from a
+                    // window whose presents were flowing normally: a distressed pipeline
+                    // (stale force-opens) smears spacings for reasons that have nothing
+                    // to do with the panel, and on glass that flapped the verdict.
+                    //
+                    // ⚠ The reference is the DISPLAY MODE's period, NOT the learned one.
+                    // The learned grid comes from our own present spacings, and a stream
+                    // running below panel rate only ever produces multiples ≥ its frame
+                    // interval — so the learner adopts our cadence as "the grid" and every
+                    // delta then looks on-grid by construction. Measured on .21
+                    // (2026-08-02): a 40-50 fps stream on a 60 Hz panel learned 18-22 ms
+                    // and the probe reported VRR on a display with VRR provably disabled.
+                    // The vblank grid is the mode's refresh; that is what presents
+                    // quantize to when VRR is off.
+                    //
+                    // ⚠⚠ And it is only asked under a FIFO-family mode. The whole test
+                    // rests on "with VRR off, a present waits for vblank" — MAILBOX and
+                    // IMMEDIATE deliberately break that, so their stamps are never
+                    // grid-quantized and the probe would call every mailbox session VRR.
+                    // Measured on .21: same panel, same second — fifo read `no`
+                    // (correct, period 16.56 ms), mailbox read `yes` (wrong). Outside
+                    // FIFO the honest answer is "cannot tell", i.e. Unknown.
+                    let healthy = st.presented.forced == 0;
+                    if presenter.vblank_locked() {
+                        st.cadence.note(&stamps, st.mode_period_ns, healthy);
+                    }
+                    // Phase-locked capture, the presenter's half: publish the grid the
+                    // local clock just learned — a recent TRUE on-glass instant plus
+                    // the latch period — for the pump's ~1 Hz PhaseReport. One learner
+                    // feeds both, so the report and the scheduler cannot disagree.
+                    if let Some(grid) = &st.latch_grid {
+                        grid.period_ns
+                            .store(st.clock.period_ns(), Ordering::Relaxed);
+                        grid.anchor_ns
+                            .store(st.clock.anchor_ns(), Ordering::Relaxed);
+                    }
+                }
            }
-            if let Some(f) = newest {
+
+            // Intake into the intent store: a newest-wins slot under latency (the
+            // shipped drain, now with displacement counters), the smoothing FIFO under
+            // smoothness. PyroWave collapses smoothness to latency for the stream: its
+            // plane-ring retirement accounting assumes the newest-wins hand-off
+            // (`video_pyrowave::RETIRE_HANDOVERS`), and all-intra frames make
+            // buffering moot anyway.
+            while let Ok(f) = st.frames.try_recv() {
+                #[cfg(all(any(target_os = "linux", windows), feature = "pyrowave"))]
+                if st.store.is_smoothing() && matches!(f.image, DecodedImage::PyroWave(_)) {
+                    st.store.force_latency();
+                    if !st.pyro_latency_forced {
+                        st.pyro_latency_forced = true;
+                        tracing::info!(
+                            "PyroWave stream — smoothness buffering does not apply \
+                             (latency pacing)"
+                        );
+                    }
+                }
+                st.store.submit(f);
+            }
+
+            // One frame out, by intent: latency takes the newest whenever the glass
+            // gate allows; smoothness serves at most one frame per latch slot (the
+            // preroll/underflow behavior lives in the store).
+            let now_ns = session::now_ns();
+            let mut slot_target = 0u64;
+            let mut to_present = if st.store.is_smoothing() {
+                let target = st
+                    .clock
+                    .next_slot_after(now_ns.saturating_add(st.margin_ns));
+                if target != st.last_target_ns {
+                    slot_target = target;
+                    st.store.take()
+                } else {
+                    None
+                }
+            } else {
+                st.store.take()
+            };
+            // The FIFO glass budget: one undisplayed present in flight, so the
+            // swapchain's own FIFO can never become a standing queue (a measured
+            // 11-13 ms at 60 Hz on MAILBOX-less drivers). Only FIFO modes queue and
+            // only present timing can count, so everywhere else this stays inert and
+            // behavior is the shipped arrival pacing.
+            if pacing_active && presenter.needs_glass_gate() && presenter.present_timing_active() {
+                if let Some(f) = to_present.take() {
+                    if st.gate.open(presenter.presents_outstanding(), now_ns) {
+                        to_present = Some(f);
+                    } else {
+                        // Parked: a newest-wins store replaces it if a fresher frame
+                        // lands; the waiter's wake (or the 100 ms stale force-open)
+                        // retries.
+                        st.store.put_back(f);
+                    }
+                }
+            }
+            if let Some(f) = to_present {
                // Resize END: a frame at the steered target size means the sharp new-mode
                // picture is here — lift the scrim. A no-op unless a switch is in flight.
                let (fw, fh) = f.image.dimensions();
@@ -1472,6 +1763,12 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                };
                if did_present {
                    presented_video = true;
+                    // Smoothness: this latch slot is served — one present per slot.
+                    // (Set only on success: a gated or failed present leaves the slot
+                    // open for the retry.)
+                    if slot_target != 0 {
+                        st.last_target_ns = slot_target;
+                    }
                    if opts.json_status && !st.ready_announced {
                        st.ready_announced = true;
                        println!("{{\"ready\":true}}");
@@ -1481,6 +1778,8 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                        // e2e/display samples arrive via `take_presented_samples` with a
                        // TRUE on-glass stamp instead of the submit-time one below.
                        presenter.note_presented(pts_ns, decoded_ns);
+                        st.gate.note_present(now_ns);
+                        st.win_out_max = st.win_out_max.max(presenter.presents_outstanding());
                    } else {
                        let displayed_ns = session::now_ns();
                        // The `displayed` stamp (same clamp rules as the pump's windows).
@@ -1495,59 +1794,81 @@ fn run_inner(mut opts: SessionOpts, mut mode: ModeCtl) -> Result<Option<Outcome>
                        }
                        st.win_disp_us
                            .push(displayed_ns.saturating_sub(decoded_ns) / 1000);
+                        // No glass stamps on this stack: the submit instant anchors an
+                        // approximate grid on the mode's refresh period, so smoothness
+                        // still drains one frame per (approximate) slot.
+                        st.clock.note_batch(&[displayed_ns]);
                    }
                }
            }

            // Fold the presenter window into the shared stats line once per second.
+            // (The on-glass samples themselves are drained every pass above — they
+            // drive the latch clock and glass gate, not just this fold.)
            if st.win_start.elapsed() >= Duration::from_secs(1) {
-                // On-glass samples the present-wait waiter completed this window (empty
-                // when timing is inactive — the legacy submit-time pushes fill in then).
-                let clock_offset_ns = st
-                    .clock_offset
-                    .as_ref()
-                    .map_or(0, |o| o.load(Ordering::Relaxed));
-                let samples = presenter.take_presented_samples();
-                // Phase-locked capture, the presenter's half: publish this window's latch
-                // grid — a recent TRUE on-glass instant plus the panel period — for the
-                // pump's ~1 Hz PhaseReport. The period is the min positive spacing of
-                // consecutive on-glass stamps (Apple's method: honest under VRR), capped
-                // by the display mode's refresh — under arrival-paced MAILBOX a stream
-                // running below the panel rate spaces its presents at k×period, and the
-                // cap keeps a 30 fps stream from claiming a 30 Hz panel grid.
-                if let Some(grid) = &st.latch_grid {
-                    if let Some(last) = samples.last() {
-                        let refresh_period = 1_000_000_000u64 / u64::from(native.refresh_hz.max(1));
-                        let min_delta = samples
-                            .windows(2)
-                            .map(|w| w[1].displayed_ns.saturating_sub(w[0].displayed_ns))
-                            .filter(|&d| d > 1_000_000) // < 1 ms apart = queued pair, not a grid step
-                            .min()
-                            .unwrap_or(refresh_period);
-                        grid.period_ns
-                            .store(min_delta.min(refresh_period), Ordering::Relaxed);
-                        grid.anchor_ns.store(last.displayed_ns, Ordering::Relaxed);
-                    }
-                }
-                for s in samples {
-                    let e2e = (s.displayed_ns as i128 + clock_offset_ns as i128 - s.pts_ns as i128)
-                        .max(0) as u64;
-                    if e2e > 0 && e2e < 10_000_000_000 {
-                        st.win_e2e_us.push(e2e / 1000);
-                    }
-                    st.win_disp_us
-                        .push(s.displayed_ns.saturating_sub(s.decoded_ns) / 1000);
-                }
                let (e2e_p50, e2e_p95) = session::window_percentiles(&mut st.win_e2e_us);
                let (disp_p50, _) = session::window_percentiles(&mut st.win_disp_us);
+                let (pace_p50, _) = session::window_percentiles(&mut st.win_pace_us);
+                let (latch_p50, _) = session::window_percentiles(&mut st.win_latch_us);
+                // Drained ONCE per window and shared by the HUD and the log line below —
+                // a second `take_counters` would read zeros.
+                let (replaced, q_drop, q_dry) = st.store.take_counters();
+                let (gated, forced) = st.gate.take_counters();
                st.presented = PresentedWindow {
                    e2e_p50_ms: e2e_p50 as f32 / 1000.0,
                    e2e_p95_ms: e2e_p95 as f32 / 1000.0,
                    display_ms: disp_p50 as f32 / 1000.0,
+                    pace_ms: pace_p50 as f32 / 1000.0,
+                    latch_ms: latch_p50 as f32 / 1000.0,
+                    mode: presenter.present_mode_name(),
+                    vrr: st.cadence.verdict(),
+                    smoothing: st.store.is_smoothing(),
+                    q_drop,
+                    q_dry,
+                    gated,
+                    forced,
                };
                st.win_e2e_us.clear();
                st.win_disp_us.clear();
+                st.win_pace_us.clear();
+                st.win_latch_us.clear();
                st.win_start = Instant::now();
+                // Adaptive slot margin (the Android presenter's measured recipe):
+                // start at 0 — a fixed lead is pure display tax — and widen one step
+                // per window whose measured latch misses demand it. One-way per
+                // stream; the next stream restarts at 0.
+                if st.store.is_smoothing() && st.win_misses > 2 && st.margin_ns < MARGIN_MAX_NS {
+                    st.margin_ns = (st.margin_ns + MARGIN_STEP_NS).min(MARGIN_MAX_NS);
+                    tracing::info!(
+                        margin_us = st.margin_ns / 1000,
+                        misses = st.win_misses,
+                        "smoothness slot margin widened (measured latch misses)"
+                    );
+                }
+                // The 1 Hz presenter line (the Apple `pf-present` analogue): emitted
+                // when anything moved, or always under PUNKTFUNK_PRESENT_DEBUG=1 —
+                // the field-triage instrument for the intent engine.
+                if pacing_active && (present_debug || q_drop + q_dry + gated + forced > 0) {
+                    tracing::info!(
+                        smoothing = st.presented.smoothing,
+                        mode = st.presented.mode,
+                        vrr = st.presented.vrr.label(),
+                        replaced,
+                        q_drop,
+                        q_dry,
+                        gated,
+                        forced,
+                        misses = st.win_misses,
+                        out_max = st.win_out_max,
+                        pace_ms = st.presented.pace_ms,
+                        latch_ms = st.presented.latch_ms,
+                        period_us = st.clock.period_ns() / 1000,
+                        margin_us = st.margin_ns / 1000,
+                        "presenter window"
+                    );
+                }
+                st.win_misses = 0;
+                st.win_out_max = 0;
            }
        }

@@ -2007,6 +2328,32 @@ struct PresentedWindow {
    e2e_p50_ms: f32,
    e2e_p95_ms: f32,
    display_ms: f32,
+    /// The display stage split (design/desktop-presentation-rebuild.md WP4):
+    /// `pace` = decoded → present-submit (our own pipeline), `latch` = submit → on-glass
+    /// (the presentation engine's queue + the vblank wait). Both `0` without
+    /// `VK_KHR_present_wait`, where the two are not separable — the HUD then shows the
+    /// unsplit figure rather than inventing a zero latch.
+    ///
+    /// This split is what makes a high `display` self-diagnosing: latch dominating means
+    /// the vsync/queue floor (or a standing queue), pace dominating means us.
+    /// `pace` is also the honest cross-platform twin of the Apple client's shaved
+    /// number — Apple subtracts its measured OS present floor, and the latch IS our
+    /// floor, so `pace` is what remains on both sides of that comparison.
+    pace_ms: f32,
+    latch_ms: f32,
+    /// The live swapchain present mode (`mailbox`/`fifo`/…). Shown because a mode is
+    /// chosen from what the surface offers, so "why is my latch a refresh long" is
+    /// usually answered by a MAILBOX request having landed on FIFO.
+    mode: &'static str,
+    /// Whether variable refresh is measurably live (never claimed without evidence).
+    vrr: Cadence,
+    /// Presenter-engine counters for the window: the smoothing FIFO's overflow drops and
+    /// post-preroll underflows, and the FIFO glass gate's holds/stale force-opens.
+    smoothing: bool,
+    q_drop: u32,
+    q_dry: u32,
+    gated: u32,
+    forced: u32,
 }

 /// The capture hints (`ui_stream` parity — the words the user reads while released).
@@ -2112,6 +2459,15 @@ fn stats_text(
            " · decode {:.1} · display {:.1} ms",
            s.decode_ms, p.display_ms
        ));
+        // The display split (WP4). Only with true on-glass stamps — without them the
+        // two halves are not separable and the unsplit figure stands alone rather than
+        // implying a zero latch.
+        if p.latch_ms > 0.0 || p.pace_ms > 0.0 {
+            text.push_str(&format!(
+                " (pace {:.1} + latch {:.1})",
+                p.pace_ms, p.latch_ms
+            ));
+        }
        // Extended 0xCF host-stage split (T0.1): its own line so the per-stage attribution
        // (queue → encode → seal/xfer → pace) reads as the host pipeline in order.
        if s.staged {
@@ -2120,6 +2476,32 @@ fn stats_text(
                s.host_queue_ms, s.host_encode_ms, s.host_xfer_ms, s.host_pace_ms
            ));
        }
+        // The presenter line: the swapchain mode that is actually live, the chosen
+        // intent, and the engine's own counters. Present-mode alone answers most
+        // "why is my latch a whole refresh" questions; the counters only render when
+        // they are non-zero, so a healthy latency session shows just the mode.
+        if !p.mode.is_empty() {
+            text.push_str(&format!("\npresent: {}", p.mode));
+            // Only once measured — an unproven "vrr no" would be a claim, not a reading.
+            if p.vrr != Cadence::Unknown {
+                text.push_str(&format!(" · vrr {}", p.vrr.label()));
+            }
+            if p.smoothing {
+                text.push_str(" · smoothing");
+            }
+            if p.q_drop > 0 {
+                text.push_str(&format!(" · qdrop {}", p.q_drop));
+            }
+            if p.q_dry > 0 {
+                text.push_str(&format!(" · qdry {}", p.q_dry));
+            }
+            if p.gated > 0 {
+                text.push_str(&format!(" · gated {}", p.gated));
+            }
+            if p.forced > 0 {
+                text.push_str(&format!(" · forced {}", p.forced));
+            }
+        }
    }
    if s.lost > 0 {
        text.push_str(&format!("\nlost {} ({:.1}%)", s.lost, s.lost_pct));
@@ -2393,6 +2775,7 @@ mod tests {
                e2e_p50_ms: 6.4,
                e2e_p95_ms: 9.1,
                display_ms: 1.1,
+                ..Default::default()
            },
        )
    }
@@ -2430,6 +2813,70 @@ mod tests {
            !normal.contains("queue"),
            "host-stage split is Detailed-only"
        );
+        assert!(
+            !detailed.contains("pace 1.1"),
+            "no glass stamps in this sample — the display stage stays unsplit"
+        );
+    }
+
+    /// WP4: with true on-glass stamps the display stage reads as its two halves, the
+    /// live present mode is named, and the engine counters render only when non-zero —
+    /// so a healthy latency session shows the mode and nothing else. Without glass
+    /// stamps (no `VK_KHR_present_wait`) the split is absent rather than a zero latch.
+    #[test]
+    fn detailed_splits_display_into_pace_and_latch() {
+        let (s, mut p) = sample();
+        p.display_ms = 12.4;
+        p.pace_ms = 1.1;
+        p.latch_ms = 11.3;
+        p.mode = "fifo";
+        let split = stats_text(
+            StatsVerbosity::Detailed,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(split.contains("display 12.4 ms (pace 1.1 + latch 11.3)"));
+        assert!(split.contains("\npresent: fifo"));
+        assert!(
+            !split.contains("qdrop") && !split.contains("gated") && !split.contains("smoothing"),
+            "quiet counters stay off the HUD: {split}"
+        );
+
+        // The smoothing FIFO and the glass gate surface once they actually do something.
+        p.smoothing = true;
+        p.q_drop = 2;
+        p.q_dry = 1;
+        p.gated = 7;
+        p.forced = 1;
+        let busy = stats_text(
+            StatsVerbosity::Detailed,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(busy.contains("present: fifo · smoothing · qdrop 2 · qdry 1 · gated 7 · forced 1"));
+
+        // A tier below Detailed never carries any of it.
+        let normal = stats_text(
+            StatsVerbosity::Normal,
+            "m",
+            &s,
+            &p,
+            false,
+            false,
+            false,
+            None,
+        );
+        assert!(!normal.contains("present:") && !normal.contains("pace"));
    }

    /// The honest HDR badges: a PQ stream on the software-decode lane is shown WITHOUT
@@ -33,7 +33,7 @@ mod reconfig;
 mod resources;
 mod setup;

-pub use setup::list_adapters;
+pub use setup::{list_adapters, PresentPref};

 /// One presenter iteration's video input.
 pub enum FrameInput<'a> {
@@ -247,10 +247,75 @@ impl Presenter {
    /// (the presenter itself never sees them). No-op when timing is inactive.
    pub(crate) fn note_presented(&mut self, pts_ns: u64, decoded_ns: u64) {
        if let (Some(t), Some((sc, id))) = (&self.present_timer, self.last_presented.take()) {
-            t.enqueue(sc, id, pts_ns, decoded_ns);
+            // The submit stamp: `present()` already returned, so "now" is within the
+            // present-call tail — the pace/latch split point.
+            t.enqueue(
+                sc,
+                id,
+                pts_ns,
+                decoded_ns,
+                pf_client_core::session::now_ns(),
+            );
        }
    }

+    /// Undisplayed id-carrying presents in flight (0 when timing is inactive) — the
+    /// FIFO glass gate's budget count.
+    pub(crate) fn presents_outstanding(&self) -> usize {
+        self.present_timer.as_ref().map_or(0, |t| t.outstanding())
+    }
+
+    /// Install the run loop's wake for present completions (an SDL event push). No-op
+    /// without present timing — there is nothing to wake on then.
+    pub(crate) fn set_present_wake(&self, cb: Box<dyn Fn() + Send>) {
+        if let Some(t) = &self.present_timer {
+            t.set_wake(cb);
+        }
+    }
+
+    /// The live swapchain present mode, for the stats overlay: a mode is picked from
+    /// what the surface actually offers, so the requested one and this can differ (a
+    /// MAILBOX request lands on FIFO wherever the driver has no mailbox — AMD's Windows
+    /// driver, notably). Showing it is what makes that visible instead of puzzling.
+    pub(crate) fn present_mode_name(&self) -> &'static str {
+        match self.present_mode {
+            vk::PresentModeKHR::MAILBOX => "mailbox",
+            vk::PresentModeKHR::FIFO => "fifo",
+            vk::PresentModeKHR::FIFO_RELAXED => "fifo-relaxed",
+            vk::PresentModeKHR::IMMEDIATE => "immediate",
+            setup::fifo_latest_ready::MODE => "fifo-latest-ready",
+            _ => "other",
+        }
+    }
+
+    /// The active present mode QUEUES presents — the only modes where the swapchain
+    /// itself can become a standing queue, and so the only ones the glass gate governs.
+    ///
+    /// MAILBOX and IMMEDIATE replace/flip and never queue. Nor does
+    /// `FIFO_LATEST_READY`, which retires stale images in the driver: gating on top of it
+    /// would hold frames back to emulate something the presentation engine is already
+    /// doing, paying the serialisation twice.
+    pub(crate) fn needs_glass_gate(&self) -> bool {
+        matches!(
+            self.present_mode,
+            vk::PresentModeKHR::FIFO | vk::PresentModeKHR::FIFO_RELAXED
+        )
+    }
+
+    /// The active present mode shows images ON THE VBLANK GRID — the premise the VRR
+    /// cadence probe rests on ("with VRR off, a present waits for vblank"). The whole
+    /// FIFO family qualifies, `FIFO_LATEST_READY` included: it drops stale images but
+    /// still presents on the refresh boundary. MAILBOX/IMMEDIATE do not, and under them
+    /// the probe reports Unknown rather than calling every session VRR.
+    pub(crate) fn vblank_locked(&self) -> bool {
+        matches!(
+            self.present_mode,
+            vk::PresentModeKHR::FIFO
+                | vk::PresentModeKHR::FIFO_RELAXED
+                | setup::fifo_latest_ready::MODE
+        )
+    }
+
    /// Take the window's completed on-glass samples (empty when timing is inactive).
    pub(crate) fn take_presented_samples(&self) -> Vec<present_timing::PresentedSample> {
        self.present_timer
@@ -26,6 +26,9 @@ pub(crate) struct PresentedSample {
    pub pts_ns: u64,
    /// Decode-complete stamp (client clock) — the display-stage anchor.
    pub decoded_ns: u64,
+    /// `vkQueuePresentKHR`-return stamp (client clock) — the pace/latch split point:
+    /// `submitted − decoded` is our pipeline, `displayed − submitted` the vsync latch.
+    pub submitted_ns: u64,
    /// `vkWaitForPresentKHR` completion = the image is visible (client clock).
    pub displayed_ns: u64,
 }
@@ -35,15 +38,24 @@ struct Job {
    present_id: u64,
    pts_ns: u64,
    decoded_ns: u64,
+    submitted_ns: u64,
 }

+/// The run loop's wake callback (an SDL event push), shared with the waiter thread.
+type WakeSlot = Arc<Mutex<Option<Box<dyn Fn() + Send>>>>;
+
 /// The waiter: a channel-fed thread turning (swapchain, present-id) pairs into
 /// [`PresentedSample`]s. One frame in flight upstream keeps the queue depth ~1.
 pub(crate) struct PresentTimer {
    tx: Option<mpsc::Sender<Job>>,
-    /// Jobs enqueued but not yet finished — the drain barrier for swapchain teardown.
+    /// Jobs enqueued but not yet finished — the drain barrier for swapchain teardown,
+    /// and the glass gate's "undisplayed presents in flight" count.
    pending: Arc<AtomicUsize>,
    results: Arc<Mutex<Vec<PresentedSample>>>,
+    /// Called by the waiter after each completed wait (sample or not) — the run loop
+    /// installs an SDL wake here so a gate reopen / smoothness slot never waits out the
+    /// event-loop timeout.
+    wake: WakeSlot,
    join: Option<std::thread::JoinHandle<()>>,
 }

@@ -52,7 +64,8 @@ impl PresentTimer {
        let (tx, rx) = mpsc::channel::<Job>();
        let pending = Arc::new(AtomicUsize::new(0));
        let results = Arc::new(Mutex::new(Vec::with_capacity(256)));
-        let (pending_t, results_t) = (pending.clone(), results.clone());
+        let wake: WakeSlot = Arc::new(Mutex::new(None));
+        let (pending_t, results_t, wake_t) = (pending.clone(), results.clone(), wake.clone());
        let join = std::thread::Builder::new()
            .name("pf-present-wait".into())
            .spawn(move || {
@@ -69,12 +82,20 @@ impl PresentTimer {
                        results_t.lock().unwrap().push(PresentedSample {
                            pts_ns: job.pts_ns,
                            decoded_ns: job.decoded_ns,
+                            submitted_ns: job.submitted_ns,
                            displayed_ns,
                        });
                    }
                    // SUBOPTIMAL/TIMEOUT/DEVICE_LOST: no sample; the frame still showed
                    // (or the loop is about to find out) — never poison the window.
                    pending_t.fetch_sub(1, Ordering::AcqRel);
+                    // Wake the run loop AFTER the count dropped: what it observes on
+                    // wake is the post-completion state (the gate may now be open).
+                    // Called under the slot lock — the callback is a bare SDL event
+                    // push and never reenters this type.
+                    if let Some(cb) = wake_t.lock().unwrap().as_ref() {
+                        cb();
+                    }
                }
            })
            .expect("spawn pf-present-wait");
@@ -82,10 +103,23 @@ impl PresentTimer {
            tx: Some(tx),
            pending,
            results,
+            wake,
            join: Some(join),
        }
    }

+    /// Install the run loop's wake callback (an SDL event push — thread-safe by design).
+    pub(crate) fn set_wake(&self, cb: Box<dyn Fn() + Send>) {
+        *self.wake.lock().unwrap() = Some(cb);
+    }
+
+    /// Presents handed to the waiter and not yet resolved to glass — the glass gate's
+    /// budget count. (Also counts a wait that will end SUBOPTIMAL/TIMEOUT; those resolve
+    /// within the 250 ms cap, far past the gate's own 100 ms stale force-open.)
+    pub(crate) fn outstanding(&self) -> usize {
+        self.pending.load(Ordering::Acquire)
+    }
+
    /// Hand a successfully submitted present to the waiter.
    pub(crate) fn enqueue(
        &self,
@@ -93,6 +127,7 @@ impl PresentTimer {
        present_id: u64,
        pts_ns: u64,
        decoded_ns: u64,
+        submitted_ns: u64,
    ) {
        if let Some(tx) = &self.tx {
            self.pending.fetch_add(1, Ordering::AcqRel);
@@ -102,6 +137,7 @@ impl PresentTimer {
                    present_id,
                    pts_ns,
                    decoded_ns,
+                    submitted_ns,
                })
                .is_err()
            {
@@ -13,10 +13,55 @@ use ash::vk;
 use ash::vk::Handle as _;
 use std::ffi::{c_char, CString};

+/// `VK_EXT_present_mode_fifo_latest_ready`, hand-declared: it postdates the Vulkan headers
+/// ash 0.38 is generated from (1.3.281), so there is no binding for it — which is also why
+/// an unenabled driver reports the mode back as the bare number `1000361000`.
+///
+/// The mode is FIFO's tear-free vblank pacing that presents the **latest ready** image at
+/// each refresh and retires the older ones, instead of draining a queue. That is precisely
+/// what [`super::super::present_pace::PresentGate`] emulates in software, done by the
+/// driver — and it matters most exactly where the gate does: on a surface that offers no
+/// MAILBOX, this restores newest-wins behaviour without the app holding frames back.
+pub(crate) mod fifo_latest_ready {
+    use ash::vk;
+
+    /// `VK_EXT_present_mode_fifo_latest_ready` (extension 361).
+    pub(super) const NAME: &std::ffi::CStr = c"VK_EXT_present_mode_fifo_latest_ready";
+    /// `VK_PRESENT_MODE_FIFO_LATEST_READY_EXT`.
+    pub(crate) const MODE: vk::PresentModeKHR = vk::PresentModeKHR::from_raw(1000361000);
+    /// `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PRESENT_MODE_FIFO_LATEST_READY_FEATURES_EXT`.
+    const S_TYPE: vk::StructureType = vk::StructureType::from_raw(1000361000);
+
+    /// `VkPhysicalDevicePresentModeFifoLatestReadyFeaturesEXT`. The mode is usable only
+    /// when this feature is enabled at device creation, so the surface advertising the
+    /// mode is NOT on its own permission to request it.
+    #[repr(C)]
+    #[derive(Clone, Copy)]
+    pub(super) struct Features {
+        pub s_type: vk::StructureType,
+        pub p_next: *mut std::ffi::c_void,
+        pub present_mode_fifo_latest_ready: vk::Bool32,
+    }
+
+    impl Default for Features {
+        fn default() -> Features {
+            Features {
+                s_type: S_TYPE,
+                p_next: std::ptr::null_mut(),
+                present_mode_fifo_latest_ready: vk::FALSE,
+            }
+        }
+    }
+}
+
 impl Presenter {
    /// Bring up instance → surface → device → swapchain over an SDL window.
    /// `instance_extensions` comes from `VideoSubsystem::vulkan_instance_extensions()`.
-    pub fn new(window: &sdl3::video::Window, instance_extensions: &[String]) -> Result<Presenter> {
+    pub fn new(
+        window: &sdl3::video::Window,
+        instance_extensions: &[String],
+        pref: PresentPref,
+    ) -> Result<Presenter> {
        // SAFETY: per the Vulkan contract above - a create/allocate call on the live device, over
        // builder structs that are locals outliving the call; the handle it returns is owned by
        // the value being built here.
@@ -176,6 +221,21 @@ impl Presenter {
        // structs through its pNext chain, so any later use of it would pin those borrows —
        // every read of a chained struct below must come after this, have_f2's last use.
        let have_shader_int16 = have_f2.features.shader_int16;
+        // FIFO_LATEST_READY: the surface may list the mode even with the extension
+        // disabled, so the device feature is the real gate on using it.
+        let flr_ok = if has(fifo_latest_ready::NAME) {
+            let mut feat = fifo_latest_ready::Features::default();
+            let mut probe = vk::PhysicalDeviceFeatures2 {
+                p_next: (&mut feat) as *mut _ as *mut std::ffi::c_void,
+                ..Default::default()
+            };
+            // SAFETY: per the Vulkan contract above - a read-only query on the live
+            // instance/device, filling locals returned by value; `feat` outlives the call.
+            unsafe { instance.get_physical_device_features2(pdev, &mut probe) };
+            feat.present_mode_fifo_latest_ready == vk::TRUE
+        } else {
+            false
+        };
        let present_wait_ok = present_wait_exts
            && have_pid.present_id == vk::TRUE
            && have_pwait.present_wait == vk::TRUE;
@@ -273,6 +333,13 @@ impl Presenter {
            dev_exts.push(ash::khr::present_id::NAME.as_ptr());
            dev_exts.push(ash::khr::present_wait::NAME.as_ptr());
        }
+        if flr_ok {
+            dev_exts.push(fifo_latest_ready::NAME.as_ptr());
+        }
+        let mut en_flr = fifo_latest_ready::Features {
+            present_mode_fifo_latest_ready: vk::TRUE,
+            ..Default::default()
+        };
        let mut en_pid = vk::PhysicalDevicePresentIdFeaturesKHR::default().present_id(true);
        let mut en_pwait = vk::PhysicalDevicePresentWaitFeaturesKHR::default().present_wait(true);

@@ -295,6 +362,11 @@ impl Presenter {
        if present_wait_ok {
            en_f2 = en_f2.push_next(&mut en_pid).push_next(&mut en_pwait);
        }
+        if flr_ok {
+            // Hand-rolled struct, so chain it by hand: splice into the pNext list head.
+            en_flr.p_next = en_f2.p_next;
+            en_f2.p_next = (&mut en_flr) as *mut _ as *mut std::ffi::c_void;
+        }
        en_f2.features.shader_int16 = if pyrowave_ok { vk::TRUE } else { vk::FALSE };

        let priorities = [1.0f32];
@@ -450,11 +522,17 @@ impl Presenter {
        if let Some(v) = video_export.as_mut() {
            v.d3d11_hdr10 = win_capable && import_rgb10 && hdr10_format.is_some();
        }
-        let present_mode = pick_present_mode(&surface_i, pdev, surface)?;
+        let mut pref = pref;
+        pref.vrr_fifo_opt_in = vrr_fifo_opt_in();
+        pref.fifo_latest_ready = flr_ok;
+        let present_mode = pick_present_mode(&surface_i, pdev, surface, pref)?;
        tracing::info!(
            ?format,
            ?hdr10_format,
            ?present_mode,
+            vsync = pref.vsync,
+            allow_vrr = pref.allow_vrr,
+            fifo_latest_ready = flr_ok,
            hdr_metadata = has_hdr_metadata,
            "swapchain config"
        );
@@ -730,42 +808,275 @@ pub(super) fn pick_formats(
    Ok((sdr, hdr10))
 }

-/// MAILBOX when the surface offers it, FIFO otherwise (`PUNKTFUNK_PRESENT_MODE=
-/// 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.
+/// What the user asked the presentation to be, resolved into a swapchain present mode by
+/// [`present_mode_chain`] (design/desktop-presentation-rebuild.md WP3).
+#[derive(Clone, Copy, Debug, Default)]
+pub struct PresentPref {
+    /// Tear-free presentation (the `vsync` setting, default on).
+    pub vsync: bool,
+    /// Let a variable-refresh display follow the stream cadence (`allow_vrr`, default on).
+    pub allow_vrr: bool,
+    /// Opt-in for the VRR FIFO-first ladder (`PUNKTFUNK_VRR_FIFO=1`). Off by default on
+    /// measured evidence — see [`present_mode_chain`].
+    pub vrr_fifo_opt_in: bool,
+    /// `VK_EXT_present_mode_fifo_latest_ready` is enabled on the device, so the mode may
+    /// be requested. Resolved during device creation; never set by callers.
+    pub fifo_latest_ready: bool,
+    /// The session STARTED fullscreen. The mode is chosen once, at swapchain creation, so
+    /// this is the starting state and an F11 mid-session does not re-pick — consistent
+    /// with the shells' "Display changes apply from the next session" footer, and why
+    /// live present-mode switching is an explicit non-goal.
+    pub fullscreen: bool,
+}
+
+/// The preference ladder, most to least wanted. The caller takes the first entry the
+/// surface actually offers; FIFO ends every chain because the spec guarantees it.
+///
+/// * **V-Sync off** — IMMEDIATE (tears, no wait at all), then FIFO_RELAXED (tears only on
+///   a late frame), then the tear-free modes. Asking for tearing and silently getting
+///   vsync is a lie the stats line now exposes, but the ladder still degrades safely.
+/// * **V-Sync on + VRR allowed + fullscreen + `PUNKTFUNK_VRR_FIFO=1`** — FIFO first. On a
+///   variable-refresh panel with direct scanout the FIFO present IS the flip, so the panel
+///   follows the stream's cadence; MAILBOX would decouple presents from scanout and
+///   re-quantize to the compositor's clock.
+///
+///   **Automatic where a queue-free vblank mode exists, opt-in otherwise.** The history is
+///   worth keeping: this was default-on, then measured on glass (.21, GNOME/Wayland,
+///   NVIDIA, *non*-VRR 60 Hz panel, 2026-08-02) to cost ~27 ms of display stage against
+///   MAILBOX — `28.4 ms (pace 11.8 + latch 16.6)` versus `1.4 ms (0.2 + 1.2)` — because a
+///   plain-FIFO present's on-glass confirmation lands a whole refresh later and the
+///   presenter serialises behind it. It became opt-in on that evidence.
+///
+///   `FIFO_LATEST_READY` removes the cause rather than working around it: the driver
+///   retires stale images, so the vblank-locked path measured **2.6 ms** on the same box —
+///   0.6 ms over MAILBOX instead of 27. So where the device offers it, following the panel
+///   is cheap enough to be the default again; where it does not, the ladder would fall
+///   back to plain FIFO and the regression returns, so it stays behind
+///   `PUNKTFUNK_VRR_FIFO=1` there. The win on a genuine VRR panel is still UNMEASURED —
+///   no VRR display was available — but the cost of trying is now small and bounded.
+/// * **Otherwise** — MAILBOX, then FIFO: the shipped default. MAILBOX never queues more
+///   than the newest frame, so an arrival-paced presenter doesn't block in the present
+///   queue (a measured 11-13 ms standing wait at 60 Hz when the compositor holds images
+///   for a vblank pass, or when arrival cadence drifts against refresh).
 ///
 /// 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.
+/// expected, not a misconfiguration, and now visible in the `present:` stats line.
+fn present_mode_chain(pref: PresentPref) -> Vec<vk::PresentModeKHR> {
+    use vk::PresentModeKHR as M;
+    let flr = pref.fifo_latest_ready.then_some(fifo_latest_ready::MODE);
+    let mut chain: Vec<M> = if !pref.vsync {
+        vec![M::IMMEDIATE, M::FIFO_RELAXED, M::MAILBOX]
+    } else if pref.allow_vrr && pref.fullscreen && (pref.fifo_latest_ready || pref.vrr_fifo_opt_in)
+    {
+        // The VRR ladder wants the vblank-locked family; LATEST_READY is that with the
+        // queue removed, so it outranks plain FIFO here too.
+        vec![]
+            .into_iter()
+            .chain(flr)
+            .chain([M::FIFO, M::MAILBOX, M::FIFO_RELAXED, M::IMMEDIATE])
+            .collect()
+    } else {
+        // MAILBOX first (measured good), then LATEST_READY — which is what gives a
+        // MAILBOX-less surface the same newest-wins behaviour, in the driver instead of
+        // in our glass gate.
+        vec![M::MAILBOX]
+            .into_iter()
+            .chain(flr)
+            .chain([M::FIFO_RELAXED, M::IMMEDIATE])
+            .collect()
+    };
+    if !pref.vsync {
+        chain.extend(flr);
+    }
+    // FIFO ends every chain: the spec guarantees it exists, so there is always a landing.
+    chain.push(M::FIFO);
+    chain
+}
+
+/// `PUNKTFUNK_VRR_FIFO=1` — opt into the FIFO-first ladder for variable-refresh panels.
+/// See [`present_mode_chain`] for the measurement that made this opt-in rather than
+/// default.
+fn vrr_fifo_opt_in() -> bool {
+    std::env::var("PUNKTFUNK_VRR_FIFO").is_ok_and(|v| v != "0")
+}
+
+/// Resolve the present mode: `PUNKTFUNK_PRESENT_MODE` pins one outright (the debug lever,
+/// unchanged), otherwise the first entry of [`present_mode_chain`] the surface offers.
 fn pick_present_mode(
    surface_i: &ash::khr::surface::Instance,
    pdev: vk::PhysicalDevice,
    surface: vk::SurfaceKHR,
+    pref: PresentPref,
 ) -> Result<vk::PresentModeKHR> {
    // SAFETY: per the Vulkan contract above - a read-only query on the live instance/device,
    // filling locals returned by value.
    let modes = unsafe { surface_i.get_physical_device_surface_present_modes(pdev, surface) }?;
-    let want = match std::env::var("PUNKTFUNK_PRESENT_MODE").ok().as_deref() {
-        Some("fifo") => vk::PresentModeKHR::FIFO,
-        Some("immediate") => vk::PresentModeKHR::IMMEDIATE,
-        Some("fifo_relaxed") => vk::PresentModeKHR::FIFO_RELAXED,
-        Some("mailbox") | None => vk::PresentModeKHR::MAILBOX,
+    let pinned = match std::env::var("PUNKTFUNK_PRESENT_MODE").ok().as_deref() {
+        Some("fifo") => Some(vk::PresentModeKHR::FIFO),
+        Some("immediate") => Some(vk::PresentModeKHR::IMMEDIATE),
+        Some("fifo_relaxed") => Some(vk::PresentModeKHR::FIFO_RELAXED),
+        Some("mailbox") => Some(vk::PresentModeKHR::MAILBOX),
+        None => None,
        Some(other) => {
            tracing::warn!(
                value = other,
-                "unknown PUNKTFUNK_PRESENT_MODE (expected fifo|mailbox|immediate|fifo_relaxed) — using mailbox"
+                "unknown PUNKTFUNK_PRESENT_MODE (expected fifo|mailbox|immediate|fifo_relaxed) — following the settings"
            );
-            vk::PresentModeKHR::MAILBOX
+            None
        }
    };
-    Ok(if modes.contains(&want) {
-        want
-    } else {
-        vk::PresentModeKHR::FIFO // always available per spec
-    })
+    if let Some(want) = pinned {
+        if modes.contains(&want) {
+            return Ok(want);
+        }
+        tracing::warn!(
+            ?want,
+            "PUNKTFUNK_PRESENT_MODE not offered by this surface — falling back"
+        );
+    }
+    // What the surface ACTUALLY offers, logged unconditionally. "AMD's Windows driver
+    // has no MAILBOX" is the premise the FIFO glass gate is built on, and it has been
+    // carried in comments rather than measured — present modes are a property of the
+    // (surface, device) pair, so they vary by platform surface, driver version and
+    // fullscreen state, and the only way to settle it is to read it back from real
+    // machines. One line here makes every field log answer the question.
+    tracing::info!(
+        available = ?modes,
+        "surface present modes"
+    );
+    let chain = present_mode_chain(pref);
+    let chosen = chain
+        .iter()
+        .copied()
+        .find(|m| modes.contains(m))
+        .unwrap_or(vk::PresentModeKHR::FIFO); // always available per spec
+                                              // The one line that answers "did V-Sync off actually take?" — a request the surface
+                                              // can't serve is a fact about the driver, and it must not look like our choice.
+    if chosen != chain[0] {
+        tracing::info!(
+            requested = ?chain[0],
+            active = ?chosen,
+            vsync = pref.vsync,
+            allow_vrr = pref.allow_vrr,
+            "the surface does not offer the preferred present mode"
+        );
+    }
+    Ok(chosen)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use vk::PresentModeKHR as M;
+
+    /// The preference ladders (WP3). Every chain must end at FIFO, which the spec
+    /// guarantees exists — a chain whose entries a surface all refuses would otherwise
+    /// have no landing.
+    #[test]
+    fn present_mode_chains_rank_by_intent() {
+        let pref = |vsync, allow_vrr, fullscreen| PresentPref {
+            vsync,
+            allow_vrr,
+            fullscreen,
+            vrr_fifo_opt_in: true, // the ladder under test; the DEFAULT is off (see below)
+            fifo_latest_ready: false,
+        };
+        let flr = fifo_latest_ready::MODE;
+
+        // V-Sync off asks to tear, hardest first, and outranks the VRR rule (tearing
+        // already gives a VRR-like latch, so the two never fight).
+        assert_eq!(present_mode_chain(pref(false, true, true))[0], M::IMMEDIATE);
+        assert_eq!(
+            present_mode_chain(pref(false, false, false))[0],
+            M::IMMEDIATE
+        );
+        assert_eq!(
+            present_mode_chain(pref(false, true, true))[1],
+            M::FIFO_RELAXED,
+            "tears only on a late frame — the gentler tearing rung"
+        );
+
+        // Tear-free + VRR allowed + fullscreen prefers the vblank-locked family — but
+        // ONLY when opted in.
+        assert_eq!(present_mode_chain(pref(true, true, true))[0], M::FIFO);
+        // Without the opt-in the shipped MAILBOX-first default stands: measured on glass
+        // to be ~27 ms of display stage better on a non-VRR panel.
+        assert_eq!(
+            present_mode_chain(PresentPref {
+                vsync: true,
+                allow_vrr: true,
+                fullscreen: true,
+                vrr_fifo_opt_in: false,
+                fifo_latest_ready: false,
+            })[0],
+            M::MAILBOX,
+            "without a queue-free vblank mode the VRR ladder would lead with plain FIFO, \
+             which measured ~27 ms worse — so it stays opt-in there"
+        );
+        assert_eq!(
+            present_mode_chain(PresentPref {
+                vsync: true,
+                allow_vrr: true,
+                fullscreen: true,
+                vrr_fifo_opt_in: false,
+                fifo_latest_ready: true,
+            })[0],
+            fifo_latest_ready::MODE,
+            "with LATEST_READY available, following the panel costs 0.6 ms over MAILBOX \
+             instead of 27 — cheap enough to be automatic"
+        );
+
+        // FIFO_LATEST_READY only appears where the device enabled it, and it outranks
+        // plain FIFO everywhere: it is FIFO's vblank pacing WITHOUT the queue, which is
+        // what a MAILBOX-less surface otherwise needs the software glass gate for.
+        let with_flr = |vsync, allow_vrr, fullscreen| PresentPref {
+            vsync,
+            allow_vrr,
+            fullscreen,
+            vrr_fifo_opt_in: true,
+            fifo_latest_ready: true,
+        };
+        for p in [
+            pref(true, false, false),
+            pref(true, true, true),
+            pref(false, true, true),
+        ] {
+            assert!(
+                !present_mode_chain(p).contains(&flr),
+                "never requested unless the device enabled the extension"
+            );
+        }
+        let default_flr = present_mode_chain(with_flr(true, false, false));
+        assert_eq!(
+            default_flr[0],
+            M::MAILBOX,
+            "MAILBOX still leads by measurement"
+        );
+        assert_eq!(default_flr[1], flr, "then the driver-native newest-wins");
+        assert!(
+            default_flr.iter().position(|m| *m == flr)
+                < default_flr.iter().position(|m| *m == M::FIFO),
+            "LATEST_READY must outrank plain FIFO — it is FIFO minus the standing queue"
+        );
+        assert_eq!(
+            present_mode_chain(with_flr(true, true, true))[0],
+            flr,
+            "the VRR ladder takes the queue-free vblank mode first"
+        );
+
+        // Every ladder can land: FIFO appears in all of them.
+        for p in [
+            pref(true, true, true),
+            pref(true, true, false),
+            pref(true, false, true),
+            pref(false, true, true),
+            pref(false, false, false),
+            with_flr(true, false, false),
+        ] {
+            assert!(
+                present_mode_chain(p).contains(&M::FIFO),
+                "FIFO is the guaranteed landing"
+            );
+        }
+    }
 }
@@ -407,13 +407,21 @@ pub fn open(compositor: Compositor) -> Result<Box<dyn VirtualDisplay>> {
        // The pf-vdisplay all-Rust IddCx driver is the sole virtual-display backend (the legacy SudoVDA
        // fallback was removed — its driver is no longer shipped). The compositor arg is moot on Windows.
        let _ = compositor;
-        // `ensure_available` self-heals the hostless-zombie state a WUDFHost crash leaves (adapter
-        // devnode present, interface gone): one device cycle + re-probe before giving up.
-        anyhow::ensure!(
-            driver::ensure_available(),
-            "pf-vdisplay driver interface not found — the pf-vdisplay IddCx driver is not installed or \
-             not loaded (the host installer bundles it; reinstall or check the driver state)"
-        );
+        // `ensure_available` waits out a devnode that is merely coming up (the wake-from-sleep case:
+        // the adapter re-enters D0 and re-registers its interface while a reconnecting client is
+        // already knocking) and self-heals the hostless-zombie state a WUDFHost crash leaves (adapter
+        // devnode present, interface gone) by reloading the adapter.
+        //
+        // `context`, not a replacement message: it reports WHY — how long it waited, whether a reload
+        // ran, how many interface instances were seen and in what state. A flat "the driver is not
+        // installed" is what a field report carried from a box whose driver was installed, started,
+        // and simply mid-resume, and it pointed every reader at the wrong problem.
+        use anyhow::Context as _;
+        driver::ensure_available().context(
+            "pf-vdisplay driver interface not available — the pf-vdisplay IddCx driver is not \
+             installed, not loaded, or did not finish coming back up (the host installer bundles \
+             it; reinstall or check the driver state)",
+        )?;
        Ok(Box::new(driver::PfVdisplayDisplay::new()?))
    }
    #[cfg(not(any(target_os = "linux", target_os = "windows")))]
@@ -425,6 +425,20 @@ pub fn control_device_handle() -> Option<HANDLE> {
    VDM.get().and_then(VirtualDisplayManager::device_handle)
 }

+/// Retire the cached control handle from OUTSIDE the manager, for a caller that KNOWS the device
+/// died — the adapter-reload recovery in [`crate::driver`], which tears the driver stack down and
+/// back up. Without it the stale handle survives into the next session's `IOCTL_ADD` and is only
+/// recovered by the gone-classified retry one failed IOCTL later.
+///
+/// Takes the `device` mutex, so it must NOT be called from inside it (notably not from
+/// `VdisplayDriver::open`, which `ensure_device` invokes while holding it). No-op before any backend
+/// opened the device.
+pub(crate) fn invalidate_cached_device(why: &str) {
+    if let Some(m) = VDM.get() {
+        m.invalidate_device(&anyhow::anyhow!("{why}"));
+    }
+}
+
 /// Re-commit the CURRENT display config under the manager `state` lock (the sole-topology-mutator
 /// contract of [`force_mode_reenumeration`]). The secure-desktop guard's actuator: the OS only
 /// reverts a path to its software-cursor default ON a mode commit, so standing the hardware-cursor
@@ -21,6 +21,7 @@ use std::ffi::c_void;
 use std::mem::size_of;
 use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle};
 use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};

 use anyhow::{Context, Result};
 use windows::core::{GUID, PCWSTR};
@@ -143,31 +144,70 @@ fn reap_ghost_monitors() -> u32 {
    }
 }

-/// Kick the pf-vdisplay ADAPTER device (disable → enable) — the in-process equivalent of
-/// `reset-pf-vdisplay.ps1` step 3. A crashed/killed WUDFHost can leave the devnode "started" yet
-/// HOSTLESS (PnP Status OK, no WUDFHost process, zero device-interface instances) — a zombie no
-/// session can open until the stack reloads; on-glass, only a device cycle recovered it. Called by
-/// [`VdisplayDriver::open`] when `open_device` finds no openable interface; the caller retries the
-/// open afterwards. Best-effort + bounded (~7 s inside the script). Returns whether a punktfunk
-/// adapter devnode was found (and therefore cycled) — `false` means the driver genuinely is not
-/// installed and a retry is pointless.
-fn restart_vdisplay_device() -> bool {
+/// What an adapter-cycle attempt actually DID — deliberately NOT the devnode's PnP status afterwards.
+/// The old script reported that status, and a device it had failed to touch at all still reads `OK`,
+/// so a no-op cycle was indistinguishable from a real one in the log (field report 2026-08-02: a
+/// woken host logged `cycled … status=OK` and then failed the session for a missing interface).
+enum AdapterCycle {
+    /// The driver stack was genuinely reloaded. `how` names the lever that worked.
+    Reloaded { how: &'static str, status: String },
+    /// No punktfunk adapter devnode exists at all — the driver is not installed and retrying is
+    /// pointless.
+    NotInstalled,
+    /// A devnode exists but could not be reloaded; carries the reason (already whitespace-collapsed).
+    Refused(String),
+}
+
+/// Reload the pf-vdisplay ADAPTER device — the in-process equivalent of `reset-pf-vdisplay.ps1`
+/// step 3. A crashed/killed WUDFHost can leave the devnode "started" yet HOSTLESS (PnP Status OK, no
+/// WUDFHost process, zero device-interface instances) — a zombie no session can open until the stack
+/// reloads; on-glass, only a device reload recovered it.
+///
+/// Two levers, in order. `Disable-PnpDevice` + `Enable-PnpDevice` is the one `reset-pf-vdisplay.ps1`
+/// uses — but that script stops the host service FIRST, precisely because the host holds the driver's
+/// control device open (its step 1), and a disable can be refused for a device in use. This runs
+/// INSIDE the host, so it structurally cannot take that step: the retired-but-never-closed handles in
+/// [`DeviceSlot`](super::manager) are still open on the very device being disabled. So a refusal is
+/// the expected case here, not the exotic one, and `pnputil /restart-device` — which reloads a device
+/// that is in use — is the fallback. Whichever runs, the failure paths re-enable, so a half-completed
+/// cycle can never leave the adapter DISABLED.
+///
+/// Best-effort + bounded (~6 s inside the script).
+fn reload_vdisplay_adapter() -> AdapterCycle {
    // Mirrors reset-pf-vdisplay.ps1's Get-PfAdapter selector ('punktfunk Virtual Display' is the INF
-    // device description — locale-invariant). Same spawn shape as `reap_ghost_monitors` above.
+    // device description — locale-invariant). Same spawn shape as `reap_ghost_monitors` above; the
+    // reported tokens are ours, so parsing them is locale-invariant too.
+    //
+    // Every step that can fail is `-ErrorAction Stop` inside a `try` — the old script ran the whole
+    // cycle under `SilentlyContinue` and then reported `(Get-PnpDevice …).Status`, which reports the
+    // DEVICE, not the cycle: a disable that was refused left the device untouched, started, and
+    // reading `OK`, so the host logged a successful recovery it had never performed.
+    //
+    // `$LASTEXITCODE = 1` before the pnputil call for the same reason: no native command runs before
+    // it, so an unlaunchable pnputil would otherwise leave the variable holding whatever it held and
+    // let "never ran" read as "returned 0". Pre-seeding a failure means only a real exit 0 reports a
+    // reload. pnputil is resolved by full path — a LocalSystem service's PATH need not include
+    // System32.
    const CYCLE_PS: &str = "$ErrorActionPreference='SilentlyContinue'; \
        $ad = Get-PnpDevice -Class Display | Where-Object { $_.FriendlyName -match 'punktfunk Virtual Display' } | Select-Object -First 1; \
-        if ($ad) { \
-            Disable-PnpDevice -InstanceId $ad.InstanceId -Confirm:$false; Start-Sleep -Seconds 3; \
-            Enable-PnpDevice -InstanceId $ad.InstanceId -Confirm:$false; Start-Sleep -Seconds 3; \
-            $st = (Get-PnpDevice -InstanceId $ad.InstanceId).Status; \
-            if ($st -ne 'OK') { Enable-PnpDevice -InstanceId $ad.InstanceId -Confirm:$false; Start-Sleep -Seconds 2; \
-                $st = (Get-PnpDevice -InstanceId $ad.InstanceId).Status }; \
-            Write-Output $st \
-        } else { Write-Output 'ABSENT' }";
+        if (-not $ad) { Write-Output 'ABSENT'; exit }; \
+        $id = $ad.InstanceId; $err = ''; \
+        try { \
+            Disable-PnpDevice -InstanceId $id -Confirm:$false -ErrorAction Stop; Start-Sleep -Seconds 2; \
+            try { Enable-PnpDevice -InstanceId $id -Confirm:$false -ErrorAction Stop } \
+            catch { Start-Sleep -Seconds 2; Enable-PnpDevice -InstanceId $id -Confirm:$false -ErrorAction Stop }; \
+            Start-Sleep -Seconds 2; \
+            Write-Output ('RELOADED cycle ' + (Get-PnpDevice -InstanceId $id).Status); exit \
+        } catch { $err = ($_.Exception.Message -replace '\\s+', ' ') }; \
+        $pnp = ($env:SystemRoot + '\\System32\\pnputil.exe'); $LASTEXITCODE = 1; \
+        if (Test-Path $pnp) { & $pnp /restart-device $id *> $null }; \
+        if ($LASTEXITCODE -eq 0) { Start-Sleep -Seconds 2; \
+            Write-Output ('RELOADED restart ' + (Get-PnpDevice -InstanceId $id).Status) } \
+        else { Enable-PnpDevice -InstanceId $id -Confirm:$false; Write-Output ('REFUSED ' + $err) }";
    let ps = std::env::var("SystemRoot")
        .map(|r| format!(r"{r}\System32\WindowsPowerShell\v1.0\powershell.exe"))
        .unwrap_or_else(|_| "powershell.exe".to_string());
-    match std::process::Command::new(&ps)
+    let out = match std::process::Command::new(&ps)
        .args([
            "-NoProfile",
            "-NonInteractive",
@@ -178,22 +218,65 @@ fn restart_vdisplay_device() -> bool {
        ])
        .output()
    {
-        Ok(o) => {
-            let status = String::from_utf8_lossy(&o.stdout).trim().to_string();
-            if status == "ABSENT" {
-                tracing::warn!("pf-vdisplay: no adapter devnode to cycle — driver not installed");
-            } else {
-                tracing::warn!(
-                    %status,
-                    "pf-vdisplay: cycled the adapter device (hostless-zombie recovery)"
-                );
-            }
-            status != "ABSENT"
-        }
+        Ok(o) => String::from_utf8_lossy(&o.stdout).trim().to_string(),
        Err(e) => {
-            tracing::warn!(error = %e, "pf-vdisplay: adapter cycle could not spawn powershell");
-            false
+            tracing::warn!(error = %e, "pf-vdisplay: adapter reload could not spawn powershell");
+            return AdapterCycle::Refused(format!("could not spawn powershell: {e}"));
        }
+    };
+    let outcome = classify_reload_output(&out);
+    match &outcome {
+        AdapterCycle::NotInstalled => {
+            tracing::warn!("pf-vdisplay: no adapter devnode to reload — driver not installed");
+        }
+        AdapterCycle::Reloaded { how, status } => tracing::warn!(
+            how,
+            %status,
+            "pf-vdisplay: reloaded the adapter device (hostless-zombie recovery)"
+        ),
+        AdapterCycle::Refused(why) => tracing::warn!(
+            reason = %why,
+            "pf-vdisplay: the adapter devnode exists but could NOT be reloaded — a session cannot \
+             recover from this without a host-service restart or a reboot"
+        ),
+    }
+    outcome
+}
+
+/// Parse [`reload_vdisplay_adapter`]'s script output. Split out to be testable without a box: the
+/// bug this whole change answers was a recovery that MISreported its own outcome, so the decoding of
+/// that outcome is worth pinning down.
+fn classify_reload_output(out: &str) -> AdapterCycle {
+    let out = out.trim();
+    let (verb, rest) = out.split_once(char::is_whitespace).unwrap_or((out, ""));
+    match verb {
+        "ABSENT" => AdapterCycle::NotInstalled,
+        "RELOADED" => {
+            let (how, status) = rest
+                .trim()
+                .split_once(char::is_whitespace)
+                .unwrap_or((rest.trim(), ""));
+            // Held as `&'static str` so the two levers stay distinguishable in a field report:
+            // `restart` means the disable was refused, i.e. something still holds the device open —
+            // worth knowing when a reload does not fix the box.
+            let how: &'static str = if how == "restart" {
+                "pnputil /restart-device"
+            } else {
+                "disable+enable"
+            };
+            AdapterCycle::Reloaded {
+                how,
+                status: status.trim().to_string(),
+            }
+        }
+        // Covers `REFUSED <reason>` and anything unrecognised, including an empty stdout (powershell
+        // died before writing). All of them mean an un-reloaded devnode, which is the only thing
+        // callers act on; the text rides along for the log.
+        _ => AdapterCycle::Refused(if rest.trim().is_empty() {
+            format!("unexpected adapter-reload output: {out:?}")
+        } else {
+            rest.trim().to_string()
+        }),
    }
 }

@@ -325,6 +408,55 @@ impl Drop for DevInfoList {
    }
 }

+/// What a device-interface enumeration found. The counts are what let [`ensure_available`] tell a
+/// devnode that is MID-TRANSITION (present, interface registered, not started yet — resuming from
+/// sleep, restarting, reloading) apart from one that is genuinely gone. Only the second is worth
+/// answering with device surgery; cycling the first only lengthens the outage it is waiting out.
+struct Probe {
+    /// The control handle, if any interface instance opened.
+    handle: Option<OwnedHandle>,
+    /// Instances seen with `SPINT_ACTIVE` set — the owning device is started.
+    active: u32,
+    /// Instances seen with `SPINT_ACTIVE` clear — registered, but the owning device is not started.
+    inactive: u32,
+    /// The last enumeration/open failure, kept for the diagnostic.
+    last_err: Option<anyhow::Error>,
+}
+
+impl Probe {
+    /// No interface instance of ANY kind. With an adapter devnode present this is the hostless-zombie
+    /// state a WUDFHost crash leaves; with none, the driver is not installed. Either way, waiting
+    /// alone will not fix it.
+    fn is_absent(&self) -> bool {
+        self.handle.is_none() && self.active == 0 && self.inactive == 0
+    }
+
+    /// Why no handle came back, NAMING what was seen — "0 interfaces" and "1 inactive interface" are
+    /// completely different diagnoses (not installed vs. still coming up), and the old message
+    /// collapsed both into "is the driver installed?". Call only on a miss; a hit reports as much.
+    fn into_error(self) -> anyhow::Error {
+        let seen = format!("{} active, {} inactive", self.active, self.inactive);
+        if self.handle.is_some() {
+            return anyhow::anyhow!("pf-vdisplay device interface opened ({seen})");
+        }
+        match self.last_err {
+            Some(e) => e.context(format!("no openable pf-vdisplay device interface ({seen})")),
+            None => anyhow::anyhow!(
+                "no pf-vdisplay device interface found ({seen}) — is the pf-vdisplay driver \
+                 installed and its device started?"
+            ),
+        }
+    }
+
+    /// Consume into the [`open_device`] result.
+    fn into_result(mut self) -> Result<OwnedHandle> {
+        match self.handle.take() {
+            Some(h) => Ok(h),
+            None => Err(self.into_error()),
+        }
+    }
+}
+
 /// Open the pf-vdisplay control device.
 ///
 /// SAFE, and owning. It has no caller obligation — it takes no arguments and every precondition is
@@ -333,26 +465,40 @@ impl Drop for DevInfoList {
 /// this file has already leaked from once (see the wrap-IMMEDIATELY comment in `open`). Returning an
 /// `OwnedHandle` makes the close a `Drop`, so there is exactly one way to get it wrong: not at all.
 fn open_device() -> Result<OwnedHandle> {
+    probe_device().into_result()
+}
+
+/// [`open_device`], reporting WHAT it found rather than only whether it succeeded.
+fn probe_device() -> Probe {
+    let mut probe = Probe {
+        handle: None,
+        active: 0,
+        inactive: 0,
+        last_err: None,
+    };
    // SAFETY: plain SetupAPI enumeration call; the returned list is solely owned by the RAII wrapper.
-    let hdev = DevInfoList(
-        unsafe {
-            SetupDiGetClassDevsW(
-                Some(&PF_VDISPLAY_INTERFACE),
-                PCWSTR::null(),
-                None,
-                DIGCF_DEVICEINTERFACE | DIGCF_PRESENT,
-            )
+    let hdev = match unsafe {
+        SetupDiGetClassDevsW(
+            Some(&PF_VDISPLAY_INTERFACE),
+            PCWSTR::null(),
+            None,
+            DIGCF_DEVICEINTERFACE | DIGCF_PRESENT,
+        )
+    }
+    .context("SetupDiGetClassDevsW(pf-vdisplay) — is the pf-vdisplay driver installed?")
+    {
+        Ok(h) => DevInfoList(h),
+        Err(e) => {
+            probe.last_err = Some(e);
+            return probe;
        }
-        .context("SetupDiGetClassDevsW(pf-vdisplay) — is the pf-vdisplay driver installed?")?,
-    );
+    };

    // Enumerate EVERY interface instance, not just index 0: after a driver upgrade a present-but-
    // failed devnode (Code 10) can hold index 0 while the LIVE node's interface sits at a later
    // index — the old single-index read then failed every session with "driver not installed"
    // even though a working interface existed. `SPINT_ACTIVE` filters dead interfaces (an interface
    // is active only while its owning device is started); the first active + openable one wins.
-    let mut inactive = 0u32;
-    let mut last_err: Option<anyhow::Error> = None;
    for index in 0..64u32 {
        let mut idata = SP_DEVICE_INTERFACE_DATA {
            cbSize: size_of::<SP_DEVICE_INTERFACE_DATA>() as u32,
@@ -367,9 +513,10 @@ fn open_device() -> Result<OwnedHandle> {
            break; // ERROR_NO_MORE_ITEMS — no further candidates
        }
        if idata.Flags & SPINT_ACTIVE == 0 {
-            inactive += 1;
+            probe.inactive += 1;
            continue;
        }
+        probe.active += 1;
        let mut required = 0u32;
        // SAFETY: sizing call — null buffer plus a valid `required` out-param; the expected
        // ERROR_INSUFFICIENT_BUFFER "failure" is ignored and only `required` is consumed.
@@ -409,20 +556,18 @@ fn open_device() -> Result<OwnedHandle> {
                })
        };
        match opened {
-            // SAFETY: `h` is the handle `CreateFileW` just returned to THIS call and nothing else
-            // holds it, so transferring it into the `OwnedHandle` gives it a single owner that
-            // closes it exactly once on drop.
-            Ok(h) => return Ok(unsafe { OwnedHandle::from_raw_handle(h.0 as _) }),
+            Ok(h) => {
+                // SAFETY: `h` is the handle `CreateFileW` just returned to THIS call and nothing
+                // else holds it, so transferring it into the `OwnedHandle` gives it a single owner
+                // that closes it exactly once on drop.
+                probe.handle = Some(unsafe { OwnedHandle::from_raw_handle(h.0 as _) });
+                return probe;
+            }
            // A raced-away or wedged device — remember the error, try the next interface.
-            Err(e) => last_err = Some(e),
+            Err(e) => probe.last_err = Some(e),
        }
    }
-    Err(last_err.unwrap_or_else(|| {
-        anyhow::anyhow!(
-            "no ACTIVE pf-vdisplay device interface found ({inactive} inactive) — is the \
-             pf-vdisplay driver installed and its device started?"
-        )
-    }))
+    probe
 }

 /// The pf-vdisplay IOCTL surface behind the shared [`VirtualDisplayManager`](super::manager::VirtualDisplayManager)
@@ -435,29 +580,14 @@ impl VdisplayDriver for PfVdisplayDriver {
    }

    unsafe fn open(&self, reap_orphans: bool) -> Result<(OwnedHandle, u32, u32)> {
-        let device = match open_device() {
-            Ok(d) => d,
-            Err(first) => {
-                // No openable interface. If a WUDFHost crash left the devnode a hostless zombie
-                // (validated on-glass: PnP Status OK, zero interface instances), a device cycle
-                // reloads the stack — kick it once and retry the open over a short arrival window.
-                if !restart_vdisplay_device() {
-                    return Err(first); // no adapter devnode at all — genuinely not installed
-                }
-                let mut reopened = Err(first);
-                for _ in 0..8 {
-                    std::thread::sleep(std::time::Duration::from_millis(500));
-                    match open_device() {
-                        Ok(d) => {
-                            reopened = Ok(d);
-                            break;
-                        }
-                        Err(e) => reopened = Err(e),
-                    }
-                }
-                reopened.context("pf-vdisplay interface still absent after an adapter cycle")?
-            }
-        };
+        // A short re-probe, and deliberately NO adapter reload — this replaces the second, impatient
+        // copy of the recovery that used to live here. Session bring-up already ran the full
+        // `ensure_available` before constructing the backend, so anything left for this open to
+        // absorb is a race, not a wedge. `hw_cursor_capable` also lands here, mid client handshake,
+        // where a reload's tens of seconds would be entirely the wrong trade for one capability bool
+        // — and where reloading would deadlock besides, since `ensure_device` calls us holding the
+        // manager's `device` mutex (see the `RECOVERY` ordering contract).
+        let device = wait_for_interface(BRIEF_RETRY, false).0?;
        // `open_device` hands back an `OwnedHandle`, so every `?` below closes the device exactly
        // once by construction — the shape this used to reach by wrapping the raw handle here, and
        // which leaked whenever GET_INFO itself failed before that wrap was moved up.
@@ -879,25 +1009,159 @@ pub fn is_available() -> bool {
    open_device().is_ok()
 }

-/// [`is_available`], with self-heal: an interface-less driver whose adapter devnode EXISTS is the
-/// hostless-zombie state a WUDFHost crash leaves behind (validated on-glass — PnP reports Status OK
-/// with no WUDFHost process and zero interface instances, and every session fails at this gate until
-/// the device reloads). Cycle the adapter once and re-probe over a short arrival window. A genuinely
-/// uninstalled driver (no adapter devnode) fails fast without the wait.
-pub fn ensure_available() -> bool {
-    if is_available() {
-        return true;
+/// How often the interface is re-probed while waiting.
+const PROBE_INTERVAL: Duration = Duration::from_millis(500);
+
+/// How long a devnode whose interface exists but is NOT-READY (no active instance, or `CreateFileW`
+/// refused) is given to come up on its own before the adapter is reloaded.
+///
+/// This is the wake-from-sleep window. Resuming re-enters D0 and re-registers the interface while
+/// the rest of the resume storm is still running, and a client reconnecting a second after wake
+/// arrives inside that gap — which the old code, probing exactly ONCE, answered by disabling and
+/// re-enabling a display adapter that was seconds from being ready anyway.
+const NOT_READY_GRACE: Duration = Duration::from_secs(15);
+
+/// How long a fully ABSENT interface is given before the adapter is reloaded. Short — a hostless
+/// devnode does not heal itself, and that is the case this recovery exists for — but non-zero, so a
+/// resume that briefly de-registers the interface is not met with device surgery either.
+const ABSENT_SETTLE: Duration = Duration::from_secs(3);
+
+/// How long the interface is given to ARRIVE after a reload.
+///
+/// Was 4 s, which a quiet box meets and a box still finishing a resume does not: PnP is contended
+/// right after wake. Field report 2026-08-02 — a woken host logged a successful adapter cycle and
+/// then failed the session 4 s later for a missing interface, and the client could not connect.
+const ARRIVAL_AFTER_RELOAD: Duration = Duration::from_secs(15);
+
+/// Hard ceiling on the whole wait, so display prep can never block for an unbounded sum of the
+/// windows above. Without it a devnode wedged NOT-READY costs the full grace, then the reload, then
+/// the full arrival window before failing — the pathological case paying nearly a minute per session.
+/// Patience for a device that is coming back is the point; patience for one that never will is not.
+const TOTAL_BUDGET: Duration = Duration::from_secs(30);
+
+/// The budget a caller that must NOT stall gives the interface: no adapter reload, just a short
+/// re-probe to ride out a race. [`VdisplayDriver::open`] uses it — by the time the manager opens,
+/// session bring-up has already run the full [`ensure_available`] above, and the OTHER path that
+/// reaches it (`manager::hw_cursor_capable`, a best-effort capability answer during the client
+/// handshake) must never hold the Welcome for tens of seconds to decide one bool.
+const BRIEF_RETRY: Duration = Duration::from_secs(3);
+
+/// Serializes the recovery so N sessions racing in after a wake perform ONE adapter reload between
+/// them rather than N interleaved ones — each of which tears down the stack the others are waiting
+/// on. The second caller through typically finds the interface already up and returns at once.
+///
+/// Taken ONLY by [`ensure_available`], which holds no manager lock, and released before the retire
+/// hook below takes the manager's `device` mutex. That is what keeps the lock order one-way:
+/// [`VdisplayDriver::open`] runs *inside* that same `device` mutex, so if it could also take this
+/// lock the two orders would invert and deadlock. It cannot — it never reloads.
+static RECOVERY: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+/// [`is_available`], with self-heal — and with PATIENCE, which is the part that matters after a
+/// wake from sleep.
+///
+/// Returns the reason on failure instead of a bare `false`: the caller used to replace it with a
+/// flat "the driver is not installed", which is what a field report showed on a box whose driver was
+/// installed, started, and merely mid-resume.
+pub fn ensure_available() -> Result<()> {
+    // Poisoning carries no meaning here — the guard protects a `()`, not state a panic could leave
+    // inconsistent — so a previous panic must not wedge every later session out of recovery.
+    let (result, reloaded) = {
+        let _serialize = RECOVERY.lock().unwrap_or_else(|e| e.into_inner());
+        wait_for_interface(NOT_READY_GRACE, true)
+    };
+    // OUTSIDE the recovery lock, by the ordering contract on `RECOVERY`. A reload tore the driver
+    // stack down and back up, so any control handle a previous session cached is dead by
+    // construction — retire it while we know that for certain, rather than leaving the next session
+    // to discover it by having an IOCTL fail. No-op before any backend opened the device.
+    if reloaded {
+        super::manager::invalidate_cached_device(
+            "the pf-vdisplay adapter was reloaded (hostless-zombie recovery)",
+        );
    }
-    if !restart_vdisplay_device() {
-        return false;
-    }
-    for _ in 0..8 {
-        std::thread::sleep(std::time::Duration::from_millis(500));
-        if is_available() {
-            return true;
+    result.map(|_| ())
+}
+
+/// Wait for an openable control interface, reloading the adapter if `reload` and the devnode looks
+/// genuinely hostless. Returns the handle (so the manager's own open can keep it) alongside whether
+/// a reload ran.
+///
+/// Two distinguishable states hide behind "cannot open the interface", and they want opposite
+/// treatment:
+///
+/// * **Not ready** — instances are registered but none is active (or the open is refused). The
+///   devnode is THERE and coming up: resuming from sleep, restarting, reloading. It heals itself;
+///   reloading the adapter underneath it only lengthens the outage.
+/// * **Absent** — no instance at all. With an adapter devnode present this is the hostless-zombie
+///   state a WUDFHost crash leaves (validated on-glass: PnP Status OK, no WUDFHost process, zero
+///   interface instances). Only a reload clears it.
+///
+/// So: probe, wait out a not-ready device, reload an absent one after a short settle, and give the
+/// interface a real arrival window afterwards. A reload is still attempted once at the end of
+/// `not_ready_grace`, so a devnode wedged not-ready (a failed start) recovers exactly as it did
+/// before. A genuinely uninstalled driver — no adapter devnode — still fails FAST, with no wait.
+fn wait_for_interface(not_ready_grace: Duration, reload: bool) -> (Result<OwnedHandle>, bool) {
+    let started = Instant::now();
+    let mut deadline = started + not_ready_grace;
+    let mut absent_since: Option<Instant> = None;
+    let mut reloaded = false;
+    loop {
+        let mut probe = probe_device();
+        if let Some(h) = probe.handle.take() {
+            if reloaded || started.elapsed() > PROBE_INTERVAL {
+                tracing::info!(
+                    waited_ms = started.elapsed().as_millis() as u64,
+                    reloaded,
+                    "pf-vdisplay: control interface available"
+                );
+            }
+            return (Ok(h), reloaded);
        }
+        // Track how long we have seen NOTHING. Reset by any sighting, so a device that flickers
+        // between absent and not-ready is treated as the transition it is.
+        if probe.is_absent() {
+            absent_since.get_or_insert_with(Instant::now);
+        } else {
+            absent_since = None;
+        }
+        let absent_long_enough = absent_since.is_some_and(|t| t.elapsed() >= ABSENT_SETTLE);
+        if reload && !reloaded && (absent_long_enough || Instant::now() >= deadline) {
+            match reload_vdisplay_adapter() {
+                // No devnode at all — waiting cannot conjure a driver. Fail immediately rather than
+                // burning the arrival window on a box that simply does not have it installed.
+                AdapterCycle::NotInstalled => {
+                    let e = Err(probe.into_error()).context(
+                        "no punktfunk virtual-display adapter devnode exists — the driver is not \
+                         installed",
+                    );
+                    return (e, reloaded);
+                }
+                AdapterCycle::Refused(why) => {
+                    let e = Err(probe.into_error()).context(format!(
+                        "the pf-vdisplay adapter devnode could not be reloaded ({why})"
+                    ));
+                    return (e, reloaded);
+                }
+                AdapterCycle::Reloaded { .. } => {
+                    reloaded = true;
+                    absent_since = None;
+                    deadline = (Instant::now() + ARRIVAL_AFTER_RELOAD).min(started + TOTAL_BUDGET);
+                }
+            }
+        }
+        if Instant::now() >= deadline {
+            let e = Err(probe.into_error()).context(format!(
+                "the pf-vdisplay control interface did not appear within {:?}{}",
+                started.elapsed(),
+                if reloaded {
+                    " (including an adapter reload)"
+                } else {
+                    ""
+                }
+            ));
+            return (e, reloaded);
+        }
+        std::thread::sleep(PROBE_INTERVAL);
    }
-    false
 }

 #[cfg(test)]
@@ -906,6 +1170,96 @@ mod tests {
    use std::thread;
    use std::time::Duration;

+    /// The recovery must not be able to claim success it did not achieve. This is the whole bug:
+    /// the old script ran the cycle under `SilentlyContinue` and reported `(Get-PnpDevice).Status`,
+    /// so a device whose disable had been REFUSED — untouched, still started — reported `OK`, and
+    /// the host logged `cycled the adapter device … status=OK` while nothing had been cycled at all
+    /// (field report 2026-08-02). A refusal must decode as a refusal, carrying its reason.
+    #[test]
+    fn a_refused_reload_is_not_reported_as_a_reload() {
+        let refused =
+            classify_reload_output("REFUSED This device cannot be disabled because it is in use.");
+        match refused {
+            AdapterCycle::Refused(why) => {
+                assert!(why.contains("in use"), "the reason must survive: {why:?}")
+            }
+            other => panic!("a refused reload decoded as {}", variant(&other)),
+        }
+        // A bare device status — what the OLD script emitted on every path — must NEVER decode as a
+        // successful reload now, however healthy it looks.
+        for stale in ["OK", "Error", "Unknown"] {
+            assert!(
+                matches!(classify_reload_output(stale), AdapterCycle::Refused(_)),
+                "{stale:?} is a device status, not a reload outcome"
+            );
+        }
+    }
+
+    /// The outcomes callers branch on: `NotInstalled` fails a session fast, `Reloaded` earns the
+    /// arrival window, and the lever that worked stays visible in the log (`restart` means the
+    /// disable was refused and something still holds the device open).
+    #[test]
+    fn reload_outcomes_decode() {
+        assert!(matches!(
+            classify_reload_output("ABSENT"),
+            AdapterCycle::NotInstalled
+        ));
+        match classify_reload_output("RELOADED cycle OK") {
+            AdapterCycle::Reloaded { how, status } => {
+                assert_eq!(how, "disable+enable");
+                assert_eq!(status, "OK");
+            }
+            other => panic!("expected Reloaded, got {}", variant(&other)),
+        }
+        match classify_reload_output("RELOADED restart OK\r\n") {
+            AdapterCycle::Reloaded { how, status } => {
+                assert_eq!(how, "pnputil /restart-device");
+                assert_eq!(status, "OK");
+            }
+            other => panic!("expected Reloaded, got {}", variant(&other)),
+        }
+        // powershell died before writing anything — an un-reloaded devnode, so `Refused`, not a
+        // silent success.
+        assert!(matches!(
+            classify_reload_output("   "),
+            AdapterCycle::Refused(_)
+        ));
+    }
+
+    /// `is_absent` is what decides between WAITING and performing device surgery, so the two states
+    /// it separates are pinned here. An interface that is registered but not yet ACTIVE is a devnode
+    /// mid-transition — the wake-from-sleep case — and reloading the adapter under it only lengthens
+    /// the outage it is already recovering from.
+    #[test]
+    fn only_a_total_absence_counts_as_absent() {
+        let probe = |active, inactive| Probe {
+            handle: None,
+            active,
+            inactive,
+            last_err: None,
+        };
+        assert!(probe(0, 0).is_absent(), "no instances at all = absent");
+        assert!(
+            !probe(0, 1).is_absent(),
+            "a registered-but-inactive instance is a device coming up, not a missing one"
+        );
+        assert!(
+            !probe(1, 0).is_absent(),
+            "an active instance we merely failed to open is not a missing device"
+        );
+        // And the diagnostic names what was seen — the old message collapsed every one of these
+        // into "is the driver installed?", which sent a field report down the wrong path.
+        assert!(probe(0, 2).into_error().to_string().contains("2 inactive"));
+    }
+
+    fn variant(c: &AdapterCycle) -> &'static str {
+        match c {
+            AdapterCycle::Reloaded { .. } => "Reloaded",
+            AdapterCycle::NotInstalled => "NotInstalled",
+            AdapterCycle::Refused(_) => "Refused",
+        }
+    }
+
    /// Live hardware round trip — `#[ignore]`d (needs the pf-vdisplay driver installed); run with
    /// `cargo test -p pf-vdisplay -- --ignored live_create_drop`. Exercises the real trait path: open -> create -> hold -> drop (REMOVE).
    #[test]
@@ -24,17 +24,19 @@
 //! AIMD shape: a SEVERE window (an unrecoverable frame, a flush, ≥6 % loss, or a decode-latency
 //! excursion far past baseline) backs off ×0.7 immediately; ordinary congestion
 //! (heavy-but-recoverable loss, an OWD rise, a decode rise) needs two consecutive bad windows.
-//! Recovery is two-mode: **slow start** — until the first congestion signal the rate DOUBLES each
-//! clean window (cooldown-paced), which is how an Automatic session climbs from the conservative
-//! start to the [`set_ceiling`](BitrateController::set_ceiling) measured by the startup
-//! link-capacity probe in seconds instead of minutes — then classic additive recovery (+~6 %
-//! after ~4.5 s clean, ceilinged). Changes are rate-limited (each one costs the IDR the host's
+//! Recovery is two-mode: **slow start** — until the first congestion signal each clean window
+//! asks for double the current rate, bounded (like every climb) by the proven-throughput
+//! headroom below, so the step a loaded session actually takes is ×1.5 over what it last
+//! delivered; either way it climbs from the conservative start to the
+//! [`set_ceiling`](BitrateController::set_ceiling) measured by the startup link-capacity probe
+//! in seconds rather than minutes — then classic additive recovery (+~6 % after ~4.5 s clean,
+//! ceilinged). Changes are rate-limited (each one costs the IDR the host's
 //! rebuilt encoder opens with) and the whole controller disables itself against a host that never
 //! answers [`crate::quic::BitrateChanged`] (an older build that ignores unknown control messages).
 //! Standing limits are LEARNED rather than re-poked: two identical short host acks latch the
 //! encoder's ceiling (`host_cap_kbps`), two consecutive decode-severe backoffs at a similar rate
 //! latch the client decoder's knee (`decode_cap_kbps`) — and both re-probe slowly
-//! ([`CAP_REPROBE_WINDOWS`]) so neither latch outlives the condition that taught it.
+//! ([`CAP_REPROBE_WINDOWS_MIN`]) so neither latch outlives the condition that taught it.
 //!
 //! Climbs are additionally **evidence-gated**. The target is only a *promise* to the encoder —
 //! how many bits it actually emits depends on the content — so on calm content (a menu, an idle
@@ -128,15 +130,26 @@ const ENCODE_RISE_US: i64 = 4_000;
 /// Host-encode latency this far above baseline (≈1.5 × a 120 Hz budget) is SEVERE — the encode
 /// queue is growing past the knee; skip the two-window confirmation.
 const ENCODE_SEVERE_US: i64 = 12_000;
-/// Clean windows parked at the learned [`host cap`](BitrateController::host_cap_kbps) before
-/// re-probing above it (~60 s at the 750 ms tick). A cadence-refusal cap is scene-dependent
-/// evidence, not a spec limit — without a re-probe, one heavy scene would cap the whole
-/// session. A still-standing limit just re-teaches itself in two short acks, which the host
-/// pre-clamps without touching the encoder — the re-probe costs no rebuild, no IDR.
-/// The [`decode cap`](BitrateController::decode_cap_kbps) re-probes on the same clock for the
-/// same reason: the decoder's knee moves with content and thermals, so its latch must not be
-/// permanent either.
-const CAP_REPROBE_WINDOWS: u32 = 80;
+/// Clean windows parked at a learned cap before re-probing above it, and the ceiling that
+/// interval backs off to.
+///
+/// A learned cap is EVIDENCE, not a spec limit: the host's short ack means "not right now",
+/// which covers both its encoder's codec-level ceiling (durable) and a climb refused while
+/// encode is behind cadence (transient, and routinely latched during slow start at the
+/// conservative 20 Mbps default). The client cannot tell those apart from the ack alone, so the
+/// re-probe is what keeps a transient from becoming the session's ceiling — and a flat ~60 s
+/// clock at +12.5 % made that escape take upwards of twenty minutes to cross the gap to a
+/// probe-measured link ceiling, which is indistinguishable from never.
+///
+/// So: probe again after 12 s, and DOUBLE the interval each time the lift is immediately
+/// re-learned at the same value (see [`on_ack`](BitrateController::on_ack)). A transient is out
+/// in one interval; a standing limit settles into a slow poll instead of a permanent one. The
+/// re-probe itself is nearly free either way — a still-standing limit re-teaches itself in two
+/// short acks, which the host pre-clamps without touching the encoder: no rebuild, no IDR.
+/// The [`decode cap`](BitrateController::decode_cap_kbps) re-probes on the same schedule for
+/// the same reason: the decoder's knee moves with content and thermals.
+const CAP_REPROBE_WINDOWS_MIN: u32 = 16;
+const CAP_REPROBE_WINDOWS_MAX: u32 = 128;
 /// Two consecutive decode-driven backoffs latch the
 /// [`decode cap`](BitrateController::decode_cap_kbps) only when their pre-backoff rates agree
 /// within ±1/8: the decoder's knee is a RATE, so repeated chokes at the same rate are its
@@ -146,6 +159,17 @@ const DECODE_CAP_SIMILAR_DIV: u32 = 8;
 /// Rolling window (in 750 ms report windows, ~30 s) whose minimum mean is the OWD baseline.
 /// Long enough to remember the uncongested floor, short enough to follow genuine path changes.
 const BASELINE_WINDOWS: usize = 40;
+/// Windows a rolling baseline must hold before the signal it feeds may fire. A baseline is a
+/// rolling MINIMUM, so a single sample IS the baseline — and if that one window landed on calm
+/// content, ordinary content variance clears the rise threshold by itself. That hole is not
+/// theoretical: [`on_ack`](BitrateController::on_ack) deliberately CLEARS the encode baseline
+/// after every decrease we ourselves asked for, so the encode down-driver re-armed on a
+/// one-sample floor each time — a calm re-seed window followed by a motion scene reads as
+/// `ENCODE_RISE_US` of "congestion", backs off, clears again, and ratchets to the floor on a
+/// link that was never the problem. Four windows (3 s) of evidence before any of the three
+/// latency signals may fire costs a little reaction latency at session start and buys a floor
+/// that means something.
+const BASELINE_MIN_WINDOWS: usize = 4;
 /// Requests sent without a single [`crate::quic::BitrateChanged`] ack before concluding the host
 /// predates bitrate renegotiation and going quiet for the rest of the session.
 const MAX_UNACKED: u32 = 3;
@@ -167,6 +191,37 @@ fn ceiling_cap_from_env() -> Option<u32> {
        .map(|m| m.saturating_mul(1_000))
 }

+/// Score one window's latency sample against its rolling-min baseline, then record it.
+///
+/// Shared by all three latency signals (OWD, client decode, host encode) — same shape, different
+/// thresholds. `mean` is `None` when nobody reports the signal (no clock handshake, an embedder
+/// that doesn't measure decode, a host that ships no stage timings); the signal is then simply
+/// absent rather than clean, so it can neither mark a window bad nor teach a baseline.
+///
+/// The baseline is the minimum of the PRIOR windows — this window is compared before it is
+/// recorded, so a rising window can't drag its own floor up with it — and only counts once
+/// [`BASELINE_MIN_WINDOWS`] of them exist. Returns `(rise, severe)`; pass `i64::MAX` for
+/// `severe_us` on a signal with no severe tier.
+fn score_baseline(
+    means: &mut VecDeque<i64>,
+    mean: Option<i64>,
+    rise_us: i64,
+    severe_us: i64,
+) -> (bool, bool) {
+    let Some(mean) = mean else {
+        return (false, false);
+    };
+    let base = (means.len() >= BASELINE_MIN_WINDOWS)
+        .then(|| means.iter().min().copied())
+        .flatten();
+    let over = |t: i64| base.is_some_and(|b| mean > b.saturating_add(t));
+    if means.len() == BASELINE_WINDOWS {
+        means.pop_front();
+    }
+    means.push_back(mean);
+    (over(rise_us), over(severe_us))
+}
+
 /// One decision per report window; `Some(kbps)` = send a [`crate::quic::SetBitrate`].
 pub(crate) struct BitrateController {
    /// `false` = permanently off (explicit user bitrate, an old host, or ack silence).
@@ -199,7 +254,7 @@ pub(crate) struct BitrateController {
    /// asked twice consecutively at the same value — its encoder's codec-level ceiling, or a
    /// climb refusal while host encode can't hold cadence. Kept apart from `ceiling_kbps` so
    /// the probe-measured link authority survives a mode switch's reset. Slowly re-probed
-    /// ([`CAP_REPROBE_WINDOWS`]) so scene-dependent evidence can't cap the session forever.
+    /// ([`CAP_REPROBE_WINDOWS_MIN`]) so scene-dependent evidence can't cap the session forever.
    host_cap_kbps: Option<u32>,
    /// The rate the last [`request`](Self::request) asked for — the reference an ack is judged
    /// short against. Taken (not kept) by the ack, so one request is judged at most once.
@@ -210,8 +265,11 @@ pub(crate) struct BitrateController {
    /// deterministic min()s, so a persistent limit reproduces exactly.
    short_ack_kbps: u32,
    short_acks: u32,
-    /// Clean windows spent parked at the learned cap (the re-probe clock).
+    /// Clean windows spent parked at the learned cap (the re-probe clock) and the interval it is
+    /// counting toward — [`CAP_REPROBE_WINDOWS_MIN`], doubled toward
+    /// [`CAP_REPROBE_WINDOWS_MAX`] each time a lift is immediately re-learned.
    cap_probe_windows: u32,
+    cap_reprobe_after: u32,
    /// The client-decoder rate cap, mirroring [`host_cap_kbps`](Self::host_cap_kbps) for the
    /// OTHER end of the pipe: latched when two CONSECUTIVE backoffs carried decode-severe
    /// evidence (a deep decode-latency excursion, or a jump-to-live flush — in the
@@ -220,7 +278,7 @@ pub(crate) struct BitrateController {
    /// ceiling is a permanent 30–60 s sawtooth: every ×0.7 backoff re-climbs toward a ceiling
    /// the decoder can't hold, and each cycle costs a flush plus a dropped-frame burst (the
    /// 1440p120 HEVC field case: knee ~490 Mbps under a ~658 Mbps ceiling). Slowly re-probed
-    /// on the [`CAP_REPROBE_WINDOWS`] clock, exactly like the host cap, so a decoder that
+    /// on the [`CAP_REPROBE_WINDOWS_MIN`] clock, exactly like the host cap, so a decoder that
    /// recovers (lighter content, thermal headroom) climbs again — the latch is never
    /// permanent.
    decode_cap_kbps: Option<u32>,
@@ -228,8 +286,10 @@ pub(crate) struct BitrateController {
    /// decode-driven): the reference the next one must land near ([`DECODE_CAP_SIMILAR_DIV`])
    /// to latch the cap — one spurious flush teaches nothing.
    decode_backoff_kbps: u32,
-    /// Clean windows spent parked at the learned decode cap (its re-probe clock).
+    /// Clean windows spent parked at the learned decode cap (its re-probe clock), and that
+    /// clock's own backoff interval — same schedule as the host cap's.
    decode_cap_probe_windows: u32,
+    decode_cap_reprobe_after: u32,
    /// Proven throughput: the session's highest windowed ACTUAL delivered rate seen with flat
    /// decode latency — the known-good high-water mark climbs are bounded against. Never decays;
    /// shrinking capacity (thermals, a heavier scene) is the reactive decode signal's job. On
@@ -241,6 +301,10 @@ pub(crate) struct BitrateController {
    last_change: Option<Instant>,
    /// Requests since the last ack — reaching [`MAX_UNACKED`] disables the controller.
    unacked: u32,
+    /// The last ceiling-clamp target asked for (0 = none). A session running ABOVE its effective
+    /// ceiling is asked down to it exactly once per distinct target — a host that answers higher
+    /// has said it cannot go there, and re-asking every cooldown only costs reconfigures.
+    ceiling_ask_kbps: u32,
 }

 impl BitrateController {
@@ -257,7 +321,12 @@ impl BitrateController {
        BitrateController {
            enabled: start_kbps > 0,
            current_kbps: start_kbps,
-            ceiling_kbps: start_kbps,
+            // The env cap binds the NEGOTIATED ceiling too, not just probe-learned ones. It is
+            // the only lever an Automatic session gives the operator (Automatic is precisely
+            // "no explicit bitrate"), so a start rate above it has to come down rather than
+            // stand as a ceiling the user asked not to reach — see the clamp-down step in
+            // [`on_window`](Self::on_window).
+            ceiling_kbps: start_kbps.min(ceiling_cap_kbps.unwrap_or(u32::MAX)),
            ceiling_cap_kbps,
            floor_kbps: FLOOR_KBPS.min(start_kbps.max(1)),
            probing: true,
@@ -269,14 +338,17 @@ impl BitrateController {
            short_ack_kbps: 0,
            short_acks: 0,
            cap_probe_windows: 0,
+            cap_reprobe_after: CAP_REPROBE_WINDOWS_MIN,
            decode_cap_kbps: None,
            decode_backoff_kbps: 0,
            decode_cap_probe_windows: 0,
+            decode_cap_reprobe_after: CAP_REPROBE_WINDOWS_MIN,
            proven_kbps: 0,
            bad_windows: 0,
            clean_windows: 0,
            last_change: None,
            unacked: 0,
+            ceiling_ask_kbps: 0,
        }
    }

@@ -321,8 +393,21 @@ impl BitrateController {
                        self.short_acks = 1;
                    }
                    if self.short_acks >= 2 && self.host_cap_kbps.is_none_or(|c| kbps < c) {
+                        // Re-learning a cap we had already lifted means the limit is STANDING,
+                        // not the transient the re-probe exists to escape — back its clock off
+                        // (see [`CAP_REPROBE_WINDOWS_MIN`]) so a hard encoder ceiling settles
+                        // into a slow poll instead of two pointless acks every 12 s. A first
+                        // latch starts the clock fast, because that is the case that matters.
+                        self.cap_reprobe_after = if self.host_cap_kbps.is_some() {
+                            self.cap_reprobe_after
+                                .saturating_mul(2)
+                                .min(CAP_REPROBE_WINDOWS_MAX)
+                        } else {
+                            CAP_REPROBE_WINDOWS_MIN
+                        };
                        tracing::info!(
                            cap_kbps = kbps,
+                            reprobe_after_windows = self.cap_reprobe_after,
                            "adaptive bitrate: host cap learned (encoder ceiling or cadence \
                             refusal) — climbs stop here until it lifts"
                        );
@@ -331,9 +416,34 @@ impl BitrateController {
                    }
                } else {
                    self.short_acks = 0;
+                    // GRANTED in full at or above the learned cap: the limit that taught it is
+                    // gone, and we have the host's own word for it. Drop the cap outright rather
+                    // than keep crawling up in +12.5 % re-probe steps — for a cap latched from a
+                    // transient (a host briefly behind cadence) that crawl is the entire
+                    // remaining cost of the transient, and it is measured in minutes.
+                    if self.host_cap_kbps.is_some_and(|c| kbps >= c) {
+                        tracing::info!(
+                            granted_kbps = kbps,
+                            "adaptive bitrate: host granted a climb at the learned cap — the \
+                             limit has lifted, dropping it"
+                        );
+                        self.host_cap_kbps = None;
+                        self.cap_probe_windows = 0;
+                        self.cap_reprobe_after = CAP_REPROBE_WINDOWS_MIN;
+                    }
                }
            }
            self.current_kbps = kbps;
+            // The host may run ABOVE our climb ceiling, and be right to: it sends an unsolicited
+            // `BitrateChanged` when a rebuild re-resolves an Automatic rate for what it actually
+            // encodes (a 1080p session mirroring a 4K panel resolves ~3× higher), and that is
+            // the host's own Automatic answer, not a climb we asked for. Let the ceiling follow
+            // — `set_ceiling` only ever raises, and still clamps to the operator's
+            // `PUNKTFUNK_ABR_MAX_MBPS`, which is what must bind here if anything does. Without
+            // this the ceiling stays at the stale negotiated rate and the step-down below
+            // immediately drags the host back off the rate it just chose. A no-op for ordinary
+            // acks: we never request above the effective ceiling in the first place.
+            self.set_ceiling(kbps);
        }
        self.unacked = 0;
    }
@@ -343,14 +453,30 @@ impl BitrateController {
    /// decoder's knee is just as mode-scoped (pixel rate drives both ends of the codec), so
    /// the decode cap goes with it. The probe-measured `ceiling_kbps` (a LINK property)
    /// survives.
+    ///
+    /// Every rolling BASELINE is mode-scoped too, and for the same reason the encode one always
+    /// was: a mode switch changes what "normal" costs at both ends of the pipe. 4K120 decodes
+    /// and encodes far slower than 1080p60 and puts bigger frames on the wire, so a baseline
+    /// learned under the old mode is a floor the new one clears on its very first window —
+    /// [`DECODE_RISE_US`] is 15 µs-thousands, well inside the gap between those two modes. Left
+    /// standing (only `encode_means` used to be cleared here), the ~30 s it takes
+    /// [`BASELINE_WINDOWS`] to age out is ~30 s of every window scoring bad, which is a ×0.7
+    /// backoff every other window: a switch UP in mode cratered the rate instead of raising it.
+    /// `proven_kbps` goes with them — it is the mark climbs are bounded against, and throughput
+    /// the OLD mode's decoder digested is not evidence about this one. It re-earns itself from
+    /// the next window.
    pub(crate) fn on_mode_switch(&mut self) {
        self.host_cap_kbps = None;
        self.short_acks = 0;
        self.cap_probe_windows = 0;
+        self.cap_reprobe_after = CAP_REPROBE_WINDOWS_MIN;
        self.decode_cap_kbps = None;
        self.decode_backoff_kbps = 0;
        self.decode_cap_probe_windows = 0;
+        self.owd_means.clear();
+        self.decode_means.clear();
        self.encode_means.clear();
+        self.proven_kbps = 0;
    }

    /// Feed one report window; returns the rate to request now, if any. `dropped` = frames that
@@ -389,22 +515,9 @@ impl BitrateController {
            return None;
        }
        // OWD: compare against the rolling-min baseline of PRIOR windows (so a rising window
-        // doesn't drag its own baseline up), then record it.
-        let owd_bad = match owd_mean_us {
-            Some(mean) => {
-                let bad = self
-                    .owd_means
-                    .iter()
-                    .min()
-                    .is_some_and(|&base| mean > base + OWD_RISE_US);
-                if self.owd_means.len() == BASELINE_WINDOWS {
-                    self.owd_means.pop_front();
-                }
-                self.owd_means.push_back(mean);
-                bad
-            }
-            None => false,
-        };
+        // doesn't drag its own baseline up), then record it. No severe tier — a standing queue is
+        // congestion evidence, not visible damage, so it always takes the two-window path.
+        let (owd_bad, _) = score_baseline(&mut self.owd_means, owd_mean_us, OWD_RISE_US, i64::MAX);
        // Decode-stage latency: same rolling-min-baseline treatment as OWD, but measuring the
        // CLIENT'S decoder rather than the link. A rise means the decoder is backlogging frames —
        // the bottleneck the network signals are blind to. Marking the window bad both ends slow
@@ -412,43 +525,22 @@ impl BitrateController {
        // the link ceiling) and, sustained, drives the ×0.7 backoff down to the real decode limit.
        // An excursion far past baseline is SEVERE: the decoder is deep in spike-overload and the
        // user is watching it — skip the two-window confirmation.
-        let (decode_bad, decode_severe) = match decode_mean_us {
-            Some(mean) => {
-                let base = self.decode_means.iter().min().copied();
-                let bad = base.is_some_and(|b| mean > b + DECODE_RISE_US);
-                let severe = base.is_some_and(|b| mean > b + DECODE_SEVERE_US);
-                if self.decode_means.len() == BASELINE_WINDOWS {
-                    self.decode_means.pop_front();
-                }
-                self.decode_means.push_back(mean);
-                (bad, severe)
-            }
-            None => (false, false),
-        };
+        let (decode_bad, decode_severe) = score_baseline(
+            &mut self.decode_means,
+            decode_mean_us,
+            DECODE_RISE_US,
+            DECODE_SEVERE_US,
+        );
        // Host-encode latency: the same rolling-min-baseline treatment, measuring the HOST'S
        // encoder — the compute-knee down-driver (see [`ENCODE_RISE_US`]). This is the only
        // signal that can push an already-too-high rate back under the knee: the host refuses
        // further climbs while behind cadence, but nothing else ever DESCENDS on a clean LAN.
-        let (encode_bad, encode_severe) = match encode_mean_us {
-            Some(mean) => {
-                let base = self.encode_means.iter().min().copied();
-                let bad = base.is_some_and(|b| mean > b + ENCODE_RISE_US);
-                let severe = base.is_some_and(|b| mean > b + ENCODE_SEVERE_US);
-                if self.encode_means.len() == BASELINE_WINDOWS {
-                    self.encode_means.pop_front();
-                }
-                self.encode_means.push_back(mean);
-                (bad, severe)
-            }
-            None => (false, false),
-        };
-        // The proven-throughput high-water mark: this window's delivered rate is now demonstrably
-        // digestible (decode latency stayed flat while it was carried). Loss doesn't disqualify —
-        // the bytes that DID arrive still went through the decoder; what loss means for the rate
-        // is the bad/severe machinery's business.
-        if !decode_bad && actual_kbps > self.proven_kbps {
-            self.proven_kbps = actual_kbps;
-        }
+        let (encode_bad, encode_severe) = score_baseline(
+            &mut self.encode_means,
+            encode_mean_us,
+            ENCODE_RISE_US,
+            ENCODE_SEVERE_US,
+        );
        // SEVERE = the user already saw damage (an unrecoverable frame, a jump-to-live flush, a
        // deep decode-latency excursion, a window spent begging for keyframes) or loss far past
        // any blip — one window is enough. Ordinary congestion (heavy-but-recoverable loss, an
@@ -466,6 +558,17 @@ impl BitrateController {
            || decode_bad
            || encode_bad
            || recovery_kf >= RECOVERY_KF_BAD;
+        // The proven-throughput high-water mark: this window's delivered rate is now demonstrably
+        // digestible — the pipeline carried it and NOTHING went wrong while it did. Scored after
+        // the verdict and gated on the whole of it, not on decode alone: the mark never decays, so
+        // one window is permanent authority over how far every later climb may step, and the
+        // windows that overstate delivered throughput are exactly the damaged ones (a stall's
+        // backlog draining in a single window, a flush's queue, the FEC surge that answers a loss
+        // burst). "Loss doesn't disqualify, the bytes still arrived" was true about the bytes and
+        // wrong about the conclusion drawn from them.
+        if !bad && actual_kbps > self.proven_kbps {
+            self.proven_kbps = actual_kbps;
+        }
        if bad {
            self.bad_windows += 1;
            self.clean_windows = 0;
@@ -475,16 +578,16 @@ impl BitrateController {
            self.clean_windows += 1;
            self.bad_windows = 0;
        }
-        // The learned host cap re-probe (see [`CAP_REPROBE_WINDOWS`]): after ~60 s of clean
-        // windows parked at the cap, lift it one step (+12.5 %, ceiling-bounded) so a
-        // scene-dependent refusal can't quietly cap the whole session — a still-standing limit
-        // just re-latches from the next pair of short acks, at zero encoder cost.
+        // The learned host cap re-probe (see [`CAP_REPROBE_WINDOWS_MIN`]): after a clean run
+        // parked at the cap, lift it one step (+12.5 %, ceiling-bounded) so a scene-dependent
+        // refusal can't quietly cap the whole session — a still-standing limit just re-latches
+        // from the next pair of short acks, at zero encoder cost, and backs the clock off.
        if let Some(cap) = self.host_cap_kbps {
            if bad {
                self.cap_probe_windows = 0;
            } else if self.current_kbps >= cap.saturating_sub(cap / 16) {
                self.cap_probe_windows += 1;
-                if self.cap_probe_windows >= CAP_REPROBE_WINDOWS {
+                if self.cap_probe_windows >= self.cap_reprobe_after {
                    self.cap_probe_windows = 0;
                    let lifted = cap.saturating_add(cap / 8).min(self.ceiling_kbps);
                    if lifted > cap {
@@ -508,7 +611,7 @@ impl BitrateController {
                self.decode_cap_probe_windows = 0;
            } else if self.current_kbps >= cap.saturating_sub(cap / 16) {
                self.decode_cap_probe_windows += 1;
-                if self.decode_cap_probe_windows >= CAP_REPROBE_WINDOWS {
+                if self.decode_cap_probe_windows >= self.decode_cap_reprobe_after {
                    self.decode_cap_probe_windows = 0;
                    let lifted = cap.saturating_add(cap / 8).min(self.ceiling_kbps);
                    if lifted > cap {
@@ -538,18 +641,42 @@ impl BitrateController {
            // knee. One event never latches (a spurious flush must stay a one-off), and a
            // backoff without decode evidence in between breaks the streak — whatever it saw,
            // it wasn't the same knee.
-            if decode_severe || flushed {
+            // A bare flush counts as decode evidence only where the decode signal can't speak
+            // for itself. On an embedder that reports decode latency, a flush with FLAT decode
+            // is a network event (a stall, a clock step) that drained a queue the decoder was
+            // keeping up with — teaching a "decoder knee" from it caps the session on the wrong
+            // end of the pipe. Where the signal is absent the old reading stands: the flush is
+            // the only decoder-saturation evidence there is.
+            let decode_evidence =
+                decode_severe || (flushed && (decode_bad || decode_mean_us.is_none()));
+            if decode_evidence {
                let rate = self.current_kbps;
                let similar = self.decode_backoff_kbps > 0
                    && rate.abs_diff(self.decode_backoff_kbps)
                        <= self.decode_backoff_kbps / DECODE_CAP_SIMILAR_DIV;
-                if similar && self.decode_cap_kbps.is_none_or(|c| rate < c) {
+                // Latch just UNDER the rate that choked, not at it: the knee is the rate the
+                // decoder could not hold, so a cap sitting exactly on it authorizes climbing
+                // straight back into the failure — the sawtooth the cap exists to end, merely
+                // slower. One sixteenth is inside the ±1/8 band the pair had to agree within,
+                // so it costs nothing the evidence actually established.
+                let knee = rate.saturating_sub(rate / 16).max(self.floor_kbps);
+                if similar && self.decode_cap_kbps.is_none_or(|c| knee < c) {
+                    // Same standing-vs-transient backoff as the host cap.
+                    self.decode_cap_reprobe_after = if self.decode_cap_kbps.is_some() {
+                        self.decode_cap_reprobe_after
+                            .saturating_mul(2)
+                            .min(CAP_REPROBE_WINDOWS_MAX)
+                    } else {
+                        CAP_REPROBE_WINDOWS_MIN
+                    };
                    tracing::info!(
-                        cap_kbps = rate,
+                        cap_kbps = knee,
+                        choked_at_kbps = rate,
+                        reprobe_after_windows = self.decode_cap_reprobe_after,
                        "adaptive bitrate: decode cap learned (decoder knee) — climbs stop \
                         here until it lifts"
                    );
-                    self.decode_cap_kbps = Some(rate.max(self.floor_kbps));
+                    self.decode_cap_kbps = Some(knee);
                    self.decode_cap_probe_windows = 0;
                }
                self.decode_backoff_kbps = rate;
@@ -574,6 +701,23 @@ impl BitrateController {
            .ceiling_kbps
            .min(self.host_cap_kbps.unwrap_or(u32::MAX))
            .min(self.decode_cap_kbps.unwrap_or(u32::MAX));
+        // Above the ceiling with nothing wrong: the session negotiated a rate the operator's
+        // `PUNKTFUNK_ABR_MAX_MBPS` forbids (no congestion signal will ever find this — the link
+        // is fine, the cap is a policy). Step straight to it rather than sitting above a limit
+        // the user set, and never below the floor. Asked ONCE per distinct target: if the host
+        // answers with something higher it has told us it cannot go there (its own floor, an
+        // encoder minimum), and repeating the ask every cooldown would buy nothing but a
+        // reconfigure each time.
+        let ceiling_target = eff_ceiling.max(self.floor_kbps);
+        if self.current_kbps > ceiling_target && self.ceiling_ask_kbps != ceiling_target {
+            tracing::info!(
+                from_kbps = self.current_kbps,
+                to_kbps = ceiling_target,
+                "adaptive bitrate: session rate is above the configured ceiling — stepping down"
+            );
+            self.ceiling_ask_kbps = ceiling_target;
+            return self.request(ceiling_target, now);
+        }
        let cap = eff_ceiling
            .min(self.proven_kbps.saturating_mul(PROVEN_HEADROOM_NUM) / PROVEN_HEADROOM_DEN);
        if self.current_kbps < eff_ceiling && utilized && cap > self.current_kbps {
@@ -602,6 +746,17 @@ impl BitrateController {
        // request just recomputes from the same base next time (and counts toward MAX_UNACKED).
        Some(kbps)
    }
+
+    /// The decision [`on_window`](Self::on_window) returned never reached the wire (the control
+    /// queue was full). Undo the request's bookkeeping: [`MAX_UNACKED`] exists to detect a HOST
+    /// that doesn't answer, and counting a message we never sent toward it retires the
+    /// controller for the session — with a log line blaming an "older host" that is not what
+    /// happened. Clearing the pending request also keeps a later unsolicited ack from being
+    /// judged short against a rate we never asked for.
+    pub(crate) fn on_request_dropped(&mut self) {
+        self.unacked = self.unacked.saturating_sub(1);
+        self.last_requested_kbps = None;
+    }
 }

 #[cfg(test)]
@@ -1110,14 +1265,16 @@ mod tests {

    #[test]
    fn decode_latency_caps_the_slow_start_climb() {
-        // A fat link (probe measured ~300 Mbps) but a decoder that saturates around the start rate.
+        // A fat link (probe measured ~300 Mbps) but a decoder that saturates below it.
        let mut c = BitrateController::new(20_000);
        c.set_ceiling(300_000);
        let start = Instant::now();
-        // First clean window (decoder fine at 20 Mbps) → slow start doubles to 40.
-        assert_eq!(
-            c.on_window(
-                ticks(start, 0),
+        // Slow start doubles while the decoder keeps up, and the first BASELINE_MIN_WINDOWS of
+        // those windows are what teach the decode baseline (one sample is not a floor).
+        let mut last = 0;
+        for i in 0..BASELINE_MIN_WINDOWS as u32 {
+            if let Some(k) = c.on_window(
+                ticks(start, i * 2),
                0,
                0,
                Some(10_000),
@@ -1125,16 +1282,18 @@ mod tests {
                None,
                1_000_000,
                false,
-                0
-            ),
-            Some(40_000)
-        );
-        c.on_ack(40_000);
-        // At 40 Mbps the decoder starts backing up (30 ms over baseline): the window is bad, so the
-        // climb stops here instead of doubling on toward the 300 Mbps link ceiling…
+                0,
+            ) {
+                last = k;
+                c.on_ack(k);
+            }
+        }
+        assert_eq!(last, 300_000, "slow start should reach the probed ceiling");
+        // Now the decoder starts backing up (30 ms over the learned baseline): the window is bad,
+        // so the climb stops instead of parking at the link ceiling…
        assert_eq!(
            c.on_window(
-                ticks(start, 2),
+                ticks(start, 20),
                0,
                0,
                Some(10_000),
@@ -1146,11 +1305,11 @@ mod tests {
            ),
            None
        );
-        // …and a second backed-up window backs the rate off, settling at the decode limit rather
+        // …and a second backed-up window backs the rate off toward the real decode limit rather
        // than choking the decoder at the link ceiling (the reported bug).
        assert_eq!(
            c.on_window(
-                ticks(start, 4),
+                ticks(start, 22),
                0,
                0,
                Some(10_000),
@@ -1160,7 +1319,54 @@ mod tests {
                false,
                0
            ),
-            Some(28_000)
+            Some(210_000)
+        );
+    }
+
+    #[test]
+    fn one_calm_window_is_not_a_baseline() {
+        // The ratchet this guard exists to stop: our own decrease CLEARS the encode baseline, so
+        // it re-seeds from whatever the next window happens to be. If that window is calm, the
+        // ordinary content variance that follows reads as a rise, backs off, clears again — all
+        // the way to the floor on a link that was never the problem. A single sample must not
+        // arm the signal.
+        let mut c = BitrateController::new(100_000);
+        let start = Instant::now();
+        // One calm 3 ms encode window, then windows 9 ms above it: far past ENCODE_RISE_US, and
+        // sustained — yet no baseline exists to judge them against yet.
+        for i in 0..BASELINE_MIN_WINDOWS as u32 {
+            let mean = if i == 0 { 3_000 } else { 12_000 };
+            assert_eq!(
+                c.on_window(
+                    ticks(start, i),
+                    0,
+                    0,
+                    Some(10_000),
+                    None,
+                    Some(mean),
+                    1_000_000,
+                    false,
+                    0
+                ),
+                None,
+                "window {i} fired off a baseline of fewer than {BASELINE_MIN_WINDOWS} samples"
+            );
+        }
+        // With a real baseline (min 3 ms over 4 windows) the signal works exactly as before: a
+        // sustained rise past it still backs the rate off.
+        assert_eq!(
+            c.on_window(
+                ticks(start, 8),
+                0,
+                0,
+                Some(10_000),
+                None,
+                Some(20_000),
+                1_000_000,
+                false,
+                0
+            ),
+            Some(70_000)
        );
    }

@@ -1385,8 +1591,8 @@ mod tests {

    #[test]
    fn learned_cap_reprobes_after_a_sustained_clean_run() {
-        // A cadence-refusal cap is scene evidence, not a spec limit: after ~60 s parked clean
-        // at the cap, lift one step so a one-time heavy scene can't cap the session forever. A
+        // A cadence-refusal cap is scene evidence, not a spec limit: after a clean run parked at
+        // the cap, lift one step so a one-time heavy scene can't cap the session forever. A
        // still-standing limit just re-latches from the next short-ack pair, at zero cost.
        let mut c = BitrateController::new(400_000);
        c.set_ceiling(1_400_000);
@@ -1396,7 +1602,10 @@ mod tests {
        assert_eq!(run_clean(&mut c, start, 10, 1), Some(1_400_000));
        c.on_ack(794_000);
        assert_eq!(c.host_cap_kbps, Some(794_000));
-        for i in 0..CAP_REPROBE_WINDOWS {
+        // The FIRST re-probe is the fast one — a transient refusal must not cost the session
+        // minutes to escape.
+        assert_eq!(c.cap_reprobe_after, CAP_REPROBE_WINDOWS_MIN);
+        for i in 0..CAP_REPROBE_WINDOWS_MIN {
            let _ = c.on_window(
                ticks(start, 20 + i),
                0,
@@ -1412,6 +1621,130 @@ mod tests {
        assert_eq!(c.host_cap_kbps, Some(794_000 + 794_000 / 8));
    }

+    #[test]
+    fn a_transient_refusal_does_not_pin_the_session() {
+        // The field failure this whole cap-escape change exists for. A host that escalates its
+        // capture/encode pipeline once — a startup hitch is enough — used to refuse every climb
+        // for the rest of the session; the client latched that refusal as a cap, at whatever
+        // rate slow start had reached, which is routinely the 20 Mbps default. Escaping cost
+        // +12.5 % per ~60 s: north of twenty minutes to reach a 300 Mbps link ceiling, which the
+        // user experiences as "Automatic is broken".
+        let mut c = BitrateController::new(20_000);
+        c.set_ceiling(300_000); // the startup probe measured a fat link
+        let start = Instant::now();
+        let mut tick = 0u32;
+        let mut windows_pinned = 0u32;
+        // Two refused climbs at the same rate → the cap latches at 20 Mbps.
+        for _ in 0..2 {
+            let k = run_clean(&mut c, start, tick, 4).expect("slow start should ask to climb");
+            tick += 4;
+            assert!(k > 20_000);
+            c.on_ack(20_000); // "behind cadence — held at the current rate"
+        }
+        assert_eq!(c.host_cap_kbps, Some(20_000));
+        // The host recovers immediately (its bucket drains; the escalation bought the headroom
+        // it was for), but the client has no way to know that except by asking again. Drive
+        // clean windows and grant whatever it asks for.
+        while c.current_kbps < 150_000 && windows_pinned < 400 {
+            if let Some(k) = c.on_window(
+                ticks(start, tick),
+                0,
+                0,
+                Some(10_000),
+                None,
+                None,
+                1_000_000,
+                false,
+                0,
+            ) {
+                c.on_ack(k);
+            }
+            tick += 1;
+            windows_pinned += 1;
+        }
+        assert!(
+            c.current_kbps >= 150_000,
+            "still pinned at {} after {windows_pinned} windows",
+            c.current_kbps
+        );
+        // ~750 ms a window: this must be tens of seconds, not the old tens of minutes.
+        assert!(
+            windows_pinned <= 40,
+            "took {windows_pinned} windows (~{} s) to escape a transient refusal",
+            windows_pinned * 3 / 4
+        );
+        // And the disproven cap is gone, not merely nudged upward.
+        assert!(c.host_cap_kbps.is_none());
+    }
+
+    #[test]
+    fn a_host_retarget_above_the_ceiling_raises_it() {
+        // The host sends an unsolicited `BitrateChanged` when a rebuild re-resolves an Automatic
+        // rate for what it ACTUALLY encodes — a 1080p session mirroring a 4K panel resolves far
+        // above the negotiated rate. That is the host's own Automatic answer, so the climb
+        // ceiling has to follow it; otherwise the ceiling stays stale and the step-down drags
+        // the host straight back off the rate it just chose.
+        let mut c = BitrateController::new(20_000);
+        assert_eq!(c.ceiling_kbps, 20_000);
+        c.on_ack(60_000); // unsolicited: no request was outstanding
+        assert_eq!(c.current_kbps, 60_000);
+        assert_eq!(c.ceiling_kbps, 60_000);
+        let start = Instant::now();
+        // No step-down, and no spurious re-target of any kind.
+        assert_eq!(run_clean(&mut c, start, 0, 4), None);
+        // The operator's cap still outranks it — that is the one thing that must bind here.
+        let mut c = BitrateController::with_ceiling_cap(20_000, Some(50_000));
+        c.on_ack(60_000);
+        assert_eq!(c.ceiling_kbps, 50_000);
+        assert_eq!(run_clean(&mut c, start, 0, 1), Some(50_000));
+    }
+
+    #[test]
+    fn a_standing_cap_backs_its_reprobe_clock_off() {
+        // The other half of the re-probe: an encoder's real codec ceiling (794 Mbps, L6.2)
+        // re-teaches itself every time the lift is tried. Escaping fast is right for a
+        // transient and pointless here, so each re-learn doubles the interval — a hard limit
+        // settles into a slow poll instead of two acks every 12 s for the whole session.
+        let mut c = BitrateController::new(400_000);
+        c.set_ceiling(1_400_000);
+        let start = Instant::now();
+        assert_eq!(run_clean(&mut c, start, 0, 1), Some(800_000));
+        c.on_ack(794_000);
+        assert_eq!(run_clean(&mut c, start, 10, 1), Some(1_400_000));
+        c.on_ack(794_000);
+        assert_eq!(c.cap_reprobe_after, CAP_REPROBE_WINDOWS_MIN);
+        // Each round: park clean at the cap until it re-probes upward, then have the host refuse
+        // the lift at the same value again. That is a STANDING limit, so the clock doubles.
+        let mut tick = 20;
+        for round in 0..3 {
+            let before = c.cap_reprobe_after;
+            for _ in 0..before {
+                let _ = c.on_window(
+                    ticks(start, tick),
+                    0,
+                    0,
+                    Some(10_000),
+                    None,
+                    None,
+                    1_000_000,
+                    false,
+                    0,
+                );
+                tick += 1;
+            }
+            let lifted = c.host_cap_kbps.expect("cap should still be latched");
+            assert!(lifted > 794_000, "round {round}: the re-probe never lifted");
+            // The host clamps the lift straight back to its real ceiling.
+            c.last_requested_kbps = Some(lifted);
+            c.on_ack(794_000);
+            assert_eq!(c.host_cap_kbps, Some(794_000));
+            assert_eq!(
+                c.cap_reprobe_after,
+                (before * 2).min(CAP_REPROBE_WINDOWS_MAX)
+            );
+        }
+    }
+
    #[test]
    fn host_encode_latency_rise_backs_off() {
        // The compute knee: link pristine, client decoder fine — only HOST encode time moves
@@ -1593,6 +1926,25 @@ mod tests {
        assert_eq!(run_clean(&mut c, start, 4, 20), None);
    }

+    #[test]
+    fn a_session_above_the_env_cap_steps_down_to_it_once() {
+        // PUNKTFUNK_ABR_MAX_MBPS is the only lever an Automatic session gives the operator, and
+        // it used to bind only ceilings the PROBE taught — so a session that negotiated a rate
+        // above the cap simply ran above it forever. No congestion signal will ever find that:
+        // the link is fine, the cap is policy.
+        let mut c = BitrateController::with_ceiling_cap(100_000, Some(50_000));
+        assert_eq!(c.ceiling_kbps, 50_000);
+        let start = Instant::now();
+        assert_eq!(run_clean(&mut c, start, 0, 1), Some(50_000));
+        // Suppose the host answers HIGHER than asked (its own floor, an encoder minimum): that
+        // is the host saying it cannot go there. Don't re-ask every cooldown forever.
+        c.on_ack(80_000);
+        assert_eq!(run_clean(&mut c, start, 2, 20), None);
+        // A ceiling that MOVES is a new question, and gets asked once more.
+        c.set_ceiling(90_000); // clamped to the 50 Mbps cap → still 50 000, no new ask
+        assert_eq!(run_clean(&mut c, start, 24, 20), None);
+    }
+
    #[test]
    fn decode_cap_latches_after_two_consecutive_decode_severe_backoffs() {
        // The 1440p120 field sawtooth: a decoder knee (~500 Mbps) well under the (inflated)
@@ -1650,7 +2002,7 @@ mod tests {
            ),
            Some(350_000)
        );
-        assert_eq!(c.decode_cap_kbps, Some(500_000));
+        assert_eq!(c.decode_cap_kbps, Some(500_000 - 500_000 / 16));
        // The backoff applies; from here every climb must stop AT the knee — not the 900 Mbps
        // link ceiling the old sawtooth kept re-poking.
        c.on_ack(350_000);
@@ -1667,14 +2019,22 @@ mod tests {
                false,
                0,
            ) {
-                assert!(k <= 500_000, "climb past the decode cap: {k}");
+                // Never past the cap in force when the decision was made. (A long clean run
+                // legitimately re-probes that cap upward — `decode_cap_reprobes_after_a_
+                // sustained_clean_run` owns that; here the point is that nothing climbs toward
+                // the 900 Mbps LINK ceiling the old sawtooth kept re-poking.)
+                assert!(
+                    k <= c.decode_cap_kbps.unwrap(),
+                    "climb past the decode cap: {k}"
+                );
                max_req = max_req.max(k);
                c.on_ack(k);
            }
        }
-        assert_eq!(max_req, 500_000);
-        assert_eq!(c.current_kbps, 500_000);
-        assert_eq!(c.decode_cap_kbps, Some(500_000));
+        assert!(
+            max_req < 600_000,
+            "the decode knee stopped binding: climbed to {max_req}"
+        );
    }

    #[test]
@@ -1748,10 +2108,10 @@ mod tests {
                0,
            );
        }
-        assert_eq!(c.decode_cap_kbps, Some(500_000));
+        assert_eq!(c.decode_cap_kbps, Some(500_000 - 500_000 / 16));
        // The host's ack parks the session at the knee (its clamp is authoritative).
-        c.on_ack(500_000);
-        for i in 0..CAP_REPROBE_WINDOWS {
+        c.on_ack(500_000 - 500_000 / 16);
+        for i in 0..CAP_REPROBE_WINDOWS_MIN {
            let _ = c.on_window(
                ticks(start, 8 + i),
                0,
@@ -1764,7 +2124,8 @@ mod tests {
                0,
            );
        }
-        assert_eq!(c.decode_cap_kbps, Some(500_000 + 500_000 / 8));
+        let knee = 500_000 - 500_000 / 16;
+        assert_eq!(c.decode_cap_kbps, Some(knee + knee / 8));
    }

    #[test]
@@ -1800,7 +2161,7 @@ mod tests {
                0,
            );
        }
-        assert_eq!(c.decode_cap_kbps, Some(500_000));
+        assert_eq!(c.decode_cap_kbps, Some(500_000 - 500_000 / 16));
        c.on_mode_switch();
        assert!(c.decode_cap_kbps.is_none());
        assert_eq!(c.ceiling_kbps, 900_000);
@@ -232,7 +232,7 @@ impl DataPump {
                last_late = st.fec_late_shards;
                last_received = st.packets_received;
                last_dropped = st.frames_dropped;
-                last_bytes = st.bytes_received;
+                last_bytes = st.media_bytes_received;
                last_report = Instant::now();
                discard_abr_window = true;
                flush_in_window = false;
@@ -317,11 +317,12 @@ impl DataPump {
                            "adaptive bitrate: capacity probe declined — keeping negotiated ceiling"
                        );
                    }
-                    // The probe's FLAG_PROBE filler landed in `bytes_received` but never reached
-                    // the decoder — rebase the ABR window's byte counter past it, or the next
-                    // window's "actual throughput" reads as the burst rate and poisons the
-                    // controller's proven-throughput high-water mark with the LINK rate.
-                    last_bytes = st.bytes_received;
+                    // Rebase the ABR window's byte anchor past the burst. (Probe filler is
+                    // routed out of `media_bytes_received` at the reassembler, so it can no
+                    // longer read as the burst rate on its own — but the anchor still has to
+                    // skip the video that landed around the burst under a suppressed report
+                    // tick, which would otherwise divide a long span's bytes by one window.)
+                    last_bytes = st.media_bytes_received;
                } else if Instant::now() >= deadline {
                    // The host never answered (a build that ignores ProbeRequest): clear the
                    // stuck-active state so LossReports resume, keep the negotiated ceiling.
@@ -454,11 +455,17 @@ impl DataPump {
                // the next one.
                let recovery_kf_reqs = pump_recovery_kf.swap(0, Ordering::Relaxed);
                // The window's ACTUAL delivered throughput — what the pipeline really carried, vs
-                // the target it was allowed. Wire bytes (headers + FEC) slightly overstate the
-                // media rate the decoder ingests; acceptable for the climb gate / proven-mark
-                // semantics (both compare against targets with their own headroom).
+                // the target it was allowed. MEDIA bytes (data-shard payload: no headers, no FEC
+                // parity, no probe filler, no audio), because both consumers compare it against
+                // the ENCODER's target: the utilization gate asks "was the target genuinely
+                // tested?" and the proven mark bounds every later climb. Wire bytes answered a
+                // different question — they rise with the redundancy the host adds in answer to
+                // loss, so the gate read ~25 % high precisely on the links it exists for.
                let window_ms = last_report.elapsed().as_millis().max(1) as u64;
-                let actual_kbps = (st.bytes_received.wrapping_sub(last_bytes).saturating_mul(8)
+                let actual_kbps = (st
+                    .media_bytes_received
+                    .wrapping_sub(last_bytes)
+                    .saturating_mul(8)
                    / window_ms) as u32;
                // A discard window feeds the controller NOTHING — its signals are probe-tail
                // residue, and one "congestion" verdict here ends slow start for good.
@@ -492,7 +499,15 @@ impl DataPump {
                        recovery_kf = recovery_kf_reqs,
                        "adaptive bitrate: requesting encoder re-target"
                    );
-                    let _ = ctrl_tx.try_send(CtrlRequest::SetBitrate(kbps));
+                    if ctrl_tx.try_send(CtrlRequest::SetBitrate(kbps)).is_err() {
+                        // Never reached the control task — tell the controller, or three of
+                        // these retire it for the session as "the host never acked".
+                        abr.on_request_dropped();
+                        tracing::warn!(
+                            kbps,
+                            "adaptive bitrate: control queue full — re-target dropped"
+                        );
+                    }
                }
                flush_in_window = false;
                last_report = Instant::now();
@@ -500,7 +515,7 @@ impl DataPump {
                last_late = st.fec_late_shards;
                last_received = st.packets_received;
                last_dropped = st.frames_dropped;
-                last_bytes = st.bytes_received;
+                last_bytes = st.media_bytes_received;
                if pump_perf_on {
                    if let Some(p) = session.take_pump_perf() {
                        let per_pkt_ns = |ns: u64| ns.checked_div(p.packets).unwrap_or(0);
@@ -73,9 +73,9 @@ pub struct StreamedAu {
    pts_ns: u64,
    user_flags: u32,
    /// Bytes not yet sealed into a block: the sub-shard remainder plus anything below the
-    /// slice-flush threshold. The final block always has ≥ 1 byte (flushes emit only whole
-    /// shards and never drain to empty on a slice that ends the AU — `finish_streamed` seals
-    /// whatever remains).
+    /// slice-flush threshold. The final block always has ≥ 1 byte — flushes emit only whole
+    /// shards, and a flush that WOULD empty this keeps one shard back (see `push_streamed`),
+    /// so `finish_streamed` always has something real to seal.
    pending: Vec<u8>,
    /// Sentinel blocks already emitted.
    blocks_out: u16,
@@ -418,7 +418,18 @@ impl Packetizer {
                    "streamed AU exceeds the negotiated max_frame_bytes",
                ));
            }
-            let k = whole.min(self.fec.max_data_per_block as usize);
+            // Never drain `pending` to EMPTY. [`finish_streamed`] must have bytes left to seal,
+            // or the final block degenerates to a single zero-padded filler shard whose derived
+            // base (`total_data − 1`) overlaps the block flushed just now — which the receiver's
+            // retro-validation correctly reads as a lying header and kills the whole AU. It bites
+            // exactly when the AU's length is a multiple of `shard_payload` (~1 in 1408 frames on
+            // a 1500-MTU link), and only on the slice arm: the legacy `must_flush` is a strict
+            // `>`, so its remainder is never empty. Keeping one whole shard back costs nothing —
+            // it rides out in the final block, which has to exist regardless.
+            let mut k = whole.min(self.fec.max_data_per_block as usize);
+            if k > 1 && k == whole && au.pending.len() == whole * payload {
+                k -= 1;
+            }
            let sof = !au.opened;
            let (bi, pts, uf) = (au.blocks_out, au.pts_ns, au.user_flags);
            let fi = au.frame_index;
@@ -429,6 +429,13 @@ impl Reassembler {
            stats
                .probe_last_arrival_ns
                .store(now_ns, std::sync::atomic::Ordering::Relaxed);
+        } else if hdr.shard_index < hdr.data_shards {
+            // Media accounting (see `Stats::media_bytes_received`): DATA shards only, payload
+            // only. Stamped at the same routing decision as the probe counters and for the same
+            // reason — the adaptive-bitrate utilization gate compares delivered throughput
+            // against an ENCODER target, so parity, headers and probe filler have no business
+            // in the numerator.
+            StatsCounters::add(&stats.media_bytes_received, shard_bytes as u64);
        }
        let win = if is_probe { probe } else { video };
        win.advance_window(
@@ -467,14 +474,33 @@ impl Reassembler {
            return Ok(None);
        }

-        // First packet of a frame allocates its whole (zeroed) buffer, budget-gated; later
-        // packets must agree with its geometry. A sentinel-opened (streamed) frame allocates at
-        // the limits' maximum — its real size doesn't exist yet.
-        let buf_len = if sentinel {
-            total_data_max * shard_bytes
+        // How many shards of frame buffer THIS packet proves the frame needs. A sentinel carries
+        // no total, but it does pin its own block's extent — a slice sentinel by its wire base,
+        // a legacy one by its full-K position — and that is what the buffer must cover to place
+        // the shard. The frame grows as later blocks reveal more, and the final (non-sentinel)
+        // block's totals settle it.
+        //
+        // ⚠ NOT `total_data_max` (= the negotiated `max_frame_bytes`, 8-64 MiB): that shape
+        // shipped in 0.23.0 and was survivable only while sentinels were rare — the streamed
+        // path emitted one solely for an AU exceeding a whole FEC block (~281 KB). The slice
+        // wire flushes at `MIN_STREAM_BLOCK_SHARDS`, so EVERY ordinary AU became sentinel-opened
+        // and every one of them committed the full ceiling: a multi-megabyte zeroed allocation
+        // per access unit, and an in-flight budget (`IN_FLIGHT_BUF_FACTOR × max_frame_bytes`)
+        // exhausted after ~3 concurrent frames — beyond which every packet of every further
+        // frame was dropped outright. On a jittery link that is a permanent loss storm.
+        let need_shards = if sentinel && slice_stream {
+            frame_bytes / shard_bytes + data_shards
+        } else if sentinel {
+            // Legacy sentinels are full-K uniform blocks (firewall-enforced), so the block's
+            // index alone gives its end.
+            (block_idx + 1).saturating_mul(lim.max_data_shards)
        } else {
-            total_data * shard_bytes
-        };
+            total_data
+        }
+        .min(total_data_max);
+        // First packet of a frame allocates its (zeroed) buffer, budget-gated; later packets must
+        // agree with its geometry.
+        let buf_len = need_shards * shard_bytes;
        let frame = match win.frames.entry(hdr.frame_index) {
            std::collections::hash_map::Entry::Occupied(e) => e.into_mut(),
            std::collections::hash_map::Entry::Vacant(e) => {
@@ -602,6 +628,21 @@ impl Reassembler {
            drop(stats);
            return Ok(None);
        }
+        // Grow to this packet's proven extent. A streamed frame opens at whichever block arrived
+        // first and learns its real size from the final block's totals (or a later, higher
+        // sentinel base) — reorder means either can come first, so the buffer is sized by
+        // whatever the frame has proven so far. Never shrinks: the totals only settle the frame's
+        // END, and completion truncates to `frame_bytes` anyway. The budget is re-checked here
+        // for exactly the reason it is checked at open — growth commits memory too.
+        if buf_len > frame.buf.len() {
+            let delta = buf_len - frame.buf.len();
+            if *in_flight_bytes + delta > IN_FLIGHT_BUF_FACTOR * lim.max_frame_bytes {
+                drop(stats);
+                return Ok(None);
+            }
+            *in_flight_bytes += delta;
+            frame.buf.resize(buf_len, 0);
+        }
        let FrameBuf {
            buf,
            blocks,
@@ -941,8 +941,9 @@ fn slice_config() -> Config {

 /// Slice chunks chosen to exercise every packetizer path: an exact-shard slice, a slice with
 /// a sub-shard remainder, a slice below [`MIN_STREAM_BLOCK_SHARDS`] that must accumulate,
-/// and a finish tail. 1023 B total → blocks (K, base-shard): (20, 0), (25, 20), (18, 45),
-/// final (1, 63) with block_count 4.
+/// and a finish tail. 1023 B total → blocks (K, base-shard): (19, 0), (26, 19), (18, 45),
+/// final (1, 63) with block_count 4. Chunk 0 is an exact 20-shard multiple and flushes 19:
+/// a flush never drains `pending` to empty, so `finish_streamed` always seals real bytes.
 fn slice_chunks() -> Vec<Vec<u8>> {
    [320usize, 403, 100, 200]
        .iter()
@@ -1007,7 +1008,8 @@ fn slice_streamed_wire_shape_and_roundtrip() {
    assert_eq!(src.len(), 1023);
    // (block_index, K, base bytes) — chunk 2 (100 B) accumulated instead of flushing (6
    // whole shards < MIN_STREAM_BLOCK_SHARDS) and rode into block 2 with chunk 3's bytes.
-    let expect = [(0u16, 20u16, 0u32), (1, 25, 320), (2, 18, 720)];
+    // Block 0 keeps one shard back (chunk 0 is an exact multiple), which rides into block 1.
+    let expect = [(0u16, 19u16, 0u32), (1, 26, 304), (2, 18, 720)];
    for p in &pkts {
        let h = PacketHeader::read_from_bytes(&p[..HEADER_LEN]).unwrap();
        assert_ne!(
@@ -1478,15 +1480,24 @@ fn parts_flow_for_legacy_streamed_frames() {
    assert!(got.last().unwrap().complete);
 }

-/// A sentinel first-packet commits a MAX-sized frame buffer, so the in-flight budget must
-/// bite after IN_FLIGHT_BUF_FACTOR frames — the amplification bound for one-datagram opens.
+/// A one-datagram open commits only the buffer its OWN header proves it needs, and the
+/// in-flight budget still bounds the ones that claim a lot.
+///
+/// Both halves matter. A sentinel that claims little must cost little: sizing every
+/// sentinel-opened frame at `max_frame_bytes` (the 0.23.0 shape) was survivable only while
+/// sentinels were rare, and the slice wire made every ordinary AU one — after which the budget
+/// was spent on ~3 frames and everything else on the link was dropped. A sentinel that claims a
+/// lot must still be bounded: its wire base can point near the frame ceiling, which is the
+/// amplification this budget exists for.
 #[test]
-fn streamed_open_amplification_is_budget_bounded() {
-    let mut r = Reassembler::new(limits());
+fn streamed_open_commits_its_own_extent_and_stays_bounded() {
    let coder = coder_for(FecScheme::Gf8);
+    // limits(): shard 16 B, max_data_shards 8, max_frame_bytes 4096 → budget = 4 × 4096.
+    // Modest legacy sentinels (block 0, full K = 8 → 128 B each): far more than
+    // IN_FLIGHT_BUF_FACTOR of them must fit, because none of them claims the ceiling.
+    let mut r = Reassembler::new(limits());
    let stats = StatsCounters::default();
-    // limits(): max_frame_bytes 4096 → each sentinel open commits 4096 B; budget = 4×4096.
-    for fi in 0..5u32 {
+    for fi in 0..32u32 {
        let mut h = base_header();
        h.block_count = 0;
        h.frame_bytes = 0;
@@ -1498,10 +1509,35 @@ fn streamed_open_amplification_is_budget_bounded() {
            .unwrap()
            .is_none());
    }
+    assert_eq!(
+        stats.snapshot().packets_dropped,
+        0,
+        "ordinary one-datagram opens must not exhaust the in-flight budget"
+    );
+
+    // A SLICE sentinel whose wire base sits just under the ceiling really does commit a
+    // max-sized frame (base 3968 B + K 8 = 256 shards = 4096 B) — four fit the budget, the
+    // fifth must be refused.
+    let mut r = Reassembler::new(limits());
+    let stats = StatsCounters::default();
+    for fi in 0..5u32 {
+        let mut h = base_header();
+        h.user_flags = USER_FLAG_SLICE_STREAM;
+        h.block_count = 0;
+        h.frame_bytes = 4096 - 8 * 16;
+        h.block_index = 1;
+        h.data_shards = 8;
+        h.recovery_shards = 0;
+        h.frame_index = fi;
+        assert!(r
+            .push(&packet(h), coder.as_ref(), &stats)
+            .unwrap()
+            .is_none());
+    }
    assert_eq!(
        stats.snapshot().packets_dropped,
        1,
-        "the fifth max-sized open must be refused by the in-flight budget"
+        "the fifth ceiling-claiming open must be refused by the in-flight budget"
    );
 }

@@ -1612,3 +1648,124 @@ fn streamed_second_final_with_different_totals_is_rejected() {
        .expect("frame completes under the first pinned totals");
    assert_eq!(got.data.len(), 160);
 }
+
+/// Production-shaped slice geometry: a 1500-MTU shard payload and the smallest frame ceiling
+/// the QUIC handshake ever negotiates (`max_frame_bytes` is clamped to ≥ 8 MiB there).
+fn prod_slice_config() -> Config {
+    use crate::config::{FecConfig, ProtocolPhase, Role};
+    Config {
+        role: Role::Host,
+        phase: ProtocolPhase::P2Punktfunk,
+        fec: FecConfig {
+            scheme: FecScheme::Gf16,
+            fec_percent: 20,
+            max_data_per_block: 200,
+        },
+        shard_payload: crate::config::mtu1500_shard_payload(),
+        max_frame_bytes: 8 << 20,
+        encrypt: false,
+        key: SessionKey::Aes128Gcm([0u8; 16]),
+        salt: [0u8; 4],
+        loopback_drop_period: 0,
+    }
+}
+
+/// Packetize one streamed AU of `chunks`, each chunk an encoder slice boundary.
+fn streamed_packets_with(
+    cfg: &Config,
+    frame_index: u32,
+    pts_ns: u64,
+    slice: bool,
+    chunks: &[usize],
+) -> (Vec<Vec<u8>>, Vec<u8>) {
+    let coder = coder_for(cfg.fec.scheme);
+    let mut pk = Packetizer::new(cfg);
+    let uf = if slice { USER_FLAG_SLICE_STREAM } else { 0 };
+    let mut au = pk.begin_streamed(pts_ns, uf, Some(frame_index));
+    let (mut pkts, mut src) = (Vec::new(), Vec::new());
+    let sink = |pkts: &mut Vec<Vec<u8>>, h: &PacketHeader, b: &[u8]| {
+        let mut p = Vec::with_capacity(HEADER_LEN + b.len());
+        p.extend_from_slice(h.as_bytes());
+        p.extend_from_slice(b);
+        pkts.push(p);
+    };
+    for (c, &n) in chunks.iter().enumerate() {
+        let data: Vec<u8> = (0..n).map(|i| (c * 57 + i * 131 + 7) as u8).collect();
+        src.extend_from_slice(&data);
+        pk.push_streamed(&mut au, &data, true, coder.as_ref(), |h, b| {
+            sink(&mut pkts, h, b);
+            Ok(())
+        })
+        .unwrap();
+    }
+    pk.finish_streamed(au, coder.as_ref(), |h, b| {
+        sink(&mut pkts, h, b);
+        Ok(())
+    })
+    .unwrap();
+    (pkts, src)
+}
+
+/// An AU whose length is an exact multiple of the shard payload must still reassemble.
+///
+/// Regression: the slice flush drained `pending` to empty, so `finish_streamed` sealed a final
+/// block of one zero-padded FILLER shard. Its derived base (`total_data − 1`) overlapped the
+/// sentinel block flushed a moment earlier, the receiver's retro-validation read that as a lying
+/// header, and the whole AU was destroyed — one frame in every `shard_payload` (~12 s at 120 fps),
+/// each costing a re-anchor freeze and a recovery keyframe.
+#[test]
+fn slice_streamed_exact_shard_multiple_completes() {
+    let cfg = prod_slice_config();
+    let coder = coder_for(FecScheme::Gf16);
+    let payload = cfg.shard_payload;
+    for shards in [16usize, 29, 30, 64] {
+        let (pkts, src) = streamed_packets_with(&cfg, 1, 1000, true, &[shards * payload]);
+        // Whatever the block split, the final block must carry real bytes — never a lone
+        // zero-pad shard sitting on top of the previous block's range.
+        let mut r = Reassembler::new(ReassemblerLimits::from_config(&cfg));
+        let stats = StatsCounters::default();
+        let f = push_all(&mut r, coder.as_ref(), &stats, &pkts)
+            .unwrap_or_else(|| panic!("{shards}-shard AU (exact multiple) must complete"));
+        assert_eq!(f.data, src, "{shards}-shard AU must be byte-identical");
+    }
+    // ...and the sweep around one of them, so an off-by-one in the keep-back can't hide.
+    for extra in 0..3usize {
+        let n = 30 * payload + extra;
+        let (pkts, src) = streamed_packets_with(&cfg, 2, 2000, true, &[n]);
+        let mut r = Reassembler::new(ReassemblerLimits::from_config(&cfg));
+        let stats = StatsCounters::default();
+        let f = push_all(&mut r, coder.as_ref(), &stats, &pkts)
+            .unwrap_or_else(|| panic!("{n}-byte AU must complete"));
+        assert_eq!(f.data, src);
+    }
+}
+
+/// A slice-streamed frame must cost the reassembler its OWN size, not the negotiated ceiling.
+///
+/// Regression: sentinel-opened frames allocated `max_frame_bytes` (8-64 MiB) each. Since the
+/// slice wire makes every ordinary AU sentinel-opened, the in-flight budget
+/// (`IN_FLIGHT_BUF_FACTOR × max_frame_bytes`) was spent after ~3 concurrent frames and every
+/// packet of every further frame was dropped outright — a permanent loss storm on any link with
+/// normal reorder, plus a multi-megabyte zeroing per access unit.
+#[test]
+fn slice_streamed_in_flight_budget_matches_legacy() {
+    let cfg = prod_slice_config();
+    let coder = coder_for(FecScheme::Gf16);
+    // A normal 40 KB access unit, opened but not completed — the shape a link with reorder
+    // holds several of at once.
+    for slice in [false, true] {
+        let mut r = Reassembler::new(ReassemblerLimits::from_config(&cfg));
+        let stats = StatsCounters::default();
+        for i in 0..12u32 {
+            let (pkts, _) = streamed_packets_with(&cfg, i, 1_000_000 * i as u64, slice, &[40_000]);
+            r.push(&pkts[0], coder.as_ref(), &stats).unwrap();
+        }
+        assert_eq!(
+            stats
+                .packets_dropped
+                .load(std::sync::atomic::Ordering::Relaxed),
+            0,
+            "slice={slice}: 12 ordinary AUs in flight must fit the in-flight budget"
+        );
+    }
+}
@@ -1,9 +1,105 @@
 //! Circular (directional) statistics for phase-locked capture (design/phase-locked-capture.md):
-//! the client-side half of the controller's v2 error signal. Pure math, no features — shared so
-//! every vsync-aware presenter (Android today, iOS next) computes the SAME statistic the host
+//! the client-side half of the controller's v2 error signal, plus the panel-grid learner every
+//! vsync-aware presenter paces against. Pure math, no features — shared so every presenter
+//! (Android today, iOS and the desktop session client next) computes the SAME statistic the host
 //! controller was tuned against, and so the controller's simulation tests can generate their
 //! synthetic reports through the identical code path.

+/// Plausible panel periods: ~24 Hz to ~500 Hz. A spacing outside this is a clock glitch, not a
+/// display mode, and must never reach the estimate.
+const PANEL_PERIOD_RANGE_NS: std::ops::RangeInclusive<i64> = 2_000_000..=42_000_000;
+
+/// Spacings within this of the estimate are the same grid — absorbs ordinary timeline jitter.
+const PANEL_GRID_TOLERANCE_NS: i64 = 200_000;
+
+/// Consecutive WIDER observations required before the estimate grows. One stray wide sample is a
+/// scheduling hiccup; eight in a row (~66 ms at 120 Hz) is a display that really did slow down.
+const PANEL_WIDEN_STREAK: u8 = 8;
+
+/// The panel's true refresh period, learned from observed vsync/frame-timeline spacing.
+///
+/// A presenter subdivides its release targets onto this grid, so an estimate FINER than the panel
+/// makes it aim at instants that never arrive and release faster than the display consumes —
+/// which is why the estimate has to be able to move both ways.
+///
+/// Seeding is the reason this is not simply "believe the last sample". The platform's *configured*
+/// mode is not the panel: under a per-uid frame-rate override a 120 Hz panel reports 60
+/// (`Display.getRefreshRate` returns the override — observed on-glass, A024), and the app's own
+/// choreographer callbacks arrive at the down-rated rate while the panel scans at its own. The
+/// mode TABLE is honest about what the panel *can* do, so it is the seed; the timeline spacing is
+/// honest about what it is *doing*, so it is the correction.
+///
+/// The asymmetry is deliberate. **Narrowing is immediate**: a finer real grid is always safe to
+/// subdivide onto, and it is the down-rate case the seed most often gets wrong. **Widening needs
+/// [`PANEL_WIDEN_STREAK`] consecutive agreeing observations** and then adopts the *narrowest* of
+/// them, because a wide sample is far more likely to be a missed callback than a mode change.
+///
+/// ⚠ 0.23.0 shipped this learner as narrow-only, seeded from the display mode the app *requests*
+/// (`preferredDisplayModeId` is a hint the system may refuse). A refused 120 Hz switch therefore
+/// left the presenter pacing a 60 Hz panel on an 8.33 ms grid with no way back — permanently.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct PanelGrid {
+    period_ns: i64,
+    widen_streak: u8,
+    /// Narrowest wider-than-estimate spacing seen during the current streak.
+    widen_candidate: i64,
+}
+
+impl PanelGrid {
+    /// Seed from the display mode's refresh rate (`0` = unknown — the first plausible observation
+    /// then sets the estimate outright).
+    pub fn seeded(hz: i32) -> PanelGrid {
+        PanelGrid {
+            period_ns: if hz > 0 { 1_000_000_000 / hz as i64 } else { 0 },
+            widen_streak: 0,
+            widen_candidate: 0,
+        }
+    }
+
+    /// The learned period, or `0` while unknown.
+    pub fn period_ns(&self) -> i64 {
+        self.period_ns
+    }
+
+    /// Fold one observed grid spacing. Returns `true` when [`period_ns`](Self::period_ns) changed.
+    pub fn observe(&mut self, spacing_ns: i64) -> bool {
+        if !PANEL_PERIOD_RANGE_NS.contains(&spacing_ns) {
+            return false; // implausible — a clock glitch, not a display mode
+        }
+        if self.period_ns == 0 {
+            self.reset_streak();
+            self.period_ns = spacing_ns;
+            return true;
+        }
+        if spacing_ns < self.period_ns - PANEL_GRID_TOLERANCE_NS {
+            self.reset_streak();
+            self.period_ns = spacing_ns;
+            return true;
+        }
+        if spacing_ns > self.period_ns + PANEL_GRID_TOLERANCE_NS {
+            self.widen_streak = self.widen_streak.saturating_add(1);
+            self.widen_candidate = if self.widen_candidate == 0 {
+                spacing_ns
+            } else {
+                self.widen_candidate.min(spacing_ns)
+            };
+            if self.widen_streak >= PANEL_WIDEN_STREAK {
+                self.period_ns = self.widen_candidate;
+                self.reset_streak();
+                return true;
+            }
+            return false;
+        }
+        self.reset_streak(); // this sample agreed — the run of wider ones is broken
+        false
+    }
+
+    fn reset_streak(&mut self) {
+        self.widen_streak = 0;
+        self.widen_candidate = 0;
+    }
+}
+
 /// Circular (vector-mean) statistics of latch samples against a display period: the mean latch
 /// mod the period (ns) and the coherence (‰).
 ///
@@ -90,3 +186,111 @@ mod tests {
        assert!(circular_latch(&[1_000; 16], 0).is_none());
    }
 }
+
+#[cfg(test)]
+mod panel_grid_tests {
+    use super::*;
+
+    const P120: i64 = 8_333_333;
+    const P60: i64 = 16_666_666;
+
+    #[test]
+    fn seeds_from_the_mode_and_reports_unknown_without_one() {
+        assert_eq!(PanelGrid::seeded(120).period_ns(), 8_333_333);
+        assert_eq!(PanelGrid::seeded(0).period_ns(), 0);
+        let mut g = PanelGrid::seeded(0);
+        assert!(
+            g.observe(P120),
+            "the first plausible sample sets an unseeded grid"
+        );
+        assert_eq!(g.period_ns(), P120);
+    }
+
+    #[test]
+    fn narrows_immediately_when_the_panel_is_faster_than_the_mode_said() {
+        // The down-rate case: the mode table read 60, the timelines run at 120.
+        let mut g = PanelGrid::seeded(60);
+        assert!(g.observe(P120));
+        assert_eq!(g.period_ns(), P120, "a finer real grid is adopted at once");
+    }
+
+    /// The 0.23.0 bug: `preferredDisplayModeId` is a request, so a refused 120 Hz switch seeds a
+    /// 120 Hz grid on a panel that is really running 60. The narrow-only learner could never
+    /// climb back, and the presenter aimed at instants the panel never reached.
+    #[test]
+    fn widens_back_out_when_the_requested_mode_was_refused() {
+        let mut g = PanelGrid::seeded(120);
+        for i in 0..PANEL_WIDEN_STREAK - 1 {
+            assert!(!g.observe(P60), "sample {i} must not widen on its own");
+            assert_eq!(g.period_ns(), P120);
+        }
+        assert!(
+            g.observe(P60),
+            "a sustained run of wider spacings widens the grid"
+        );
+        assert_eq!(g.period_ns(), P60);
+    }
+
+    #[test]
+    fn one_stray_wide_sample_never_widens() {
+        let mut g = PanelGrid::seeded(120);
+        for _ in 0..40 {
+            assert!(!g.observe(P60));
+            assert!(!g.observe(P120)); // an agreeing sample breaks the run
+        }
+        assert_eq!(
+            g.period_ns(),
+            P120,
+            "alternating samples must not accumulate"
+        );
+    }
+
+    #[test]
+    fn widening_adopts_the_narrowest_of_the_run() {
+        let mut g = PanelGrid::seeded(120);
+        // A run of wide spacings that includes some very wide outliers.
+        let run = [
+            P60,
+            33_000_000,
+            P60 + 400_000,
+            41_000_000,
+            P60,
+            P60,
+            P60,
+            P60,
+        ];
+        for s in run {
+            g.observe(s);
+        }
+        assert_eq!(
+            g.period_ns(),
+            P60,
+            "the estimate takes the narrowest of the run, never an outlier"
+        );
+    }
+
+    #[test]
+    fn implausible_spacings_are_ignored_entirely() {
+        let mut g = PanelGrid::seeded(120);
+        for _ in 0..100 {
+            assert!(!g.observe(0));
+            assert!(!g.observe(-1));
+            assert!(!g.observe(1_000_000)); // 1000 Hz — below the range floor
+            assert!(!g.observe(100_000_000)); // 10 Hz — above the ceiling
+        }
+        assert_eq!(g.period_ns(), P120);
+    }
+
+    #[test]
+    fn a_transient_narrow_glitch_self_heals() {
+        // Narrowing is immediate, so a glitch DOES poison the estimate — the point is that it is
+        // no longer permanent (0.23.0's learner had no way back).
+        let mut g = PanelGrid::seeded(120);
+        assert!(g.observe(2_100_000), "a glitch narrows the estimate");
+        assert_eq!(g.period_ns(), 2_100_000);
+        for _ in 0..PANEL_WIDEN_STREAK {
+            g.observe(P120);
+        }
+        assert_eq!(g.period_ns(), P120, "and the real grid wins it back");
+    }
+}
@@ -45,6 +45,16 @@ pub struct Stats {
    /// so a speed-test numerator built from it inherits whatever video was in flight around
    /// the burst — these keep video out of the probe math. Deliberately NOT mirrored into the
    /// C-ABI `PunktfunkStats` (probe measurements surface via `ProbeOutcome`).
+    /// Media bytes delivered to the video reassembler: DATA-shard payload only — no packet
+    /// headers, no FEC parity, no probe filler, no audio. This is the rate the encoder's target
+    /// is a promise about, and the only honest thing to compare that target against.
+    /// `bytes_received` counts every accepted datagram, so a "delivered throughput" built from
+    /// it rises with the FEC redundancy the host adds in answer to loss — which meant the
+    /// adaptive-bitrate utilization gate ("did the pipeline actually carry ~the target?") read
+    /// 25 % high exactly on the lossy links it exists for, and the never-decaying
+    /// proven-throughput mark inherited the same inflation. Deliberately NOT mirrored into the
+    /// C-ABI `PunktfunkStats`.
+    pub media_bytes_received: u64,
    pub probe_packets_received: u64,
    pub probe_bytes_received: u64,
    /// First / last probe-packet arrival (monotonic ns, see [`now_monotonic_ns`]; 0 = none
@@ -75,6 +85,7 @@ pub struct StatsCounters {
    pub fec_late_shards: AtomicU64,
    pub bytes_sent: AtomicU64,
    pub bytes_received: AtomicU64,
+    pub media_bytes_received: AtomicU64,
    pub probe_packets_received: AtomicU64,
    pub probe_bytes_received: AtomicU64,
    pub probe_first_arrival_ns: AtomicU64,
@@ -101,6 +112,7 @@ impl StatsCounters {
            fec_late_shards: self.fec_late_shards.load(l),
            bytes_sent: self.bytes_sent.load(l),
            bytes_received: self.bytes_received.load(l),
+            media_bytes_received: self.media_bytes_received.load(l),
            probe_packets_received: self.probe_packets_received.load(l),
            probe_bytes_received: self.probe_bytes_received.load(l),
            probe_first_arrival_ns: self.probe_first_arrival_ns.load(l),
@@ -110,6 +110,11 @@ pub fn capture_virtual_output(
    vout: crate::vdisplay::VirtualOutput,
    want: OutputFormat,
    _capture: crate::session_plan::CaptureBackend,
+    // The output's compositor rewrites `SPA_META_Cursor` on every buffer (KWin), so an id-0 meta
+    // is an authoritative "pointer hidden" — the caller derives it from the backend that created
+    // `vout` (which also covers registry-pooled reuse: a kept display only ever matches its own
+    // backend). See `pf_capture`'s `cursor_id0_hides` contract.
+    cursor_id0_hides: bool,
 ) -> Result<Box<dyn Capturer>> {
    // The portal negotiates its own pixel format, so `want.gpu` gates GPU zero-copy capture (the
    // capture backend is always the portal — the `CaptureBackend` arg is a Windows-only dispatch)
@@ -132,6 +137,7 @@ pub fn capture_virtual_output(
        want.hdr,
        zero_copy_policy(want.pyrowave, want.nv12_native),
        vout.expect_exact_dims,
+        cursor_id0_hides,
    )
 }

@@ -171,6 +177,9 @@ pub fn capture_virtual_output(
    vout: crate::vdisplay::VirtualOutput,
    want: OutputFormat,
    _capture: crate::session_plan::CaptureBackend,
+    // Linux-only fact (the PipeWire cursor-meta contract); the IDD-push path has no
+    // `SPA_META_Cursor` and its own CURSOR_SUPPRESSED hide source.
+    _cursor_id0_hides: bool,
 ) -> Result<Box<dyn Capturer>> {
    let target = vout.win_capture.clone().ok_or_else(|| {
        anyhow::anyhow!(
@@ -285,6 +294,7 @@ pub fn capture_virtual_output(
    _vout: crate::vdisplay::VirtualOutput,
    _want: OutputFormat,
    _capture: crate::session_plan::CaptureBackend,
+    _cursor_id0_hides: bool,
 ) -> Result<Box<dyn Capturer>> {
    anyhow::bail!("virtual-output capture requires Linux or Windows")
 }
@@ -559,6 +559,7 @@ pub fn mirror_test(args: &[String]) -> Result<()> {
        vout,
        fmt,
        crate::session_plan::CaptureBackend::resolve(),
+        compositor == crate::vdisplay::Compositor::Kwin,
    )
    .context("attach a capturer to the mirrored monitor")?;
    cap.set_active(true);
@@ -570,6 +570,7 @@ fn open_gs_mirror_source(
        vout,
        pf_frame::OutputFormat::resolve(cfg.hdr, crate::zerocopy::enabled()),
        crate::session_plan::CaptureBackend::resolve(),
+        compositor == crate::vdisplay::Compositor::Kwin,
    )
    .context("attach a capturer to the mirrored monitor")
 }
@@ -782,6 +783,7 @@ fn open_gs_virtual_source(
        vout,
        capture::OutputFormat::resolve(cfg.hdr, crate::encode::resolved_backend_is_gpu()),
        crate::session_plan::CaptureBackend::resolve(),
+        compositor == crate::vdisplay::Compositor::Kwin,
    )
    .context("capture virtual output")?;
    capturer.set_active(true);
@@ -77,6 +77,32 @@ impl LogRing {
            .duration_since(UNIX_EPOCH)
            .map(|d| d.as_millis() as u64)
            .unwrap_or(0);
+        self.push_entry(level.to_string(), target.to_string(), msg, ts_ms);
+    }
+
+    /// Ingest a line that was produced in **another process** — the plugin/script runner, via
+    /// `POST /plugins/logs` (see `mgmt::plugins::ingest_plugin_logs`).
+    ///
+    /// Plugins are not host child processes: the runner is a separate bun process that `import()`s
+    /// each plugin in-process, so a plugin's output never passes through this process's `tracing`
+    /// and [`RingLayer`] can't see it. Without this door the console's log page shows nothing about
+    /// the plugins at all, and on Windows nothing else does either — the runner task writes no log
+    /// file, so a failing plugin was diagnosable only by stopping the task and re-running it by
+    /// hand (field report 2026-08-03, the VirtualHere plugin).
+    ///
+    /// The caller's `ts_ms` is kept — the line was stamped when it happened, and re-stamping it on
+    /// arrival would collapse a whole batch onto the moment it was flushed. `seq` stays ours: it is
+    /// the cursor for a single ring with several producers, so only the ring can mint it.
+    pub fn push_remote(&self, level: &str, target: &str, msg: &str, ts_ms: u64) {
+        self.push_entry(
+            normalize_level(level).to_string(),
+            target.to_string(),
+            truncate_msg(msg.to_string()),
+            ts_ms,
+        );
+    }
+
+    fn push_entry(&self, level: String, target: String, msg: String, ts_ms: u64) {
        let mut inner = self.inner.lock().unwrap_or_else(|e| e.into_inner());
        let seq = inner.next_seq;
        inner.next_seq += 1;
@@ -86,8 +112,8 @@ impl LogRing {
        inner.entries.push_back(LogEntry {
            seq,
            ts_ms,
-            level: level.to_string(),
-            target: target.to_string(),
+            level,
+            target,
            msg,
        });
    }
@@ -125,6 +151,33 @@ pub fn ring() -> &'static LogRing {
    RING.get_or_init(LogRing::new)
 }

+/// Coerce an externally-supplied level to the five the console's filter ranks. Anything else —
+/// a plugin inventing `NOTICE`, a truncated line, empty — becomes `INFO` rather than being
+/// rejected: an unfamiliar level is not a reason to drop the operator's diagnostics on the floor,
+/// and an unranked string would sort as `0` in the console's `RANK` map and hide under every filter.
+fn normalize_level(level: &str) -> &'static str {
+    match level.trim().to_ascii_uppercase().as_str() {
+        "ERROR" | "FATAL" | "SEVERE" => "ERROR",
+        "WARN" | "WARNING" => "WARN",
+        "DEBUG" => "DEBUG",
+        "TRACE" | "VERBOSE" => "TRACE",
+        _ => "INFO",
+    }
+}
+
+/// Cap a message at [`MAX_MSG`], cutting on a char boundary and marking the elision.
+fn truncate_msg(mut msg: String) -> String {
+    if msg.len() > MAX_MSG {
+        let mut end = MAX_MSG;
+        while !msg.is_char_boundary(end) {
+            end -= 1;
+        }
+        msg.truncate(end);
+        msg.push('…');
+    }
+    msg
+}
+
 /// Targets whose DEBUG/TRACE output is steady-state chatter, not diagnostics — left in, they evict
 /// the entire ring tail: `mdns_sd` DEBUG-logs every multicast packet it can't parse (one chatty
 /// AirPlay/HomePod device on the LAN floods thousands of entries per hour), and `wasapi` DEBUG-logs
@@ -223,15 +276,7 @@ impl FieldFmt {
        } else {
            self.msg.push_str(&self.fields);
        }
-        if self.msg.len() > MAX_MSG {
-            let mut end = MAX_MSG;
-            while !self.msg.is_char_boundary(end) {
-                end -= 1;
-            }
-            self.msg.truncate(end);
-            self.msg.push('…');
-        }
-        self.msg
+        truncate_msg(self.msg)
    }
 }

@@ -360,6 +405,45 @@ mod tests {
        assert!(page.entries.iter().any(|e| e.target == "mdns_sdx"));
    }

+    #[test]
+    fn remote_entries_keep_their_own_timestamp_and_share_the_cursor() {
+        let ring = LogRing::new();
+        ring.push(&tracing::Level::INFO, "punktfunk_host", "local".into());
+        ring.push_remote("WARN", "plugin:virtualhere", "remote", 1_700_000_000_123);
+
+        let page = ring.since(0, 10);
+        assert_eq!(page.entries.len(), 2);
+        // One sequence across both producers — the console's cursor cannot see two rings.
+        assert_eq!(page.entries[0].seq, 1);
+        assert_eq!(page.entries[1].seq, 2);
+        let remote = &page.entries[1];
+        assert_eq!(remote.level, "WARN");
+        assert_eq!(remote.target, "plugin:virtualhere");
+        assert_eq!(remote.msg, "remote");
+        // Stamped when it happened, not when the batch arrived.
+        assert_eq!(remote.ts_ms, 1_700_000_000_123);
+    }
+
+    #[test]
+    fn remote_levels_are_coerced_not_rejected() {
+        assert_eq!(normalize_level("error"), "ERROR");
+        assert_eq!(normalize_level(" Warning "), "WARN");
+        assert_eq!(normalize_level("TRACE"), "TRACE");
+        // An unranked level would sort as 0 in the console's filter and hide under every setting.
+        assert_eq!(normalize_level("NOTICE"), "INFO");
+        assert_eq!(normalize_level(""), "INFO");
+    }
+
+    #[test]
+    fn remote_messages_are_truncated_like_local_ones() {
+        let ring = LogRing::new();
+        ring.push_remote("INFO", "plugin:x", &"ä".repeat(MAX_MSG), 1);
+        let page = ring.since(0, 10);
+        let msg = &page.entries[0].msg;
+        assert!(msg.ends_with('…'));
+        assert!(msg.len() <= MAX_MSG + '…'.len_utf8());
+    }
+
    #[test]
    fn message_truncation_keeps_char_boundary() {
        let f = FieldFmt {
@@ -253,6 +253,7 @@ fn api_router_parts() -> (Router<Arc<MgmtState>>, utoipa::openapi::OpenApi) {
                .routes(routes!(plugins::list_plugins))
                .routes(routes!(plugins::register_plugin, plugins::delete_plugin))
                .routes(routes!(plugins::get_ui_credential))
+                .routes(routes!(plugins::ingest_plugin_logs))
                .routes(routes!(store::get_catalog))
                .routes(routes!(store::refresh_catalog))
                .routes(routes!(store::list_installed))
@@ -29,6 +29,12 @@ use std::time::{Duration, Instant};
 /// this tolerates two missed ticks before a plugin drops out of the listing.
 const LEASE_TTL: Duration = Duration::from_secs(90);

+/// Lines accepted per `POST /plugins/logs`. The runner batches on a short timer, so a batch this
+/// size means a plugin is logging faster than the ring can usefully hold — the shipper drops its
+/// own backlog (and says so in a line of its own) rather than letting one chatty plugin evict the
+/// whole ring in a single request.
+const MAX_LOG_BATCH: usize = 256;
+
 // ---------------------------------------------------------------- wire shapes

 /// A plugin's UI surface as it registers it. Carries the secret — this shape is only ever a request
@@ -60,6 +66,26 @@ pub(crate) struct PluginRegistration {
    pub ui: Option<PluginUi>,
 }

+/// One log line produced by the runner or a plugin inside it (`POST /plugins/logs`).
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct PluginLogLine {
+    /// When the line was produced, unix milliseconds. Kept verbatim — see
+    /// [`crate::log_capture::LogRing::push_remote`].
+    pub ts_ms: u64,
+    /// `ERROR` | `WARN` | `INFO` | `DEBUG` | `TRACE`. Anything else is coerced to `INFO`.
+    pub level: String,
+    /// Which unit emitted it — a plugin's `definePlugin` name, a package name, or `runner`.
+    /// Surfaced in the console's target column as `plugin:<source>`.
+    pub source: String,
+    pub msg: String,
+}
+
+/// A batch of runner log lines.
+#[derive(Deserialize, ToSchema)]
+pub(crate) struct PluginLogBatch {
+    pub entries: Vec<PluginLogLine>,
+}
+
 /// The secret-free view of a plugin's UI surface — what [`list_plugins`] returns to the browser.
 #[derive(Serialize, ToSchema)]
 pub(crate) struct PluginUiPublic {
@@ -264,6 +290,26 @@ fn sanitize(s: &str) -> String {
        .to_string()
 }

+/// The console target for a runner-supplied line: `plugin:<source>`.
+///
+/// The source is NOT a [`valid_plugin_id`] — the runner names a unit by its `definePlugin` name
+/// (`virtualhere`), its package name (`@punktfunk/plugin-virtualhere`), a bare script's file stem,
+/// or `runner` for its own supervision lines, and all four are worth telling apart in the log. So
+/// this sanitizes rather than validates: control characters go (a log target is rendered in a
+/// terminal by `logs download` as readily as in the console), length is capped, and an empty source
+/// becomes `runner` so a line is never attributed to nothing.
+fn log_target(source: &str) -> String {
+    let mut s = sanitize(source);
+    if s.is_empty() {
+        s = "runner".into();
+    }
+    // Cap on CHARS, not bytes — truncating a multi-byte name mid-sequence would panic.
+    if s.chars().count() > 64 {
+        s = s.chars().take(64).collect();
+    }
+    format!("plugin:{s}")
+}
+
 /// Validate a registration body into the internal [`Valid`] form, or a human-readable reason.
 fn validate(reg: PluginRegistration) -> Result<Valid, String> {
    let title = sanitize(&reg.title);
@@ -367,6 +413,63 @@ pub(crate) async fn register_plugin(
    StatusCode::NO_CONTENT.into_response()
 }

+/// Ingest runner log lines
+///
+/// The plugin/script runner ships its output here so the console's **Logs** page can show it.
+///
+/// Plugins are not host child processes — the runner is a separate `bun` process that `import()`s
+/// each plugin in-process — so nothing a plugin logs passes through the host's own `tracing`, and
+/// before this endpoint the console's log page could not show a single plugin line. On Linux the
+/// fallback was `journalctl --user -u punktfunk-scripting`; on Windows the runner task writes no
+/// log file at all, so a failing plugin was diagnosable only by stopping the scheduled task and
+/// re-running the runner by hand. Both are shell access on the host box, which is exactly what the
+/// console exists to avoid.
+///
+/// Lines land in the same ring as the host's own, sharing one `seq` cursor, targeted
+/// `plugin:<source>` — so `GET /logs` needs no second cursor and the console needs no second poll.
+#[utoipa::path(
+    post,
+    path = "/plugins/logs",
+    tag = "plugins",
+    operation_id = "ingestPluginLogs",
+    request_body = PluginLogBatch,
+    responses(
+        (status = NO_CONTENT, description = "Lines ingested"),
+        (status = BAD_REQUEST, description = "Batch too large", body = ApiError),
+        (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
+    )
+)]
+pub(crate) async fn ingest_plugin_logs(ApiJson(batch): ApiJson<PluginLogBatch>) -> Response {
+    if batch.entries.len() > MAX_LOG_BATCH {
+        return api_error(
+            StatusCode::BAD_REQUEST,
+            &format!("at most {MAX_LOG_BATCH} entries per batch"),
+        );
+    }
+    for line in batch.entries {
+        crate::log_capture::ring().push_remote(
+            &line.level,
+            &log_target(&line.source),
+            &sanitize_msg(&line.msg),
+            line.ts_ms,
+        );
+    }
+    StatusCode::NO_CONTENT.into_response()
+}
+
+/// Strip control characters from an ingested message, keeping tabs.
+///
+/// Same reasoning as [`sanitize`], one exception wider: a plugin's messages routinely carry a
+/// stack trace or a vendor CLI's output, and an embedded newline would let one line forge several
+/// in the downloaded log file. Tabs survive because they are load-bearing in that kind of output.
+fn sanitize_msg(s: &str) -> String {
+    s.chars()
+        .map(|c| if c == '\t' || !c.is_control() { c } else { ' ' })
+        .collect::<String>()
+        .trim_end()
+        .to_string()
+}
+
 /// List registered plugins
 ///
 /// The live plugin directory (lease not expired), sorted by title. **Secret-free**: each entry
@@ -620,6 +620,23 @@ async fn plugin_token_lane_is_scoped_and_loopback_only() {
        StatusCode::NO_CONTENT
    );

+    // Log ingest. This is the ONLY token the scripting runner holds (on Windows its LocalService
+    // principal cannot even read the admin one), so if this lane ever stopped reaching this route
+    // the console's plugin logs would go quiet with nothing else failing — pin it here rather than
+    // rely on `plugin_may_access`'s denylist continuing to not match `/plugins/logs`.
+    let body = serde_json::json!({"entries": [{
+        "ts_ms": 1_700_000_000_000u64,
+        "level": "INFO",
+        "source": "virtualhere",
+        "msg": "hello from the runner",
+    }]});
+    let req = axum::http::Request::post("/api/v1/plugins/logs")
+        .header("content-type", "application/json")
+        .header("authorization", "Bearer plugin-secret")
+        .body(Body::from(body.to_string()))
+        .unwrap();
+    assert_eq!(send(&app, req).await.0, StatusCode::NO_CONTENT);
+
    // The carve-outs answer 403 (authenticated but not authorized), not 401.
    for (method, path) in [
        (Method::GET, "/api/v1/hooks"),
@@ -972,6 +989,59 @@ async fn plugin_registry_roundtrip() {
    assert_eq!(status, StatusCode::BAD_REQUEST);
 }

+/// Runner log ingest: lines reach the same ring `GET /logs` serves, tagged so the console can tell
+/// them from the host's own, and one chatty plugin can't evict the ring in a single request.
+#[tokio::test]
+async fn plugin_log_ingest_lands_in_the_ring() {
+    let app = test_app(test_state(), None);
+    let marker = "vh-ingest-marker-3f9a";
+
+    let (status, _) = send(
+        &app,
+        post_json(
+            "/api/v1/plugins/logs",
+            serde_json::json!({"entries": [
+                {"ts_ms": 1_700_000_000_123u64, "level": "warn", "source": "virtualhere", "msg": marker},
+                // No source: attributed to the runner rather than to nothing.
+                {"ts_ms": 1_700_000_000_124u64, "level": "NOTICE", "source": "", "msg": "orphan"},
+            ]}),
+        ),
+    )
+    .await;
+    assert_eq!(status, StatusCode::NO_CONTENT);
+
+    let (status, body) = send(&app, get_req("/api/v1/logs?limit=1000")).await;
+    assert_eq!(status, StatusCode::OK);
+    let entries = body["entries"].as_array().unwrap();
+
+    let mine = entries
+        .iter()
+        .find(|e| e["msg"] == marker)
+        .expect("ingested line is served by GET /logs");
+    // `plugin:` is what the console's Host/Plugins filter keys on.
+    assert_eq!(mine["target"], "plugin:virtualhere");
+    // Lowercase in, canonical out — the console ranks these five and nothing else.
+    assert_eq!(mine["level"], "WARN");
+    // Stamped when the line happened, not when the batch arrived.
+    assert_eq!(mine["ts_ms"], 1_700_000_000_123u64);
+
+    let orphan = entries.iter().find(|e| e["msg"] == "orphan").unwrap();
+    assert_eq!(orphan["target"], "plugin:runner");
+    // An unranked level would sort as 0 in the console's filter and hide under every setting.
+    assert_eq!(orphan["level"], "INFO");
+
+    // An oversized batch is refused whole rather than half-ingested.
+    let big: Vec<serde_json::Value> = (0..300)
+        .map(|i| serde_json::json!({"ts_ms": 1u64, "level": "INFO", "source": "x", "msg": format!("f{i}")}))
+        .collect();
+    let (status, _) = send(
+        &app,
+        post_json("/api/v1/plugins/logs", serde_json::json!({"entries": big})),
+    )
+    .await;
+    assert_eq!(status, StatusCode::BAD_REQUEST);
+}
+
 /// The OpenAPI document lists every route with a unique operationId (codegen relies
 /// on both), and the checked-in copy is current.
 #[test]
@@ -1073,6 +1073,17 @@ async fn serve_session(
    // accepted ack as "the active mode is now X" and fixes itself; old clients just log it.
    let (reconfig_result_tx, reconfig_result_rx) =
        tokio::sync::mpsc::unbounded_channel::<Reconfigured>();
+    // Unsolicited bitrate re-target, data plane → control task (the `reconfig_result_tx` pattern
+    // again, for the same reason). A pipeline rebuild can RE-RESOLVE an Automatic rate — most
+    // visibly when the source delivers a different size than the session negotiated, e.g. a
+    // client that asked for 1080p mirroring a 4K panel — and that number is what everything
+    // downstream reasons about: the send pacer, the console, and the base a `SetBitrate` ack is
+    // measured against. The client's copy only ever moved on an ack, so it stayed on the
+    // negotiated rate while the host encoded at another one, and the ABR's first climb computed
+    // from that stale base asked for LESS than the host was already sending — a re-target
+    // downward, with the rebuild it costs. Tell the client instead; `BitrateChanged` already
+    // means exactly this and old clients already handle one arriving unprompted.
+    let (retarget_tx, retarget_rx) = tokio::sync::mpsc::unbounded_channel::<u32>();
    // Cursor-forward bridge (M2): the encode loop diffs each frame's cursor serial and hands
    // changed SHAPES here; the control task (the control stream's sole writer) sends them.
    // Same shape as `probe_result_tx`. Wired even when the channel wasn't negotiated — it
@@ -1133,6 +1144,7 @@ async fn serve_session(
        probe_tx,
        probe_result_rx,
        reconfig_result_rx,
+        retarget_rx,
        cursor_shape_rx,
        cursor_client_draws,
        clip_enabled,
@@ -1579,6 +1591,7 @@ async fn serve_session(
                        probe_rx,
                        probe_result_tx,
                        reconfig_result_tx,
+                        retarget_tx,
                        fec_target: fec_target_dp,
                        phase: phase_ctl,
                        conn: conn_stream,
@@ -40,6 +40,9 @@ pub(super) async fn run(
    probe_tx: std::sync::mpsc::Sender<ProbeRequest>,
    mut probe_result_rx: tokio::sync::mpsc::UnboundedReceiver<ProbeResult>,
    mut reconfig_result_rx: tokio::sync::mpsc::UnboundedReceiver<Reconfigured>,
+    // Host-initiated bitrate re-target (a rebuild re-resolved an Automatic rate): forwarded to
+    // the client as a `BitrateChanged` so its controller's climb base tracks the real encoder.
+    mut retarget_rx: tokio::sync::mpsc::UnboundedReceiver<u32>,
    mut cursor_shape_rx: tokio::sync::mpsc::UnboundedReceiver<punktfunk_core::quic::CursorShape>,
    cursor_client_draws: Arc<AtomicBool>,
    clip_enabled: Arc<AtomicBool>,
@@ -338,6 +341,27 @@ pub(super) async fn run(
                    None => clip_offer_closed = true,
                }
            }
+            retarget = retarget_rx.recv() => {
+                // A pipeline rebuild re-resolved the Automatic rate (see `retarget_tx`). Same
+                // message the `SetBitrate` path answers with — the client's controller treats
+                // any `BitrateChanged` as authoritative for what the encoder now targets, which
+                // is exactly right here: it IS what the encoder now targets, we just weren't
+                // asked. PyroWave reaches this too, and should: its rate is pinned against
+                // mid-stream RETARGETS, but a mode switch legitimately re-resolves the pin
+                // (~1.6 bpp for the new pixel rate) and the client's live-rate display is
+                // otherwise stuck on the old one. Its controller is off, so nothing acts on it.
+                let Some(kbps) = retarget else { break }; // data plane gone
+                tracing::info!(
+                    kbps,
+                    "encoder re-targeted by a pipeline rebuild — telling the client"
+                );
+                if io::write_msg(&mut ctrl_send, &BitrateChanged { bitrate_kbps: kbps }.encode())
+                    .await
+                    .is_err()
+                {
+                    break;
+                }
+            }
            correction = reconfig_result_rx.recv() => {
                // H2 rollback/correction ack: the data plane reports the mode ACTUALLY live
                // after a rebuild that failed (stayed at the old mode) or that the backend
@@ -629,6 +629,20 @@ const RUMBLE_RENEW_FLOOR_MS: u64 = 60;
 /// own expiry. `3` total zero sends = the immediate one + this many renewal re-sends.
 const RUMBLE_STOP_BURST: u8 = 2;

+/// Clear a removed pad's rumble bookkeeping — the level, the "we have seen a level" flag, and any
+/// stop re-sends still owed. Together these end the pad's lease, so a re-plug on the same wire
+/// index inherits nothing that could buzz the new device.
+///
+/// The per-pad rumble **sequence is deliberately not a parameter**: it must stay monotonic for the
+/// life of the connection because the client gates on it with a wrapping half-space compare and
+/// never resets its side (`punktfunk-core/src/client/pump/datagram_task.rs`). Resetting it here is
+/// the bug pinned by [`tests::rumble_seq_survives_a_removal_so_the_client_gate_accepts`].
+fn clear_pad_feedback(state: &mut (u16, u16), seen: &mut bool, stop_burst: &mut u8) {
+    *state = (0, 0);
+    *seen = false;
+    *stop_burst = 0;
+}
+
 /// Send one rumble datagram on the universal 0xCA plane. `envelope_on` picks the self-terminating
 /// v2 form (`[level][seq][ttl_ms]`, the default) or the legacy v1 level datagram (the
 /// `PUNKTFUNK_RUMBLE_ENVELOPE=0` bisect hatch). Best-effort like every side-plane datagram.
@@ -824,11 +838,22 @@ pub(super) fn input_thread(
                            tracing::info!(pad = idx, "gamepad unplugged (native detach)");
                        }
                        // Fresh feedback bookkeeping so a later re-plug on this index inherits no
-                        // stale rumble lease/seq (a lease still ticking would buzz the new pad).
-                        rumble_state[idx] = (0, 0);
-                        rumble_seen[idx] = false;
-                        rumble_seq[idx] = 0;
-                        rumble_stop_burst[idx] = 0;
+                        // stale rumble lease (a lease still ticking would buzz the new pad).
+                        //
+                        // `rumble_seq` deliberately SURVIVES — do not reset it here. The client's
+                        // rumble reorder gate (`client/pump/datagram_task.rs`) is per-CONNECTION
+                        // and has no reset path, so restarting this counter strands every later
+                        // envelope for the re-plugged pad until the host climbs back past the
+                        // value the client already stored (up to 128 sends ≈ 15 s of continuous
+                        // rumble, or dozens of separate rumble events). The three clears below are
+                        // what actually kill a stale lease; the sibling `pad_seq` gate keeps its
+                        // value across a removal for exactly the same reason (see the comment at
+                        // the top of this arm).
+                        clear_pad_feedback(
+                            &mut rumble_state[idx],
+                            &mut rumble_seen[idx],
+                            &mut rumble_stop_burst[idx],
+                        );
                    }
                }
                InputKind::GamepadArrival => {
@@ -1071,6 +1096,72 @@ mod tests {
        }
    }

+    /// A pad re-plug must not strand the client's rumble reorder gate.
+    ///
+    /// The client's `rumble_last_seq` lives for the whole QUIC connection and has no reset path
+    /// (`punktfunk-core/src/client/pump/datagram_task.rs`), so this host's per-pad rumble counter
+    /// has to stay monotonic across a `GamepadRemove`. Regression: the removal arm used to do
+    /// `rumble_seq[idx] = 0`, which made every envelope after a re-plug fail `seq_newer` until the
+    /// counter climbed back past the value the client had already stored — up to 128 sends.
+    ///
+    /// Drives the real wire encoder and the real gate, so it fails if either side's rule moves.
+    #[test]
+    fn rumble_seq_survives_a_removal_so_the_client_gate_accepts() {
+        use punktfunk_core::input::GamepadSnapshot;
+        use punktfunk_core::quic::{decode_rumble_envelope, encode_rumble_datagram_v2};
+
+        // The client half: one per-pad slot, per connection, never reset.
+        let deliver = |seq: u8, gate: &mut Option<u8>| {
+            let d = encode_rumble_datagram_v2(0, 0x4000, 0x8000, seq, 400);
+            let env = decode_rumble_envelope(&d)
+                .expect("v2 envelope decodes")
+                .envelope
+                .expect("v2 tail present");
+            if GamepadSnapshot::seq_newer(env.seq, *gate) {
+                *gate = Some(env.seq);
+                true
+            } else {
+                false
+            }
+        };
+
+        // The host half: one wrapping counter, bumped on every change and every renewal.
+        let mut gate: Option<u8> = None;
+        let mut seq = 0u8;
+
+        // A long rumble before the unplug pushes the client's stored seq well past zero.
+        for _ in 0..100 {
+            seq = seq.wrapping_add(1);
+            assert!(deliver(seq, &mut gate));
+        }
+        assert_eq!(gate, Some(100));
+
+        // The pad is unplugged mid-buzz: the lease is cleared, the counter is not.
+        let (mut state, mut seen, mut burst) = ((0x1234u16, 0x5678u16), true, RUMBLE_STOP_BURST);
+        clear_pad_feedback(&mut state, &mut seen, &mut burst);
+        assert_eq!(
+            (state, seen, burst),
+            ((0, 0), false, 0),
+            "lease not cleared"
+        );
+
+        // It returns on the same wire index and the game rumbles again: the very first envelope
+        // has to reach the actuator.
+        seq = seq.wrapping_add(1);
+        assert!(
+            deliver(seq, &mut gate),
+            "first envelope after a re-plug was dropped by the client's reorder gate"
+        );
+
+        // Non-vacuity: the pre-fix behaviour (counter restarted at 0) really is rejected, and
+        // stays rejected for the whole forward window — this is the bug, reproduced.
+        let mut stranded = Some(100u8);
+        assert!(
+            (1..=100).all(|s| !deliver(s, &mut stranded)),
+            "test is vacuous — a restarted counter should have been gated out"
+        );
+    }
+
    /// Incremental wire events accumulate into the full pad frame the virtual xpad applies.
    #[test]
    fn gamepad_accumulator() {
@@ -1214,6 +1214,9 @@ pub(super) struct SessionContext {
    /// `Reconfigured { accepted: true, mode: <actually live> }` when a rebuild failed (stayed at
    /// the old mode) or the backend honored a different refresh than requested.
    pub(super) reconfig_result_tx: tokio::sync::mpsc::UnboundedSender<Reconfigured>,
+    /// Host-initiated bitrate re-target → control task → the client's `BitrateChanged`. Fired
+    /// by [`adopt_built_bitrate`] when a rebuild lands on a rate the client wasn't told about.
+    pub(super) retarget_tx: tokio::sync::mpsc::UnboundedSender<u32>,
    /// Adaptive-FEC target the control task updates from the client's loss reports.
    pub(super) fec_target: Arc<AtomicU8>,
    /// The QUIC control connection (carries host→client 0xCE source-HDR metadata mid-stream).
@@ -1397,6 +1400,7 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
        probe_rx,
        probe_result_tx,
        reconfig_result_tx,
+        retarget_tx,
        fec_target,
        conn,
        timing_conn,
@@ -1597,7 +1601,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
    ) = pipe;
    // The encoder may have opened at a re-resolved rate (a mirrored head delivering a size this
    // session never negotiated). Adopt it before anything downstream reads `bitrate_kbps`.
-    adopt_built_bitrate(&mut bitrate_kbps, built_bitrate, &live_bitrate);
+    adopt_built_bitrate(
+        &mut bitrate_kbps,
+        built_bitrate,
+        &live_bitrate,
+        &retarget_tx,
+    );

    // Capture is live — launch the requested title so it renders onto the streamed output and
    // grabs focus. Windows spawns the library id into the interactive user session; Linux spawns
@@ -1815,6 +1824,10 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
    // on purpose — it survives every in-loop rebuild path (session switch, mode/stall rebuilds,
    // encoder backoff), so a mid-stream rebuild keeps the acquired lock.
    let mut phase_ctl = PhaseController::new();
+    // Frame-driven wire-rate cap (see [`PaceBudget`]): a loop local like `phase_ctl`, and for the
+    // same reason — it must survive every in-loop rebuild path so a mid-stream rebuild can't
+    // reopen the overshoot. Bounded burst (CAP) is all a rebuild gap can buy.
+    let mut pace = PaceBudget::new(std::time::Instant::now());
    // The session's video frame numbering, owned HERE (the wire `frame_index` of the next AU this
    // loop hands to the send thread; the packetizer seals with exactly this via `seal_frame_at`).
    // A submission's future index is predicted as `au_seq + inflight.len()` — exact because AUs
@@ -2033,7 +2046,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                        // The new compositor may deliver a different size than the old one did (a
                        // Game→Desktop switch onto a mirrored 4K panel is exactly that), so adopt
                        // the rate the rebuilt encoder actually opened at.
-                        adopt_built_bitrate(&mut bitrate_kbps, new_bitrate, &live_bitrate);
+                        adopt_built_bitrate(
+                            &mut bitrate_kbps,
+                            new_bitrate,
+                            &live_bitrate,
+                            &retarget_tx,
+                        );
                        vd = new_vd;
                        compositor = sw.compositor;
                        next = std::time::Instant::now();
@@ -2173,7 +2191,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                    }
                };
            if rebuilt {
-                adopt_built_bitrate(&mut bitrate_kbps, built_bitrate, &live_bitrate);
+                adopt_built_bitrate(
+                    &mut bitrate_kbps,
+                    built_bitrate,
+                    &live_bitrate,
+                    &retarget_tx,
+                );
                cur_mode = new_mode;
                next = std::time::Instant::now();
                // H2/H3: the backend may have honored a different mode than requested — KWin caps
@@ -2302,6 +2325,11 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                );
                if applied_kbps < new_kbps {
                    encoder_ceiling_kbps.store(applied_kbps, Ordering::Relaxed);
+                    // The control task already acked the client with its own resolve, which was
+                    // higher than what the encoder took. Correct it, or the controller climbs
+                    // from a rate the encoder never ran at until its NEXT request happens to be
+                    // pre-clamped by the ceiling we just stored.
+                    let _ = retarget_tx.send(applied_kbps);
                }
                if applied_kbps < bitrate_kbps {
                    // Down-step: the behind-cadence backlog was scored against the old,
@@ -2352,6 +2380,9 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                        enc = new_enc;
                        if applied_kbps < new_kbps {
                            encoder_ceiling_kbps.store(applied_kbps, Ordering::Relaxed);
+                            // As in the in-place arm: the ack the client already has promises
+                            // more than the fresh encoder accepted — correct it.
+                            let _ = retarget_tx.send(applied_kbps);
                        }
                        bitrate_kbps = applied_kbps;
                        live_bitrate.store(applied_kbps, Ordering::Relaxed);
@@ -2793,7 +2824,7 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                // A capture-loss rebuild can land on a different source than it lost (this loop
                // re-detects the session every cycle, precisely so it can follow a switch), so the
                // delivered size — and with it an Automatic rate — may have changed under us.
-                adopt_built_bitrate(&mut bitrate_kbps, new_bitrate, &live_bitrate);
+                adopt_built_bitrate(&mut bitrate_kbps, new_bitrate, &live_bitrate, &retarget_tx);
                enc.request_keyframe(); // belt-and-suspenders; a fresh encoder opens on an IDR anyway
                last_forced_idr = Some(std::time::Instant::now()); // anchor the IDR cooldown from the rebuild
                next = std::time::Instant::now();
@@ -3117,8 +3148,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
        // up to here. Each in-flight frame carries its own (capture_ns, deadline) for when it's polled.
        // Frame-driven mode (T1.1) re-anchors to the ACTUAL submit — arrivals are the clock, and a
        // fixed `+= interval` grid would drift against them and squeeze the pacing budget; the
-        // legacy tick keeps its fixed grid (with the catch-up reset in the tail).
+        // legacy tick keeps its fixed grid (with the catch-up reset in the tail). The rate-cap
+        // charge lives under the same guard as the tail's gate: the legacy tick paces by its grid
+        // alone, and charging it without ever accruing would bank unbounded debt that stalls the
+        // loop if a rebuild later flips the capturer to arrival-wait.
        next = if frame_driven_enabled() && capturer.supports_arrival_wait() {
+            pace.charge();
            std::time::Instant::now() + interval
        } else {
            next + interval
@@ -3389,11 +3424,22 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
                };
                let escalated = cur_depth > 1 || pipelined_active || deescalating;
                // Export "encode can't hold cadence" for the control task's climb refusal.
-                // An escalated session stays flagged even with the bucket drained: its climb
-                // headroom is spent, and letting climbs resume would saw against the
+                // An escalated session is held to a stricter standard — ANY net behind-frame
+                // keeps it flagged, where an unescalated one is given the full bucket — because
+                // its climb headroom really is partly spent and a climb would saw against the
                // escalation and starve the de-escalation clean run below.
+                //
+                // But being escalated cannot flag it BY ITSELF, which is what this used to do.
+                // The client can't tell a transient refusal from an encoder's real ceiling: two
+                // identical short acks latch a cap, so a session that escalated once — the
+                // bucket needs ~20 net misses, which a startup hitch supplies while the ABR is
+                // still in slow start at the 20 Mbps default — got pinned there, and stayed
+                // pinned long after the escalation had bought back the headroom it was for.
+                // Escalating exists precisely so cadence CAN be held; once it is (bucket
+                // drained, every frame on time), refusing climbs is refusing the thing that
+                // worked.
                cadence_degraded.store(
-                    escalated || behind_score >= DEPTH_DEGRADE,
+                    encode_behind_cadence(escalated, behind_score, DEPTH_DEGRADE),
                    Ordering::Relaxed,
                );
                if deescalating {
@@ -3477,9 +3523,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
            // T1.1 frame-driven trigger: instead of sleeping out the whole tick and then
            // SAMPLING (which holds a frame that arrived just after the previous sample for up
            // to a full interval — ~half on average), sleep only to the rate floor and then
-            // wake on the capture's actual arrival. The 0.9×interval floor caps the encode
-            // rate at ~1.11× target when the source runs faster (compositor Hz > session fps);
-            // the +0.5×interval keepalive keeps a static desktop re-encoding (bitrate shape,
+            // wake on the capture's actual arrival. The 0.9×interval floor leaves per-gap jitter
+            // headroom; the `pace` budget pins the long-run AVERAGE at the pacing rate — the
+            // floor alone let a source that always has a frame pending (an HZ_MULT-overdriven
+            // display under uncapped content) settle at 0.9-interval spacing, 1.11× the
+            // negotiated rate on the wire, frames the client's panel can only drop. The
+            // +0.5×interval keepalive keeps a static desktop re-encoding (bitrate shape,
            // client liveness) at 1.5×interval cadence and bounds control-servicing latency.
            //
            // Anchor the floor to THIS frame's arrival (`t_cap`), not to `next` — `next` is
@@ -3489,9 +3538,12 @@ pub(super) fn virtual_stream(ctx: SessionContext, prepared: Option<PreparedDispl
            // period becomes interval + encode (≈158 fps off a 240 Hz source; 360 Hz → ~200).
            // An async encoder (NVENC) returns from submit in ≈0, so t_cap ≈ post-submit and this
            // is a no-op for it — which is why H.26x already holds full rate. Arrival-anchoring
-            // lets the synchronous encode overlap the interval; the ≥0.9×interval spacing from
-            // the last grab still caps the rate at ~1.11× target.
-            let earliest = t_cap + interval.mul_f32(0.9);
+            // lets the synchronous encode overlap the interval; the budget, not the floor, is
+            // what bounds the sustained rate.
+            let earliest = std::cmp::max(
+                t_cap + interval.mul_f32(0.9),
+                pace.earliest(std::time::Instant::now(), interval),
+            );
            if let Some(d) = earliest.checked_duration_since(std::time::Instant::now()) {
                std::thread::sleep(d);
            }
@@ -4001,13 +4053,95 @@ fn pacing_hz(session_hz: u32, achieved_hz: u32) -> u32 {
    achieved_hz.min(session_hz).max(1)
 }

+/// Long-run rate limiter for the frame-driven trigger (T1.1): pins the AVERAGE encode rate at the
+/// pacing rate while the 0.9×interval arrival floor keeps its jitter headroom.
+///
+/// The floor alone bounds only each gap, so a source that always has a frame pending — a display
+/// overdriven by `PUNKTFUNK_VDISPLAY_HZ_MULT`, uncapped content — settles at 0.9-interval spacing:
+/// 1.11× the negotiated rate on the wire (field report: 132 fps on a 120 fps session, frames the
+/// client's 120 Hz panel can only drop). Credit accrues at one frame per interval of real elapsed
+/// time (capped at [`Self::CAP`]) and every submitted frame spends one; a grab may run early only
+/// against banked credit, so per-gap jitter still passes while the average cannot exceed the
+/// pacing rate. A source at or below the pacing rate banks credit faster than it spends and is
+/// never delayed.
+struct PaceBudget {
+    /// Banked frames, in `[-1.0, CAP]`. Transiently dips below 0 when a grab spent credit it had
+    /// only partly banked; the owed fraction is repaid before the next grab.
+    credit: f32,
+    /// When credit last accrued (the previous [`Self::earliest`] call).
+    last: std::time::Instant,
+}
+
+impl PaceBudget {
+    /// Burst allowance: at most this many frames may follow a stall back-to-back before the
+    /// bucket re-gates. One frame of instant catch-up plus the floor's own headroom.
+    const CAP: f32 = 1.25;
+
+    fn new(now: std::time::Instant) -> PaceBudget {
+        PaceBudget {
+            credit: Self::CAP,
+            last: now,
+        }
+    }
+
+    /// Accrue the elapsed credit and return the earliest instant the next grab may run: `now`
+    /// once a full frame is banked, else the missing fraction of an interval out.
+    fn earliest(
+        &mut self,
+        now: std::time::Instant,
+        interval: std::time::Duration,
+    ) -> std::time::Instant {
+        let secs = interval.as_secs_f32();
+        if secs > 0.0 {
+            let accrued = now.duration_since(self.last).as_secs_f32() / secs;
+            self.credit = (self.credit + accrued).min(Self::CAP);
+        }
+        self.last = now;
+        now + interval.mul_f32((1.0 - self.credit).max(0.0))
+    }
+
+    /// One frame submitted — spend its credit.
+    fn charge(&mut self) {
+        self.credit -= 1.0;
+    }
+}
+
+/// Does the encoder currently fail to hold the frame cadence? Exported to the control task, which
+/// refuses bitrate CLIMBS while it is true (descents always pass — they are the cure).
+///
+/// `escalated` = the session has already spent an adaptive-depth / pipelined-retrieve step to buy
+/// headroom; `behind_score` is the leaky bucket of frames whose work overran the cadence deadline.
+/// An escalated session is judged strictly — ANY net behind-frame keeps it flagged — but being
+/// escalated does not flag it on its own. That distinction is the whole point: the client cannot
+/// tell a transient refusal from an encoder's hard ceiling (two identical short acks latch a cap),
+/// so "escalated ⇒ degraded, permanently" pinned Automatic sessions at whatever rate they happened
+/// to hold when a startup hitch escalated them — routinely the 20 Mbps default, while slow start
+/// had barely begun. Escalation exists so cadence CAN be held; once it is, refusing climbs refuses
+/// the thing that worked.
+fn encode_behind_cadence(escalated: bool, behind_score: u32, degrade_at: u32) -> bool {
+    behind_score >= degrade_at || (escalated && behind_score > 0)
+}
+
 /// Adopt the rate a freshly built pipeline's encoder was actually opened at.
 ///
 /// The session's own `bitrate_kbps` is the number every later decision reads — the ABR controller's
 /// climb base, the console's sample, what a `SetBitrate` ack is measured against — so letting it
 /// disagree with the live encoder means each of those reasons about a stream that doesn't exist.
 /// Silent when nothing changed, which is the overwhelmingly common case.
-fn adopt_built_bitrate(current: &mut u32, built: u32, live: &Arc<AtomicU32>) {
+///
+/// The client keeps its OWN copy of that number, and it used to move only on an ack — so a
+/// rebuild that re-resolved an Automatic rate (`build_pipeline` does, whenever the source
+/// delivers a size the session did not negotiate) left the two disagreeing for the rest of the
+/// session. The ABR's next climb then computed from the stale base and asked for a rate BELOW
+/// what the host was already sending: a re-target downward, paying an encoder rebuild to get
+/// there. So tell the client too — `BitrateChanged` is the same message the `SetBitrate` path
+/// answers with, and means the same thing arriving unprompted.
+fn adopt_built_bitrate(
+    current: &mut u32,
+    built: u32,
+    live: &Arc<AtomicU32>,
+    retarget: &tokio::sync::mpsc::UnboundedSender<u32>,
+) {
    if built == *current {
        return;
    }
@@ -4018,6 +4152,7 @@ fn adopt_built_bitrate(current: &mut u32, built: u32, live: &Arc<AtomicU32>) {
    );
    *current = built;
    live.store(built, Ordering::Relaxed);
+    let _ = retarget.send(built); // control task gone ⇒ the session is ending anyway
 }

 /// Encode-stall recovery: rebuild the encoder in place (keeping capture + the session up) and
@@ -4122,9 +4257,19 @@ fn build_pipeline(
    // VIDEO_CAP_10BIT + host opted in via PUNKTFUNK_10BIT) is our HDR path → BT.2020 PQ Rgb10a2;
    // otherwise the FP16 IDD frames are converted to 8-bit SDR. (Ignored by non-IDD-push backends,
    // which auto-detect HDR from the monitor state.)
-    let mut capturer =
-        crate::capture::capture_virtual_output(vout, plan.output_format(), plan.capture)
-            .context("capture virtual output")?;
+    //
+    // KWin rewrites `SPA_META_Cursor` on every buffer, so its id-0 metas are an authoritative
+    // "pointer hidden" the cursor blend/forward must honor — without this, the composited arrow
+    // outlives every in-game/Big Picture hide (0.22.0 field report). Derived from the backend
+    // (correct for pooled reuse too — a kept display only matches its own backend).
+    let cursor_id0_hides = vd.name() == pf_vdisplay::Compositor::Kwin.id();
+    let mut capturer = crate::capture::capture_virtual_output(
+        vout,
+        plan.output_format(),
+        plan.capture,
+        cursor_id0_hides,
+    )
+    .context("capture virtual output")?;
    // gamescope (Phase C): gamescope paints no `SPA_META_Cursor`, so hand the capturer a way to
    // reach gamescope's nested Xwaylands — it reads the pointer over X11 (XFixes shape +
    // QueryPointer position) and feeds `cursor()`, which the encode loop composites.
@@ -4252,6 +4397,38 @@ fn build_pipeline(
 mod tests {
    use super::*;

+    #[test]
+    fn an_escalated_but_caught_up_encoder_stops_refusing_climbs() {
+        const DEGRADE: u32 = 10;
+        // Not escalated: the full bucket is allowed before climbs are refused.
+        assert!(!encode_behind_cadence(false, 0, DEGRADE));
+        assert!(!encode_behind_cadence(false, 9, DEGRADE));
+        assert!(encode_behind_cadence(false, 10, DEGRADE));
+        // Escalated and still missing deadlines: strict — one net behind-frame is enough.
+        assert!(encode_behind_cadence(true, 1, DEGRADE));
+        // Escalated, bucket fully drained: cadence is being HELD, which is what escalating was
+        // for. This is the case that used to stay latched for the rest of the session and pin an
+        // Automatic client at its slow-start rate.
+        assert!(!encode_behind_cadence(true, 0, DEGRADE));
+    }
+
+    #[test]
+    fn adopting_a_rebuilt_rate_tells_the_client() {
+        let live = Arc::new(AtomicU32::new(20_000));
+        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel::<u32>();
+        let mut current = 20_000;
+        // The overwhelmingly common case: the rebuild landed on the same rate — silent.
+        adopt_built_bitrate(&mut current, 20_000, &live, &tx);
+        assert_eq!(rx.try_recv().ok(), None);
+        // A re-resolve (the client asked 1080p, the source delivers a mirrored 4K panel): the
+        // host's rate moves, so the client has to hear about it — its controller's climb base is
+        // its own copy of this number, and a stale one makes the next "climb" a cut.
+        adopt_built_bitrate(&mut current, 60_000, &live, &tx);
+        assert_eq!(current, 60_000);
+        assert_eq!(live.load(Ordering::Relaxed), 60_000);
+        assert_eq!(rx.try_recv().ok(), Some(60_000));
+    }
+
    #[test]
    fn pacing_never_exceeds_the_session_rate_or_the_display() {
        // Backend honored the request exactly (the multiplier off): pace at it.
@@ -4270,6 +4447,105 @@ mod tests {
        assert_eq!(pacing_hz(60, 0), 1);
    }

+    /// Drive [`PaceBudget`] against a source that ALWAYS has a frame pending (the overdriven
+    /// display + uncapped content case): each cycle grabs the instant the gate opens, the next
+    /// `earliest` call runs right after (encode folded into the wait, like the loop). Returns the
+    /// grab instants.
+    fn grab_saturated(
+        b: &mut PaceBudget,
+        start: std::time::Instant,
+        interval: std::time::Duration,
+        n: usize,
+    ) -> Vec<std::time::Instant> {
+        let mut now = start;
+        let mut grabs = Vec::with_capacity(n);
+        for _ in 0..n {
+            let gate = b.earliest(now, interval);
+            let grab = gate.max(now);
+            b.charge();
+            grabs.push(grab);
+            now = grab;
+        }
+        grabs
+    }
+
+    #[test]
+    fn pace_budget_pins_a_saturated_source_at_the_interval() {
+        let interval = std::time::Duration::from_millis(10);
+        let t0 = std::time::Instant::now();
+        let mut b = PaceBudget::new(t0);
+        let grabs = grab_saturated(&mut b, t0, interval, 120);
+        // Whatever the initial credit bought, the total may exceed the on-rate schedule by at
+        // most the burst cap — 120 grabs span no less than (120 - 1 - CAP) intervals.
+        let span = grabs[119].duration_since(grabs[0]);
+        assert!(
+            span >= interval.mul_f32(120.0 - 1.0 - PaceBudget::CAP),
+            "span {span:?} admits more than CAP frames of overshoot"
+        );
+        // And the steady state is EXACTLY the interval: past the warmup, consecutive grabs are
+        // one interval apart (not 0.9 — the 132-fps bug).
+        for w in grabs[20..].windows(2) {
+            let gap = w[1].duration_since(w[0]);
+            assert!(
+                gap >= interval.mul_f32(0.999) && gap <= interval.mul_f32(1.001),
+                "steady-state gap {gap:?} != interval {interval:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn pace_budget_never_delays_an_on_rate_or_slow_source() {
+        let interval = std::time::Duration::from_millis(10);
+        let t0 = std::time::Instant::now();
+        let mut b = PaceBudget::new(t0);
+        // A source at half the pacing rate (a 60 fps game on a 120 fps session): every arrival
+        // banks two frames of credit and spends one — the gate is always already open.
+        let mut now = t0;
+        for _ in 0..50 {
+            now += interval * 2;
+            assert_eq!(
+                b.earliest(now, interval),
+                now,
+                "slow source must not be gated"
+            );
+            b.charge();
+        }
+        // Exactly on-rate: still never gated (credit hovers at the cap, never below 1).
+        let mut b = PaceBudget::new(t0);
+        let mut now = t0;
+        for _ in 0..50 {
+            now += interval;
+            assert_eq!(
+                b.earliest(now, interval),
+                now,
+                "on-rate source must not be gated"
+            );
+            b.charge();
+        }
+    }
+
+    #[test]
+    fn pace_budget_burst_after_a_stall_is_capped() {
+        let interval = std::time::Duration::from_millis(10);
+        let t0 = std::time::Instant::now();
+        let mut b = PaceBudget::new(t0);
+        // Settle into the gated steady state, then stall the source for 10 intervals.
+        let grabs = grab_saturated(&mut b, t0, interval, 20);
+        let stall_end = grabs[19] + interval * 10;
+        // However long the stall, the recovery may run ahead of the on-rate schedule by at most
+        // CAP frames: the second post-stall grab is already re-gated.
+        let after = grab_saturated(&mut b, stall_end, interval, 3);
+        assert_eq!(after[0], stall_end, "first post-stall grab is immediate");
+        assert!(
+            after[1].duration_since(after[0]) >= interval.mul_f32(2.0 - PaceBudget::CAP),
+            "second post-stall grab spent more than the burst cap"
+        );
+        assert!(
+            after[2].duration_since(after[1]) >= interval.mul_f32(0.999),
+            "third post-stall grab must be back on the interval grid"
+        );
+    }
+
    #[test]
    fn display_mode_multiplier_scales_only_the_refresh() {
        // Default (no env set in the test process) is 1× — the identity, which is what every
@@ -118,6 +118,7 @@ pub fn run(opts: Options) -> Result<()> {
                vout,
                capture::OutputFormat::resolve(false, crate::encode::resolved_backend_is_gpu()),
                crate::session_plan::CaptureBackend::resolve(),
+                compositor == crate::vdisplay::Compositor::Kwin,
            )
            .context("capture virtual output")?
        }
@@ -237,6 +237,13 @@ the session, gives it back if anything crashes, and tells you which half of the
 it isn't working. That is the supported route, and the rest of this section is only for people who
 would rather not install a plugin.

+**Turn off controller forwarding on the couch.** Whatever route you take below, the client that
+hands the device over should stop *also* forwarding it: Settings → **Forward controllers**, off
+([Client settings](/docs/client-settings#input)). Otherwise the host ends up with two controllers
+for one pair of hands and games read both. On Linux and Windows it matters twice over — while the
+client has the pad open it has *claimed* the device node, and VirtualHere cannot bind a device
+somebody else is holding.
+
 **The two sides.** VirtualHere is a server/client pair, and you run both: the **server on the couch**
 (where the device is plugged in) shares it, and the **client on the host** mounts it. The client's
 `-t` flag is a one-shot IPC to the already-running client — `-t LIST` prints every visible device
@@ -15,8 +15,10 @@ The Linux, Windows, Mac, iPhone/iPad and Android apps group settings the same wa
 **Display**, **Input**, **Audio**, **Controllers** — under *Preferences* on Linux and *Settings*
 elsewhere. The Apple TV app shows one scrolling list instead, and so does any client's settings
 screen reached with a controller. A controller-driven launch (Steam Deck Gaming Mode) opens the
-client's **console home**, whose settings screen is one steppable list; the Decky plugin has a
-smaller section of its own. The console home is part of the client — it is not the host's
+client's **console home**, whose settings screen is one steppable list; the Decky plugin's Settings
+tab covers the same store in the same groups and the same order, as a left rail of categories the
+way SteamOS's own Settings looks. The console home is part of the
+client — it is not the host's
 [web console](/docs/web-console).

 Linux stores them in `~/.config/punktfunk/client-gtk-settings.json`, the same file the Decky plugin
@@ -43,8 +45,9 @@ and your client scales what it gets — see

 **Match window** — *default: off.* The stream mode follows your window instead, and each resize
 renegotiates the host's display and encoder, so a windowed session stays pixel-exact. Fullscreen
-degenerates to the display's native mode. Offered by the Linux, Windows, Mac, iPhone/iPad and console
-home screens; not by Android or Decky.
+degenerates to the display's native mode. Offered by the Linux, Windows, Mac, iPhone/iPad, console
+home and Decky screens (on Decky it sits in the Resolution picker, and Gaming-Mode streams are
+always fullscreen, so it lands on native); not by Android.

 **Refresh rate** — *default: Native*, the refresh of the display your window is on. The Apple app
 stores an explicit rate (60 Hz by default): iPhone and iPad offer the rates the device can display,
@@ -69,8 +72,8 @@ link. The stops run 0.5× to 4×. The result is floored to an even size and capp

 **Video codec** — *default: Automatic.* A soft preference: the host emits your choice when it can
 also produce it, otherwise the best codec you both speak, in the order HEVC → AV1 → H.264.
-**PyroWave** is never auto-picked — pick it explicitly on Linux, Windows, the console home, or an
-Apple device whose decode probe passes; anywhere else it isn't offered, and asking for it lands on
+**PyroWave** is never auto-picked — pick it explicitly on Linux, Windows, the console home, Decky, or
+an Apple device whose decode probe passes; anywhere else it isn't offered, and asking for it lands on
 that same order. See [PyroWave](/docs/pyrowave). The Android and Apple apps hide AV1 unless the
 device has a hardware AV1 decoder; Android never offers PyroWave.

@@ -82,9 +85,38 @@ Full detail: [HDR](/docs/hdr).
 **Full chroma (4:4:4)** — *default: off.* Crisp small text and thin lines, at more bandwidth. It
 needs HEVC or PyroWave, the host's own 4:4:4 policy left on, a capture path that delivers full
 chroma, and a GPU that can encode it; if any gate fails the host says 4:2:0 before your decoder is
-built. **Today only the Apple app actually advertises 4:4:4**, and only when its hardware decode
-probe passes — the Linux and Windows apps store the toggle but their session doesn't advertise the
-capability yet, so it has no effect there. Android, Decky and the console home don't offer it.
+built. The Apple, Linux and Windows apps all advertise it (Apple additionally requires its hardware
+decode probe to pass). The console home and Decky offer the toggle; Android doesn't.
+
+**Prioritize** — *default: Lowest latency.* What the client optimizes for when a decoded frame is
+ready. **Lowest latency** shows every frame the moment the display can take it, so a network hiccup
+becomes an occasional repeated or skipped frame. **Smoothness** holds a small buffer that evens
+those hiccups out, at that buffer's worth of added delay. Linux and Windows apps, the console home
+and Decky; the Apple and Android apps have carried the same setting for a while, and it is stored
+under the same name, so a [profile](/docs/profiles-and-links) means the same thing on every device.
+
+**Smoothness buffer** — *default: Automatic (two frames).* Only shown under **Smoothness**. How
+many frames are held back before showing. Each frame absorbs roughly one screen refresh of network
+hiccup and costs one refresh of delay — so on a 120 Hz screen, two frames is about 17 ms of extra
+delay bought against 17 ms of jitter. If you never see stutter, you don't need this. Wherever
+**Prioritize** is offered, and greyed out until you pick Smoothness.
+
+**V-Sync** — *default: on.* Tear-free presentation. Turning it off asks the GPU to show each frame
+the instant it's ready instead of waiting for the screen's next refresh: the lowest delay a display
+can give you, at the cost of visible tearing on fast motion. It is **best-effort** — not every
+driver or compositor offers a tearing mode, and where none is available the stream stays tear-free.
+The Detailed [stats overlay](/docs/stats) names the mode actually in use, so you can tell "off"
+from "off but unavailable". Linux and Windows apps, the console home and Decky.
+
+**Follow variable refresh rate** — *default: on.* On a VRR / FreeSync / G-Sync screen, let the panel
+refresh in step with the stream rather than on a fixed cadence — which removes the wait between a
+frame being ready and the screen being willing to show it. Applies to **fullscreen** sessions (a
+windowed one is at the compositor's mercy) and is harmless on a fixed-refresh screen. It needs a
+graphics driver that offers the modern queue-free display mode; on an older driver it does nothing
+unless you also set `PUNKTFUNK_VRR_FIFO=1` (see [configuration](/docs/configuration)), because the
+older way of following a panel costs noticeable latency on a fixed-refresh screen. The stats overlay
+reports `vrr yes` once it has *measured* that the panel really is following. Linux and Windows apps,
+the console home and Decky.

 **Host compositor** — *default: Automatic.* Which backend a **Linux** host uses to drive the virtual
 output. Advisory: a host without that backend quietly auto-detects instead.
@@ -96,7 +128,7 @@ stereo. The count the host will really send comes back in the handshake, and you
 decoder from *that*, never from the request. What surround means differs by host: a **Linux** host
 claims a sink advertising exactly that many channels, so applications produce real surround, while a
 **Windows** host loopback-captures your current output endpoint and lets Windows convert it — so 5.1
-from a stereo endpoint is an upmix, not new channels. Offered everywhere except the Decky plugin.
+from a stereo endpoint is an upmix, not new channels. Offered everywhere.

 **Microphone** — *default: off on Linux, Windows, Android, the console home and Decky; on in the
 Apple app.* Sends this device's microphone to the host's virtual mic. On Linux and Windows the
@@ -110,22 +142,44 @@ from an echo-cancelled PipeWire source when your desktop provides one, on **Wind
 for the Communications stream category so the endpoint's processing engages, and on **Apple** and
 **Android** the platform's voice-processing mode. Turn it off if your microphone already runs its
 own processing, or if the canceller makes your voice sound thin. The row sits under the microphone
-toggle and greys out while the microphone is off. Offered by the Linux, Windows, Apple, Android and
-console-home clients; Decky has no toggle. What it can and can't fix is in
+toggle and greys out while the microphone is off. Offered by the Linux, Windows, Apple, Android,
+console-home and Decky clients. What it can and can't fix is in
 [Why do I hear myself](/docs/echo).

 **Speaker** and **Microphone** device pickers — *default: System default.* Which endpoint stream
-audio plays out of, and which input feeds the uplink. Only the Linux app (PipeWire nodes) and the
-**Mac** app (which also has a microphone *channel* picker) have these — iPhone, iPad, Apple TV,
-Android, Decky and the console home have none, and the Windows app has none and ignores a stored
+audio plays out of, and which input feeds the uplink. Only the Linux app (PipeWire nodes), the
+**Mac** app (which also has a microphone *channel* picker) and **Decky** have these — iPhone, iPad,
+Apple TV, Android and the console home have none, and the Windows app has none and ignores a stored
 speaker choice. On Linux, a device that has since disappeared keeps a "(not detected)" entry rather
-than silently snapping back to the default; the Mac shows it as "Unavailable device".
+than silently snapping back to the default; the Mac shows it as "Unavailable device" and Decky as
+"(not connected)". Decky reads the endpoint list from the client's session binary, so a client
+older than the two-binary split leaves these pickers on Automatic.

 ## Input

-Touch modes, mouse modes and the in-stream chords have their own page: [Input](/docs/input). Four
+Touch modes, mouse modes and the in-stream chords have their own page: [Input](/docs/input). Five
 more settings are worth naming here.

+**Forward controllers** — *default: on*, on every client. Off, the controllers connected to *this*
+device are not sent to the host at all. That is what you want when your controller already reaches
+the host by some other route — [USB passthrough](/docs/automation#recipe-full-controller-passthrough-virtualhere)
+such as VirtualHere, or simply a pad plugged into the host itself. Leaving forwarding on in that
+situation hands the host two controllers for one pair of hands, and games read both: a stick drifts
+because the second pad is centred, or a menu takes every input twice.
+
+On Linux and Windows it does more than stay quiet. Opening a controller is what *claims* it — the
+client's SDL takes the device node — and a claimed device is one a passthrough tool cannot bind. So
+with this off the session never opens the controller at all, which is precisely what leaves it free
+for VirtualHere to hand over. The consequence to know: the
+[controller escape chord](/docs/input#leaving-with-a-controller) is read off forwarded pads, so it is
+unavailable on those two while this is off — leave a stream with the keyboard chord or the client's
+own UI. The Apple and Android apps claim nothing, so their chords keep working either way; the
+Android app does stop its DualSense and Steam Controller 2 USB captures, which *do* claim the
+device.
+
+The rows below it — which pad, and what type — have nothing to act on while this is off, and every
+client greys them out to say so.
+
 **Gamepad type** (*Controller type* on Apple, Android and the console home) — *default: Automatic*,
 which matches each physical controller. The pickers offer Xbox 360, Xbox One, DualSense and
 DualShock 4 everywhere, plus Steam Deck on Linux, Android, the console home and Decky. Your client
@@ -139,8 +193,10 @@ which forwards *every* connected controller, each as its own player, on Linux, W
 console home. Pinning one restricts the session to that controller alone — single-player. The Android
 app has no such picker.

-**Capture system shortcuts** — *default: on.* Offered by the Linux and Windows apps only; Windows
-spells the row out as *Capture system shortcuts (Alt+Tab, Win, …)*. On, Alt+Tab and the Windows key
+**Capture system shortcuts** — *default: on.* Offered by the Linux and Windows apps, the console home
+and Decky; Windows spells the row out as *Capture system shortcuts (Alt+Tab, Win, …)*. On a Deck it
+matters only for a keyboard you attached yourself, for the reason the paragraph below gives: Gaming
+Mode is gamescope, which has nothing to hold back. On, Alt+Tab and the Windows key
 (Super on Linux) reach the host while the stream has input captured. Off, they act on this machine
 instead — what you want when the stream shares a screen with local work. Either way the chords come
 back the moment you release capture with **Ctrl+Alt+Shift+Q**, the window loses focus, or the stream
@@ -159,17 +215,22 @@ the wlroots compositors all do, and X11 sessions grab the keyboard directly. Und
 Wake-on-LAN and waits for it to boot — only for a host whose MAC address this client has already
 learned. Turn it off for hosts you reach over a VPN, where "offline" usually means "not reachable by
 broadcast" and the wake only adds a delay. The Linux, Windows, Apple and Android apps have this
-toggle. The console home has no toggle — it offers wake as an explicit action on an offline host
-instead — and the Decky plugin always sends a wake before a stream starts. See
+toggle, as do the console home and Decky — and note that the Decky plugin sends a wake of its own
+before a stream starts whatever this setting says, so on a Deck it governs the client's connect
+rather than the launch. The console home also offers wake as an explicit action on an offline host.
+See
 [Wake-on-LAN](/docs/wake-on-lan).

 **Show game library** — *default: off on Linux and Windows; on in the Apple and Android apps.* Browse
-a paired host's games and launch one directly; the Windows app still labels it experimental. There is
-no toggle in the console home or in Decky. See [Game library](/docs/game-library).
+a paired host's games and launch one directly; the Windows app still labels it experimental. The
+console home and Decky have the toggle too — on Decky it governs the *client's* screens, since the
+plugin's own library browser works either way. See [Game library](/docs/game-library).

 **Start streams in fullscreen** — *default: on.* On Linux and Windows, F11 or Alt+Enter leaves
 fullscreen live. On a Mac the setting is **Fullscreen while streaming**, and the window comes back
-when you return to the host list. iPhone, iPad, Apple TV and Android have no equivalent.
+when you return to the host list. The console home and Decky carry the row for the desktop client
+that shares the store — a Gaming-Mode launch is fullscreen whatever it says. iPhone, iPad, Apple TV
+and Android have no equivalent.

 ## Overlay

@@ -177,7 +238,8 @@ when you return to the host list. iPhone, iPad, Apple TV and Android have no equ
 superset of the one before. This setting only picks the tier a session *starts* at — you can cycle
 them live in-stream, with a shortcut that differs by platform. The Apple app additionally lets you
 choose which corner the overlay sits in (Top Left, Top Right, Bottom Left, Bottom Right). The Decky
-plugin has no stats setting. The shortcuts, and every number in the overlay, are in
+plugin has the tier picker too, in its Settings section. The shortcuts, and every number in the
+overlay, are in
 [Understanding the stats overlay](/docs/stats).

 ## Settings that are facts about your device
@@ -189,11 +251,14 @@ stay global and **cannot be put in a settings profile**:
  vendor-ordered and falls back on its own; change it only when debugging, and note that
  `PUNKTFUNK_DECODER` overrides it
  ([Configuration](/docs/configuration#client-side-native-clients)). The decoder picker is on Linux,
-  Windows and in the console home; the GPU picker on Windows, and on Linux only when the machine has
-  more than one adapter. The Apple and Android apps have neither.
+  Windows, in the console home and in Decky; the GPU picker on Windows, and on Linux and Decky only
+  when the machine has more than one adapter — which a Deck doesn't, so the row isn't there. The
+  Apple and Android apps have neither.
 - **Speaker** and **Microphone** device pickers — this device's audio endpoints.
 - **Forwarded controller** — which physical pad is in your hands. The *type* the host creates is a
-  preference and can live in a profile; which pad you hold cannot.
+  preference and can live in a profile; which pad you hold cannot. **Forward controllers** is a
+  preference too, and does live in a profile — a work profile can decline to forward what a game
+  profile forwards.
 - **Auto-wake on connect** and **Show game library** — decisions about this device and this network,
  not about how a given host is streamed.

@@ -242,6 +242,9 @@ A few knobs are read by the native **clients**, not the host:
 | `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_PRESENTER` | `arrival` | Turn the frame-pacing engine off for this run: frames present the instant they decode, exactly as they did before the **Prioritize** setting existed. A diagnostic — if a pacing change is suspected of causing judder or added delay, this switches it off without reinstalling anything. Linux and Windows clients. |
+| `PUNKTFUNK_VRR_FIFO` | `1` | Force the display mode used to follow a **variable-refresh (VRR / FreeSync / G-Sync)** screen, on graphics drivers too old to offer the modern one. You almost certainly don't need this: where the driver supports the modern mode — which is what **Follow variable refresh rate** in [client settings](/docs/client-settings#video) uses — following the panel is already automatic and costs almost nothing. On an older driver the only way to follow the panel is a mode that measured roughly 27 ms *worse* on a fixed-refresh screen, so it stays off unless you ask for it, and it's only worth asking if you genuinely have a VRR screen and play fullscreen. Check the Detailed [stats overlay](/docs/stats): `vrr yes` means the panel really is following the stream. Linux and Windows clients. |
+| `PUNKTFUNK_PRESENT_DEBUG` | `1` | Log the presenter's own 1-second summary (display mode, buffer drops, pacing counters) every second, even when nothing is going wrong. Without it the line appears only when there is something to report. |
 | `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. |
@@ -92,6 +92,12 @@ an Xbox pad), held on any connected pad.
 - **Android** — holding it about a second disconnects. A quick press does nothing; the moment the
  chord completes a **Hold to quit…** cue appears so you know it registered.

+The chord is read off the pads a client forwards, so turning
+[**Forward controllers**](/docs/client-settings#input) off takes it away on **Linux and Windows** —
+there the client stops opening the controller at all, which is the point of the setting. Use
+**Ctrl+Alt+Shift+D** or the client's own UI to leave instead. The Apple and Android apps keep
+watching for the chord either way.
+
 ## Mouse modes

 There are two, and they are a per-client setting called **Mouse input**:
@@ -295,8 +295,23 @@ installer's `PATH` change, or call the exe by full path. On Linux the host packa
 On SteamOS, re-run `scripts/steamdeck/install.sh` (or
 `scripts/steamdeck/update.sh`). On Windows, re-run the installer and keep the scripting component.

-**The plugin doesn't show up in the console** — check the runner is actually running with
-`punktfunk-host plugins status`, then look at its log:
+**Where a plugin's log output goes** — the console's **Logs** page, under the **Plugins** filter.
+The runner ships everything your plugins print to the host, so a plugin's own lines sit next to the
+host's, on one timeline, with the same search and download. Each is tagged `plugin:<name>` — the
+plugin's own name for lines it logged itself, `plugin:runner` for the supervisor's (starting a
+plugin, restarting a crashed one, refusing an unsafe file).
+
+An empty Plugins view almost always means the runner isn't running — it is a separate service, and
+opt-in on Linux. Check with `punktfunk-host plugins status`.
+
+<Callout>
+Nothing is lost if the host is down: the runner keeps buffering and sends the backlog when the host
+comes back. It says so in the log if the buffer overflowed, rather than presenting a gap as
+continuity.
+</Callout>
+
+**Reading the runner's log directly** — rarely needed now, but it is the ground truth if the runner
+can't reach the host at all:

 <Tabs items={['Linux', 'Windows']}>
 <Tab value="Linux">
@@ -318,6 +333,22 @@ plugins (stop it with <kbd>Ctrl</kbd>+<kbd>C</kbd>):
 </Tab>
 </Tabs>

+**A plugin can't reach a service running on the same box (Linux)** — plugins that drive a local
+daemon usually talk to it over a socket or FIFO in `/tmp`. The runner's unit shipped with
+`PrivateTmp=yes` in earlier releases, which gave it a private `/tmp` and hid all of it: the plugin would
+launch the vendor's binary happily and then time out reaching the daemon behind it, while the same
+command worked perfectly in your own shell. If you are on an older host, or you have a drop-in that
+reinstates it, put the real `/tmp` back:
+
+```sh
+systemctl --user edit punktfunk-scripting
+```
+```ini
+[Service]
+PrivateTmp=no
+ReadWritePaths=/tmp
+```
+
 ## Writing your own

 A plugin is a TypeScript module built on **`@punktfunk/plugin-kit`** (`definePluginKit`), supervised
@@ -62,8 +62,9 @@ differently. Linux · Windows · Steam Deck:

 ```
 1920×1080@120 · 120 fps · 24.3 Mb/s · target 30 Mb/s (auto) · vulkan · HDR
-e2e 14.2/19.8 ms (p50/p95) · host 3.1 · net 6.7 · decode 2.1 · display 2.3 ms
+e2e 14.2/19.8 ms (p50/p95) · host 3.1 · net 6.7 · decode 2.1 · display 2.3 ms (pace 0.6 + latch 1.7)
 host: queue 0.6 · encode 1.8 · xfer 0.2 · pace 0.5 ms
+present: mailbox
 lost 3 (2.4%)
 ```

@@ -109,10 +110,11 @@ lost 3 (2.4%)
  which otherwise reads as inexplicable judder plus a refresh of extra latency.
 - **Line 2 — the headline.** `end-to-end` (`e2e` on Linux/Windows) is the *directly
  measured* time from host capture to the endpoint named at the end of the line —
-  `capture→on-glass` or `capture→displayed`. Linux/Windows don't spell the endpoint out,
-  because their presenter always measures to the present instant. `p50` = the typical
-  frame (median), `p95` = the slow outliers. This is the one number that summarizes your
-  stream.
+  `capture→on-glass` or `capture→displayed`. On Linux/Windows the endpoint is the moment
+  the frame is genuinely **visible** wherever the GPU driver can report it (most can);
+  where it can't, the measurement stops at the instant the frame is handed to the display
+  and so reads slightly optimistic. `p50` = the typical frame (median), `p95` = the slow
+  outliers. This is the one number that summarizes your stream.
 - **Line 3 — where the time goes.** The first four stages **tile the end-to-end interval** —
  each starts where the previous one ends, so they add up to the headline. The two extra
  terms under them are not extra time: one is excluded from the total, the other sits inside a
@@ -123,7 +125,12 @@ lost 3 (2.4%)
    reassembly on your device.
  - `decode` — received → decoded, on your device.
  - `display` — decoded → displayed: waiting for the right screen refresh, rendering,
-    and vsync.
+    and vsync. On Linux/Windows it splits into `(pace + latch)` when your driver reports
+    true on-glass timing: **pace** is Punktfunk's own work — getting the decoded frame
+    submitted — and **latch** is the wait for the display to take it. A large `latch` is
+    the screen's refresh cycle, not the stream; a large `pace` is us. (`pace` is also the
+    fair number to compare against an iPhone or iPad, whose figure already has its
+    equivalent of `latch` removed.)
  - `os present` *(iOS and tvOS)* — the fixed depth of the OS present pipeline, which is
    excluded from both the headline and `display` and printed here so you can add it
    back.
@@ -143,6 +150,15 @@ lost 3 (2.4%)
  encode … · xfer … · pace …` — splitting the host's own share into its stages, when the
  host reports them.

+  Linux/Windows Detailed also carries a **`present:`** line naming how frames are reaching
+  your screen: the display mode in use (`mailbox`, `fifo`, `fifo-latest-ready`, …), `vrr yes`/`vrr no` once the
+  client has *measured* whether your screen is following the stream's cadence (it is
+  reported only when measured — no guess from what the display claims), and, when the
+  [presentation setting](/docs/client-settings#video) is *Smoothness*, the word
+  `smoothing`. Counters join it only when they're doing something — `qdrop`/`qdry` mean
+  the smoothing buffer overflowed or ran dry (a jittery link), and `gated`/`forced`
+  belong to the pacing that keeps frames from stacking up behind the display.
+
  (Stage values are per-stage medians, so they sum only *approximately* to the
  headline median — percentiles aren't perfectly additive. The headline is measured
  directly, never computed as a sum.)
@@ -360,7 +360,10 @@ Read the host's log around the failed connect or capture.

 1. Open the web console's **Logs** page. It always holds the host's recent output at *debug* detail,
   whatever the log level is set to — there's nothing to switch on and no restart needed.
-2. Filter it down to the level or the text you're after.
+2. Filter it down to the level or the text you're after. The **Host / Plugins** switch beside the
+   level buttons picks the producer: your [plugins](/docs/plugins) log to the same page, tagged
+   `plugin:<name>`, so a misbehaving plugin is one click away rather than a separate hunt through
+   the journal.
 3. Use **Download logs** to save exactly what you're filtering on as a timestamped `.log` file you
   can attach to a bug report. The button beside it hands the same text to your phone or tablet's
   share sheet, or copies it to the clipboard on a desktop.
@@ -107,8 +107,9 @@ Nine destinations in the sidebar (a **More** tab on a phone holds the last five)
  title with its own art and launch command. See [Your game library](/docs/game-library).
 - **Performance** — arm a capture, run a session, stop it, and read the recording back as
  per-stage latency, throughput and health graphs.
- **Logs** — the host's recent log stream: follow it live, filter by level, search it, and download
-  or share it for a bug report.
+- **Logs** — the host's recent log stream *and your plugins'*: follow it live, filter by level or
+  producer, search it, and download or share it for a bug report. Plugin lines are tagged
+  `plugin:<name>` and the **Host / Plugins** switch isolates either side.
 - **Pairing** — arm a PIN, approve or deny devices waiting for approval, and unpair a device. A
  second PIN box for [Moonlight/GameStream](/docs/moonlight) clients appears only when this host
  runs the GameStream plane.
@@ -0,0 +1,111 @@
+Wire-compatible with 0.23.x — everything you have already paired keeps working, and you can update one side at a time. Nothing here changes how a host and a client agree on what to send each other, so an old client on a new host (or the other way round) streams exactly as it does today.
+
+This release is mostly about making 0.23.0 right. **If you stream to an Android phone or to the Linux or Windows desktop app, update the client** — 0.23.0's new send-a-frame-in-pieces delivery had a fault that could throw most of the video away on a busy link, and the fix lives in the client. The other big one is **Automatic bitrate**, which could decide early in a session that your connection was worth 20 Mb/s and then hold you there for the rest of it: a sweep of that path fixed eleven separate faults, and a session that used to need seventeen minutes to climb out now does it in about sixteen seconds. Alongside those: the Linux and Windows app finally gets the frame scheduler the phone and Apple apps have had, the Steam Deck plugin reaches every setting instead of nine of them, controllers can be told *not* to be forwarded for couches that pass the pad through some other way, and plugin output shows up in the web console's log page instead of nowhere at all.
+
+## New
+
+- **The Linux and Windows app schedules frames onto your screen instead of throwing them at it.** Until now the desktop app showed each frame the instant it finished decoding, so every frame carried whatever jitter the network and the decoder had just added — the same problem the phone and Apple apps had before their rebuilds. It now has the same two-way choice under **Prioritize**: **Lowest latency** (the default, and what you have today) or **Smoothness**, which holds a small buffer of frames and releases one per screen refresh so an uneven stream plays evenly. The buffer is 1–3 frames, your pick. On screens where the graphics driver holds a queue of pending frames — which is most Windows machines with an AMD card, and any machine under a compositor that does the same — the app now also stops that queue from building up, which is where a whole extra refresh of delay used to come from.
+
+- **V-Sync and "Follow variable refresh rate" are real settings now.** Both rows have existed for a while and neither did anything: the app picked one presentation mode at startup and kept it. **V-Sync** off asks for the tear-capable mode and says in the stats overlay which mode it actually got, because a graphics driver is free to refuse. **Follow variable refresh rate** lets a VRR/FreeSync/G-SYNC display follow the stream's own cadence rather than a fixed grid; where your driver supports the newest tear-free presentation mode it turns itself on, and elsewhere it stays off unless you ask for it, because on those drivers it costs more than it wins. Whether you actually *have* variable refresh is now measured from what your display does rather than believed from what it claims — no platform reports it honestly enough to trust.
+
+- **The Steam Deck plugin covers every setting, in a sidebar that fits on screen.** Nine of the client's settings had a row here and about twenty did not, so a Deck that never sees a desktop could not reach its own decoder, full chroma, HDR, audio layout, echo cancellation, touch or mouse model, scroll direction, auto-wake, or either audio device. All of it is here now, split across a left rail of categories — the layout SteamOS's own Settings uses — so every page fits without scrolling and nothing is more than one hop away. The categories, their order and the wording match the console's settings screen, because two different orders for one set of settings is how people stop trusting either. Two things are deliberately absent and named as such: which physical controller is player 1, and the remembered window size.
+
+- **The stats overlay has an off switch on the Steam Deck.** Reported from the field: there was no way to turn it off from the plugin, and it defaults to on — so a Deck configured only through this panel streamed with the overlay up and no way here to put it down. The keyboard shortcut and the three-finger tap both existed but neither is discoverable from a couch. The row now sits at the foot of the section, worded the way the console words it.
+
+- **"Forward controllers" — an off switch for setups that hand the pad over another way.** If your controller already reaches the host by USB passthrough (VirtualHere and friends), or is simply plugged into the host, it arrived there twice: once as the real device and once as the virtual pad the client built from the same hands. Games read both, so a stick drifts against the second, centred pad and menus take every input twice. The new per-client setting defaults to on — today's behaviour — and can be set per profile. On Linux and Windows it does more than stop sending: opening a controller is what *claims* it, so with this off the app never opens one at all, leaving the device free for the passthrough tool to bind. The consequence is stated at the setting: the controller escape chord is read off forwarded pads, so it is unavailable while this is off. The Apple and Android apps never claim the pad, so they keep their chords and only stop sending — losing an Apple TV's only way out of a stream would have been the worse bug.
+
+- **Plugin output reaches the web console's log page.** Plugins do not run as children of the host, so nothing they printed ever passed through the host's own logging and the Logs page could not show a single plugin line. The fallback was a terminal on the host box — and on Windows, no log file at all, so a failing plugin was diagnosable only by stopping its task and re-running it by hand. That is exactly what the console exists to avoid, and it left the one question a stuck user asks with no answer. The plugin runner now sends its output to the host, where it joins everything else under one timeline; the Logs page grows a **Host / Plugins** switch beside the level filter, and an empty Plugins view says the thing that is usually actually wrong (the runner isn't running) rather than telling you to adjust the filter.
+
+- **The Windows app can show you where its log lives.** "Check the client log" never said where that was. **Settings ▸ About** grows an **Open log folder** row, and the message you get when a stream fails to start now names the path. It opens the folder rather than the file, so the previous session's rotated log is in reach too.
+
+## Improved
+
+- **The stats overlay's display figure splits into two numbers.** It used to be one number covering everything between "decoded" and "on your screen", which is two very different things stacked: the app's own work, and the wait for the screen to accept the frame. They are now separate, so a high figure diagnoses itself — if the second number dominates it is the refresh rate floor or a queue in the driver, and if the first dominates it is us. The Detailed tier also names the presentation mode actually in use, which answers most "why is my display number a whole refresh" questions on its own.
+
+- **The full-chroma explanation names what it actually needs.** The Windows app's caption said 4:4:4 was "HEVC only, and only where the host can encode it", which sends people hunting through host settings; the web console's explainer was similarly vague. Both now name the real requirement. Host-side, the log line that reports the decision stopped being named after the capture side when it was never about capture — a field report burned real time hunting a capture problem because of it — and a session that asked for full chroma and did not get it now says which end declined.
+
+## Fixed
+
+- **0.23.0 could freeze the picture on Android and on the Linux and Windows app.** 0.23.0 started cutting each frame into pieces and sending them as they were produced. The receiving side then sized every arriving frame at the largest a frame is ever allowed to be — many megabytes — so its budget for frames-in-progress ran out after about three. With normal traffic that meant twelve frames arriving and nine of them thrown away before a single byte could be placed: on any link that reorders packets at all, a loss storm that does not end. Frames never complete, the picture freezes, and the client keeps begging for a fresh one. A second fault in the same path killed one frame in roughly every 1408 outright — about once every twelve seconds at 120 fps, each costing a freeze and a recovery. Only Android and the Linux/Windows desktop app ever took this path, which is why it read as a platform-specific video fault in the field; the Apple apps and the Windows in-process client were never affected. **Updating the client is what fixes it** — a 0.23.0 client still has the bug whatever host it talks to.
+
+- **Automatic bitrate could pin a session at 20 Mb/s for the rest of its life.** Sessions start at 20 Mb/s and climb, and a host refuses a climb while it is briefly behind on encoding. But an ordinary hitch at startup — which arrives while the rate is still at that 20 Mb/s floor — was enough to make the host refuse, and the client cannot tell a momentary refusal apart from an encoder that genuinely cannot go faster: both arrive looking identical. Two of them and the client concluded there was a permanent ceiling. Escaping cost 12.5% per minute, so crossing the gap to what a fast link could actually carry took upwards of twenty minutes, and in practice often never happened — which is why "my bitrate is stuck at 20" has been such a persistent report. Three things changed: the host no longer refuses climbs merely because it is running in its own high-effort mode (that mode exists so it *can* keep up — refusing climbs once it is working refuses the thing that worked), the client re-checks after 12 seconds instead of a minute and backs that off only if the limit proves real, and a request granted in full is taken as proof the limit is gone rather than nudging the guess upward. Measured end to end: a session pinned at 20 Mb/s under a 300 Mb/s connection now reaches 150 Mb/s in about sixteen seconds, where the same case previously needed around seventeen minutes.
+
+- **Automatic bitrate drew permanent conclusions from single moments.** Five more faults of the same shape. The reference points it compares against — network delay, decode time, encode time — could arm off *one* window, and since each is a rolling minimum that one window became the floor; a calm window followed by ordinary motion then read as congestion on a link that was never the problem. Changing resolution or refresh rate re-based only some of what it had learned, so switching *up* a mode was scored against the old mode's easier numbers and cratered the rate instead of raising it. The high-water mark that bounds how far every later climb may step never decayed and was raised by damaged windows — a stall's backlog arriving at once, or a flush's queue — which are exactly the windows that overstate what was delivered. The decoder ceiling latched *at* the rate that had just choked, authorising a climb straight back into the failure, and a network hiccup could be mistaken for a decoder one. And a manual bitrate cap bound only ceilings the speed test had learned, so it did nothing at all if the session already started above it.
+
+- **Your connection was measured including the redundancy sent to protect it.** Two checks compare what actually arrived against what the encoder was asked to produce, and both counted every byte accepted — packet headers, audio, and the extra error-correction data the host adds *in answer to* packet loss. So the measurement rose with the loss it was supposed to detect: at 25% redundancy the check passed while the encoder was emitting barely half its target, and the permanent high-water mark inherited that inflation for good. The signal was weakest on exactly the lossy links it exists for. Only the actual video payload is counted now.
+
+- **A host that re-chose the rate never told the client.** When a host rebuilds its pipeline it can legitimately re-pick an Automatic rate — a 1080p session mirroring a 4K panel needs roughly three times what it negotiated — but that number never reached the client, which kept its own stale copy as the basis for every later step. So a client believing 20 Mb/s while the host encoded 60 would compute its first climb from the stale figure and ask for 40: a request to go *down*, paying for an encoder rebuild to get there. The host now tells the client whenever the applied rate moves, using a message that already meant exactly that and which existing clients already handle arriving unprompted — no wire change, and older clients are unaffected.
+
+- **On KDE hosts, a hidden mouse pointer stayed on screen.** Since 0.22.0 a KDE stream always had a cursor and it never went away again — not in a game, not in Big Picture, not with a controller in hand. The host was blending an arrow onto the picture forever because the signal KDE sends to say "the pointer is not here" was being ignored. It is honoured now, so a game that hides the pointer mid-stream actually hides it. GNOME hosts keep the behaviour they have, because there the same signal means something different and honouring it made the cursor flicker.
+
+- **A KDE host could stream a copy of your monitor instead of its own screen.** KDE remembers display arrangements per set of connected screens, and one of the things it remembers is "this screen mirrors that one". Because the streamed screen carries a stable name, any arrangement that had ever recorded it as a mirror got that re-applied on every later session that reproduced the same set of monitors — which is why it looked so arbitrary: the stream cloned the panel whenever exactly one monitor was live, and behaved normally the moment the others came back. A mirroring screen is not its own desktop; it takes the physical screen's size and viewport instead of the one you negotiated. The streamed screen now says outright that it mirrors nothing, and if it ever finds itself mirroring anyway it says so in the log instead of leaving that as something only you can see.
+
+- **Waking a Windows PC no longer fails the first connection.** A host that had just woken refused connections with a message claiming its virtual-display driver was not installed, on machines where it plainly was. Resuming re-registers that driver while the rest of the wake is still going, and a client reconnecting a second later landed inside the gap. The host checked exactly once, read the gap as a dead driver, and answered a device that was seconds from ready by resetting it — a reset that was then refused, because the host itself was holding the driver open, and reported as a success anyway. It now waits out a driver that is mid-wake instead of resetting it, reports what a reset actually did rather than what the device looks like afterwards, only ever runs one reset when several sessions arrive at once, and says in the log how long it waited and what it saw.
+
+- **AV1 streams quietly decoded in software.** Every AV1 session opened a software decoder no matter what your graphics card could do, because of how the decoder was being looked up by name. Each frame then failed the hardware check and the session walked down its fallback ladder mid-stream — around three seconds of black, with "hardware decode active" already printed and every hardware check green. Decoders are now chosen by what they can actually do. H.264 and HEVC pick exactly what they always did, and every decode log now names the decoder in use, which was the whole diagnosis and no line said it. Separately, a software-decoded HDR stream used to be shown washed out with no warning and an overlay badge claiming a tone-map that never ran; it now warns, and the badge distinguishes the two.
+
+- **A 120 fps session sent 132 frames a second.** The option that runs the virtual display at a multiple of the session's rate promises extra display refreshes without extra frames on the wire, but it only enforced a floor between frames — so content that always had a frame ready settled about ten percent above the rate you negotiated. That is ten percent more bitrate, encode and decode for frames a 120 Hz screen can only drop. The pacing now holds the long-run average at the negotiated rate while keeping the same room for jitter, and a source running at or below the rate is never delayed.
+
+- **On an iPad, Escape handed the mouse back to iPadOS.** iPadOS releases the pointer by itself when you press Escape — its built-in "let me out". But Escape in a stream is a game key, not a request to give the mouse back, so pressing it for an in-game menu silently cost you the capture until you clicked into the video again. An unwanted release is now re-requested, briefly and a bounded number of times. Every deliberate way out (the menu, the two keyboard chords, switching apps) is untouched, and while the re-grab is in flight the local cursor stays hidden and pointer movement is held, so it reads as "Escape did nothing to my mouse" rather than a cursor blinking in and out.
+
+- **The Windows app showed settings something else had already changed.** A field report said a codec setting "changed by itself" between sessions. Nothing writes it back — what they saw was a stale copy. The app read the settings file once at startup, but it is not the file's only writer (the stream itself stores its window size, and the console and the Deck plugin save too), so the page showed values another part of Punktfunk had already replaced — until you touched any row, at which point the value visibly jumped. It re-reads the file on entry now, and on the profile path too. A related one: an older build's save used to *drop* settings a newer client had written, and now carries them through untouched.
+
+- **A Windows host could fight your sound settings.** When no usable playback device was left — a display isolated, the speakers excluded, the microphone holding a virtual device — the host re-ran its whole audio setup every two seconds for as long as it took anyone to notice, including writing your default recording device back each time. That silently undid any recording-device change you made while a stream was up. An impossible arrangement is now recognised as impossible: the host says so once, with the devices it found and why each was rejected, then waits for a device to actually appear or disappear instead of retrying a verdict that cannot change. The default recording device is only asserted when the plan changed or something else moved it.
+
+- **PlayStation Accessories stopped offering a controller update that could never finish.** The emulated DualSense reported a 2021-era firmware version, so Sony's app — and games using their controller library — offered an update that can only ever end in "can't complete the update", since the virtual pad speaks no update protocol. A real pad plugged in directly reads as up to date, which made the prompt look like Punktfunk having corrupted the controller. It now reports a version above anything Sony has shipped, rather than chasing their latest and resurrecting the prompt with every Sony release.
+
+- **Rumble stopped for good after unplugging and plugging a controller back in.** Reconnect a pad mid-session — or have Bluetooth drop it for a moment — and roughly half the time it never rumbled again for the rest of that session. Everything else about the controller kept working, which is what made it look random rather than broken. The host restarts a counter when a controller goes away, and the client uses that counter to throw away force-feedback that arrives out of order; because the client does *not* restart its side, everything sent after the reconnect looked older than what it had already seen, and it dropped the lot until the host counted back past where it left off. How long that took depended on how much the pad had rumbled before you unplugged it, so a quiet session healed at once and a busy one stayed silent. The counter now survives a reconnect, which is what the same code already does for the controller's buttons and sticks.
+
+- **An unplugged controller stayed plugged in as far as the game was concerned.** Unplug a pad mid-session and the game kept seeing a connected controller that never pressed anything again — it simply never went away. If it was your only controller, this happened every time. Tearing the virtual pad down takes a brief settling delay first, so a momentary glitch cannot make a device disappear and reappear, but the second look that finishes the job only ever happened when *another* controller sent something afterwards. With one controller there is nothing left to send it. The teardown now completes on the host's own clock, about a third of a second after the pad goes, whether or not anything else is connected — and a glitch that comes back within the delay still leaves the device alone.
+
+- **The speed test overstated your connection, and Automatic bitrate believed it.** Throughput was worked out by dividing what the client received by how long the *host* spent sending — a window wrong on both ends, since the host's clock stops the moment its send window closes, while the data is still draining through the network toward you. On a gigabit link a test aiming at 2 Gb/s "measured" 1266 Mb/s and set an 886 Mb/s ceiling the link could never carry, permanently, for the whole session. It is now measured over the interval the client actually received across, and video around the test contaminates neither half of the sum. Two guards ride along: a manual bitrate cap now binds no matter what any test concludes, and a decoder that keeps drowning below the link's ceiling has that noticed and remembered, instead of a 30–60 second cycle of climbing back into the same wall and flushing — a 1440p120 case cost a dropped-frame burst every cycle.
+
+- **Plugins on Linux could not reach anything else on the machine.** Reported by a user who could not get the VirtualHere plugin to talk to their VirtualHere client, and the reason was ours: the plugin runner was given its own private temporary directory. But integrating with things already running on the box is the entire job of a plugin, and on Linux those talk through that directory. So a plugin would launch a vendor program happily and then never be able to reach the service behind it — while the identical command worked perfectly in the operator's own terminal. No setting could fix it. Plugins now see the real one.
+
+- **Android: a decoder hiccup turned into a burst of broken frames.** When the decoder handed back an input slot it could not actually fill, both the slot and the video in it were dropped on the floor — leaking one of the decoder's input buffers each time, until the pipeline ran out of them entirely and the resulting keyframe storm read as a decode fault rather than the bookkeeping mistake it was. The dropped video also left a hole nothing asked to repair, so the damage was free to reach the screen. Both go back now.
+
+- **Android: the app could pin the wrong refresh rate for a whole session.** Asking a phone for 120 Hz is a request the system may refuse — Smooth Display off, battery saver, thermal limits, an OEM's own governor. The app took the answer on faith and could only ever revise it downward, so a refused request left it aiming at screen refreshes that never arrive, for the rest of the session, with no way back. It now corrects in both directions: instantly toward a faster screen, and toward a slower one after eight consecutive agreeing observations, because one slow sample is a missed callback and eight in a row is a display that really did slow down. Two related fixes: the app now holds back when the system stops confirming that frames reached the screen, instead of feeding a queue that has stopped draining until the decoder stalls; and the timing margin it adapts now widens on frames that actually missed the screen rather than on ordinary pacing, which on a healthy phone had been walking it to its ceiling and re-imposing the delay the 0.23.0 work had just measured away.
+
+- **Windows stutter reports blamed the wrong thing.** The host tries to tell you whether frames stopped arriving because the *game* went quiet — a menu, a loading screen, an ordinary hitch — or because the display path did. Its witness for the display path never worked: it was reading timestamps in one unit and comparing them against another, so it saw zero display activity always, and every quiet stretch was reported as the game going quiet. The category the whole thing exists to catch was unreachable. It reads correctly now, and it can tell "the witness was working and saw nothing" from "the witness was not working", which are opposite conclusions. If you have a stall report from an earlier version, its verdict is not evidence.
+
+## Under the hood (for developers)
+
+- **Versions.** All unchanged from 0.23.0: wire protocol 2, C ABI 14, virtual-display driver protocol 6, Windows virtual-gamepad channel 3. No new negotiated capability bits — `VIDEO_CAP_MULTI_SLICE` (`0x80`) was already the video-caps byte's last free bit and nothing needed the next one. The only C-header change is documentation: `PunktfunkProbeResult::elapsed_ms` now means the client-measured receive interval (see the ABR entry), and the probe clamp comment corrects 3 Gbps → 10 Gbps to match `MAX_PROBE_KBPS`.
+
+- **Slice-streamed reassembly.** Every ordinary access unit on the streamed path is now opened by a sentinel header (the block flush at `MIN_STREAM_BLOCK_SHARDS` guarantees it), and the reassembler was sizing those at `max_frame_bytes` — 8–64 MiB after the QUIC handshake clamp. Each AU therefore allocated and zeroed a multi-megabyte buffer, and `IN_FLIGHT_BUF_FACTOR × max_frame_bytes` was exhausted after ~3 concurrent frames. A sentinel now sizes to its own block extent (a slice sentinel by its wire base, a legacy one by its full-K position) and grows as later blocks or the final block's totals reveal more, with the in-flight budget re-checked on growth. Separately, `flush_block` drained `pending` to empty when the AU length was an exact multiple of the shard payload, leaving `finish_streamed` to seal a final block of one zero-padded filler shard whose derived base overlapped the block flushed a moment earlier — correctly read as a lying header, killing the AU. A flush now retains one whole shard, restoring the invariant `StreamedAu::pending` already documented.
+
+- **Desktop presentation engine.** `pf-presenter` gains `present_pace.rs` (pure state + arithmetic): `FrameStore` (newest-wins slot or smoothing FIFO with preroll-to-capacity, drop-oldest overflow and underflow re-arming the preroll — the Apple/Android semantics, with `qDrop`/`qDry`), `LatchClock` (panel grid from `VK_KHR_present_wait` glass stamps, publishing the host-facing `LatchGrid`), and `PresentGate` (one undisplayed present in flight on FIFO surfaces, 100 ms stale force-open; inert on MAILBOX/IMMEDIATE and without present timing). Settings ride the keys the Apple client already writes into the shared profile catalog — `present_priority` / `smooth_buffer` / `vsync` / `allow_vrr`, now tier-P routed — and `PresentPriority::resolve` mirrors the Android reference exactly, so a profile authored on any client means the same thing everywhere. PyroWave collapses smoothness to latency (its plane-ring retirement assumes the depth-2 newest-wins hand-off, and all-intra frames make buffering moot).
+
+- **Present-mode ladder and `VK_PRESENT_MODE_FIFO_LATEST_READY_EXT`.** Mode selection is a preference ladder rather than a constant: V-Sync off → IMMEDIATE, FIFO_RELAXED, then tear-free; V-Sync on + VRR + fullscreen → LATEST_READY first; otherwise MAILBOX then FIFO. The extension postdates ash 0.38's headers (Vulkan 1.3.281), so the mode value, extension name and `VkPhysicalDevicePresentModeFifoLatestReadyFeaturesEXT` are hand-declared. **Trap:** the surface advertises the mode even with the extension disabled, and using it on that basis is undefined — the ladder only offers it where the device feature came back true and was enabled. The gate predicate splits in two on purpose: `needs_glass_gate()` is FIFO and FIFO_RELAXED only (gating on a driver that already retires stale images pays the serialisation twice — the ~27 ms an A/B measured), while `vblank_locked()` is the whole FIFO family including LATEST_READY, since the VRR cadence probe's premise still holds there. Measured on .21 (NVIDIA 610.43.03, GNOME/Wayland): `display 2.6 ms (pace 0.6 + latch 2.0)` on the VRR ladder against 13–28 ms for FIFO + gate, and 1.4 ms for MAILBOX. ⚠ Unverified off that box: whether Windows (Vulkan WSI through DXGI) or Intel drivers expose the mode at all — `surface present modes` and `fifo_latest_ready=` are logged unconditionally, so one run on any box settles it. `allow_vrr` is automatic only where the device offers the mode, and stays behind `PUNKTFUNK_VRR_FIFO=1` elsewhere.
+
+- **VRR detection is measured, never queried.** No portable query exists (SDL exposes none, Wayland does not report adaptive-sync state, Windows surfaces nothing through Vulkan) and the platforms that do answer have been caught lying. The discriminator is quantization: `CadenceProbe` folds each present delta to its distance from the nearest multiple of the *display mode's* period — not the learned one, which is circular when the stream runs below panel rate — and takes the median. Tri-state: Unknown below 24 deltas, after a display change, and outside a FIFO-family mode (MAILBOX decouples presents from scanout, so its stamps are never grid-quantized; the same panel read `no` on FIFO and `yes` on MAILBOX in one minute).
+
+- **`PanelGrid`, shared.** The panel-period learner is extracted to `punktfunk_core::phase::PanelGrid` and adopted by the Android, iOS and desktop presenters, replacing three copies with the same bug: a seed capped at the display mode's refresh, when the mode is only a *claim*. Narrowing is immediate; widening needs eight consecutive agreeing observations and then takes the narrowest of them. `preferredDisplayModeId` on Android is a request the system may refuse, which is the case that made this a session-length failure.
+
+- **ABR probe measurement.** The reassembler stamps probe-scoped counters (bytes, packets, first/last arrival, monotonic ns) at `FLAG_PROBE` routing, so the throughput divisor is the client's first→last arrival interval and video around the burst contaminates neither numerator nor denominator; the host duration remains the fallback below two probe packets. `ProbeOutcome`/`PunktfunkProbeResult` layouts are unchanged. The controller latches `decode_cap_kbps` when two *consecutive* backoffs carry decode-severe evidence at a similar pre-backoff rate (mirroring `host_cap_kbps`), re-probing on the `CAP_REPROBE_WINDOWS` clock; one spurious flush never latches.
+
+- **ABR sweep — eleven defects.** Wire format and ABI untouched throughout; 34 abr tests plus 2 host tests. Host side: `cadence_degraded` was latched true for as long as the session was *escalated* (adaptive capture depth or pipelined retrieve), independent of whether encode was still missing deadlines — and escalation needs only ~20 net behind-frames, which a startup hitch supplies while ABR is still in slow start at the 20 Mbps default. The rule moves into `encode_behind_cadence`: an escalated session is still judged strictly (any net behind-frame keeps it flagged, where an unescalated one gets the full bucket), but escalation alone no longer flags it. `adopt_built_bitrate` now publishes the rate a rebuilt pipeline actually opened at (`build_pipeline` re-resolves an Automatic rate whenever the source delivers an unnegotiated size — the mirrored-panel case — and the encoder's clamp can land below what control already acked), pushed to the control task as the existing 9-byte `BitrateChanged`. Client side: all three rolling baselines (OWD, decode, encode) now require `BASELINE_MIN_WINDOWS` of evidence via one shared `score_baseline` — the three copies had drifted apart, and `on_ack` clears the encode baseline after every self-requested decrease, re-opening the one-sample hole each time. A mode switch rebases decode and OWD as well as encode, and drops `proven_kbps` with them. `proven_kbps` is raised only by *clean* windows (it never decays and holds permanent authority over climb step size, and the windows that overstate delivered throughput are precisely the damaged ones). `decode_cap_kbps` latches just *under* the choke rate, inside the ±1/8 band the evidence already required, and credits a bare jump-to-live flush only where the decode signal is absent. The two throughput-driven gates are fed data-shard payload counted at the reassembler's routing decision rather than `bytes_received` (which includes headers, FEC parity, probe filler and audio — at 25% FEC the utilization gate passed with the encoder emitting ~55% of target). `PUNKTFUNK_ABR_MAX_MBPS` binds at construction, not only on probe-learned ceilings, and a session starting above its cap steps down to it (no congestion signal will ever find that — the link is fine, the cap is policy). Cap escape re-probes after 12 s, doubling each time the lift is immediately re-learned, and a request granted **in full** at or above the cap drops the cap outright rather than nudging it +12.5%. An ack above the current ceiling raises the ceiling to meet it (`set_ceiling` still only ever raises, still clamps to `PUNKTFUNK_ABR_MAX_MBPS`), so a host-initiated re-target is not immediately stepped back down. Finally, a `SetBitrate` dropped by a full control queue no longer counts toward `MAX_UNACKED` — three of those retired the controller for the session while blaming an "older host".
+
+- **Frame pacing under `PUNKTFUNK_VDISPLAY_HZ_MULT`.** The frame-driven trigger enforced its pace as a per-gap floor only (sleep to 0.9×interval, wake on arrival), so an always-ready source settled at 1.11× the negotiated rate. `PaceBudget` accrues one frame of credit per interval of *real elapsed* time, caps at 1.25 frames of post-stall burst, and charges one per submitted frame — the 0.9 floor keeps its jitter headroom while the long-run average cannot exceed the rate. Anchoring to real elapsed time preserves the synchronous-encode overlap the arrival-anchored floor bought and cannot fight the phase lock's submit grid. The charge sits under the same guard as the gate: the legacy fixed tick paces by its own grid, and charging without accruing would bank unbounded debt.
+
+- **Force-feedback lifecycle.** `native/input.rs` no longer resets `rumble_seq[idx]` on `GamepadRemove`: the client's v2 reorder gate is per-connection with no reset path, so restarting the sender's counter stranded every later envelope behind `seq_newer` until it climbed past the stored value (up to 128 sends). The lease clears that actually end a rumble move into `clear_pad_feedback`, whose signature omits the seq so the arm cannot regress. `PadSlots` splits `sweep` (arm the grace from a state frame) from a new `reap` (complete the unplug, no frame required), and all three backends reap from the periodic pump they already run; `reap` never arms a clock, so it cannot invent an unplug however often it runs. Regression tests drive the unplug through a pump tick rather than the hand-fed second frame the old tests used — that second frame is not something the producer ever sends, and its absence is what hid both defects.
+
+- **ETW present witness.** The consumer was opened without `PROCESS_TRACE_MODE_RAW_TIMESTAMP`, so `ProcessTrace` converted every event's `TimeStamp` to FILETIME regardless of `ClientContext=1` — FILETIME ticks are ~4 orders of magnitude above QPC, so every comparison was false, `etw=none` always printed, and `classify()` convicted every compose-silence hole as CONTENT-SILENCE, making FRAME-GENERATION unreachable. Two comments asserted the wrong contract and now state the real one. `summary()` and `window_counts()` merge into one `window_report()` (one ring lock, one anchor — they could previously disagree about the same hole); `present_history`/`queue_history` now mean witness *liveness* within a 5 s lookback ending at the hole's start rather than "an event ever sat in the ring", and the static ring is cleared per session. Conviction thresholds untouched. **Any stall verdict from before this fix is void.**
+
+- **Hardware decoder selection.** `avcodec_find_decoder(id)` returns the registry's first decoder for the id and upstream orders the native AV1 decoder *last* on purpose ("hwaccel hooks only, so prefer external decoders"), so all three hardware backends were opening libdav1d — which ignores `hw_device_ctx` and never calls `get_format`. `find_hw_decoder` walks `av_codec_iterate` and takes the first decoder whose `avcodec_get_hw_config` advertises the backend's surface via `HW_DEVICE_CTX`, so a build without a usable hardware decoder fails at open in milliseconds and the ladder runs there. Registry order still wins among capable decoders; the software path keeps the id lookup deliberately (libdav1d is the fastest CPU AV1, and the native decoder has no software path).
+
+- **KWin mirroring.** `OutputConfigurationStore` persists `replicationSource` per *setup* (the exact connected-output set, matched by EDID/connector), and our virtual output carries a stable name by design — so a stored mirror entry re-applies on every session reproducing that monitor set. `applyMirroring` overrides scale and render offset to the source's, and the protocol states that a mirroring output may not be in the output order, so the primary assertion silently stops meaning anything too. The topology config now includes `set_replication_source(ours, "")`, gated on output-management v13 where the request appeared (wayland-rs does not range-check requests; an out-of-range opcode kills the connection). `extend`/`auto` issue no topology calls by design, so they get `clear_replication_source`, which enumerates and applies only when our output really is mirroring. The device's `replication_source` event is now read and warned on.
+
+- **KWin cursor visibility.** Two producer contracts meet on `SPA_META_Cursor` id 0. KWin rewrites cursor meta on every enqueued buffer and writes id 0 whenever `Cursor::isOnOutput` says the pointer is not in this stream — covering both a globally hidden cursor and a client null-cursor surface — so there id 0 *is* the hide. Mutter only rewrites meta when the cursor changed, so recycled buffers carry stale id-0 regions between damage frames, and honouring those flickered the cursor off between hovers. A flag rides from the backend that created the output through `capture_virtual_output` into the parser's `CursorState`; the portal-monitor path stays on the stale-meta contract (only Mutter's HDR mirror routes through it today).
+
+- **Plugin runner and logging.** `punktfunk-scripting.service` drops `PrivateTmp=yes` and adds `/tmp` to `ReadWritePaths` (which `ProtectSystem=strict` would otherwise make read-only) — VirtualHere's client IPC is the `/tmp/vhclient` + `/tmp/vhclient_response` FIFO pair, and X11 is `/tmp/.X11-unix`. The runner tees stdout to `POST /api/v1/plugins/logs`, joining the host's ring under one cursor with target `plugin:<name>`; stdout stays authoritative, the queue is bounded and drops oldest (then reports how many), the shipper backs off when the host is away and re-sends a batch the host refused. `plugin_may_access` is an exclusion list, so `/plugins/logs` is reachable today only because it does not match `/ui-credential` — now asserted directly, since a change there would silence plugin logs with no other symptom. Two shipper bugs fixed with tests that fail against the previous code: the recursion guard was held across the whole `await fetch` and `enqueue` checked it (so every line logged while a POST was open was dropped — worst exactly when the host is slow), and an explicit `flush()` hit the same guard and returned having sent nothing, which is the shutdown path where the last lines say whether shutdown was clean.
+
+- **Gamepad claiming and the new setting.** `forward_gamepads` is tier-P (profile-routable), default on. On Linux and Windows it prevents the session opening any pad slot and enables no Valve HIDAPI drivers, because opening a controller is what claims the device node and a claimed device cannot be bound by a passthrough tool. Menu navigation is unaffected (the launcher still opens the active pad, and a session supersedes menu mode either way). Apple and Android claim nothing, so they gate only the wire sends; Android does stop its DualSense and Steam Controller 2 USB captures, which do claim.
+
+- **Virtual DualSense firmware version.** The feature report `0x20` update version moves `0x0154` → `0x0999`, above anything Sony has shipped, in both blobs (host uhid and the Windows driver; the DualSense Edge shares them). The old value existed to keep the kernel and SDL on the flag0 `COMPATIBLE_VIBRATION` convention, but `parse_ds_output` has since learned `COMPATIBLE_VIBRATION2` (firmware ≥ 2.24), so writers that read the version now use the v2 flag; both conventions land in the same rumble plane.
+
+- **Windows client settings store.** `Settings` gains unknown-key passthrough, matching the contract `SettingsOverlay::extra` already gave profiles — additive, empty on every existing store, and an empty map serialises to nothing so no file churns. The page re-bases on the file at entry, and the profile-scope commit arm reloads before cloning (it was diffing overlay absorption against stale globals). `save()` was already temp+rename.
+
+- **Environment.** `PUNKTFUNK_PRESENT_MODE` gains explicit `mailbox` and `fifo_relaxed` arms (both previously folded into the default with every typo) and falls back to the settings rather than to mailbox on an unknown name. New: `PUNKTFUNK_PRESENTER=arrival` (disables the whole desktop pacing engine for a field A/B without a rebuild), `PUNKTFUNK_PRESENT_DEBUG`, `PUNKTFUNK_VRR_FIFO=1`.
+
+- **Android release channel.** A `vX.Y.Z` tag now publishes to Play **production at 100%**, not alpha — production access came through 2026-08-01. Canary is unchanged on `internal`, and its run-number version codes always outrank production so testers keep the newer build. Play's "What's new" gets its own file, `docs/releases/whatsnew/vX.Y.Z.txt`, capped at 500 *characters* per language (`•` is three bytes in UTF-8, so a byte count can reject a legal file). A tag without that file fails the android job at step 1, before the build: Play does not show an empty "What's new" when the file is missing — it carries the previous release's text onto the new version, which is the same shape as the v0.22.3 notes announcing a feature that tag never contained. The gate also rejects a file byte-identical to another release's. `android-promote.yml` is the lever for promoting a tested build, halting a rollout, or rolling production back onto an older version code, with `dry_run` defaulting to true.
@@ -0,0 +1,6 @@
+• Automatic bitrate no longer gets stuck at 20 Mbps for a whole session. It now climbs to what your connection really carries in seconds, not minutes.
+• Fixes a fault from 0.23.0 that could freeze the picture on a busy connection.
+• Fixes a refresh-rate mix-up that left the picture juddering for a whole session.
+• A decoder hiccup no longer causes a burst of broken frames.
+• Controllers rumble again after a reconnect.
+• New "Forward controllers" switch, for pads that reach the PC another way.
@@ -360,9 +360,32 @@ fn ring_len(view: &pf_umdf_util::section::MappedView) -> u32 {
 /// from being coalesced away by a following LED/trigger report inside one host poll window (the
 /// confirmed stuck-rumble path).
 fn publish_output(view: &pf_umdf_util::section::MappedView, bytes: &[u8]) {
+    // Serialized: the whole publish is a read-modify-write (read the cursor, write the slot it
+    // names, then advance it) and the framework dispatches output callbacks in PARALLEL, so two
+    // can be inside this at once. Unsynchronized, both read the same `ring_head`, both write the
+    // SAME slot — tearing one report's bytes across the other's — and both store head+1, so the
+    // cursor advances once for two reports and the host sees a single torn entry.
+    //
+    // An atomic `fetch_add` on the head does not fix it. That hands each writer a distinct slot,
+    // but it advances the cursor BEFORE the slot bytes exist, so the host can read a slot that is
+    // still being filled — trading a torn slot for a torn slot the host is invited to read. Making
+    // the head-advance mean "the slot below is complete" is exactly what the lock buys.
+    //
+    // Poison-tolerant on purpose. Poison is sticky, so the repo's usual `if let Ok(g) = lock()`
+    // would skip the publish for the REST OF THE PROCESS after a single panic elsewhere — silently
+    // ending game output. Recovering the guard is safe here: the protected state is bytes in a
+    // shared section, not an invariant a panic could have broken.
+    let _publish = RING_PUBLISH
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
    view.write_bytes(OFF_OUTPUT, bytes);
    let seq = view.read_u32(OFF_OUT_SEQ).wrapping_add(1);
-    view.write_u32(OFF_OUT_SEQ, seq);
+    // Release, not a plain write: the host loads `out_seq` with Acquire specifically to order its
+    // copy of the report bytes after it (`dualsense_windows.rs`, "Acquire pairs with the driver's
+    // publish-then-bump store order"). An Acquire load pairs with a Release store and nothing
+    // else, so as a plain write this promised the host an ordering it never actually established —
+    // on a weakly-ordered core (ARM64) the fresh seq could arrive ahead of the bytes it announces.
+    view.store_u32(OFF_OUT_SEQ, seq, Ordering::Release);
    let len = ring_len(view);
    if len != 0 {
        let head = view.read_u32(OFF_RING_HEAD);
@@ -375,6 +398,11 @@ fn publish_output(view: &pf_umdf_util::section::MappedView, bytes: &[u8]) {
    }
 }

+/// Serializes [`publish_output`] against itself — see the note there for why an atomic cursor is
+/// not enough. Uncontended in the common case: one output report at a time is the norm, and the
+/// critical section is a few dozen bytes of memcpy into an already-mapped view.
+static RING_PUBLISH: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
 /// The sealed-channel client (per-pad: `ProcessSharingDisabled` gives each pad its own WUDFHost, so
 /// this static is per-pad). The handshake/adoption/validation state machine lives in `pf_umdf_util`.
 static CHANNEL: ChannelClient = ChannelClient::new();
@@ -358,20 +358,48 @@ fn read_state(data: Option<&MappedView>) -> (u32, u16, u8, u8, i16, i16, i16, i1
 /// host can tell "driver bound and alive" apart from "driver package missing/failed to bind" and see
 /// the game-visible polling path advance.
 fn touch_driver_marks(data: &MappedView) {
+    let _marks = SECTION_PUBLISH
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
    data.write_u32(OFF_DRIVER_PROTO, GAMEPAD_PROTO_VERSION);
    let hb = data.read_u32(OFF_DRIVER_HEARTBEAT).wrapping_add(1);
    data.write_u32(OFF_DRIVER_HEARTBEAT, hb);
 }

 /// Publish a game's rumble (from SET_STATE) into the DATA section for the host to forward.
+///
+/// Serialized and Release-published, because IOCTLs arrive concurrently and neither property held
+/// before. `seq` was a read-modify-write across the two motor bytes: two `SET_STATE` calls could
+/// both read the same value and both write back `seq + 1`, so the host — which treats an unchanged
+/// seq as "nothing new" — saw one bump for two writes and skipped a level entirely. A skipped
+/// **stop** is the one that hurts: the pad keeps buzzing until the host's ~2.5 s idle force-off
+/// notices the game went quiet, which is where the bound on this bug comes from.
+///
+/// The seq store is Release for the same reason as `pf-gamepad`'s `out_seq`: the host loads it with
+/// Acquire and documents that as ordering its read of the motor bytes ("the driver bumps
+/// `rumble_seq` AFTER writing the rumble bytes", `gamepad_windows.rs`). A plain write gives that
+/// Acquire nothing to pair with, so the guarantee the host's comment claims did not exist in either
+/// direction — the host could read a fresh seq against stale motor levels on a weakly-ordered core.
 fn publish_rumble(data: Option<&MappedView>, large: u8, small: u8) {
    let Some(v) = data else { return };
+    let _publish = SECTION_PUBLISH
+        .lock()
+        .unwrap_or_else(std::sync::PoisonError::into_inner);
    v.write_u8(OFF_RUMBLE_LARGE, large);
    v.write_u8(OFF_RUMBLE_SMALL, small);
    let seq = v.read_u32(OFF_RUMBLE_SEQ).wrapping_add(1);
-    v.write_u32(OFF_RUMBLE_SEQ, seq);
+    v.store_u32(OFF_RUMBLE_SEQ, seq, Ordering::Release);
 }

+/// Serializes the section's read-modify-write publishes ([`publish_rumble`], [`touch_driver_marks`])
+/// against each other. One lock rather than one per field: they are all short byte writes into the
+/// same mapped view, and the contention is nil compared to the IOCTL round trip that reaches them.
+///
+/// Poison-tolerant deliberately — poison is sticky, so bailing out on it would silently stop
+/// forwarding rumble for the rest of the process. The protected state is bytes in a shared section,
+/// not an invariant a panic elsewhere could have violated.
+static SECTION_PUBLISH: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
 // Build the 29-byte GET_STATE buffer (the layout xinput1_4 parses).
 fn build_get_state(data: Option<&MappedView>) -> [u8; 29] {
    let (packet, buttons, lt, rt, lx, ly, rx, ry) = read_state(data);
@@ -33,16 +33,24 @@ KillSignal=SIGTERM
 TimeoutStopSec=30
 # Sandbox: free hardening for well-behaved plugins. The filesystem is read-only outside the home
 # directory (ReadWritePaths keeps plugin state, download dirs, and ~/.config/punktfunk writable);
-# /tmp is private; no setuid re-escalation; sockets limited to what automation actually uses
-# (loopback mgmt API, LAN/IPv6 webhooks, unix sockets). A plugin that must write OUTSIDE $HOME
-# (e.g. a library on another mount) gets a drop-in:
+# no setuid re-escalation; sockets limited to what automation actually uses (loopback mgmt API,
+# LAN/IPv6 webhooks, unix sockets). A plugin that must write OUTSIDE $HOME (e.g. a library on
+# another mount) gets a drop-in:
 #   systemctl --user edit punktfunk-scripting   →   [Service]\nReadWritePaths=/mnt/games
-# NOTE: the mount-namespace options (ProtectSystem/PrivateTmp) need unprivileged user namespaces
-# for a *user* unit; on kernels/distros that restrict those, drop them via the same drop-in.
+# NOTE: the mount-namespace options (ProtectSystem) need unprivileged user namespaces for a
+# *user* unit; on kernels/distros that restrict those, drop them via the same drop-in.
+#
+# PrivateTmp is deliberately OFF (field report 2026-08-03, the VirtualHere plugin). A plugin's
+# whole job is integrating with things already running on this box, and on Linux those talk over
+# /tmp: VirtualHere's client IPC is the FIFO pair /tmp/vhclient + /tmp/vhclient_response, and X11
+# is /tmp/.X11-unix. A private /tmp namespace hides all of it — the plugin launches the vendor
+# binary fine and then cannot reach the daemon behind it, which presents as an unexplained error
+# that no amount of config fixes (the operator's own shell works, because that has the real /tmp).
+# ReadWritePaths=/tmp puts the write bit back that ProtectSystem=strict takes away.
 NoNewPrivileges=yes
-PrivateTmp=yes
+PrivateTmp=no
 ProtectSystem=strict
-ReadWritePaths=%h
+ReadWritePaths=%h /tmp
 RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6

 [Install]
@@ -0,0 +1,287 @@
+// The runner's log door into the web console (field report 2026-08-03, the VirtualHere plugin).
+//
+// WHY THIS EXISTS: plugins are not host child processes. The runner is a separate bun process that
+// `import()`s each plugin in-process, so a plugin's output is THIS process's stdout and the host's
+// `tracing` ring — the thing `GET /api/v1/logs` and the console's Logs page serve — never sees a
+// byte of it. On Linux the fallback was `journalctl --user -u punktfunk-scripting`; on Windows the
+// runner scheduled task writes no log file AT ALL, so a failing plugin could only be diagnosed by
+// stopping the task and re-running the runner by hand. Both need shell access on the host box,
+// which is the exact thing the console exists to avoid. A user hitting a plugin misconfiguration
+// therefore had no way to see the error explaining it.
+//
+// So: tee every console line to `POST /api/v1/plugins/logs`, which lands it in the host's ring
+// alongside the host's own lines under the target `plugin:<source>`.
+//
+// Design rules this file will not break:
+// - **stdout stays authoritative.** The original console method is called FIRST and always, so
+//   journald/foreground output is unchanged whatever the host is doing. Shipping is additive.
+// - **Never recurse.** Nothing on the shipping path may log through the patched console; a failed
+//   POST that logged its own failure would enqueue that line, fail again, and spin.
+// - **Never throw into a caller.** `console.log` is not allowed to fail because the host is down.
+// - **Bounded.** The queue has a hard cap and drops its OLDEST lines, then says how many — an
+//   unreachable host must not turn the runner into a memory leak.
+import { format } from "node:util";
+import { type ConnectOptions, resolveConfig } from "./config.js";
+
+/** The level a console method implies when a line carries no level of its own. */
+const LEVEL_BY_METHOD = {
+	log: "INFO",
+	info: "INFO",
+	debug: "DEBUG",
+	warn: "WARN",
+	error: "ERROR",
+} as const;
+type Method = keyof typeof LEVEL_BY_METHOD;
+const METHODS = Object.keys(LEVEL_BY_METHOD) as Method[];
+
+/**
+ * `<ISO> [<source>] [LEVEL:] <message>` — the line format `plugin-kit`'s `loggingLayer` and this
+ * package's `runner.ts` both emit. Parsing it back recovers the plugin name and level that the
+ * formatting flattened, so the console can show `plugin:virtualhere` / `WARN` instead of one
+ * undifferentiated `runner` stream.
+ *
+ * A line that does NOT match is still shipped — attributed to `runner` at the console method's own
+ * level. A plugin calling bare `console.error("boom")` is precisely the case this must not lose.
+ */
+const STAMPED =
+	/^(\d{4}-\d{2}-\d{2}T[\d:.]+Z) \[([^\]\n]{1,64})\](?:[ \t]+([A-Z]{3,9}):)?[ \t]?([\s\S]*)$/;
+
+/** Lines per POST. Must stay ≤ the host's `MAX_LOG_BATCH` or a batch is rejected wholesale. */
+const BATCH = 256;
+/** Queued lines before the oldest start dropping. ~2 MB worst case at the host's 2 KB cap. */
+const QUEUE_LIMIT = 1000;
+/** A multi-line message (a stack trace) ships as one entry per line, capped here. */
+const MAX_LINES_PER_MESSAGE = 40;
+
+export interface LogShipperOptions {
+	/** Connection overrides. Defaults to the same zero-config resolution `connect()` uses. */
+	connect?: ConnectOptions;
+	/** Flush cadence in ms (default 2000). */
+	intervalMs?: number;
+}
+
+export interface LogShipper {
+	/** Send whatever is queued right now. Never rejects. */
+	flush: () => Promise<void>;
+	/** Restore the original console methods and stop the timer. */
+	stop: () => void;
+}
+
+interface Line {
+	ts_ms: number;
+	level: string;
+	source: string;
+	msg: string;
+}
+
+/**
+ * Split a rendered console call into shippable lines.
+ *
+ * Newlines become separate entries rather than one blob: the log viewer is line-oriented, and the
+ * payload that matters most here — an Effect `Cause.pretty` stack from a plugin that failed to
+ * start — is unreadable folded onto a single row. The cap keeps one pathological dump from
+ * evicting the ring on its own.
+ */
+const toLines = (method: Method, args: unknown[]): Line[] => {
+	const text = format(...args);
+	const m = STAMPED.exec(text);
+	const source = m?.[2] ?? "runner";
+	const level = m?.[3] ?? LEVEL_BY_METHOD[method];
+	const parsedTs = m?.[1] !== undefined ? Date.parse(m[1]) : Number.NaN;
+	const ts_ms = Number.isNaN(parsedTs) ? Date.now() : parsedTs;
+	const body = m?.[4] ?? text;
+
+	const parts = body.split(/\r?\n/);
+	const kept = parts.slice(0, MAX_LINES_PER_MESSAGE);
+	if (parts.length > kept.length) {
+		kept.push(`… ${parts.length - kept.length} more line(s) suppressed`);
+	}
+	// A trailing newline yields one empty part; an all-empty message still ships one entry so the
+	// console never silently swallows a call.
+	const meaningful = kept.filter((l) => l.trim() !== "");
+	return (meaningful.length > 0 ? meaningful : [""]).map((msg) => ({
+		ts_ms,
+		level,
+		source,
+		msg,
+	}));
+};
+
+/**
+ * Patch the console to tee into the host's log ring, and start the flush timer.
+ *
+ * Install this ONLY in the managed runner (`runner-cli.ts`). A plugin's own CLI (`punktfunk-plugin-x
+ * doctor`) must keep its output local — an operator running a diagnostic in their terminal is not
+ * asking to write to the host's log.
+ */
+export const installLogShipper = (
+	options: LogShipperOptions = {},
+): LogShipper => {
+	const queue: Line[] = [];
+	let droppedByOverflow = 0;
+	// True from the moment a flush claims a batch until its POST settles. Guards flush RE-ENTRY
+	// only — the interval can fire while a slow POST is still open, and two concurrent flushes
+	// would splice disjoint batches out of one queue and deliver them out of order.
+	//
+	// It deliberately does NOT gate `enqueue`. It used to, as a recursion guard, and that silently
+	// dropped every line logged during the few ms of a POST — which under load is a great many of
+	// them, and exactly the lines a busy plugin is producing. The recursion it was guarding is
+	// handled by the rule at the top of this file instead: nothing on the shipping path logs.
+	let shipping = false;
+	let stopped = false;
+	// Set once the host's URL/token/CA resolve. Before that (the host writes `plugin-token` as it
+	// boots, and the runner may well start first) lines keep queueing — those earliest lines are
+	// exactly the ones that explain a plugin failing to load.
+	let resolved: Awaited<ReturnType<typeof resolveConfig>> | undefined;
+	let resolving = false;
+	// Consecutive failures, for backoff. The host being down is normal (restart, update) and must
+	// not mean a POST attempt every 2 s forever.
+	let failures = 0;
+	let skipTicks = 0;
+
+	// The ORIGINAL function objects, unbound. `stop()` must put back exactly what it found: binding
+	// here and restoring the bound copy would leave a different function in place each cycle, so
+	// an install/stop/install sequence accumulates a wrapper per round. Calls go through `.call`
+	// below to keep `this` right without touching identity.
+	const original = Object.fromEntries(METHODS.map((m) => [m, console[m]])) as Record<
+		Method,
+		(...args: unknown[]) => void
+	>;
+
+	const enqueue = (method: Method, args: unknown[]) => {
+		if (stopped) return;
+		try {
+			for (const line of toLines(method, args)) {
+				if (queue.length >= QUEUE_LIMIT) {
+					queue.shift();
+					droppedByOverflow += 1;
+				}
+				queue.push(line);
+			}
+		} catch {
+			// Formatting a hostile object must never break the caller's console call.
+		}
+	};
+
+	for (const method of METHODS) {
+		console[method] = ((...args: unknown[]) => {
+			original[method].call(console, ...args);
+			enqueue(method, args);
+		}) as typeof console.log;
+	}
+
+	const ensureResolved = async (): Promise<boolean> => {
+		if (resolved) return true;
+		if (resolving) return false;
+		resolving = true;
+		try {
+			resolved = await resolveConfig(options.connect);
+			return true;
+		} catch {
+			// No token yet (or no host at all). Keep buffering and try again next tick.
+			return false;
+		} finally {
+			resolving = false;
+		}
+	};
+
+	/** Put a failed batch back at the FRONT, still honoring the cap (oldest lose). */
+	const requeue = (batch: Line[]) => {
+		queue.unshift(...batch);
+		if (queue.length > QUEUE_LIMIT) {
+			droppedByOverflow += queue.length - QUEUE_LIMIT;
+			queue.splice(0, queue.length - QUEUE_LIMIT);
+		}
+	};
+
+	const flush = async (): Promise<void> => {
+		if (stopped || shipping || queue.length === 0) return;
+		if (!(await ensureResolved()) || !resolved) return;
+		// Re-check after the await: `ensureResolved` yields, so another flush may have claimed the
+		// queue in the meantime.
+		if (stopped || shipping || queue.length === 0) return;
+
+		shipping = true;
+		const batch = queue.splice(0, BATCH);
+		if (droppedByOverflow > 0) {
+			// Tell the operator the tail is incomplete rather than presenting a gap as continuity —
+			// the same contract the host's ring keeps with its `dropped` flag.
+			batch.unshift({
+				ts_ms: Date.now(),
+				level: "WARN",
+				source: "runner",
+				msg: `log shipper dropped ${droppedByOverflow} line(s): the queue filled while the host was unreachable`,
+			});
+			droppedByOverflow = 0;
+		}
+
+		try {
+			const res = await resolved.fetch(`${resolved.url}/api/v1/plugins/logs`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${resolved.token}`,
+				},
+				body: JSON.stringify({ entries: batch }),
+			});
+			if (!res.ok) {
+				// 4xx is our bug (a shape the host rejects) and retrying cannot fix it — drop the
+				// batch. 5xx/transport is the host's problem and worth keeping.
+				if (res.status >= 500) requeue(batch);
+				// A token that went stale (host re-keyed) resolves again from disk on the next tick.
+				if (res.status === 401) resolved = undefined;
+				failures += 1;
+			} else {
+				failures = 0;
+			}
+		} catch {
+			requeue(batch);
+			failures += 1;
+		} finally {
+			shipping = false;
+			// 2 s, 4 s, 8 s … capped at ~30 s while the host stays away.
+			skipTicks = failures === 0 ? 0 : Math.min(2 ** (failures - 1), 15);
+		}
+	};
+
+	// The most recent flush, so an explicit `flush()` can WAIT for a periodic one rather than hit
+	// the re-entry guard and return having sent nothing. That matters on the shutdown path: the
+	// runner flushes once more after its units' finalizers have run, and those last lines are the
+	// ones that say whether the shutdown was clean. The window is widest exactly when the host is
+	// slow — which is when the logs are worth most.
+	let inFlight: Promise<void> = Promise.resolve();
+	const runFlush = (): Promise<void> => {
+		inFlight = flush();
+		return inFlight;
+	};
+
+	const timer = setInterval(() => {
+		if (skipTicks > 0) {
+			skipTicks -= 1;
+			return;
+		}
+		void runFlush();
+	}, options.intervalMs ?? 2_000);
+	// The runner parks on its own keep-alive handle; this timer must not be what holds the process
+	// open, or a runner with nothing to run would never exit.
+	timer.unref?.();
+
+	return {
+		flush: async () => {
+			skipTicks = 0;
+			// `flush` never rejects (every path is caught); `.catch` only keeps that a guarantee.
+			await inFlight.catch(() => {});
+			await runFlush();
+		},
+		stop: () => {
+			stopped = true;
+			clearInterval(timer);
+			for (const method of METHODS) {
+				console[method] = original[method] as typeof console.log;
+			}
+		},
+	};
+};
+
+/** Exported for tests. */
+export const __test = { toLines, STAMPED };
@@ -22,6 +22,7 @@
 // plugin store (crates/punktfunk-host/src/store), which installs one reviewed version of a
 // package that may live on somebody else's registry — but they are ordinary CLI flags too.
 import { Effect, Fiber } from "effect";
+import { installLogShipper } from "./log-ship.js";
 import { addPlugins, listInstalled, removePlugins } from "./plugins.js";
 import { discoverUnits, runner } from "./runner.js";

@@ -157,16 +158,30 @@ if (process.argv.includes("--list")) {
 // nothing at all: field report 2026-07-25 had it pinning a full core indefinitely, `strace`
 // showing a bare `clock_gettime` loop and nothing else. One idle handle is the whole fix.
 const keepAlive = setInterval(() => {}, 2 ** 31 - 1);
+
+// Tee this process's output to the host so the console's Logs page can show it. Installed HERE and
+// not in `runner.ts`, so it covers the supervised run only: a plugin's own CLI builds the same
+// layer graph, and an operator running `punktfunk-plugin-x doctor` in their terminal is not asking
+// to write into the host's log. Must be installed before the runner starts — the lines that explain
+// a plugin failing to load are the first ones out.
+const shipper = installLogShipper();
+
 const fiber = Effect.runFork(runner(options));
 let stopping = false;
 const shutdown = (signal: string) => {
 	if (stopping) return process.exit(1); // second signal = get out now
 	stopping = true;
 	console.log(`${new Date().toISOString()} [runner] ${signal} — interrupting units…`);
-	void Effect.runPromise(Fiber.interrupt(fiber)).finally(() => process.exit(0));
+	void Effect.runPromise(Fiber.interrupt(fiber))
+		// Ship what the finalizers just said before the process goes away — a clean shutdown's
+		// last lines are the ones that tell you whether it WAS clean.
+		.finally(() => shipper.flush())
+		.finally(() => process.exit(0));
 };
 process.on("SIGINT", () => shutdown("SIGINT"));
 process.on("SIGTERM", () => shutdown("SIGTERM"));

 await Effect.runPromise(Fiber.await(fiber));
-clearInterval(keepAlive); // every unit ended on its own — let the process exit
+await shipper.flush(); // every unit ended on its own — don't leave their last lines unsent
+shipper.stop();
+clearInterval(keepAlive); // …then let the process exit
@@ -41,10 +41,24 @@ export interface RunnerOptions {
 	connect?: ConnectOptions;
 	/** Restart backoff base (test seam). Default 1 s, capped at 60 s, jittered. */
 	restartBase?: Duration.Input;
-	/** Line sink. Default: stamped stdout. */
-	log?: (line: string) => void;
+	/**
+	 * Line sink. Default: stamped stdout, with `warn`/`error` going to the matching console method
+	 * (hence stderr, and hence the right level in the console's log page — see `log-ship.ts`).
+	 *
+	 * `level` is optional so an existing `(line: string) => void` sink stays assignable.
+	 */
+	log?: (line: string, level?: RunnerLogLevel) => void;
 }

+/**
+ * Severity of a runner line. Only three, because that is all the runner distinguishes: it is
+ * reporting on units, not producing application logs.
+ */
+export type RunnerLogLevel = "info" | "warn" | "error";
+
+/** The sink shape used internally, with the level always supplied by the caller's default. */
+type LogSink = (line: string, level?: RunnerLogLevel) => void;
+
 export interface Unit {
 	/** Display name: the file stem, or the plugin package name. */
 	name: string;
@@ -52,8 +66,12 @@ export interface Unit {
 	file: string;
 }

-const defaultLog = (line: string) =>
-	console.log(`${new Date().toISOString()} ${line}`);
+const defaultLog: LogSink = (line, level = "info") => {
+	const stamped = `${new Date().toISOString()} ${line}`;
+	if (level === "error") console.error(stamped);
+	else if (level === "warn") console.warn(stamped);
+	else console.log(stamped);
+};

 // ---- unit-file trust (the sshd rule, both halves) ---------------------------------------------

@@ -225,7 +243,7 @@ const windowsPowershellEnv = (): Record<string, string | undefined> => {
 };

 /** Read a file's SDDL and apply [`windowsSddlUnsafeReason`]. Unreadable ACL ⇒ refuse. */
-const windowsFileIsSafe = (file: string, log: (l: string) => void): boolean => {
+const windowsFileIsSafe = (file: string, log: LogSink): boolean => {
 	const escaped = file.replace(/'/g, "''");
 	const res = spawnSync(
 		windowsPowershell(),
@@ -244,7 +262,7 @@ const windowsFileIsSafe = (file: string, log: (l: string) => void): boolean => {
 	);
 	const sddl = res.status === 0 ? (res.stdout ?? "").trim() : "";
 	if (!sddl) {
-		log(`[runner] REFUSING ${file} — could not read its ACL`);
+		log(`[runner] REFUSING ${file} — could not read its ACL`, "error");
 		return false;
 	}
 	const reason = windowsSddlUnsafeReason(sddl, processSid());
@@ -253,6 +271,7 @@ const windowsFileIsSafe = (file: string, log: (l: string) => void): boolean => {
 			`[runner] REFUSING ${file} — ${reason}. Reinstall the plugin with ` +
 				`\`punktfunk-host plugins add\`, or re-own the file to Administrators and strip ` +
 				`non-admin write ACEs (icacls).`,
+			"error",
 		);
 		return false;
 	}
@@ -264,13 +283,14 @@ const windowsFileIsSafe = (file: string, log: (l: string) => void): boolean => {
 * could have written — group/world-writable mode on Unix; on Windows, an owner outside
 * SYSTEM/Administrators/TrustedInstaller or a write-capable ACE for a non-admin principal.
 */
-const fileIsSafe = (file: string, log: (l: string) => void): boolean => {
+const fileIsSafe = (file: string, log: LogSink): boolean => {
 	if (process.platform === "win32") return windowsFileIsSafe(file, log);
 	try {
 		const mode = fs.statSync(file).mode & 0o022;
 		if (mode !== 0) {
 			log(
 				`[runner] REFUSING ${file} — group/world-writable (chmod go-w it first)`,
+				"error",
 			);
 			return false;
 		}
@@ -285,7 +305,7 @@ const SCRIPT_EXTENSIONS = new Set([".ts", ".js", ".mjs", ".mts", ".cjs"]);
 /** Enumerate the operator's units: loose scripts plus installed plugin packages. */
 export const discoverUnits = (
 	options: RunnerOptions = {},
-	log: (l: string) => void = options.log ?? defaultLog,
+	log: LogSink = options.log ?? defaultLog,
 ): Unit[] => {
 	const units: Unit[] = [];
 	const scriptsDir = options.scriptsDir ?? path.join(configDir(), "scripts");
@@ -332,7 +352,7 @@ export const discoverUnits = (
 			if (!fileIsSafe(file, log)) return;
 			units.push({ name, file });
 		} catch (e) {
-			log(`[runner] skipping ${name}: unreadable package.json (${e})`);
+			log(`[runner] skipping ${name}: unreadable package.json (${e})`, "warn");
 		}
 	};
 	try {
@@ -379,7 +399,7 @@ const attemptUnit = (
 	unit: Unit,
 	attempt: number,
 	options: RunnerOptions,
-	log: (l: string) => void,
+	log: LogSink,
 ): Effect.Effect<"plugin" | "script", unknown> =>
 	Effect.gen(function* () {
 		const mod = (yield* Effect.tryPromise(
@@ -431,7 +451,8 @@ export const superviseUnit = (
 	let attempt = 0;
 	const once = Effect.suspend(() => {
 		attempt += 1;
-		if (attempt > 1) log(`[${unit.name}] restarting (attempt ${attempt})`);
+		if (attempt > 1)
+			log(`[${unit.name}] restarting (attempt ${attempt})`, "warn");
 		return attemptUnit(unit, attempt, options, log);
 	});
 	return once.pipe(
@@ -446,13 +467,18 @@ export const superviseUnit = (
 		),
 		Effect.tapCause((cause) =>
 			Effect.sync(() =>
-				log(`[${unit.name}] failed: ${Cause.pretty(cause).split("\n")[0]}`),
+				log(
+					`[${unit.name}] failed: ${Cause.pretty(cause).split("\n")[0]}`,
+					"error",
+				),
 			),
 		),
 		Effect.retry(restart),
 		Effect.catchCause((cause) =>
 			// A retry schedule that gives up (it doesn't, but stay total) — log and end.
-			Effect.sync(() => log(`[${unit.name}] gave up: ${Cause.pretty(cause)}`)),
+			Effect.sync(() =>
+				log(`[${unit.name}] gave up: ${Cause.pretty(cause)}`, "error"),
+			),
 		),
 		Effect.asVoid,
 	);
@@ -0,0 +1,329 @@
+// The log shipper's contract: what it recovers from a formatted line, that it tees rather than
+// swallows, that a POST failure neither loses lines nor spins, and that it stays bounded.
+import { afterEach, describe, expect, test } from "bun:test";
+import { __test, installLogShipper } from "../src/log-ship.js";
+
+const { toLines } = __test;
+
+const TOKEN = "ship-token";
+
+interface Captured {
+	entries: { ts_ms: number; level: string; source: string; msg: string }[];
+}
+
+/** A host that records every batch, answering with whatever `status()` says. */
+const mockHost = (status: () => number = () => 204) => {
+	const batches: Captured[] = [];
+	const auth: (string | null)[] = [];
+	const server = Bun.serve({
+		port: 0,
+		fetch: async (req) => {
+			const url = new URL(req.url);
+			if (url.pathname !== "/api/v1/plugins/logs") {
+				return new Response("not found", { status: 404 });
+			}
+			auth.push(req.headers.get("authorization"));
+			batches.push((await req.json()) as Captured);
+			const s = status();
+			return new Response(s === 204 ? null : "nope", { status: s });
+		},
+	});
+	return {
+		batches,
+		auth,
+		url: `http://127.0.0.1:${server.port}`,
+		stop: () => server.stop(true),
+	};
+};
+
+/**
+ * Run `body` with a shipper installed, always restoring the console.
+ *
+ * The console is swapped for a recorder BEFORE the shipper installs, so `seen` is what the shipper
+ * teed through to "stdout" — and the suite stays readable, since a test that logs 2000 lines would
+ * otherwise print all 2000.
+ */
+const withShipper = async <T>(
+	url: string,
+	body: (
+		s: ReturnType<typeof installLogShipper>,
+		seen: string[],
+	) => Promise<T>,
+): Promise<T> => {
+	const seen: string[] = [];
+	const real = { log: console.log, warn: console.warn, error: console.error };
+	const record = (...a: unknown[]) => {
+		seen.push(String(a[0]));
+	};
+	console.log = record;
+	console.warn = record;
+	console.error = record;
+	const shipper = installLogShipper({
+		connect: { url, token: TOKEN },
+		// Long enough that only explicit flushes fire — the tests drive the timing.
+		intervalMs: 60_000,
+	});
+	try {
+		return await body(shipper, seen);
+	} finally {
+		shipper.stop();
+		console.log = real.log;
+		console.warn = real.warn;
+		console.error = real.error;
+	}
+};
+
+describe("parsing a formatted line", () => {
+	test("recovers the plugin name and timestamp plugin-kit's format flattened", () => {
+		const [line] = toLines(
+			"log",
+			["2026-08-03T10:11:12.345Z [virtualhere] holding nothing"],
+		);
+		expect(line?.source).toBe("virtualhere");
+		expect(line?.level).toBe("INFO");
+		expect(line?.msg).toBe("holding nothing");
+		expect(line?.ts_ms).toBe(Date.parse("2026-08-03T10:11:12.345Z"));
+	});
+
+	test("an explicit level in the line beats the console method", () => {
+		// plugin-kit renders Effect's level verbatim — "WARNING", not "WARN". The host coerces it.
+		const [line] = toLines("log", [
+			"2026-08-03T10:11:12.345Z [virtualhere] WARNING: vhclient failed (ETIMEDOUT)",
+		]);
+		expect(line?.level).toBe("WARNING");
+		expect(line?.msg).toBe("vhclient failed (ETIMEDOUT)");
+	});
+
+	test("the runner's own error lines keep their severity", () => {
+		const [line] = toLines("error", [
+			"2026-08-03T10:11:12.345Z [virtualhere] failed: VhIpcError: no such binary",
+		]);
+		expect(line?.source).toBe("virtualhere");
+		expect(line?.level).toBe("ERROR");
+	});
+
+	test("an unstamped call is kept, not dropped", () => {
+		// A plugin reaching for bare console.error is exactly the case that must not be lost.
+		const [line] = toLines("error", ["boom", { code: 7 }]);
+		expect(line?.source).toBe("runner");
+		expect(line?.level).toBe("ERROR");
+		expect(line?.msg).toContain("boom");
+		expect(line?.msg).toContain("7");
+	});
+
+	test("a multi-line message becomes one entry per line", () => {
+		const lines = toLines("log", [
+			"2026-08-03T10:11:12.345Z [x] failed\n  at foo\n  at bar",
+		]);
+		expect(lines.map((l) => l.msg)).toEqual(["failed", "  at foo", "  at bar"]);
+		// Every fragment keeps the original stamp, so the trace cannot interleave with other units.
+		expect(new Set(lines.map((l) => l.ts_ms)).size).toBe(1);
+	});
+
+	test("a pathological dump is capped and says so", () => {
+		const lines = toLines("log", [
+			`2026-08-03T10:11:12.345Z [x] ${"line\n".repeat(200)}`,
+		]);
+		expect(lines.length).toBeLessThanOrEqual(41);
+		expect(lines.at(-1)?.msg).toContain("more line(s) suppressed");
+	});
+});
+
+describe("shipping", () => {
+	let stopHost: (() => void) | undefined;
+	afterEach(() => {
+		stopHost?.();
+		stopHost = undefined;
+	});
+
+	test("tees: stdout still gets the line, and the host gets it too", async () => {
+		const host = mockHost();
+		stopHost = host.stop;
+		const seen = await withShipper(host.url, async (shipper, seen) => {
+			console.log("2026-08-03T10:11:12.345Z [virtualhere] hello");
+			await shipper.flush();
+			return seen;
+		});
+
+		// The original console still ran — journald/foreground output is never traded away.
+		expect(seen).toEqual(["2026-08-03T10:11:12.345Z [virtualhere] hello"]);
+		expect(host.batches).toHaveLength(1);
+		expect(host.batches[0]?.entries[0]).toMatchObject({
+			source: "virtualhere",
+			level: "INFO",
+			msg: "hello",
+		});
+		expect(host.auth[0]).toBe(`Bearer ${TOKEN}`);
+	});
+
+	test("a 5xx keeps the lines for the next flush", async () => {
+		let status = 500;
+		const host = mockHost(() => status);
+		stopHost = host.stop;
+		await withShipper(host.url, async (shipper) => {
+			console.log("2026-08-03T10:11:12.345Z [x] keep me");
+			await shipper.flush();
+			expect(host.batches).toHaveLength(1);
+			status = 204;
+			await shipper.flush();
+		});
+		// Re-sent rather than dropped: the host being down is not the line's fault.
+		expect(host.batches).toHaveLength(2);
+		expect(host.batches[1]?.entries[0]?.msg).toBe("keep me");
+	});
+
+	test("a 4xx drops the batch instead of retrying forever", async () => {
+		const host = mockHost(() => 400);
+		stopHost = host.stop;
+		await withShipper(host.url, async (shipper) => {
+			console.log("2026-08-03T10:11:12.345Z [x] malformed");
+			await shipper.flush();
+			await shipper.flush();
+		});
+		// A shape the host rejects cannot be fixed by sending it again.
+		expect(host.batches).toHaveLength(1);
+	});
+
+	test("a line logged WHILE a POST is in flight is not lost", async () => {
+		// A plugin logging during the few ms of a POST is the normal case under load, not an edge
+		// one. An earlier version held a `shipping` flag across the whole `await fetch` and dropped
+		// everything enqueued in that window — silently, which is the worst way to lose a log line.
+		let release: (() => void) | undefined;
+		const held = new Promise<void>((r) => {
+			release = r;
+		});
+		let arrived: (() => void) | undefined;
+		// Resolves once the server actually has the request — i.e. the shipper is genuinely mid-POST.
+		// Logging merely "after calling flush()" proves nothing: flush yields at its own awaits long
+		// before the fetch starts, so the line would land in the pre-send queue and the test would
+		// pass against the broken code.
+		const received = new Promise<void>((r) => {
+			arrived = r;
+		});
+		const batches: Captured[] = [];
+		const server = Bun.serve({
+			port: 0,
+			fetch: async (req) => {
+				batches.push((await req.json()) as Captured);
+				arrived?.();
+				await held; // hold this POST open
+				return new Response(null, { status: 204 });
+			},
+		});
+		stopHost = () => server.stop(true);
+
+		await withShipper(`http://127.0.0.1:${server.port}`, async (shipper) => {
+			console.log("2026-08-03T10:11:12.345Z [x] before");
+			const inFlight = shipper.flush();
+			await received;
+			// The POST is open right now; this is the line that used to vanish.
+			console.log("2026-08-03T10:11:12.345Z [x] during");
+			release?.();
+			await inFlight;
+			await shipper.flush();
+		});
+
+		const all = batches.flatMap((b) => b.entries.map((e) => e.msg));
+		expect(all).toContain("before");
+		expect(all).toContain("during");
+	});
+
+	test("an explicit flush waits for an in-flight one instead of no-opping", async () => {
+		// This is the shutdown path. The runner flushes once more after its units' finalizers have
+		// run, and those last lines are the ones that say whether the shutdown WAS clean. If a
+		// periodic flush happened to be mid-POST, an explicit flush that simply returned would
+		// leave them unsent — and the window is widest exactly when the host is slow, which is when
+		// the logs matter most.
+		let release: (() => void) | undefined;
+		const held = new Promise<void>((r) => {
+			release = r;
+		});
+		let arrived: (() => void) | undefined;
+		const received = new Promise<void>((r) => {
+			arrived = r;
+		});
+		let first = true;
+		const batches: Captured[] = [];
+		const server = Bun.serve({
+			port: 0,
+			fetch: async (req) => {
+				batches.push((await req.json()) as Captured);
+				if (first) {
+					first = false;
+					arrived?.();
+					await held;
+				}
+				return new Response(null, { status: 204 });
+			},
+		});
+		stopHost = () => server.stop(true);
+
+		await withShipper(`http://127.0.0.1:${server.port}`, async (shipper) => {
+			console.log("2026-08-03T10:11:12.345Z [x] first");
+			const slow = shipper.flush();
+			await received;
+			console.log("2026-08-03T10:11:12.345Z [x] shutdown line");
+			release?.();
+			// The shutdown flush: must not return until the tail is actually sent.
+			await shipper.flush();
+			await slow;
+		});
+
+		const all = batches.flatMap((b) => b.entries.map((e) => e.msg));
+		expect(all).toContain("shutdown line");
+	});
+
+	test("overlapping flushes do not double-send", async () => {
+		// The timer can fire while a slow POST is still open. Two concurrent flushes would splice
+		// disjoint batches out of one queue and deliver them out of order.
+		const host = mockHost();
+		stopHost = host.stop;
+		await withShipper(host.url, async (shipper) => {
+			console.log("2026-08-03T10:11:12.345Z [x] one");
+			await Promise.all([shipper.flush(), shipper.flush()]);
+		});
+		expect(host.batches).toHaveLength(1);
+		expect(host.batches[0]?.entries).toHaveLength(1);
+	});
+
+	test("an unreachable host neither throws into the caller nor grows without bound", async () => {
+		// Nothing listening on this port.
+		await withShipper("http://127.0.0.1:1", async (shipper) => {
+			for (let i = 0; i < 2_000; i++) {
+				console.log(`2026-08-03T10:11:12.345Z [x] line ${i}`);
+			}
+			// The whole point: console.log above must not have thrown, and flush must not reject.
+			await shipper.flush();
+		});
+	});
+
+	test("overflow is announced, not silently swallowed", async () => {
+		const host = mockHost();
+		stopHost = host.stop;
+		await withShipper(host.url, async (shipper) => {
+			// Overrun the 1000-line cap while the shipper has had no chance to drain.
+			for (let i = 0; i < 1_200; i++) {
+				console.log(`2026-08-03T10:11:12.345Z [x] line ${i}`);
+			}
+			await shipper.flush();
+		});
+		const first = host.batches[0]?.entries[0];
+		expect(first?.level).toBe("WARN");
+		expect(first?.msg).toContain("dropped");
+		// The tail is what survived — the oldest lines are the ones that went.
+		expect(host.batches[0]?.entries[1]?.msg).toBe("line 200");
+	});
+
+	test("stop() puts the real console back", async () => {
+		const host = mockHost();
+		stopHost = host.stop;
+		const before = console.log;
+		const shipper = installLogShipper({
+			connect: { url: host.url, token: TOKEN },
+			intervalMs: 60_000,
+		});
+		expect(console.log).not.toBe(before);
+		shipper.stop();
+		expect(console.log).toBe(before);
+	});
+});
@@ -88,6 +88,7 @@ mod linux {
            false,
            policy,
            vout.expect_exact_dims,
+            compositor == pf_vdisplay::Compositor::Kwin,
        )
        .context("attach the PipeWire capturer")?;
        cap.set_active(true);
@@ -319,7 +319,11 @@
 	"nav_stats": "Leistung",
 	"nav_logs": "Logs",
 	"logs_title": "Logs",
-	"logs_subtitle": "Der aktuelle Log-Stream des Hosts — live verfolgen, nach Level filtern, durchsuchen.",
+	"logs_subtitle": "Der aktuelle Log-Stream des Hosts und deiner Plugins — live verfolgen, nach Level filtern, durchsuchen.",
+	"logs_source_all": "Alle",
+	"logs_source_host": "Host",
+	"logs_source_plugins": "Plugins",
+	"logs_empty_plugins": "Noch keine Plugin-Ausgabe. Plugins loggen hier, sobald der Plugin-Runner läuft — prüfe `punktfunk-host plugins status`.",
 	"logs_follow": "Folgen",
 	"logs_pause": "Pause",
 	"logs_clear": "Leeren",
--- a/Show More
+++ b/Show More